@agenticprimitives/ontology
A trust substrate is only as coherent as its vocabulary. When thirty packages, forty-two contracts, and a knowledge graph all talk about agents, credentials, custody, and delegation, "what exactly is a CredentialFacet" cannot have thirty answers. This package is the monorepo-wide formal vocabulary — the off-chain source of truth that the on-chain ontology (ADR-0009) instantiates and that identity-directory (spec 223) conforms to.
It is deliberately declarative: it names and constrains, it never authorizes. The vocabulary root depends on nothing — not even @agenticprimitives/types — so every other package can reference the same IRIs without inverting the dependency graph.
Part of agenticprimitives — the trust substrate for the agent economy: one canonical Smart Agent identity with custody, delegation, naming, credentials, and audit evidence designed as one system.
See spec 225 for the full contract and ADR-0018 for the decision.
Layout (T-box / C-box / A-box)
context.jsonld @context — namespace prefix → IRI bindings
tbox/ RDFS/OWL schema (classes + properties), per domain
cbox/ SHACL shapes + SKOS controlled vocabularies (codelists)
abox/ example / fixture instances (tests + golden vectors only)
mappings/ external-standard crosswalks (HCS / ERC-8004, spec 226)
src/index.ts typed IRI constants + artifact paths
T-box = terminology, C-box = constraints + controlled vocabularies, A-box = instances.
UML class-diagram documentation of the T-box — inheritance + relationships per domain area —
lives in docs/tbox/. For the plain-language version — the principles
the vocabulary protects and why — start with docs/story.md.
Usage
import { NS, CLASS, SHAPE, ARTIFACTS, artifactPath } from '@agenticprimitives/ontology';
CLASS.CanonicalAgentId; // "https://agenticprimitives.dev/ns/core#CanonicalAgentId"
artifactPath(ARTIFACTS.tbox[0]); // absolute path to tbox/core.ttl — load into a SPARQL store
Two entry points, split on purpose:
- Main entry (browser-safe) — pure IRI constants:
NS,CLASS,PREDICATE,SHAPE,ONTOLOGY_VERSION. No Node builtins; this is whatidentity-directory(and through it, browser apps) imports. /artifactssubpath (Node-only) —ARTIFACTS+artifactPath(rel)to resolve the shipped TTL/JSON-LD files for a SPARQL loader or SHACL engine. Server-side only.
How it's different
Generic SKOS/SHACL toolchains manage vocabularies as documents — governed in an editor, detached from the systems that depend on them, drifting the moment runtime code changes. Here the vocabulary is load-bearing and lockstep-checked in three directions:
- On chain — a shape or predicate here must match its on-chain counterpart in
OntologyTermRegistry/ShapeRegistry(spec 225 §8); drift is logged as a finding, not tolerated as skew. - In TypeScript — the IRIs mirror the branded types in
types(CanonicalAgentId,Assurance, …). One brand; this package names the IRI, never redefines the type. - Across standards —
mappings/*.ttlcarries explicit crosswalks to external agent-identity standards (HCS, ERC-8004, OASF) instead of informal "roughly corresponds to" prose.
And it ships light: no heavy RDF/SHACL libraries in the published surface — consumers wire their own engines against the artifacts.
Scope
Bounded to generic AP primitives: identity, credential, custody, delegation, audit, naming, org, registry/discovery, trust, public exposure findings, and the substrate-spine T-box class definitions (spec 225 §11.5). Runtime SHACL shapes for product flows live in their owning packages; GraphDB A-box ingestion shapes for discovery live in cbox/discovery-graph-shapes.shacl.ttl; vertical vocabulary remains app-owned (ADR-0021).
The discovery ontology deliberately builds from the domain-derived vocabulary shape in Agent Explorer's apps/ontology/ontology modules — core.ttl, discovery.ttl, descriptors.ttl, erc8004.ttl, hol.ttl, oasf.ttl, and trust.ttl — while refining it into AP-native namespaces rooted in PROV-O and DOLCE+DnS/DUL.
Module map (additions by spec)
| Concern | T-box | C-box |
|---|---|---|
| Identity, kinds, derived types | tbox/core.ttl, tbox/identity.ttl | cbox/controlled-vocabularies.ttl, cbox/canonical-agent-id-shape.shacl.ttl |
| Typed naming, registry core (spec 346) | tbox/naming.ttl, tbox/registry.ttl | cbox/naming-registry-shapes.shacl.ttl, cbox/registry-vocabulary.ttl |
| Capabilities, claims, taxonomy mappings (specs 251/325/347 §5) | tbox/skills.ttl (aps:SkillTaxonomyMapping — relation = a SKOS mapping property) | cbox/skill-vocabulary.ttl, cbox/capability-catalog-shapes.shacl.ttl |
| Canonical profile → A2A Agent Card → projection → publication → external identity binding (spec 347 §11; ADR-0062) | tbox/card-projection.ttl — a second module of the ap: core namespace; PROV-O-grounded (generation/publication ⊑ prov:Activity; artifact/releases ⊑ prov:Entity; publisher/adapter ⊑ prov:SoftwareAgent); "canonical agent" ≡ ap:Agent, no second class | cbox/card-projection-shapes.shacl.ttl — public card metadata; projection provenance (all eight digests as named sub-properties of ap:hasDigest); external binding; public disclosure boundary (SPARQL-targeted at ap:disclosureScope "public": no loopback / private / link-local endpoint, no vault locator; absence of scope is private). Codelists ap:lossCategoryScheme, card-release / projection-instance / binding lifecycles, ap:bindingVerificationStateScheme, ap:digestRoleScheme in cbox/controlled-vocabularies.ttl |
| Agentic interaction (spec 340) | tbox/interaction.ttl | cbox/interaction-shapes.shacl.ttl, cbox/interaction-vocabulary.ttl |
| Coordination / engagement / execution (specs 332/336/330) | tbox/coordination.ttl, tbox/engagement.ttl, tbox/execution.ttl, tbox/plan.ttl | — |
What this is NOT
- Not the TS types —
@agenticprimitives/typesownsCanonicalAgentId,Assurance, etc.; this package names the IRIs. One brand. - Not the runtime CAIP-10 builder — that is
@agenticprimitives/agent-profile. - Not an authority — it names and validates; it never grants custody or mints identity.
Status
Phase 1 implemented — the T/C/A-box artifacts, mappings, and the declarative TS surface ship today. SHACL-engine validation over instances and the live A-box knowledge graph (a SPARQL store — Ontotext GraphDB reference, projected by identity-directory) are Phase 2, wired by consumers per spec 225 §11 — and even then the ontology stays a validator, never an authority.
Testnet/pilot-ready. Production launch is gated on the public checklist in the root README — including third-party contract audit and governance key rotation. Track every security finding live in
docs/audits/findings.yaml.
Authoritative spec: specs/225-ontology.md. Bounded surface: CLAUDE.md + capability.manifest.json.
Build
pnpm --filter @agenticprimitives/ontology typecheck
pnpm --filter @agenticprimitives/ontology test
pnpm --filter @agenticprimitives/ontology build