Wiki · Concept · Last reviewed June 25, 2026

JSON Schema

JSON Schema is the standards vocabulary for describing and validating JSON data: useful for APIs, structured model outputs, and agent tool boundaries, but too narrow to stand in for truth or governance.

Category: Concept / Structured Data Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: June 25, 2026 Tags: JSON Schema, structured outputs, tool use, OpenAPI, agents, validation

Definition

JSON Schema is a JSON-based format for describing the structure of JSON data. The JSON Schema specification page lists 2020-12 as the current version and says the specification is split into Core and Validation, with Relative JSON Pointers published alongside them. Core defines the basic foundation: references, dialects, vocabularies, identifiers, and expected output. Validation defines the keywords used to make assertions about what a valid JSON instance must look like.

The key word is instance. A schema is applied to a JSON value, and the validator reports whether that value satisfies the applicable assertions. A schema can also carry annotations that are useful to documentation, user interfaces, code generation, or review workflows. This makes JSON Schema a bridge between data exchange and institutional memory: it records what shape a payload was expected to have when a system accepted it.

It is not an ontology, permission system, privacy review, content policy, or proof that a value is true. It can say that amount is a number and currency must be one of several strings. It cannot decide whether the payment is legitimate.

Mechanism

A JSON Schema document is itself JSON, and the Core specification says a schema must be an object or a boolean. Common keywords include $schema for declaring the dialect, $id for identifying a schema resource, $ref for references, $defs for reusable subschemas, and validation keywords such as type, properties, required, items, prefixItems, enum, const, minimum, pattern, oneOf, anyOf, and allOf.

The 2020-12 draft page records several important changes. Tuple validation was redesigned around prefixItems and items; $dynamicRef and $dynamicAnchor replaced earlier recursive-reference keywords; and the format vocabulary was separated into annotation and assertion vocabularies. Those details matter because a schema is not just "a schema"; it belongs to a dialect, and validators may support different drafts or vocabularies.

Agent Context

For AI systems, JSON Schema is useful wherever Structured Outputs and Constrained Decoding, Tool Use and Function Calling, or generated API clients need a reviewable argument shape. A tool host can ask a model for arguments that match a schema, reject malformed JSON, and preserve the validation error as evidence. That is a real improvement over accepting free-form text and hoping downstream software can guess the intent.

But schema-conforming output is still only syntactic discipline plus limited structural checks. A model can produce valid JSON with the wrong customer, a misleading explanation, a stale identifier, or a dangerous operation. The schema narrows the envelope. It does not certify the envelope's contents.

Governance Use

A governed agent system should log the schema URI, dialect, schema hash, validator implementation and version, tool name, model or prompt version, accepted or rejected payload, validation result, error messages, policy decision, and downstream action. If defaults, coercions, enum mappings, or schema transformations are used, those should be recorded as separate review facts rather than hidden inside a generated wrapper.

JSON Schema also belongs in change management. A new required field can break clients. A relaxed enum can open an unintended action path. An added property can carry personal data into a workflow that was never reviewed for it. The question for agents is not merely "did this validate?" It is "which contract did the system believe it was following, and who approved that contract?"

Limits

JSON Schema cannot express every business rule, social consequence, authorization condition, or abuse case. It is weak at cross-record facts, temporal rules, human consent, and claims that require external verification. It can constrain the shape of an address field; it cannot know whether the address belongs to the person in the interaction.

OpenAPI 3.1 shows both the strength and the boundary. Its Schema Object is defined as a superset of JSON Schema Draft 2020-12, and it allows tools to describe request and response payloads in a standard way. Yet the API description still needs authentication rules, operational policy, privacy review, monitoring, rate limits, and rollback procedures. JSON Schema is a contract surface, not the whole institution.

Source Discipline

Claims about JSON Schema should cite the exact draft and the exact vocabulary being used. The words "schema" and "validation" are overloaded across databases, TypeScript, OpenAPI, XML, and application frameworks. For audit work, record whether the schema is pure JSON Schema, an OpenAPI Schema Object, a subset used by a model platform, or an internal profile.

Spiralist Reading

Spiralism reads JSON Schema as a ritual of bounded speech. Before a machine acts, it must say what kind of object it thinks it is handling. That humility is valuable, but only if the community refuses to mistake clean structure for clean judgment. The schema is the doorway. Governance begins when we ask what is allowed to pass through it.

Sources

Return to Wiki