JSON Schema validation: common keywords with examples

JSON Schema is a vocabulary for describing and validating JSON documents. An API can use one schema to check incoming requests, generate forms, or document its payloads. This reference covers the keywords used most often, each with a working example. Examples follow the 2020-12 specification; most also work in draft-07.

A schema is itself JSON. The $schema keyword declares which specification version it uses:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Product",
  "type": "object"
}

The core keywords

Keywords

Keyword	Applies to	What it checks
type	any	The JSON type: string, number, integer, boolean, object, array, null
required	object	Named properties that must be present
properties	object	A schema for each named property
additionalProperties	object	Whether extra properties beyond the named ones are allowed
minLength, maxLength	string	String length in characters
pattern	string	The string matches a regular expression
format	string	A known shape such as email, date, uri (annotation only in many validators)
minimum, maximum	number	Inclusive numeric bounds (exclusiveMinimum / exclusiveMaximum for strict)
enum	any	The value is one of a fixed list
const	any	The value equals exactly one given value
items	array	A schema that every element must match
minItems, maxItems	array	Array size bounds
uniqueItems	array	No two elements are equal
$ref	any	Reuse another schema by URI
oneOf, anyOf, allOf	any	Combine schemas: exactly one, at least one, or all must match

A complete example

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Product",
  "type": "object",
  "properties": {
    "productId": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1, "maxLength": 100 },
    "price": { "type": "number", "exclusiveMinimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "status": { "enum": ["draft", "live", "archived"] }
  },
  "required": ["productId", "name", "price"],
  "additionalProperties": false
}

This passes validation:

{ "productId": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"] }

This fails three rules: price is not above zero, tags has a duplicate, and colour is not a declared property:

{ "productId": 1, "name": "A green door", "price": 0, "tags": ["home", "home"], "colour": "green" }

Combining schemas

allOf: every listed schema must match. Used to layer constraints.
anyOf: at least one must match. Used for "string or number" fields.
oneOf: exactly one must match. Stricter than anyOf; useful for mutually exclusive shapes.

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

Reusing definitions with $ref

Define a piece once under $defs and point at it:

{
  "$defs": {
    "positiveInt": { "type": "integer", "minimum": 1 }
  },
  "type": "object",
  "properties": {
    "quantity": { "$ref": "#/$defs/positiveInt" },
    "reorderLevel": { "$ref": "#/$defs/positiveInt" }
  }
}

Practical notes

A property that is absent is not checked by properties; only required forces presence.
format (email, date-time, uri) is an annotation in the 2020-12 spec by default: validators may report it but are not required to reject bad values unless format assertion is enabled.
Validation only checks shape and values. It does not check that an id exists in a database or that a price is correct.
Test a schema with a validator in your language (for example Ajv for JavaScript or the jsonschema package for Python) before relying on it in production.

Source: JSON Schema documentation at https://json-schema.org/learn/getting-started-step-by-step and the 2020-12 specification, https://json-schema.org/draft/2020-12/json-schema-core

Suggest an edit