devtools.codes

How to validate JSON against a schema

Your tool input is processed locally in your browser and is not intentionally uploaded to our servers. Advertising and analytics providers may still process normal page, device, cookie and network information.

JSON Schema validation answers one question: does this document satisfy the contract. The useful part is not the yes or no, but the explanation when the answer is no.

Every validation error has three components worth reading. The property path tells you where in the document the problem is, written as a pointer like /items/0/name. The keyword tells you which constraint was not met — type, required, enum, additionalProperties. The actual value tells you what was there instead. An error missing any of the three is hard to act on.

A handful of keywords do most of the work in practice. The type keyword catches the string-where-a-number-was-expected case. The required array catches missing fields. The enum keyword constrains a value to a fixed set, which is the single most effective way to stop a model inventing a category. And additionalProperties set to false catches fields nobody declared.

Validate the schema itself before blaming the document. A schema with a typo in a keyword name often still compiles and simply fails to constrain anything, so everything passes and you conclude the validation is working. Compiling the schema separately from validating the document distinguishes the two failures.

Where validation runs matters as much as whether it runs. Validating in the browser means the schema and the document never leave the machine, which matters when the document is a customer record or the schema describes something unreleased. It also means you can check a payload without waiting for a deployment.

One caveat on drafts: JSON Schema has several, and they differ in ways that occasionally matter. Draft 2020-12 is the current default and the one most provider tool-definition formats expect. If your schema declares a $schema keyword, whatever validator you use should respect it.

More on how to validate JSON against a schema

What does a property path like /items/0/name mean?

It is a JSON Pointer, read left to right as a route through the document. Start at the root, take the items property, take the element at index zero, take its name property. That is the exact location the constraint failed at. Indexes are zero-based, so /items/0 is the first element rather than the second.

Which JSON Schema draft should I use?

Draft 2020-12 unless something forces otherwise. It is the current default and the one most provider tool-definition formats expect. Mixing drafts is where surprises come from: a keyword that constrains in one draft may be ignored in another, so a schema that appears to validate can in fact be constraining nothing.

My schema passes everything. What is wrong?

Almost always a keyword that is not doing what you think. A misspelled keyword is not an error in JSON Schema, it is an unknown annotation that is silently ignored, so the constraint simply is not there. Compile the schema on its own first, then deliberately validate a document you know should fail.

The tool behind this, and related guides