Validating

Chapter 6 taught the vocabulary. This chapter is about using it in a real program: how to run a validator without making it slow, how to express "one of these shapes" and "if this, then that", how to keep a schema closed without breaking it, how to get error messages a human can act on, how to see the schema working in your editor, how to generate types and documentation from it, and how to change a schema without breaking the people who depend on it. For where a schema sits in API design (request and response contracts), see API Types & Design 4.

Run the Validator Efficiently: Compile Once

A validator library reads your schema and builds a checking function. In Ajv that step is compiling and it is expensive; running the compiled function is very cheap. I validated the six real orders, repeated to 20,000 documents:

The last row is a trap worth remembering: a schema with an $id can only be registered once per Ajv. Code that re-reads or re-creates the schema for every request will either be slow (new Ajv each time) or throw (same Ajv, new copy). Compile at start-up, keep the function, call it for every document.

Python's jsonschema has a different cost profile:

Building a Python validator is cheap, but jsonschema.validate() is the slow convenience function: it checks that the schema is valid on every call (given a broken schema it raised SchemaError, while Draft202012Validator(bad).is_valid did not check it, and a misspelt type name raised UnknownType only at use time). Build one validator object, call check_schema once when the schema loads, then call is_valid or iter_errors per document. Python was about 150 times slower per document than compiled Ajv here (62.7 versus 0.40 microseconds); that is rarely a problem unless you validate millions of documents.

Combining Schemas: allOf, anyOf, oneOf, not

The usual mistake is oneOf where anyOf was meant: if the branches overlap, a document that matches two fails. Use oneOf only when the branches are genuinely exclusive (usually because a field such as type differs). For "a string or null", prefer "type": ["string", "null"], which gives one error instead of three. All of these gave the same verdicts in Python's jsonschema.

Conditionals: if/then/else and dependentRequired

if picks a branch: when its schema passes, then must pass; otherwise else must. A UK address needs a postcode and a US address needs a state and a zip:

The last row is the if trap. {} has no country, and an if made only of properties passes when the property is absent, so the document was sent down the then branch and was also told that postcode is missing, which is a confusing message. Put "required": ["country"] inside the if so it only fires when the property is really there (the payment schema below does). Python gave the same verdicts.

Two lighter tools: dependentRequired says "if this property is present, these others must be too" ({"card": ["expiry", "cvv"]} accepted {} and a full card, rejected {"card":"4111"}; Ajv printed one message per missing property, so two lines), and dependentSchemas applies a whole schema when a property is present ({"card": {required: ["billing"], properties: {billing: {type: "object"}}}} rejected a card with no billing, and a card with billing: "no").

Closed Objects: additionalProperties versus unevaluatedProperties

additionalProperties: false means "no keys except the ones in this schema's own properties". It cannot see inside allOf. A common design, a base schema plus extras, therefore breaks:

Version A rejects every document, including the simplest valid one, because id is declared inside allOf where A's additionalProperties cannot see it. unevaluatedProperties (new in 2019-09) means "no keys that no keyword in this schema or its allOf/$ref/if branches evaluated", so B is closed and still allows both id and name. The older workaround is to repeat additionalProperties: false and every property in each branch, which I also tried: the base branch with additionalProperties: false then rejected name. unevaluatedItems is the same idea for arrays (prefixItems with unevaluatedItems: false accepted ["a"] and rejected ["a", 1]). Ajv and Python gave identical verdicts for all of these (except that the repeated-branch variant was run in Ajv only).

A caveat that I met in the payment exercise: when a then branch fails, the properties it would have evaluated count as unevaluated, so the validator also reports unevaluatedProperties errors for them. For the document {"method":"card","amount":500,"card_number":"411111111111111","expiry":"10/29"} (15 digits) Ajv listed the real error, /card_number pattern, and then two unevaluatedProperties errors that are just echoes. When you show errors to people, ignore the unevaluated ones if another error is present.

A Realistic Schema: Payments

This schema combines most of the chapter: a required core, a method-dependent part via if/then (with required inside each if), dependentRequired, and unevaluatedProperties: false so unknown fields and fields for the wrong method are rejected:

I wrote an expected verdict for each of 18 test documents (4 valid, 14 invalid) and ran them in both validators: 18 of 18 behaved as expected in each, and the two agreed on every document. Examples: a complete card payment was valid; a cash payment with a stray iban was invalid (unevaluatedProperties); a card with expiry month 13 failed the expiry pattern; an amount of 9.99 failed type (money as integer cents again); currency without amount failed both required and dependentRequired. As a control, I flipped one verdict on purpose and the comparison named exactly that case. The IBAN pattern is only a shape check (two letters, two digits, then 11 to 30 letters or digits): it does not verify the IBAN checksum, which a schema cannot do.

Error Messages People Can Use

The more flexible the schema, the noisier the errors. I took an event document that should have been a click but has x: "ten" (a string where an integer is needed), and validated it against three ways of writing "one of these three event shapes":

So for documents with a "kind" field, use if/then keyed on that field, or Ajv's discriminator option, instead of a bare oneOf: the validator then looks only at the branch that applies. The discriminator keyword is an Ajv option, not part of the JSON Schema specification, so another validator would ignore it and fall back to ordinary oneOf behaviour. In Python, the same oneOf produced a single top-level error, ... is not valid under any of the given schemas, with the per-branch errors tucked into its context (five of them); best_match returned that top-level error, not the useful one, while the if/then chain gave just ['x'] type: 'ten' is not of type 'integer'.

Two ways to make messages friendlier. Custom messages in the schema, with the ajv-errors plugin: an errorMessage keyword turned the results for {}, {qty: 1.5} and {qty: 0} into quantity is required, quantity must be a whole number and quantity must be at least 1. And a small formatter in your code; mine for Python turned the order errors into plain lines:

Group errors by path, show the path in the user's vocabulary (a form field name, not items/0/sku), and never match on message text: it differs between libraries and versions.

Schemas in the Editor

VS Code can check a JSON file against a schema as you type. You map files to a schema in settings.json with json.schemas; the VS Code documentation shows fileMatch (a list of patterns, * is supported, a leading ! excludes), a url (use a relative path such as ./order.schema.json for a workspace schema), or an inline schema instead of a url:

A file can also name its own schema with a "$schema" property (the docs call this VS Code-specific and warn it changes the file's contents, so other tools may fail validation). The documentation also says VS Code supports drafts 4 to 7 fully and has limited support for 2019-09 and 2020-12.

I did not drive the VS Code window. Instead I ran the JSON language service package that VS Code's JSON support is built on (vscode-json-languageservice 6.0.0-next.4; the JSON language server inside the VS Code 1.138.0 installed here depends on ^6.0.0-next.4) and asked it for diagnostics. That shows what the editor's engine reports, not how the squiggles look. Results with my order schema:

Three practical points. Schema problems showed as warnings (severity 2) and syntax problems as errors (severity 1). The engine understood the 2020-12 keywords I tried, even though the documentation says "limited", so test your own schema rather than assuming either way. It did not check format for the one format I tried. And a schema that closes the object with additionalProperties: false will reject the very $schema line you add to link it, so for closed schemas map files with json.schemas instead.

Generating Types and Documentation

Types. json-schema-to-typescript 16.0.0 turned the order schema into:

The $defs item became its own interface, the enum a union of strings, and the optional or open shapes differed: for the shop schema (no additionalProperties: false) each object also got [k: string]: unknown;, phone became phone?: string | null, and minItems: 1 became the tuple [Product, ...Product[]]. I then wrote a TypeScript file with eight objects and compiled it with TypeScript 7.0.2 (tsc --noEmit, strict). The compiler caught five mistakes: status: 'lost', a missing items, an extra note field on the closed order, id: '1' (a string), and an empty products list. It did not catch an order with id: 0, an empty customer, a nonsense date, sku: 'a1', qty: -3 and price: 0, because those rules (minimum, pattern, format) cannot be expressed as TypeScript types; nor an extra field on the open shop schema. Generated types describe the shape; the validator still has to run on real data.

Documentation. json-schema-for-humans 1.5.1 (generate-schema-doc --config template_name=md order.schema.json order.md) wrote a 5.4 KB Markdown page with a table of contents, one section per property and its restrictions (for id: type integer, required, minimum ≥ 1), and "Additional properties: Not allowed" for the closed object. It also marked the whole document's Required as "No" (that row is about whether the root itself is required in a larger document), which is not what a reader might expect. Other generators exist; I tested only these two.

Changing a Schema Without Breaking People

Once other programs rely on a schema, every change is a compatibility question, and there are two directions: is the new schema backward compatible (does it still accept every document that was valid under the old one, so existing data keeps working?) and is it forward compatible (does the old schema accept documents produced under the new one, so programs that have not upgraded keep working?). I tested eleven kinds of change with sample documents in both directions:

The pattern: loosening a schema (optional property, extra enum value, wider range or type) keeps old data valid but can make old readers reject new data; tightening it (required property, fewer enum values, narrower range) does the opposite. A rename is both a removal and an addition, so it breaks both directions. Keep the safe changes (adding optional properties to an open schema) for minor versions, put breaking ones behind a new version of the schema (a new $id, for example .../order/v2.json), and keep a corpus of example documents that every version must still accept. This table used a handful of sample documents per change, so it demonstrates the pattern; it is not a proof for any particular schema.

Hands-On Exercises