JSON Schema guide — validate your data structure with examples

JSON Schema is a vocabulary for describing and validating the structure of JSON data. It lets you define what fields are required, what types they must be, and constraints like min/max values — then validate any JSON document against those rules.

A minimal schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age":  { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

This schema says: the root value must be an object; it must have a name string; age, if present, must be a non-negative integer.

Core types

{ "type": "string" }   // any string
{ "type": "number" }   // integer or float
{ "type": "integer" }  // whole numbers only
{ "type": "boolean" }  // true or false
{ "type": "null" }     // null
{ "type": "array" }    // JSON array
{ "type": "object" }   // JSON object

// Allow multiple types
{ "type": ["string", "null"] }   // string or null

String constraints

{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-z0-9_-]+$",   // regex
  "format": "email"               // requires ajv-formats
}

Number constraints

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "exclusiveMinimum": 0,   // > 0, not >= 0
  "multipleOf": 0.01       // e.g. for currency
}

Object schemas

{
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "role":  { "type": "string", "enum": ["admin", "user", "guest"] }
  },
  "required": ["id", "email"],
  "additionalProperties": false   // reject unknown keys
}

Array schemas

{
  "type": "array",
  "items": { "type": "string" },   // every element must be a string
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

// Tuple — different type per position
{
  "type": "array",
  "prefixItems": [
    { "type": "string" },
    { "type": "integer" }
  ],
  "items": false   // no additional items allowed
}

Combining schemas

// allOf — must match ALL sub-schemas
{ "allOf": [{ "type": "object" }, { "required": ["id"] }] }

// anyOf — must match AT LEAST ONE
{ "anyOf": [{ "type": "string" }, { "type": "null" }] }

// oneOf — must match EXACTLY ONE
{ "oneOf": [
    { "type": "integer", "minimum": 1 },
    { "type": "string", "pattern": "^[0-9]+$" }
] }

// not — must NOT match
{ "not": { "type": "null" } }

Reusing definitions with $ref

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

Validating with Ajv in JavaScript

import Ajv from "ajv";
const ajv = new Ajv();

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

const validate = ajv.compile(schema);
const valid = validate({ name: "Ada" });
if (!valid) console.log(validate.errors);

Validating with jsonschema in Python

from jsonschema import validate, ValidationError

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

try:
    validate(instance={"name": "Ada"}, schema=schema)
    print("Valid")
except ValidationError as e:
    print(e.message)

Use the JSON Schema Validator on this site to test schemas interactively in your browser — no setup required.