JSON Schema: Validating the Shape of Your Data

← All guides

Plain JSON parsing answers one question: is this text well-formed? It does not tell you whether the data is correct — whether age is a number, whether email is present, or whether status is one of your allowed values. JSON Schema fills that gap. It is a standard, itself written in JSON, for describing the expected shape of a JSON document so you can validate data automatically.

Why you need it

As soon as JSON crosses a boundary — between a client and a server, between two services, or in and out of a database — you are trusting that the other side sent what you expect. A schema turns that trust into an enforceable contract. It lets you reject bad data early with a clear error, generate documentation and types, and keep producers and consumers in sync as an API evolves.

A first schema

Suppose this is the data you expect:

{
  "id": 42,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "roles": ["admin", "editor"]
}

A schema describing it looks like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer" },
    "name":  { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Read it top to bottom: the document must be an object; each named property has its own type rules; id, name and email must be present; and additionalProperties: false forbids any field not listed.

The core keywords

• type — one of string, number, integer, boolean, object, array, null.
• properties — describes each key of an object.
• required — an array of keys that must be present.
• items — the schema every element of an array must satisfy.
• enum — restricts a value to a fixed set of allowed options.
• additionalProperties — whether unlisted keys are allowed.

Constraints for each type

Beyond the type, you can tighten the rules. Strings support minLength, maxLength, pattern (a regular expression) and format (email, date-time, uri, uuid and more). Numbers support minimum, maximum and multipleOf. Arrays support minItems, maxItems and uniqueItems.

{
  "type": "object",
  "properties": {
    "status": { "enum": ["active", "paused", "closed"] },
    "age":    { "type": "integer", "minimum": 0, "maximum": 130 },
    "tags":   { "type": "array", "uniqueItems": true }
  }
}

Nested objects and arrays of objects

Schemas nest exactly the way data does. To validate an array of order objects, put an object schema inside items:

{
  "type": "object",
  "properties": {
    "orders": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "sku":   { "type": "string" },
          "qty":   { "type": "integer", "minimum": 1 },
          "price": { "type": "number", "minimum": 0 }
        },
        "required": ["sku", "qty"]
      }
    }
  }
}

How validation runs in practice

You rarely validate by hand. Instead you use a library: ajv in JavaScript, jsonschema in Python, everit in Java, and many others. They take your schema and a document and return either "valid" or a list of precise errors — which field failed and why. This is ideal for validating incoming API requests in middleware before your business logic ever runs.

Tips for writing good schemas

• Start permissive, then tighten. Add required and additionalProperties: false once you are confident about the shape.
• Use $ref to reuse sub-schemas (e.g. a shared address definition) instead of repeating yourself.
• Keep the schema in version control next to the code that uses it, so they evolve together.
• Use enum for status fields — it documents the allowed values and catches typos.

Frequently asked questions

Is JSON Schema part of JSON?

No. JSON Schema is a separate specification that happens to be written in JSON. Plain JSON has no built-in validation; JSON Schema is the most widely adopted way to add it.

Which draft of JSON Schema should I use?

Draft 2020-12 is the current standard and what new projects should target. Older drafts (draft-07 in particular) are still common because many libraries support them well — check what your validator supports.

Can JSON Schema generate TypeScript types?

Yes. Tools like json-schema-to-typescript turn a schema into type definitions, so your runtime validation and compile-time types come from one source of truth.

Try it

Paste both your data and your draft schema into the two panels of the JSON Wallet editor to format and eyeball them side by side, and use Compare to track schema changes over time. If you are still learning the basics, start with What is JSON? and JSON syntax rules.

Keep reading

Ready to put this into practice? Open the free JSON editor →