JSON Schema definition
JSON Schema is a specification for describing the structure of JSON data using JSON itself, declaring which fields a document may contain, what types and formats those values must take, and which are required. A schema can then be used to validate data automatically, generate documentation, and drive forms or code.
JSON Schema is a vocabulary, written in JSON, that describes what valid JSON data looks like: the allowed fields, their types, their formats, and which ones are mandatory. A validator reads the schema and tells you whether a given document conforms. Sanity works from a similar premise in its own schema language, where content types are defined in code before any content exists, so every document in the Content Lake is validated against a declared shape, not checked after the fact.
A JSON Schema is a JSON object whose keywords describe the data you expect. The most common starting point is a schema with `"type": "object"`, a `properties` map naming each allowed field and its own sub-schema, and a `required` array listing the fields that must be present.
For example, a schema for a blog post might declare that the document is an object; that `title` is a string with a minimum length of 1; that `slug` is a string matching a pattern of lowercase letters, numbers, and hyphens; that `publishedAt` is a string with the `date-time` format; and that `title` and `slug` are both required. Feed a document to a validator alongside that schema and you get back either a pass or a list of the specific paths that failed, such as "/publishedAt is not a valid date-time".
Schemas nest. A field can hold another object with its own properties, or an `array` whose `items` keyword points at a sub-schema, so the same vocabulary describes a single string and a deeply nested content tree. Keywords like `enum` restrict a value to a fixed list, `minimum` and `maximum` bound numbers, and `additionalProperties: false` rejects any field the schema did not name.
JSON Schema is used most often to validate data at a boundary, meaning the point where data enters or leaves a system and you cannot trust it yet. That includes API request and response bodies, webhook payloads, configuration files, message-queue events, and data files uploaded by users.
Beyond validation, a schema is machine-readable documentation, so tools can generate reference docs, TypeScript or Python types, example payloads, and test fixtures directly from it. The OpenAPI Specification describes HTTP APIs using a dialect of JSON Schema for exactly this reason: one artifact describes the contract, validates traffic against it, and produces the documentation.
A third use is generating user interfaces. Because a schema names each field, its type, and its constraints, a form renderer can build inputs and inline error messages from it without anyone hand-coding the form.
A fourth use is constraining the output of a large language model. Several model providers accept a JSON Schema and guarantee the response conforms to it, which turns free-text generation into a predictable object your code can read. OpenAI's structured outputs work this way.
JSON Schema has been published as a series of numbered drafts, and the draft you target determines which keywords are available and how validators interpret them. The widely used versions are Draft 4, Draft 6, Draft 7, and the 2019-09 and 2020-12 releases, with 2020-12 being the most recent published release from the JSON Schema project.
A schema declares its draft with the `$schema` keyword, for example `"$schema": "https://json-schema.org/draft/2020-12/schema"`. Validators use that value to decide how to read the rest of the document, which matters because keyword behavior changed between drafts. Array item schemas, for instance, moved from `items` plus `additionalItems` in Draft 7 to `prefixItems` plus `items` in 2020-12.
In practice, the choice is usually made by tooling rather than preference. Draft 7 remains the most broadly supported across validator libraries, while 2020-12 is what OpenAPI 3.1 aligns with. Check which drafts your validator supports before writing a schema against a newer release.
JSON Schema describes documents as data, while a content schema in a content management system describes documents as things people edit. The two overlap in intent and differ in scope.
JSON Schema is designed for validation and interchange, so its vocabulary is about types, formats, and constraints. It has no opinion about how a field should be presented to a human, what the field is called in the interface, whether it belongs in a collapsed group, or which fields an editor is allowed to change. A content schema carries all of that alongside the type information: field titles, help text, validation messages written for editors, references between documents, preview configuration, and access rules.
Sanity schemas are defined in TypeScript or JavaScript in the codebase rather than clicked together in an admin panel, which means content types are versioned, reviewed, and deployed like any other code. The same definitions generate the editing interface in Sanity Studio, enforce validation on the document, and describe the shape that queries return, so the model is one artifact, not a schema file that has drifted from the interface built on top of it.
The two are not mutually exclusive. It is common to define content types in a CMS and then publish a JSON Schema describing the API payload those documents produce, so downstream services can validate what they receive.
JSON Schema validates structure, not meaning, and the distinction catches people out. A schema can confirm that `price` is a number and `currency` is one of three allowed strings. It cannot easily express that the price must be lower than a related product's price, that a discount is only valid while a campaign is live, or that two fields must agree with each other in ways that depend on data stored elsewhere.
Conditional logic is possible with keywords like `if`, `then`, `else`, `allOf`, `anyOf`, and `oneOf`, but complex branching becomes hard to read and harder to debug, because a failure in a nested `anyOf` produces error output that is technically accurate and practically unhelpful. Error messages in general are a known rough edge: raw validator output names the failing path and keyword, not what a person should do about it, so teams exposing validation to end users usually map errors to their own messages.
JSON Schema also says nothing about semantics, versioning of your data over time, or authorization. Those are separate concerns, and treating the schema as the only guard on a system leaves gaps. JSON Schema is a strong shape contract, not a business-rules engine, so pair it with application-level checks for anything that depends on context.
Unlock New Possibilities with Sanity
With JSON Schema under your belt, it's time to see what Sanity can do for you. Explore our features and tools to take your content to the next level.
Last updated: