Why Ontology-First
The problem with ad-hoc naming
Section titled “The problem with ad-hoc naming”Every engineering team invents vocabulary. Tables get called dim_products, combo_logs, raw_shopify_orders. Column names drift across files — product_id here, shopify_product_id there, productId in TypeScript. DTOs accumulate inconsistent field names. Over time, no one can answer basic questions without archaeology:
- Is an order a thing or an event?
- Is a combo template a plan or a record?
- Is
classificationa measurement or a label? - Does
product_asset_mappingsmean the asset depicts the product, or the product contains the asset?
These aren’t pedantic questions — they determine module boundaries, data ownership, API contracts, and whether a refactor breaks something.
What ontology-first means
Section titled “What ontology-first means”Ontology-first means grounding every entity, relation, and process in a formal category from established ontologies. Instead of inventing names, we adopt vocabulary from a six-layer stack that has been refined by ISO standards bodies, defense contractors, financial regulators, and industrial engineers:
| Layer | Ontology | What it gives us |
|---|---|---|
| 1 | BFO 2020 | The fundamental split: things that persist (Continuants) vs things that happen (Occurrents) |
| 2 | IAO | Information artifacts: documents, datasets, identifiers, reports, specifications |
| 3 | CCO | Agents, acts, measurements (nominal/ordinal/ratio), designators, time |
| 4 | IOF | Material artifacts, assemblies, engineered systems, capabilities |
| 5 | FIBO | Commercial transaction patterns, product/service lifecycle |
| 6 | PKO | Procedures, steps, executions, verification, error handling |
Plus REA (Resources, Events, Agents) for the economic/accounting lens.
When we say a Shopify order is a Process (BFO Occurrent) rather than an Object (BFO Continuant), that’s not decoration — it determines that orders belong in occurrent tables, are tracked by temporal regions, and participate in duality relations with revenue events. See ODR-005 for the full reasoning.
Three engineering benefits
Section titled “Three engineering benefits”1. Schema clarity — names that prevent misinterpretation
Section titled “1. Schema clarity — names that prevent misinterpretation”The table material_artifact tells you exactly what’s inside: physical things with causal unity (phone cases). The table plan_specification tells you it prescribes future actions (combo templates). The column nominal_classification tells you it’s a categorical label, not a continuous measurement. No archaeology needed.
2. Module boundaries that don’t drift
Section titled “2. Module boundaries that don’t drift”When each module owns a defined ontological domain — the Performance module owns Measurement Data and Objective Specifications, the Assets module owns Information Content Entities and their Information Bearing Entities — there’s a principled answer to “does this new feature belong here?” If it creates or queries measurement data, it belongs in Performance. If it manages information artifacts, it belongs in Assets.
3. Precise data ownership vocabulary
Section titled “3. Precise data ownership vocabulary”Instead of vague statements like “the ingest pipeline owns raw data”, we can say: the Ingest module executes ProcedureExecutions (PKO) that produce Information Bearing Entities (R2 objects) carrying Process Records (IAO Reports of commercial transactions). Each term has a formal definition that’s consistent across every page of this specification.
How to read annotations in these docs
Section titled “How to read annotations in these docs”Throughout this specification, you’ll see inline annotations like:
[BFO: Independent Continuant | IOF: MaterialArtifact]
These follow the pattern [Ontology: Class] and tell you exactly where a concept comes from. They appear after the plain-English explanation, never instead of it.
Some pages include :::note admonitions labeled Ontological Grounding that provide deeper mapping context. These are optional reading for anyone who wants to trace a design decision back to its formal basis.
The Quick Reference page is a glossary of all ontological terms used in this spec — look there first if you encounter an unfamiliar term.
Pragmatic, not academic
Section titled “Pragmatic, not academic”This is engineering documentation, not a philosophy paper. We use ontology to make schemas self-documenting, module boundaries principled, and naming conventions consistent. We don’t use OWL syntax, RDF triples, or runtime reasoners. The ontology lives in the documentation and the naming conventions — it’s a design discipline, not a runtime dependency (ODR-002).
If a formal category doesn’t help clarify a design decision, we don’t force it. If two ontological options are equally valid, we pick the one that produces clearer table names and move on. The Ontological Decision Records capture these pragmatic choices.