JSON Schema

JSON Schema specifies a JSON-based format to define the structure of JSON data for validation, documentation, and interaction control.

Description

A JSON Schema provides a contract for the JSON data required by a given application, and how that data can be modified.

JSON Schema is based on the concepts from XML Schema (XSD), but is JSON-based.

The JSON data schema can be used to validate JSON data.

As in XSD, the same serialization/deserialization tools can be used both for the schema and data.

The schema is self-describing.

JSON Schema was an Internet Draft, most recently version 4, which expired on August 4, 2013.

There are several validators available for different programming languages, each with varying levels of conformance.

Example

Example of a JSON schema:

{
  "$schema": "http://json-schema.org/schema#",
  "title": "Product",
  "type": "object",
  "required": ["id", "name", "price"],
  "properties": {
    "id": {
      "type": "number",
      "description": "Product identifier"
    },
    "name": {
      "type": "string",
      "description": "Name of the product"
    },
    "price": {
      "type": "number",
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "stock": {
      "type": "object",
      "properties": {
        "warehouse": {
          "type": "number"
        },
        "retail": {
          "type": "number"
        }
      }
    }
  }
}

The JSON Schema above can be used to test the validity of the JSON code below:

{
  "id": 1,
  "name": "Foo",
  "price": 123,
  "tags": [
    "Bar",
    "Eek"
  ],
  "stock": {
    "warehouse": 300,
    "retail": 20
  }
}

Example two

It is customary (but not required) to use a top-level key named definitions:

{
  "$schema": "http://json-schema.org/draft-04/schema#",

  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city":           { "type": "string" },
        "state":          { "type": "string" }
      },
      "required": ["street_address", "city", "state"]
    }
  },

  "type": "object",

  "properties": {
    "billing_address": { "$ref": "#/definitions/address" },
    "shipping_address": { "$ref": "#/definitions/address" }
  }
}

We can then refer to this schema snippet from elsewhere using the $ref keyword. The easiest way to describe $ref is that it gets logically replaced with the thing that it points to.

So, to refer to the above, we would include:

{ "$ref": "#/definitions/address" }

The value of $ref is a string in a format called JSON Pointer.

See also

• JSON - an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs.
• JSON Pointer - a string format for JSON Schema data.

External links

• JSON#Schema @ Wikipedia
• json-schema.org - "The home of JSON Schema."
• Understanding JSON Schema @ Space Telescope Science Institute.
• Schema Guru a tool (CLI, Spark job and web) allowing you to derive JSON Schemas from a set of JSON instances process and transform it into different data definition formats.