{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://toolpath.dev/schema/toolpath.schema.json",
"title": "Toolpath",
"description": "A tool-agnostic format for tracking artifact transformation provenance",
"$defs": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp"
},
"actorRef": {
"type": "string",
"pattern": "^(human|agent|tool|ci):[a-zA-Z0-9_-]+(\/[a-zA-Z0-9_.-]+)?$",
"description": "Actor reference string (e.g., 'human:alex', 'agent:claude-code', 'tool:rustfmt/1.5.0')",
"examples": ["human:alex", "agent:claude-code", "tool:rustfmt", "ci:github-actions"]
},
"identity": {
"type": "object",
"description": "External identity reference",
"properties": {
"system": {
"type": "string",
"description": "Identity system (e.g., 'github', 'email', 'orcid')",
"examples": ["github", "gitlab", "email", "twitter", "orcid", "crates.io", "npm", "anthropic"]
},
"id": {
"type": "string",
"description": "Identifier within the system"
}
},
"required": ["system", "id"],
"additionalProperties": false
},
"key": {
"type": "object",
"description": "Cryptographic key reference",
"properties": {
"type": {
"type": "string",
"enum": ["gpg", "ssh", "sigstore"],
"description": "Key type"
},
"fingerprint": {
"type": "string",
"description": "Key fingerprint or identifier"
},
"href": {
"type": "string",
"format": "uri",
"description": "URL to retrieve the public key"
}
},
"required": ["type", "fingerprint"],
"additionalProperties": false
},
"actorDefinition": {
"type": "object",
"description": "Full actor definition with identity and key information",
"properties": {
"name": {
"type": "string",
"description": "Display name"
},
"provider": {
"type": "string",
"description": "Provider (for agents)"
},
"model": {
"type": "string",
"description": "Model identifier (for agents)"
},
"identities": {
"type": "array",
"items": { "$ref": "#/$defs/identity" },
"description": "External identities"
},
"keys": {
"type": "array",
"items": { "$ref": "#/$defs/key" },
"description": "Cryptographic keys"
}
},
"additionalProperties": false
},
"actors": {
"type": "object",
"description": "Map of actor references to their definitions",
"propertyNames": { "$ref": "#/$defs/actorRef" },
"additionalProperties": { "$ref": "#/$defs/actorDefinition" }
},
"signature": {
"type": "object",
"description": "Cryptographic signature",
"properties": {
"signer": {
"$ref": "#/$defs/actorRef",
"description": "Actor who signed"
},
"key": {
"type": "string",
"description": "Key identifier (type:fingerprint)",
"examples": ["gpg:ABCD1234", "ssh:SHA256:abc123"]
},
"scope": {
"type": "string",
"enum": ["author", "reviewer", "witness", "ci", "release"],
"description": "Role of the signer"
},
"timestamp": {
"$ref": "#/$defs/timestamp",
"description": "When the signature was created"
},
"sig": {
"type": "string",
"description": "The signature data"
}
},
"required": ["signer", "key", "scope", "sig"],
"additionalProperties": false
},
"ref": {
"type": "object",
"description": "Reference to external resource",
"properties": {
"rel": {
"type": "string",
"description": "Relationship type",
"examples": ["fixes", "implements", "references", "milestone", "changelog"]
},
"href": {
"type": "string",
"description": "URI of the referenced resource"
}
},
"required": ["rel", "href"],
"additionalProperties": false
},
"artifactChange": {
"type": "object",
"description": "Change to a single artifact with one or more perspectives",
"properties": {
"raw": {
"type": "string",
"description": "Unified Diff format change"
},
"structural": {
"type": "object",
"description": "Language-aware structural operation",
"properties": {
"type": {
"type": "string",
"description": "Operation type (e.g., 'rust.add_items', 'core.replace')"
}
},
"required": ["type"],
"additionalProperties": true
}
},
"anyOf": [
{ "required": ["raw"] },
{ "required": ["structural"] }
],
"additionalProperties": false
},
"change": {
"type": "object",
"description": "Map of artifact URLs to their changes",
"additionalProperties": { "$ref": "#/$defs/artifactChange" }
},
"vcsSource": {
"type": "object",
"description": "Reference to a VCS revision that produced this step",
"properties": {
"type": {
"type": "string",
"description": "VCS type (git, hg, fossil, jj, svn, darcs, etc.)",
"examples": ["git", "hg", "fossil", "jj", "svn", "darcs"]
},
"revision": {
"type": "string",
"description": "Full revision identifier (commit hash, revision number, etc.)"
},
"change_id": {
"type": "string",
"description": "Change ID for VCS systems that distinguish changes from commits (e.g., jj)"
}
},
"required": ["type", "revision"],
"additionalProperties": true
},
"stepMeta": {
"type": "object",
"description": "Optional metadata for a step",
"properties": {
"intent": {
"type": "string",
"description": "Human-readable description of purpose"
},
"source": {
"$ref": "#/$defs/vcsSource",
"description": "VCS revision this step was derived from"
},
"refs": {
"type": "array",
"items": { "$ref": "#/$defs/ref" },
"description": "Links to issues, docs, reasoning"
},
"actors": {
"$ref": "#/$defs/actors",
"description": "Actor definitions (for standalone steps)"
},
"signatures": {
"type": "array",
"items": { "$ref": "#/$defs/signature" },
"description": "Cryptographic signatures"
}
},
"additionalProperties": true
},
"stepIdentity": {
"type": "object",
"description": "Step identity and lineage",
"properties": {
"id": {
"type": "string",
"description": "Unique step identifier"
},
"parents": {
"type": "array",
"items": { "type": "string" },
"description": "Parent step IDs (empty or omitted for root steps)"
},
"actor": {
"$ref": "#/$defs/actorRef",
"description": "Actor who performed this step"
},
"timestamp": {
"$ref": "#/$defs/timestamp",
"description": "When the step was performed"
}
},
"required": ["id", "actor", "timestamp"],
"additionalProperties": false
},
"step": {
"type": "object",
"description": "A single change to one or more artifacts",
"properties": {
"step": {
"$ref": "#/$defs/stepIdentity"
},
"change": {
"$ref": "#/$defs/change"
},
"meta": {
"$ref": "#/$defs/stepMeta"
}
},
"required": ["step", "change"],
"additionalProperties": false
},
"base": {
"type": "object",
"description": "Root context for a path. The URI identifies the origin (repository, filesystem, or another toolpath document); all other fields are optional.",
"properties": {
"uri": {
"type": "string",
"description": "Origin identifier: a repository (e.g., 'github:org/repo'), a filesystem location (e.g., 'file:///path/to/repo'), or another toolpath step ('toolpath:path-id/step-id').",
"examples": ["github:org/repo", "svn://server/repo", "file:///path/to/repo", "toolpath:path-main/step-005"]
},
"ref": {
"type": "string",
"description": "State identifier the origin uses to name a specific reproducible state — commit hash, tag, revision number, changeset ID, etc. Interpretation depends on the origin.",
"examples": ["abc123def456", "12345", "v1.0"]
},
"branch": {
"type": "string",
"description": "Branch name the path was opened against, when one applies.",
"examples": ["main", "release/v2", "feature/auth"]
}
},
"required": ["uri"],
"additionalProperties": false
},
"pathIdentity": {
"type": "object",
"description": "Path identity and context",
"properties": {
"id": {
"type": "string",
"description": "Unique path identifier"
},
"base": {
"$ref": "#/$defs/base",
"description": "Root context this path branches from. Optional: paths derived from a sealed agent session or a synthetic single-step graph may have no upstream VCS state to anchor to."
},
"head": {
"type": "string",
"description": "Current tip step ID"
},
"graph_ref": {
"type": "string",
"description": "Optional $ref-style URL naming the graph this path belongs to",
"examples": [
"toolpath://archive/release-v2",
"https://archive.example.com/graphs/release-v2.json"
]
}
},
"required": ["id", "head"],
"additionalProperties": false
},
"pathMeta": {
"type": "object",
"description": "Optional metadata for a path",
"properties": {
"title": {
"type": "string",
"description": "Human-readable title"
},
"source": {
"type": "string",
"description": "Source reference (e.g., PR URL)"
},
"intent": {
"type": "string",
"description": "Human-readable description of purpose"
},
"refs": {
"type": "array",
"items": { "$ref": "#/$defs/ref" },
"description": "Links to issues, docs, reasoning"
},
"actors": {
"$ref": "#/$defs/actors",
"description": "Actor definitions shared by steps"
},
"signatures": {
"type": "array",
"items": { "$ref": "#/$defs/signature" },
"description": "Cryptographic signatures"
}
},
"additionalProperties": true
},
"path": {
"type": "object",
"description": "Collection of steps with base context",
"properties": {
"path": {
"$ref": "#/$defs/pathIdentity"
},
"steps": {
"type": "array",
"items": { "$ref": "#/$defs/step" },
"description": "Steps in this path"
},
"meta": {
"$ref": "#/$defs/pathMeta"
}
},
"required": ["path", "steps"],
"additionalProperties": false
},
"pathRef": {
"type": "object",
"description": "Reference to an external path",
"properties": {
"$ref": {
"type": "string",
"format": "uri",
"description": "URL to the external path document"
}
},
"required": ["$ref"],
"additionalProperties": false
},
"pathOrRef": {
"oneOf": [
{ "$ref": "#/$defs/path" },
{ "$ref": "#/$defs/pathRef" }
],
"description": "Either an inline path or a reference to an external path"
},
"graphIdentity": {
"type": "object",
"description": "Graph identity",
"properties": {
"id": {
"type": "string",
"description": "Unique graph identifier"
}
},
"required": ["id"],
"additionalProperties": false
},
"graphMeta": {
"type": "object",
"description": "Optional metadata for a graph",
"properties": {
"title": {
"type": "string",
"description": "Human-readable title"
},
"intent": {
"type": "string",
"description": "Human-readable description of purpose"
},
"refs": {
"type": "array",
"items": { "$ref": "#/$defs/ref" },
"description": "Links to milestones, changelogs, etc."
},
"actors": {
"$ref": "#/$defs/actors",
"description": "Actor definitions shared by paths"
},
"signatures": {
"type": "array",
"items": { "$ref": "#/$defs/signature" },
"description": "Cryptographic signatures (e.g., release signature)"
}
},
"additionalProperties": true
},
"graph": {
"type": "object",
"description": "Collection of related paths",
"properties": {
"graph": {
"$ref": "#/$defs/graphIdentity"
},
"paths": {
"type": "array",
"items": { "$ref": "#/$defs/pathOrRef" },
"description": "Paths in this graph (inline or referenced)"
},
"meta": {
"$ref": "#/$defs/graphMeta"
}
},
"required": ["graph", "paths"],
"additionalProperties": false
}
},
"$ref": "#/$defs/graph"
}