JSON Schema 可以理解为 JSON 数据的结构说明书：哪些字段必须存在、每个字段是什么类型、数组里应该放什么，都可以写成规则。
在接口联调、配置校验、低代码表单和数据导入场景中，JSON Schema 可以帮助你在数据进入业务逻辑前先发现结构错误。
从一段 JSON 开始
{
"id": 1001,
"email": "user@example.com",
"roles": ["admin"],
"active": true
}这段数据包含数字、字符串、数组和布尔值。对应的 Schema 可以描述每个字段的类型以及必填规则。
{
"type": "object",
"required": ["id", "email", "roles", "active"],
"properties": {
"id": { "type": "number" },
"email": { "type": "string", "format": "email" },
"roles": {
"type": "array",
"items": { "type": "string" }
},
"active": { "type": "boolean" }
}
}常用字段是什么意思？
| Schema 字段 | 作用 | 例子 |
|---|---|---|
| type | 限制值的基础类型 | object、array、string、number |
| properties | 描述对象里的字段 | email、roles、active |
| required | 规定必须出现的字段 | id、email |
| items | 描述数组元素类型 | roles 里的每一项是 string |
| format | 补充字符串格式语义 | email、uri、date-time |
接口校验怎么用？
- 用真实接口样本生成第一版 Schema。
- 根据接口文档补充 required、format、enum、minLength 等规则。
- 用 Schema 校验真实请求或响应数据。
- 根据错误路径定位具体字段，再修正数据或调整规则。
从样本生成的 Schema 只是起点
生成器只能观察样本里已经出现的值。它无法知道某个字段是否可能缺失，字符串是不是固定枚举，数字有没有上下限，也无法从一个 null 推断真实业务类型。因此自动结果适合搭建骨架，最终约束仍要对照接口文档、数据库规则和异常样本补齐。
| 样本现象 | 自动推断的盲点 | 人工补充 |
|---|---|---|
| 字段每次都出现 | 不代表业务上必填 | 按合同决定是否放入 required |
| 值是 paid | 看不出还有 draft 或 failed | 补充 enum 或 oneOf |
| 数组只有一项 | 看不出其它元素形态 | 加入更多样本并检查 items |
| 对象没有额外字段 | 看不出是否允许扩展 | 明确 additionalProperties 策略 |
校验通过也不等于业务正确
Schema 主要验证结构与声明的约束。即使 email 格式正确，也不能证明邮箱真实存在；即使金额是正数，也不能证明订单允许退款；format 关键字是否强制检查还取决于验证器配置。把 Schema 放在输入边界用于尽早拒绝坏数据，跨字段规则、权限和业务状态仍应由应用代码处理。
团队还应固定所使用的 JSON Schema draft 与验证器版本。不同 draft 的关键字和引用行为可能不同，Schema 文件最好声明 $schema，并把验证规则纳入接口测试，避免生产端和文档端使用不同解释。
总结
JSON Schema 的价值不只是说明数据长什么样，更重要的是把结构约束变成可执行校验，减少接口和数据流里的隐性错误。