JSON Schema: how to describe and validate JSON

A first schema: types and properties

Start with the shape of the request: an object with a username and an age.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "age": { "type": "integer" }
  }
}

{}

$schema says which version of JSON Schema the file uses. type restricts the kind of value. The seven types are string, number, integer, boolean, object, array, and null. integer means a number with no fractional part, so 29 and 29.0 both count. properties gives a schema for each named property.

The empty object {} passes. properties only checks properties that are present; it doesn’t require any of them. That surprises almost everyone the first time, and it’s what the next keyword is for.

Required properties and extra properties

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["username", "email"],
  "properties": {
    "username": { "type": "string" },
    "email": { "type": "string" }
  },
  "additionalProperties": false
}

{
  "username": "maya_chen",
  "emial": "maya@example.com"
}

required is a list of property names, and it goes on the object, next to properties. additionalProperties: false rejects any property that isn’t listed. That catches typos like emial. Without it, emial would be accepted as an extra property, and the only clue would be that email is missing. The trade-off is flexibility: if you add a field to your API later, clients running an older schema will reject responses that include it. Many teams use false for requests they receive and leave responses open.

Rules for values

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^[a-z0-9_]+$" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 13 },
    "plan": { "enum": ["free", "pro", "team"] }
  }
}

{
  "username": "Maya Chen",
  "email": "maya@example",
  "age": 12,
  "plan": "premium"
}

Strings

minLength and maxLength count characters. pattern is a regular expression in JavaScript syntax. format names a common kind of string, such as email, date-time, date, uri, or uuid. The specification lets validators treat format as a description only, so check that yours enforces it. Ajv needs the ajv-formats package, and Python’s jsonschema needs a FormatChecker. Even then, checks differ: Python’s email check only looks for an @, so it accepts maya@, which Ajv rejects.

Numbers

minimum and maximum include the limit itself; exclusiveMinimum and exclusiveMaximum don’t. multipleOf restricts values to steps, such as 5 for items sold in packs of five. Be careful with decimal steps. Because of floating-point rounding, Ajv rejects 19.99 as a multiple of 0.01 unless you set its multipleOfPrecision option. For money, it’s simpler to store whole cents as an integer, as the JSON format guide suggests.

Fixed values

enum lists every allowed value, and const allows exactly one. Both compare the whole value, including its type, so "1" doesn’t match 1.

Arrays

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 5,
      "uniqueItems": true
    },
    "point": {
      "type": "array",
      "prefixItems": [{ "type": "number" }, { "type": "number" }],
      "items": false
    }
  }
}

{
  "tags": ["beta", "beta", 7],
  "point": [42.36, -71.06, 12]
}

items is the schema every item must match, and minItems, maxItems, and uniqueItems limit the list as a whole. For a fixed-length list where each position means something different, such as a latitude and longitude pair, use prefixItems with one schema per position, and set items: false to forbid anything after them. Draft-07 wrote this as an array under items plus additionalItems.

Reusing definitions with $defs and $ref

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "billing": { "$ref": "#/$defs/address" },
    "shipping": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": { "type": "string", "minLength": 2, "maxLength": 2 }
      }
    }
  }
}

{
  "billing": { "street": "1 Main St", "city": "Boston", "country": "US" },
  "shipping": { "street": "9 Elm St", "country": "USA" }
}

Put shared pieces under $defs and point to them with $ref. The value is a JSON Pointer into the schema, so #/$defs/address means “the address definition in this file”. Errors are reported at the place the data sits, here /shipping, so you can tell the two addresses apart. Older schemas use definitions instead of $defs; it works the same way. A $ref can also point to another file or URL, but that needs a validator that loads them. The JSON Tidy validator only follows references inside the schema.

Combining schemas: anyOf, oneOf, allOf, and if/then

anyOf: at least one must match

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "phone": { "type": "string" }
  },
  "anyOf": [
    { "required": ["email"] },
    { "required": ["phone"] }
  ]
}

{ "name": "Maya" }

oneOf: exactly one must match

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    { "type": "number" },
    { "type": "integer" }
  ]
}

5

This is the most common trap with oneOf. Use it only when the options can’t overlap, for example objects told apart by a "type" field with different const values. Otherwise use anyOf. allOf requires every listed schema to match, which is useful for combining a shared base with extra rules.

if, then, and else

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "properties": { "country": { "const": "US" } },
    "required": ["country"]
  },
  "then": {
    "properties": { "postalCode": { "pattern": "^[0-9]{5}$" } }
  }
}

{ "country": "US", "postalCode": "SW1A 1AA" }

Include required in the if schema. Without it, an object with no country at all would match the condition, because properties ignores missing properties.

Allowing null

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "middleName": { "type": ["string", "null"] }
  }
}

{ "middleName": null }

To allow a value or null, list both types. OpenAPI 3.0 used nullable: true instead, which isn’t part of JSON Schema. OpenAPI 3.1 uses JSON Schema directly.

Validating in code

In JavaScript, Ajv is the most widely used validator. Its default import supports draft-07, so import the 2020-12 build for newer schemas, and add ajv-formats so that format is checked:

import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);

const validate = ajv.compile(schema);
if (!validate(data)) {
  console.log(validate.errors);
}

Compile each schema once and reuse the function, since compiling is the slow part. allErrors reports every problem instead of stopping at the first. In Python, use the jsonschema package:

from jsonschema import Draft202012Validator, FormatChecker

validator = Draft202012Validator(schema, format_checker=FormatChecker())
for error in validator.iter_errors(data):
    print(error.json_path, error.message)

Common mistakes

Putting required inside a property

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "email": { "type": "string", "required": true }
  }
}

{}

"required": true inside a property is the old draft-03 style. In current drafts, required must be a list on the parent object, so newer validators reject this schema, and older ones ignore it and require nothing.

Expecting pattern to match the whole string

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string",
  "pattern": "[0-9]{5}"
}

"Zip code: 02108, Boston"

A pattern passes if it matches anywhere in the string. Wrap it in ^ and $ to match the whole value: "^[0-9]{5}$". See regular expressions in JSON Schema.

Using additionalProperties with allOf

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "allOf": [
    { "properties": { "username": { "type": "string" } } }
  ],
  "properties": { "age": { "type": "integer" } },
  "additionalProperties": false
}

{ "username": "maya_chen", "age": 29 }

additionalProperties only knows about the properties next to it, not those inside allOf or a $ref. In draft 2019-09 and later, use unevaluatedProperties: false, which accounts for every part of the schema. Open the fixed version.

Misspelled keywords

Validators ignore keywords they don’t recognize, so "minLenght": 3 does nothing and no error appears. Ajv’s strict mode, which is on by default in code, reports unknown keywords. Turn it on in tests even if you turn it off in production.

Which draft to use

Use draft 2020-12, the current version, for new schemas. Draft-07 is still common in older projects and tools. The differences that matter most are $defs instead of definitions, prefixItems for fixed-length arrays, and unevaluatedProperties. OpenAPI 3.1 uses draft 2020-12; OpenAPI 3.0 uses its own variant of an older draft.

Frequently asked questions