契约检查工作台
JSON Schema 校验在线工具 — OpenAPI 3.1 结构检查
用 Ajv 按 Draft-07 或 2020-12 校验 JSON 数据实例，追踪实例路径与 schema path，并在浏览器本地查看 OpenAPI 3.1 结构和接口路径差异。
- 01
解析文档
JSON 或 YAML 语法能否被正确读取？
- 02
编译 Schema
所选 dialect 能否识别并编译这份 schema？
- 03
校验实例
JSON 数据是否满足类型、必填项和取值约束？
- 04
检查 API
paths、operations、components 与引用能否形成可审查的契约？
选择不同 Draft，会改变关键字和引用行为
| 问题 | Draft-07 | 2020-12 / OpenAPI 3.1 |
|---|---|---|
| 复用定义 | definitions | $defs |
| 数组元组规则 | items 数组 | prefixItems |
| 与 OpenAPI 的关系 | OpenAPI 3.0 风格的旧式子集 | OpenAPI 3.1 使用该 vocabulary |
实例错误追踪
把实例路径和 schema path 放在一起看。
/items/1/price 必须 >= 0 ↳ schema /properties/items/items/properties/price/minimum
实例指针告诉你哪个值校验失败，schema 指针说明触发了哪条规则。Ajv 同时给出这两条线索，避免你在一长串模糊报错里反复猜位置。
OpenAPI 3.1 用 JSON Schema 串起 HTTP 操作与数据结构
路径 + 方法参数请求体响应Components / schemas
比较契约前先查看这张结构图：一个 component 可能被多个 operation 复用，因此局部 schema 或引用的变化可能同时影响多个接口。
本地引用结果可复现，远程引用需要额外信任
DevSexy 只解析输入文档中已经存在的本地引用，不会请求任意远程 URL，也不会把尚未解析的远程引用误报为校验通过。
#/components/schemas/Order → 本地解析 https://…/common.json → 标记为远程引用
判断破坏性变更，不能只看一份自动结果
- 删除 path 或 operation
- 新增必填参数或属性
- 收窄 enum 或数值范围
- 改变响应状态码或媒体类型
- 改变身份验证要求
检查清单只能标出候选风险；是否兼容还取决于实际调用方、默认值和部署策略。
JSON Schema 与 OpenAPI 常见问题
- JSON 语法正确，就一定符合 JSON Schema 吗？
- 不一定。语法解析只说明 JSON 可以读取；实例校验还会检查 schema 定义的类型、必填字段、取值范围和其他约束。
- OpenAPI 3.1 就是 JSON Schema 吗？
- 不是。OpenAPI 3.1 的 Schema Object 与 JSON Schema 2020-12 对齐，但完整 OpenAPI 文档还包含 paths、operations、parameters、responses 等 API 结构。
- 工具会加载远程 $ref 吗？
- 不会。远程引用只会被标记，不会自动请求，以便让本地校验保持可复现，也避免把内部文档地址发送到外部服务。