JSON Toolkit

Xác thực YAML bằng JSON Schema: lưới an toàn cho file cấu hình

Kết luận: Một file YAML parse không lỗi chưa chắc là file đúng: country: NO không phải chuỗi với parser YAML 1.1, và version: 1.10 âm thầm trở thành số thực 1.1. Bài hướng dẫn này giải thích vì sao JSON Schema có thể xác thực YAML, các cách CLI và editor để triển khai, một schema đã chặn được sự cố thật với mã quốc gia Na Uy thế nào, và ba giới hạn của việc xác thực bằng schema.

Trung cấpĐọc khoảng 6 phútXuất bản 2026-11-13Cập nhật 2026-11-13
Sơ đồ minh họa xác thực file cấu hình YAML bằng JSON Schema

Kết luận: YAML 1.2 là tập con chặt của JSON theo chiều ngược — nói đúng hơn, nó là siêu tập chặt của JSON, nên JSON Schema xác thực cấu trúc dữ liệu sau khi parse, không phải định dạng file — viết schema một lần và nó bao phủ cả dữ liệu JSON lẫn YAML. Chính vì thế mà nó chặn được các sự cố khi parser âm thầm đổi kiểu.

Một yaml.safe_load không lỗi chỉ chứng minh file là YAML hợp lệ. Nó không chứng minh country: NO vẫn là chuỗi — dưới parser YAML 1.1 nó đã là false từ lâu trước khi code của bạn nhìn thấy file.

Một: parse không lỗi ≠ cấu hình đúng — trước hết, một sự cố có thật

Một đội e-commerce thêm Na Uy vào danh sách quốc gia giao hàng: một dòng, NO, trong một list ở group_vars của Ansible. Đã review, đã validate, đã deploy. Một tuần sau: không đơn hàng Na Uy nào — file JSON trên server chứa "DK", false, "SE". Ansible parse file biến bằng PyYAML, một parser YAML 1.1: NO đã thành boolean false ngay từ lúc đọc file, và filter to_json ghi lại trung thành. Template render xong, JSON hợp lệ, chẳng ai phàn nàn — chỉ có dịch vụ checkout tiếp tục từ chối từng khách Na Uy vì NO không có trong danh sách.

Điểm chung của những sự cố này: mọi công cụ cú pháp đều xanh trong khi lớp dữ liệu đã sai. Bảng dưới cho thấy trôi kiểu đo được trên PyYAML 6.0.3; các parser YAML 1.2 chỉ sửa được một phần:

Bạn viết YAML 1.1 đọc YAML 1.2 đọc Bạn muốn
country: NO false "NO" "NO"
version: 1.10 số thực 1.1 số thực 1.1 "1.10"
zip: 02134 bát phân 1116 thập phân 2134 "02134"
mode: 0755 thập phân 493 thập phân 755 493 hoặc "0755"
ports: ["22:22"] thập lục phân-giờ 1342 "22:22" "22:22"

Cách chữa tận gốc: đặt ngoặc kép cho mọi chuỗi giống code. Nhưng ngoặc kép dựa vào trí nhớ con người; schema dựa vào kiểm tra của máy — vì thế YAML xứng đáng có JSON Schema.

Hai: vì sao JSON Schema có thể cai quản YAML

Đặc tả YAML 1.2 nói thẳng: mục tiêu chính của 1.2 là biến YAML thành siêu tập chặt của JSON, và parser 1.2 đọc JSON thường không thay đổi. Cả hai định dạng parse về cùng cấu trúc dữ liệu, nên phần mở rộng file chẳng có ý nghĩa gì với validator. Toàn bộ pipeline chỉ gồm ba bước:

  1. Parse file YAML thành object/array;
  2. Nạp JSON Schema;
  3. Xác thực dữ liệu theo schema — lỗi hoặc qua.

Lưu ý bước một không đòi hỏi serialize YAML thành văn bản JSON rồi parse lại; thư viện YAML của ngôn ngữ bạn truyền cấu trúc thẳng cho validator. Chính schema cũng có thể viết bằng YAML (yq -P schema.json > schema.yaml chuyển trong một lệnh), nhưng giữ nó ở JSON là lựa chọn an toàn hơn: tương thích công cụ tốt hơn và toàn bộ schema trong danh mục schemastore.org đều là JSON.

Ba: ba đường CLI dùng được ngay hôm nay

Lấy một config.yaml mà schema yêu cầu name và version, bắt buộc dạng semver và countries là mảng chuỗi hai chữ cái in hoa:

# 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);

Pipeline thuần (yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# Hoặc check-jsonschema, vốn nhận YAML trực tiếp
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

Ba đường chỉ khác nhau ở bước parse: hai đường đầu tường minh, hai dòng lệnh; pipeline chảy trong một dòng; còn check-jsonschema làm việc chuyển đổi YAML→JSON bên trong. File schema giống nhau cho cả ba.

Bốn: xác thực thời gian thực trong editor: modeline và SchemaStore

Extension YAML của Red Hat (dựa trên yaml-language-server) có khoảng 30 triệu lượt cài trên VS Code và hỗ trợ JSON Schema draft-04/07/2019-09/2020-12. Ba cách gắn vào:

# Cách 1: modeline — dòng đầu tiên của file trỏ tới schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Cách 2 và 3: .vscode/settings.json, theo tên file hoặc glob
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable mặc định bật: các file quen thuộc như package.json, GitHub workflow hay docker-compose được gán tự động vào danh mục schemastore.org, không cần cấu hình gì. Các trường description của schema thành gợi ý tự hoàn thành và tooltip, còn thuộc tính required thiếu bị gạch đỏ — lỗi cấu hình chuyển từ "debug sau khi deploy" sang "ngay khoảnh khắc bạn gõ phím". Điều này cũng giải thích vì sao là SchemaStore chứ không phải một "chuẩn schema cho YAML": YAML không có chuẩn schema chính thức, và JSON Schema là chuẩn trên thực tế.

Năm: một schema đã chặn được vấn đề Na Uy thế nào

Quay lại sự cố NO ở mục một. Cho countries một schema ở mức phần tử:

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

false mà PyYAML sinh ra không phải chuỗi, nên type: string sập ngay; kể cả parser đọc được là "no" chữ thường, pattern cũng chặn. Muốn chặt hơn nữa, thêm whitelist enum. Cùng một schema chạy trong CI qua các đường CLI của mục ba và trong editor qua modeline của mục bốn — một hợp đồng ở cả hai đầu.

Phân công với yamllint đáng một câu: luật truthy của yamllint (chỉ chấp nhận true/false, cách viết boolean khác nào cũng bị báo) cai quản phong cách viết và chặn flag: yes ở tầng lint; JSON Schema cai quản hình dạng dữ liệu, bất kể parser. Đội trong sự cố cuối cùng áp cả ba: ngoặc kép cho chuỗi, yamllint truthy trong pipeline và kiểm tra chuỗi hai chữ cái trong template. Hai tầng phòng thủ không chồng lên nhau — chúng bổ sung cho nhau.

Sáu: xác thực hàng loạt manifest Kubernetes

Chính API Kubernetes được mô tả bằng OpenAPI, và dự án kubernetes-json-schema chuyển nó thành JSON Schema chuẩn. Kubeconform dùng kho này để xác thực hàng loạt: trên laptop 4 nhân, 35.139 file và 50.714 resource với kubeconform -ignore-missing-schemas -n 8 -summary xong trong 6,7 giây, so với 35 giây của kubeval cho cùng việc. Đòn Helm tiêu chuẩn: render trước, validate sau:

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

-strict loại bỏ trường schema không định nghĩa (lỗi gõ thấy sớm); resource CRD có thể bỏ qua bằng -ignore-missing-schemas hoặc cấp từ kho riêng qua -schema-location.

Bảy: việc xác thực bằng schema không làm được: ba giới hạn

  1. Trôi phiên bản parser xảy ra ở bước parse. Schema chỉ thấy kết quả parse: NO mà PyYAML đọc đã là false, schema chỉ có thể khóa giá trị sai này bằng type/pattern. Cách chữa tận gốc vẫn là ngoặc kép; đừng mong schema sửa parser.
  2. Lỗi logic nằm ngoài phạm vi. Một selector gõ sai hoặc K8s selector trỏ tới label không tồn tại — schema biết hình dạng, không biết ngữ nghĩa. Đó là lãnh địa của admission webhooks, chính sách OPA hay kubectl apply --dry-run=server.
  3. Khóa trùng thắng trong im lặng. Nhiều parser YAML nhận khóa trùng không cảnh báo (thắng khóa sau), nên schema nhận dữ liệu đã mất một khóa. Luật key-duplicates của yamllint hay hook parse vẫn là các detector.

Checklist trước khi deploy: ngoặc kép cho chuỗi giống code → chạy yamllint (truthy + key-duplicates) → xác thực JSON Schema cả trong CI lẫn editor → với resource của cluster, thêm --dry-run=server. Với bốn bước này, sự cố Na Uy ở mục một không sống nổi đến bước hai của pipeline.

FAQ

JSON Schema có xác thực trực tiếp file YAML không?

Có — nhưng nó xác thực dữ liệu mà file parse ra, không phải file. YAML 1.2 là siêu tập chặt của JSON, cả hai parse về cùng cấu trúc, nên một schema phục vụ cho cả JSON và YAML. Chọn một trong bốn đường — Python, Node, pipeline yq hay check-jsonschema — không phải chuyển đổi định dạng tay.

SchemaStore là gì và dùng thế nào?

schemastore.org là danh mục JSON Schema (catalog.json) gom schema của hàng trăm file cấu hình thông dụng: package.json, GitHub workflow, docker-compose v.v. Các editor hỗ trợ YAML/JSON tự gán file vào danh mục này, hoặc bạn có thể map URL thủ công trong yaml.schemas. Bạn cũng có thể nộp schema dự án riêng vào danh mục.

yamllint và JSON Schema có trùng nhau không?

Không. yamllint kiểm tra phong cách viết (thụt lề, độ dài dòng, truthy, khóa trùng) ở tầng văn bản; JSON Schema kiểm tra cấu trúc dữ liệu (kiểu, required, enum, pattern) ở tầng dữ liệu. Danh sách sửa lỗi của sự cố Na Uy dùng cả hai: luật truthy chặn cách viết như flag: yes, còn schema chặn một false lạc vào mảng chuỗi.

Với Kubernetes: kubeconform hay kubectl dry-run?

Hai nghề khác nhau. Kubeconform chạy offline và theo lô, không cần cluster, chỗ của nó là CI để bắt lỗi cấu trúc; dry-run=server nói chuyện với API server thật và bộc lộ vấn đề admission webhook và quota, nhưng cần quyền vào cluster. Kết hợp chuẩn: kubeconform trong CI, rồi một lượt --dry-run=server trước deploy — giữ cả hai tầng.


Viết xong schema, dán JSON chuyển từ YAML của bạn vào công cụ xác thực JSON online để thấy lỗi trước; để viết từ khóa của schema, xem hướng dẫn JSON Schema; để giữ schema được test trong CI canh chừng, đọc kiểm thử hợp đồng JSON Schema; để chuyển đổi JSON↔YAML hằng ngày, dùng công cụ chuyển đổi JSON YAML XML.