支持的 JSON Schema 关键字

注意

OAS 3 本指南适用于 OpenAPI 3.0。

OpenAPI 3.0 使用 JSON Schema 规范 Wright 草案 00 (又称草案 5) 的扩展子集来描述数据格式。“扩展子集”意味着某些关键字受支持而某些不受支持，某些关键字的用法与 JSON Schema 略有不同，并且引入了附加关键字。

支持的关键字

这些关键字与 JSON Schema 具有相同含义

• title
• pattern
• required
• enum
• minimum
• maximum
• exclusiveMinimum
• exclusiveMaximum
• multipleOf
• minLength
• maxLength
• minItems
• maxItems
• uniqueItems
• minProperties
• maxProperties

这些关键字支持但有细微差异

• type – 值必须是单一类型，而不是类型数组。null 不受支持作为类型，请改用 nullable: true 关键字。
• format – OpenAPI 有自己的预定义格式，也允许自定义格式。
• description – 支持 CommonMark 语法用于富文本表示。
• items – 如果 type 是 array，则必须存在。项目模式必须是 OpenAPI 模式，而不是标准 JSON Schema。
• properties – 单个属性定义必须遵循 OpenAPI 模式规则，而不是标准 JSON Schema。
• additionalProperties – 值可以是布尔值（true 或 false）或 OpenAPI 模式。
• default – 默认值必须符合指定的模式。
• allOf – 子模式必须是 OpenAPI 模式，而不是标准 JSON Schema。
• oneOf – 子模式必须是 OpenAPI 模式，而不是标准 JSON Schema。
• anyOf – 子模式必须是 OpenAPI 模式，而不是标准 JSON Schema。
• not – 子模式必须是 OpenAPI 模式，而不是标准 JSON Schema。

不支持的关键字

• $schema
• additionalItems
• const
• contains
• dependencies
• id,
• $id
• patternProperties
• propertyNames

附加关键字

OpenAPI 模式还可以使用以下不属于 JSON Schema 的关键字

• deprecated
• discriminator
• example
• externalDocs
• nullable
• readOnly
• writeOnly
• xml

参考资料

OpenAPI 3.0 – Schema 对象

JSON Schema 验证 – JSON Schema 关键字参考

JSON Schema 草案 Wright 00 – 核心 JSON Schema 规范

没有找到您要找的内容？询问社区
发现错误？告诉我们