Specs and Schemas

SOIT is spec-first. Platform primitives are described by versioned JSON Schemas before they become runtime behavior — any new capability starts with a spec update, and the runtime validates incoming spec JSON against its schema.

Schema location

Kernel v1 schemas live under:

soit/server/app/kernel/specs/v1

Current schema families include agents, chat, knowledge, memory, nodes, notifications, plugins, refs, run traces, tools, and workflows.

Refs: the cross-resource language

All cross-resource references follow refs.schema.json — a stable string format of kind:qualifier:name:

model:openai:gpt-4.1      # a model on a provider
knowledge:kb_support      # a knowledge base
tool:http:ticket_create   # an HTTP tool
node:tool:health_check    # a workflow node
wf:rag_answer             # a workflow
secret:zendesk_token      # a secret reference

Refs are what make typed bindings source-agnostic: an agent spec binds tool:http:ticket_create without caring whether that tool is built-in or plugin-exported.

Rules

• Keep v1 stable. Prefer additive optional fields for minor changes; breaking changes require a new schema version.
• Validate at the boundary. Runtime validates spec_json, manifest_json, and graph_json against the appropriate schema before persistence or execution.
• Ship examples. Spec changes must include examples close to the schema — they double as documentation and test fixtures.
• Immutability applies. Once a version row is created, its spec_json is never edited in place (see Versioning and Release).

Why it matters

Schemas make APIs, storage, runtime validation, and documentation share the same contract language. A reviewer can evaluate a new capability from its spec diff before any runtime code exists, and the platform can reject malformed definitions at every boundary instead of failing mid-execution. Spec validation rejection is one of the mandatory test cases in the quality gate.