JSON Schema Validation: The Complete Guide

What Is JSON Schema?

JSON Schema is a vocabulary for describing and validating the structure of JSON data. It defines what fields a JSON object should have, what types those fields should be, which ones are required, and what constraints apply — minimum values, string patterns, enum options, and more.

Think of JSON Schema as a contract for your data. APIs use it to validate request bodies before processing them. Configuration files use it for editor autocompletion and error highlighting. Documentation generators use it to produce accurate API references. The schema itself is just JSON, making it easy to read, write, and share.

Basic Type Definitions

JSON Schema supports seven primitive types: string, number, integer, boolean, null, object, and array.

Numbers support minimum, maximum, exclusiveMinimum, exclusiveMaximum, and multipleOf constraints. Strings support minLength, maxLength, pattern (regex), and format (semantic validation like email, date, URI).

Objects & Properties

Object schemas define the expected properties, their types, and which ones are required:

required lists properties that must be present. additionalProperties: false rejects any fields not listed in properties — useful for strict API validation. Set it to a schema to allow extra properties of a specific type.

Array Validation

Array schemas control item types, length, and uniqueness:

For tuple validation (arrays with a fixed sequence of differently-typed items), use prefixItems:

This validates that the first item is a number, the second a string, and the third a boolean.

String Formats & Patterns

The format keyword provides semantic validation for common string types:

email, uri, date-time, date, time, ipv4, ipv6, uuid, hostname, json-pointer, and regex.

For custom patterns, use the pattern keyword with a regular expression:

This validates strings like "US-1234" or "GB-5678". Combine format and pattern for layered validation — format catches the general shape, pattern enforces specific structure.

Composition Keywords: allOf, anyOf, oneOf

Composition keywords combine multiple schemas:

`allOf` — the data must match all listed schemas. Used for extending a base schema with additional constraints.

`anyOf` — the data must match at least one schema. Used for fields that accept multiple types.

`oneOf` — the data must match exactly one schema (not zero, not more than one). Used for discriminated unions.

This validates a notification channel that's either an email (with address) or an SMS (with phone), but not both.

Conditional Schemas

The if/then/else keywords enable conditional validation:

If payment_method is "credit_card", then card_number and expiry are required. Otherwise, account_number and routing_number are required. This is cleaner than duplicating the entire schema with oneOf.

Validation Libraries

Every major language has JSON Schema validation libraries:

JavaScript/TypeScript: AJV (the fastest and most popular), Zod (TypeScript-first schema library that can export JSON Schema).

Python: jsonschema (reference implementation), fastjsonschema (compiled validation for performance).

Go: gojsonschema. Java: everit-org/json-schema. PHP: justinrainbow/json-schema.

Most API frameworks integrate JSON Schema validation directly. Express.js uses AJV through middleware. FastAPI uses Pydantic models that generate JSON Schema automatically. Spring Boot supports JSON Schema validation through annotations.

JSON Schema for API Documentation

OpenAPI (Swagger) specifications use JSON Schema to describe request and response bodies. Your schema definitions serve double duty: they validate incoming data and generate interactive API documentation.

Tools like Swagger UI, Redoc, and Stoplight render JSON Schema into browsable documentation with type information, constraints, and example values. When your schema changes, the documentation updates automatically.

The JSON Schema Generator tool can create schemas from example JSON data — paste an API response and get a draft schema you can refine. This is much faster than writing schemas by hand for complex nested objects.