Skip to content

Schema index

This page lists the YAML and JSON schemas that mas-ctl validate, mas-lab check, and the benchmark UI use. A schema states which keys a manifest may hold and what type each has. The files live under docs/schemas/.

Example: check an agent manifest against its schema.

mas-ctl validate agent.yaml

Human-readable field docs are in Specifications.

Hand-written vs generated

Every file under docs/schemas/ is hand-written. It is the single source of truth. Nothing in that folder is generated. These artifacts derive from it:

Generated file Generator Inputs
runtime/src/mas/runtime/spec/schema_bindings_generated.py (binding key sets) python scripts/gen_schema_artifacts.py (--check fails when stale) runtime/fragments/*-binding, context-manager-*-params, infra-*-params
runtime/src/mas/runtime/spec/schema_defaults_generated.py (default constants) same execution-binding, context-manager-*-params, agent.schema.yaml
ui/src/types/agent-types.ts, ui/src/types/mas-types.ts yarn generate:types in ui/ Resolved agent / mas schemas from mas-lab serve GET /api/schemas/{id}?resolved=1

Two hand-written runtime package schemas live outside this folder: runtime/src/mas/runtime/defaults.schema.yaml (built-in defaults.yaml) and runtime/src/mas/runtime/aliases.schema.yaml (plugin alias table).

Overlay and CLI merge metadata

The session tree maps address prefixes to each owning manifest reference and schema.

x-merge annotations define collection identity and merge behaviour. They apply to both YAML overlays and CLI --override patches.

  • CLI overrides become canonical kind: Overlay documents.
  • The runtime validates them against the target schema.
  • They apply last.
  • Session-tree paths identify the document, for example .agent.spec.tools, .mas.agent[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 and project

Schema Purpose
config.schema.yaml Root config.yaml. See the field reference (mas_ctl, mas_lab, infra refs, manifest_libraries:)
library.schema.yaml kind: Library (library.yaml). See 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 and settings. See 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. See infra.md and the reference.
runtime/tool.schema.yaml Tool definition. See tool.md
runtime/fragments/infra-tool-server.schema.yaml Infra tool_servers[] item. See tool-server-registry.md
runtime/tool_bundle.schema.yaml Bundled tools
runtime/prompt_bundle.schema.yaml Prompt bundles

Shared fragments live under runtime/fragments/. They cover bindings, workflow nodes and edges, policy rules, and design-pattern config.

Lab and 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

Shared lab fragments live under lab/fragments/: memory-seed-entry, message (conversation message), ref (file ref), and tool-fixture-mapping.

Contracts, components, and evaluation

Schema Purpose
contracts-registry.yaml Plugin contract registry. See Contracts.
component-registry.yaml Embedder-chosen component ids (runtimes, placement backends, framework adapters); manifest plugins resolve through PluginRegistry instead. See Thin waist.
evaluation-envelope.schema.yaml Evaluation result envelope

Examples

Sample overlays and bindings under schemas/examples/:

The deployment, effective-bind, placement, memory-seed, and runtime-profile schemas also have *.example.yaml siblings, including deployment.local-inproc.example.yaml.

See also