# 我扫了 1370 份 JSON Schema，找「声明和正文对不上」的：真正符合的只有 1 份，而我第一次数出来 19 份

## 一、先说结论

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

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

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

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

顺带说一句时间线：这篇稿在 2026-09-17 写的第一版，到今天 2026-09-27 重新拉这份文件，它**还是老样子**。这个裂缝不会自己愈合——因为作者的工具链永远撞不到它（第五节解释为什么）。

## 二、三行代码复现

```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 | 通过 |
| 2019-09 | 通过 |
| 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` 决定方言，再加载」的校验库。**这些读者会照规矩办事，然后拒绝整份文档。**

于是出现一个经典形态：

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

## 五、这次往下走了一步：这不是孤例吗？

第一版发出去之后，我心里有个没答的问题：**这到底是 1 个 bug，还是一类现象？**

要回答它，就需要一个足够大的样本。JSON Schema 有个现成的目录——[SchemaStore](https://www.schemastore.org/)，编辑器（VS Code 的 YAML 插件就是它）背后那份 schema 清单，几十个生态、上千份文件都在里面登记着，每份都带 URL。

于是我把整个目录拉下来跑了一遍。做法很朴素：

1. 拉目录 → 1486 个条目
2. 逐个下载 schema → 取到 1436 份，其中 1407 份解析成 JSON 成功（剩下的是 YAML 或网络失败）
3. 筛出**声明了 `$schema` 的** → **1370 份**
4. 对每一份，用它**自己声明的**那一版 metaschema 去校验它自己

```
$ python scan_schemastore.py
目录条目 1486 | 取到 1436 | 解析成功 1407 | 声明了方言 1370
判为「与自己声明的方言不一致」  19   (1.4%)
```

**19 份。1.4%。**

如果我在这里收尾，标题就是《1370 份 schema 里，1.4% 声明和正文对不上》。听起来很扎实，有数字、有分母、有工具背书。

我去逐条读了那 19 份。

## 六、逐条读完之后：19 变成 1

**16 份，是我的探针自己的问题。**

它们的 `pattern` 里写了这些东西：

```
(?<major>0|[1-9]\d*)\.(?<minor>...)      # .NET global.json
^[\p{L}\p{N}\s_.:/=+\-@]*$               # AWS AgentCore
(?<=...)                                  # 若干 OSCAL 规范文件
```

`\p{L}`（Unicode 字母类）、`(?<name>...)`（命名捕获组）——**这些在 ECMA-262 里全是合法语法**，而 ECMA-262 正是 JSON Schema 规定的正则方言。

但 metaschema 把 `pattern` 声明为 `format: regex`，而 Python 的 `re` 模块**不是** ECMA-262 引擎：它不认 `\p{L}`，命名组得写成 `(?P<name>...)`。于是校验在「这条正则编不过」上直接失败。

**这不是那 16 份文件的缺陷，是我的测量工具的引擎差异。**把它们算进去，就是把「我的尺子不准」记成「你的东西坏了」。

**1 份，五个版本全都不接受，所以它不属于这一类。**

GraphQL Code Generator 那份，正文里写着：

```json
"type": "{(boolean | TypeNamePattern)}"
```

这是模板占位符没被替换就发布了。它跟方言没关系——draft-04 到 2020-12 全都拒绝它。

**1 份，两种口径给出不同答案，我查不出原因。**

AWS AgentCore CLI 那份：用 `check_schema` 报错，用「直接拿 metaschema 跑一遍它」却零错。我试了几轮没定位到原因，**所以我不用它的结论**——一个我自己都解释不了的异常，不该进统计。

**剩下 1 份，才是真的。**

就是开头那份 `vercel.json`：draft-04 拒绝它，draft-06 / draft-07 / 2019-09 / 2020-12 全部通过。

```
共 19 份进复检：
  正则引擎差异（我的尺子不准，不计入）  16
  各版都不通过 / 两种口径打架           2
  ★ 只在自己声明那版不成立              1
      - Vercel  https://openapi.vercel.sh/vercel.json

共 1436 份判定自洽的里抽 100 份反向复核：误判 0 份
```

> **1370 份里，真正属于这一类的只有 1 份。0.07%。**

## 七、这个 19 比 1，比 1.4% 那个数字重要得多

我把这次的坑记下来，因为它是通用件：

**第一版扫出来的 19，有 16 个是我自己的正则引擎撑不住 ECMA-262 语法。**而这不是一个「细心的错误」——它是一个**结构性**的错误：我拿一个专用解析器（Python 的 `re`）去验证通用性（ECMA-262 的兼容），这恰好就是原稿第四节批评 Vercel 的那件事。**同一个错误，在三个小时里从我批评的对象，搬到了我自己手上。**

第二层错误更值得说：**如果我不读那 19 份，我会发出去一个 19 倍的数字。**而且它看起来非常可信——有目录、有分母、有工具名、有百分比。

> **直接从工具里捞出来、又没有逐条读过的数字，大概率是假的。**
> 它不一定是错的，但它是**未审计的**——而「未审计的数字」和「假的数字」在传播上没有区别。

第三层，是关于「扫得越多越好」这件事本身：这轮扫描真正有价值的产出不是 1.4%，而是**这个类在现实里到底有多罕见**。知道「1370 份里只有 1 份」，比知道「有 19 份」更有用——因为它告诉你，这不是一个需要人人自查的流行病，而是一个**低概率、高代价**的陷阱：命中率千分之一，命中一次就是编辑器和校验库全线失效。

对于写 schema 的人，最后有一条可操作的自查：

```bash
pip install check-jsonschema
# 用「通用读者」的方式加载一遍你自己的 schema
check-jsonschema --check-metaschema your-schema.json
```

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

## 八、一般化的教训

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

对写 schema 的人：

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

对用 schema 的人：

**你的编辑器没有报错，不等于它在检查。**

对自己写测量脚本的人（也就是我）：

**在报出任何一个百分比之前，先把分母里的异常逐条读完。**读完再决定它算不算。

---

## 这个发现是怎么来的

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

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

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

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

上面这个 vercel.json 的复现**不依赖它**——那三行代码自己就站得住。第六节那份全量扫描的脚本、原始结果（1436 行 JSONL）与逐条分类，也放在同一个仓库的实验目录里。

---

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


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

我扫了 1370 份 JSON Schema 找「声明和正文对不上」的：真正符合的只有 1 份，而我第一次数出来 19 份

一份被编辑器广泛引用的 schema 声明自己是 draft-04，正文却用了 draft-06/07 的关键字——严格按声明加载的实现会拒绝整份文档，你写的校验其实从未生效。这次我把 SchemaStore 全量 1370 份扫了一遍：工具报出 19 份「不一致」，逐条读完只剩 1 份。附三行复现。

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

开发工具

编程语言

测试

扫描1370份JSON Schema发现仅1份声明与正文不符：Vercel的schema声明draft-04却使用const、if/then等新关键字，导致严格校验器拒绝加载。初始误报19份，经逐条复核排除正则引擎差异等测量误差，真实占比0.07%。此类低概率高代价陷阱需用通用校验器自查，避免专用解析器盲区。

代码解释

编译器

Python

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

我扫了 1370 份 JSON Schema 找「声明和正文对不上」的：真正符合的只有 1 份，而我第一次数出来 19 份-腾讯云开发者社区-腾讯云

我扫了 1370 份 JSON Schema 找「声明和正文对不上」的：真正符合的只有 1 份，而我第一次数出来 19 份

我扫了 1370 份 JSON Schema 找「声明和正文对不上」的：真正符合的只有 1 份，而我第一次数出来 19 份

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐