JSON Toolkit

Mengesahkan YAML dengan JSON Schema: keselamatan bersarang untuk fail konfigurasi

Inti pati: Fail YAML yang di-parse tanpa ralat belum tentu fail yang betul: country: NO bukan rentetan bagi penghurai YAML 1.1, dan version: 1.10 senyap menjadi terapung 1.1. Panduan ini menerangkan mengapa JSON Schema boleh mengesahkan YAML, cara CLI dan editor untuk memasangnya, bagaimana satu schema boleh menahan insiden sebenar kod negara Norway, dan tiga batasan pengesahan berasaskan schema.

Pertengahan~6 min bacaanDiterbitkan 2026-11-13Dikemas kini 2026-11-13
Rajah yang menggambarkan pengesahan fail konfigurasi YAML dengan JSON Schema

Rumusan: YAML 1.2 ialah superset ketat JSON, jadi JSON Schema mengesahkan struktur data selepas parsing, bukan format fail — tulis schema sekali dan ia meliputi data JSON dan YAML. Justru itulah ia mampu menahan insiden apabila penghurai senyap menukar jenis.

yaml.safe_load tanpa ralat hanya membuktikan fail itu YAML sah. Ia tidak membuktikan country: NO masih rentetan — di bawah penghurai YAML 1.1 ia sudah menjadi false jauh sebelum kod anda melihat fail itu.

Satu: parsing tanpa ralat ≠ konfigurasi betul — dahulu, insiden sebenar

Sebuah pasukan e-commerce menambah Norway ke senarai negara penghantaran: satu baris, NO, dalam senarai di group_vars Ansible. Disemak, disahkan, dideploy. Seminggu kemudian: sifar pesanan Norway — fail JSON di pelayan mengandungi "DK", false, "SE". Ansible mem-parse fail pemboleh ubahnya dengan PyYAML, penghurai YAML 1.1: NO menjadi boolean false sejak fail dibaca, dan penapis to_json menulisnya setia. Templat dirender, JSON sah, tiada siapa merungut — hanya perkhidmatan checkout terus menolak setiap pelanggan Norway kerana NO tiada dalam senarai.

Benang merah insiden begini: semua alatan sintaks hijau sedangkan lapisan data sudah salah. Jadual berikut menunjukkan hanyut jenis yang diukur dengan PyYAML 6.0.3; penghurai YAML 1.2 hanya membetulkan sebahagian:

Anda tulis YAML 1.1 baca YAML 1.2 baca Anda mahu
country: NO false "NO" "NO"
version: 1.10 terapung 1.1 terapung 1.1 "1.10"
zip: 02134 oktal 1116 perpuluhan 2134 "02134"
mode: 0755 perpuluhan 493 perpuluhan 755 493 atau "0755"
ports: ["22:22"] seksagesimal 1342 "22:22" "22:22"

Ubat paling menyeluruh: beri petikan pada setiap rentetan yang kelihatan seperti kod. Tetapi petikan bertunjang pada ingatan manusia; schema bertunjang pada semakan mesin — sebab itu YAML berhak mendapat JSON Schema.

Dua: mengapa JSON Schema boleh mentadbir YAML

Spesifikasi YAML 1.2 menyatakannya jelas: matlamat utama 1.2 ialah menjadikan YAML superset ketat JSON, dan penghurai 1.2 membaca JSON biasa tanpa perubahan. Kedua-dua format di-parse ke struktur data yang sama, jadi sambungan fail tiada makna bagi pengesah. Keseluruhan pipeline hanya tiga langkah:

  1. Parse fail YAML kepada objek/array;
  2. Muatkan JSON Schema;
  3. Sahkan data terhadap schema — ralat atau lulus.

Perhatikan langkah satu tidak mensyaratkan serialisasi YAML kepada teks JSON lalu di-parse semula; pustaka YAML bahasa anda meneruskan struktur terus kepada pengesah. Schema itu sendiri juga boleh ditulis dalam YAML (yq -P schema.json > schema.yaml menukar dalam satu arahan), tetapi menyimpannya dalam JSON ialah pilihan paling selamat: keserasian alatan lebih baik dan semua schema dalam katalog schemastore.org adalah JSON.

Tiga: tiga laluan CLI yang berfungsi hari ini

Ambil satu config.yaml yang schema mensyaratkan name dan version, memaksa bentuk semver dan countries sebagai array rentetan dua huruf besar:

# 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 tulen (yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# Atau check-jsonschema, yang menerima YAML terus
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

Ketiga-tiga laluan hanya berbeza pada langkah parsing: dua laluan pertama jelas, dua baris; pipeline mengalir satu arus; dan check-jsonschema membuat penukaran YAML→JSON di dalam. Fail schema sama untuk ketiga-tiga.

Empat: pengesahan masa nyata dalam editor: modeline dan SchemaStore

Sambungan YAML Red Hat (berasaskan yaml-language-server) mencatat kira-kira 30 juta pemasangan dalam VS Code dan menyokong JSON Schema draft-04/07/2019-09/2020-12. Tiga cara untuk menghubungkannya:

# Opsyen 1: modeline — baris pertama fail menunjuk ke schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Opsyen 2 dan 3: .vscode/settings.json, mengikut nama fail atau glob
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

yaml.schemaStore.enable dihidupkan secara lalai: fail lazim seperti package.json, workflow GitHub atau docker-compose dikaitkan secara automatik dengan katalog schemastore.org, tanpa sebarang konfigurasi. Medan description schema menjadi bantuan autolengkap dan tooltip, dan sifat required yang hilang digaris bawah merah — ralat konfigurasi berpindah daripada "debug selepas deploy" kepada "semasa anda menaip". Ini juga menjelaskan mengapa SchemaStore dan bukan "standard schema untuk YAML": YAML tidak mempunyai standard schema rasmi, dan JSON Schema ialah standard de facto.

Lima: bagaimana schema boleh menahan masalah Norway

Kembali ke insiden NO pada seksyen satu. Beri countries schema pada tahap elemen:

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

false yang dihasilkan PyYAML bukan rentetan, jadi type: string jatuh serta-merta; malah jika penghurai membacanya sebagai "no" huruf kecil, pattern menghalangnya. Untuk kawalan lebih rapi, tambah senarai putih enum. Schema yang sama berjalan dalam CI melalui laluan CLI seksyen tiga dan dalam editor melalui modeline seksyen empat — satu kontrak di kedua-dua hujung.

Pembahagian kerja dengan yamllint berbalas satu ayat: peraturan truthy yamllint (hanya true/false diterima, ejaan boolean lain dilaporkan) mentadbir gaya penulisan dan menahan flag: yes di lapisan lint; JSON Schema mentadbir bentuk data, apa pun penghurai. Pasukan dalam insiden itu akhirnya mengambil ketiga-tiga: petikan pada rentetan, yamllint truthy dalam pipeline, dan penegasan rentetan dua huruf dalam templat. Dua lapis pertahanan tidak bertindih — mereka saling melengkapkan.

Enam: pengesahan kelompok manifest Kubernetes

API Kubernetes sendiri dideskripsikan dalam OpenAPI, dan projek kubernetes-json-schema mengubahnya menjadi JSON Schema standard. Kubeconform menggunakan daftar itu untuk pengesahan kelompok: pada komputer riba 4 teras, 35 139 fail dan 50 714 sumber dengan kubeconform -ignore-missing-schemas -n 8 -summary selesai dalam 6.7 saat, berbanding 35 saat kubeval untuk tugas yang sama. Gerak Helm standard: render dahulu, sahkan kemudian:

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

-strict menolak medan yang tidak ditakrifkan schema (kesilapan taip kelihatan awal); sumber CRD boleh dilangkau dengan -ignore-missing-schemas atau disediakan daripada daftar tersuai melalui -schema-location.

Tujuh: apa yang pengesahan schema tidak mampu: tiga batasan

  1. Hanyut versi penghurai berlaku semasa parsing. Schema melihat hasil parsing: NO yang dibaca PyYAML sudah false, dan schema hanya mampu mengunci nilai salah itu dengan type/pattern. Ubat menyeluruh kekal petikan; jangan berharap schema membaiki penghurai.
  2. Ralat logik di luar perimeter. Kesilapan taip dalam selector atau selector K8s yang menunjuk label tiada — schema tahu bentuk, bukan semantik. Itu wilayah admission webhooks, polisi OPA atau kubectl apply --dry-run=server.
  3. Kunci pendua menang senyap. Banyak penghurai YAML menerima kunci pendua tanpa amaran (yang terakhir menang), jadi schema menerima data yang sudah kehilangan satu kunci. Peraturan key-duplicates yamllint atau pengait parsing kekal sebagai pengesan.

Senarai semak sebelum deploy: petikan pada rentetan seumpama kod → jalankan yamllint (truthy + key-duplicates) → pengesahan JSON Schema sama ada dalam CI mahupun editor → bagi sumber kluster, tambah --dry-run=server. Dengan empat langkah ini, insiden Norway pada seksyen satu tidak hidup sampai langkah kedua pipeline.

FAQ

Bolehkah JSON Schema mengesahkan fail YAML secara langsung?

Boleh — tetapi ia mengesahkan data yang fail di-parse, bukan fail itu sendiri. YAML 1.2 superset ketat JSON, kedua-dua di-parse ke struktur sama, jadi satu schema berkhidmat untuk JSON dan YAML. Pilih satu daripada empat laluan — Python, Node, pipeline yq atau check-jsonschema — tanpa menukar format secara manual.

Apakah SchemaStore dan cara menggunakannya?

schemastore.org ialah katalog JSON Schema (catalog.json) yang menghimpun schema ratusan fail konfigurasi lazim: package.json, workflow GitHub, docker-compose dan sebagainya. Editor dengan sokongan YAML/JSON mengaitkan fail ke katalog ini secara automatik, atau anda boleh memetakan URL secara manual dalam yaml.schemas. Schema projek sendiri juga boleh dihantar ke katalog.

Adakah yamllint dan JSON Schema bertindih?

Tidak. yamllint menyemak gaya penulisan (indentasi, panjang baris, truthy, kunci pendua) pada tahap teks; JSON Schema menyemak struktur data (jenis, required, enum, pattern) pada tahap data. Senarai pembetulan insiden Norway menggunakan kedua-duanya: peraturan truthy menahan ejaan seperti flag: yes, manakala schema menahan false yang mendarat dalam array rentetan.

Untuk Kubernetes: kubeconform atau kubectl dry-run?

Dua kerja berbeza. Kubeconform beroperasi luar talian dan berkelompok, tanpa kluster, tempatnya dalam CI untuk menangkap ralat berstruktur; dry-run=server bercakap dengan pelayan API sebenar dan mendedahkan masalah admission webhook dan kuota, tetapi memerlukan akses kluster. Gabungan standard: kubeconform dalam CI, kemudian satu laluan --dry-run=server sebelum deploy — kekalkan kedua-dua lapis.


Selepas menulis schema, tampal JSON yang ditukar daripada YAML anda ke pengesah JSON dalam talian untuk melihat ralat dahulu; untuk menulis kata kunci schema, lihat panduan JSON Schema; untuk menjaga schema dijaga ujian dalam CI, baca ujian kontrak JSON Schema; untuk penukaran harian JSON↔YAML, gunakan penukar JSON YAML XML.