JSON Schemas & Contracts

FleetForge publishes canonical JSON Schemas under api/schemas/. SDKs, runtime validations, and docs all ingest the same files so configuration and run payloads stay consistent.

Looking for the explorer?

Open the Schemas Explorer for direct links to the JSON sources plus the regeneration command. This doc stays the canonical reference; the explorer is just a quick-launch surface.

Schema inventory

Schema	Path	Description
Run spec	api/schemas/run_spec.json	Planner output (steps, adapters, budgets) submitted to runs.create.
Run event	api/schemas/run_event.json	Streaming tap payloads (step_started, tool_output, guardrail verdicts).
Capability token	api/schemas/capability_token.json	Scope/budget records minted per step.
Agent run	api/schemas/agent_run.json	High-level run envelope referencing step attestations.
Artifact	api/schemas/artifact.json	Signed artifacts plus manifest metadata.
Step	api/schemas/step.json	Deterministic replay snapshot per agent/tool step.

Regenerating schema docs

pnpm -C docs run generate:schemas

The script converts the JSON Schemas into Markdown under docs/reference/schemas/ for deep dives. Update this page when new schemas land or existing ones change.

Usage tips

• Treat these schemas as source of truth for SDK typings; sdk/typescript and sdk/python import them during build.
• CI runs just lint + schema validation to prevent breaking changes; use buf breaking + pnpm docs generate:schemas before pushing contract updates.
• Link to the relevant schema from How-to/Concept docs instead of duplicating field tables.