Skip to main content
最终版标准轨道
字段值
SEP1613
标题确立 JSON Schema 2020-12 为 MCP 默认方言
状态最终版
类型标准轨道
创建日期2025-10-06
作者Ola Hungerford
赞助者无
PR#1613

​
摘要

本 SEP 确立 JSON Schema 2020-12 为 MCP 消息中嵌入式模式（工具 inputSchema/outputSchema 和需求收集 requestedSchema 字段）的默认方言。模式可以通过 $schema 字段显式声明替代方言。这解决了导致实现之间兼容性问题的歧义。

​
动机

MCP 规范未明确说明嵌入式模式应使用哪个 JSON Schema 版本。这导致了：
  • 客户端和服务器假设不同版本之间的验证失败
  • SDK 生态系统之间的实现分歧
  • 开发者不确定性，需要进行任意版本选择
社区讨论（GitHub Discussion #366, PR #655）显示，实现方案在 draft-07 和 2020-12 之间分裂，多位维护者和社区成员强烈偏好将 2020-12 作为默认值。

​
规范

​
1. 默认方言

当不存在 $schema 字段时，MCP 消息中的嵌入式 JSON 模式必须符合 JSON Schema 2020-12。

​
2. 显式方言声明

模式可以包含显式的 $schema 字段以声明不同的方言： 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" }
  }
}

​
3. 模式验证要求

  • 模式必须根据其声明或默认方言有效
  • inputSchema 字段不得为 null
对于无参数的工具，使用以下有效方法之一：
  • true - 接受任何输入（最宽松）
  • {} - 等同于 true，接受任何输入
  • { "type": "object" } - 接受具有任何属性的任何对象
  • { "type": "object", "additionalProperties": false } - 仅接受空对象 {}
示例：无参数的工具 
{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

​
4. 适用范围

本规范适用于：
  • tools/list 响应：inputSchema 和 outputSchema
  • prompts/elicit 请求：requestedSchema
  • 未来嵌入 JSON Schema 定义的 MCP 功能

​
5. 实现要求

服务器必须：
  • 默认生成符合 2020-12 的模式
  • 使用非默认方言时包含显式的 $schema
客户端必须：
  • 根据声明或默认方言验证模式
  • 至少支持 JSON Schema 2020-12

​
理由

​
为什么选择 2020-12？

  1. 生态系统对齐：Python SDK（通过 Pydantic）和 Go SDK 实现偏好/使用 2020-12
  2. 现代特性：更好的验证能力和组合支持
  3. 社区偏好：PR #655 讨论中的多位维护者和社区成员倡导使用 2020-12 而非 draft-07
  4. 当前标准：截至 2025 年，2020-12 是稳定版本

​
为什么允许显式声明？

  • 支持现有模式的迁移路径
  • 提供灵活性而无需协议变更
  • 遵循 JSON Schema 最佳实践

​
考虑的替代方案

  • Draft-07 作为默认值：社区反馈后被拒绝；版本较旧，功能较少
  • 无默认值：被拒绝，因为不必要的冗长；增加样板代码
  • 多个同等版本：被拒绝；造成不可预测性和碎片化

​
向后兼容性

这在技术上是一个澄清，而非破坏性变更：
  • 没有 $schema 的现有模式默认为 2020-12
  • 服务器可以在过渡期间添加显式的 $schema
  • 基本模式（type, properties, required）跨版本工作
默认假设使用 draft-07 的模式可能需要迁移：
  • 使用 dependencies 的模式（→ dependentSchemas + dependentRequired）
  • 位置数组验证（→ prefixItems）
迁移策略： 在过渡期间添加显式的 $schema: "http://json-schema.org/draft-07/schema#"，然后更新为 2020-12 特性。

​
参考实现

​
SDK 实现

Python SDK - 已兼容：
  • 使用 Pydantic 生成模式
  • Pydantic 通过 .model_json_schema() 默认为 2020-12
Go SDK - 已实现 2020-12：
  • 显式 2020-12 实现已完成
  • 由 @samthanawalla 在 PR #655 讨论中确认
其他 SDK：
  • 可能需要更新，但基于其他示例，应该有简单或开箱即用的选项来支持此功能。我可以在此添加更多示例，或者我们可以在接受后创建问题进行跟进。

​
安全影响

未发现将 2020-12 确立为默认方言有任何特定的安全影响。该澄清减少了可能导致实现之间验证不匹配的歧义，这是通过增加可预测性带来的轻微安全改进。 与任何依赖项一样，实现应使用维护良好的 JSON Schema 验证器库并保持更新。

​
相关工作

​
SEP-1330: 需求收集枚举模式改进

SEP-1330 提议弃用非标准的 enumNames 属性，转而使用符合 JSON Schema 2020-12 的模式。这项工作直接由确立 2020-12 为默认方言启用。 实现考虑：
正如 SEP-1330 讨论中所指出的，对于高级 JSON Schema 特性（如 oneOf 和 anyOf）的解析复杂性存在一些担忧。然而，这些特性是 JSON Schema 标准的一部分，并由成熟的验证器库良好支持。实现可以通过使用经过良好测试的 JSON Schema 验证库来平衡标准合规性与它们的解析需求。

​
SEP-834: 完整 JSON Schema 2020-12 支持

本 SEP 奠定了基础（默认方言），而 SEP-834 解决了对 2020-12 特性的全面支持。

​
未决问题

规范本身的模式引用了 draft-07，而我们用于生成它的 typescript-json-schema 包仅支持 draft-07。 选项：
  1. 更新模式生成脚本，在生成后修补为 2020-12（这是我在当前 PR 中所做的）
  2. 切换到支持 2020-12 的不同模式生成器
  3. 保持原样，因为它实际上不与规范冲突？
个人而言，我短期内更倾向于 (1)，然后作为后续工作采用 (2)。