Ontology

The Ontology is the Intelligence-plane schema that every other plane reads against. Without it, agents, tools, evidence, and policy disagree about what an “order” or a “customer” actually is.

Definition

A versioned, governed schema that defines canonical entity_types, relationship_types, attribute types, derived fields, and validation rules. Every record in the Knowledge Graph, every CEID in the Identity Layer, and every reference inside a Context Pack resolves against an explicit ontology version.

Why it exists

Across a real enterprise, the same word means different things in different systems. CRM “customer” includes prospects; OMS “customer” requires a paid order; finance “customer” is a billing entity. If agents reason against ad-hoc fields, they produce decisions that look right in one system and wrong in another. The Ontology gives the runtime a single, governed truth so policy, retrieval, and decision contracts compose.

How it works

1. Authored: domain owners propose changes against the active version.
2. Validated: changes are checked for breaking compatibility, derived-field correctness, and reference integrity.
3. Approved: governance review for high-risk types (PII, regulated, financial).
4. Published: a new ontology version is pinned per environment and rolled out.
5. Migrated: dependent indices, packs, and decision specs are revalidated against the new version.

Schema elements

Versioning and compatibility

Changes fall into three classes:

• Additive — new entity types, new optional attributes, new relationships. No migration required; existing packs continue to compile.
• Refining — narrowing a type, tightening a constraint, deprecating an attribute. Requires deprecation window and migration plan; old packs can compile with a warning until the deprecation window closes.
• Breaking — removing a type or relationship, renaming a CEID format, changing classification upward. Requires a major version bump, a redirect/aliasing rule, and an explicit migration of dependent packs.

The runtime refuses to compile a Context Pack against an ontology version it does not satisfy. The error names the missing or incompatible element so the pack author can fix it.

Schema evolution governance

• Changes are merged through a version-controlled repo with required review.
• Breaking changes require an active deprecation period and a documented migration.
• Each environment pins one ontology version; promotion from staging to production is a deliberate step.
• A change-set diff (added / removed / refined) is published with every version so dependent teams can plan.

Improvement surface

The Ontology participates in the Improvement Loop as an Intelligence-plane artifact, but it is not a free-form search surface. Autotune and reviewer agents may propose ontology changes only when the proposal is backed by traces, failed compiles, unresolved entities, or repeated operator corrections.

Breaking changes, classification downgrades, CEID format changes, and relationship removals are never auto-tunable. They are governance events. The Improvement Loop can open a proposal, but promotion requires domain-owner approval, migration evidence, and replay against the dependent Context Packs and Decision Specs.

Derived fields

Derived fields are pure functions, not stored facts. They run at query time with full access to evidence refs of inputs.

derived_fields:
  - name: is_high_value_customer
    type: boolean
    expression: "lifetime_value_inr > 100000 AND tenure_days > 180"
    inputs:
      - Customer.lifetime_value_inr
      - Customer.tenure_days

Validation rules execute alongside derived fields and surface violations as conflicts to the Knowledge Graph.

Identity alignment

CEIDs (Canonical Entity IDs) are generated and resolved by the Identity Layer. The Ontology defines the entity types, relationship rules, classification rules, and constraints that a CEID must resolve against. A change that invalidates existing CEID resolution is a breaking ontology change.

Interfaces

Inputs

• Source schemas, business glossaries, regulatory definitions
• Entity-resolution rules and confidence thresholds
• Domain-owner approvals

Outputs

• Versioned ontology bundles
• Compatibility report between adjacent versions
• Migration scripts for refining and breaking changes
• Validation rules consumed by the Knowledge Graph

Failure modes

• Implicit semantic drift across teams when changes are not classified honestly (a “refining” change that is actually breaking).
• Derived fields that depend on stale inputs and silently mislead retrieval.
• Ontology change merged without dependent-pack revalidation, breaking compilations in production.
• PII-classified attribute downgraded to INTERNAL, opening a write-back path that violates Memory governance.
• Multiple ontology versions live in the same environment because promotion was not atomic.

Operational concerns

• One pinned ontology version per environment.
• Atomic promotion across the snapshot index, the Context Pack registry, and the Decision Catalog.
• Backward compatibility for at least one minor version during deprecation windows.
• Staged rollout with shadow-compile of packs before flipping reads.
• Audit trail of approver, change class, and migration outcome.

Evaluation metrics

• Compilation success rate against the active ontology version.
• Number of breaking changes per release window.
• Mean time from authored change to production rollout.
• Migration completeness (zero open dependents at version cut-over).
• Drift detected between sibling environments (should be one minor version at most).

Example

A minimal slice of a support-domain ontology:

ontology_version: "ont.support@4.2.0"
entity_types:
  - name: Customer
    ceid_format: "customer:cus_<id>"
    attributes:
      - { name: email, type: string, classification: CONFIDENTIAL }
      - { name: lifetime_value_inr, type: number, classification: INTERNAL }
      - { name: tenure_days, type: integer, classification: INTERNAL }
    lifecycle_states: [active, dormant, churned]
  - name: Order
    ceid_format: "order:ord_<id>"
    attributes:
      - { name: total_amount_inr, type: number, classification: INTERNAL }
      - { name: created_at, type: timestamp, classification: INTERNAL }
relationship_types:
  - name: order_belongs_to_customer
    from: Order
    to: Customer
    cardinality: many_to_one
constraints:
  - "Order.total_amount_inr >= 0"
derived_fields:
  - name: order_age_days
    type: integer
    expression: "days_between(now(), Order.created_at)"
    inputs: [Order.created_at]

Common misconceptions

• It is not a database schema. Database schemas are physical layouts; the ontology is the semantic contract above them.
• It is not optional for cross-team agents. Without it, every team’s “customer” diverges and decisions become incomparable.
• It is not free to change. The runtime treats ontology changes as governance events, not config tweaks.