Skip to content

Schema index

YAML and JSON schemas used by mas-ctl validate, mas-lab check, and the benchmark UI. Files live under docs/schemas/.

Human-readable field docs are in Specifications.

Overlay and CLI merge metadata

x-merge annotations define collection identity and merge behavior for both YAML overlays and CLI --override patches. CLI overrides become canonical kind: Overlay documents, are validated against the target schema, and apply last. Root-qualified paths identify the document, for example agent:spec.tools, mas:spec.agency.agents[id=qa].spec.memory, or experiment:experiment.run.n_runs.

The canonical overlay schema is runtime/overlay.schema.yaml. Its target-specific patch fragments are overlay-agent-patch.schema.yaml, overlay-mas-patch.schema.yaml, overlay-infra-patch.schema.yaml, and overlay-flavour-patch.schema.yaml. The Overlay manifest reference defines target.kind, target.name, spec.patch, and grouped spec.overrides together.

Workspace & project

Schema Purpose
config.schema.yaml Root config.yaml — field reference (mas_ctl, flavour, infra refs, manifest_libraries:)
library.schema.yaml kind: Library (library.yaml) — labs-and-libraries.md
deployment.schema.yaml Deployment / placement descriptors
runtime-profile.schema.yaml Runtime profile flags (governance, observability)
placement-plan.schema.yaml Component placement plan
effective-bind.schema.yaml Resolved binding after overlay merge
memory-seed.schema.yaml Dataset memory seed files
checkpoint.schema.yaml Execution checkpoint payloads

Checkpoint payload version 1 contains the kernel snapshot. Version 2 also contains session lineage, working memory, and a hash-verified embedded agent manifest; see Session checkpoints.

Runtime manifests

Top-level kinds (see manifest reference):

Schema kind / role
runtime/agent.schema.yaml Agent
runtime/llm-model-catalog.schema.yaml Curated per-model context/settings — llm-model-catalog.md
runtime/mas.schema.yaml MAS
runtime/workflow.schema.yaml Workflow
runtime/overlay.schema.yaml Overlay
runtime/flavour.schema.yaml Flavour
runtime/infra.schema.yaml Infra bundle / middleware / ToolServerRegistry — infra.md · reference
runtime/tool.schema.yaml Tool definition — tool.md
runtime/fragments/infra-tool-server.schema.yaml Infra tool_servers[] item — tool-server-registry.md
runtime/tool_bundle.schema.yaml Bundled tools
runtime/prompt_bundle.schema.yaml Prompt bundles

Shared fragments under runtime/fragments/ — bindings, workflow nodes/edges, policy rules, design-pattern config, etc.

Lab & benchmarks

Schema Purpose
lab/experiment.schema.yaml experiment.yaml
lab/dataset.schema.yaml Dataset manifest
lab/pipeline.schema.yaml Pipeline step definitions
lab/lab.schema.yaml Lab folder metadata
lab/lab-config.schema.yaml Lab config, including lab.libraries
lab/run-input.schema.yaml Per-run inputs
lab/pipeline-manifest.schema.json Serialized pipeline manifest
lab/artefacts/run_info.schema.json Run metadata artefact
lab/artefacts/metrics.schema.json Metrics artefact

Contracts, components & evaluation

Schema Purpose
contracts-registry.yaml Plugin contract registry (see Contracts)
component-registry.yaml Component / plugin registry
evaluation-envelope.schema.yaml Evaluation result envelope

Examples

Sample overlays and bindings under schemas/examples/:

Plus *.example.yaml siblings next to deployment, placement, memory-seed, and runtime-profile schemas.