JSON Schema Guide: Validate APIs and LLM Outputs

What JSON Schema is for

A schema is a contract. It lets a producer and a consumer of JSON agree, in machine-checkable form, on exactly what a valid document looks like — which fields exist, what types they hold, which are required, and what values are allowed. Instead of writing prose documentation that drifts out of date, you write a schema that a validator enforces automatically.

JSON Schema is itself written in JSON, so it travels and versions like any other data. It is defined by a series of drafts; the widely used modern versions are Draft 7 and the 2020-12 draft, the latter of which OpenAPI 3.1 aligns with. You declare which version a schema targets with the $schema keyword.

Essential keywords

A small set of keywords covers the majority of real schemas. type constrains the kind of value, properties describes an object's fields, required lists the mandatory keys, and constraint keywords like enum, minimum, and maxLength tighten individual values.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" }
  },
  "required": ["email"],
  "additionalProperties": false
}

• type — string, number, integer, boolean, array, object, or null.
• properties — the schema for each named field of an object.
• required — an array of keys that must be present.
• enum — the exact set of allowed literal values.
• items — the schema applied to every element of an array.
• minimum / maximum — numeric bounds; minLength / maxLength for strings.
• format — semantic hints such as email, date-time, uri, or uuid.
• additionalProperties — whether keys not listed in properties are allowed.

Modeling objects, arrays, and nesting

Real payloads are rarely flat. Schemas compose: an object property can itself be an object schema, and an array's items can be an object schema, so you can describe arbitrarily deep structures. Setting additionalProperties to false makes a schema strict, rejecting any field you did not explicitly declare — valuable for catching typos and unexpected data from a client.

{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": { "id": { "type": "integer" } },
      "required": ["id"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["user"]
}

Constraints and enums

Beyond types, schemas can constrain the range of acceptable values. Numeric bounds (minimum, maximum, multipleOf), string limits (minLength, maxLength, pattern for regular expressions), and array rules (minItems, uniqueItems) let you encode business rules directly. enum is especially useful for status fields and categories, because it both documents the allowed set and rejects anything outside it — the same guardrail you want when an LLM might hallucinate a plausible-but-wrong value.

{
  "type": "object",
  "properties": {
    "status": { "enum": ["open", "closed", "pending"] },
    "priority": { "type": "integer", "minimum": 1, "maximum": 5 }
  }
}

Schema in the AI era

Schemas have become central to building reliable AI systems. When an LLM emits JSON for a tool call or a structured output, a schema is the guardrail that keeps the model honest. Anthropic's Claude models, for example, accept a JSON Schema as the input definition for a tool, and the model is steered to produce arguments that fit it. Supplying the schema both shapes generation and gives you a hard validation gate afterward, so a hallucinated field or wrong type is caught before your code acts on it.

The schema does double duty: it improves the model's output and it verifies that output. Even with constrained generation, validating against the schema after the fact is the difference between hoping the data is right and knowing it is.

Workflow: sample to schema to validation

You rarely need to write a schema from scratch. Start from a representative 'golden' JSON sample and generate a schema from it, then refine — mark fields required, tighten types, add enums and bounds. Once you have a schema, validate every incoming or outgoing payload against it in your test suite and CI, so a malformed response fails the build rather than a customer's integration. When the API evolves, update the schema first; the validator will then flag any payload that no longer conforms, turning breaking changes into caught errors instead of silent failures.

A JSON Schema Generator can produce the initial draft from a sample, and a JSON Schema Validator checks documents against it — both run client-side on JsonDrift, so schemas and payloads containing real data never leave your browser.