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.

Primitive types

JSON Schema defines seven primitive types for JSON values:

• array = a JSON array.
• boolean = a JSON boolean.
• integer = a JSON number without a fraction or exponent part.
• number = any JSON number. Number includes integer.
• null = the JSON null value.
• object = a JSON object.
• string = a JSON string.

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

• Database schema
• Iglu repository - a store of data schemas for Snowplow (software), currently (August 2016) supporting JSON Schemas only.
• 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

General

• 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.
• Introducing self-describing JSONs
• Structuring a complex schema
• JSON Validation with JSON Schema @ davidwalsh.name

Validators

• JSON Schema Validator @ jsonschemavalidator.net
• JSON Schema Validator @ json-schema-validator.herokuapp.com
• JSON schema validator @ jsonschemalint.com
• JSON formatter and validator @ jsonformatter.curiousconcept.com
• JSON lint @ jsonlint.com