JSON Schema 驗證完整教學：確保資料正確性
當 API 越來越複雜，如何確保資料的結構和內容符合預期？JSON Schema 提供了一套標準化的方式來描述和驗證 JSON 資料的結構。本文將從基礎概念開始，帶你完整了解 JSON Schema 的使用方法。
什麼是 JSON Schema？
JSON Schema 是一種用來描述 JSON 資料結構的規範。它本身也是一份 JSON 文件，用來定義另一份 JSON 資料應該具備的結構、資料型別和約束條件。
JSON Schema 的主要用途包括：
- 資料驗證 — 檢查 JSON 資料是否符合預期的結構
- API 文件 — 作為 API 輸入輸出的規格說明
- 程式碼生成 — 根據 Schema 自動生成型別定義或資料模型
- 表單生成 — 根據 Schema 自動生成使用者介面
JSON Schema 基本關鍵字
JSON Schema 使用一系列關鍵字來定義資料結構。以下是最常用的關鍵字：
| 關鍵字 | 用途 | 範例值 |
|---|---|---|
type | 定義資料型別 | "string", "number", "object" |
properties | 定義物件的屬性 | 包含各屬性的 Schema |
required | 必填欄位列表 | ["name", "email"] |
minLength | 字串最小長度 | 1 |
maxLength | 字串最大長度 | 255 |
minimum | 數字最小值 | 0 |
maximum | 數字最大值 | 100 |
pattern | 正則表達式驗證 | "^[a-z]+$" |
enum | 限定允許的值 | ["active", "inactive"] |
items | 定義陣列元素的 Schema | 元素的 Schema 定義 |
進階驗證功能
1. 條件驗證
JSON Schema 支援條件邏輯，可以根據某些欄位的值來決定其他欄位的驗證規則。使用 if、then、else 關鍵字可以實現條件驗證。例如，當 type 為 "company" 時，要求 taxId 為必填欄位。
2. 組合驗證
JSON Schema 提供了四個組合關鍵字：
- allOf — 資料必須符合所有指定的 Schema
- anyOf — 資料必須符合至少一個指定的 Schema
- oneOf — 資料必須恰好符合一個指定的 Schema
- not — 資料不能符合指定的 Schema
3. 參照（$ref）
使用 $ref 可以引用其他 Schema 定義，實現結構重用。這在大型 API 中特別有用，可以避免重複定義相同的資料結構。
最佳實踐：將常用的資料結構（如地址、分頁資訊）定義為獨立的 Schema，然後在需要的地方使用 $ref 引用，保持 DRY（Don't Repeat Yourself）原則。
JSON Schema 與 OpenAPI
OpenAPI Specification（以前稱為 Swagger）廣泛使用 JSON Schema 來定義 API 的請求和回應格式。如果你正在開發 REST API，JSON Schema 知識可以直接應用在 OpenAPI 文件中。
OpenAPI 3.1 版本完全支援 JSON Schema Draft 2020-12，使得 API 文件和資料驗證可以無縫整合。
常用的 JSON Schema 驗證工具
| 語言 | 套件 | 說明 |
|---|---|---|
| JavaScript | Ajv | 目前最快的 JSON Schema 驗證器 |
| Python | jsonschema | Python 社群最常用的驗證套件 |
| Java | everit-org/json-schema | 支援 Draft 4-7 的驗證器 |
| Go | xeipuuv/gojsonschema | Go 語言的 JSON Schema 驗證 |
| PHP | justinrainbow/json-schema | PHP 的 JSON Schema 驗證 |
JSON Schema 版本演進
JSON Schema 經歷了多個草案版本的演進：
- Draft 4（2013）— 最廣泛支援的版本
- Draft 6（2017）— 新增
const、contains等 - Draft 7（2018）— 新增
if/then/else條件驗證 - Draft 2019-09 — 重構了詞彙系統
- Draft 2020-12 — 目前最新版本，被 OpenAPI 3.1 採用
開始驗證你的 JSON
在撰寫 Schema 之前，先確保你的 JSON 資料格式正確。使用我們的格式化工具快速檢查：
立即使用 JSON 格式化工具 →結語
JSON Schema 是確保資料品質的強大工具。無論是在 API 開發、資料管線還是表單驗證中，它都能幫助你定義清晰的資料合約，減少因資料格式錯誤導致的問題。投入學習 JSON Schema 的時間，將在長期的專案維護中獲得豐厚回報。
參考文獻
- JSON Schema Organization. "JSON Schema Specification." json-schema.org. https://json-schema.org/specification
- Wright, A. et al. "JSON Schema: A Media Type for Describing JSON Documents." IETF Internet-Draft, 2022. https://json-schema.org/draft/2020-12/json-schema-core
- OpenAPI Initiative. "OpenAPI Specification v3.1.0." OpenAPI, 2021. https://spec.openapis.org/oas/v3.1.0
- Ajv Contributors. "Ajv JSON schema validator." GitHub. https://ajv.js.org/