JSON Schema Overview

What is JSON Schema?

JSON Schema is intended to be a clear, human- and machine-readable format for describing what constitutes valid [JSON](JSON Overview) data.

The "clear, human- and machine-readable format" that JSON Schema uses to describe JSON data structures is itself written in JSON.

Here is a simple schema provided at the JSON Schema website example page:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product",
    "description": "A product from Acme's 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
        },
        "tags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "minItems": 1,
            "uniqueItems": true
        }
    },
    
    "required": ["id", "name", "price"]
}

This schema example has six properties, called keywords:

1. $schema
2. title
3. description
4. type
5. properties
6. required

The first three are not required. The $schema keyword declares that this is a schema based on the draft v4 specification, and the title and description keywords are simply informational.

The last three keywords (type, properties, required) declare constraints for valid JSON objects intended to represent product data.

These keywords declare that a JSON data document must satisify the following constraints to be considered a valid instance of this schema:

• id, name, and price properties must be present
• id must be of type integer
• name must be of type string
• price must be of type number with a value greater than zero
• tags is an optional array with string values; if present, there must be at least one element and all elements must be unique.

Using this example, a schema validator can be used to verify that the following JSON data satisfies all constraints to be a valid instance:

{
    "id": 1,
    "name": "A green door",
    "price": 12.50,
    "tags": ["home", "green"]
}

Based on the schema, the JSON examples from the previous section would not be valid instances because of both structural and type differences.

Where to learn more about JSON Schema

JSON Schema is a specification split into three parts. The latest draft of the specification is v4 and it can be found both on the IETF site as Internet Drafts and on the official JSON Schema website here.

These are the three parts:

1. JSON Schema Core (defines basic foundation, such as core definitions and terminology
2. JSON Schema Validation (defines the validation keywords)
3. JSON Hyper-Schema (defines hyperlink and hypermedia keywords)

Access to specifications is obviously important for those implementing a JSON Schema validator (a tool or library used to validate JSON instances against a JSON schema). For those looking for a more accessible way to understand simply how to read and write JSON Schema, Michael Droettboom of the Space Telescope Science Institute has created a very nice open source online book located here.