What is JSON Schema?
JSON Schema is a specification for describing the structure of JSON data, stating which fields exist, what types they hold, which are required, and what values are allowed. It is used both to validate documents automatically and to document them. In AI systems it is the usual way to define tool parameters and to constrain model output.
A schema is itself a JSON document. It builds up from keywords for types, required properties, string patterns, numeric ranges, enumerated values, and composition rules that combine subschemas. A validator checks a document against the schema and reports exactly which constraint failed, which makes it useful as an automatic gate rather than as hand written checking code scattered through an application.
The specification has evolved through a series of drafts, and several remain in active use, so libraries do not all support the same keyword set. Model providers typically accept only a subset, often excluding advanced composition and reference features. Writing a schema that a general purpose validator accepts is therefore no guarantee that a model provider will accept the same document.
Schemas are the shared contract between a model and the code around it. One definition can be shown to the model as guidance, used to constrain generation, and used to validate the result before anything executes. Having a single source of truth for that shape is what makes model output safe to hand to a typed system without defensive parsing everywhere.
The main pitfall is over trusting validation. A schema proves shape and not truth, so it will happily pass a syntactically perfect but entirely fabricated identifier. The other is verbosity, since deeply nested schemas with many optional branches are harder for models to satisfy and expensive to carry in context. Flattening them usually improves results.
Key points
- Declarative description of JSON structure, types, and constraints.
- Used for validation, documentation, and constraining model output.
- Several draft versions remain in use with differing support.
- Model providers usually accept only a subset of keywords.
- Validates shape and never factual correctness.
In practice
An invoice extraction step defines a schema with a required invoice_number string, a required total as a number, a currency limited to three allowed codes, and an optional array of line items. The model reads a scanned invoice and returns JSON. Anything missing the total, or using an unexpected currency, fails validation immediately, so the malformed case is caught long before it reaches the accounting system.