開始使用

建立您的第一個綱要

JSON Schema 是一種您可以用來註解和驗證 JSON 文件的詞彙。本教學課程將引導您完成建立 JSON Schema 的過程。

建立您的 JSON Schema 後，您可以使用您選擇的語言的驗證器，根據您的綱要驗證範例資料。請造訪工具並選擇最適合您需求的驗證器。

如果您已經知道如何建立 JSON Schema，並且正在尋找不同的 JSON Schema 用例，例如綱要生成、程式碼生成、文件、UI 生成或 JSON Schema 處理或轉換，請造訪工具並探索 JSON Schema 生態系統中提供的驚人工具。

選單圖示目錄

概觀

我們在本指南中使用的範例是一個產品目錄，它使用 JSON 物件來儲存其資料，如下所示

資料
{ "productId": 1, "productName": "A green door", "price": 12.50, "tags": [ "home", "green" ]}

目錄中的每個產品都有：

  • productId：產品的識別碼
  • productName：產品名稱
  • price：消費者的價格
  • tags：一個可選的識別標籤陣列

JSON 物件是人類可讀的，但它不包含任何上下文或元數據。從物件本身無法得知鍵的含義或可能的輸入是什麼。JSON Schema 是一種提供這些問題答案的標準。在本指南中，您將建立一個 JSON Schema 文件，用於描述一組 JSON 資料的結構、約束和資料類型。

JSON Schema 簡介

實例 是正在驗證或描述的 JSON 文件，而 綱要 是包含描述的文件。

最基本的綱要是一個空白的 JSON 物件，它沒有約束任何內容、允許任何內容，並且沒有描述任何內容

資料
{}

透過將驗證關鍵字新增至綱要，您可以將約束套用到實例。例如，您可以使用 type 關鍵字，將實例約束為物件、陣列、字串、數字、布林值或 null

資料
{ "type": "string" }

JSON Schema 已準備好使用超媒體，非常適合註釋您現有的基於 JSON 的 HTTP API。JSON Schema 文件由 URI 識別，URI 可用於 HTTP 連結標頭和 JSON Schema 文件內，以允許遞迴定義。

建立綱要定義

若要建立基本綱要定義，請定義以下關鍵字

  • $schema：指定綱要遵循哪個版本的 JSON Schema 標準。
  • $id：設定綱要的 URI。您可以使用此唯一 URI，從同一文件內或從外部 JSON 文件中參照綱要的元素。
  • title 和 description：說明綱要的意圖。這些關鍵字不會對正在驗證的資料新增任何約束。
  • type：定義 JSON 資料的第一個約束。在以下產品目錄範例中，此關鍵字指定資料必須是 JSON 物件。

例如

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product in the catalog", "type": "object"}

關鍵字是使用 JSON 鍵定義的。通常，要驗證的資料包含在 JSON 資料文件中，但 JSON Schema 也可以驗證包含在其他內容類型（如文字或 XML 檔案）中的 JSON 資料。

在 JSON Schema 術語中，$schema 和 $id 是綱要關鍵字，title 和 description 是綱要註解，而 type 則是驗證關鍵字。

定義屬性

此部分會加入 properties 關鍵字。在 JSON Schema 術語中，properties 是一個驗證關鍵字。當您定義 properties 時，您會建立一個物件，其中每個屬性都代表正在驗證的 JSON 資料中的一個鍵。您也可以指定物件中定義的哪些屬性是必要的。

新增 properties 物件

使用產品目錄範例，productId 是一個數值，用於唯一識別產品。由於這是產品的標準識別碼，因此是必要的。

將 properties 物件新增至綱要

  1. 將 properties 驗證關鍵字新增至綱要結尾

    1 ...
2   "title": "Product",
3   "description": "A product from Acme's catalog",
4   "type": "object",
5   "properties": {
6     "productId": {}
7   }

  2. 新增 productId 關鍵字，以及下列綱要註解

    • description：描述 productId 是什麼。在此案例中，它是產品的唯一識別碼。

    • type：定義預期的資料類型。在此範例中，由於產品識別碼是數值，因此請使用 integer。

      1...
2  "properties": {
3    "productId": {
4      "description": "The unique identifier for a product",
5      "type": "integer"
6    }
7  }

使用新的 properties 驗證關鍵字，整體綱要看起來像這樣

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" } }}

以下範例新增了另一個必要的鍵 productName。此值為字串。

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" } }}

現在，properties 物件包含兩個鍵，分別是 productId 和 productName。當 JSON 資料針對此 schema 進行驗證時，如果任何文件中在這兩個欄位中包含無效資料，驗證將會失敗。

定義必要屬性

本節說明如何指定某些屬性為必要屬性。此範例將兩個現有的鍵設為必要，並新增另一個名為 price 的必要鍵。price 鍵與其他鍵一樣，具有 description 和 type，但它也指定了最小值。由於商店中沒有任何東西是免費的，因此每項產品都需要一個大於零的價格值。請使用 exclusiveMinimum 驗證關鍵字來定義此最小值。

定義必要屬性的步驟

  1. 在 properties 物件中，加入 price 鍵。包含通常的 schema 註解 description 和 type，其中 type 是一個數字。

    1   "properties": {
2     ...
3     "price": {
4       "description": "The price of the product",
5       "type": "number"
6     }
7   }

  2. 加入 exclusiveMinimum 驗證關鍵字，並將其值設定為零。

    1   "price": {
2     "description": "The price of the product",
3     "type": "number",
4     "exclusiveMinimum": 0
5   }

  3. 在 schema 的結尾，properties 物件之後，加入 required 驗證關鍵字。將 productID、productName 和新的 price 鍵加入到陣列中。

    1 ...
2   "properties": {
3     ...
4     "price": {
5       "description": "The price of the product",
6       "type": "number",
7       "exclusiveMinimum": 0
8     },
9   },
10   "required": [ "productId", "productName", "price" ]

有了新的 required 關鍵字和 price 鍵，整體 schema 看起來像這樣。

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 } }, "required": [ "productId", "productName", "price" ]}

exclusiveMinimum 驗證關鍵字設定為零，這表示只有大於零的值才被視為有效。若要將零包含為有效選項，您可以使用 minimum 驗證關鍵字來代替。

定義選填屬性

本節描述如何定義一個選填屬性。在此範例中，使用以下條件定義一個名為 tags 的關鍵字

  • tags 關鍵字是選填的。
  • 如果包含 tags，則它必須包含至少一個項目。
  • 所有標籤都必須是唯一的。
  • 所有標籤都必須是文字。

若要定義選填屬性

  1. 在 properties 物件中，加入 tags 關鍵字。包含通常的 schema 註解 description 和 type，並將 type 定義為陣列。

    1 ...
2   "properties": {
3     ...
4     "tags": {
5       "description": "Tags for the product",
6       "type": "array"
7     }
8   }

  2. 加入一個新的 items 驗證關鍵字，以定義陣列中的內容。例如，string。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       }
8     }

  3. 為確保陣列中至少有一個項目，請使用 minItems 驗證關鍵字。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1
9     }

  4. 為確保陣列中的每個項目都是唯一的，請使用 uniqueItems 驗證關鍵字，並將其設定為 true。

    1 ...
2     "tags": {
3       "description": "Tags for the product",
4       "type": "array",
5       "items": {
6         "type": "string"
7       },
8       "minItems": 1,
9       "uniqueItems": true
10     }

有了新的 tags 關鍵字，整體 schema 看起來像這樣。

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true } }, "required": [ "productId", "productName", "price" ]}

由於新的關鍵字不是必填的，因此 required 區段沒有任何變更。

建立巢狀資料結構

先前的範例描述了只有一層的平面 schema。本節描述如何在 JSON Schema 中使用巢狀資料結構。

若要建立巢狀資料結構

  1. 在 properties 物件中，建立一個名為 dimensions 的新鍵。

    1 ...
2   "properties": {
3   ...
4     "dimensions": {}
5   }

  2. 將 type 驗證關鍵字定義為 object。

    1 ...
2   "dimensions": {
3     "type": "object"
4   }

  3. 加入 properties 驗證關鍵字，以包含巢狀資料結構。在新 properties 關鍵字中，加入 length、width 和 height 的關鍵字，這些關鍵字都使用 number 類型。

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     }
15   }

  4. 為了使這些屬性都是必填的，請在 dimensions 物件內加入 required 驗證關鍵字。

    1 ...
2   "dimensions": {
3     "type": "object",
4     "properties": {
5       "length": {
6         "type": "number"
7       },
8       "width": {
9         "type": "number"
10       },
11       "height": {
12         "type": "number"
13       }
14     },
15     "required": [ "length", "width", "height" ]
16 }

使用新的巢狀資料結構，整體 schema 看起來像這樣。

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] } }, "required": [ "productId", "productName", "price" ]}

新的 required 驗證關鍵字僅適用於 dimensions 鍵的範圍內。

加入外部參照

本節描述如何參照 schema 外部的資源。在許多資料結構之間共享 schema 是使其更容易使用、閱讀和保持最新的常見方法。到目前為止，產品目錄 schema 是獨立的。本節將建立一個新的 schema，然後在產品目錄 schema 中參照它。

以下 schema 驗證地理位置

綱要
{ "$id": "https://example.com/geographical-location.schema.json", "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "title": "Longitude and Latitude", "description": "A geographical coordinate on a planet (most commonly Earth).", "required": [ "latitude", "longitude" ], "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } }}

若要在產品目錄 schema 中參照此 schema

  1. 在 properties 物件中，加入一個名為 warehouseLocation 的鍵。

    1 ...
2   "properties": {
3   ...
4     "warehouseLocation": {}
5   }

  2. 若要連結到外部地理位置 schema，請加入 $ref schema 關鍵字和 schema URL。

    1 ...
2   "warehouseLocation": {
3     "description": "Coordinates of the warehouse where the product is located.",
4     "$ref": "https://example.com/geographical-location.schema.json"
5   }

有了外部 schema 參照，整體 schema 看起來像這樣。

綱要
{ "$schema": "https://json-schema.dev.org.tw/draft/2020-12/schema", "$id": "https://example.com/product.schema.json", "title": "Product", "description": "A product from Acme's catalog", "type": "object", "properties": { "productId": { "description": "The unique identifier for a product", "type": "integer" }, "productName": { "description": "Name of the product", "type": "string" }, "price": { "description": "The price of the product", "type": "number", "exclusiveMinimum": 0 }, "tags": { "description": "Tags for the product", "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "dimensions": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "warehouseLocation": { "description": "Coordinates of the warehouse where the product is located.", "$ref": "https://example.com/geographical-location.schema.json" } }, "required": [ "productId", "productName", "price" ]}

根據 schema 驗證 JSON 資料

現在您有了 JSON Schema，是時候使用 JSON 資料，根據它使用 JSON Schema 驗證器 進行驗證。

驗證器是一個實作 JSON Schema 規格的工具。所有驗證器都以類似的方式運作：它們將 JSON Schema 和 JSON 實例作為輸入，並將驗證結果作為輸出傳回。

How JSON Schema works

若要親自試試，請瀏覽 工具 並選取最符合您需求的驗證器，或使用以下提供的編輯器來探索不同的 Schema 和實例，並查看不同的驗證結果。

JSON Schema

1

JSON 實例

1

驗證結果

red cross

下一步是什麼？

現在您知道如何建立 JSON Schema 並使用它來驗證 JSON 資料，我們邀請您繼續您的 JSON Schema 之旅。

  • 瀏覽 參考文件，深入了解 JSON Schema。
  • 探索最新版本規格 2020-12 的詳細資訊。

如果您已經知道如何建立 JSON Schema，並且正在尋找不同的 JSON Schema 用例，例如綱要生成、程式碼生成、文件、UI 生成或 JSON Schema 處理或轉換，請造訪工具並探索 JSON Schema 生態系統中提供的驚人工具。

需要協助？

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

幫助我們讓文件變得更好！

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

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

仍然需要協助？

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

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