## 先说结论

`https://openapi.vercel.sh/vercel.json` 这一份被大量编辑器引用的 schema，文件开头声明自己是 **draft-04**，但正文里用了 21 处 `const`、15 处 `if`/`then`、2 处 `propertyNames`——**这些关键字在 draft-04 里根本不存在**。

后果不是"某个字段少校验了"，而是：**任何严格遵循 `$schema` 声明的实现，会在加载这一步就拒绝整份文档。**

于是编辑器里那份看起来在保护你的校验，**其实从未生效**。

而你写错一个字段名的时候，看到的和写对的时候一模一样。

## 三行代码复现

```bash
pip install jsonschema
curl -sO https://openapi.vercel.sh/vercel.json
```

```python
import json, jsonschema
s = json.load(open("vercel.json"))
print(s["$schema"])                       # http://json-schema.org/draft-04/schema#
jsonschema.Draft4Validator.check_schema(s)
```

```
jsonschema.exceptions.SchemaError: {'type': 'object', 'additionalProperties': False,
 'required': ['root'], 'properties': {'root': {'description': 'Path to the servic...
```

同一份文件，不做任何修改，换 metaschema 再看：

| 用哪个 draft 校验 | 结果 |
| --- | --- |
| **draft-04**（它自己声明的） | **拒绝** |
| draft-06 | 通过 |
| draft-07 | 通过 |
| 2020-12 | 通过 |

**换句话说：这份 schema 唯一不成立的地方，就是它自己声明要遵守的那一版。**

## 为什么会产生这个裂缝

draft-04 之后，JSON Schema 陆续引入了这些关键字：

| 关键字 | 引入版本 | 这份文件里出现的次数 |
| --- | --- | --- |
| `const` | draft-06 | 21 |
| `propertyNames` | draft-06 | 2 |
| `if` / `then` | draft-07 | 15 / 15 |
| `exclusiveMinimum` | draft-06 起改为数值 | 3 |

**最后一行值得停一下。** `exclusiveMinimum` 在 draft-04 里是**布尔值**——用来修饰 `minimum`，表示"是否排除边界"；从 draft-06 开始它变成**数字**本身。

也就是说，这个词在旧标准和新标准里**含义不同**，不只是"不认识"。一份声称自己是 draft-04 的文件，读到 `"exclusiveMinimum": 0` 的实现，可能理解成一个布尔值，也可能直接报错。**两种反应都不是作者想要的。**

## 为什么"内部测试全绿"也发现不了

这是最值得聊的部分。

Vercel 自己的工具链**不会**撞上这个问题——因为它的类型生成脚本是**手写解析**这份 schema 的（`packages/config/scripts/generate-types.ts`），读者的 interface 里本来就列着 `const`、`oneOf`、`patternProperties` 这些新关键字。**手写解析器不在乎你声明的是哪一版，它只读它认识的键。**

问题在于，**schema 的多数读者不是那个手写解析器**。它们是编辑器内置的语言服务、Ajv 的严格模式、以及各语言里"先读 `$schema` 决定方言，再加载"的校验库。**这些读者会照规矩办事，然后拒绝整份文档。**

于是出现一个经典形态：

> **作者用自己的工具测了一遍，绿的；用户用通用工具加载，根本加载不上。**
> 两边都没说谎，裂缝在"谁在测"和"谁在用"之间。

## 修法是一行

把方言声明改成正文已经在用的那一版：

```diff
-  "$schema": "http://json-schema.org/draft-04/schema#",
+  "$schema": "http://json-schema.org/draft-07/schema#",
```

不需要改任何其他内容：现在文件里的每一样东西 draft-07 都接受。

（如果 `$data` 引用是刻意保留的功能，那它是 Ajv 的**扩展**而非标准关键字，换方言不会影响它的行为，但值得加一行 `$comment` 说明，否则下一位读者还会困惑。）

## 一般化的教训

这个案例之所以值得单独讲，是因为它不属于"漏了个约束"那一类——**它是一份校验规则自己不可加载**。

对写 schema 的人：

1. **声明哪一版，就只用哪一版的语法**。这不是形式主义：方言决定的是"哪些关键字有定义"，而关键字决定的是"检查到底做不做"。
2. **别用自己的专用解析器验证通用性**。你的工具只读它认识的键，所以它永远不会告诉你"通用读者加载不了"。
3. **把 schema 当作要被陌生人消费的产物**，跑一遍通用校验器的严格模式——就像发布前用别人的编译器编一遍自己的代码。

对用 schema 的人：

**你的编辑器没有报错，不等于它在检查。** 有些失效是响亮的（报错刷屏），有些是安静的——这份 schema 属于后者。

---

## 这个发现是怎么来的

我做了一个小工具，专门用来找这一类问题：**它不检查你的代码，它检查你的检查。**

思路来自变异测试，但目标换了位置——不是"给代码植入缺陷看测试抓不抓得住"，而是**"给已知合法的输入做小改动，看你的门禁抓不抓得住"**。一个从未拒绝过任何东西的门禁，和没有门禁的区别，只在你以为它有的时候才显出来。

工具是 `greencheck`，零依赖，`pip install greencheck` 就能跑：

```
https://github.com/simin-yuan/greencheck
```

上面这个 vercel.json 的复现**不依赖它**——那三行代码自己就站得住。

---

*本文涉及的具体文件与行号均可在 2026-09 复现；schema 由对方维护，随时可能修复。若已修复，这正是它该有的结局。*


https://openapi.vercel.sh/vercel.json 这一份被大量编辑器引用的 schema，文件开头声明自己是 draft-04，但正文里用了 21 处 const、15 处 if/then、2 处 propertyNames——这些关键字在 draft-04 里根本不存在。

一份 JSON Schema 声明自己是旧标准，却在使用新标准的语法

创始人｜腾讯云同盟架构师

编程语言

开发工具

架构设计

一份声称draft-04的Vercel schema文件实际使用了21处const、15处if/then等新关键字，导致严格校验器直接拒绝加载，编辑器校验静默失效。三行代码即可复现，将方言声明改为draft-07即可修复，无需其他改动。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

一份 JSON Schema 声明自己是旧标准，却在使用新标准的语法-腾讯云开发者社区-腾讯云

一份 JSON Schema 声明自己是旧标准，却在使用新标准的语法

一份 JSON Schema 声明自己是旧标准，却在使用新标准的语法

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐