JSON 工具箱

用 JSON Schema 校驗 YAML:配置檔的類型防線

結論:YAML 解析通過只說明語法沒寫錯,不說明值是對的:country: NO 在 YAML 1.1 解析器裡根本不是字串,version: 1.10 會靜默變成浮點數 1.1。本文講清 JSON Schema 為什麼能校驗 YAML、CLI 與編輯器兩條落地路徑、怎麼用 schema 提前攔住挪威國家碼這類真實事故,以及它管不了的三件事。

進階約 6 分鐘發佈於 2026-11-13更新於 2026-11-13
用 JSON Schema 校驗 YAML 配置檔的類型防線示意圖

結論:YAML 是 JSON 的嚴格超集,所以 JSON Schema 校驗的是 parse 之後的資料結構,而不是檔案格式——schema 寫一次,JSON 資料和 YAML 資料通吃,這正是它能管住「解析器靜默改類型」這類事故的原因。

yaml.safe_load 不報錯,只證明檔案是合法 YAML;不證明 country: NO 還是字串——在 YAML 1.1 解析器裡它早就是 false 了。

一、解析通過 ≠ 配置正確:先看一次真實事故

一家電商團隊把挪威加入配送國家:在 Ansible 的 group_vars 裡往列表加了一行 NO,過 review,上線。一週後挪威 0 訂單——伺服器上的 JSON 檔案裡躺著 "DK", false, "SE"。Ansible 用 PyYAML 讀變數檔,PyYAML 是 YAML 1.1 解析器,NO 從檔案讀進來的那一刻就是布林 false,to_json 忠實地把它寫了出去。模板渲染正常、JSON 合法、沒有任何報錯,只有 checkout 服務在用 NO not in list 拒掉每一個挪威客戶。

這類事故的共同點:語法層工具全綠,資料層已經錯了。下表是 PyYAML 6.0.3 實測的類型漂移,YAML 1.2 解析器只修正其中一部分:

你寫的 YAML 1.1 讀到 YAML 1.2 讀到 想 要
country: NO false "NO" "NO"
version: 1.10 浮點 1.1 浮點 1.1 "1.10"
zip: 02134 八進制 1116 十進制 2134 "02134"
mode: 0755 十進制 493 十進制 755 493 或 "0755"
ports: ["22:22"] 六十進制 1342 "22:22" "22:22"

治本的辦法是所有程式碼類字串加引號。但引號靠人記,Schema 靠機器查——這就是為什麼要給 YAML 配上一套 JSON Schema。

二、為什麼 JSON Schema 能管 YAML

YAML 1.2 規範明說:1.2 的首要目標就是成為 JSON 的嚴格超集,1.2 解析器可以直接讀普通 JSON。既然兩邊 parse 之後是同一種資料結構,「檔案副檔名是什麼」對校驗器毫無意義。整條鏈路只有三步:

  1. parse YAML 檔案,得到物件/陣列;
  2. 載入 JSON Schema;
  3. 用 schema 校驗資料,報錯或通過。

注意第一步不需要真的把 YAML 序列化成 JSON 文字再 parse 一遍,任何語言的 YAML 庫直接給出資料結構就能進校驗器。Schema 本身也可以用 YAML 寫(yq -P schema.json > schema.yaml 一條命令互轉),但建議保持 JSON——工具鏈相容性更好,schemastore.org 目錄裡的所有 schema 也都是 JSON。

三、CLI 三條落地路徑

以一份 config.yaml 為例,schema 要求 name、version 必填,version 必須匹配語意化版本,countries 必須是兩字母大寫字串陣列:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

Python(jsonschema + PyYAML):

import json, yaml
from jsonschema import validate

data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)

Node(js-yaml + Ajv):

import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";

const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);

純管道(yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# 或者 check-jsonschema 直接吃 YAML
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

三條路的差別只在 parse 層:前兩條顯式兩步,管道一條流過去,check-jsonschema 內部替你做了 YAML→JSON。schema 檔案是同一個。

四、編輯器即時校驗:modeline 與 SchemaStore

Red Hat 的 YAML 擴充(基於 yaml-language-server)在 VS Code 裝機量約 3000 萬,支援 JSON Schema draft-04/07/2019-09/2020-12。三種接法:

# 方式一:modeline,檔案第一行指路
# yaml-language-server: $schema=./schema.json
name: checkout
// 方式二/三:.vscode/settings.json,按檔名或 glob 批次關聯
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable 預設開啟:package.json、GitHub workflow、docker-compose 這類常見檔案會被自動關聯到 schemastore.org 的目錄,不用寫一行配置。Schema 裡的 description 會變成補全項說明和 hover 提示,required 的缺失會畫紅線——配置錯誤從「上線後排查」前移到「敲鍵盤的當下」。這也解釋了為什麼是 SchemaStore 而不是某個「YAML Schema 標準」:YAML 官方沒有 schema 標準,JSON Schema 就是那個事實標準。

五、Schema 怎麼提前攔住挪威問題

回到第一節的 NO 事故。給 countries 寫上元素級 schema:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

PyYAML 讀出來的 false 不是字串,type: string 直接判負;即便某個解析器把它讀成了字串 "no"(小寫),pattern 也攔得住。想更嚴可以再加 enum 白名單。同一份 schema 放進 CI 走第三節的 CLI 路徑,放進編輯器走第四節的 modeline,兩頭都是同一個契約。

和 yamllint 的分工也要說清:yamllint 的 truthy 規則(只認 true/false,其餘布林樣拼寫一律告警)管的是寫作風格,在 lint 那一層就把 flag: yes 標出來;JSON Schema 管的是資料形狀,不管你用哪種解析器。事故團隊最終三件套全上:字串加引號 + yamllint truthy 進流水線 + 模板斷言。兩層防線不重複,是互補。

六、批次校驗 Kubernetes 清單

Kubernetes 的 API 本身就用 OpenAPI 描述,kubernetes-json-schema 專案把它轉成了標準 JSON Schema。kubeconform 拿這套 schema 做批次校驗:4 核筆記本上 35139 個檔案、50714 個資源,kubeconform -ignore-missing-schemas -n 8 -summary 用時 6.7 秒,同任務 kubeval 要 35 秒。Helm 使用者的標準動作是先渲染再校驗:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict 會拒絕 schema 裡沒定義的欄位(typo 早暴露),CRD 資源用 -ignore-missing-schemas 跳過或用 -schema-location 掛自訂 schema。

七、Schema 校驗不了什麼:三條邊界

  1. 解析器版本差異發生在 parse 層。schema 看到的是 parse 結果:PyYAML 讀出來的 NO 已經是 false,schema 只能靠 type/pattern 把這個假值兜住,治本仍然是把值加引號。別指望 schema 修解析器。
  2. 邏輯錯誤管不了。selector 和 labels 拼錯、K8s 裡 selector 指向不存在的 label,schema 只認形狀不認語意——這類錯誤要靠 admission webhook、OPA 策略或 kubectl apply --dry-run=server 兜底。
  3. 重複鍵靜默勝出。很多 YAML 解析器對重複鍵不告警(後者贏),schema 收到的資料已經丟了一個鍵,得靠 yamllint 的 key-duplicates 或解析鉤子查。

上線前 checklist:值加引號(程式碼類字串一律引號)→ yamllint(truthy + key-duplicates)→ JSON Schema 校驗(CI + 編輯器雙掛)→ 叢集類資源再過 dry-run=server。四步做完,第一節的挪威事故在這條流水線上活不過第二步。

常見問題

JSON Schema 能直接校驗 YAML 檔案嗎?

能,但校驗的不是「檔案」而是檔案 parse 之後的資料。YAML 1.2 是 JSON 的嚴格超集,兩邊 parse 出同一種資料結構,所以同一份 schema 對 JSON 和 YAML 通用。Python、Node、yq 管道、check-jsonschema 四條路任選,不需要手工先轉一遍格式。

SchemaStore 是什麼,怎麼用?

schemastore.org 是一份 JSON Schema 目錄(catalog.json),收錄了幾百種常見配置檔的 schema:package.json、GitHub workflow、docker-compose 等。編輯器裝上 YAML/JSON 語言支援後預設從它自動關聯,也可以在 yaml.schemas 裡手動映射 URL。自研配置檔可以把自己專案的 schema 提交進目錄。

yamllint 和 JSON Schema 校驗是不是重複了?

不重複。yamllint 查寫作風格(縮排、行寬、truthy、重複鍵),發生在文字層;JSON Schema 查資料結構(類型、必填、枚舉、pattern),發生在資料層。挪威事故的修復清單裡兩個都在:truthy 規則攔 flag: yes 這類拼寫,schema 攔 false 混進字串陣列這類值。

校驗 Kubernetes 清單用 kubeconform 還是 kubectl dry-run?

分工不同。kubeconform 離線批次、不需要叢集,適合塞進 CI 攔結構性錯誤;dry-run=server 走真實 API server,能發現 admission webhook 和配額層的問題,但必須連叢集。標準做法是 CI 裡跑 kubeconform,部署前再過一次 dry-run=server,兩層都不省。


寫完 schema 想先在瀏覽器裡對一對資料合不合规,可以先用 JSON 線上校驗工具 把 YAML 轉出的 JSON 貼進去看報錯;schema 本身怎麼寫關鍵字,見 JSON Schema 完全指南;想讓 schema 在 CI 裡被測試盯住,看 JSON Schema 契約測試;日常 JSON↔YAML 互轉用 JSON YAML XML 互轉工具。

參考資料

相關文章

JSON Schema 從入門到工程化

關鍵字很多,真正天天用的只有十幾個。把 type/properties/required/$ref 用對,再處理好錯誤資訊,就能覆蓋八成場景。

進階約 14 分鐘更新於 2026-10-30

JSON Schema 契約測試:把校驗規則焊進 CI

schema 寫完不改就是壞的起點:一個 typo 讓校驗器靜默放行,一次重構讓 fixture 全線誤報。本文給出一套可落地的契約測試方案——正例、負例、快照三件套,schema 本身先進 lint,編譯一次複用,再把四道閘門焊進 CI,讓契約壞了構建先紅。

實戰約 8 分鐘更新於 2026-11-05

JSON 與 YAML、XML 的互轉邊界

JSON 是 YAML 的子集,這句話只保證了單向成立;而 XML 根本沒有官方 JSON 對映,全靠約定。

進階約 12 分鐘更新於 2026-10-30