What is the difference between JSON and JSON Schema?

JSON is a text format for data, and JSON Schema is a vocabulary for describing what a JSON document must contain. JSON (JavaScript Object Notation) writes data as objects, arrays, strings, numbers, booleans, and null. JSON Schema is itself written in JSON. It states which fields are required, what type each field has, and what limits apply. A validator reads both documents and reports whether the data satisfies the schema. The word "schema" also has a looser meaning, the structure of any data as opposed to the data itself, and that reading is covered further down.

A JSON Document

A JSON document is only values, with no rules attached. The example below describes one product. Nothing in the file says that price must be a number or that sku must be present. A parser accepts it as long as the braces, quotes, and commas are well formed.

{
  "sku": "LAMP-204",
  "name": "Desk lamp",
  "price": 34.5,
  "inStock": true,
  "tags": ["lighting", "office"]
}

The JSON Schema for That Document

A JSON Schema states the rules that the document above must follow. The $schema keyword names the draft of the specification being used. type says the root is an object, properties lists the allowed fields with their types, and required names the fields that must be present. additionalProperties: false rejects any field not listed.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "type": "object",
  "properties": {
    "sku": { "type": "string", "pattern": "^[A-Z]+-[0-9]+$" },
    "name": { "type": "string", "minLength": 1 },
    "price": { "type": "number", "minimum": 0 },
    "inStock": { "type": "boolean" },
    "tags": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["sku", "name", "price"],
  "additionalProperties": false
}

A validator given both files returns a pass. Change "price": 34.5 to "price": "34.5" and the validator reports that price must be a number. Remove sku and it reports a missing required field.

What JSON Schema Can Express

The keywords cover types, ranges, formats, and structure. For numbers there are minimum, maximum, and multipleOf. For strings there are minLength, maxLength, pattern, and format, where format names a known shape such as an email address. For arrays there are items, minItems, and uniqueItems. enum fixes a value to a list of allowed constants.

Schemas can be composed. $ref points to another schema, or to a definitions block in the same file, so a shared Address schema is written once. oneOf, anyOf, and allOf combine schemas. A JSON Schema is also a JSON document, so the specification publishes a meta-schema, which is a JSON Schema that validates other JSON Schemas. That is the file the $schema URL points to.

Where JSON Schema Is Used

JSON Schema is used wherever JSON passes between two parties. An API validates each request body against a schema before the handler runs, so bad input is rejected with a clear message. OpenAPI documents describe request and response bodies with a JSON Schema dialect. Code editors read a schema to offer autocomplete and warnings inside configuration files. Code generators produce classes in Java, TypeScript, or Python from a schema, so both sides agree on the shape.

Data Versus Its Structure

In the looser sense, a schema is the structure of data, and JSON is one way to write the data. A relational database has a schema too. It is the set of tables, columns, types, and constraints, and the rows are the data. The same split applies inside a database when a table has a JSON column. The table schema says the column exists and holds JSON, but the shape of the JSON inside it is unchecked unless the application validates it, for example with a JSON Schema.

This is the trade behind a common design question: several configuration objects per user, stored in a separate table or in one JSON field. A separate table gives the database a structure to enforce and columns to index. A JSON column gives flexibility, and the application takes over the checking.

JSON Schema Versus JSON Type Definition

JSON Type Definition (JTD) is a smaller alternative format. It is defined in RFC 8927 and is aimed at code generation, so it has fewer keywords and maps directly onto types in a programming language. JSON Schema is larger, older, and more widely supported by validators and editors. Most projects encounter JSON Schema first, through an API framework or an editor.