JSON Schema 實用範例：驗證常用寫法

一分鐘理解 JSON Schema

JSON Schema 用來描述 JSON 資料的允許結構與規則。語法檢查回答「是否為合法 JSON」；Schema 驗證回答「是否符合我們的資料契約」。

以下範例對齊 Draft 2020-12（見 $schema）。請與你所用驗證器支援的草案一致。

若需複習 JSON 基礎，可先讀 什麼是 JSON？。

最小的 object 範例

Schema — 必填 name（字串）與 age（整數），tags 選填：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/person.min.json",
  "title": "Person",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0 },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["name", "age"]
}

合法實例

{ "name": "Asha", "age": 30, "tags": ["beta"] }

不合法實例（缺少 age，且 additionalProperties: false 禁止未知欄位 extra）

{ "name": "Asha", "extra": true }

字串：長度、pattern、format

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "handle": { "type": "string", "pattern": "^[a-z0-9_]{3,20}$" },
    "contact": { "type": "string", "format": "email" },
    "createdAt": { "type": "string", "format": "date-time" }
  },
  "required": ["handle"]
}

提示： 在核心規格中 format 常作為註解；Ajv 等需外掛才會依格式驗證。未啟用時請把 format 當文件約定。

數值：範圍與倍數

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "qty": { "type": "integer", "minimum": 1, "maximum": 99 },
    "price": { "type": "number", "minimum": 0, "multipleOf": 0.01 }
  },
  "required": ["qty", "price"]
}

整數用 integer，需要小數時用 number。

enum 與 const

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "role": { "type": "string", "enum": ["admin", "editor", "viewer"] },
    "version": { "const": 1 }
  },
  "required": ["role", "version"]
}

陣列：items、長度、唯一性

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "ids": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" },
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true
    }
  },
  "required": ["ids"]
}

anyOf、oneOf、allOf

anyOf — 至少符合一個分支（適合「字串 或 數字」）：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "value": {
      "anyOf": [
        { "type": "string", "minLength": 1 },
        { "type": "number" }
      ]
    }
  },
  "required": ["value"]
}

oneOf — 恰好一個分支（注意分支條件勿重疊）。allOf — 合併所有子 schema 的約束。

用 $defs 與 $ref 重複使用

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {
    "Email": { "type": "string", "format": "email" }
  },
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "owner": { "$ref": "#/$defs/Email" },
    "billing": { "$ref": "#/$defs/Email" }
  },
  "required": ["owner"]
}

additionalProperties 與 API 契約

在根物件使用 additionalProperties: false 有助於抓欄位拼字錯誤。對外 API 通常與明確的 properties、required 一併使用。

常見誤區

• • $ref 片段錯誤或草案不一致會導致無法解析。

• • null 不會自動允許；需要時使用 { "type": ["string", "null"] } 等寫法。

• • oneOf 分支重疊會出現「符合多於一個分支」錯誤。

• • integer 與 number 混用導致小數無法通過整數檢查。

在 JSON Work 中實作

• • 將 schema 與資料貼到 JSON 驗證器，於瀏覽器本機查看驗證結果。

• • 有範例 JSON、想產生初稿 schema 時，可使用 JSON 轉 Schema。

生產環境常使用 Ajv（JavaScript）或 jsonschema（Python）等；務必核對函式庫對所宣告 $schema 草案的支援。