Memvalidasi YAML dengan JSON Schema: jaring pengaman file konfigurasi
Intinya: File YAML yang di-parse tanpa error belum tentu file yang benar: country: NO bukan string bagi parser YAML 1.1, dan version: 1.10 senyap menjadi float 1.1. Panduan ini menjelaskan mengapa JSON Schema dapat memvalidasi YAML, cara CLI dan editor untuk memasangnya, bagaimana sebuah schema akan menangkap insiden nyata kode negara Norwegia, serta tiga batasan validasi berbasis schema.

Kesimpulan: YAML 1.2 adalah superset ketat dari JSON, jadi JSON Schema memvalidasi struktur data setelah parsing, bukan format file — tulis schema sekali dan ia mencakup data JSON maupun YAML. Justru karena itulah ia mampu menangkap insiden ketika parser mengubah tipe secara senyap.
yaml.safe_loadtanpa error hanya membuktikan file itu YAML yang sah. Ia tidak membuktikancountry: NOmasih string — di bawah parser YAML 1.1 sudah menjadifalsejauh sebelum kode Anda melihat file itu.
Satu: parse tanpa error ≠ konfigurasi benar — dulu, insiden nyata
Sebuah tim e-commerce menambahkan Norwegia ke daftar negara pengiriman: satu baris, NO, dalam sebuah list di group_vars Ansible. Direview, divalidasi, dideploy. Seminggu kemudian: nol pesanan Norwegia — file JSON di server berisi "DK", false, "SE". Ansible mem-parse file variabelnya dengan PyYAML, parser YAML 1.1: NO menjadi boolean false sejak file dibaca, dan filter to_json menuliskannya setia. Template berhasil dirender, JSON valid, tak ada yang protes — hanya layanan checkout yang terus menolak setiap pelanggan Norwegia karena NO tak ada dalam daftar.
Benang merah insiden semacam ini: semua alat sintaksis hijau padahal lapisan data sudah salah. Tabel berikut menunjukkan drift tipe yang diukur dengan PyYAML 6.0.3; parser YAML 1.2 hanya memperbaiki sebagian:
| Anda menulis | YAML 1.1 membaca | YAML 1.2 membaca | Anda menginginkan |
|---|---|---|---|
country: NO |
false |
"NO" |
"NO" |
version: 1.10 |
float 1.1 |
float 1.1 |
"1.10" |
zip: 02134 |
oktal 1116 |
desimal 2134 |
"02134" |
mode: 0755 |
desimal 493 |
desimal 755 |
493 atau "0755" |
ports: ["22:22"] |
seksagesimal 1342 |
"22:22" |
"22:22" |
Obat yang menyeluruh: beri tanda kutip pada setiap string yang menyerupai kode. Tapi tanda kutip bertumpu pada ingatan manusia; schema bertumpu pada verifikasi mesin — itulah kenapa YAML layak mendapat JSON Schema.
Dua: mengapa JSON Schema dapat memerintah YAML
Spesifikasi YAML 1.2 menyatakannya jelas: tujuan utama 1.2 adalah menjadikan YAML superset ketat dari JSON, dan parser 1.2 membaca JSON biasa tanpa perubahan. Kedua format di-parse ke struktur data yang sama, sehingga ekstensi file tak berarti apa pun bagi validator. Seluruh pipeline hanya tiga langkah:
- Parse file YAML menjadi objek/array;
- Muat JSON Schema;
- Validasi data terhadap schema — error atau lolos.
Perhatikan langkah satu tidak mensyaratkan serialisasi YAML menjadi teks JSON lalu di-parse lagi; pustaka YAML bahasa Anda meneruskan struktur langsung ke validator. Schema itu sendiri juga bisa ditulis dalam YAML (yq -P schema.json > schema.yaml mengonversi dalam satu perintah), tapi menyimpannya dalam JSON adalah pilihan teraman: kompatibilitas alat lebih baik dan semua schema di katalog schemastore.org berupa JSON.
Tiga: tiga jalur CLI yang sudah berfungsi hari ini
Ambil sebuah config.yaml yang oleh schema disyaratkan memiliki name dan version, bentuk semver, serta countries sebagai array string dua huruf kapital:
# 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 murni (yq + ajv-cli):
yq -o=json config.yaml | ajv validate -s schema.json -d -
# Atau check-jsonschema, yang mengonsumsi YAML langsung
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml
Ketiga jalur hanya berbeda pada langkah parsing: dua jalur pertama eksplisit dalam dua baris, pipeline mengalir satu arus, dan check-jsonschema melakukan konversi YAML→JSON di dalam. File schema sama untuk ketiganya.
Empat: validasi waktu nyata di editor: modeline dan SchemaStore
Ekstensi YAML Red Hat (berbasis yaml-language-server) tercatat sekitar 30 juta instalasi di VS Code dan mendukung JSON Schema draft-04/07/2019-09/2020-12. Tiga cara menghubungkannya:
# Opsi 1: modeline — baris pertama file menunjuk ke schema
# yaml-language-server: $schema=./schema.json
name: checkout
// Opsi 2 dan 3: .vscode/settings.json, berdasar nama file atau glob
{
"yaml.schemas": {
"./schema.json": ["config/*.yaml", "*.config.yaml"],
"https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
}
}
yaml.schemaStore.enable aktif secara bawaan: file umum seperti package.json, workflow GitHub, atau docker-compose otomatis dikaitkan dengan katalog schemastore.org, tanpa konfigurasi apa pun. Field description schema menjadi bantuan autocompletion dan tooltip, properti required yang hilang digarisbawahi merah — error konfigurasi pindah dari "debug setelah deploy" ke "saat Anda mengetik". Ini juga menjelaskan mengapa SchemaStore dan bukan "standar schema untuk YAML": YAML tidak punya standar schema resmi, dan JSON Schema adalah standar de facto.
Lima: bagaimana schema akan menangkap masalah Norwegia
Kembali ke insiden NO pada bagian satu. Beri countries sebuah schema di level elemen:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
false yang dihasilkan PyYAML bukan string, jadi type: string langsung gagal; bahkan bila parser membacanya sebagai "no" huruf kecil, pattern menghentikannya. Untuk kontrol lebih ketat, tambahkan whitelist enum. Schema yang sama berjalan di CI lewat jalur CLI bagian tiga dan di editor lewat modeline bagian empat — satu kontrak di kedua ujung.
Pembagian kerja dengan yamllint layak satu kalimat: aturan truthy yamllint (hanya true/false diterima, ejaan boolean lain dilaporkan) mengatur gaya penulisan dan menangkap flag: yes di lapisan lint; JSON Schema mengatur bentuk data, apa pun parsernya. Tim pada insiden itu akhirnya mengadopsi ketiganya: tanda kutip pada string, yamllint truthy dalam pipeline, dan asersi string dua huruf di template. Dua lapis pertahanan ini tidak tumpang tindih — saling melengkapi.
Enam: validasi batch manifest Kubernetes
API Kubernetes sendiri dideskripsikan dalam OpenAPI, dan proyek kubernetes-json-schema mengonversinya menjadi JSON Schema standar. Kubeconform memakai registri itu untuk validasi batch: pada laptop 4 core, 35.139 file dan 50.714 resource dengan kubeconform -ignore-missing-schemas -n 8 -summary selesai dalam 6,7 detik, dibanding 35 detik kubeval untuk tugas yang sama. Gerakan Helm standar: render dulu, validasi kemudian:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict menolak field yang tidak didefinisikan schema (typo terlihat cepat); resource CRD bisa dilewati dengan -ignore-missing-schemas atau dilayani registri kustom via -schema-location.
Tujuh: apa yang tidak bisa dilakukan validasi schema: tiga batasan
- Drift versi parser terjadi saat parsing. Schema melihat hasil parsing:
NOyang dibaca PyYAML sudahfalse, dan schema hanya bisa mengunci nilai salah itu dengantype/pattern. Obat menyeluruh tetap tanda kutip; jangan berharap schema memperbaiki parser. - Error logis di luar perimeter. Typo pada selector atau K8s selector yang menunjuk label tak ada — schema tahu bentuk, bukan semantik. Itu wilayah admission webhooks, kebijakan OPA, atau
kubectl apply --dry-run=server. - Kunci duplikat menang senyap. Banyak parser YAML menerima kunci duplikat tanpa peringatan (yang terakhir menang), sehingga schema menerima data yang sudah kehilangan satu kunci. Aturan
key-duplicatesyamllint atau hook parsing tetap menjadi detektornya.
Checklist sebelum deploy: tanda kutip pada string mirip kode → jalankan yamllint (truthy + key-duplicates) → validasi JSON Schema baik di CI maupun editor → untuk resource cluster, tambahkan --dry-run=server. Dengan empat langkah ini, insiden Norwegia di bagian satu tak selamat hingga langkah kedua pipeline.
FAQ
Bisakah JSON Schema memvalidasi file YAML langsung?
Bisa — tetapi ia memvalidasi data hasil parse file, bukan file itu sendiri. YAML 1.2 superset ketat dari JSON, keduanya di-parse ke struktur sama, jadi satu schema melayani JSON dan YAML. Pilih salah satu dari empat jalur — Python, Node, pipeline yq, atau check-jsonschema — tanpa mengonversi format secara manual.
Apa itu SchemaStore dan cara memakainya?
schemastore.org adalah katalog JSON Schema (catalog.json) yang menghimpun schema ratusan file konfigurasi umum: package.json, workflow GitHub, docker-compose, dan lain-lain. Editor dengan dukungan YAML/JSON mengaitkan file ke katalog ini otomatis, atau Anda bisa memetakan URL secara manual di yaml.schemas. Schema proyek Anda sendiri juga bisa diserahkan ke katalog.
Apakah yamllint dan JSON Schema tumpang tindih?
Tidak. yamllint memeriksa gaya penulisan (indentasi, panjang baris, truthy, kunci duplikat) di level teks; JSON Schema memeriksa struktur data (tipe, required, enum, pattern) di level data. Daftar perbaikan insiden Norwegia memakai keduanya: aturan truthy menangkap ejaan seperti flag: yes, sementara schema menangkap false yang mendarat di array string.
Untuk Kubernetes: kubeconform atau kubectl dry-run?
Dua profesi berbeda. Kubeconform bekerja offline dan batch, tanpa cluster, tempatnya di CI untuk menangkap error struktural; dry-run=server berbicara dengan API server sungguhan dan mengungkap masalah admission webhook dan kuota, tetapi memerlukan akses cluster. Kombinasi standar: kubeconform di CI, lalu satu putaran --dry-run=server sebelum deploy — pertahankan kedua lapisan.
Setelah menulis schema, tempel JSON yang dikonversi dari YAML Anda ke validator JSON online untuk melihat error lebih dulu; untuk menulis kata kunci schema, lihat panduan JSON Schema; untuk menjaga schema dijaga uji di CI, baca pengujian kontrak JSON Schema; untuk konversi harian JSON↔YAML, gunakan konverter JSON YAML XML.