Configuration JSON Schema

AgentGuard publishes a versioned JSON Schema for agentguard.yaml. It provides editor validation and completion for the same public fields consumed by the production load_config path.

The canonical v1 schema is agentguard-config-v1.schema.json. It uses JSON Schema Draft 2020-12 and ships inside the agentguard-evals wheel and source distribution as agentguard/schemas/agentguard-config-v1.schema.json.

Source of truth and drift checks

The production loader remains authoritative because it also performs checks that a data-only JSON Schema cannot perform, including resolving repository and prompt-file paths, checking prompt-file existence and size, normalizing guard ignore paths, and comparing cross-field, aggregate, UTF-8 byte, and filesystem limits. YAML can also represent non-finite floats such as .nan and .inf, which are outside JSON Schema's standard JSON data model; the production loader explicitly rejects them in metadata and numeric configuration fields.

The additive contained_execution block is a version-aware contract for agentguard contained-run. Ordinary agentguard ci, local-command, agent-command, and other uncontained paths reject configs with this block before running tests or agents. The contract is documented in Contained Execution Contract, including Linux Docker Engine as the supported platform, Docker Desktop as experimental/reduced-claim, default network none, digest-required image provenance, required non-root UID/GID Docker preflight values, evidence outside the agent-mounted repository, explicit environment allowlists with no ambient token forwarding, and rejection of privileged containers, host networking, Docker socket mounts, device exposure, and host namespace sharing. Omitting the block preserves existing behavior.

The checked-in JSON file is the canonical editor schema. CI runs python scripts/validate_config_schema.py, which:

1. checks the schema itself with a Draft 2020-12 validator;
2. validates every maintained file under examples/configs/ against it; and
3. loads those same files through production load_config.

Focused contract tests additionally compare the schema's top-level fields, policy names, enums, built-in detector IDs, field bounds, required fields, nested property sets, conditionals, and unknown-property behavior with loader constants and a loader-versus-schema parity corpus. Changes to either side must therefore update the contract and examples together. The production loader is still the final validation authority at execution time.

When sandbox.docker.cpus is a string, the shared schema/loader contract uses a bounded positive decimal or scientific form (for example, "0.5" or "1e3"). Native numeric values must also be finite and positive. This keeps editor validation deterministic instead of inheriting every platform-specific spelling accepted by Python's float() conversion.

VS Code

Install the YAML extension by Red Hat, then add a repository setting in .vscode/settings.json:

{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/richinmrudul/agentguard/main/agentguard/schemas/agentguard-config-v1.schema.json": "agentguard.yaml"
  }
}

Pin a released schema by replacing main with a release tag that contains the schema. A repository may also use a relative path to a vendored copy.

YAML Language Server modeline

YAML Language Server users can associate one file without editor settings:

# yaml-language-server: $schema=https://raw.githubusercontent.com/richinmrudul/agentguard/main/agentguard/schemas/agentguard-config-v1.schema.json
task_id: pr_safety_check
description: Validate this pull request after tests run.
mode: ci
test_command: pytest
expected_modified_files:
  min: 0
  max: 25

The schema improves editing but does not replace agentguard ci --config agentguard.yaml. AgentGuard CI performs post-execution validation; neither the schema nor the CI configuration contains an untrusted coding agent.