本文目录
什么是 JSON Schema？
JSON Schema 是一套用于描述 JSON 数据结构和校验规则的词汇表。它本身也用 JSON 编写，一份 schema 定义了对象可以拥有哪些属性、允许哪些类型、哪些字段是必需的，以及适用哪些约束——从而把非正式的数据契约转化为机器可读的规范。
使用最广泛的版本是 Draft-07，尽管较新的草案（2019-09、2020-12）增加了条件式 schema 和动态引用等特性。JSON Schema 生成器自动化了手写 schema 这一繁琐过程——它会分析示例 JSON 数据，并自动推断出其类型、结构和必需字段。
Schema 生成的工作原理
schema 生成器会检查你的示例 JSON，并生成一份能够对其进行校验的 schema。这一过程涉及类型推断、结构分析和约束检测。
- 类型推断——检查每个值以确定其 JSON 类型（string、number、integer、boolean、null、array、object），schema 会赋予相应的 type 关键字
- 嵌套结构分析——对对象进行递归分析，为每个属性生成子 schema；并检查数组，从其元素中推断出 items schema
- 必需字段检测——示例中出现的所有属性通常都会被标记为必需，因为生成器假定该示例代表了一个完整且有效的实例
免费试用 —— 无需注册
生成 JSON Schema →何时使用 JSON Schema
对于任何需要发送或接收 JSON 数据的项目来说，JSON Schema 都是一项基础工具。
- API 请求校验——在处理之前，先用 schema 校验传入的负载，尽早拒绝格式错误的请求，并向 API 使用方提供清晰的错误信息
- 表单生成——react-jsonschema-form 和 vue-form-generator 等 UI 库可以根据 JSON Schema 自动渲染表单，让后端校验与前端界面保持同步
- CI/CD 中的契约测试——在集成测试中验证 API 响应是否符合预期 schema，在破坏性更改进入生产环境之前将其捕获
常见问题
我应该使用哪个 JSON Schema 草案版本？
为获得广泛兼容性，Draft-07 是最稳妥的选择——大多数校验器、表单生成器和代码生成器都完全支持它。如果你需要 $dynamicRef、prefixItems 或 unevaluatedProperties 等高级特性，则使用 2020-12。请务必确认你所用的校验器库支持你选择的草案。
如何组合多个 schema？
JSON Schema 提供了组合关键字：allOf 要求所有子 schema 都匹配，anyOf 要求至少一个匹配，oneOf 要求恰好一个匹配。使用 $ref 来引用可复用的 schema 定义。例如，一个 User schema 可以使用 allOf 将一个基础的 PersonSchema 与额外的身份验证字段组合起来。
我可以从 JSON Schema 生成 TypeScript 类型吗？
可以。json-schema-to-typescript 和 quicktype 等工具能够将 JSON Schema 转换为 TypeScript 接口，确保你的前端类型与后端契约保持同步。这在 monorepo 中尤为有用——schema 可作为 API 校验和客户端类型检查两方面的唯一可信来源。