json-schema-validator 1.99.13 API

A JSON Schema validator implementation in Java which aims for correctness and performance, in that order

See: Description

Packages 
Package Description
com.github.fge.jsonschema.cfg  
com.github.fge.jsonschema.exceptions  
com.github.fge.jsonschema.exceptions.unchecked  
com.github.fge.jsonschema.format
Format attribute base classes
com.github.fge.jsonschema.format.common
Common format attribute classes for draft v3 and draft v4
com.github.fge.jsonschema.format.draftv3
Format attributes specific to draft v3
com.github.fge.jsonschema.format.draftv4
Format attributes specific to draft v4
com.github.fge.jsonschema.format.helpers
Helper classes for format attributes
com.github.fge.jsonschema.keyword.digest
Keyword digesters
com.github.fge.jsonschema.keyword.digest.common  
com.github.fge.jsonschema.keyword.digest.draftv3  
com.github.fge.jsonschema.keyword.digest.draftv4  
com.github.fge.jsonschema.keyword.digest.helpers  
com.github.fge.jsonschema.keyword.syntax  
com.github.fge.jsonschema.keyword.syntax.common  
com.github.fge.jsonschema.keyword.syntax.draftv3  
com.github.fge.jsonschema.keyword.syntax.draftv4  
com.github.fge.jsonschema.keyword.syntax.helpers  
com.github.fge.jsonschema.keyword.validator  
com.github.fge.jsonschema.keyword.validator.common  
com.github.fge.jsonschema.keyword.validator.draftv3  
com.github.fge.jsonschema.keyword.validator.draftv4  
com.github.fge.jsonschema.keyword.validator.helpers  
com.github.fge.jsonschema.library  
com.github.fge.jsonschema.library.digest  
com.github.fge.jsonschema.library.format  
com.github.fge.jsonschema.library.syntax  
com.github.fge.jsonschema.library.validator  
com.github.fge.jsonschema.load  
com.github.fge.jsonschema.main  
com.github.fge.jsonschema.messages  
com.github.fge.jsonschema.processors  
com.github.fge.jsonschema.processors.build  
com.github.fge.jsonschema.processors.data  
com.github.fge.jsonschema.processors.digest  
com.github.fge.jsonschema.processors.format  
com.github.fge.jsonschema.processors.ref  
com.github.fge.jsonschema.processors.syntax  
com.github.fge.jsonschema.processors.validation  
A JSON Schema validator implementation in Java which aims for correctness and performance, in that order

What this is

Motivation

This implementation is meant to be purely server-side if Java is your language of choice. You may, or may not, use it in your Java Web application; this library has no dependencies on anything Web-related.

Strong points

This library has complete draft v3 and draft v4 validation support.

It also has three particular features making it stand apart:

  • regular expressions obey ECMA 262 (ie, those are JavaScript regular expressions);
  • it can validate numeric JSON data or abitrary scale/precision;
  • it is very customizable.

Sample usage

TODO: rewrite examples

The validation process

The validation process is a five step process:

  • $ref resolution;
  • schema syntax validation;
  • schema digesting;
  • keyword building;
  • instance validation (ie, validate your data).

All these steps are performed through a series of Processors, and you can write your own. Note that all of these processors also cache results (using a LoadingCache for future reuse.

$ref resolution

This is a critically important part of the validation process. You may encounter, during validation, what is called a JSON Reference. A JSON Reference is a JSON Object with one member named $ref, and the value of this member is a text value which embodies a URI. Implementations are required to follow JSON References until an actual final content is reached (and this content may, or may not, be a valid JSON Schema).

Also, consider this schema:

    {
        "$ref": "some://where/else",
        "minimum": 3
    }

This is still a JSON Reference. Other schema keywords, such as minimum in this example, should be ignored. And this is what this implementation does.

Note that any failure in $ref validation is considered a fatal error.

The processor in charge of this step is processors.ref.RefResolverProcessor.

Schema syntax checking

This is an equally important part of the validation process. One thing to note about the previous step is that it will only check that JSON Reference resolution ultimately leads to a JSON document, whatever that document is. Which means it may not even be a JSON Object, therefore not a JSON Schema. This basic check is done at that level.

After schema syntax checking is done, you are ensured that the schema is well formed: this simplifies later processing. Note however that syntax checking will not follow JSON References.

The processor in charge of this step is syntax.SyntaxProcessor.

Digesting

This step of the processing chain takes into account both the schema and the instance to validate. Its role is to check the instance type, pick the relevant keywords for that instance type into the current schema, and build digested forms of these keywords for the next step.

For instance, consider that you are validating a number instance, and the current schema reads:

    {
        "minItems": 3,
        "maximum": 3
    }

minItems does not apply to numbers, it will therefore be filtered out here. But this is not all. Now consider those two schemas:

    {
        "additionalItems": true
    }

    {
        "additionalItems": { "type": "string" }
    }

They have exactly the same influence on the validation of the array itself (note: the array, not its elements). The digest for these two schemas when the instance to validate is an array will therefore be the same. This allows to prune a lot of duplicates out of keyword caching.

The processor in charge of this step is digest.SchemaDigester.

Keyword building

At this step, the digested form of the current schema is grabbed and all relevant keywords are built (if they are not found in the cache). The real validation can now take place.

Again, all results are cached for future reuse. And as all keywords are context-free, a same result can be reused across different schemas.

The processor in charge of this step is build.KeywordBuilder.

Instance (aka data) validation

This is the part which actually matters to end users: ensure that their data is valid.

This step of the processing consists of two distinct elements:

  • running the keyword validators built at the previous step;
  • (recursively) validating children of arrays and/or objects.

As some keywords require that this very same processor be called again, all keyword validators keep a reference to it: this is what also allows keywords such as anyOf, allOf and others to work correctly. In a similar manner, this processor also needs a reference to the start of the chain (the reference resolver processor).

The processor in charge of this step is validation.ValidationProcessor.

More

Processing customization

The core interfaces used for the mechanism above are really simple:

  • Processor denotes an individual processor in the chain;
  • ProcessorChain allows you to chain processors to make another processor;
  • ProcessingReport covers all logging needs, and you can customize it;
  • MessageProvider allows you to grab a context dependent message template for informative logging.

This library is therefore not limited to pure validation anymore: you can imagine -- and code -- any processor of your choice and chain it with others.

Copyright © 2013. All Rights Reserved.