jsonschema-rs 0.24.0

A high-performance JSON Schema validator for Python

jsonschema-rs

A high-performance JSON Schema validator for Python.

import jsonschema_rs

schema = {"maxLength": 5}
instance = "foo"

# One-off validation
try:
    jsonschema_rs.validate(schema, "incorrect")
except jsonschema_rs.ValidationError as exc:
    assert str(exc) == '''"incorrect" is longer than 5 characters

Failed validating "maxLength" in schema

On instance:
    "incorrect"'''

# Build & reuse (faster)
validator = jsonschema_rs.validator_for(schema)

# Iterate over errors
for error in validator.iter_errors(instance):
    print(f"Error: {error}")
    print(f"Location: {error.instance_path}")

# Boolean result
assert validator.is_valid(instance)

⚠️ Upgrading from pre-0.20.0? Check our Migration Guide for key changes.

Highlights

• 📚 Support for popular JSON Schema drafts
• 🌐 Remote reference fetching (network/file)
• 🔧 Custom format validators

Supported drafts

The following drafts are supported:

• 
• 
• 
• 
• 

There are a few known bugs, you can check the current status on the Bowtie Report.

Limitations

• No support for arbitrary precision numbers

Installation

To install jsonschema-rs via pip run the following command:

pip install jsonschema-rs

Usage

If you have a schema as a JSON string, then you could pass it to validator_for to avoid parsing on the Python side:

import jsonschema_rs

validator = jsonschema_rs.validator_for('{"minimum": 42}')
...

You can use draft-specific validators for different JSON Schema versions:

import jsonschema_rs

# Automatic draft detection
validator = jsonschema_rs.validator_for({"minimum": 42})

# Draft-specific validators
validator = jsonschema_rs.Draft7Validator({"minimum": 42})
validator = jsonschema_rs.Draft201909Validator({"minimum": 42})
validator = jsonschema_rs.Draft202012Validator({"minimum": 42})

JSON Schema allows for format validation through the format keyword. While jsonschema-rs provides built-in validators for standard formats, you can also define custom format validators for domain-specific string formats.

To implement a custom format validator:

1. Define a function that takes a str and returns a bool.
2. Pass it with the formats argument.
3. Ensure validate_formats is set appropriately (especially for Draft 2019-09 and 2020-12).

import jsonschema_rs

def is_currency(value):
    # The input value is always a string
    return len(value) == 3 and value.isascii()


validator = jsonschema_rs.validator_for(
    {"type": "string", "format": "currency"}, 
    formats={"currency": is_currency},
    validate_formats=True  # Important for Draft 2019-09 and 2020-12
)
validator.is_valid("USD")  # True
validator.is_valid("invalid")  # False

Additional configuration options are available for fine-tuning the validation process:

• validate_formats: Override the draft-specific default behavior for format validation.
• ignore_unknown_formats: Control whether unrecognized formats should be reported as errors.

Example usage of these options:

import jsonschema_rs

validator = jsonschema_rs.Draft202012Validator(
    {"type": "string", "format": "date"},
    validate_formats=True,
    ignore_unknown_formats=False
)

# This will validate the "date" format
validator.is_valid("2023-05-17")  # True
validator.is_valid("not a date")  # False

# With ignore_unknown_formats=False, using an unknown format will raise an error
invalid_schema = {"type": "string", "format": "unknown"}
jsonschema_rs.Draft202012Validator(invalid_schema, ignore_unknown_formats=False)  # Raises an error

Performance

jsonschema-rs is designed for high performance, outperforming other Python JSON Schema validators in most scenarios:

• Up to 30-390x faster than jsonschema for complex schemas and large instances
• Generally 2-5x faster than fastjsonschema on CPython
• Comparable or slightly slower performance for very small schemas

For detailed benchmarks, see our full performance comparison.

Python support

jsonschema-rs supports CPython 3.8, 3.9, 3.10, 3.11, and 3.12.

Acknowledgements

This library draws API design inspiration from the Python jsonschema package. We're grateful to the Python jsonschema maintainers and contributors for their pioneering work in JSON Schema validation.

Support

If you have questions, need help, or want to suggest improvements, please use GitHub Discussions.

Sponsorship

If you find jsonschema-rs useful, please consider sponsoring its development.

Contributing

We welcome contributions! Here's how you can help:

• Share your use cases
• Implement missing keywords
• Fix failing test cases from the JSON Schema test suite

See CONTRIBUTING.md for more details.

License

Licensed under MIT License.