Introduction to JSON Schema in Java

I usually post about Jackson and JSON stuff on Twitter - you can follow me there:

1. Overview

JSON Schema is a declarative language for validating the format and structure of a JSON Object. It allows us to specify a number of special primitives to describe exactly what a valid JSON Object will look like.

The JSON Schema specification is divided into three parts:

• JSON Schema Core: The JSON Schema Core specification is where the terminology for a schema is defined.
• JSON Schema Validation: The JSON Schema Validation specification is the document that defines the valid ways to define validation constraints. This document also defines a set of keywords that can be used to specify validations for a JSON API. In the examples that follow, we’ll be using some of these keywords.
• JSON Hyper-Schema: This is another extension of the JSON Schema spec, where-in, the hyperlink and hypermedia-related keywords are defined.

2. Defining a JSON Schema

Now that we have defined what a JSON Schema is used for, let’s create a JSON Object and the corresponding JSON Schema describing it.

The following is a simple JSON Object representing a product catalog:

{
    "id": 1,
    "name": "Lampshade",
    "price": 0
}

We could define its JSON Schema as follow:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from the catalog",
    "type": "object",
    "properties": {
        "id": {
            "description": "The unique identifier for a product",
            "type": "integer"
        },
        "name": {
            "description": "Name of the product",
            "type": "string"
        },
        "price": {
            "type": "number",
            "minimum": 0,
            "exclusiveMinimum": true
        }
    },
    "required": ["id", "name", "price"]
}

As we can see a JSON Schema is a JSON document, and that document MUST be an object. Object members (or properties) defined by JSON Schema are called keywords.

Let’s explain the keywords that we have used in our sample:

• The $schema keyword states that this schema is written according to the draft v4 specification.
• The title and description keywords are descriptive only, in that they do not add constraints to the data being validated. The intent of the schema is stated with these two keywords: describes a product.
• The type keyword defines the first constraint on our JSON data: it has to be a JSON Object.

Also, a JSON Schema MAY contain properties which are not schema keywords. In our case id, name, price will be members (or properties) of the JSON Object.

For each properties we can define the type. We defined id and name as string and price as number. In JSON Schema a number can have a minimum. By default this minimum is inclusive, so we need to specify exclusiveMinimum.

Finally, the Schema tells that id, name and price are required.

3. Validation with JSON Schema

With our JSON Schema put in place we can validate our JSON Object.

There are many libraries to accomplish this task. For the purpose of our example we have chosen the Java json-schema library.

First of all we need to add the following dependency to our pom.xml:

<dependency>
    <groupId>org.everit.json</groupId>
    <artifactId>org.everit.json.schema</artifactId>
    <version>1.3.0</version>
</dependency>

Finally we can write a couple of simple test case to validate our JSON Object:

@Test
public void givenInvalidInput_whenValidating_thenInvalid() throws ValidationException {
    JSONObject jsonSchema = new JSONObject(
      new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json")));
    JSONObject jsonSubject = new JSONObject(
      new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_invalid.json")));
    
    Schema schema = SchemaLoader.load(jsonSchema);
    jsonSchema.validate(jsonSubject);
}

In this case thrown ValidationException will point to #/price. If you look at the console it will print the following output:

#/price: 0.0 is not higher than 0

The second test look like the following:

@Test
public void givenValidInput_whenValidating_thenValid() throws ValidationException {
    JSONObject jsonSchema = new JSONObject(
      new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/schema.json")));
    JSONObject jsonSubject = new JSONObject(
      new JSONTokener(JSONSchemaTest.class.getResourceAsStream("/product_valid.json")));

    Schema schema = SchemaLoader.load(jsonSchema);
    jsonSchema.validate(jsonSubject);
}

Since we use a valid JSON Object no validation error will be thrown.

4. Conclusion

In this article we have defined what is a JSON Schema and wich are some relevant keyword that help us to define our own schema.

Coupling a JSON Schema with its corresponding JSON Object representation we can perform some validation task.

A simple test case of this article can be found in the github project.