Version 1.0 API

[Stranger6667]

Here is the prototype for the 1.0 API. Please, share your concerns and ideas!

Context

There are two versions of roughly the same API for JSON Schema validation - async & blocking. The async one is default and is helpful for cases when the schema contains external references, so resolving does not block.

The blocking version is available in the blocking module and provides functions & methods with the same signatures except for asyncness.

The validation process contains two phases - building the validator and validation. jsonschema provides shortcuts that combine them both. They also could be used separately for performance reasons.

As reference resolving happens only during the first phase, asyncness is only present in the APIs that involve this phase.

Schema & input are generic and are not restricted to serde_json::Value but to anything that implements the Json trait.

One-off API

A set of functions useful for running validation once with the default configuration:

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let schema = json!({"type": "integer"});
    let instance = json!("a");

    // Boolean
    assert!(!jsonschema::is_valid(&instance, &schema).await);

    // Result<(), ValidationError>
    jsonschema::validate(&instance, &schema).await?;

    // Iterator
    for error in jsonschema::iter_errors(&instance, &schema).await {
        println!("{}", error);
    }

    // Serializable output
    let verbose = jsonschema::evaluate(&instance, &schema).await.verbose();
    let serialized = serde_json::to_string(&verbose)?;

    Ok(())
}

Details:

// Boolean result (panics on invalid schema)
async fn is_valid<J: Json>(schema: &J, instance: &J) -> bool
// Boolean result (errors on invalid schema)
async fn try_is_valid<J: Json>(schema: &J, instance: &J) -> Result<bool, BuildError>

// The first error (panics on invalid schema)
async fn validate<J: Json>(schema: &J, instance: &J) -> Result<(), ValidationError>
// The first error (errors on invalid schema)
async fn try_validate<J: Json>(schema: &J, instance: &J) -> Result<Result<(), ValidationError>, BuildError>

// Iterate over all errors (panics on invalid schema)
async fn iter_errors<'s, 'i, J: Json>(
    schema: &'s J,
    instance: &'i J,
) -> ValidationErrorIter<'static, 'i, J>
// Iterate over all errors (errors on invalid schema)
async fn try_iter_errors<'s, 'i, J: Json>(
    schema: &'s J,
    instance: &'i J,
) -> Result<ValidationErrorIter<'static, 'i, J>, BuildError>

// Structured output per the JSON Schema output formats (panics on invalid schema)
async fn evaluate<'i, J: Json>(
    instance: &'i J,
    schema: &J,
) -> Output<'static, 'i, J>
// Structured output per the JSON Schema output formats (errors on invalid schema)
async fn try_evaluate<'i, J: Json>(
    instance: &J,
    schema: &J,
) -> Result<Output<'static, 'i, J>, BuildError>

Reusing validators

use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let schema = json!({"type": "integer"});
    let instances = vec![json!(1), json!(2), json!("a"), json!(3)];

    // Build once, reuse many times
    let validator = jsonschema::validator_for(&schema).await?;
    
    for instance in instances {
        // Boolean
        assert!(validator.is_valid(&instance));

        // Result<(), ValidationError>
        validator.validate(&instance)?;

        // Iterator
        for error in validator.iter_errors(&instance) {
            println!("{}", error);
        }

        // Serializable output
        let verbose = validator.evaluate(&instance).verbose();
        let serialized = serde_json::to_string(&verbose)?;
    }
    Ok(())
}

Details:

// Construct a validator with automatic JSON Schema draft detection
async fn validator_for<J: Json>(schema: &J) -> Result<Validator, BuildError>
// Equivalents to the one-off API
impl Validator {
    fn is_valid<J: Json>(&self, instance: &J) -> bool;
    fn validate<J: Json>(&self, instance: &J) -> Result<(), ValidationError>;
    fn iter_errors<'v, 'i, J: Json>(
        &'v self,
        instance: &'i J,
    ) -> ValidationErrorIter<'v, 'i, J>;
    fn evaluate<'v, 'i, J: Json>(
        &'v self,
        instance: &'i J,
    ) -> Output<'v, 'i, J>;
}

Output formatting

// Returned by `.flag()`
pub struct Flag {
    pub valid: bool,
}

// Returned by `.list()`
pub struct List<J: Json> {
    pub valid: bool,
    pub nested: Vec<OutputUnit<J>>,
}

// Returned by `.hierarchical()`
pub type Hierarchical<J> = OutputUnit<J>;

// NOTE: Fields will be camelCase in the output
pub struct OutputUnit<J: Json> {
    pub valid: bool,
    pub evaluation_path: String,
    pub schema_location: String,
    pub instance_location: String,
    pub nested: Option<Vec<OutputUnit<J>>>,
    pub annotations: Option<BTreeMap<String, J>>,
    pub dropped_annotations: Option<BTreeMap<String, J>>,
    pub errors: Option<BTreeMap<String, String>>,
}

Configuration

Adjusting how validation behaves:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let validator = jsonschema::ValidatorBuilder::default()
        // Set explicit draft
        .draft(jsonschema::Draft::Draft07)
        // Ignore unknown "format" values
        .ignore_unknown_formats(false)
        .build(&schema)
        .await?;

    Ok(())
}

Custom reference resolving

Changing how resolving external references works (i.e. forbidding any external references)

use jsonschema::{Json, BuildResult};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ... omitted for brevity
    struct Resolver;

    impl<J: Json> jsonschema::ReferenceResolver<J> for Resolver {
        async fn resolve_external(&self, url: &str) -> BuildResult<J> {
            Ok(J::from_str("{}")?)
        }
    };


    let validator = jsonschema::ValidatorBuilder::default()
        .resolver(Resolver)
        .build(&schema)
        .await?;

    Ok(())
}

Custom formats

Validate strings with a non-standard format checker:

use jsonschema::{Json, BuildResult, BoxedFormat};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ... omitted for brevity

    struct FixedSize {
        size: usize,
    }

    impl jsonschema::Format for FixedSize {
        fn is_valid(&self, value: &str) -> bool {
            value.len() == self.size
        }
    }

    fn fixed_size_factory<J: Json>(
        schema: &J,
        path: &JsonPointerNode,
        parent: &J,
    ) -> BuildResult<BoxedFormat> {
        Ok(Box::new(FixedSize { size: 43 }))
    }

    let validator = jsonschema::ValidatorBuilder::default()
        .format(
            "fixed-size-1",
            |schema, path, parent| -> BuildResult<BoxedFormat> {
                Ok(Box::new(FixedSize { size: 5 }))
            }
        )
        // Alternative approach with a factory function
        .format("fixed-size-2", fixed_size_factory)
        .build(&schema)
        .await?;

    Ok(())
}

Custom keywords

Custom validation implementation - requires validate and optionally is_valid:

use jsonschema::{Json, BuildResult, ValidationResult, ValidationError, BoxedKeyword};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ... omitted for brevity

    #[derive(Debug)]
    struct IsAscii {
        max_size: usize
    }

    impl<J: Json> jsonschema::Keyword<J> for IsAscii {

        fn validate(&self, instance: &J, instance_path: &JsonPointerNode) -> ValidationResult {
            if let Some(string) = instance.as_string().map(AsRef::as_ref) {
                if string.is_ascii() && string.len() > self.max_size {
                    // Or some shortcut like `return Err(self.error_builder())` or 
                    // `return self.error_with_message("bla bla")`
                    return Err(
                        ValidationError::builder()
                            .message("Ascii string is too long")
                            .instance_path(instance_path)
                            // Optional - if you choose to store it during initialization
                            // .schema_path(self.schema_path)
                            .build()
                    );
                }
            }
            Ok(())
        }
        
        // A faster version that MAY take some shortcuts
        fn is_valid(&self, instance: &J) -> bool {
            if let Some(string) = instance.as_string().map(AsRef::as_ref) {
                if string.is_ascii() {
                    return string.len() <= self.max_size;
                }
            }
            true
        }
    }

    fn is_ascii_factory<J: Json>(
        // That is likely to be something J::Object instead
        parent: &J,
        value: &J,
        path: &JsonPointerNode,
    ) -> BuildResult<BoxedKeyword<J>> {
        Ok(Box::new(IsAscii { max_size: 42 }))
    }

    let validator = jsonschema::ValidatorBuilder::default()
        .keyword(
            "ascii",
            |parent, value, path| -> BuildResult<BoxedKeyword<_>> {
                Ok(Box::new(IsAscii { max_size: 42 }))
            }
        )
        // Alternative approach with a factory function
        .keyword("also-ascii", is_ascii_factory)
        .build(&schema)
        .await?;

    Ok(())
}

Errors

struct BuildError {
    /// Errors that may happen during the build phase
};
struct ValidationError {
    /// Regular validation errors
}

Depending on the final size, they could be either enums or structs (with boxed inner enum)

[gregsdennis]

As reference resolving happens only during the first phase...

How do you handle cases where references can only be resolved at validation time, i.e. when there is an instance? This is how $dynamicRef often works.

For example, from the test suite:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://test.json-schema.org/dynamic-ref-with-multiple-paths/main",
  "if": {
    "properties": {
      "kindOfList": { "const": "numbers" }
    },
    "required": ["kindOfList"]
  },
  "then": { "$ref": "numberList" },
  "else": { "$ref": "stringList" },

  "$defs": {
    "genericList": {
      "$id": "genericList",
      "properties": {
        "list": {
          "items": { "$dynamicRef": "#itemType" }
        }
      },
      "$defs": {
        "defaultItemType": {
          "$comment": "Only needed to satisfy bookending requirement",
          "$dynamicAnchor": "itemType"
        }
      }
    },
    "numberList": {
      "$id": "numberList",
      "$defs": {
        "itemType": {
          "$dynamicAnchor": "itemType",
          "type": "number"
        }
      },
      "$ref": "genericList"
    },
    "stringList": {
      "$id": "stringList",
      "$defs": {
        "itemType": {
          "$dynamicAnchor": "itemType",
          "type": "string"
        }
      },
      "$ref": "genericList"
    }
  }
}

In this case, you don't know where $dynamicRef: #itemType will resolve until you have an instance that has a kindOfList property.

This example has all of the reference targets defined in this document, but that doesn't have to be the case.

[Stranger6667]

Thank you for pointing this out @gregsdennis!

Indeed, I wasn't thinking about $dynamicRef, and it is surely something that has to happen at validation time. My original idea was to push all IO operations to the "building" step and therefore avoid asyncness at validation time. I think this is still possible unless JSON Schema allows for referring other instances from the input document.

There is no support for some kind of "composite" inputs where they are broken down into multiple pieces that are referred from some "root" input, right?

Otherwise, I think $dynamicRef is somehow different from other nodes in the graph - just the proper edge will be decided at validation time.

[gregsdennis]

If you want to think of dynamic references having multiple conditional outcomes, and you can calculate all of that up front then just pick the right one at eval time, that's definitely an option. I've been trying to figure out how to do something similar in my lib, but how to fit that into my architecture has eluded me so far.

Instances don't typically refer to each other, no. If they did, any such references would need to be resolved prior to schema evaluation.

The other aspect of $dynamicRef is how it can model extensibility. The 2020-12 meta-schema uses it this way. If I want to create an extension meta-schema, I will need to add a $dynamicAnchor: meta to my meta-schema and then have it reference the 2020-12 meta-schema. My docs for how vocabs work show this being done.

This kind of dynamic reference isn't instance-based, but it does depend on where you start evaluation. The first matching $dynamicAnchor in the evaluation path is what's resolved.

[Hendler]

I am not a sophisticated user, but want to build a tool that lets devs use JSON schema in a document utility called JACS.

I like assert!(!jsonschema::is_valid(&instance, &schema).await); - currently I load some schemas into memory for this purpose. Curious if there is any internal caching of resolutions. [1]

Custom keywords
I like all the custom validations. I use a custom field to print out human readable fields vs machine used fields.
https://github.com/HumanAssisted/JACS/blob/c20bfb6f9d8ee2ee21acdac7e7d32b36b11b0c9b/src/schema/mod.rs#L68

Custom reference resolving - If I understand, a general ability to turn off all remote references would be a valuable feature. Maybe that can be done already

I'm likely going to use blocking features until the need for async arrises, which is why I ask about the caching of resolutions.

Hope this is helpful.

[1] -
Here’s the custom loader to handle embedded strings, then check urls - the $id and $ref alternates between in program embedded strings, filesystem, and remote.
https://github.com/HumanAssisted/JACS/blob/c20bfb6f9d8ee2ee21acdac7e7d32b36b11b0c9b/src/schema/utils.rs#L91
https://github.com/HumanAssisted/JACS/blob/c20bfb6f9d8ee2ee21acdac7e7d32b36b11b0c9b/src/agent/mod.rs#L623C1-L634C6

[Stranger6667]

Thank you for the context!

I like assert!(!jsonschema::is_valid(&instance, &schema).await); - currently I load some schemas into memory for this purpose. Curious if there is any internal caching of resolutions.

I think this could be implemented with a custom resolver + global cache:

static CACHE: Lazy<Mutex<HashMap<String, Value>>> = ...;

struct CachingResolver;

impl jsonschema::ReferenceResolver<Value> for Resolver {
    async fn resolve_external(&self, url: &str) -> BuildResult<Value> {
        let mut cache = CACHE.lock().unwrap();
        if let Some(value) = cache.get(url) {
            return Ok(value);
        }
        let resolved = ...  // Resolve the external reference, e.g. `reqwest::get`
        cache.insert(url.to_string(), resolved.clone());
        Ok(resolved)
    }
};

Something like that (could also be RwLock / semaphore for some more fine-grained locking) and similarly for the current implementation.

There is no plan for caching by default, but maybe it could be a configuration option:

#[tokio::main]
async fn main() {
    // ...
    let validator = jsonschema::ValidatorBuilder::default()
        .cache(
            // This is an LRU cache
            jsonschema::RemoteReferenceCache::new(
                NonZeroUsize::new(5).expect("Invalid cache size")
            )
        )
        .build(&schema)
        .await
        .unwrap();
}

I like all the custom validations. I use a custom field to print out human readable fields vs machine used fields.
https://github.com/HumanAssisted/JACS/blob/c20bfb6f9d8ee2ee21acdac7e7d32b36b11b0c9b/src/schema/mod.rs#L68

That is cool! I think custom keywords can simplify the implementation you have! The implementation is already merged and I hope to release it this week - the API is roughly the same as described above (except for the J parameter, the current version works only with serde_json::Value + minor naming that I'll adjust soon).

Custom reference resolving - If I understand, a general ability to turn off all remote references would be a valuable feature. Maybe that can be done already

Yep. There is an example in the docs that is close to what you describe:

struct MyCustomResolver;

impl SchemaResolver for MyCustomResolver {
    fn resolve(&self, root_schema: &Value, url: &Url, _original_reference: &str) -> Result<Arc<Value>, SchemaResolverError> {
        match url.scheme() {
            "json-schema" => {
                Err(anyhow!("cannot resolve schema without root schema ID"))
            },
            "http" | "https" => {
                Ok(Arc::new(json!({ "description": "an external schema" })))
            }
            _ => Err(anyhow!("scheme is not supported"))
        }
    }
}

So, you'll need to return anyhow::Error on remote references.

Or do you mean to have it as a built-in configuration option?

I'm likely going to use blocking features until the need for async arrises, which is why I ask about the caching of resolutions.

Yep, makes sense!

Hope this is helpful.

Thank you, I appreciate your feedback and questions! Let me know if I can elaborate or provide more details on any of these topics.