A practical, hands-on guide to JSON Schema — what it is, how to write one, and how to validate documents locally in your browser.

JSON tells you whether a document is well-formed. It does not tell you whether the document is meaningful — whether age is a number, whether email looks like an email, whether required fields are present. JSON Schema is the standard way to express those expectations and check them automatically. This guide walks through writing a schema and validating documents against it.

What is JSON Schema?

A JSON Schema is itself a JSON document. It describes the shape of another JSON document: which keys must be present, what types they must have, what ranges are allowed, what format strings should match. Once you have a schema, any validator can check a JSON document against it and tell you exactly where and why it fails.

JSON Schema is widely used in OpenAPI/Swagger (REST API contracts), JSON-RPC, configuration validation (for example, VS Code settings.json), and data pipelines. Knowing how to read and write it is one of the highest-leverage skills in modern API development.

A minimal example

Here is a tiny JSON document and a schema that constrains it.

The document

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "role": "admin"
}

The schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "name", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "type": "string", "enum": ["admin", "user", "guest"] }
  },
  "additionalProperties": false
}

This schema says:

the document must be an object;
id, name, and email are required;
id is a positive integer, name is a non-empty string, email is a string that looks like an email;
role, if present, must be one of admin, user, or guest;
no other properties are allowed (additionalProperties: false).

You can paste both into our JSON Schema Validator and try modifying the document — change role to "superuser" or remove email to see what the errors look like.

The most useful keywords

type — object, array, string, number, integer, boolean, null. A value can have multiple allowed types if you use an array.
required — an array of property names that must be present. (Note: a property listed here must exist; whether it can be null depends on its own type.)
properties — schemas for each named key. Optional by default; combine with required to force presence.
enum / const — restrict to a fixed set of values or a single value.
minimum / maximum — numeric bounds. minLength / maxLength — string length bounds.
pattern — a regex the string must match.
format — semantic formats like email, date-time, uri, uuid, ipv4. Whether these are enforced depends on the validator; Ajv enforces them when ajv-formats is loaded (it is, in our validator).
items / prefixItems — schemas for array elements (homogeneous vs positional).
oneOf / anyOf / allOf — combine schemas for unions and intersections.
$ref — reference another schema (in the same document or externally) for reuse.

Which draft should I use?

The current draft is 2020-12. Always set "$schema" at the top of your document to declare which draft you target — validators behave differently across drafts. Older drafts (draft-07, draft-04) are still common in existing schemas and mostly work with modern validators, but for new schemas, default to 2020-12.

How validation works under the hood

Most JavaScript projects use Ajv, which compiles schemas into fast validator functions. Our online validator runs Ajv in your browser — the same engine, just packaged for the web. That means your schemas and documents never leave your device, which matters because schemas often describe the shape of sensitive internal data.

Common pitfalls

Forgetting that required does not forbid null. A field listed in required must be present, but if its type does not exclude null, a null value passes. Add "type": ["string", "null"] or forbid null explicitly.
Assuming format is enforced. Some validators only check format as a hint by default. Ajv enforces it when ajv-formats is registered — ours is.
Using additionalProperties: false incorrectly. It applies to properties not listed in properties, so if you forget to declare a property, valid data will fail.
Mixing drafts. $ref resolution differs across drafts. Pick one and stick to it.

JSON Formatter

How to validate JSON against a JSON Schema