JSON Schema validation: common keywords with examples

JSON Schema validation: common keywords with examples

json-schema, programming, data

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
KeywordApplies toWhat it checks
typeanyThe JSON type: string, number, integer, boolean, object, array, null
requiredobjectNamed properties that must be present
propertiesobjectA schema for each named property
additionalPropertiesobjectWhether extra properties beyond the named ones are allowed
minLength, maxLengthstringString length in characters
patternstringThe string matches a regular expression
formatstringA known shape such as email, date, uri (annotation only in many validators)
minimum, maximumnumberInclusive numeric bounds (exclusiveMinimum / exclusiveMaximum for strict)
enumanyThe value is one of a fixed list
constanyThe value equals exactly one given value
itemsarrayA schema that every element must match
minItems, maxItemsarrayArray size bounds
uniqueItemsarrayNo two elements are equal
$refanyReuse another schema by URI
oneOf, anyOf, allOfanyCombine 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