Schema 版本与校验流程

JSON Schema 有 draft 版本。draft 定义了哪些关键字存在，以及校验器应如何解释它们。现代 schema 常用 Draft 2020-12，较老的生态仍可能要求 Draft 7。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

$schema 字段告诉工具应使用哪种方言。选择 draft 时，要看你的校验器、编辑器和 API 工具链支持什么。

校验错误也是契约的一部分

有用的 schema 应该能给出指向问题的错误：

• 缺少必填属性
• 类型错误
• 值低于最小值
• 字符串不符合格式
• 出现策略不允许的额外属性

审查 schema 时，应同时测试合法和非法示例。非法 fixture 往往更有价值，因为它能证明校验器确实拦住了你关心的问题。

兼容性规则

修改 schema 可能破坏客户端。应像对待 API 演进一样对待 schema 演进：

• 新增可选属性通常安全。
• 新增必填属性可能破坏已有生产者。
• 缩窄枚举可能破坏历史数据和客户端。
• 修改类型通常是破坏性变更。
• 删除字段可能破坏消费者。

实践中的 draft 选择

对于新的本地工作流，Draft 2020-12 是合理默认值。对于必须兼容旧工具的项目，Draft 7 仍然有用。最好的 draft 是生产校验器真正支持的最新版本。

Schema 是会演进的契约。把它和示例、测试、发布说明放近一点，数据契约才不会和真实系统慢慢漂移。