English | 日本語

Operational Ontology

An operational ontology is a shared domain model built on top of the data of systems you don't own — objects, links, and actions — where reads traverse the model and writes are gated by actions that carry business rules, are audited, and propagate back to the systems of record that own the state they change.

A semantic layer lets you read your business. An operational ontology lets you run it.

Palantir Foundry's Ontology is one implementation of this pattern. This repository is another: a minimal reference implementation, small enough to read in one sitting. It exists to make the definition precise and runnable; it is not a framework. Fork it and reuse the ideas.

Quickstart

pnpm install
pnpm demo    # physical data → integrate → index → read → write → refusal → write-back
pnpm test    # the same behavior, as executable tests

The demo uses the scenario from the article this repository accompanies. A company acquires a competitor and inherits two legacy order systems with different schemas and status encodings. A few dozen lines of SQL and a small TypeScript mapping integrate them, and the ontology models Customer, Order, and Product on top — plus Note, a type that exists in no source system. The demo then shows:

• a link traversal answering "which orders contain this product?" across both systems
• assignOrder writing state that exists in no legacy system — edits can live in a layer above the sources
• cancelOrder on a shipped order refused with SHIPPED_ORDER_CANNOT_BE_CANCELLED
• cancelOrder on an open order succeeding, with the row in the legacy ERP actually changing
• a re-index of the live legacy systems, where order data refreshes from the ERP while the assignment and notes — state the ontology itself owns — survive
• every attempt, applied or refused, recorded in the audit log

https://github.com/user-attachments/assets/02bb8ca0-a476-4e33-b0ea-25c46c6e9dda

The four properties

A system implements the pattern when all four properties hold. They constrain what must be true, not how to build it: outbox or webhook, SQL or search index, one store or many are all implementation choices. Treat them as shared vocabulary for discussing systems, not as a certification to pass.

1. Semantic objects and links. Business entities and their relationships are modeled explicitly, on top of physical data that existed first and that other systems own.

2. Action-gated writes. A business decision changes state only through a named action. There is no generic update path — not for a user, not for an application, not for an agent. State in this layer also changes for two other reasons, and neither is a loophole: re-indexing only replays what the sources already say, and schema evolution (under review) changes what can be said, not what is true. Any write that picks a business outcome is a decision, whatever the endpoint is named, and decisions go through actions.

3. Business rules at the action. Preconditions check domain invariants ("a shipped order cannot be cancelled") and refuse violations with machine-readable errors. They are not access control, and not UI validation. Every attempt, applied or refused, is recorded in the audit log.

   

4. Write-back to systems of record. The model declares, for every piece of state, which system owns it. There are three kinds:

   • source-backed — state owned by an upstream system, such as an order's status mastered in the ERP. A change to it propagates back to that source as a governed, ordered side effect; the source stays authoritative.
   • ontology-owned — state no source system has a column for, such as an assignee or a triage note. For this state the ontology's own store is the system of record, by declaration.
   • derived — computed state such as aggregates and counts. It is never written.

   What the property forbids is state with no declared owner: a local copy of source-owned data that is modified but never written back, or a write nobody can place. An implementation with no source-backed writes at all does not implement a smaller version of this pattern; it is an ordinary application with its own database.

   

A quick test: "Can you cancel an order from your semantic layer?"

• If the answer is no, you have a read layer — useful, but a different thing.
• If the answer is yes but no row in any system of record ever changes, you have a parallel database — also a different thing.
• If it also cancels already-shipped orders without complaint, you have a write API; property 3 is the whole difference.

Why another word?

The pattern needs a name of its own because "ontology" already means too many things:

Each row is a legitimate tool, and the table is not a ranking. But the one property that changes what a layer can do — whether it accepts writes governed by business rules — cuts across the whole table and had no name of its own. This repository gives it one.

What an implementation declares

The four properties leave the mechanisms open, but some choices differ between implementations in ways users can observe. Those choices must be declared, not left silent. There are four:

• Authority — which state is source-backed, which ontology-owned, which derived.
• Failure semantics — what happens when write-back and the local commit disagree.
• Re-indexing vs edits — whether ontology-owned state survives a refresh of the base.
• Visibility default — what an object with no policy falls back to.

This repository's answers, in the same order. Ownership is declared in the model — owned marks ontology-owned properties, link types, or whole object types, and writeback: true marks an action's changes source-backed — and the runtime checks every edit plan against those declarations instead of trusting them (details). Write-back runs before the local commit, so if the source refuses, nothing changes here (see Failure semantics). Ontology-owned state survives re-indexing: edits live in an overlay that load() reapplies over the fresh base, and a re-index that would orphan an edit is refused whole. Visibility defaults to fail-open: no policy means visible to everyone (see the FAQ).

All four answers are also collected in one enumerable value, Runtime.declarations, so they can be read at runtime rather than trusted as prose. An implementation may answer all four differently and still be inside the pattern. If a product calls itself an operational ontology, ask for its four answers, not for a certificate.

For AI agents (MCP)

pnpm mcp     # serve the same ontology to agents over stdio

The MCP tool surface is generated from the model: search_order, traverse_customer_orders, cancel_order, read_audit_log, … — one tool per query shape and one per action. The tool surface is derived from the schema side; the calls act on the instance side. Two consequences:

• There is no raw SQL tool. Agents get exactly the operations the model defines, and nothing else.
• The same preconditions that gate humans gate agents. An agent that tries to cancel a shipped order receives { "error": { "code": "SHIPPED_ORDER_CANNOT_BE_CANCELLED", … } } — a machine-readable refusal it can read, recover from, and explain to its user.

Reads are scoped the same way. Every query runs as an actor — the identity on whose behalf the call is made — and visibility policies attached to the model decide which objects that actor can see. Agent sessions are no exception; the audit log is the one declared exception, an unscoped administrative view. Over stdio all callers collapse into one actor. OO_AGENT=<name> pnpm mcp names that actor, which is labeling, not authentication.

https://github.com/user-attachments/assets/28327062-e09f-4103-943e-434a0e55b327

Business rules live in the ontology, not in the prompt.