jsonschema-fast 1.0.0

A fast, Rust-accelerated hybrid implementation of JSON Schema validation for Python

jsonschema

jsonschema is an implementation of the JSON Schema specification for Python.

>>> from jsonschema import validate

>>> # A sample schema, like what we'd get from json.load()
>>> schema = {
...     "type" : "object",
...     "properties" : {
...         "price" : {"type" : "number"},
...         "name" : {"type" : "string"},
...     },
... }

>>> # If no exception is raised by validate(), the instance is valid.
>>> validate(instance={"name" : "Eggs", "price" : 34.99}, schema=schema)

>>> validate(
...     instance={"name" : "Eggs", "price" : "Invalid"}, schema=schema,
... )                                   # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
    ...
ValidationError: 'Invalid' is not of type 'number'

It can also be used from the command line by installing check-jsonschema.

Rust-Backed Hybrid Engine (Optimized Fork)

This fork integrates a high-performance, Rust-backed hybrid validation engine powered by PyO3 and Rayon. It acts as a 100% transparent, drop-in replacement for the original pure-Python validator, delivering native performance with zero API changes.

⚡ Key Highlights & Architecture

• 13x to 20x Faster Validation: Up to 93% reduction in validation latency on standard schemas.
• Parallel Validation (Rayon): Multi-threaded work-stealing validation loops automatically scale validation tasks across CPU cores for massive JSON arrays and nested payloads.
• Zero-Overhead Hybrid Fallback: Automatically detects custom Python format checkers, resolvers, or schema extensions. If any are detected, the validator seamlessly cascades back to the pure-Python implementation, ensuring 100% backward compatibility and zero regressions.
• Zero-Copy Memory Down-casting: Traverses CPython objects (PyAny pointers) directly using highly-optimized PyO3 bindings, bypassing intermediate JSON serialization and minimizing memory allocations.

📊 Performance Benchmarks (via pyperf)

Below are the results of isolated system benchmarks on a large nested database payload (1,000 items):

Validation Engine / Mode	Mean Latency	Speedup vs. Baseline
Pure Python (Original)	10.9 ms ± 0.3 ms	Baseline (1.0x)
Hybrid Rust Engine	806 μs ± 26 μs	13.5x Faster 🚀
Direct Rust C-Extension	808 μs ± 19 μs	13.5x Faster 🚀

How It Works Under the Hood

1. Fast-Path (Rust Native C-Ext): Standard validations run entirely in Rust compiled space. Schema types and instance trees are validated directly against memory layouts.
2. Hybrid Fallback: When custom formats (e.g. customized FormatChecker registries) or customized resolver methods are detected, the validator cascades down to python interpreter execution, ensuring your custom logic works out-of-the-box.
3. Exact Exception Parity: If validation fails, standard jsonschema.exceptions.ValidationError is raised, retaining full attribute compatibility (.path, .schema_path, .message, etc.). Existing exception checks and try-except loops do not need to be updated.

Features

• Full support for Draft 2020-12, Draft 2019-09, Draft 7, Draft 6, Draft 4 and Draft 3
• Lazy validation that can iteratively report all validation errors.
• Programmatic querying of which properties or items failed validation.

Installation

jsonschema is available on PyPI. You can install using pip:

$ pip install jsonschema

Extras

Two extras are available when installing the package, both currently related to format validation:

• format
• format-nongpl

They can be used when installing in order to include additional dependencies, e.g.:

$ pip install jsonschema'[format]'

Be aware that the mere presence of these dependencies – or even the specification of format checks in a schema – do not activate format checks (as per the specification). Please read the format validation documentation for further details.

Running the Test Suite

If you have nox installed (perhaps via pipx install nox or your package manager), running nox in the directory of your source checkout will run jsonschema's test suite on all of the versions of Python jsonschema supports. If you don't have all of the versions that jsonschema is tested under, you'll likely want to run using nox's --no-error-on-missing-interpreters option.

Of course you're also free to just run the tests on a single version with your favorite test runner. The tests live in the jsonschema.tests package.

Benchmarks

jsonschema's benchmarks make use of pyperf. Running them can be done via:

$ nox -s perf

Community

The JSON Schema specification has a Slack, with an invite link on its home page. Many folks knowledgeable on authoring schemas can be found there.

Otherwise, opening a GitHub discussion or asking questions on Stack Overflow are other means of getting help if you're stuck.

About

This fork, featuring the Rust-backed hybrid engine, was contributed by Gaurav Saini.

All credit for the original jsonschema library, its core design, and its long-term maintenance goes to the original author, Julian Berman, and the python-jsonschema contributors. The original project is hosted on GitHub.

If you wish to support the original author, you can sponsor Julian. For companies wishing to support jsonschema's continued growth, the package is supportable via TideLift.