Guide
What Is JSON Schema?
JSON validates as syntax, but syntax does not tell you whether a payload has the fields your app needs. JSON Schema fills that gap. It is a way to describe the expected shape of JSON and then check real data against that description. This guide introduces it without assuming prior exposure.
Syntax validity is not enough
Consider an endpoint that expects a user with a numeric id and a string email. This payload is perfectly valid JSON:
{ "id": "not-a-number", "emial": "ada@example.com" }It parses without error, but id is a string instead of a number and email is misspelled as emial. A parser is happy. Your app is not. JSON Schema catches exactly this kind of problem by describing what the data should look like and validating against it.
A schema is itself JSON
A JSON Schema is a JSON document that describes another JSON document. Here is a schema for that user:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": { "type": "integer" },
"email": { "type": "string", "format": "email" }
},
"required": ["id", "email"]
}It says the value is an object, id must be an integer, email must be a string, and both are required. Run the earlier payload against this schema and validation fails on two counts: id is the wrong type, and the required email key is missing.
The keywords you meet first
- type: the expected type, such as object, array, string, integer, number, boolean, or null.
- properties: the schema for each key of an object.
- required: the list of keys that must be present.
- items: the schema every element of an array must match.
- enum: a fixed set of allowed values.
- format: an extra hint like email, date-time, or uri on top of a string type.
There are many more, covering things like minimum and maximum, string patterns, and conditional rules, but these six carry most everyday schemas.
What the draft version means
JSON Schema is a standard that has evolved through numbered drafts. Draft 2020-12 is the current one, and the $schema line at the top of a schema declares which draft it uses. You mostly need to know this so a validator interprets your schema with the right rules. Most tools default to a recent draft, and 2020-12 is a safe modern choice.
Where a schema earns its keep
- Validating incoming requests at an API boundary so bad data is rejected early with a clear reason.
- Documenting the exact shape of a config file or payload, in a form that tools can check rather than prose that goes stale.
- Generating types and validators in your language from a single source of truth.
A quick way to start is to infer a schema from a sample payload and then tighten it. Paste representative JSON into the schema tool to get a draft 2020-12 schema, then add required fields and constraints by hand.
FAQ
How is JSON Schema different from validating JSON?
Validating JSON checks that the text is well-formed and will parse. JSON Schema checks that the data has the expected fields, types, and constraints. One is about syntax, the other about meaning.
Is a JSON Schema written in JSON?
Yes. A schema is itself a JSON document, which means the same tools that read JSON can read and produce schemas.
Which draft should I use?
Draft 2020-12 is the current version and a safe default. The $schema keyword at the top of your schema declares which draft a validator should apply.