StackMap
Subscribe
Explore / operational-ontology
gura105

operational-ontology

Minimal TypeScript reference implementation of the Operational Ontology pattern behind Palantir Foundry: shared objects and links, action-gated writes, business rules, audit and write-back.

167 20 TypeScript MITupdated today
knowledge-graphsdata
View on GitHubDispute this mapping →
Curator's take

Read this before you build or buy an 'ontology' for agents. It draws the line most projects blur: a semantic layer lets an agent read the business, an operational ontology lets it run it, because every write goes through named actions that enforce rules, audit refused attempts and write back to the system of record. The runnable demo (two legacy order systems merged, a shipped order that refuses cancellation) makes the pattern concrete in code you can fork. It says itself it is a learning resource, not a framework: no package, no scaling story, one maintainer. Use it to design the action layer your agents need; do not deploy it.

Mapped by ShipWithAI editors · links verified

Continue your stack

What teams reach for next — and why each earns a place beside operational-ontology. Ranked by curator confidence.

pairs wellpairs wellalternativeslayerneocartaHugAgentOSoperational-ontology
pairs wellalternativebuilt withpick a node for the why · open it from the panel
Weekly digest
README.md2 min read

English | 日本語 | 简体中文

Operational Ontology

CI License: MIT

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.

Reads travel from a shared model to agents, apps, and people. Writes enter through an audited action gate and write back to the systems of record that own the state.

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.

pnpm install
pnpm demo    # physical data → integrate → index → read → write → refusal → write-back
pnpm test    # verify the behavior

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. W