rsonschema

Prologue

In the world of data validation, ensuring your data conforms to a specified structure is crucial.

At hiop, we sought a language-agnostic format to define how data should be structured, and JSON Schema stood out as the perfect solution.

This inspired the creation of rsonschema, a fast, simple, and user-friendly JSON Schema validator for Rust

Why Rust?

Rust is celebrated for its performance and safety capabilities. These attributes make it an excellent choice for building a fast, user-friendly, secure, and efficient validator

Alternatives

• jsonschema: was previously our choice, offering robust validation but suffering from complex error handling. For example:

  1. jsonschema::error::ValidationError borrows the instance attribute, adding complexity.
  2. it lacks of useful error messages for end users, especially when validating schemas with Schema Composition failures.

• valico: like jsonschema, it has complex error handling. Moreover it is not actively maintained.

• schemars: a de facto standard which inspired us with over 19 million downloads. However, it lacks of validation APIs

Usage

Installation

Add rsonschema to your Cargo.toml:

cargo add rsonschema

Example

Here's how you can start using rsonschema in your Rust project:

let schema = serde_json::json!({
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "minLength": 3
});

let instance = serde_json::json!("foo");
let report = rsonschema::validate(
    &instance,
    schema.clone(),
);
assert!(report.is_valid());

let instance = serde_json::json!("a");
let report = rsonschema::validate(
    &instance,
    schema,
);
assert_eq!(
    report,
    rsonschema::ValidationReport {
        errors: Some(
            rsonschema::error::ValidationErrors::from([
                rsonschema::error::ValidationError {
                    instance: serde_json::json!("a"),
                    type_: rsonschema::error::type_::ValidationErrorType::MinLength {
                        limit: 3.into(),
                    },
                    ..Default::default()
                }
            ])
        ),
        ..Default::default()
    }
);

Performance

rsonschema is benchmarked against jsonschema across representative scenarios. Selected results on Apple M3 (lower is better):

Cold means the competitor also compiles the schema on every call, matching rsonschema's usage model. See BENCHMARKS.md for the full methodology and results, including Python bindings.

Reliability

Currently, rsonschema supports only the latest (2020-12) JSON Schema specification.

All official tests, located in the tests folder, are passing, except for features that are not yet supported

Compatibility

Currently, rsonschema intentionally does not support dynamic keywords such as $dynamicAnchor and $dynamicRef, as these introduce complexity

Community

Contribution

We firmly believe that collaboration is the key to innovation!

If you find a bug or have a feature request, please open an issue. If you want to go further and tackle it, open a pull request on our GitHub repository.

License

rsonschema is licensed under the Apache-2.0 License. See the LICENSE file for more details.