JSON Schema

JSON Schema is a vocabulary for annotating and validating JSON documents. It's platform-independent and widely used for API validation.

Current Specification: Draft 2020-12
Meta-schema: https://json-schema.org/draft/2020-12/schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Product",
  "description": "A product in the catalog",
  "type": "object"
}

The $schema keyword declares which JSON Schema version is used.

{
  "type": "string"
}

Seven basic types:

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

Accepts either a string or a number.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.json",
  "title": "User",
  "description": "A registered user",
  "default": {},
  "examples": [
    {
      "name": "Alice",
      "email": "alice@example.com"
    }
  ]
}

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billing": { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  }
}

Use $ref to reuse schema definitions.

{
  "type": "object",
  "properties": {
    "user": {
      "$ref": "https://example.com/schemas/user.json"
    }
  }
}

Reference schemas from external files or URLs.

{
  "type": "string",
  "minLength": 3,
  "maxLength": 20
}

Restricts string length (inclusive).

{
  "type": "string",
  "pattern": "^[A-Za-z0-9_]+$"
}

Validates against a regular expression (ECMA-262).

{
  "type": "string",
  "format": "email"
}

Built-in format validators:

Date/Time Formats

Network Formats

URI Formats

Other Formats

{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}

Inclusive minimum and maximum values.

{
  "type": "number",
  "exclusiveMinimum": 0,
  "exclusiveMaximum": 100
}

Exclusive boundaries (0 < x < 100).

{
  "type": "number",
  "multipleOf": 0.01
}

Value must be a multiple of the given number (useful for currency: 2 decimal places).

{
  "type": "integer",
  "minimum": 1,
  "maximum": 10
}

Integers are a subset of numbers (no decimals).

{
  "type": "array",
  "items": {
    "type": "string"
  }
}

All items must match the schema (homogeneous array).

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "type": "boolean" }
  ]
}

Validates positional items (heterogeneous array/tuple).

{
  "type": "array",
  "minItems": 1,
  "maxItems": 10
}

Constrains array size.

{
  "type": "array",
  "uniqueItems": true
}

All items must be unique (set semantics).

{
  "type": "array",
  "contains": {
    "type": "string",
    "pattern": "^admin"
  },
  "minContains": 1,
  "maxContains": 3
}

Array must contain at least minContains items matching the schema.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" },
    "email": {
      "type": "string",
      "format": "email"
    }
  }
}

Defines expected properties and their schemas.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" }
  },
  "required": ["name", "email"]
}

Lists mandatory properties.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "additionalProperties": false
}

Set to false to disallow unlisted properties.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  },
  "additionalProperties": {
    "type": "string"
  }
}

Or provide a schema for additional properties.

{
  "type": "object",
  "patternProperties": {
    "^[0-9]+$": {
      "type": "number"
    },
    "^[a-z]+$": {
      "type": "string"
    }
  }
}

Schema for properties matching regex patterns.

{
  "type": "object",
  "propertyNames": {
    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
  }
}

Validates all property names against a schema.

{
  "type": "object",
  "minProperties": 1,
  "maxProperties": 10
}

Limits number of properties in the object.

{
  "allOf": [
    { "type": "object" },
    {
      "properties": {
        "name": { "type": "string" }
      }
    },
    {
      "properties": {
        "age": { "type": "integer" }
      }
    }
  ]
}

Data must be valid against all subschemas.

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

Data must be valid against at least one subschema.

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "credit_card" },
        "card_number": { "type": "string" }
      }
    },
    {
      "properties": {
        "type": { "const": "bank_account" },
        "account_number": { "type": "string" }
      }
    }
  ]
}

Data must be valid against exactly one subschema.

{
  "not": {
    "type": "null"
  }
}

Data must not be valid against the subschema.

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postal_code": { "type": "string" }
  },
  "if": {
    "properties": {
      "country": { "const": "USA" }
    }
  },
  "then": {
    "properties": {
      "postal_code": {
        "pattern": "^[0-9]{5}(-[0-9]{4})?$"
      }
    }
  },
  "else": {
    "properties": {
      "postal_code": {
        "pattern": "^[A-Z0-9]+$"
      }
    }
  }
}

Apply different schemas based on conditions.

{
  "type": "object",
  "properties": {
    "credit_card": { "type": "string" }
  },
  "dependentSchemas": {
    "credit_card": {
      "properties": {
        "billing_address": { "type": "string" }
      },
      "required": ["billing_address"]
    }
  }
}

When credit_card is present, billing_address becomes required.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "credit_card": { "type": "string" },
    "billing_address": { "type": "string" }
  },
  "dependentRequired": {
    "credit_card": ["billing_address"]
  }
}

Simpler syntax when only requiring fields conditionally.

{
  "type": "string",
  "enum": ["red", "green", "blue"]
}

Value must be one of the enumerated values.

{
  "type": "string",
  "const": "active"
}

Value must exactly match the constant.

{
  "type": "string",
  "deprecated": true,
  "readOnly": true,
  "writeOnly": false
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user-registration.schema.json",
  "title": "User Registration",
  "description": "Schema for user registration form",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "Unique username (alphanumeric and underscore)"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Valid email address"
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]+$",
      "description": "Password with uppercase, lowercase, digit, and special char"
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120,
      "description": "User must be 18 or older"
    },
    "terms_accepted": {
      "type": "boolean",
      "const": true,
      "description": "User must accept terms"
    }
  },
  "required": ["username", "email", "password", "terms_accepted"]
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Product",
  "description": "A product in the catalog",
  "type": "object",
  "$defs": {
    "price": {
      "type": "number",
      "minimum": 0,
      "multipleOf": 0.01
    },
    "dimension": {
      "type": "object",
      "properties": {
        "length": { "type": "number", "minimum": 0 },
        "width": { "type": "number", "minimum": 0 },
        "height": { "type": "number", "minimum": 0 }
      },
      "required": ["length", "width", "height"]
    }
  },
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique product identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "price": {
      "$ref": "#/$defs/price"
    },
    "discount_price": {
      "$ref": "#/$defs/price"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "uniqueItems": true,
      "minItems": 1
    },
    "dimensions": {
      "$ref": "#/$defs/dimension"
    },
    "in_stock": {
      "type": "boolean"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "food", "books", "other"]
    }
  },
  "required": ["id", "name", "price", "in_stock", "category"],
  "if": {
    "properties": {
      "discount_price": { "type": "number" }
    },
    "required": ["discount_price"]
  },
  "then": {
    "properties": {
      "discount_price": {
        "type": "number",
        "exclusiveMaximum": { "$data": "1/price" }
      }
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/api-response.schema.json",
  "title": "API Response",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["success", "error"]
    }
  },
  "required": ["status"],
  "oneOf": [
    {
      "properties": {
        "status": { "const": "success" },
        "data": {
          "type": "object",
          "description": "Response payload"
        }
      },
      "required": ["data"]
    },
    {
      "properties": {
        "status": { "const": "error" },
        "error": {
          "type": "object",
          "properties": {
            "code": { "type": "integer" },
            "message": { "type": "string" }
          },
          "required": ["code", "message"]
        }
      },
      "required": ["error"]
    }
  ]
}

npm install ajv

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv();
addFormats(ajv);

const schema = {
  type: "object",
  properties: {
    email: { type: "string", format: "email" },
  },
  required: ["email"],
};

const validate = ajv.compile(schema);
const valid = validate({ email: "user@example.com" });

if (!valid) {
  console.log(validate.errors);
}

Popular libraries:

• ajv - Fast and feature-complete
• @hyperjump/json-schema - Spec-compliant
• jsonschema - Simple validator

pip install jsonschema

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name"]
}

data = {"name": "Alice", "age": 30}

try:
    validate(instance=data, schema=schema)
    print("Valid!")
except ValidationError as e:
    print(f"Invalid: {e.message}")

Popular libraries:

• jsonschema - Reference implementation
• fastjsonschema - High performance

Schema validates your data.
Meta-schema validates your schema.

Always include $schema to declare which JSON Schema version you're using.

By default, additionalProperties is true (allows any extra properties).

{
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  }
}

This allows { "name": "Alice", "age": 30 }.

To disallow: set "additionalProperties": false.

Patterns are implicitly anchored (match entire string).

{ "pattern": "abc" }

Matches "abc" anywhere in the string. Use ^abc$ for exact match.

The format keyword is for validation but may be ignored by validators.

Always check your validator's format support. Use ajv-formats with AJV.

In older drafts, sibling keywords to $ref were ignored.

{
  "$ref": "#/$defs/address",
  "description": "This might be ignored!"
}

Draft 2019-09+: Sibling keywords are now respected.

integer is a distinct type from number.

{ "type": "integer" }

Rejects 1.0 even though mathematically equal to 1 in some validators.

Empty arrays/objects are valid by default.

Use minItems: 1 or minProperties: 1 to require content.