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