JSON Schema Examples: Practical Patterns for Validation

JSON Schema in one minute

JSON Schema describes allowed shape and rules for JSON data. Syntax-only checks (balanced braces, valid strings) answer “is this JSON?”; schema validation answers “does this JSON match our contract?”

This guide uses examples compatible with Draft 2020-12 (see the $schema meta-schema). The vocabulary is stable across many stacks; always pin the draft your validator uses.

If you are new to JSON itself, start with What is JSON?.

Minimal object schema

Schema — require name (string) and age (integer), optional tags:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/person.min.json",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["name", "age"]
}

Valid instance

{ "name": "Asha", "age": 30, "tags": ["beta"] }

Invalid instance (missing age, and extra is forbidden by additionalProperties: false)

{ "name": "Asha", "extra": true }

Strings: length, pattern, and format

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "handle": { "type": "string", "pattern": "^[a-z0-9_]{3,20}$" },
    "contact": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["handle"]
}

Tip: format is an annotation in the core spec; validators like Ajv enable formats via plugins. Treat format as documentation unless your runtime turns it on.

Numbers: bounds and multiples

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "qty": { "type": "integer", "minimum": 1, "maximum": 99 },
    "price": { "type": "number", "minimum": 0, "multipleOf": 0.01 }
  },
  "required": ["qty", "price"]
}

Use integer when you mean whole units; use number for decimals or scientific values.

enum and const

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
    "version": { "const": 1 }
  },
  "required": ["role", "version"]
}

Arrays: items, bounds, uniqueness

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ids": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["ids"]
}

anyOf, oneOf, and allOf

anyOf — at least one branch must match (good for “string or number”):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "value": {
      "anyOf": [
        { "type": "string", "minLength": 1 },
        { "type": "number" }
      ]
    }
  },
  "required": ["value"]
}

oneOf — exactly one branch (watch overlaps: two branches that both match will fail validation).

allOf — merge constraints from every subschema (common for “base type + extensions”).

Reuse with $defs and $ref

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Email": { "type": "string", "format": "email" }
  },
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "owner": { "$ref": "#/$defs/Email" },
    "billing": { "$ref": "#/$defs/Email" }
  },
  "required": ["owner"]
}

additionalProperties and API contracts

Setting additionalProperties: false on the root object catches typos like naem vs name. Pair it with explicit properties and required for public APIs.

Common mistakes

• • $ref targets a URI fragment; typos in $defs keys or draft differences break resolution.

• • null is not implied; allow null with { "type": ["string", "null"] } or nullable patterns per your draft/tooling.

• • oneOf with overlapping numeric ranges causes “valid against more than one branch” errors.

• • integer vs number: decimals fail integer even when mathematically whole in floating point.

Try it in JSON Work

• • Paste a schema and payload into the JSON Validator to see validation errors in the browser (local processing).

• • Explore JSON to Schema when you have sample JSON and want a first-pass schema to refine.

For production pipelines, libraries such as Ajv (JavaScript) or jsonschema (Python) are common; always align library draft support with your $schema URL.