gura105/operational-ontology

Operational Ontology
> **An operational ontology is a shared domain model over other systems' data: objects and links for reading the business, and actions that enforce business rules, audit attempts, and write changes back to the systems of record.**
>
> A semantic layer lets you *read* your business. An operational ontology lets you *run* it.
This repository makes that definition runnable in a small TypeScript reference implementation. Palantir Foundry's Ontology is the pattern's starting point; this example isolates the ideas so you can read, fork, and adapt them. It is a learning resource, not a framework or an npm dependency.
Quickstart
Requires Node.js 24 or later and pnpm.
The demo follows the accompanying article: a company acquires a competitor and inherits **two legacy order systems with different schemas and status encodings**. SQL and a small mapping integrate their data into one model. Run it to see:
- links and aggregates answer questions across both systems;
- cancelOrder refuse a shipped order and write an allowed cancellation back to the original ERP;
- assignOrder and addOrderNote store state owned by the ontology, which survives re-indexing while source data refreshes;
- applied and rejected action attempts appear in the audit log.
https://github.com/user-attachments/assets/02bb8ca0-a476-4e33-b0ea-25c46c6e9dda
Why define Operational Ontology?
Answering “How many unshipped orders does this customer have?” consistently requires a model for reading data in business terms. When an application or AI agent goes on to cancel an order, it also needs to check the operation's conditions, record the attempt, and deliver the change to the ERP that owns the record. Treating these responsibilities as part of a shared model is this repository's starting point.
The terms “semantic layer” and “ontology” alone do not tell us how much of that responsibility is included. Comparing nearby concepts by what they model and how they handle business operations makes the distinction clearer.
| Concept or arrangement | What it primarily models | Relationship to business operations |
| --- | --- | --- |
| Semantic layer | The meaning of metrics, attributes, and aggregates | Answers data questions consistently. Operation conditions and write-back require additional design. |
| Formal ontology / knowledge graph | Conceptual meaning, entities, and relationships | Represents meaning and relationships. Business rules and audit need to be designed alongside data updates. |
| AI context layer | Meaning and background for answers and decisions | Supports an agent's understanding. Governance of the operations it executes requires additional design. |
| CRUD API / API wrapper | Data access or individual operations | Where rules, audit, and write-back are enforced depends on each API's design. |
| **Operational ontology** | **Shared objects and links, plus actions carrying business rules** | **Makes operation conditions, audit, and write-back to authoritative sources part of the shared model's contract.** |
These technologies can be combined. The arrangement we want to name is one where **every consumer changes state through the same model, under the same business rules**. We draw this arrangement from Foundry's Ontology and define it as Operational Ontology through the four properties below, so it can be discussed and implemented independently of a particular product.
The four properties
This repository uses *operational ontology* for a system with all four properties. They describe the pattern; storage engines, integration tools, and consistency mechanisms are implementation choices.
1. **Semantic objects and links.** Business entities and relationships are modeled explicitly over existing data owned by other systems.
2. **Action-gated writes.** Business decisions change state only through named actions. Every consumer uses that same API. Source re-indexing is a separate infrastructure operation.