[ADP-754] OpenAPI: JSON Schema
概述
OpenAPI 規範定義了許多常見的驗證格式。然而，有些情況並未被默認的 OpenAPI schema 所涵蓋。在這些情況下，可以使用自定義 JSON Schema 來定義特定的屬性(property)值格式，確保 API 的全面驗證和一致性。
指導原則
- 應該(SHOULD)使用 JSON Schema 來定義 OpenAPI schema 範圍之外的格式
- 應該(SHOULD)按需定義自定義 JSON Schema
- 創建自定義 schema 時必須(MUST)遵循 ADP-701 的屬性設計原則
- 在自定義 schema 中應該(SHOULD)使用 ADP-704 的 ID 屬性(property)約定
- 更新 schema 時必須(MUST)遵守 ADP-24 的版本控制原則
示例
示例 1: 定義國家代碼
國家代碼通常使用 ISO 3166-1 alpha-2 格式表示。以下是使用 JSON Schema 定義國家代碼的方法:
json
{
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "ISO 3166-1 alpha-2 國家代碼"
}此 schema 將國家代碼定義為由兩個大寫字母組成的字符串。
示例 2: 定義語言代碼
語言代碼通常使用 ISO 639-1 格式表示。以下是使用 JSON Schema 定義語言代碼的方法:
json
{
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "ISO 639-1 語言代碼"
}此 schema 將語言代碼定義為由兩個小寫字母組成的字符串。
JSON Schema 基礎
類型
JSON Schema 支持多種數據類型，包括:
stringnumberintegerbooleanarrayobjectnull
定義屬性
通過定義其屬性來描述 JSON 對象。例如:
json
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "integer",
"minimum": 0
}
},
"required": ["name"]
}在此 schema 中:
type指定數據應為對象。properties定義對象的預期屬性。required表示name屬性必須存在。
數組
可以定義數組以指定其包含的項目類型:
json
{
"type": "array",
"items": {
"type": "string"
}
}此 schema 指定數組應只包含字符串項目。
嵌套對象
JSON Schema 可以定義嵌套對象和數組以表示複雜的數據結構:
json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
}
},
"required": ["street", "city"]
}
},
"required": ["id", "address"]
}在此示例中，address 屬性本身是一個具有 street 和 city 屬性的對象。
高級功能
- 模式: 使用正則表達式強制執行特定格式。
- 枚舉: 為屬性定義一組有效值。
- 組合 Schema: 使用
allOf、anyOf、oneOf和not來組合或限制 schema。