JSON Schema tutorial

October 23, 2026 · 15 min read

JSON Schema is a vocabulary for describing valid JSON documents: which keys exist, their types, string formats, numeric ranges, and nested object shapes. Teams use it for OpenAPI request bodies, config linting, and CI gates before bad payloads hit production. This tutorial covers draft-07 style basics you can apply immediately.

What JSON Schema is

A schema is JSON describing rules for instance JSON. Validators walk the instance and emit errors with JSON Pointer paths like /items/2/price. Unlike informal README examples, schemas are machine-checkable and composable with $ref across files.

Types and simple constraints

The type keyword accepts string, number, integer, boolean, object, array, and null. Strings add minLength, maxLength, pattern, and format (email, uuid, date-time). Numbers use minimum, maximum, and multipleOf.

{
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "active": { "type": "boolean" },
    "score": { "type": "integer", "minimum": 0, "maximum": 100 }
  },
  "required": ["id", "active"]
}

Properties, required, and additionalProperties

properties maps field names to subschemas. required lists keys that must be present - absence fails validation even if the key is listed in properties. Set additionalProperties": false when unknown keys should be rejected (common for strict public APIs).

Combining schemas with allOf and oneOf

allOf - instance must satisfy every subschema (layer base + extensions).
anyOf - at least one subschema passes.
oneOf - exactly one must pass (good for discriminated unions).
$ref - reuse definitions from #/definitions/User or external files.

Validation workflow in development

Author schemas beside OpenAPI or in a schemas/ directory, validate fixtures in CI with ajv or similar, and paste failing webhook bodies into the JSON validator for syntax before schema errors confuse the picture. Use the JSON formatter to normalize indentation during review.

FAQ

Which JSON Schema draft should I use?: OpenAPI 3.0 often references draft-05/07; OpenAPI 3.1 aligns with 2020-12. Pick one draft per repo and pin validator settings.
Does required allow null values?: required only means the key must exist. Allow null with type: ["string", "null"] if needed.
Can I validate arrays of objects?: Yes. Use items with an object subschema or tuple validation with items as an array of schemas.
Is JSON Schema the same as TypeScript types?: Similar goals, different runtimes. You can generate one from the other with tools, but they are not interchangeable.

Browse all tools