Building an Ontology Schema for a Small Supply Network

Description and use

A single YAML ontology schema was built for a small supply network, ensuring consistent metrics like on‑time, fill, dwell, and late hours, producing a 57.1 % on‑time rate and lane‑level insights.

Problem

Different notebooks defined the same operational word inconsistently, leading to conflicting metrics such as on‑time rates.

Outcome

The ontology schema enforces consistent metric definitions, preventing duplicate or misspelled columns, and produces a 57.1% on‑time rate with clear lane‑level insights.

Workflow

• Define the question and cutoff (on‑time < 50%)
• Choose fact grain (Shipment) and dimensions (Node, Lane, Carrier, Sku)
• Define properties (actual_hours, planned_hours, etc.) and metrics (OnTime, FillPercent, DwellHours, LateHours)
• Write YAML schema in schema/inland_network.yaml
• Load schema with PyYAML and validate with ontology.py
• Bind data from data/network.json with bind.py
• Score shipments with metrics.py using rules from ontology
• Generate brief table via main.py and FastAPI endpoint
• Run tests with pytest to ensure correctness

Evidence

I wanted one place that says what a shipment is, which lane it used, and what "on time" means, before any table or brief was allowed to invent a second meaning.

Source

LaneSchema is that place, as a personal experiment on a laptop.

Source

The ontology lives in schema/inland_network.yaml.

Source

The fact grain is Shipment. The dimensions are Node, Lane, Carrier, and Sku.

Source

A metric that points at a property the grain does not have dies in load_ontology with a SchemaError.

Source

python main.py prints that table. FastAPI serves the same build_report function.

Source