支援的 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 – 綱要物件

JSON Schema 驗證 – JSON Schema 關鍵字參考

JSON Schema 草案 Wright 00 – 核心 JSON Schema 規格

找不到您要找的東西？ 向社群提問
發現錯誤？ 告訴我們