Schema Contract

The AI schema contract defines the JSON structure that AI consumers MUST accept when receiving IDL information and MUST produce when generating IDL-conformant output. The schema is machine-validated and versioned independently from the IDL grammar version. Breaking schema changes — changes that would cause previously valid JSON to fail schema validation — require a major schema version increment.

Schema Structure

The AI schema contract exposes IDL constructs as JSON objects with a defined set of required and optional properties. Token objects include: name, type, tier, value (for concrete tokens), alias (for alias tokens), and metadata. Component objects include: identifier, version, props, slots, states, transitions, variants, and token-references. The schema is defined using JSON Schema draft-07.

Schema Versioning

The schema version is encoded in every serialised object in the root schemas property. AI consumers MUST declare the schema version they produce and consume. When an AI consumer produces output against schema version N and the current validation layer enforces schema version N+1, the validation layer MUST accept schema version N output for a defined compatibility window — currently one major schema version.

Schema Contract and Prompt Primitives

Prompt primitives (defined in 08-prompt-primitives) encode the schema contract in natural language for injection into AI system prompts. When an AI system produces JSON output that fails schema validation, the most common cause is a mismatch between the prompt primitive version used in the system prompt and the current schema version. Keeping prompt primitives and schema versions synchronised is a governance responsibility.