入門

雜項範例

在此頁面中，您將找到各種範例，說明不同的使用案例，以協助您充分利用 JSON Schema。每個範例都附有相關的 JSON 資料和說明。

基本

此範例提供您在 JSON Schema 中可能看到的典型最小值。它包含

  • $id 關鍵字
  • $schema 關鍵字
  • title 註解關鍵字
  • type 執行個體資料模型
  • properties 驗證關鍵字
  • 三個鍵：firstName、lastName 和 age，每個都有自己的
    • description 註解關鍵字。
    • type 執行個體資料模型（見上文）。
  • minimum age 鍵上的驗證關鍵字。
schema
{ "$id": "https://example.com/person.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Person", "type": "object", "properties": { "firstName": { "type": "string", "description": "The person's first name." }, "lastName": { "type": "string", "description": "The person's last name." }, "age": { "description": "Age in years which must be equal to or greater than zero.", "type": "integer", "minimum": 0 } }}

資料

資料
{ "firstName": "John", "lastName": "Doe", "age": 21}

在資料範例中，我們提供了 firstName、lastName 和 age 屬性的值。這些值符合定義的 schema，其中 firstName 是一個字串，lastName 也是一個字串，而 age 則是一個大於或等於零的整數。

事物陣列

陣列是 JSON 中基本結構 — 在此我們示範幾種描述它們的方式

  • 一個字串值的陣列。
  • 一個物件的陣列。

我們也透過這個範例介紹以下內容

對於 fruits 屬性

  • type 設定為 "array"，表示它是一個陣列。
  • items 描述陣列中的項目。在此案例中，它們應該是 "string" 型別。

對於 vegetables 屬性

  • type 也設定為 "array"，表示它是一個陣列。
  • items 參考 $defs/veggie 的定義，表示陣列中的項目應該符合 $defs 區段中定義的 "veggie" schema。
schema
{ "$id": "https://example.com/arrays.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "description": "Arrays of strings and objects", "title": "Arrays", "type": "object", "properties": { "fruits": { "type": "array", "items": { "type": "string" } }, "vegetables": { "type": "array", "items": { "$ref": "#/$defs/veggie" } } }, "$defs": { "veggie": { "type": "object", "required": [ "veggieName", "veggieLike" ], "properties": { "veggieName": { "type": "string", "description": "The name of the vegetable." }, "veggieLike": { "type": "boolean", "description": "Do I like this vegetable?" } } } }}

資料

資料
{ "fruits": [ "apple", "orange", "pear" ], "vegetables": [ { "veggieName": "potato", "veggieLike": true }, { "veggieName": "broccoli", "veggieLike": false } ]}

資料範例顯示了陣列的使用方式。fruits 屬性包含一個字串陣列，而 vegetables 屬性包含一個物件陣列，每個物件都符合 "veggie" schema 定義。

列舉值

這個範例介紹了 enum 驗證關鍵字，它與一個包含整數 (42)、布林值 (true)、字串 ("hello")、null 和陣列 ([1, 2, 3]) 的值陣列一起使用。這示範了如何使用 enum 來指定一組不同型別的允許值。

schema
{ "$id": "https://example.com/enumerated-values.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "列舉值", "type": "object", "properties": { "data": { "enum": [42, true, "hello", null, [1, 2, 3]] } }}

資料

資料
{ "data": [1, 2, 3]}

提供的資料透過使用列舉陣列中指定的確切值：[1, 2, 3]，符合該 schema。

正規表示式模式

此範例引入了 pattern 關鍵字，並定義了一個名為 code 的屬性，該屬性必須符合特定的正規表示式模式：^[A-Z]{3}-\d{3}$。此處的模式要求三個大寫字母，後接一個連字號和三個數字。

schema
{ "$id": "https://example.com/regex-pattern.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Regular Expression Pattern", "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Z]{3}-\\d{3}$" } }}

資料

資料
{ "code": "ABC-123"}

提供的資料「ABC-123」符合此綱要中定義的模式。

具有巢狀屬性的複雜物件

下方的綱要代表一個複雜的物件，其中包含各種屬性，例如 name、age、address 和 hobbies。address 屬性是一個包含巢狀屬性的物件，而 hobbies 屬性是一個字串陣列。 name 和 age 屬性為必填。

schema
{ "$id": "https://example.com/complex-object.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Complex Object", "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer", "minimum": 0 }, "address": { "type": "object", "properties": { "street": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postalCode": { "type": "string", "pattern": "\\d{5}" } }, "required": ["street", "city", "state", "postalCode"] }, "hobbies": { "type": "array", "items": { "type": "string" } } }, "required": ["name", "age"]}

資料

資料
{ "name": "John Doe", "age": 25, "address": { "street": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001" }, "hobbies": ["reading", "running"]}

所提供的資料符合綱要，包含了必要屬性的值，並確保 age 為大於等於零的整數。address 物件包含所有必要的屬性，且 hobbies 屬性是一個字串陣列。

使用 dependentRequired 的條件驗證

在這個範例中，dependentRequired 關鍵字被用來指定當 foo 屬性存在時，bar 屬性是必要的。此綱要強制規定，如果 foo 存在，則 bar 也必須存在。

schema
{ "$id": "https://example.com/conditional-validation-dependentRequired.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Conditional Validation with dependentRequired", "type": "object", "properties": { "foo": { "type": "boolean" }

資料

資料
{ "foo": true, "bar": "Hello World"}

依照 schema，當 foo 屬性存在（true）時，bar 屬性會變成必要。bar 屬性提供的值為 "Hello World"，符合字串的要求，並確保符合 dependentRequired 條件。

資料
{}

由於 foo 和 bar 都缺失，實例仍然有效，並且也符合 dependentRequired 條件。

資料
{ "foo": true}

上述 schema 無效，因為 foo 屬性存在，但 bar 不存在，這使得 dependentRequired 關鍵字的條件失效。

使用 dependentSchemas 的條件驗證

給定的 schema 展示了 dependentSchemas 關鍵字的使用。它允許定義一個子 schema，如果存在特定屬性，則必須滿足該子 schema。

  • 在這個範例中，schema 定義了一個具有兩個屬性的物件：foo 和 propertiesCount。foo 屬性的類型為布林值，而 propertiesCount 屬性的類型為整數，最小值為 0。
  • 根據子 schema，當 foo 屬性存在時，propertiesCount 屬性會變成必要，並且必須是一個最小值為 7 的整數。
schema
{ "$id": "https://example.com/conditional-validation-dependentSchemas.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Conditional Validation with dependentSchemas", "type": "object", "properties": { "foo": { "type": "boolean" }, "propertiesCount": { "type": "integer", "minimum": 0 } }, "dependentSchemas": { "foo": { "required": ["propertiesCount"], "properties": { "propertiesCount": { "minimum": 7 } } } }}

資料

資料
{ "foo": true, "propertiesCount": 10}

在此，foo 屬性設定為 true，表示它存在。根據 schema，當 foo 存在時，propertiesCount 屬性會變成必要。在此情況下，propertiesCount 屬性提供的值為 10，符合必須是整數且最小值為 7 的要求。

資料
{ "propertiesCount": 5}

在上述資料中，propertiesCount 為 5，但由於 foo 缺失，propertiesCount 不需要是 7 或大於 7，它只需要大於或等於 0。因此，此實例有效。

資料
{ "foo": true, "propertiesCount": 5}

在此例中，foo 的值為 true，但 propertiesCount 的值為 5。根據 dependentSchemas 的設定，schema 中 propertiesCount 的最小值應為 7。因此，這是一個無效的實例。

使用 if-else 的條件驗證

在這個 schema 中，我們有兩個屬性：isMember 和 membershipNumber。條件驗證是基於 isMember 屬性的值。驗證關鍵字為 if、then 和 else。

以下說明此範例中的驗證運作方式

如果 isMember 的值為 true

  • 則會套用 then 區塊，該區塊指定 membershipNumber 屬性應為長度至少 10 個字元且最多 10 個字元的字串。

如果 isMember 的值不是 true 的任何其他值

  • 則會套用 else 區塊，該區塊指定 membershipNumber 屬性可以是任何字串。
schema
{ "$id": "https://example.com/conditional-validation-if-else.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Conditional Validation with If-Else", "type": "object", "properties": { "isMember": { "type": "boolean" }, "membershipNumber": { "type": "string" } }, "required": ["isMember"], "if": { "properties": { "isMember": { "const": true } } }, "then": { "properties": { "membershipNumber": { "type": "string", "minLength": 10, "maxLength": 10 } } }, "else": { "properties": { "membershipNumber": { "type": "string", "minLength": 15 } } }}

資料

資料
{ "isMember": true, "membershipNumber": "1234567890"}

在此例中，isMember 屬性設定為 true，因此會套用 then 區塊。membershipNumber 屬性是一個長度為 10 個字元的字串，符合驗證。

資料
{ "isMember": false, "membershipNumber": "GUEST1234567890"}

在此例中，isMember 屬性為 false，因此會套用 else 區塊。membershipNumber 屬性可以是任何長度大於或等於 15 的字串，因此符合驗證。

需要協助嗎？

您覺得這些文件有幫助嗎？

請幫助我們改進文件！

在 JSON Schema 中，我們重視文件貢獻，就像其他任何類型的貢獻一樣！

在 Github 上編輯此頁面
了解如何貢獻

仍然需要協助嗎？

學習 JSON Schema 通常會令人困惑，但別擔心，我們在這裡提供協助！

在 GitHub 上向社群提問
在 Slack 上向社群提問