JSON Validator、JSON Linter 與 JSON Schema 有什麼不同？一次看懂三者用途

一段 JSON 能被解析，不代表它一定符合 API；Validator 顯示有效，Linter 仍可能提出警告。這些結果並不衝突，因為三者檢查的是不同層次。

JSON Validator 檢查文字是否合法，JSON Linter 檢查品質與一致性，JSON Schema 描述資料必須符合的結構與限制。

> 建議順序：先驗證語法，再執行 Lint，最後依 JSON Schema 驗證資料契約。

先釐清 Validator 的兩種意思

「JSON Validator」可能指兩種工具：語法驗證器使用解析器檢查 JSON 文字；JSON Schema Validator 則接收 Schema 與 JSON Instance，判斷資料是否符合契約。

Json Work 的 JSON Validator主要屬於前者。JSON Schema 官方文件中的 Validator 通常指後者。討論系統時最好明確寫出 syntax validator 或 schema validator，避免雙方用同一個詞描述不同關卡。

JSON Validator：文字能不能解析

RFC 8259定義了 JSON 的物件、陣列、字串、數字、布林值與 null 等語法。以下內容因缺少逗號而無效：

{
  "id": 101
  "name": "Alice"
}

語法驗證器能發現缺少逗號、引號或括號未閉合、非法跳脫、未加雙引號的鍵，以及 undefined、NaN 等不支援的值。

但下面的內容語法完全有效：

{
  "id": "one hundred",
  "email": "not-an-email",
  "active": "yes"
}

Validator 不知道 id 應為整數，也不知道 active 應為布林值。它只回答「這是不是合法 JSON 文字」。語法失敗時可先用 JSON Validator定位；若內容只是接近 JSON，再使用 JSON Repair產生候選修復並人工複核。

JSON Linter：品質是否一致

Lint 是依規則執行的靜態分析。它不像 JSON 語法有單一標準，規則通常由工具或團隊依可維護性與風險制定。

{
  "user_id": 101,
  "userName": "Alice",
  "isActive": "true"
}

這是合法 JSON，但 Linter 可能提示命名風格混用、布林欄位看似使用字串、相同欄位型別不一致或巢狀結構過深。這些是待確認的規則結果，不一定代表資料錯誤；上游契約也可能明確要求字串 "true"。

因此 JSON Linter適合檢查團隊約定與可疑結構，卻不能在沒有契約時證明業務資料錯誤。

JSON Schema：正式定義資料契約

JSON Schema 是描述與限制 JSON 文件的標準化詞彙，可表達型別、必填欄位、陣列元素、長度、範圍、列舉與組合條件。JSON Schema 官方網站將驗證、互通交換與文件化列為主要用途。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "active": { "type": "boolean" }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Schema 是規則文件，不是執行程式。仍需 Ajv 或 Python jsonschema 等 Schema Validator 將它套用至實際 Instance。官方入門教學也明確區分兩者。

實作選項同樣重要，例如 format 依驗證器與設定可能只是註解，而非強制斷言。官方 format 說明特別提醒了這點。

可先用 JSON Schema 產生器從代表性樣本建立初稿，再人工補上範圍、長度、正規表示式、列舉與額外欄位政策。

同一份 API 資料的三種答案

{
  "id": "101",
  "name": "Alice",
  "email": "alice@example.com",
  "active": "true"
}

• • Validator：通過。所有符號與值都符合 JSON 語法。

• • Linter：可能警告。id 與 active 看起來用了可疑字串型別，但無法證明意圖。

• • Schema Validator：失敗。依前述 Schema，id 必須是整數，active 必須是布林值。

語法有效 ≠ 風格一致 ≠ 符合業務契約

完整比較

建議的驗證流程

1. Syntax gate：先確認原始文字可解析。

1. Lint gate：檢查命名、一致性與團隊規則。

1. Schema gate：依明確版本的 Schema 驗證契約。

1. Business gate：處理跨欄位、權限與狀態相關規則。

Schema 無法取代所有業務邏輯，例如「結束時間必須晚於開始時間」或權限判斷通常仍需應用程式處理。

使用 Ajv 驗證 Schema

import Ajv from "ajv";

const schema = {
  type: "object",
  properties: {
    id: { type: "integer" },
    name: { type: "string" },
    active: { type: "boolean" }
  },
  required: ["id", "name"],
  additionalProperties: false
};

const data = { id: "101", name: "Alice", active: true };
const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

if (!validate(data)) console.log(validate.errors);

Ajv 會報告 id 不符合 integer。其官方指南建議編譯一次 Schema 並重複使用驗證函式。若輸入是網路原始文字，仍應先解析 JSON，讓語法錯誤與契約錯誤分開呈現。

常見誤解

• • Validator 通過代表資料完全正確？不是，它只證明語法有效；Schema 通過也只代表符合目前這份契約。

• • 每個 Lint 警告都要修改？不一定，規則應服務明確的團隊約定。

• • 一份樣本生成的 Schema 就是最終契約？不是，單一樣本無法揭露所有選填欄位、範圍與邊界。

• • JSON Schema 可以修復無效 JSON？不能，Schema 負責描述與驗證，不負責補逗號或修引號。

總結

Validator 守住合法語法，Linter 守住品質與一致性，JSON Schema 守住結構與資料契約。可靠做法是依序組合，而不是只選一個。

可以先使用 JSON Validator，再用 JSON Linter檢查品質，最後透過 JSON Schema 產生器建立可維護的資料契約。所有處理都能在瀏覽器本機完成。