JSON 模式验证器

支持的关键词

核心：type、enum、const、multipleOf、maximum、minimum、exclusiveMaximum、exclusiveMinimum、maxLength、minLength、pattern、maxItems、minItems、uniqueItems、maxContains、minContains、maxProperties、minProperties、required、dependentRequired。

组合：allOf、anyOf、oneOf、not。

应用器：properties、patternProperties、additionalProperties、items、prefixItems、contains、propertyNames。

条件：if、then、else、dependentSchemas。

引用：$ref、$defs、$id、$anchor。

格式（启用时会进行验证）：date-time、date、time、duration、email、hostname、ipv4、ipv6、uri、uuid、regex。

错误输出

FAIL  /user/email        format            "not-an-email" is not a valid "email"
FAIL  /user/age          minimum           -3 is less than the minimum 0
FAIL  /orders/0/total    type              "42" is not of type "number"
FAIL  /                  required          missing required property "shippingAddress"

每条错误都包含失败的路径和关键词，便于您在编辑器中快速定位。

那些真正棘手的草案差异

请设置正确的草案；将草案 04 的模式当作 2020-12 来验证，会错误解读 id 及其他一些细微差别。

典型工作流程

• API 契约测试：部署前，将生成或更新后的 OpenAPI 模式与真实的示例响应进行比对验证。
• 配置加固：合并前，在 CI 中将每个 YAML/JSON 配置与模式进行验证。
• 数据摄入：尽早拒绝与预期结构不符的载荷，并给出清晰的错误提示。

常见错误

• 忘记强制执行 format。 默认情况下，大多数验证器将未知格式仅视为注释。请启用严格格式验证，以真正拒绝无效的电子邮件和日期。
• 过度使用 oneOf。 若 oneOf 的两个分支存在重叠，文档将无法通过验证（必须恰好匹配其中一个）。请使用 anyOf 或判别器模式。
• 使用 additionalProperties: false 的严格模式。 添加新的可选字段会变成破坏性变更。除非您确实需要一个封闭对象，否则请勿设置它。