JSON Schema Explained: How to Describe and Validate JSON Structure

JSON Schema is a standard way to describe the shape of your JSON: which fields exist, what type each value must be, and which ones are required. You write a schema (itself a JSON document) and then a validator checks any data against it, so a bad payload gets caught before it reaches your code.

That is the whole idea. The rest of this guide shows the core keywords, a worked example you can copy, and where teams actually use it.

What is JSON Schema? (a contract for your JSON)

Think of JSON Schema as a contract. Plain JSON tells you what the data is right now. A schema tells you what the data is allowed to be, every time.

Here is the smallest useful version. Say your app expects a user object with a name and an age. The schema looks like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"]
}

Run that against { "name": "Mezi", "age": 34 } and it passes. Run it against { "age": 34 } and it fails, because name is required. The $schema line just says which version of the spec you are using (the 2020-12 draft is the current one most tools support).

A schema is written in JSON, so the same tools you already use for JSON work on it. If a schema itself looks messy, paste it into a formatter first so the nesting is readable.

JSON Schema vs plain JSON validation

Plain JSON validation only answers one question: is this valid JSON syntax? A missing comma or an unquoted key fails. But { "age": "thirty-four" } is perfectly valid JSON, even though age should be a number. Syntax checking cannot catch that.

JSON Schema validation goes further. It checks meaning, not just grammar. Wrong type, missing required field, a string that is too long, a number out of range: a schema catches all of it.

So the two do different jobs. You want your JSON to parse first (that is JSON syntax rules), and then you want it to match your expected structure (that is the schema). One is spelling, the other is grammar.

If you are still fuzzy on what JSON itself is, start with what is JSON and come back. This guide assumes you can already read a JSON object.

Core keywords: type, properties, required

Three keywords carry most of the weight in a schema.

type says what kind of value is allowed. The seven values map to the JSON data types: string, number, integer, object, array, boolean, and null. For the full picture of how those map to real values, see JSON data types explained.

properties describes the fields inside an object. Each key gets its own mini-schema:

"properties": {
  "email": { "type": "string" },
  "active": { "type": "boolean" }
}

required lists the fields that must be present. It is an array of property names. Anything not in the list is optional by default. A field can be defined in properties and still be optional if you leave it out of required.

One thing that trips people up: by default a schema lets extra fields through. If you want to reject unknown keys, add "additionalProperties": false at the object level. Without it, { "name": "x", "hacker": true } still passes a schema that only defines name.

Validating data types with a schema

Type validation is where a schema earns its keep. You can go well past “must be a string” and pin down the exact rules.

For strings, minLength, maxLength, pattern (a regex), and format (like email or date) narrow the field. For numbers, minimum, maximum, and multipleOf set the range. For example, an age that must be a non-negative integer under 150:

"age": {
  "type": "integer",
  "minimum": 0,
  "maximum": 150
}

You can also allow more than one type. "type": ["string", "null"] accepts a string or an explicit null, which is common for optional-but-present fields coming out of a database.

Nested objects and array validation

Real data nests. A schema nests with it. To validate an object inside an object, put a full schema under that property:

"address": {
  "type": "object",
  "properties": {
    "city": { "type": "string" },
    "zip": { "type": "string" }
  },
  "required": ["city"]
}

Arrays use items to describe every element, and minItems / maxItems to bound the length. This says “an array of at least one string”:

"tags": {
  "type": "array",
  "items": { "type": "string" },
  "minItems": 1
}

Because items is itself a schema, you can validate an array of objects the same way: set items to { "type": "object", "properties": ... }. The nesting has no depth limit, so a schema can mirror any JSON structure you throw at it.

A complete JSON Schema example, annotated

Here is a full JSON Schema example for a blog post record, with each piece doing real work:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title":   { "type": "string", "minLength": 1 },
    "slug":    { "type": "string", "pattern": "^[a-z0-9-]+$" },
    "views":   { "type": "integer", "minimum": 0 },
    "draft":   { "type": "boolean" },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "maxItems": 5
    }
  },
  "required": ["title", "slug"],
  "additionalProperties": false
}

Reading it top to bottom: the record must be an object. title is a non-empty string. slug must match the regex, so my-post passes but My Post! fails. views cannot go negative. tags is capped at five strings. Only title and slug are mandatory, and additionalProperties: false blocks any field not listed here.

Feed this schema { "title": "Hi", "slug": "hi", "tags": ["a","b","c","d","e","f"] } and it fails on one rule: six tags exceed maxItems. A good validator tells you exactly that, with a path pointing at tags. That specific error message is the payoff. You find the broken field without reading the whole payload by hand.

Where JSON Schema is used (APIs, configs, forms)

Three places show up again and again.

APIs. OpenAPI (the spec behind most REST API docs) uses JSON Schema to define request and response bodies. That is how a tool can auto-generate docs and reject a bad request before it hits your handler.

Config files. Editors like VS Code read JSON Schema to give you autocomplete and inline errors in files like package.json or tsconfig.json. The red squiggle under a misspelled config key is a schema at work.

Forms and data pipelines. Some form libraries build the whole UI from a schema, and ETL jobs validate incoming records against one before loading them. When the shape of your data is a contract between two systems, a schema is the contract you can actually run.

Tools and next steps for validating your JSON

Before you validate structure, your JSON has to be clean and readable. A messy one-line blob hides the very brackets you are trying to reason about. Run it through our free JSON formatter first: it pretty-prints the data, flags syntax errors, and makes the object nesting obvious so writing (or reading) the matching schema is far easier.

From there, the workflow is simple. Format the data, sketch the schema from the fields you see, add type and required, then tighten with ranges and patterns as you learn what bad input looks like. Start loose, get it passing, then lock it down.

FAQ

What is JSON Schema in simple terms? It is a JSON document that describes what other JSON is allowed to contain: the fields, their types, and which are required. A validator then checks real data against it and reports anything that does not fit.

Is JSON Schema the same as validating JSON syntax? No. Syntax validation only checks that the JSON parses (no missing commas or quotes). JSON Schema checks meaning: correct types, required fields, value ranges. Valid syntax can still break the schema.

What are the JSON Schema data types? Seven: string, number, integer, object, array, boolean, and null. You set them with the type keyword, and a property can allow more than one, like ["string", "null"].

Do I have to write JSON Schema by hand? Not always. Many editors and API tools generate a starting schema from sample data, and you refine it from there. Formatting your sample JSON cleanly first makes that first draft much easier to read and correct.