JSON Schema is the standard way to describe, validate, and document JSON data structures. Whether you are validating API requests, defining config files, or generating developer documentation, a good schema helps prevent invalid data from spreading through your system. This guide explains the core JSON Schema keywords, the Draft 2020-12 model, common validation patterns, and practical examples you can adapt to real projects.
What is JSON Schema?
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. Think of it as a contract for your JSON data —defining what fields are required, what types are allowed, and what constraints apply.
Basic JSON Schema Example
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "User's full name"
},
"age": {
"type": "integer",
"minimum": 0,
"maximum": 150
},
"email": {
"type": "string",
"format": "email"
}
},
"required": ["name", "email"]
}Draft 2020-12 New Features
- $merge and $apply keywords for advanced composition
- unevaluatedProperties for fine-grained control
- if/then/else now supports the dependentSchemas keyword
- Improved support for recursive schemas
Best Practices
- Always specify the draft version with
$schema - Use
descriptionfields to document intent - Validate early in your request pipeline
- Generate schemas from your data models programmatically
Whether you're building internal microservices or public APIs, JSON Schema is the foundation of robust API documentation and validation in the developer ecosystem.
Frequently Asked Questions
What is JSON Schema used for?
JSON Schema is used to define the structure, rules, and constraints of JSON data so it can be validated consistently across tools and applications.
Which JSON Schema draft should I use?
Draft 2020-12 is a strong default for new projects unless your existing tooling requires an older draft for compatibility.
What is the difference between type, properties, and required?
type defines the data kind, properties defines allowed object fields, and required lists which fields must be present.
JSON Schema Fundamentals: Types, Constraints, and Validation
JSON Schema provides a powerful vocabulary for annotating and validating JSON documents. At its core, a JSON Schema is itself a JSON document that describes the expected structure, data types, and constraints of another JSON document. The schema defines what constitutes a valid instance, enabling automated validation in development, testing, and production environments.
Type keywords form the foundation of JSON Schema validation. The "type" keyword can be a single string ("string", "number", "integer", "boolean", "array", "object", "null") or an array of types for union types. Type-specific keywords provide fine-grained control: strings support "minLength", "maxLength", "pattern" (regex validation), and "format" (email, uri, date-time, etc.); numbers support "minimum", "maximum", "exclusiveMinimum", "multipleOf"; arrays support "minItems", "maxItems", "uniqueItems", and "items" for tuple validation; objects support "required", "minProperties", "maxProperties", "properties", "patternProperties", and "additionalProperties".
Combining schemas using boolean logic keywords enables complex validation scenarios. "allOf" requires that an instance validates against all specified schemas (logical AND). "anyOf" requires validation against at least one schema (logical OR). "oneOf" requires validation against exactly one schema (logical XOR). "not" requires that the instance does not validate against the specified schema. These combinators allow building sophisticated validation logic while keeping individual schemas focused and reusable.
Draft 2020-12: The Latest JSON Schema Specification
The JSON Schema Draft 2020-12 release represents a significant milestone in the specification's evolution. Key improvements include: Dynamic references ($dynamicRef and $dynamicAnchor) that allow runtime resolution of schema references based on the validation context, enabling more flexible and reusable schema compositions. Unevaluated properties (unevaluatedProperties and unevaluatedItems) that provide more precise control over schema extension points, allowing base schemas to define contracts that extensions must respect without being overly restrictive.
Vocabulary system allows schema processors to declare which sets of keywords they support, enabling progressive enhancement and better interoperability between different implementations. A validator can declare support for the "Core" vocabulary and optionally support "Format" or "Content" vocabularies, giving schema authors clear expectations about validation behavior. Annotations have been formalized as a first-class concept, enabling schemas to produce metadata (titles, descriptions, defaults, examples) during validation without affecting the validation outcome.
Migration from Draft-07 to Draft 2020-12 requires careful attention to breaking changes: the "definitions" keyword has been replaced by "$defs"; "additionalProperties" behavior has been refined to exclude properties matched by "patternProperties"; boolean schemas (true/false as schema values) are now explicitly supported. Most validators provide compatibility modes that ease the transition.
Practical Applications of JSON Schema
JSON Schema has evolved beyond simple validation into a fundamental component of modern API development workflows. API Documentation: OpenAPI 3.1 fully embraces JSON Schema for describing request and response bodies, making it the standard way to document API contracts. Tools like Swagger UI and Redoc automatically generate interactive documentation from JSON Schema definitions, reducing documentation maintenance burden.
Code Generation: JSON Schema definitions can automatically generate TypeScript interfaces, Java POJOs, Python dataclasses, and Go structs. This ensures type safety across your stack and eliminates the tedious practice of manually writing data model code that mirrors your API contract. Popular tools like quicktype, json-schema-to-typescript, and OpenAPI Generator support this workflow.
Form Generation: React JSON Schema Form (RJSF) and similar libraries dynamically generate web forms from JSON Schema definitions. When your schema defines the data model, the form library handles layout, validation, and error display automatically. This is particularly powerful for admin panels, configuration UIs, and internal tools where form requirements change frequently.
Data Validation Pipelines: In event-driven architectures, JSON Schema validates messages flowing through message brokers (Kafka, RabbitMQ, SQS). A schema registry ensures that producers and consumers agree on message formats. Validation at the broker level prevents malformed messages from entering the system, providing a strong defense against cascading failures caused by unexpected data formats.