json-schema-validator 0.5.0beta1 API

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

See:
Description

Packages

org.eel.kitchen.jsonschema.format
org.eel.kitchen.jsonschema.keyword
org.eel.kitchen.jsonschema.main
org.eel.kitchen.jsonschema.ref
org.eel.kitchen.jsonschema.schema
org.eel.kitchen.jsonschema.syntax
org.eel.kitchen.jsonschema.uri
org.eel.kitchen.util	Various utility packages

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

For the impatient...

• load your JSON Schema and data using JsonLoader,
• create a new instance of JsonValidator,
• validate!

The API covers all validation aspects of the current draft, and is also extensible, see below.

What is JSON Schema

JSON Schema can be viewed as the equivalent of XML Schema for JSON documents. Its role is therefore to validate any JSON input thrown at you so that it conform to a set of rules you define.

Here is a simple example of a schema:

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 3
        },
        "surname": {
            "type": "string",
            "minLength": 3
        },
        "gender": {
            "enum": [ "male", "female" ]
        },
        "age": {
            "type": "integer",
            "minimum": 18
        }
    },
    "additionalProperties": false
}

And here is an example of document to validate (successfully in this case):

{
    "name": "Doe",
    "surname: "John",
    "gender": "male",
    "age": 38
}

Here is a document which will not validate:

{
    "name": "Doe",
    "surname: "John",
    "gender": "martian",
    "age": 3,
    "color": "red"
}

The reasons are:

• the age property is below the required minimum (18);
• the gender property does not match any member of the enumeration;
• there is a supplementary property named color, but no additional properties are allowed.

This is only scratching the surface, JSON Schema allows much more: referencing other schemas, validating all types of JSON elements (there are seven in total: array, object, string, number, integer, boolean, null), etc etc.

This API covers all the current JSON Schema specification, which means it can handle much more complex schemas than the above (this includes detecting schema versions and acting accordingly, fetching schemas from external sources etc).As to documents to validate, you can feed it with anything you like... That is, as long as it fits in memory! Unfortunately, the API cannot handle streams as input -- yet. This is being thought on at the moment.

Extending the API

The API also offers the ability to extend the API by adding new keywords, removing keywords or changing the meaning of keywords (the latter is very useful if you wish to test a new meaning for an existing keyword).

For this, you need to:

• write a new org.eel.kitchen.jsonschema.syntax.SyntaxValidator,
• write a new KeywordValidator,
• and registering it to the JsonValidator you instantiated (optionially specifying the version of the schema you want to add this keyword to -- see the API for details).

A brief overview of features

• schema syntax checking and JSON document validation (with the ability to skip schema syntax checking);
• validator/schema caching;
• arbitrary length/precision number validation;
• ECMA 262 regexes, as required by the draft (using Rhino);
• ability to register URI handlers for any scheme (HTTP only natively);
• complete $ref support, with loop detection;
• automatic schema version detection;
• ability to change the default schema version (currently draft v3 by default);
• ability to register/unregister keywords;
• full report or fail-fast report modes.

If you find a bug, or have a feature request, please file an issue on GitHub.

Happy validation!