JSON Schema
JSON Schema is a declarative specification language for describing and validating the structure of JSON data, itself written in JSON format. It defines rules covering data types, property constraints, required fields, and enumerated values to validate and document JSON data. JSON Schema is widely used in API design, configuration file validation, form validation, and automated code generation, serving as a key tool for ensuring interoperability and data consistency.
Core Facts
Each tool in MCP has a strict JSON Schema description, including the name, functional description, and parameter specifications
Function Calling机制中，开发者将工具的名称、功能描述、参数Schema（通常为JSON Schema格式）注入到模型的请求中，模型输出结构化的JSON而非自然语言来调用工具
Agents use the Tool Calling mechanism to allow models to output calling intent in a structured JSON format, with external programs executing the actual operations and feeding results back to the model.
Timeline (last 90 days)
JSON Schema is standardized by the IETF as a series of draft documents, and draft-7, which the SDK uses, is one of those versions.
When handing the schema to the model, if the model is responsible for producing the raw input, `io: "input"` should be used.
In `io: "input"` mode, the `.transform()` on the `sku` field appears as an ordinary string in the JSON Schema; in the default `io: "output"` mode, the converter throws an error.
In the refund extraction schema demonstration, the `.refine()` on the `note` field leaves only `"type": "string"` in the JSON Schema, while the object-level `.refine()` is lost entirely.
In the refund extraction schema demonstration, `.regex(...)` is converted in JSON Schema to `pattern`, `.positive()` is converted to `exclusiveMinimum: 0`, `z.enum` is converted to `enum`, and `z.iso.date()` is converted to `format: "date"` plus `pattern`.
Model APIs such as OpenAI's and Anthropic's accept only a subset of JSON Schema keywords, and the remaining constraints are either ignored or downgraded to natural language descriptions.
JSON Schema can only express structural and simple value constraints such as types, enums, regex patterns, date formats, numeric upper and lower bounds, required fields, and array lengths; it cannot express arbitrary custom functions, cross-field comparisons, or transformations that change the shape of the data.
Structural descriptions for AI agents are closer to declarative interface definitions, for example using JSON Schema to specify data shapes, dependency graphs to make clear that only one-way references between modules are allowed, and signatures to define function contracts.
Pydantic/JSON typed Schemas eliminate 92% of tool call failures
Some APIs enable constrained decoding to force the model to output JSON conforming to the Schema, while others only use the Schema as a hint, so enums can greatly reduce but not completely eliminate the probability of the model fabricating values.
40 more timeline events
All Facts (20)
Each tool in MCP has a strict JSON Schema description, including the name, functional description, and parameter specifications
90%VerifiedFunction Calling机制中，开发者将工具的名称、功能描述、参数Schema（通常为JSON Schema格式）注入到模型的请求中，模型输出结构化的JSON而非自然语言来调用工具
80%VerifiedAgents use the Tool Calling mechanism to allow models to output calling intent in a structured JSON format, with external programs executing the actual operations and feeding results back to the model.
80%VerifiedJSON Schema is a specification for describing and validating JSON data structures, capable of defining field requirements, data types, and value ranges.
80%VerifiedStructured output imposes constraints on token generation during the decoding phase through JSON Schema or function-calling mechanisms, which is fundamentally different from requesting JSON-format output in the prompt.
80%VerifiedDefining typed JSON Schema for tools can reduce format errors and hallucinated parameter filling during model calls, improving call success rates.
75%VerifiedThe basic principle of tool calling is that the model identifies scenarios requiring external capabilities, outputs a structured function call request (usually in JSON format), and after the external system executes it, the result is returned to the model to continue reasoning.
75%VerifiedJSON Schema is a declarative specification based on JSON format, originating from a community draft in 2009, with standardization work advanced by the IETF in RFC 8927 and subsequent drafts.
75%VerifiedSetting additionalProperties: false in a JSON Schema rejects any extra fields not explicitly declared in the schema, eliminating the possibility of the model inventing additional fields.
75%VerifiedThe latest version of JSON Schema is Draft 2020-12, maintained by json-schema.org.
75%VerifiedJSON Schema is maintained by the IETF, and the current version is Draft 2020-12.
70%VerifiedSwagger已更名为OpenAPI Specification，是一套用于描述RESTful API的标准化规范，以JSON或YAML格式定义API信息，目前业界广泛使用OpenAPI 3.0/3.1版本
70%VerifiedFor AI, tools are essentially a menu described in JSON Schema; the clearer the description, the higher the accuracy with which the model selects tools.
65%VerifiedIn the tool-calling mechanism, developers attach a tool description list in JSON Schema format when calling the LLM API, and the model outputs call parameters in structured JSON format
65%VerifiedJSON Mode only guarantees that the output is valid JSON without constraining the field structure; Structured Outputs enforces output conforming to a predefined JSON Schema at the syntactic level by applying a finite state machine (FSM) to constrain the token sampling path during the decoding phase.
65%VerifiedThe schema for tool calls is essentially a JSON Schema specification that describes the tool name, parameter names, type constraints, and required fields.
65%VerifiedMCP规定了工具描述的标准格式，包括工具名称、参数schema、返回值格式
65%VerifiedTaking GPT-4o as an example, the JSON Schema description of each tool consumes an average of 200–500 tokens, and when the system integrates 50 tools, the tool description section alone consumes 10,000 to 25,000 tokens.
65%UnverifiedHermes模型从微调阶段就大量使用结构化输出训练数据，使模型天然倾向于生成格式正确的JSON
80%Unverified当前版本的ChatGPT支持通过JSON Schema或函数调用（Function Calling）约束模型输出特定格式的数据结构
80%