JSON Schema Explained for Beginners (With Examples)

Suppose your API accepts a user like this:

{
  "id": 42,
  "name": "Asha",
  "email": "asha@example.com",
  "roles": ["admin", "beta"]
}

A schema for it looks like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "User",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": {
      "type": "array",
      "items": { "type": "string", "enum": ["admin", "editor", "beta"] },
      "uniqueItems": true
    }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Read it from top to bottom: the document is an object; it may have the four listed properties with the given types and limits; id, name and email must be present; and no other properties are allowed.

{
  "id": "42",
  "name": "",
  "roles": ["admin", "admin", "root"],
  "nickname": "A"
}

• id is the string "42", not an integer.
• name is shorter than minLength 1.
• email is required but missing.
• roles contains a duplicate and a value ("root") that is not in the enum.
• nickname is not allowed because additionalProperties is false.

A good validator reports all of these with the path to each problem, so the person who sent the data can fix it in one pass.

Real schemas repeat structures. Define them once under $defs and point to them with $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",
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "zip":    { "type": "string", "pattern": "^[0-9]{6}
quot; }
      },
      "required": ["street", "city"]
    }
  }
}

To express choices, use allOf (must match all), anyOf (at least one) and oneOf (exactly one). For a value that may be missing data, allow null explicitly with "type": ["string", "null"].

Python: jsonschema

# pip install jsonschema
import json
from jsonschema import Draft202012Validator

schema = json.load(open("user.schema.json", encoding="utf-8"))
data = json.load(open("user.json", encoding="utf-8"))

validator = Draft202012Validator(schema)
for error in sorted(validator.iter_errors(data), key=lambda e: [str(part) for part in e.path]):
    location = "/".join(str(part) for part in error.path) or "(root)"
    print(f"{location}: {error.message}")

JavaScript: Ajv

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

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv); // enables checks for "email", "date-time", and so on

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

Writing a large schema by hand is slow, so it is common to generate a first draft from a sample document and then edit it. A generator can see the types in your sample, but it cannot know your rules. A sample with one string field says nothing about whether the field is required, how long it may be, or whether it is really one of a fixed set of values.

1. Generate a draft from a representative sample, ideally the most complete one you have.
2. Decide which properties are truly required and remove the rest from required.
3. Add limits such as minimum, maxLength, pattern and enum where your business rules say so.
4. Set additionalProperties deliberately, false for strict inputs and the default for forward-compatible ones.
5. Test the schema against valid and invalid examples, including empty arrays, nulls and boundary values.

• API contracts. OpenAPI 3.1 uses JSON Schema to describe request and response bodies.
• Input validation. Reject bad data at the edge of your system with a clear message.
• Configuration files. Editors can use a schema to offer autocomplete and flag mistakes while you type.
• Test data and documentation. The schema is a precise, shared definition of a data format that both humans and tools can read.