JSON Schema Validation — Core Concepts

JSON Schema is a declarative specification for describing and validating JSON data. It is language-agnostic — the schema is a JSON (or YAML) document that any language can read and enforce. In Python, the jsonschema library is the reference implementation, providing standards-compliant validation with detailed error reporting.

What JSON Schema defines

A JSON Schema document describes:

Type constraints: The data type at any level — string, number, integer, boolean, array, object, or null.

Value constraints: Minimum/maximum for numbers, minLength/maxLength for strings, pattern (regex) for strings, enum for allowed values.

Structure constraints: Required properties, additional properties allowed or forbidden, array item schemas, and minimum/maximum number of items.

Composition: allOf (must match all schemas), anyOf (must match at least one), oneOf (must match exactly one), not (must not match). These enable expressive type unions and conditional validation.

References: The $ref keyword lets schemas reference reusable definitions within the same document or from external URLs, enabling modular schema design.

How Python’s jsonschema works

The jsonschema library validates Python dicts/lists against JSON Schema documents. The core flow is straightforward: load your schema (a Python dict), load your data (a Python dict), and call validate(). If validation passes, nothing happens. If it fails, a ValidationError is raised with a detailed message and a path to the offending element.

For bulk validation, iter_errors() returns all errors instead of raising on the first one. This is essential for API responses where you want to report every problem at once.

Schema versions (drafts)

JSON Schema has evolved through several drafts: Draft 4, Draft 6, Draft 7, Draft 2019-09, and Draft 2020-12. Each adds features. The jsonschema library supports all drafts and lets you specify which one to use. Draft 2020-12 is the latest, with features like prefixItems for tuple validation and $dynamicRef for extensible schemas.

In practice, Draft 7 is the most widely supported across tooling. Use it unless you specifically need features from newer drafts.

Real-world usage

API contract validation: OpenAPI (Swagger) specifications use JSON Schema to define request and response bodies. Validating incoming API requests against the schema catches malformed data before it reaches business logic.

Configuration validation: Tools like VS Code use JSON Schema to provide autocompletion and error checking for config files (package.json, tsconfig.json). Python applications can validate their own config files the same way.

Data pipeline contracts: When teams share data through files or message queues, JSON Schema serves as the language-agnostic contract. The producing team publishes the schema, and consumers validate against it regardless of their programming language.

Generating schemas

You can write JSON Schema by hand, but for Python objects, generation is often easier. Pydantic models export JSON Schema via model_json_schema(). dataclasses can be converted using third-party tools. This lets you define your data in Python and automatically produce schemas that other languages and tools can consume.

Common misconception

Developers sometimes assume JSON Schema validation replaces application-level validation. JSON Schema handles structural validation (types, required fields, patterns) effectively but cannot handle business logic validation (does this user ID exist in the database? Is this order total consistent with the line items?). Use JSON Schema for structural contracts and application validators for business rules.

One thing to remember: JSON Schema provides a universal, language-agnostic way to define and enforce data validation rules — making it the common language for data contracts between systems written in different technologies.