BIM Ontology
The canonical classification of building objects and the canonical parameter dictionary. Owns ObjectClass, ParameterKey, ClassParameter, ParameterGroup, ParameterValue, and the Revit parameter projection. Consumed by product-marketplace, which assigns classes to products and uses the associated parameters.
Overview
BIM Ontology answers two questions that everything downstream depends on:
- What kind of thing is this? A single-parent tree of
ObjectClassnodes (ADR-0046), cross-referenced to Uniformat, Masterformat, OmniClass, ObjectClass codes, and Revit categories. - What parameter is this, canonically? One ParameterKey per concept, defined once, with value semantics (
ParameterSpec), presentation (ParameterControl), authoring grouping (ParameterGroup), and canonical values (ParameterValue, grouped into reusable templates by ParameterValueGroup) as separate concepts that reference it.
A ClassParameter assignment connects the two, and a RevitParameterProjection expresses an approved parameter inside Revit.
The module is apps/api-v1/src/modules/bim-ontology — a hexagonal module with Airtable persistence and an Airtable steward UI driven by AT-* scripts. Its base is appoSN6xLYm5M7SkN.
Implementation Status
Status: Implemented in api-v1
Ownership boundary with Product Marketplace
ParameterKey is one concept, owned here and consumed by product-marketplace. BIM Ontology defines parameter keys and their relationships to object classes and Revit. Product Marketplace assigns a class to a product and uses the associated parameters. Scraping either maps a scraped attribute onto an approved key or creates a new key in active, so product data is visible on the storefront while still flagged as needing steward mapping.
That is the whole reason the active lifecycle state exists — see ubiquitous language.
Product-marketplace pages cross-reference the entity pages here rather than redefining them. The junctions that genuinely belong to product-marketplace — ModelParameter, ModelParameterAllowedValue, VariantParameter — stay in that domain.
Aggregates and lifecycles
| Aggregate | Lifecycle | Note |
|---|---|---|
ObjectClass | draft → approved → archived | Approve requires Uniformat, Masterformat, ObjectClass code, and Revit category, plus an approved ancestor chain (ADR-0050) |
ParameterKey | draft → active → approved → archived | The only aggregate with active (ADR-0052) |
RevitParameterProjection | draft → approved → archived | System-created in draft, steward-completed, steward-approved |
ClassParameter | none | An assignment, not a lifecycle. AssignmentOrigin is provenance |
ParameterGroup, ParameterValue, ParameterSpec, ParameterControl, ParameterValueGroup | none | Reference and catalog concepts |
Flows
- Object Class Graph Mutations — mutate the tree and fan out to the four registered handlers
- Parameter Key to Revit Projection — authoring through to an approved projection
- Revit Projection Archive and Reuse — archive rather than delete, and reuse the GUID
- Object Class Demotion Cascade — losing a classification demotes the class and blocks projection approval
Primary Code References
- Module:
apps/api-v1/src/modules/bim-ontology - Composition and event registrations:
apps/api-v1/src/modules/bim-ontology/composition/bim-ontology.composition.ts - REST:
apps/api-v1/src/modules/bim-ontology/adapters/inbound/rest/app/— eight registration areas, 55 operations - OpenAPI: api-v1 spec, operations tagged
BIM Ontology / …
Documentation Links
- Ubiquitous language
- Platform ubiquitous language
- ADRs:
docs/adr/README.md - Module docs:
docs/api-v1/bim-ontology/_OVERVIEW.md - Mutation ownership:
docs/api-v1/bim-ontology/MUTATION_ROUTING.md
Open Questions
- api-v2 target. The module lives in api-v1 only. No migration plan exists yet, so no page here carries
Being migrated from api-v1 to api-v2. - Steward authorization. Every route requires an API key, but there is no per-operation role model; approve and archive are not distinguished from reads by authorization.