jsonschema

jsonschema

A high-performance JSON Schema validator for Rust.

use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let schema = json!({"maxLength": 5});
    let instance = json!("foo");

    // One-off validation
    assert!(jsonschema::is_valid(&schema, &instance));
    assert!(jsonschema::validate(&schema, &instance).is_ok());

    // Build & reuse (faster)
    let validator = jsonschema::validator_for(&schema)?;

    // Fail on first error
    assert!(validator.validate(&instance).is_ok());

    // Iterate over errors
    for error in validator.iter_errors(&instance) {
        eprintln!("Error: {error}");
        eprintln!("Location: {}", error.instance_path());
    }

    // Boolean result
    assert!(validator.is_valid(&instance));

    // Structured output (JSON Schema Output v1)
    let evaluation = validator.evaluate(&instance);
    for annotation in evaluation.iter_annotations() {
        eprintln!(
            "Annotation at {}: {:?}",
            annotation.schema_location,
            annotation.annotations.value()
        );
    }

    // Generated validators are significantly faster than runtime ones,
    // so prefer them when the schema is known at build time.
    // Requires the `macros` feature.
    // Inline schema, or `path = "schema.json"` to load from a file
    #[jsonschema::validator(schema = r#"{"maxLength": 5}"#)]
    struct Short;

    assert!(Short::is_valid(&instance));
    Short::validate(&instance)?;

    Ok(())
}

You also can use it from the command line via the jsonschema-cli crate.

$ jsonschema-cli validate schema.json -i instance.json

See more usage examples in the documentation.

⚠️ Upgrading from older versions? Check our Migration Guide for key changes.

Playground

If you’d like to try jsonschema, you can check the WebAssembly-powered playground to see the results instantly.

Highlights

• 📚 Full support for popular JSON Schema drafts
• 🔧 Custom keywords and format validators
• ⚡ Compile-time validators for Rust, Python and Ruby extension modules
• 🌐 Blocking & non-blocking remote reference fetching (network/file)
• 📦 Schema bundling into Compound Schema Documents, and $ref dereferencing
• 🎨 Structured Output v1 reports (flag/list/hierarchical)
• ✨ Meta-schema validation for schema documents, including custom metaschemas
• 🧮 Experimental schema canonicalization
• 🧩 Validation of custom in-memory JSON representations
• 🔗 Bindings for Python and Ruby
• 🚀 WebAssembly support
• 💻 Command Line Interface

Supported drafts

The following drafts are supported:

• 
• 
• 
• 
• 

You can check the current status on the Bowtie Report.

Notable Users

• Tauri: Config validation
• Apollo Router: Config file validation
• qsv: CSV record validation with custom keyword & format validator

Performance

jsonschema outperforms other Rust JSON Schema validators in most scenarios. The numbers below are for the runtime validator, which compiles a schema into a reusable Validator:

• 88-1,851x faster than valico and 11-117x faster than jsonschema_valid for complex schemas (>1,000,000x on FHIR)
• Generally 4.4-113x faster than boon, >340x on FHIR, and >9000x for recursive schemas

When the schema is known at build time, the #[jsonschema::validator] macro (macros feature) generates a specialized validator at compile time. This avoids schema compilation at runtime and validates roughly 1.7-6.5x faster than the runtime validator across our benchmark schemas.

For detailed benchmarks, see our full performance comparison.

Cargo features

Feature	Default	Enables
resolve-http	✅	Fetching remote references over HTTP
resolve-file	✅	Reading references from the filesystem
tls-aws-lc-rs	✅	TLS provider for resolve-http
idna	✅	The idn-hostname and idn-email formats
tls-ring		ring as the TLS provider instead of aws-lc-rs
resolve-async		Non-blocking reference resolution
arbitrary-precision		Arbitrarily large integers and exact decimal values
macros		The #[jsonschema::validator] compile-time validator
pyo3		Validating Python objects in place, and backend = Pyo3 for the macro
magnus		Validating Ruby objects in place, and backend = Magnus for the macro
jsonb		Validating Postgres jsonb values in place

Turning off idna drops the IDNA and ICU dependencies; idn-hostname and idn-email are then treated as unknown formats.

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.85.0 or later.

TLS Configuration

By default, jsonschema uses aws-lc-rs as the TLS cryptography provider, which is the default one in reqwest.

Using Ring Instead

You can opt into using ring as the TLS provider:

[dependencies]
jsonschema = {
    version = "0.60",
    default-features = false,
    features = ["resolve-http", "resolve-file", "tls-ring"]
}

NOTE: If both tls-aws-lc-rs and tls-ring features are enabled, aws-lc-rs takes precedence.

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 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.