用 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 互转工具。