ตรวจสอบ YAML ด้วย JSON Schema: ตาข่ายนิรภัยของไฟล์คอนฟิก
สรุปสำคัญ: ไฟล์ YAML ที่ parse ผ่านโดยไม่มี error ไม่ได้แปลว่าไฟล์ถูกต้อง: country: NO ไม่ใช่สตริงสำหรับ parser YAML 1.1 และ version: 1.10 เปลี่ยนเป็นทศนิยม 1.1 อย่างเงียบ ๆ คู่มือนี้อธิบายว่าทำไม JSON Schema จึงตรวจสอบ YAML ได้ วิธีติดตั้งผ่าน CLI และ editor อย่างไร schema หนึ่งตัวจะดักจับเหตุการณ์จริงของรหัสประเทศนอร์เวย์ และข้อจำกัดสามข้อของการตรวจสอบด้วย schema

สรุป: YAML 1.2 เป็น superset อย่างเข้มงวดของ JSON ดังนั้น JSON Schema ตรวจสอบโครงสร้างข้อมูลหลัง parse ไม่ใช่รูปแบบไฟล์ — เขียน schema ครั้งเดียวและมันครอบคลุมทั้งข้อมูล JSON และ YAML นี่คือเหตุผลที่มันดักจับเหตุการณ์ที่ parser เปลี่ยนชนิดข้อมูลเงียบ ๆ ได้
yaml.safe_loadที่ไม่มี error พิสูจน์เพียงว่าไฟล์เป็น YAML ที่ถูกต้องตามไวยากรณ์ มันไม่ได้พิสูจน์ว่าcountry: NOยังเป็นสตริง — ภายใต้ parser YAML 1.1 มันกลายเป็นfalseไปนานก่อนที่โค้ดของคุณจะเห็นไฟล์นั้น
หนึ่ง: parse ผ่าน ≠ คอนฟิกถูกต้อง — เริ่มจากเหตุการณ์จริง
ทีม e-commerce เพิ่มนอร์เวย์เข้าไปในรายชื่อประเทศที่จัดส่งสินค้า: เพิ่มหนึ่งบรรทัด, NO, ลงใน list ใน group_vars ของ Ansible ผ่านการรีวิว ผ่านการตรวจสอบ และ deploy แล้ว หนึ่งสัปดาห์ต่อมา: คำสั่งซื้อจากนอร์เวย์เป็นศูนย์ — ไฟล์ JSON บนเซิร์ฟเวอร์มีเนื้อหา "DK", false, "SE" Ansible parse ไฟล์ตัวแปรด้วย PyYAML ซึ่งเป็น parser YAML 1.1: NO กลายเป็น boolean false ตั้งแต่ตอนอ่านไฟล์ และ filter to_json ก็เขียนลงไปตามนั้น ขัดจาก template ออกมา JSON ถูกต้องตามรูปแบบ ไม่มีใครร้องเรียน — มีเพียงบริการ checkout ที่ยังคงปฏิเสธลูกค้าชาวนอร์เวย์ทุกราย เพราะ NO ไม่อยู่ในรายการ
จุดร่วมของเหตุการณ์เช่นนี้: เครื่องมือด้านไวยากรณ์ขึ้นสีเขียวทั้งหมด ทั้งที่ชั้นข้อมูลผิดไปแล้ว นั่นคือ การตรวจไวยากรณ์เพียงอย่างเดียวไม่เคยค้นพบความเสียหายเหล่านี้เลย เพราะความผิดพลาดเกิดขึ้นที่ชั้นความหมายของข้อมูล ไม่ใช่ชั้นรูปแบบของไฟล์ และนี่ก็คือเหตุผลที่เราต้องการเครื่องมือที่ทำงานอยู่บนชั้นข้อมูลโดยตรง ตารางด้านล่างแสดงการเลื่อนชนิดข้อมูลที่วัดด้วย PyYAML 6.0.3; parser 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 คือทำให้ YAML เป็น superset อย่างเข้มงวดของ JSON และ parser 1.2 อ่าน JSON ธรรมดาได้โดยไม่เปลี่ยนแปลง ทั้งสองรูปแบบ parse ลงโครงสร้างข้อมูลเดียวกัน ดังนั้นนามสกุลไฟล์จึงไร้ความหมายต่อ validator ทั้งไปป์ไลน์มีแค่สามขั้น:
- Parse ไฟล์ YAML เป็น object/array;
- โหลด JSON Schema;
- ตรวจสอบข้อมูลกับ schema — error หรือผ่าน
สังเกตว่าขั้นแรกไม่ได้บังคับให้ serialize YAML เป็นข้อความ JSON แล้ว parse ซ้ำ; ไลบรารี YAML ของภาษาคุณส่งโครงสร้างตรงเข้า validator นี่คือจุดที่ทำให้หลายคนเข้าใจผิด เพราะคิดว่าต้องแปลงไฟล์ก่อนเสมอ ความจริงคือเครื่องมือจัดการการแปลงภายในเสมอ ตัว schema เองก็เขียนเป็น YAML ได้ (yq -P schema.json > schema.yaml แปลงในหนึ่งคำสั่ง) แต่เก็บเป็น JSON เป็นทางเลือกที่ปลอดภัยกว่า: ความเข้ากันได้ของเครื่องมือดีกว่า และ schema ทั้งหมดในแคตตาล็อก schemastore.org เป็น JSON
สาม: สามเส้นทาง CLI ที่ใช้ได้ตั้งแต่วันนี้
ยกตัวอย่าง config.yaml ที่ schema กำหนดให้มี name และ version บังคับรูปแบบ semver และ 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 ภายในตัวเอง เลือกเส้นทางตามสภาพแวดล้อมของทีมคุณ ถ้าทีมใช้ Python เป็นหลักก็เลือก jsonschema ถ้าทีมเป็นสาย JavaScript ก็ใช้ Ajv ส่วนทีมเอนจิเนียร์ที่ต้องการผสมหลายภาษาใน CI เดียว เส้นทาง yq หรือ check-jsonschema จะสะดวกที่สุด ไฟล์ schema เหมือนกันสำหรับทั้งสามเส้นทาง ดังนั้นเปลี่ยนเครื่องมือได้ตลอดเวลาโดยไม่ต้องแตะไฟล์ schema เลย
สี่: ตรวจสอบแบบเรียลไทม์ใน editor: modeline และ SchemaStore
ส่วนเสริม YAML ของ Red Hat (สร้างบน yaml-language-server) มีการติดตั้งราว 30 ล้านครั้งใน VS Code และรองรับ JSON Schema draft-04/07/2019-09/2020-12 มีสามวิธีเชื่อมต่อ:
# ทางเลือก 1: modeline — บรรทัดแรกของไฟล์ชี้ไปที่ schema
# yaml-language-server: $schema=./schema.json
name: checkout
// ทางเลือก 2 และ 3: .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 โดยอัตโนมัติ ไม่ต้องตั้งค่าอะไรเลย ฟิลด์ description ของ schema กลายเป็นคำใบ้ autocompletion และ tooltip ส่วน property required ที่ขาดหายถูกขีดเส้นใต้สีแดง — ข้อผิดพลาดของคอนฟิกย้ายจาก "debug หลัง deploy" มาเป็น "ขณะที่คุณกำลังพิมพ์" นี่ยังอธิบายด้วยว่าทำไมจึงเป็น SchemaStore ไม่ใช่ "มาตรฐาน schema ของ YAML": YAML ไม่มีมาตรฐาน schema อย่างเป็นทางการ และ JSON Schema คือมาตรฐาน de facto
ห้า: schema หนึ่งตัวจะดักปัญหานอร์เวย์ได้อย่างไร
กลับไปที่เหตุการณ์ NO ในหัวข้อแรก ให้ countries มี schema ระดับสมาชิก:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
false ที่ PyYAML สร้างขึ้นไม่ใช่สตริง ดังนั้น type: string ล้มทันที; แม้ parser จะอ่านได้เป็น "no" ตัวพิมพ์เล็ก pattern ก็หยุดไว้ อยากเข้มขึ้นอีกให้เพิ่ม whitelist enum schema ตัวเดียวกันนี้รันใน CI ผ่านเส้นทาง CLI ของหัวข้อสาม และรันใน editor ผ่าน modeline ของหัวข้อสี่ — สัญญาเดียวทั้งสองปลาย
การแบ่งงานกับ yamllint ควรพูดหนึ่งประโยค: กฎ truthy ของ yamllint (ยอมรับเฉพาะ true/false สะกด boolean แบบอื่นถูกแจ้งเตือน) ครอบงาน สไตล์การเขียน และดัก flag: yes ที่ชั้น lint; JSON Schema ครอบงาน รูปร่างของข้อมูล ไม่ว่า parser ใด ทีมในเหตุการณ์นั้นสุดท้ายใช้ทั้งสามอย่าง: เครื่องหมายคำพูดกับสตริง, yamllint truthy ในไปป์ไลน์ และการตรวจสอบสตริงสองตัวอักษรในเทมเพลต สองชั้นป้องกันนี้ไม่ทับกัน — พวกมันเสริมกัน ถ้าจะสรุปภาพใหญ่ให้เห็นชัดก็คือ yamllint ยืนอยู่ใกล้ผู้เขียนไฟล์มากที่สุด ขณะที่ JSON Schema ยืนอยู่ใกล้ผู้ใช้ไฟล์มากที่สุด และเครื่องหมายคำพูดคือกำแพงแรกสุดที่ข้อมูลต้องผ่านก่อนถึงจุดใด ๆ ข้างต้น เมื่อวางสามชั้นนี้เรียงกันแล้ว ความผิดพลาดแบบนอร์เวย์จะถูกจับได้ตั้งแต่ก่อนถึงมือของผู้ใช้
หก: ตรวจสอบ manifest Kubernetes เป็นล็อต
API ของ Kubernetes เองถูกอธิบายด้วย OpenAPI และโปรเจกต์ kubernetes-json-schema แปลงมันเป็น JSON Schema มาตรฐาน สิ่งนี้ทำให้การตรวจสอบมานิฟสต์เป็นไปได้โดยไม่ต้องติดต่อคลัสเตอร์จริงเลย Kubeconform ใช้คลังนี้ตรวจสอบเป็นล็อต: บนแล็ปท็อป 4 คอร์ ไฟล์ 35,139 ไฟล์และรีซอร์ส 50,714 ชิ้นด้วย kubeconform -ignore-missing-schemas -n 8 -summary จบใน 6.7 วินาที เทียบกับ kubeval ที่ใช้ 35 วินาทีสำหรับงานเดียวกัน ท่า Helm มาตรฐานคือ render ก่อน แล้วตรวจสอบ:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict ปฏิเสธฟิลด์ที่ schema ไม่ได้นิยาม (พิมพ์ผิดเห็นเร็ว); รีซอร์ส CRD ข้ามได้ด้วย -ignore-missing-schemas หรือใช้คลังส่วนตัวผ่าน -schema-location ค่าที่วัดได้ข้างต้นแสดงว่าการตรวจสอบระดับนี้ไม่ได้แพงจนใช้ไม่ได้ในทุกการ build เลย ตรงกันข้าม มันถูกจนเหมาะจะผูกเป็นเกตบันทึกถาวรของไปป์ไลน์ และเมื่อเป็นเกตประจำ ทุกแมนิฟสต์ที่ไม่ผ่าน schema จะไม่มีทางไปถึงคลัสเตอร์จริงเลย
เจ็ด: สิ่งที่การตรวจสอบด้วย schema ทำไม่ได้: สามข้อจำกัด
ก่อนอ่านรายการนี้ ควรตั้งสติว่าข้อจำกัดเหล่านี้ไม่ใช่ข้อบกพร่องของ JSON Schema เอง แต่เป็นธรรมชาติของเครื่องมือที่ทำงานอยู่บนชั้นข้อมูล การรู้ขอบเขตของเครื่องมืออย่างแม่นยำ ช่วยให้ทีมออกแบบแนวป้องกันได้ครบทุกชั้นที่จำเป็น ไม่ใช่คิดว่าใส่ schema แล้วจบทุกปัญหา
- การเลื่อนเวอร์ชันของ parser เกิดที่ขั้น parse schema เห็นแค่ผลลัพธ์ parse:
NOที่ PyYAML อ่านแล้วเป็นfalseไปแล้ว และ schema ทำได้แค่กักค่าผิดนั้นด้วยtype/patternทางแก้เด็ดขาดยังเป็นเครื่องหมายคำพูด; อย่าหวังให้ schema ซ่อม parser - ข้อผิดพลาดเชิงตรรกะอยู่นอกวง พิมพ์ selector ผิด หรือ K8s selector ชี้ไปที่ label ที่ไม่มีอยู่ — schema รู้รูปร่าง ไม่รู้ความหมาย นั่นเป็นอาณาเขตของ admission webhooks, นโยบาย OPA หรือ
kubectl apply --dry-run=server - คีย์ซ้ำชนะอย่างเงียบ ๆ parser YAML จำนวนมากรับคีย์ซ้ำโดยไม่เตือน (ตัวหลังชนะ) ดังนั้น schema ได้รับข้อมูลที่คีย์หายไปแล้วหนึ่งตัว กฎ
key-duplicatesของ yamllint หรือ parsing hook ยังเป็นตัวจับ
เช็กลิสต์ก่อน deploy: ใส่คำพูดกับสตริงที่เหมือนโค้ด → รัน yamllint (truthy + key-duplicates) → ตรวจสอบ JSON Schema ทั้งใน CI และ editor → สำหรับรีซอร์สระดับคลัสเตอร์เพิ่ม --dry-run=server แต่ละขั้นกันความผิดพลาดต่างประเภทกัน และลำดับมีความสำคัญเพราะขั้นที่ถูกกว่าและเร็วกว่าควรทำงานก่อนเสมอ ด้วยสี่ขั้นนี้ เหตุการณ์นอร์เวย์ในหัวข้อหนึ่งจะไม่รอดถึงขั้นที่สองของไปป์ไลน์
FAQ
JSON Schema ตรวจสอบไฟล์ YAML โดยตรงได้หรือไม่?
ได้ — แต่มันตรวจสอบข้อมูลที่ไฟล์ parse ออกมา ไม่ใช่ตัวไฟล์ YAML 1.2 เป็น superset อย่างเข้มงวดของ JSON ทั้งสอง parse ลงโครงสร้างเดียวกัน ดังนั้น schema หนึ่งตัวใช้ได้ทั้ง JSON และ YAML เลือกหนึ่งจากสี่เส้นทาง — Python, Node, ไปป์ไลน์ yq หรือ check-jsonschema — โดยไม่ต้องแปลงรูปแบบด้วยมือ ข้อควรจำคือ schema ตรวจข้อมูลหลังผ่านการ parse เสมอ ดังนั้นถ้า parser เองผิดพลาดตั้งแต่ต้น schema จะเห็นเฉพาะข้อมูลที่ผิดแล้วเท่านั้น
SchemaStore คืออะไร ใช้อย่างไร?
schemastore.org เป็นแคตตาล็อก JSON Schema (catalog.json) ที่รวบรวม schema ของไฟล์คอนฟิกยอดนิยมหลายร้อยไฟล์: package.json, GitHub workflow, docker-compose เป็นต้น ตัว editor ที่รองรับ YAML/JSON ผูกไฟล์เข้ากับแคตตาล็อกนี้โดยอัตโนมัติ หรือคุณ map URL เองได้ใน yaml.schemas คุณยังส่ง schema ของโปรเจกต์ตัวเองเข้าแคตตาล็อกได้ด้วย และเมื่อ schema ของคุณอยู่ในแคตตาล็อกแล้ว ทุกคนที่ใช้ editor เดียวกันจะได้รับประโยชน์ทันทีโดยไม่ต้องตั้งค่าอะไรเพิ่ม นี่คือผลข้างเคียงที่ดีที่สุดของการมีส่วนร่วมกับชุมชน open source
yamllint กับ JSON Schema ทับซ้อนกันหรือไม่?
ไม่ yamllint ตรวจสไตล์การเขียน (ย่อหน้า ความยาวบรรทัด truthy คีย์ซ้ำ) ที่ระดับข้อความ; JSON Schema ตรวจโครงสร้างข้อมูล (ชนิด, required, enum, pattern) ที่ระดับข้อมูล ทั้งคู่ทำงานในจุดต่างกันของไปป์ไลน์ จึงควรใช้ร่วมกันเสมอ ไม่ใช่เลือกอย่างใดอย่างหนึ่ง รายการแก้ไขของเหตุการณ์นอร์เวย์ใช้ทั้งคู่: กฎ truthy ดักการสะกดอย่าง flag: yes ขณะที่ schema ดัก false ที่หลุดเข้าไปในอาร์เรย์สตริง
สำหรับ Kubernetes: kubeconform หรือ kubectl dry-run?
สองอาชีพต่างกัน Kubeconform ทำงานออฟไลน์และเป็นล็อต ไม่ต้องมีคลัสเตอร์ ที่ของมันคือ CI เพื่อจับข้อผิดพลาดเชิงโครงสร้าง; dry-run=server คุยกับ API server จริงและเปิดเผยปัญหา admission webhook และโควตา แต่ต้องเข้าถึงคลัสเตอร์ การผสมมาตรฐาน: kubeconform ใน CI แล้ววิ่ง --dry-run=server หนึ่งรอบก่อน deploy — เก็บทั้งสองชั้นไว้ ถ้าทีมมีข้อจำกัดด้านความปลอดภัยที่ไม่ให้ CI แตะคลัสเตอร์ ชุดนี้ก็ยังทำงานได้ครบเพราะ kubeconform เป็นการตรวจสอบในเครื่องล้วน ๆ ไม่ส่งข้อมูลออกไปไหนเลย
เขียน schema เสร็จแล้ว วาง JSON ที่แปลงจาก YAML ของคุณลงในเครื่องมือตรวจสอบ JSON ออนไลน์เพื่อเห็นข้อผิดพลาดก่อน; การเขียนคำสำคัญของ schema ดูได้ที่คู่มือ JSON Schema; อยากให้ schema ถูกเฝ้าด้วยเทสใน CI อ่านการทดสอบสัญญา JSON Schema; การแปลง JSON↔YAML ประจำวัน ใช้ตัวแปลง JSON YAML XML