JSON Toolkit

ตรวจสอบ YAML ด้วย JSON Schema: ตาข่ายนิรภัยของไฟล์คอนฟิก

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

ระดับกลางอ่านประมาณ 6 นาทีเผยแพร่ 2026-11-13อัปเดต 2026-11-13
แผนภาพแสดงการตรวจสอบไฟล์คอนฟิก YAML ด้วย JSON 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 ทั้งไปป์ไลน์มีแค่สามขั้น:

  1. Parse ไฟล์ YAML เป็น object/array;
  2. โหลด JSON Schema;
  3. ตรวจสอบข้อมูลกับ 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 แล้วจบทุกปัญหา

  1. การเลื่อนเวอร์ชันของ parser เกิดที่ขั้น parse schema เห็นแค่ผลลัพธ์ parse: NO ที่ PyYAML อ่านแล้วเป็น false ไปแล้ว และ schema ทำได้แค่กักค่าผิดนั้นด้วย type/pattern ทางแก้เด็ดขาดยังเป็นเครื่องหมายคำพูด; อย่าหวังให้ schema ซ่อม parser
  2. ข้อผิดพลาดเชิงตรรกะอยู่นอกวง พิมพ์ selector ผิด หรือ K8s selector ชี้ไปที่ label ที่ไม่มีอยู่ — schema รู้รูปร่าง ไม่รู้ความหมาย นั่นเป็นอาณาเขตของ admission webhooks, นโยบาย OPA หรือ kubectl apply --dry-run=server
  3. คีย์ซ้ำชนะอย่างเงียบ ๆ 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