jsonschema

jsonschema is the de facto standard library for validating JSON data against JSON Schema documents in Python. It ships full support for Drafts 2020-12, 2019-09, 7, 6, 4, and 3, exposing both a one-line validate() helper and per-draft validator classes for fine-grained control.

Beyond simple pass/fail checks, it offers lazy validation that iteratively reports every error in an instance, programmatic querying of which properties failed, custom type and format checkers, and pluggable reference resolution. It underpins a huge swath of the Python ecosystem, from API frameworks to configuration tooling.

What You Get

• A single validate() entry point plus dedicated validator classes for JSON Schema Drafts 3, 4, 6, 7, 2019-09, and 2020-12
• Lazy validation via iter_errors() that reports every validation failure instead of stopping at the first
• Rich, introspectable ValidationError and ErrorTree objects that pinpoint which schema keyword and instance path failed
• Optional format validation (email, uri, date-time, and more) through installable format and format-nongpl extras
• Extensibility hooks for custom validators, type checkers, and reference resolution built on the referencing library

Common Use Cases

• Validating incoming API request or response bodies against a schema contract
• Checking configuration files and structured data before an application consumes them
• Enforcing data quality in ETL and ingestion pipelines
• Building higher-level validation frameworks and code generators on top of a spec-compliant core

Under The Hood

Architecture - Validator classes are not hand-written per draft but generated at import time by validators.create(), which binds a version-specific meta-schema, a type checker, a format checker, and a mapping of schema keywords (in _keywords.py and _legacy_keywords.py) to validation functions; each keyword function yields ValidationError objects, so validation is a lazy generator pipeline that iter_errors() drains and validate() consumes only far enough to raise the first error. $ref and $dynamicRef resolution is delegated to the external referencing library and jsonschema-specifications, keeping schema loading and the validation core cleanly separated.

Tech Stack - Pure Python targeting 3.10+, built with hatchling and hatch-vcs for versioning. Runtime dependencies are deliberately lean: attrs for the frozen validator classes, referencing and jsonschema-specifications for schema/registry handling, and rpds-py for persistent immutable data structures. Optional format and format-nongpl extras pull in focused validators (fqdn, idna, rfc3339-validator, uri_template, webcolors) only when semantic format checking is needed. Testing and benchmarking run through nox and pyperf.

Code Quality - The test suite is larger than the source (roughly 5,900 lines of tests against 4,600 of implementation) and is anchored by test_jsonschema_test_suite.py, which runs the official cross-language JSON Schema conformance suite. The codebase uses modern typing throughout, exposes runtime_checkable Protocol definitions in protocols.py, and handles backward compatibility gracefully via module-level getattr hooks that emit DeprecationWarnings rather than breaking imports.

API Design - The public surface is deliberately layered for progressive disclosure: validate(instance, schema) is a one-liner for the common case, while Draft202012Validator and its siblings expose is_valid(), iter_errors(), and check_schema() for callers who need all errors or a specific draft. Errors are first-class objects with json_path, absolute_path, and an ErrorTree view, making programmatic failure handling ergonomic. Extensive Read the Docs documentation and inline examples keep the learning curve gentle for a spec as intricate as JSON Schema.