json-schema how to reference other schemas in jsonschema2pojo

I’ve been using the jsonschema2pojo utility at work to automatically generate java classes from JSON schemas, simplifying a lot of the tedious code that needs to be written for the marshalling and unmarshalling of JSON objects. JSON schema is a developing standard that is analogous to what XSD is to XML, providing schema definition and validation for JSON. Just like with XSD, a JSON schema can reference other schemas. This is done by using the special object property $ref.

The following is a simple JSON schema for an address object. Assume that it is stored in the file, Address.json:

{
    "id":"Address",
    "title": "Address",
    "description":"This is the json schema for an address",
    "type": "object",
    "properties": {
        "streetAddress": {
            "type": "string"
        },
        "city": {
            "type": "string"
        },
        "state/province": {
            "type": "string"
        },
        "zipcode": {
            "type": "string"
        }
    }
}

Here is a simple JSON schema for a person object. A person object contains an address. To reference the previously defined address schema, add an address object that contains a $ref property pointing to the filepath of the Address.json file:

 
{
    "id": "Person",
    "title": "Person",
    "description":"This is the json schema for a person",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        },
        "address": {
            "$ref": "Address.json"
        }
    }
}

Note that both relative and absolute pathing work in jsonschema2pojo.

To add a reference to a list of addresses, add an “addresses” object with a “type” property of array and an “items” object. Add a $ref property under “items” that points to the filepath of Address.json:

{
    "id": "Person",
    "title": "Person",
    "description":"This is the json schema for a person",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        },
        "addresses": {
            "id" : "addresses",
            "type": "array", 
            "items": { "$ref": "Address.json" },
            "uniqueItems": true
        }
    }
}

jsonschema2pojo will generate a Java class that contains a List of Address objects. Incidentally, adding the property “uniqueItems”:true it becomes a HashSet of Address objects.

A free schema generation tool is available at http://www.jsonschema.net/. When paired with utilities like jsonschema2pojo, it makes life for developers that much easier.