Schema Registry

The Agent Format Schema Registry hosts canonical JSON Schemas for every released version of the specification. SDKs, editors, and CI pipelines should reference these schemas for validation.

Schema URLs

Version	Status	Schema URL
1.0.0	Current	https://agentformat.org/schema/1.0/agentformat-schema.json

tip

Point your editor or CI tool at the canonical URL to get automatic validation. See Editor Setup below.

Versioning Convention

Schema URLs follow the pattern:

https://agentformat.org/schema/<major>.<minor>/agentformat-schema.json

• Patch versions (1.0.1) share the same schema file as their minor version — patch releases only change documentation, not the schema itself.
• Minor versions (1.1.0) get a new directory (/schema/1.1/). Minor schemas are backward-compatible supersets of the previous minor version.
• Major versions (2.0.0) get a new directory (/schema/2.0/). Major schemas may contain breaking changes and will include a migration guide.

Using the Schema in .agf.yaml

Every .agf.yaml file declares its schema version:

schema_version: "1.0.0"

The runtime uses this field to select the correct JSON Schema for validation. The schema_version field is required and MUST be a valid semver string.

Editor Setup

VS Code

Add to your .vscode/settings.json:

{
  "yaml.schemas": {
    "https://agentformat.org/schema/1.0/agentformat-schema.json": "*.agf.yaml"
  }
}

This enables autocompletion, hover documentation, and inline validation for all .agf.yaml files.

JetBrains IDEs

1. Open Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings
2. Add a new mapping:
   • Name: AgentFormat
   • Schema URL: https://agentformat.org/schema/1.0/agentformat-schema.json
   • File path pattern: *.agf.yaml

CI Validation

Use the agf CLI to validate against the schema in your CI pipeline:

info

The agf CLI will be publicly available soon. See the CLI Reference for the command reference.

agf lint my-agent.agf.yaml

Or validate directly against the schema using any JSON Schema validator:

# Using ajv-cli
ajv validate -s https://agentformat.org/schema/1.0/agentformat-schema.json -d my-agent.agf.yaml

Migration Guides

Migration guides are published with each major version release:

Migration	Status
1.x to 2.x	Not yet available (no breaking changes planned)

Playground

Validate your .agf.yaml interactively in the browser using the Validator Playground.