JSON Schema 生成器，免费

JSON Schema 用来做什么

JSON Schema 是用一种声明式的方法来描述一份 JSON 文档应该长成什么样子:它有哪些属性、这些属性持什么类型、什么是必需的还是可选的、什么值是合法的。它在 JSON 世界里相当于 XML 的 XSD,或者一个数据库表定义。官方项目在 json-schema.org。

你会在以下场合遇到它:

• API 契约。OpenAPI 3.1(2021 年 2 月发布)直接嵌入了 JSON Schema:现代 API spec 中每个请求体和响应体都用一段 JSON Schema 描述。
• IDE 自动补全和验证。VS Code 的 settings.json、你项目里的 package.json 和 tsconfig.json、GitHub Actions 的 workflow.yml 文件都靠已发布的 JSON Schema 来自动补全和 lint。
• 服务器端验证。Express / Fastify / Spring / Flask / FastAPI / Echo 都集成了 JSON Schema 验证器(AJV、jsonschema、fastjsonschema),用来在请求体抵达业务逻辑之前拒掉畸形的请求。
• 代码生成。quicktype、json-schema-to-typescript、datamodel-code-generator 这类工具能把一份 schema 转成 Go 结构体、TypeScript 类型、Python dataclass、Java POJO 等等,从单一来源提供跨语言的类型。
• 文档。对于你发布的任何 JSON 形状的数据,schema 都兼作机器可读的文档。

你在野外会看到的 draft

JSON Schema 的规范以一系列 draft 形式发布。当前稳定 draft 是 2020-12(根据官方 spec 页面:「The current version is 2020-12」)。你可能遇到的 draft:

• Draft 4,旧但仍在使用;OpenAPI 3.0 用了 JSON Schema Specification Wright Draft 00 的一个扩展子集(有时非正式地称作 Draft 5),它接近但不完全等同于 Draft 4。
• Draft 6、Draft 7,Draft 7(2018)多年来是占主导地位的生产 draft,目前在遗留工具链中仍然非常常见。
• Draft 2019-09,首个使用「年-月」标识符约定的 draft;在保留遗留 definitions 关键字的同时引入了 $defs。
• Draft 2020-12,当前稳定 draft,也是本生成器输出的版本。与 OpenAPI 3.1 对齐。

拿不准时,选与你的验证器匹配的 draft。AJV(最流行的 JavaScript 验证器)显式 opt-in 后支持 Drafts 04、06、07、2019-09 和 2020-12。Python 的 jsonschema 也是。如果你不知道下游消费者想要什么,2020-12 是新工作的安全默认。

内置类型

JSON Schema 描述了与 JSON 值种类对应的七个基本类型:

组合关键字让你混搭使用:oneOf(恰好一个)、anyOf(至少一个)、allOf(全部)、not(取反)。还有 enum 表示一个有限的允许值列表,const 表示一个固定值。

自动生成的 schema 能告诉你什么、不能告诉你什么

从单一 JSON 示例推断 schema 强大但有限。生成器能检测:

• 每个叶子值的类型(string vs number vs boolean vs array vs object)。
• 嵌套对象和数组的结构。
• 示例中出现的键(并在你启用时把它们标为 required)。

它不能检测:

• 可选字段。你示例中的某个键在真实 spec 里可能是可选的,但单一示例无法告诉你哪些。默认看起来全部都是必需的。
• 格式提示。字符串 "2024-04-12" 看起来像日期,但也可能只是一个恰好长得像日期的自由文本标签。如果该字段确实是日期,请手动加上 format: date。
• 验证约束。最大长度、允许的 enum 值、regex 模式:都需要人工输入。
• 文档字符串。每个字段上的 title、description 和 examples 能改善开发者体验,但需要人工编辑。
• 变体。如果一个字段根据上下文可以是字符串也可以是数字,单一示例只会挑一个,错过另一个。组合多个示例,或手动使用 oneOf。

把输出当作完成度 70% 的起点。有价值的补充(哪些字段真的必需、适用什么字符串格式、允许什么值范围、每个字段意味着什么)是人工编辑这一步。

两个值得了解的微妙陷阱

• format 在 2020-12 里默认是建议性的。format-annotation 词汇表把 format: email 标记为提示,而非硬性验证规则,除非你的验证器显式 opt-in 进 format-assertion。所以一个不匹配 email regex 的字符串默认还是通过。AJV 的 strict 模式和 ajv-formats 包提供完整的格式验证;在依赖格式检查处理安全敏感输入之前,请确认你的验证器的默认行为。
• additionalProperties: false 与 allOf 配合不好。如果你用 allOf 做继承式验证组合 schema,某一分支上的 additionalProperties: false 看不到兄弟分支定义的属性,所以合法字段会验证失败。Draft 2019-09+ 的修复方法是 unevaluatedProperties: false,它具有组合感知能力。

JSON Schema vs Zod / Joi / Yup vs TypeScript 类型

有几种技术与 JSON Schema 的角色重叠;每种都有自己的甜点区:

• JSON Schema。声明式 JSON、运行时验证、与语言无关。在 API 契约跨越语言边界时获胜(例如一个 Go 服务器、一个 Python 数据流水线和一个 TypeScript 前端共同消费同一个 API)。
• TypeScript 类型。仅编译期。在 TS 代码库内部用于进程内类型安全很漂亮,但它们在运行时消失,对进入的 JSON 提供不了任何验证。json-schema-to-typescript 这类工具从 schema 生成类型,以两全其美。
• Zod / Joi / Yup。JavaScript / TypeScript 中的代码优先运行时验证,带有内建的 TypeScript 推断。单一语言,但在该语言内部体验极佳。Schema 是 JS 对象,不是可移植的 JSON。
• Pydantic / Marshmallow。Python 的对应物:基于类的运行时验证,使用 Python 类型注解。

如果你的 schema 需要被多种语言或工具(IDE、OpenAPI 工具链、代码生成器)消费,JSON Schema 是合适的家。如果你只待在一种语言里,该语言的原生选项通常写起来更舒服。

常见使用场景

• 引导一份 OpenAPI spec。粘贴一份真实 API 响应,生成 schema,放进你的 components.schemas。
• 生成 TypeScript / Go / Python 类型,通过 quicktype 或类似工具,从单一来源提供跨语言的类型。
• 用 AJV / jsonschema / Pydantic 验证不可信输入到服务器端点。
• 为自定义配置格式编写 IDE 自动补全。VS Code、JetBrains IDE 等读取 JSON Schema 来驱动 JSON 文件的自动补全。
• 给下游消费者记录配置文件的形状。
• 在数据格式间迁移。从一个来源生成的 JSON Schema 可以驱动下游的验证、转换或文档。

常见错误

1. 把自动生成的 schema 当作最终 spec。它是一个起点。加上格式提示、标记真正可选的字段、加上文档、设置值范围。
2. 缺失 $schema 声明。验证器靠它知道应用哪个 draft。永远在 schema 顶部包含它。
3. 把 required 当成每个属性的属性。不像 XSD 或 Mongoose schema,JSON Schema 的 required 是父对象层面的一个数组,列出必需属性的名字。
4. 想要严格验证时忘了 additionalProperties: false。默认是 true,意思是未知键会被默默允许。
5. 把 enum 与 examples 搞混。enum = 允许值的列表(验证)。examples = 仅供文档用的示例值(无验证作用)。
6. 假设 format 被强制执行。在 Draft 2020-12 里默认是注解,不是断言;你的 email regex 不会跑,除非你 opt-in。
7. 从单一示例推断可选性。你示例里的每个键默认都变成 required。真实 spec 几乎都有可选字段;在编辑过程中把它们从 required 数组里移除。

更多常见问题

schema 能在 OpenAPI 3.1 里用吗?

能。OpenAPI 3.1(2021 年 2 月发布)把它的 schema 语言完全与 JSON Schema Draft 2020-12 对齐,这正是本生成器输出的内容。把 schema 放进你的 OpenAPI 文档的 components.schemas,通过 $ref 引用。更老的 OpenAPI 3.0 用的是更早的子集;如果你针对 3.0,可能需要调整。

我能从这个 schema 在我用的语言里生成类型吗?

可以。quicktype 能从一个 JSON Schema 生成 TypeScript、Go、Python、Java、C#、Swift、Kotlin、Rust、Elm 等等。json-schema-to-typescript 是个 JS 专属的替代。大多数现代语言至少有一个 schema-to-types 工具;生成的 schema 对所有这些工具都是合适的输入。

$defs 与 definitions 有什么区别?

两者都是放可重用子 schema 的地方,你可以在文档其它位置 $ref 它们。definitions 是遗留名字,用在 Drafts 04、06 和 07。$defs 是当前名字,在 Draft 2019-09 引入并在 2020-12 中延续。功能上等价,但新工作请用 $defs。

我的 JSON 会被发送到任何地方吗?

不会。Schema 生成完全在你的浏览器中运行。粘贴的 JSON 在本地解析、遍历,并作为 schema 输出到文本框。任何东西都不会被上传到服务器、记录或在你关闭标签页后保留。这一点很重要,因为 JSON 示例往往包含真实数据(客户记录、内部 API 响应、员工信息),你不想让这些数据流经第三方。

为什么我的数组的 schema 只描述了第一个元素?

从单一示例的推断把数组当作同质的:它看第一个元素,假设其余的相同。如果你真实数组可以包含不同形状,你需要手动把 items 写成 { "oneOf": [...] }。或者对每个变体分别运行生成器,然后合并 schema。

我到底应该用生成器,还是手写 schema?

对于一个你端到端控制的小 schema,手写让你更快学会规范。对于带几十个嵌套对象的大型 API 响应,生成几秒钟就给你一个草稿,你把省下的时间花在编辑约束、描述和 required 数组上。大多数干活的开发者两者都做:生成,然后编辑。