> ## Documentation Index
> Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SEP-1613: 确立 JSON Schema 2020-12 为 MCP 默认方言

> 确立 JSON Schema 2020-12 为 MCP 默认方言

<div className="flex items-center gap-2 mb-4">
  <Badge color="green" shape="pill">
    最终版
  </Badge>

  <Badge color="gray" shape="pill">
    标准轨道
  </Badge>
</div>

| 字段       | 值                                                                               |
| -------- | ------------------------------------------------------------------------------- |
| **SEP**  | 1613                                                                            |
| **标题**   | 确立 JSON Schema 2020-12 为 MCP 默认方言                                               |
| **状态**   | 最终版                                                                             |
| **类型**   | 标准轨道                                                                            |
| **创建日期** | 2025-10-06                                                                      |
| **作者**   | Ola Hungerford                                                                  |
| **赞助者**  | 无                                                                               |
| **PR**   | [#1613](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/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](https://json-schema.org/draft/2020-12/schema)。

### 2. 显式方言声明

模式**可以**包含显式的 `$schema` 字段以声明不同的方言：

```json theme={null}
{
  "$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 }` - 仅接受空对象 `{}`

**示例**：无参数的工具

```json theme={null}
{
  "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: 需求收集枚举模式改进](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/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 支持](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/834)

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

## 未决问题

规范本身的模式引用了 `draft-07`，而我们用于生成它的 `typescript-json-schema` 包仅支持 draft-07。

选项：

1. 更新模式生成脚本，在生成后修补为 2020-12（这是我在当前 PR 中所做的）
2. 切换到支持 2020-12 的不同模式生成器
3. 保持原样，因为它实际上不与规范冲突？

个人而言，我短期内更倾向于 (1)，然后作为后续工作采用 (2)。