JSON Schema validation guide

July 28, 2026 · 15 min read

Syntax validation tells you whether text is JSON. JSON Schema tells you whether the parsed value is the JSON you meant: required fields, string formats, numeric ranges, and forbidden extra properties. It is the contract layer between producers and consumers.

Teams adopt Schema to stop debating examples in Slack threads. One schema file powers unit tests, API documentation, and optional request validation at the edge - if you keep versions disciplined and treat schema changes as breaking API changes when appropriate.

What JSON Schema adds

A schema is a JSON document describing constraints on another JSON document. Validators walk the instance and collect errors with JSON Pointer paths, which map cleanly to form fields or API error responses.

Schema does not replace business logic: it cannot express every rule (for example, “end date after start date unless status is draft”) without extensions or custom keywords. Use Schema for structural contracts and code for semantic rules.

Essential keywords

type restricts values to object, array, string, number, integer, boolean, or null. required lists mandatory object keys. properties and additionalProperties control which keys are allowed and their nested schemas.

String formats like email, uuid, and date-time catch common mistakes early. For enums, enum is explicit; for open-ended tags, use arrays with items and uniqueness constraints.

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

Composition and reuse

allOf, anyOf, and oneOf combine subschemas - useful for discriminated unions and extending base types. $ref points to reusable definitions, often hosted at a stable URL or bundled in OpenAPI components.

Avoid deep allOf towers that confuse error messages. Prefer a single object schema with clear property docs when possible; reviewers thank you during incident response.

Draft versions in 2026

Draft 2020-12 is widely supported by modern validators (Ajv v8+, etc.). Older draft-04 schemas still appear in legacy OpenAPI 2 documents. Pin the $schema URL in every file and upgrade deliberately - keyword behavior shifted between drafts.

OpenAPI 3.1 aligns with JSON Schema 2020-12 for schema objects. If you maintain both hand-written Schema and OpenAPI, generate one from the other to avoid drift.

Validation in CI and gateways

Run schema validation on fixtures and golden responses in CI. Fail builds when examples do not validate. At runtime, validate inbound requests in the service you control - not only at the gateway - so error messages include domain context.

Return 400 with a machine-readable error array: pointer, keyword, and message. Clients fix integrations faster than with a generic “validation failed” string.

Browse all tools