How To Write Json Schemas

A minimal schema

JSON Schema is how you describe the shape of JSON data so machines can validate it, humans can understand it, and APIs can generate docs and clients from it. Write a schema once and you get validation, auto-completion, fixture generation, and contract tests for free. This guide covers the core keywords (type, properties, required, additionalProperties), the composition patterns (allOf, oneOf, $ref), how drafts differ, when to reach for JSON Schema vs alternatives (OpenAPI, Zod, TypeBox), and the common mistakes that let invalid data slip through.

Core types

String constraints

Number constraints

Object constraints

Array constraints

Composition

$ref — reusable pieces

Drafts matter

Conditional schemas — if/then/else

JSON Schema vs alternatives

Tooling

Common mistakes

Run the numbers