JSON Schema: Validate and Document Your JSON APIs

JSON Schema is a vocabulary for annotating and validating JSON documents. It serves as both documentation and a contract for your API: a single schema file describes what valid data looks like, powers automated validation, and can generate client code, mock servers, and documentation.

A Minimal Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string" },
    "email": { "type": "string", "format": "email" }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Type System

{ "type": "string" }
{ "type": "number" }
{ "type": "integer" }
{ "type": "boolean" }
{ "type": "null" }
{ "type": "array" }
{ "type": "object" }

/* Multiple types allowed */
{ "type": ["string", "null"] }   /* nullable string */

String Constraints

{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[a-zA-Z0-9_]+$",      /* regex */
  "format": "email"                   /* semantic validation */
}

/* Common formats */
"format": "email"
"format": "uri"
"format": "date"          /* YYYY-MM-DD */
"format": "date-time"     /* ISO 8601 */
"format": "uuid"
"format": "ipv4"
"format": "ipv6"

Number Constraints

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,    /* strictly greater than 0 */
  "multipleOf": 0.5         /* must be divisible by 0.5 */
}

Array Schemas

{
  "type": "array",
  "items": { "type": "string" },    /* all items must be strings */
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true               /* no duplicates */
}

/* Tuple validation — specific types per position */
{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" }
  ],
  "items": false    /* no extra items allowed */
}

Object Schemas

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age":  { "type": "integer", "minimum": 0 }
  },
  "required": ["name"],
  "additionalProperties": false,    /* reject unknown keys */
  "minProperties": 1,
  "maxProperties": 10,

  /* Pattern properties — match keys by regex */
  "patternProperties": {
    "^x_": { "type": "string" }     /* any key starting with x_ */
  }
}

Combining Schemas

allOf — must match all schemas

{
  "allOf": [
    { "type": "object", "required": ["name"] },
    { "properties": { "age": { "minimum": 18 } } }
  ]
}

anyOf — must match at least one

{
  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
}

oneOf — must match exactly one

{
  "oneOf": [
    { "properties": { "type": { "const": "email" }, "address": {} }, "required": ["address"] },
    { "properties": { "type": { "const": "phone" },  "number": {} },  "required": ["number"] }
  ]
}

not — must not match

{ "not": { "type": "null" } }   /* anything except null */

$ref and $defs — Reusable Schemas

{
  "$defs": {
    "Address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "zip":    { "type": "string", "pattern": "^[0-9]{5}$" }
      },
      "required": ["street", "city", "zip"]
    }
  },
  "type": "object",
  "properties": {
    "billing":  { "$ref": "#/$defs/Address" },
    "shipping": { "$ref": "#/$defs/Address" }
  }
}

Conditional Schemas

{
  "if":   { "properties": { "country": { "const": "US" } } },
  "then": { "required": ["zipCode"] },
  "else": { "required": ["postalCode"] }
}

Tools That Use JSON Schema

JSON Schema is supported by a large ecosystem. Validators are available for every major language: ajv (JavaScript), jsonschema (Python), json-schema-validator (Java). OpenAPI / Swagger uses a subset of JSON Schema to describe API request and response bodies. TypeScript developers can generate types from schemas using json-schema-to-ts or quicktype. VS Code uses JSON Schema for autocomplete and validation in settings files, package.json, and custom config formats.

Use the JSON Tools on io9.me to format and validate any JSON document before writing or testing a schema against it.