KiCad Protocol Schemas

@oaslananka/kicad-protocol-schemas owns the product-neutral JSON Schema contracts shared by the KiCad Studio extension and kicad-mcp-pro.

The package has no VS Code API dependency and no Python server runtime dependency. TypeScript consumers can import the schema registry and Ajv-backed validators. Python contract tests read the same schemas/*.schema.json files directly with jsonschema.

Included Contracts

• MCP tool discovery payloads returned by tools/list.
• Tool capability metadata advertised by kicad-mcp-pro.
• Extension-to-MCP active context payloads.
• Normalized DRC/ERC diagnostic records.
• BOM and netlist summary payloads.
• MCP server health/version payloads.
• Compatibility manifests for cross-product schema support.
• The existing KiCad MCP server-info contract.

Schema versioning policy

Every schema file carries an x-kicad-studio-kit.schemaVersion value using MAJOR.MINOR.PATCH. Breaking schema changes require a major version bump. Backward-compatible field additions use a minor version bump, and documentation or constraint-only fixes use a patch version bump.

The package version follows the highest schema major in the package. A consumer that supports schema major 1 may accept any 1.x.y payload after validation. Consumers must reject unknown major versions unless the caller explicitly opts into compatibility fallback behavior.

Migration policy

Schema migrations are additive first. When a field must be renamed or removed, the old field remains accepted for one minor line and the new field is documented in this README and in the affected schema description. The next major version may remove the deprecated field after extension and MCP contract tests both pass against the replacement payload.

Run the schema package checks from the repository root:

corepack pnpm run check:protocol-schemas