从 JSON 样本做 JSON Schema 推断

手写 JSON Schema 是件很折磨人的事。一个普通的 API 响应可能有二三十个字段,嵌套两三层,还混着数组。要给它写一份带 type、properties、required 的校验规则,光是把字段抄一遍就够喝一壶,抄完还容易漏。更现实的情况是:你手上根本没有现成的文档,只有几段从日志里捞出来的真实 payload。这时候,直接从样本反推 schema 就比从零手写靠谱得多。

JSON Schema 推断,做的就是这件事:你粘贴一段或几段真实 JSON,工具帮你把字段类型、必填项、数组元素形状、字符串格式都识别出来,生成一份可以直接用的 schema 初稿。

推断到底在判断什么

很多人以为推断就是把每个字段标个类型那么简单,其实判断点比这密。以一个简单的用户对象为例:

{ "id": "5f3c", "email": "a@x.com", "age": 28, "tags": ["vip"] }

从这一条样本能推断出:id 是 string、email 是 string 且格式是 email、age 是 integer、tags 是 string 数组。如果你只给了这一条,那这四个字段全部会进 required,因为它们都出现了。判断格式的逻辑是保守的:只有当某个字段下所有观察到的字符串值都匹配某种模式时,才会标 email、URI、date、date-time 或 UUID 这些格式,否则就退回普通 string。

required 的判断更要看多条样本。给一条样本,所有字段都算必填;给一批样本,只有在每一条里都出现的字段才会留在 required 里,出现率不满的字段自动降级成可选。这正是从样本推断的价值:它把"哪些字段稳定存在"这件事量化了。

一段真实输入输出

我把两条记录粘进去:

[
  { "id": 1, "name": "Ada", "active": true },
  { "id": 2, "name": "Lin" }
]

推断出来的 schema 大致是这样:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": { "type": "integer" },
      "name": { "type": "string" },
      "active": { "type": "boolean" }
    },
    "required": ["id", "name"]
  }
}

注意 active 没进 required,因为第二条记录里没有它。这个细节正是手写时最容易写错的地方:人盯着第一条样本就把 active 当必填,实际数据里它是可选的。机器按出现率判断,反而不会带这种主观偏差。

嵌套和数组怎么处理

真实 payload 很少是平的。嵌套对象会被当成独立的子 schema 递归推断,层数不限;数组则会合并所有元素的形状,得出一个统一的 items 描述。如果数组里既有带 discount 字段的对象又有不带的,那 discount 同样会被判成可选。这种合并逻辑让你不用为数组里每一种变体单独写规则,工具替你做了归并。

对于 NDJSON,也就是每行一个 JSON 值的格式,普通解析失败时工具会逐行解析,再按数组式 schema 推断。事件日志、流式导出这类数据基本都是这个形态,直接粘进去就行。

把它放进实际工作流

我自己最常用它的场景是给一个还没文档的内部接口补校验。先从测试环境捞十几条真实响应粘进去,导出 schema,再人工把业务约束补上,比如把某个状态字段收成 enum、给金额加数字下界。这一步很关键:样本只能覆盖已经出现过的字段和取值,低频的可选字段可能根本没在样本里露过面,小枚举也只是候选而非铁证。推断给的是高质量初稿,不是终稿。

输出有三种模式可挑。Markdown 报告会写明样本数量并嵌入 schema,适合贴进接口文档;JSON 模式直接下载 schema 拿去喂校验库;CSV 模式把字段路径拍平成表,评审字段覆盖率时一眼能扫完。完整功能可以直接在 JSON Schema 推断器 里试。如果你的目标是 TypeScript 项目里的运行时校验,推断完 schema 后再用 TypeScript 转 Zod Schema 把类型转成 Zod 校验器,从样本到可执行校验的链路就接通了。

数据契约这件事,与其等到出问题再回头补,不如趁手上有真实样本时先固化下来。推断帮你把最枯燥的第一稿做完,剩下的判断力留给真正需要人来定的业务约束。

---

Made by Toolora · Updated 2026-06-13