Packages
Package	Description
org.eel.kitchen.jsonschema.examples	API usage examples
org.eel.kitchen.jsonschema.format	Format attribute base classes
org.eel.kitchen.jsonschema.format.common	Common format attribute classes for draft v3 and draft v4
org.eel.kitchen.jsonschema.format.draftv3	Format attributes specific to draft v3
org.eel.kitchen.jsonschema.keyword	Schema validation core elements: keyword validators
org.eel.kitchen.jsonschema.keyword.common	Common keyword classes for draft v3 and draft v4
org.eel.kitchen.jsonschema.keyword.draftv3	Keywords specific to draft v3
org.eel.kitchen.jsonschema.keyword.draftv4	Keywords specific to draft v4
org.eel.kitchen.jsonschema.main	Main schema validation API
org.eel.kitchen.jsonschema.metaschema	"Metaschema" data
org.eel.kitchen.jsonschema.ref	JSON Reference related classes
org.eel.kitchen.jsonschema.report	Validation reports and messages
org.eel.kitchen.jsonschema.schema	Internal JSON Schema objects
org.eel.kitchen.jsonschema.syntax	Schema syntax validation package
org.eel.kitchen.jsonschema.syntax.common	Common syntax validators for draft v3 and draft v4
org.eel.kitchen.jsonschema.syntax.draftv3	Syntax validators specific to draft v3
org.eel.kitchen.jsonschema.syntax.draftv4	Syntax validators specific to draft v4
org.eel.kitchen.jsonschema.syntax.hyperschema	Hyper-schema syntax validators
org.eel.kitchen.jsonschema.syntax.hyperschema.draftv3	Draft v3 specific hyper-schema syntax validators
org.eel.kitchen.jsonschema.uri	Classes to handle downloading of JSON documents using any URI scheme
org.eel.kitchen.jsonschema.util	Various utility classes
org.eel.kitchen.jsonschema.util.jackson	Utility classes for Jackson
org.eel.kitchen.jsonschema.validator	Core validation process

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 validation support. This includes all "exotic" features of the draft, such as:

multiple schemas in extends;
schemas in type and disallow;
schemas in dependencies.

It now also has support for draft v4, and schema version detection via $schema.

It also has two 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.

Sample usage

See the org.eel.kitchen.jsonschema.examples package: it contains example usages for nearly all situations. This includes:

schema version detection;
use of inline addressing via id;
examples of URI namespaces and redirections;
schema customization (by adding new format attributes of keyword).

The validation process

The validation process is a three step process:

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

The core package for the validation process is org.eel.kitchen.jsonschema.validator, and in particular JsonValidatorCache. This class is instantiated by a schema factory and uses a LoadingCache to store already computed validators. There is one such cache per schema version.

`$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).

Now, more food for thought. 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.

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.

The syntax validation process implies a SyntaxValidator instance, which checks that all keywords are syntactically correct using a series of SyntaxChecker objects.

The role of SyntaxChecker objects in particular is very important: for a given keyword, a syntax checker ensures that the value of this keyword is well formed. This is what allows the next step in the process to be easier to implement.

Instance (aka data) validation

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

The process begins with an instance of InstanceValidator. It will query, via the factory, a set of KeywordValidator instances. All of these keyword validators will then be called in turn to validate the data.

Object/array instance validation

There is one more step to validation. The step above will only have validated that the current "path" in the JSON instance will have been validated. However, in the event where the instance is a so-called container instance, that is it has children nodes, which is the case of objects and arrays, then a further validation step is issued so that all children get validated.

The two classes responsible for this, ArrayValidator and ObjectValidator, take responsibility from this point and will restart the validation process from scratch for each of the instance children.

It should be noted that while array instance children only have to match exactly one schema, object instance children may have to match several of them, which does nothing to simplify matters...

A particular note about `type`, `disallow`, `dependencies` and `extends`

Those four schema keywords have the unfortunate property that they can also restart the validation process from their own:

type and disallow can bear schemas in their array representations; validation should consider those schemas;
similarly, dependencies can link one property in an object instance to another schema, then the whole instance must also validate against that schema -- and you may have several occurrences of that;
extends, in a similar vein, unconditionally constrains the instance to obey the schema(s) it mentions.

Those four schema keywords are an implementor's worst nightmare. Remember that the validation process starts from $ref resolution: each of these keywords, should they have schema dependencies of some sort, have to start the whole validation process from scratch.

json-schema-validator 1.4.4 API