What Is JSON Schema?

Valid JSON and JSON with the right shape are two different questions — {"age": "thirty"} parses just fine, even though age was supposed to be a number. JSON Schema is how you write down what "the right shape" means, so a machine can check it instead of you eyeballing every field by hand.

The short definition

JSON Schema is a specification for describing the structure of JSON data — what fields are allowed, which are required, what type each one must be, and constraints beyond type (a string's length, a number's range, an allowed set of values). It's maintained at json-schema.org, and — fittingly — a schema is itself written as JSON.

A minimal example

This schema describes an object with a required string and an optional number:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

{"name": "Ada"} satisfies it — age is optional. {"name": "Ada", "age": -1} fails on minimum. {"age": 30} fails because name, the only entry in required, is missing.

The keywords that come up constantly

• type — string, number, integer, boolean, null, object, or array. Can also be an array of types — ["string", "null"] means "a string, or explicitly null."
• required — a list of property names, and it lives next to properties, not inside each one. There's no "required": true flag on an individual property.
• additionalProperties — defaults to true. Schemas are permissive by default; an object can have fields you never described unless you explicitly set this to false.
• String constraints — minLength/maxLength, pattern (a regex), and format (email, date-time, uri, and others — technically advisory in the spec, but enforced by most real-world validators).
• Number constraints — minimum/maximum, and their exclusive variants.
• enum — an exact list of allowed values, for anything from a status field to a fixed set of category names.
• oneOf / anyOf / allOf — combine schemas: exactly one must match, at least one must match, or every one must match, respectively — for fields that can legitimately take more than one shape.

Which draft?

JSON Schema has gone through several versions — Draft-04 through Draft-07, then a switch to date-based names: 2019-09, and the current 2020-12. Draft-07 is still extremely common in the wild (npm's own package.json schema, most VS Code settings schemas), while 2020-12 is what new schemas should target — the most visible difference being tuple-style array validation: Draft-07 uses an items array, 2020-12 splits that into prefixItems plus a separate items for anything beyond the tuple. Most validators, including this site's, support both.

Where you'll run into it

Beyond validating API payloads directly, JSON Schema quietly powers a lot of editor and tooling features: VS Code's autocomplete and inline errors for package.json, tsconfig.json, and countless other config files come from a JSON Schema behind the scenes, via the SchemaStore registry. It's also the foundation OpenAPI request/response bodies are described with — OpenAPI 3.0 used a JSON-Schema-like subset with its own quirks (a nullable: true flag that isn't part of JSON Schema at all), while OpenAPI 3.1 dropped that in favor of full JSON Schema 2020-12 compatibility, including the real type: ["string", "null"] form.

Common mistakes worth avoiding

• Putting required inside a property instead of as a top-level array of names. A property-level "required": true is simply not a JSON Schema keyword — it's silently ignored, not an error, which makes this mistake easy to miss.
• Assuming extra fields are rejected by default. They're not — leave off additionalProperties: false and a typo'd field name will pass validation instead of getting caught.
• Forgetting format needs a validator that enforces it. The JSON Schema spec itself treats format as an annotation, not a hard constraint — some validators check it by default, others require an explicit opt-in (an extra library, a strict-mode flag), so "my email field accepted garbage" is often a validator-configuration issue, not a schema bug.

For schemas covering more real-world shapes — nested objects, arrays, enums, polymorphic oneOf fields — see JSON Schema Examples.

Try it yourself

Already have a schema? JSON Schema Validator checks data against it (Draft-07 or 2020-12) and reports every failing rule with its exact path. Don't have one yet? JSON Schema Generator writes a first draft from a sample JSON document. Both run entirely in your browser.