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

結論: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 之後是同一種資料結構,「檔案副檔名是什麼」對校驗器毫無意義。整條鏈路只有三步:
- parse YAML 檔案,得到物件/陣列;
- 載入 JSON Schema;
- 用 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 校驗不了什麼:三條邊界
- 解析器版本差異發生在 parse 層。schema 看到的是 parse 結果:PyYAML 讀出來的
NO已經是false,schema 只能靠type/pattern把這個假值兜住,治本仍然是把值加引號。別指望 schema 修解析器。 - 邏輯錯誤管不了。selector 和 labels 拼錯、K8s 裡 selector 指向不存在的 label,schema 只認形狀不認語意——這類錯誤要靠 admission webhook、OPA 策略或
kubectl apply --dry-run=server兜底。 - 重複鍵靜默勝出。很多 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 互轉工具。