Schema Basics

Until now JSON has been "whatever the sender produced". That works until a field is missing, a number arrives as a string, or a price is zero, and the failure shows up three steps later in code that trusted the data. JSON Schema is a standard way to write down what a valid document looks like, as JSON, so a program can check it. A schema is a contract: it can reject bad input at the door, document an API for humans, and feed editors and code generators. This chapter covers the vocabulary of the current version, the defaults that surprise people, how to write a schema for a real API response, and how to read a validator's error output. The next chapter covers validators in more depth (combining schemas, conditionals, editor integration).

What a Schema Is For

• Validation: "is this document acceptable?" with a list of exactly what is wrong. This is the main use, in API servers, config loaders and data pipelines.
• Documentation: a schema says which fields exist, their types, their limits and which are required, in a form tools can read.
• Tooling: editors can offer completion and red squiggles from a schema, and some tools generate types or forms from one (Chapter 7).

What a schema does not do: it does not change the data (it will not turn "1" into 1), it does not check things that need other data (is this customer id in the database?), and it does not make a bad design good. It answers one question, "is this JSON the right shape?".

Your First Schema

A schema is itself a JSON document, usually an object, made of keywords. Each keyword adds one rule, and a document is valid only if it passes all the rules. Here is a schema for one product from shop.json:

Read it as a list of conditions. It must be an object. If it has sku, that must be a string like A1; if it has stock, an integer of zero or more; and four properties must be present. The $schema line says which version of the standard the schema is written for (see "Versions" below).

The Core Keywords

I tested every keyword below in both validators with documents that should pass and fail; where a cell shows a result, both gave it unless noted.

Two more building blocks need no keyword at all: an empty schema {} accepts everything (I fed it a number, a string, null, an array and an object), and a schema can be just true (accept everything) or false (reject everything). false is useful as items: false or additionalProperties: false.

Defaults That Surprise People

• Nothing is required unless you say so. properties only describes keys that are there; an object with none of them still passes. Add required.
• Extra properties are allowed. In my shop test, adding an unknown top-level field to a valid document left it valid. Add additionalProperties: false only when you really want a closed shape, and read the Chapter 7 warning before combining it with allOf.
• Keywords are ignored for the wrong type. {"required": ["a"]} alone rejected {} but accepted [] and "x", because required only applies to objects. State the type too: {"type":"object","required":["a"]} rejected all three.
• Integers are about value, not spelling. The JSON text 1.0 and 1e2 are valid integers; true is not an integer, in either validator. (In Node, JSON.parse("1.0") is already the number 1, so the JavaScript side cannot even see the difference.)
• pattern is not anchored. "[0-9]" accepted "a1". Write ^...$ when the whole string must match. In JSON text a backslash in a pattern is doubled ("^[0-9]+\\.[0-9]{2}$" is the regular expression ^[0-9]+\.[0-9]{2}$).
• Unknown keywords are ignored, silently, by default. Python's jsonschema returned valid for {"type":"object","foo":1}, so a typo such as "requird" is not an error. See "Strictness" below.

format: Often Not Checked

format names a common pattern (date, date-time, email, uuid, uri and others). In the 2020-12 specification it is an annotation by default: a validator is allowed to ignore it, and the validators I ran did. The same string "2026-13-45" against {"type":"string","format":"date"}:

So the same schema can accept a nonsense date in one program and reject it in another. If you rely on format, turn format checking on explicitly (Ajv: add ajv-formats; Python: pass a FormatChecker), and for anything critical add a pattern as well. I only tested date; which other formats a checker supports depends on the library and on extra packages. The January 2025 post on json-schema.org says the planned next specification will make format validate by default (see "Versions").

$schema, $id, $defs and $ref

Repeating the same sub-shape (an order's items) in several places invites mistakes. Put it under $defs once and point to it with $ref. The pieces:

• $schema: which version of the rules this document uses. Include it. Python's validators.validator_for(schema) picked Draft202012Validator from it. In Ajv, the class you choose must match: the default new Ajv() failed on a 2020-12 schema with no schema with key or ref "https://json-schema.org/draft/2020-12/schema"; use require('ajv/dist/2020').
• $id: the schema's own URI (it does not need to exist online). Other schemas refer to it. In Ajv, a schema added with addSchema under its $id could be referenced from another schema, and an unknown id gave can't resolve reference https://example.com/nope.json from id #.
• $defs: a place for named sub-schemas. {"$ref": "#/$defs/item"} means "the schema at that path in this document". A missing target gave can't resolve reference #/$defs/missing from id # at compile time.
• $anchor: a plain-name target: a definition with "$anchor": "num" was reachable as "$ref": "#num" (tested in Ajv).
• Recursion is allowed: a node definition whose children are $ref: "#/$defs/node" validated a three-level tree and rejected a leaf missing name (tested in Ajv).
• Siblings of $ref are allowed since 2019-09: {"$ref": "#/$defs/n", "minimum": 10} where n is an integer rejected 5 (the sibling applied) and "x", and accepted 15 (the same in both validators). Older drafts ignored siblings of $ref.

A Schema for a Real API Response

Here is a schema for the order documents from Chapter 5, using $defs for the item shape and enums for the status. It is the schema used for every test in this chapter:

All six real orders from Chapter 5 validated in both validators, including order 4, which has an empty items list (the schema has no minItems, so empty is allowed; that is a design choice you make deliberately). Then I ran 14 test documents through both validators and compared their answers. The results, as Ajv reported them (keyword at path):

The two validators agreed on the verdict and on the keyword and path of every error in all 14 cases; the only differences are wording (below). As a check on the comparison, I deleted one Python result on purpose and the comparison reported exactly that case.

Reading Validator Output

A validator gives you either a yes/no or a list of error records. Each record answers four questions: where in the document, which rule, why, and where in the schema. For the "everything wrong" document:

• Ajv stops at the first error by default. With allErrors: false it reported one error; with allErrors: true it found all seven. Use allErrors: true to show a user everything at once (I did not measure how much slower it is, and I did not check Ajv's own advice about using it on untrusted input).
• Each Ajv error is an object with instancePath ("/items/0/sku", a JSON Pointer: Chapter 8), schemaPath ("#/$defs/item/properties/sku/pattern" style), keyword, params (for example {"additionalProperty":"note"}) and message. The root of the document is the empty string "".
• Python: iter_errors(doc) yields every error; validate(doc) raises the first one (for this document "0 is less than the minimum of 1"), and jsonschema.exceptions.best_match(errors) picked additionalProperties. Different tools can pick a different "first" error, so do not build logic on which one comes first. Each error has .path (a list such as ['items', 0, 'sku']), .validator (the keyword), .message and .schema_path.
• Messages differ (Ajv: must be >= 1; Python: 0 is less than the minimum of 1), so match on keyword and path, never on message text.

Strictness: Typos in Schemas

A schema with a mistake in it can silently validate nothing. The two libraries guard against that differently:

The habit: always call check_schema in Python (or compile in Ajv) when a schema loads, and keep a test with one valid and one invalid document for every schema, so a typo shows up as a test that no longer fails.

Two Number Pitfalls

multipleOf with a decimal fails on valid prices. I checked multipleOf: 0.01 in both validators:

19.99 and 0.07, perfectly good prices, were rejected: they are not exact multiples of 0.01 in binary floating point (this is the same cause as 0.1 + 0.2 in Chapter 3). So avoid multipleOf with a fraction. Send money as integer cents ("type": "integer", which is exact) or as a string with a pattern.

Large and precise numbers. A schema validates what the parser produced, so the JavaScript problem from Chapter 1 applies: a 20-digit id arrives in Node as an already-rounded number, and the schema sees the rounded one. A schema cannot detect digits that the parser lost before validation.

Versions: Which Draft?

JSON Schema is published as dated drafts. From json-schema.org's specification links page: Draft 4 (31 January 2013), Draft 6 (21 April 2017), Draft 7 (19 March 2018), 2019-09 (17 September 2019) and 2020-12, published 16 June 2022, which the site calls "the current version" and which is the newest published one. The meta-schema URI is https://json-schema.org/draft/2020-12/schema (I fetched it; the server returned it as application/schema+json).

The "v1" release. The project has been working on a new, more stable release with strict compatibility rules. A January 2025 post on json-schema.org describes the upcoming release as breaking some things in 2020-12 ("format will validate by default", extra data needs an x- prefix, $dynamicRef is separated from $ref), says it was "really close", and gives no date. As of 2026-10-12 I could not find a published v1: the specification page and the specification-links page list 2020-12 as newest, and a "v1/2026" address mentioned in the project's process document returned a 404 when I requested it. So write for 2020-12, say so in $schema, and re-check the site before assuming anything else. Differences you may meet between drafts in older material: items as an array (replaced by prefixItems in 2020-12), definitions instead of $defs, dependencies split into dependentRequired and dependentSchemas, and siblings of $ref ignored before 2019-09. I did not test any draft older than 2020-12.

Hands-On Exercises