JSON Schema
Community-maintained vocabulary for validating JSON
JSON Schema is a vocabulary, expressed itself as JSON, for describing the structure, types, and constraints that a JSON document must satisfy. It lets developers declare rules such as required fields, value types, numeric ranges, and…
Definition
JSON Schema is a vocabulary, expressed itself as JSON, for describing the structure, types, and constraints that a JSON document must satisfy. It lets developers declare rules such as required fields, value types, numeric ranges, and string patterns, and then validate documents against those rules automatically. It is widely used to enforce API contracts, validate configuration files, and generate documentation and client code from a single source of truth.
Overview
JSON documents are inherently schema-less: any valid JSON is accepted regardless of whether it matches what an application actually expects, which leaves gaps for malformed data to slip into systems undetected until it causes a runtime error somewhere downstream. JSON Schema was created to close that gap by giving developers a way to declare, in a machine-readable form, exactly what shape a JSON document must have. Mechanically, a JSON Schema document is itself written in JSON, using keywords such as 'type', 'properties', 'required', 'minimum', and 'pattern' to constrain an instance document. A validator library reads both the schema and the candidate document, checks the candidate against every constraint in the schema, and reports either success or a list of specific validation errors describing which fields failed and why. Schemas can also reference other schemas, allowing complex data structures to be composed from smaller, reusable definitions. JSON Schema differs from a statically typed programming language's type system in that it validates data at runtime against an external, portable specification rather than at compile time within a single codebase, which makes it useful across language boundaries where a producer and consumer are written in different languages. It also differs from simpler validation approaches, such as ad hoc if-statements in application code, by making the rules declarative, shareable, and independently testable rather than buried inside business logic. In practice, JSON Schema is used to validate incoming API request bodies before they reach application logic, to check configuration files for correctness before a service starts, and as the foundation for tooling that auto-generates API documentation, form UIs, or client library code directly from a schema definition. Many API specification formats embed JSON Schema as their mechanism for describing request and response payloads. Its main limitations are that schemas can become verbose and difficult to read for deeply nested or highly conditional structures, and that different validator implementations have historically supported different draft versions of the specification with subtle behavioral differences. Teams adopting it need to pin a specific schema draft version and validator library to avoid inconsistent validation results, and for very simple validation needs, a lighter-weight approach embedded directly in application code may be less overhead than maintaining separate schema files. Choosing JSON Schema over ad hoc checks pays off most clearly once multiple independent services or teams need to agree on the same contract, since a shared schema file becomes a single, testable source of truth that every consumer can validate against rather than each team implementing its own interpretation of the expected shape.
Specification
- Declarative, JSON-based vocabulary for describing document structure
- Validates types, required fields, ranges, and string patterns
- Schemas can reference and compose other schemas
- Produces detailed, field-level validation error messages
- Language-agnostic, usable across producer and consumer boundaries
- Foundation for auto-generating docs, forms, and client code
Use Cases
Alternatives
Frequently Asked Questions
From the Blog
Working With JSON in Python
Python's json module converts between JSON text and Python objects with four core functions. Learn to parse, create, read, and write JSON with practical examples.
Read More ProgrammingJavaScript Objects and JSON Explained
JavaScript objects store data as key-value pairs, and JSON is a text format for exchanging that data. Learn how they relate, differ, and convert between each other.
Read More ProgrammingPython File I/O: Reading and Writing Files
Almost every real Python program reads or writes files — logs, configs, CSVs, JSON, reports. This guide covers text files, CSV, JSON, binary files, and the modern pathlib approach, with best practices for safe file handling.
Read More ProgrammingBuilding REST APIs With Node.js and Express
Build a REST API with Node.js and Express by defining routes, handling JSON, and returning proper status codes. Here is how to structure one from scratch.
Read More