Using the BIMei ONT
A guide for researchers using the BIMei Ontology (ONT): what it holds, the rules it keeps, and how to consume it through the API and MCP. Everything below is documented natively — no external document required.
What the ONT is
The BIMei Ontology (ONT) is the canonical Action Statement registry for the BIMei ecosystem — the source of semantic truth, not a runtime hub. It holds the regulated vocabulary (Actions, Terms, the v4 Concepts / Relations / Attributes / Knowledge Sets) and the Action Statements built from them, each with a permanent, dereferenceable IRI.
Consuming apps (AIO, RPF, MAD, LITE) take a read-only, versioned snapshot by URI and key it by IRI (derive-and-cache). They never route live traffic through the ONT, and nothing writes into canon at runtime. The registry regulates how the vocabulary grows; it is continuously calibrated against real instances.
The three registers
Every object carries a register — a column, never encoded in the IRI. Only canonical carries semantic truth.
| canonical | Semantic truth — the Statement registry, Actions, BIMd Terms, the v4 Concepts/Relations/Attributes/Knowledge Sets, and the Topic Taxonomies. The only register that formally means anything. |
| instrument | Reusable methods and non-canonical classifications — the proximity/dedup engines, the synonym resolver, and the 18 Activity Types. Catalogued, never canonised; may read canon and propose, never write truth unattended (a one-way valve). |
| communication | Devices that explain rather than define — glossaries, diagrams, outreach (including this Help page). |
IRIs & identity
Every canonical object has a permanent IRI https://w3id.org/bimei/{type}/{slug}, fronted by w3id → ontology.bimexcellence.org. Slugs are readable and mint-once / never-rename — a relabel changes the label, not the slug.
Identity is language- and version-neutral: language is a representation selector (content negotiation), and version is the live head at the bare IRI plus pinned, citable versions/DOIs. The legacy AIO GID is provenance, never the key. register is a property of the object, never part of its IRI.
The Action Statement data model
The atom is the Action Statement, keyed by a signature = Action(verb) IRI + sorted Term IRIs; the registry deduplicates by signature (resolve-or-candidate, genericisation-first). Its three expressions are embedded projections of one record, not three rows:
Vocabulary guards
Four distinctions are load-bearing across the ONT:
| Action ≠ Activity | An Action is a regulated verb that opens a statement (one of the 50). An Activity is one of the three expressions of a statement — a separate axis. |
| Activity Type (the 18) | Non-canonical (instrument); it types the Activity expression only, and is orthogonal to the 50 Actions. |
| Competence ≠ Competency | Competence is an actor's actualised ability (an instance, outside canon). Competency is definitional/canonical. |
| Instrument ≠ Tool | An Instrument is internal apparatus (engines, the Activity Types). A Tool is a delivered, user-facing product. |
The BIMei Ontology v4 model uses Activity as a top-level Concept and Action as a Relation (edge). In the registry, "Action" stays the verb vocabulary and "Activity" stays an expression. The published Concepts and Relations are a separate, clearly-typed layer.
Actions — the verbs
The Actions are the regulated, bilingual (EN/FR) verb vocabulary (50) that opens every Action Statement in any of its three expressions. Canonical; multilingual; w3id IRIs. The original 33 verbs keep their legacy AIO GID as provenance; the 17 verbs admitted through curation in 2026 carry the registry's own curation provenance instead. In v4 terms an Action verb is a Relation — the mapping is published on the relation rows, but the Action slugs are kept stable (mint-once).
Terms, the BIMd feed & the candidate queue
Terms are the object half of a signature, sourced from BIMd — the sole editorial source. The ONT references term IRIs directly (no alias, no copy) and caches a versioned snapshot. That cache is deliberately selective: the ONT keeps only the BIMd terms it needs to define BIMei Action Statements, topic mappings, and registry outputs; the full editorial dictionary remains in BIMd. Statement [[bracket]] / AIO bimd_terms[] links resolve to term IRIs; unmatched terms route to a candidate queue proposed into BIMd — never minted as independent canonical terms. The queue is a non-canonical, read-only operational record: its rows have no IRI and do not dereference.
How the registry grows
The registry's numbers move between visits because content enters through a regulated lifecycle, never by bulk upload:
| resolve-or-candidate | Every incoming statement is keyed by its signature. A match resolves to the existing record (one identity, however many source apps carry the statement); a new signature is admitted with status candidate — never auto-promoted to canonical. |
| held, never dropped | A statement that cannot yet form a signature — no linked Terms, or an opening verb outside the regulated Actions — is held and counted, not discarded. Held statements re-enter automatically once the gap closes (a term is tagged, a verb is admitted). |
| curation | Humans rule on what the machines hold apart: synonym mappings onto existing Actions, approved rewordings (carried with explicit override provenance), and vocabulary admissions — the Action vocabulary grew from 33 to 50 this way in 2026. |
| audit | Every change records who and how: machine-rule ingestion vs human override, the originating app and source id, and an append-only decision ledger entry — so a statement's history is reconstructable from the registry itself. |
Nothing is ever deleted from source apps by this process, and consuming apps only ever see the result through the versioned snapshot.
Activity Types (the 18, instrument)
The 18 Activity Types form the instrument register; they type the Activity expression and are non-canonical and extensible — catalogued, never canonised. An Activity Type is distinct from a Tool (a delivered product).
The Topic Taxonomy
The BIMei Topic Taxonomy is an ONT-owned controlled-vocabulary Construct whose members are Terms referenced by IRI (a topic is a Term — there is no /topic/ type). ONT owns the container + membership + snapshot; BIMd blesses each member Term; members not yet blessed show awaiting BIMd blessing. Specialties are display-only children, never separate Terms or scopes.
Concepts (v4)
The 20 v4 Concepts (Ability, Activity, Actor, Asset, Tool, Authority, Construct, Constraint, Content, Context, Decision, Deliverable, Event, Example, Process, Project, Responsibility, Role, Rule, System) are the conceptual backbone — canonical, published as owl:Class. Some carry documented controlled sub-type lists (e.g. Construct.type, Content.type) as display-only reference data. Ability is the Concept the as-Ability expression realises; Construct{type:Taxonomy} is exactly what the live Topic Taxonomy is.
Relations (v4)
The v4 Relations are the canonical semantic edge vocabulary: 35 canonical relations (HAS_PART, USES, PRODUCES, TRANSFORMS, DERIVES, GOVERNS, …) and their specialised sub-relations, each with an allowed domain → range (published as owl:ObjectProperty with rdfs:domain/rdfs:range/rdfs:subPropertyOf). Each canonical relation also carries the Action verbs that map to it (e.g. assess / review / audit → EVALUATES), so the 50 Actions and the relation vocabulary stay linked without merging tables.
Attributes (v4)
The 22 core v4 Attributes (availability, cost, granularity, status, type, …) are the generic, reusable properties that qualify Concepts and Relations — canonical, published as owl:DatatypeProperty. The 11 implementation-only LPG/BPM properties (code, value, version, …) are described here but deliberately not published as data.
Knowledge Sets (v4)
The 5 v4 Knowledge Sets — KnowledgeFoundation, KnowledgeBlock, KnowledgeTool, KnowledgeWorkflow, KnowledgeView — are compilations of Concepts, Attributes and Relations (published as skos:Collection). The KnowledgeBlock sub-types include Action Statement: the ONT atom is a v4 Knowledge Block.
Relationship to BIMei Ontology v4
The registry is the canonical-truth core of the broader BIMei Ontology v4 model. v4 is a Labelled Property Graph: Concepts (PascalCase nodes), Attributes (camelCase properties), Relations (UPPER_SNAKE_CASE edges) and Knowledge Sets. The ONT publishes those four vocabularies natively (above) so apps can consume them by IRI via the API + MCP.
What the ONT deliberately does not host is the v4 execution machinery — the BPMN run-time, the Neo4j GraphRAG deployment, the implementation-only edge types and LPG/BPM properties. That layer is documented in the v4 source and remains future scope (a graph store is Phase 4, conditional). The ONT stays a relational registry of canonical vocabulary, not a runtime graph.
Action Statement → a v4 Knowledge Block · Action (verb) → a v4 Relation (not a Concept) · Term → Construct{type:Term} · Ability → the umbrella Concept the as-Ability expression realises · BIMei Topic Taxonomy → Construct{type:Taxonomy} of Terms. See docs/architecture/v4-crosswalk.md.
How to consume the ONT
Browse a type from the header, search by label, or dereference any IRI. The same IRI serves two representations by content negotiation:
| HTML | A browser (Accept: text/html, or ?format=html) gets a readable page. |
| JSON | The default for machines, or ?format=json — the resolved object with its language layers. |
| JSON-LD | Send Accept: application/ld+json or ?format=jsonld — the hybrid OWL/SKOS shape. The reusable @context is at /context. |
For derive-and-cache consumers, the deterministic, IRI-keyed versioned snapshot is at /api/snapshot — the source-of-truth contract (no live hub). A read-only MCP server exposes resolve, findBySignature, search and exportSnapshot. The new v4 vocabularies flow through all of these surfaces with no special wiring.
Roadmap & scope
Phase 1 (site + MCP, verb vocabulary, term-link preservation) and Phase 2A (backlinks, faceted browse, JSON-LD, candidate/Instruments surfacing, search, polish) are done. Phase 2 also populated the 18 Activity Types and the Topic Taxonomy V1, and now publishes the v4 Concepts / Relations / Attributes / Knowledge Sets (decision log 0019). Phase 3 is BIMd alignment. A graph store is Phase 4 — conditional, and out of scope. The store stays relational.
Glossary
| Action Statement | The atom; a verb (Action) + object Terms + optional definition, keyed by signature. |
| Signature | Action(verb) IRI + sorted Term IRIs; the dedup key. |
| Ability / Activity / Outcome | The three embedded expressions of one statement (typed by OrgScale / Activity Type / targeted-outcome). |
| OrgScale | The typing axis for the Ability expression — a canonical referenced Index of 12 Organisational Scales (Global Market … Organisational Member; Macro / Meso / Micro clusters), rolling up to the coarse individual / group / organisation / market level. |
| register | canonical | instrument | communication — a property, never in the IRI. |
| IRI | https://w3id.org/bimei/{type}/{slug}; mint-once, language/version-neutral. |
| candidate | An unmatched term link, proposed into BIMd; no IRI, does not dereference. |
| BIMd Term | The canonical object half of a signature; sourced from BIMd (the sole editorial source). |
| Concept / Relation / Attribute / Knowledge Set | The published v4 vocabulary layer (owl:Class / owl:ObjectProperty / owl:DatatypeProperty / skos:Collection). |
| Instrument vs Tool | Instrument = internal apparatus; Tool = a delivered product. |