ADR-0054: Trails Ontology — Formal Vocabulary for Agentic Knowledge-Graph Applications¶

• Status: Accepted (2026-04-19)
• Date: 2026-04-18
• Depends on: ADR-0009 (Provenance), ADR-0011 (DID Identity), ADR-0015 (WoT AgentCard), ADR-0021 (Progressive Enhancement), ADR-0035 (Temporal KG), ADR-0051 (Agent Memory), ADR-0052 (Memory Security), ADR-0053 (Trust Boundaries)
• Target milestone: M12

Context¶

Trails introduces several novel concepts for agentic knowledge-graph applications: persistent shared memory with epistemic status, bitemporal knowledge graphs, hash-chained provenance, trust calibration, capability cost tracking, and federated knowledge sharing. These concepts are currently implemented in Python code and described in ADRs but lack a formal semantic vocabulary.

Without a published ontology: - External tools cannot interpret Trails data without framework-specific knowledge - Federation partners cannot query Trails concepts using standard SPARQL - The progressive enhancement model (labels → types → SHACL → OWL) has no OWL layer to graduate to - Novel contributions to the field are not citable or machine-discoverable

Landscape survey findings¶

Decision¶

1. Namespace and Module Structure¶

Base namespace: https://trails.dev/ont/

Modules:

Each module is a separate .ttl file with its own owl:Ontology declaration. Modules import each other where needed via owl:imports.

2. External Vocabulary Alignment¶

# Adopted — used directly
@prefix prov:    <http://www.w3.org/ns/prov#> .         # W3C Rec
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> . # W3C Rec
@prefix dcterms: <http://purl.org/dc/terms/> .           # ISO 15836
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .
@prefix time:    <http://www.w3.org/2006/time#> .        # OWL-Time W3C Rec

# Referenced — aligned via subClass/subProperty, not imported
@prefix schema:  <https://schema.org/> .
@prefix odrl:    <http://www.w3.org/ns/odrl/2/> .

3. Naming Conventions¶

Following the reference application's ontology pattern: - Classes: PascalCase (Fact, CostEnvelope, BiTemporalEntity) - Properties: camelCase (hasConfidence, learnedAt, supersedes) - Individuals: SCREAMING_SNAKE for enums (GROUND_TRUTH, SELF_REPORTED) - All individuals: a owl:NamedIndividual - All modules: include ontology metadata block (label, comment, creator, issued, versionInfo)

4. Novel Contributions¶

The following concepts have no existing standard vocabulary and represent Trails' original contributions to the semantic web:

4a. Epistemic Status Hierarchy¶

A skos:ConceptScheme expressing how certain a piece of knowledge is:

GROUND_TRUTH (1.0) — externally verifiable, authoritative source
    ▲
CONSENSUS (0.95) — multiple independent confirmations
    ▲
OBSERVATION (0.85) — agent directly observed via tool invocation
    ▲
INFERENCE (0.7) — derived from other facts through reasoning
    ▲
HYPOTHESIS (0.5) — working theory, not yet validated
    ▲
HEARSAY (0.3) — received from federation without verification

No existing ontology models this hierarchy. IAO's curation_status is the closest match but covers document lifecycle (draft → published), not epistemic certainty of knowledge.

4b. Bitemporal Knowledge Representation¶

Two independent time axes for every fact:

temp:BiTemporalEntity a owl:Class ;
    rdfs:comment "An entity with both valid time and transaction time." .

temp:validFrom a owl:DatatypeProperty ;
    rdfs:domain temp:BiTemporalEntity ;
    rdfs:range xsd:dateTime ;
    rdfs:comment "When this fact became true in the real world." .

temp:validUntil a owl:DatatypeProperty ;
    rdfs:domain temp:BiTemporalEntity ;
    rdfs:range xsd:dateTime ;
    rdfs:comment "When this fact ceased to be true in the real world." .

temp:recordedAt a owl:DatatypeProperty ;
    rdfs:domain temp:BiTemporalEntity ;
    rdfs:range xsd:dateTime ;
    rdfs:comment "When this fact was recorded in the system (transaction time)." .

temp:supersededAt a owl:DatatypeProperty ;
    rdfs:domain temp:BiTemporalEntity ;
    rdfs:range xsd:dateTime ;
    rdfs:comment "When this record was superseded by a new version." .

OWL-Time (time:) provides temporal entities and intervals but has no concept of bitemporal modeling. SQL:2011 defines bitemporal tables but has no RDF vocabulary. This is a genuine gap.

4c. Hash-Chained Provenance¶

trust:HashChainRecord a owl:Class ;
    rdfs:subClassOf prov:Activity ;
    rdfs:comment "A provenance record linked to its predecessor by cryptographic hash." .

trust:prevHash a owl:DatatypeProperty ;
    rdfs:domain trust:HashChainRecord ;
    rdfs:range xsd:string ;
    rdfs:comment "SHA-256 hash of the preceding record in the chain." .

trust:selfHash a owl:DatatypeProperty ;
    rdfs:domain trust:HashChainRecord ;
    rdfs:range xsd:string ;
    rdfs:comment "SHA-256 hash of this record (computed from canonical form)." .

No RDF vocabulary models hash-chained provenance. SCITT (IETF) defines a binary transparency log format but has no RDF projection. This bridges the gap.

4d. Agent Cost Tracking¶

cost:CostEnvelope a owl:Class ;
    rdfs:comment "A budget boundary tracking token and monetary cost of agent operations." .

cost:tokenCount a owl:DatatypeProperty ;
    rdfs:range xsd:integer ;
    rdfs:comment "Total tokens consumed (input + output)." .

cost:costUSD a owl:DatatypeProperty ;
    rdfs:range xsd:decimal ;
    rdfs:comment "Monetary cost in USD." .

cost:budgetRemaining a owl:DatatypeProperty ;
    rdfs:range xsd:decimal ;
    rdfs:comment "Remaining budget in the envelope." .

No vocabulary tracks LLM/agent operational cost. This is a new requirement driven by the economics of AI agent systems.

5. File Layout¶

ontology/
├── trails-core.ttl          # Capability, NodeType, Shape, Project
├── trails-memory.ttl        # Fact, Correction, FactLink, Topic, EpistemicStatus
├── trails-temporal.ttl      # BiTemporalEntity, ValidTime, TemporalDiff, Snapshot
├── trails-trust.ttl         # TrustLevel, SourceAttestation, HashChainRecord
├── trails-agent.ttl         # Session, Planner, Hypothesis, Plan, Step
├── trails-federation.ttl    # Peer, FederatedFact, Quarantine, PeerTrust
├── trails-cost.ttl          # CostEnvelope, Budget, TokenUsage
├── trails-alignment.ttl     # skos:exactMatch / rdfs:subClassOf to PROV-O, SKOS, DC, IAO
└── README.md                # Module overview and usage guide

6. Progressive Enhancement Alignment¶

The ontology follows the same progressive enhancement model as the framework (ADR-0021):

1. Labels only — bare @capability, @node_type, no ontology needed
2. JSON-Schema types — field validation, no ontology needed
3. SHACL shapes — generated from @shape decorators, references ontology classes
4. OWL ontology — full formal vocabulary, enables reasoning and interop

Each layer is additive. An app that uses @node_type("Fact", fields={"content": str}) works without importing the ontology. Loading the ontology adds reasoning, interoperability, and external query capability.

Non-goals¶

• Complete upper ontology — Trails does not aim to be a top-level ontology (like BFO or DOLCE). It models its own domain concepts and aligns to standards where they exist.
• Automated ontology generation from code — the ontology is hand-authored (like the reference application's). @node_type generates SHACL shapes, not OWL axioms. The ontology captures design intent, not implementation structure.
• Ontology versioning protocol — use owl:versionInfo and owl:priorVersion for now. A full versioning protocol (compatible/breaking changes, migration paths) is deferred.

Consequences¶

Positive¶

• Interoperability — external tools can query and reason over Trails data using standard SPARQL
• Citability — novel concepts (epistemic status, bitemporal KG, hash-chained provenance, agent cost) are formally defined and publishable
• Federation — peers can negotiate shared vocabulary via ontology imports
• Self-documenting — the ontology serves as a machine-readable specification of every concept in the framework

Negative¶

• Maintenance overhead — the ontology must be kept in sync with code changes. Mitigation: CI check that verifies ontology classes match @node_type registrations.
• Learning curve — users who just want @capability don't need to understand OWL. Mitigation: progressive enhancement — the ontology is optional until you need reasoning or interop.

Revisit conditions¶

• When the first external consumer adopts the ontology: validate that the vocabulary is sufficient without framework-specific knowledge
• When a W3C working group publishes a trust or epistemic ontology: evaluate alignment
• When Trails reaches v1.0: freeze the ontology namespace and publish as a stable vocabulary

Open questions¶

• Q: Should the ontology be published as a W3C Community Group spec? Recommendation: Yes, once stable. A CG spec gives it discoverability and credibility without the overhead of a full W3C Recommendation track.
• Q: Should trails.toml have an [ontology] section for configuring which modules to load? Recommendation: Yes — modules = ["core", "memory", "temporal"] in trails.toml, defaulting to all.
• Q: Should the reference application's domain ontologies (iec62304.ttl, iso14971.ttl) import from trails: namespace? Recommendation: Yes — the reference application's core:Artifact should become rdfs:subClassOf trails:Entity, establishing the dependency direction.