Purpose
Operational Ontology is a reference implementation designed to make the concept of an "operational ontology" runnable, readable, and adaptable. It solves the following problem: when data from multiple systems needs to be read and operated on consistently in business terms, a semantic layer alone is not enough to describe the entire scope of responsibility. An operational ontology is used not only to read the business, but also to run the business—that is, to execute operations that are checked against business rules, auditable, and can be written back to source systems through a shared model.
Main Capabilities
This pattern has four core properties:
- Semantic objects and links: Explicitly model business entities and relationships on top of existing data owned by external systems.
- Action-gated writes: Business decisions can change state only through named actions, and all consumers use the same set of APIs.
- Business rules on actions: Preconditions enforce domain invariants (such as "a shipped order cannot be canceled"), violations produce machine-readable rejections, and both applied and rejected attempts are audited.
- Write-back to systems of record: Every state has an explicit owner, and changes to state owned by a source are propagated back to its owner through governed side effects.
Ownership in the example takes three forms: source-backed (such as ERP owning Order.status), ontology-owned (such as assignee and notes), and derived (such as totals computed at query time).
This implementation defines the model as plain values, including object types, link types, and action types. Edits describe proposed changes that actions make to objects and links, and the audit log records action execution attempts and their results. The model can also be data rather than classes, so the information needed to describe operations can be enumerated and checked at runtime, and MCP tools can be generated from it.
The demo includes: answering business questions across two systems through links and aggregation; cancelOrder rejecting shipped orders and writing allowed cancellations back to the original ERP; assignOrder and addOrderNote storing ontology-owned state that persists after source data refresh and reindexing; and applied and rejected action attempts appearing in the audit log.
Usage
Node.js 24 or later and pnpm are required. Run the demo with pnpm demo. Tests can be run with pnpm test. The repository's MCP configuration connects to the order example, and agents can call generated tools such as search_order, traverse_customer_orders, cancel_order, read_audit_log, etc. When an agent cancels an already shipped order, it receives SHIPPED_ORDER_CANNOT_BE_CANCELLED, consistent with human callers. Business rules live in the model, so prompts do not need to enforce the rules.
Applicable Scenarios
This repository is suitable for data-driven operational scenarios, such as product recalls, equipment anomalies, patient admission requests, transaction alerts, etc. Operations teams need to gather information, decide who or what to act on and based on what evidence, and repeat these decisions and actions as conditions change. The demo provides an order example, as well as extended examples for recalls, factories, hospitals, and finance, which combine set exploration with domain rules in the model. In addition, this pattern is also suitable for scenarios that need to provide AI agents with a consistent interface for business operations.
Limitations
This repository implements the middle layer, and the demo provides the surrounding application and data integrations. The runtime uses synchronous action execution and SQLite for demonstration. It does not include a UI builder, pipeline framework, scalable indexing service, or general authorization system. The write gate is an API contract within the caller process. Actions can create ontology-owned objects or create source-backed records via write-back, but use IDs specified before execution. Deletion, link properties, and composite keys are not supported. This implementation is a learning resource, not a framework or npm dependency. Release versions can be found in the release notes. The remaining limitations and API details are documented in the implementation notes.
