npm package · typescript · zero dependencies

JSON-native ontology schemas
for AI agents

Five built-in schemas — Agent, Entity, Relationship, Context, Registry — give multi-agent systems a shared vocabulary for delegation, trust, and authority. Define your own schemas in the same idiom.

$npm install jsontology
v0.1.0
typescript
import { schemas, validateAuthority } from "jsontology";

// Validate an agent's shape and trust rules:
const agent = {
  id: "agent-alpha",
  label: "Agent Alpha",
  role: "orchestrator",
  trust: { score: 0.95, level: "authoritative" },
};
schemas.Agent.validate(agent);
// { valid: true, errors: [] }

// Catch unauthorized spawns before they run:
const registry = {
  id: "reg-prod", name: "Prod Registry", governance: "authoritative",
  entries: [{ id: "agent-alpha", type: "agent" }],
};
validateAuthority({ agent: { id: "agent-pierre", label: "Pierre", role: "delegate" }, registry });
// { valid: false, errors: [{ code: "unauthorized_spawn", ... }] }
// jsontology reports; your orchestrator enforces.
Diagram of jsontology's validateAuthority example: a registry containing agent-alpha and an agent named agent-pierre with role delegate both feed validateAuthority(), which authorizes agents present in the registry and rejects agents that are not.Diagram of jsontology's validateAuthority example: a registry containing agent-alpha and an agent named agent-pierre with role delegate both feed validateAuthority(), which authorizes agents present in the registry and rejects agents that are not.
The example above, as a graph · Made with CanonDraw
Built-in schemas

Five schemas. One shared vocabulary.

Click any schema to explore its properties. Blue dots are required fields. Click object-type fields to expand nested properties.

$jsontology/agent
Agent
An AI agent with defined capabilities, roles, delegation authority, and trust boundaries.
authority: issuerdelegation: explicittrust: federated
idstring
Unique canonical identifier for this agent
labelstring
Human-readable name
rolestring
Functional role in a multi-agent system
enum: "orchestrator" | "specialist" | "observer" | "delegate" | "registry"
capabilitiesarray<string>
Capability identifiers this agent can perform
authority ▸object
Delegation and authority scope
trust ▸object
Trust assessment
disclosurestring
How this agent's identity is disclosed
enum: "public" | "private" | "federated"

required field    optional field    ▸ click object fields to expand

API reference

Two functions. Fully typed.

FunctionReturnsWhat it does
schemas.X.validate(data){ valid, errors }Validate against a built-in schema. Errors carry path, code, and message.
validate(schema, data){ valid, errors }Validate any object against any schema. Same return shape as above.
defineOntology(schema, rules?)DefinedOntologyDefine a typed, frozen schema with optional cross-field rules. Requires $id, title, description. Returns schema with bound .validate().
validateAuthority(req){ valid, errors }Validate a proposed agent spawn against a registry contract. Catches unauthorized agents and authority mismatches.
Flow diagram of jsontology validation: a Schema input and a Data input both feed the validate() function, which returns a Result object containing valid and errors fields.Flow diagram of jsontology validation: a Schema input and a Data input both feed the validate() function, which returns a Result object containing valid and errors fields.
validate(schema, data) — same contract everywhere · Made with CanonDraw
Custom schemas
typescript
import { defineOntology } from "jsontology";
import type { Rule } from "jsontology";

const budgetRule: Rule = (data) =>
  (data.amount as number) > (data.limit as number)
    ? [{ path: "$.amount", code: "exceeds_limit", message: "amount exceeds limit" }]
    : [];

const HandoffSchema = defineOntology({
  $id: "my-app/handoff",
  title: "Agent Handoff",
  description: "Task delegation from one agent to another",
  type: "object",
  required: ["from", "to", "task"],
  properties: {
    from:  { type: "string" },
    to:    { type: "string" },
    task:  { type: "string" },
    ttl:   { type: "number", minimum: 0 },
  },
  $delegation: "explicit",
  $governance: "authoritative",
});

HandoffSchema.validate({ from: "a", to: "b", task: "summarise" });
// { valid: true, errors: [] }
Web4 vocabulary annotations

Annotations are metadata — they do not affect validation. They provide interoperability context for registries and agent systems.

FieldValuesMeaning
$authoritystringWho asserts this schema's authority
$delegation"explicit" | "implicit" | "none"Delegation model for this schema type
$trust"public" | "private" | "federated"Trust boundary for schema instances
$governance"authoritative" | "federated" | "consensus" | "open"How schema entries are validated
$registrystringID of the governing registry
Shipping this to production?

Digital Solution Delivery designs and hardens jsontology-powered agent schemas — delegation contracts, registries, and validation pipelines — for teams putting multi-agent systems into production.

Book a schema design sprint →
MIT License · askander.net
Need help designing agent authority for production? →GitHub
⬡ AskanderWork with us·agentontology.organthropontology.comgraphontology.comweb4intelligence.orglinkcanon.comcanondraw.comweb4research.orgweb4asean.com