# What Is JSON Schema? — Validating JSON, Drafts, and Why Agents Use It

Canonical: https://commareports.com/glossary/json-schema
Published: 2026-10-17

> JSON Schema is a JSON document that describes what another JSON document must look like: types, required fields, allowed values. The core keywords, the draft versions (draft-07 to 2020-12), and why OpenAPI, MCP tools and LLM structured outputs are all built on it.

# JSON Schema

**JSON Schema is a JSON document that describes what another JSON
document is allowed to look like.** It names the type of every value,
which object properties exist and which are required, and the
constraints on them. A validator reads the schema and the data and
returns every mismatch with its path.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": { "type": "string", "minLength": 1 },
    "status": { "enum": ["passed", "failed", "skipped"] },
    "duration_ms": { "type": "integer", "minimum": 0 },
    "tags": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["title", "status"],
  "additionalProperties": false
}
```

`{"title": "Login", "status": "ok"}` fails that schema at `/status`;
`{"title": "Login", "status": "passed", "owner": "qa"}` fails because
`owner` isn't a declared property.

## The keywords you use most

| Keyword                                      | Checks                                                                                 |
| -------------------------------------------- | -------------------------------------------------------------------------------------- |
| `type`                                       | `string`, `number`, `integer`, `boolean`, `object`, `array`, `null`                    |
| `properties` / `required`                    | Which keys an object has, and which must be present                                    |
| `additionalProperties`                       | Whether undeclared keys are allowed                                                    |
| `items`                                      | The schema every array element must match                                              |
| `enum` / `const`                             | A fixed set of allowed values / exactly one value                                      |
| `minimum`, `maximum`, `minLength`, `pattern` | Ranges, lengths, regular expressions                                                   |
| `$ref` / `$defs`                             | Reuse a sub-schema instead of repeating it                                             |
| `oneOf`, `anyOf`, `allOf`, `not`             | Combine schemas                                                                        |
| `format`                                     | `date-time`, `email`, `uri`… — an annotation unless the validator is told to assert it |

## Versions

Schemas declare their draft with `$schema`. The ones you'll meet are
**draft-04**, **draft-06**, **draft-07**, **2019-09** and **2020-12**,
the current release. Draft-07 remains the most broadly supported;
2020-12 is what OpenAPI 3.1 uses. The differences that bite: `definitions`
became `$defs` in 2019-09, tuple validation moved from array-form
`items` to `prefixItems` in 2020-12, and `format` stopped being
validated by default.

## Where it shows up

- **APIs.** OpenAPI request and response bodies are JSON Schema.
- **Config files.** Editors use schemas (often from SchemaStore) to
  autocomplete and flag errors in `package.json`, `tsconfig.json`, CI
  YAML and similar files.
- **Agents.** Every [MCP](/glossary/model-context-protocol) tool
  publishes an `inputSchema`, and LLM function-calling and
  structured-output APIs accept JSON Schema, so the model knows what
  arguments to produce and the host can reject malformed ones before
  anything runs. Comma's own [MCP server](/mcp) describes
  `create_report`, `list_comments` and the rest this way.

## Validating

Ajv in JavaScript, `jsonschema` in Python and the validators listed at
json-schema.org cover every draft. To look at the document being
validated first, the [JSON formatter](/tools/json-formatter) pinpoints
syntax errors by line and column, the [JSON viewer](/tools/json-viewer)
gives you a searchable tree with a [JSONPath](/glossary/jsonpath) for
every node, and [JSON diff](/tools/json-diff) shows what changed between
a passing and a failing payload.

## Try it

Comma is free — unlimited reports, unlimited commenters, unlimited
revision history.

**[Open a JSON document in the viewer →](/tools/json-viewer)**

### Related

- [JSONPath](/glossary/jsonpath) · [JSON Patch](/glossary/json-patch) · [NDJSON](/glossary/ndjson)
- [Model Context Protocol (MCP)](/glossary/model-context-protocol)
- [Glossary](/glossary)