Packages
Package	Description
com.github.fge.jsonschema.examples	API usage examples
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.keyword	Schema validation core elements: keyword validators
com.github.fge.jsonschema.keyword.common	Common keyword classes for draft v3 and draft v4
com.github.fge.jsonschema.keyword.draftv3	Keywords specific to draft v3
com.github.fge.jsonschema.keyword.draftv4	Keywords specific to draft v4
com.github.fge.jsonschema.main	Main schema validation API
com.github.fge.jsonschema.metaschema	Metaschema data
com.github.fge.jsonschema.ref	JSON Reference related classes
com.github.fge.jsonschema.report	Validation reports and messages
com.github.fge.jsonschema.schema	Internal JSON Schema objects
com.github.fge.jsonschema.syntax	Schema syntax validation package
com.github.fge.jsonschema.syntax.common	Common syntax validators for draft v3 and draft v4
com.github.fge.jsonschema.syntax.draftv3	Syntax validators specific to draft v3
com.github.fge.jsonschema.syntax.draftv4	Syntax validators specific to draft v4
com.github.fge.jsonschema.syntax.hyperschema	Hyper-schema syntax validators
com.github.fge.jsonschema.syntax.hyperschema.draftv3	Draft v3 specific hyper-schema syntax validators
com.github.fge.jsonschema.uri	Classes to handle downloading of JSON documents using any URI scheme
com.github.fge.jsonschema.util	Various utility classes
com.github.fge.jsonschema.util.jackson	Utility classes for Jackson
com.github.fge.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 com.github.fge.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 com.github.fge.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.5.5 API