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. For the mechanics underneath — schema reuse, recursive schemas, conditional rules — see JSON Schema Validation Explained. For complete, verified schemas for common real forms and requests, see JSON Schema for User Registration, JSON Schema for Login Forms, JSON Schema for API Requests, and JSON Schema for Product Catalogs.

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.