@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 what identity-directory (and through it, browser apps) imports.
• /artifacts subpath (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:

1. 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.
2. In TypeScript — the IRIs mirror the branded types in types (CanonicalAgentId, Assurance, …). One brand; this package names the IRI, never redefines the type.
3. Across standards — mappings/*.ttl carries 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/types owns CanonicalAgentId, 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