{"canonical_url":"https://engineer.company/glossary/json-schema/","content_markdown":"# JSON Schema\n\n## What it is\n\nJSON Schema is a language for describing what a piece of JSON has to look like,\nand it is written in JSON itself. A description in it, called a schema, sets out\nthe rules: this value is an object, it must have these properties, this one is a\nwhole number of at least one, that one a string of at most 200 characters. A\nprogram called a validator takes a schema and an instance, the data being\nchecked, and answers whether the instance conforms, and if it does not, where\nand why. The project writes its name with a capital S, JSON Schema, while a\nsingle document written in the language is simply a schema, in lower case.\n\nThe specification is maintained by the JSON Schema project at json-schema.org.\nThe current version is 2020-12 and the one before it 2019-09; earlier versions\nwere numbered drafts, such as draft-04 and draft-07, and older tools and\narticles still refer to them by those names. The text comes in two parts. The\ncore document defines how a schema is processed, how one schema refers to\nanother and the media type `application/schema+json`, and a second document, on\nvalidation, defines the keywords that check values. The current documents for\n2020-12 are both dated 16 June 2022.\n\nEach keyword adds one constraint. `type` names one of six basic types, string,\nnumber, boolean, array, object or null, or `integer`, which accepts only numbers\nwhose fractional part is zero. Numbers take `minimum`, `maximum` and\n`multipleOf`; strings take `minLength`, `maxLength` and `pattern`, a regular\nexpression; arrays take `minItems`, `maxItems` and `uniqueItems`; objects take\n`properties`, `required` and `additionalProperties`. Keywords such as `allOf`,\n`anyOf`, `oneOf` and `not` combine schemas, and `$ref` points at a schema\ndefined elsewhere, often under `$defs` in the same document, so a shape written\nonce can be used in many places. Anything a schema does not mention is allowed.\nThe empty schema, `{}`, accepts every instance there is.\n\nA schema can also say which version of the language it is written in. The\n`$schema` keyword holds the address of a meta-schema, a schema that describes\nvalid schemas for that version, and the specification page notes that the\nmeta-schema validates itself. For 2020-12 that address is\n`https://json-schema.org/draft/2020-12/schema`.\n\n## Why it matters\n\nJSON says nothing about meaning. Any well-formed document parses, whether or not\nthe program reading it can do anything with it. Without a written description,\nevery program that reads a document keeps its own idea of what valid looks like,\nspread across conditions in its code, and those ideas drift apart until a\nrequest fails in production. A schema puts the rules in one place, in a form\nthat people and programs can both read, and it can be stored, versioned,\nreviewed and published like any other file.\n\nThe specification states its intent broadly: JSON Schema is meant for the\nvalidation and documentation of JSON data, for hyperlink navigation and for\ninteraction control, and the validation vocabulary is also meant to give the\nscreens that show the data hints about it. In practice that means one\ndescription can reject bad input at the edge of a service, document an API,\ndrive a form, and check that the JSON a language model returns has the fields\nthe next step expects.\n\nIt has also become the common ground that other specifications build on. OpenAPI\n3.1 defines its Schema Object as a superset of JSON Schema 2020-12, so the\nrequest and response bodies in an API description are JSON Schema with a few\nadditions. MCP, the protocol through which AI agents discover and call tools,\ndescribes each tool's parameters with an `inputSchema` that is a JSON Schema,\nand may describe its result with an `outputSchema` that clients should validate\nstructured results against. A shared description can therefore serve a validator, an API document and an agent.\n\n## What it looks like in practice\n\nThe schema below describes the input of a tool that books a delivery slot. It\nnames the version it is written in, lists four properties with their rules, says\nwhich three must be present, and refuses any property it does not list:\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"https://example.com/tools/book-slot.json\",\n  \"title\": \"Book a delivery slot\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"order\": { \"type\": \"string\", \"pattern\": \"^[0-9]{4,8}$\" },\n    \"date\": { \"type\": \"string\", \"format\": \"date\" },\n    \"pallets\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 30 },\n    \"note\": { \"type\": [\"string\", \"null\"], \"maxLength\": 200 }\n  },\n  \"required\": [\"order\", \"date\", \"pallets\"],\n  \"additionalProperties\": false\n}\n```\n\nAn instance that breaks the rules:\n\n```json\n{ \"order\": \"4471\", \"date\": \"27/10/2026\", \"pallets\": 0, \"pallet\": 2 }\n```\n\nThe instance fails on two counts. `pallets` is below the minimum of 1, and\n`pallet`, a typo for `pallets`, is a property the schema does not list. The\nmissing `note` is no fault, because `note` is not in `required`; had it been\nsent as `null`, that would pass too, since its type allows null. The date is the\ninstructive one. The `date` format asks for the year first, and `27/10/2026`\nputs the day first, but a validator running with its defaults accepts it,\nbecause the specification makes `format` an annotation that is checked only when\nthat checking is switched on. Switch that checking on in a validator that checks\ndates, and the same instance fails on three counts.\n\nA tool described this way is what this site's page on\n[turning existing software into tools for AI agents](/ai-tools/) is about. It\ndescribes each operation an agent should have, such as booking a slot or\nreleasing an order, offered as a tool with typed inputs, errors an agent can act\non and idempotent calls, so that a retry never books twice. The description is\nan OpenAPI document generated from the code, and an MCP server offers the same\noperations. The page's argument is that an agent trusts a tool's description\neven when it has gone out of date, and a hand-written description can drift from the implementation. The descriptions there are therefore generated from\nthe code outward, through the database, the API, the description and the client,\nwith a check at every step that fails the build when two of them disagree.\n\n## Where it goes wrong\n\n**A listed property that is never required.** `properties` checks only the\nproperties that are present, so an object that leaves all of them out passes.\nPresence is a separate keyword, and leaving `required` out means nothing is\nrequired at all. Write `required` beside `properties` every time, and keep a\ntest case for each required property with that property removed.\n\n**Typos that pass as extra properties.** Without `additionalProperties`, any\nproperty the schema does not list is allowed, so `pallet` goes through and the\nreal `pallets` is quietly missing. Setting it to `false` closes the object, but\nthe keyword sees only the `properties` and `patternProperties` in its own schema\nobject. A schema that builds on another through `allOf` or `$ref` and then\ncloses itself this way rejects the very properties it inherited. Version 2020-12\nhas `unevaluatedProperties` for that case, since it also counts the properties\nchecked through `allOf`, `$ref` and the other keywords that apply schemas in\nplace. Use `additionalProperties: false` on a schema that stands alone and\n`unevaluatedProperties: false` on one that is composed.\n\n**`format` that checks nothing.** By default `format` is an annotation and not\nan assertion: the specification requires a validator that can check formats to\nkeep that checking switched off unless it is asked for, and even when it is\nswitched on, a validator may let any format pass unchecked. OpenAPI 3.1 follows\nthe same rule, and adds that how well formats are checked varies between\nimplementations. Switch format checking on in the validator you use, prove it\nwith a test case that should fail, and where a format matters but cannot be\nchecked, add a `pattern` or a check in code.\n\n**Patterns that match part of a value.** A `pattern` is not anchored, so\n`[0-9]{4}` accepts `order 4471b` because four digits appear somewhere inside it;\nthe specification's own example is that `es` matches `expression`. Start the\npattern with `^` and end it with `$` when the whole value has to match. Patterns\nfollow the ECMA-262 dialect, and the specification recommends a small set of\nconstructs for patterns that should behave alike everywhere, so keep to simple\nclasses, quantifiers and anchors.\n\n**Missing, null and empty treated as one.** A property that is absent, a\nproperty set to `null` and an empty string are three different instances.\n`\"type\": \"string\"` rejects `null`, and a property not listed in `required` may\nbe absent. A client that sends `null` to mean no value, against a schema written\nfor absence, fails on every such request. Decide per property what each of the\nthree means and write it down: `[\"string\", \"null\"]` when null carries meaning,\nabsence from `required` when the property is optional, and `minLength: 1` when\nan empty string is not a value.\n\n**No `$schema`, or two versions mixed.** When the root of a schema has no\n`$schema`, the specification leaves the behaviour to the implementation, and\neach validator applies whichever version it defaults to. The versions differ in\nplaces that matter. In 2019-09 an array given to `items` described a tuple; in\n2020-12 that job belongs to `prefixItems`, and `items` took over the role of\n`additionalItems`. Put `$schema` in every root, follow the release notes when\nmoving between versions, and validate every schema against its meta-schema in\nCI.\n\n## Further reading\n\n- [JSON Schema Specification](https://json-schema.org/specification) — the\n  project's index of the current version, its meta-schemas and the release notes\n  for every earlier draft.\n- [JSON Schema: A Media Type for Describing JSON Documents](https://json-schema.org/draft/2020-12/json-schema-core)\n  — Core 2020-12: how schemas are processed, `$schema`, `$ref` and `$defs`, and\n  the keywords that combine schemas.\n- [JSON Schema Validation: A Vocabulary for Structural Validation of JSON](https://json-schema.org/draft/2020-12/json-schema-validation)\n  — the keywords for each type of value, `required`, and the rules for `format`.\n- [JSON Schema 2020-12 Release Notes](https://json-schema.org/draft/2020-12/release-notes)\n  — what changed since 2019-09, with `prefixItems` and `$dynamicRef` side by\n  side with what they replaced.\n- [OpenAPI Specification v3.1.1](https://spec.openapis.org/oas/v3.1.1.html) —\n  the Schema Object as a superset of JSON Schema 2020-12, and `format` as an\n  annotation by default.\n- [Model Context Protocol: Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)\n  — how a tool declares its parameters and its structured output in JSON Schema.\n\n\u003chttps://engineer.company/glossary/json-schema/\u003e\n","date_modified":"2026-11-12T05:34:23Z","description":"How a JSON document can describe what valid data looks like, where that one description is put to work, and the defaults that let bad data through.","formats":{"gemtext":"https://engineer.company/glossary/json-schema/index.gmi","gopher":"https://engineer.company/glossary/json-schema/gophermap","html":"https://engineer.company/glossary/json-schema/","json":"https://engineer.company/glossary/json-schema/index.json","markdown":"https://engineer.company/glossary/json-schema/index.md","pdf":"https://engineer.company/glossary/json-schema/index.pdf"},"kind":"page","language":"en","title":"What is JSON Schema?","url":"https://engineer.company/glossary/json-schema/","version":1}