What is JSON Schema? How LLM tools and MCP use it

Also called JSON Schema 2020-12, inputSchema

Definition

JSON Schema is a declarative vocabulary, itself written in JSON, for describing the structure of JSON data; LLM APIs and MCP use it to define tool arguments and constrain model output.

JSON Schema is a vocabulary for describing what valid JSON data looks like: which properties an object has, their types, which ones are required, and which values are allowed. A schema is itself a JSON document. The current version listed on json-schema.org is 2020-12, published as a Core specification and a Validation specification. In AI engineering, JSON Schema is the shared language for tool parameters: model APIs use it to describe tools to the model in tool calling, and MCP servers use it to declare each tool's inputs and outputs.

How JSON Schema works#

A JSON Schema works as a set of keywords, each constraining one aspect of a JSON value. type restricts the JSON type, properties describes each field of an object, required lists the fields that must be present, and keywords such as enum, pattern, minimum, and maxItems narrow the allowed values. A validator checks a value against every keyword.

A typical tool argument schema:

{
  "type": "object",
  "properties": {
    "city": { "type": "string", "description": "City name, such as Lisbon" },
    "units": { "type": "string", "enum": ["metric", "imperial"] },
    "days": { "type": "integer", "minimum": 1, "maximum": 7 }
  },
  "required": ["city"],
  "additionalProperties": false
}

Validators ignore annotation keywords such as description, but a model reads a field's description as guidance for filling it, so field descriptions are part of the prompt. $defs and $ref let a schema reuse subschemas, and $schema declares which dialect a schema follows.

The Model Context Protocol makes JSON Schema mandatory for tools. The MCP base protocol says a schema without a $schema field defaults to 2020-12, implementations must support at least that dialect, and they must not automatically dereference a $ref that points to a network URI. Every tool's inputSchema must be a valid schema object; a tool with no parameters should use { "type": "object", "additionalProperties": false }. An optional outputSchema describes the tool's structuredContent. Revision 2026-07-28 loosened both fields to accept any 2020-12 keyword. MCP SDKs usually generate these schemas from code, such as Python type hints or Zod definitions in TypeScript.

JSON Schema vs structured outputs#

JSON Schema is a description language; structured outputs is a model API feature that uses a JSON Schema to constrain what the model generates. A validator checks JSON after it exists, while constrained decoding blocks invalid tokens during generation. Providers support only a subset of JSON Schema for constrained decoding.

JSON Schema validation Structured outputs
When it runs After the JSON exists During generation
Keywords Everything in the declared dialect A provider-defined subset
On a mismatch Reports errors; the caller retries Invalid tokens are never generated
Typical use MCP tool inputs, API payloads, config files Model responses and strict tool arguments

OpenAI's supported schemas section shows how large the gap is. Structured Outputs accepts string, number, boolean, integer, object, array, enum, and anyOf, with pattern and format for strings, range and multipleOf keywords for numbers, and minItems and maxItems for arrays. Every field must be listed in required, with optional fields written as a union with null, and every object needs additionalProperties: false. The root must be an object, not anyOf. A schema may have up to 5,000 object properties and 10 levels of nesting, and allOf, not, if, then, else, dependentRequired, and dependentSchemas are not supported. Definitions and recursive schemas are allowed.

The gap matters when one schema feeds several consumers. A schema that MCP accepts as an inputSchema can still be rejected by a provider's strict mode if it uses allOf or a conditional. Write tool schemas for the strictest consumer, and keep validation in code for business rules that no schema expresses.

Tool calling shows how schemas shape tool definitions and strict mode.

Cite this definition

The AI Engineering Editors. "What is JSON Schema? How LLM tools and MCP use it." The AI Engineering, updated Nov 06, 2026. https://theaiengineering.com/glossary/json-schema

Title
What is JSON Schema? How LLM tools and MCP use it
Author
The AI Engineering Editors
Publisher
The AI Engineering
Updated
View as Markdown

Part of the Prompt and context engineering hub · Updated