JSON Schema is a vocabulary for describing the shape of JSON data, written in JSON itself. A schema states which type a value must be, which object properties exist and which are required, and constraints such as allowed values, string patterns and number ranges. A validator checks a document against it and reports every violation by path.

Which JSON Schema version should I use?

Draft 2020-12 is the current release and the one OpenAPI 3.1 aligns with. Draft-07 is still the most widely supported by older tools. Declare the version you write against with the `$schema` keyword so validators apply the right rules — the drafts differ in details such as `definitions` becoming `$defs` and how `items` handles tuples.

What is the difference between JSON Schema and OpenAPI?

JSON Schema describes data. OpenAPI describes an HTTP API — paths, methods, parameters, responses — and uses JSON Schema for the bodies inside it. OpenAPI 3.1 uses JSON Schema 2020-12 directly; earlier OpenAPI versions used a modified subset.

Why do AI agents and MCP use JSON Schema?

A tool an agent can call needs a machine-readable description of its arguments. The Model Context Protocol gives every tool an `inputSchema` that is a JSON Schema object, and LLM function-calling and structured-output APIs take JSON Schema the same way, so the model knows what to produce and the host can validate it before running anything.

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.

{
  "$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 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 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 pinpoints syntax errors by line and column, the JSON viewer gives you a searchable tree with a JSONPath for every node, and 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 →