JSON 模式

JSON Schema 本身就是一个 JSON 文档，它规定了其他文档必须遵循的规则：文档类型、属性（包括必需属性）、属性值的类型和格式，以及字符串和数组的长度限制。所有主流编程语言中的验证器都会根据 Schema 检查文档，并报告任何违规情况。

工作原理

类型、属性、必需项、项、枚举、格式和模式等关键字组合起来描述一个结构；$ref 会重用定义。OpenAPI 3.1 使用 JSON Schema（草案 2020-12）来定义请求和响应主体，因此 API 描述本身也是一组用于验证其通信的验证器。

误解

additionalProperties 的默认值为 false。默认情况下，模式允许存在未明确列出的属性，这意味着即使响应中包含大量意外字段，仍然能够通过验证。严格的契约检查必须将 additionalProperties 设置为 false，否则就无法捕获到额外的字段。

点击这里试试

每个 API 的 OpenAPI 文档都嵌入了 JSON Schema 来表示其主体；将 Try it out 的响应粘贴到同级网站的 JSON 到 JSON Schema 生成器中，即可从数据本身推断出模式。

相关内容

• What OpenAPI is
• JSON to JSON Schema generator (fundata.dev)

资料来源

• HTTP semantics — RFC 9110
• OpenAPI Initiative

其他术语

• OpenAPI — HTTP API 的机器可读描述——包括其路径、参数、主体和响应——以 JSON 或 YAML 格式表示。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日