JSON Schema Guide

JSON Schema is a vocabulary for validating the structure and content of JSON data. Define what fields are required, what types they must be, and what values are allowed — then validate any JSON against that contract.

Draft-07

2020-12

Used by: OpenAPI, Postman, AJV, Pydantic

What is JSON Schema?

A JSON Schema is itself a JSON document that describes the expected shape of another JSON document. You write a schema once, then use a validator library (like AJV in JavaScript, or jsonschema in Python) to validate incoming data against it at runtime.

JSON Schema is the foundation of OpenAPI/Swagger specs, Pydantic models, TypeScript type generation, and form validation in countless applications.

A complete object schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "name":  { "type": "string",  "minLength": 2, "maxLength": 100 },
    "email": { "type": "string",  "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 },
    "role":  { "type": "string",  "enum": ["admin", "user", "guest"] }
  },
  "additionalProperties": false
}

Validate JSON against this schema →

Generate schema from your JSON →

Array schema with item validation

{
  "type": "array",
  "items": {
    "type": "object",
    "required": ["id", "price"],
    "properties": {
      "id":    { "type": "string" },
      "price": { "type": "number", "minimum": 0 },
      "tags":  { "type": "array", "items": { "type": "string" } }
    }
  },
  "minItems": 1,
  "maxItems": 100
}

Combining schemas with oneOf

Use oneOf to allow exactly one of several shapes — useful for discriminated unions like different payment methods.

{
  "type": "object",
  "properties": {
    "payment": {
      "oneOf": [
        {
          "type": "object",
          "required": ["type", "cardNumber"],
          "properties": {
            "type":       { "const": "card" },
            "cardNumber": { "type": "string", "pattern": "^[0-9]{16}$" }
          }
        },
        {
          "type": "object",
          "required": ["type", "email"],
          "properties": {
            "type":  { "const": "paypal" },
            "email": { "type": "string", "format": "email" }
          }
        }
      ]
    }
  }
}

Keyword Reference

type

Constrains the value type. Values: "string", "number", "integer", "boolean", "null", "array", "object"

required

Array of property names that must be present in the object

properties

Defines schemas for each property of an object

additionalProperties

false disallows any properties not listed in "properties"

enum

Value must be one of the listed values

const

Value must be exactly this value

minLength / maxLength

String length constraints

pattern

String must match this regular expression

format

Semantic validation: "email", "uri", "date", "date-time", "uuid"

minimum / maximum

Numeric range constraints (inclusive)

exclusiveMinimum / exclusiveMaximum

Exclusive numeric range constraints

multipleOf

Number must be a multiple of this value

items

Schema that each item in an array must validate against

minItems / maxItems

Array length constraints

uniqueItems

true means all array items must be unique

allOf

Must be valid against ALL listed schemas

anyOf

Must be valid against AT LEAST ONE listed schema

oneOf

Must be valid against EXACTLY ONE listed schema

not

Must NOT be valid against the given schema

$ref

Reference to another schema definition (use with $defs)

JSON Schema Tools