jsonschema — JSON Schema Validation for Python

Introduction

jsonschema is a Python library that validates JSON documents against JSON Schema definitions. It is the most widely used JSON Schema validator in the Python ecosystem, supporting every published draft of the specification from Draft 3 through Draft 2020-12. It is used by Jupyter, pip, and many API frameworks for configuration and request validation.

What jsonschema Does

• Validates Python dicts, lists, and primitives against JSON Schema documents
• Supports all JSON Schema drafts: Draft 3, 4, 6, 7, 2019-09, and 2020-12
• Reports detailed validation errors with JSON Pointer paths to the failing location
• Resolves $ref references including remote schemas via configurable referencing
• Provides format checkers for email, URI, date-time, IPv4, IPv6, and other string formats

Architecture Overview

jsonschema compiles a JSON Schema into a validator object that walks the data structure recursively. Each schema keyword (type, properties, items, allOf, oneOf, etc.) maps to a validation function. The library uses a registry-based reference resolution system (via the referencing library) to handle $ref pointers across schema documents. Errors are collected lazily, allowing both fail-fast and collect-all-errors modes.

Self-Hosting & Configuration

• Install: pip install jsonschema (or pip install jsonschema[format] for format validators)
• Basic usage: jsonschema.validate(instance, schema) raises ValidationError on failure
• Choose a specific draft validator: Draft202012Validator(schema).validate(instance)
• Configure reference resolution by creating a referencing.Registry with pre-loaded schemas
• Use iter_errors() instead of validate() to collect all validation errors without stopping at the first

Key Features

• Full compliance with JSON Schema Test Suite for all supported drafts
• Lazy error iteration with iter_errors() for collecting every validation issue in one pass
• Custom format checkers and vocabulary extensions for application-specific validation rules
• Referencing system that resolves $ref, $id, and $anchor across schema graphs
• Thread-safe validators with no global state, suitable for multi-threaded applications

Comparison with Similar Tools

• Pydantic — validates Python objects using type hints and can generate JSON Schema; jsonschema validates raw JSON data against existing schemas
• Cerberus — Python-native validation with its own schema format; jsonschema uses the standard JSON Schema specification
• fastjsonschema — compiles schemas to Python code for speed; jsonschema prioritizes spec compliance and flexibility over raw performance
• Zod — TypeScript-first schema validation; jsonschema serves the Python ecosystem with the language-agnostic JSON Schema standard
• Ajv — JavaScript JSON Schema validator; jsonschema is the Python equivalent with similar spec coverage

FAQ

Q: Which JSON Schema draft should I use for new projects? A: Draft 2020-12 is the latest and most feature-complete. Use it unless you need compatibility with tooling that only supports older drafts.

Q: How do I validate format strings like email and date-time? A: Install with format extras: pip install jsonschema[format]. Then pass format_checker=jsonschema.FormatChecker() to the validator.

Q: Is jsonschema fast enough for high-throughput validation? A: For most applications, yes. If validation is a bottleneck, consider fastjsonschema which compiles schemas to optimized Python code.

Q: Can I use jsonschema with YAML or TOML data? A: Yes. Parse the YAML or TOML into a Python dict first, then validate the dict against a JSON Schema as usual.

Sources

• https://github.com/python-jsonschema/jsonschema
• https://python-jsonschema.readthedocs.io/