JSON Toolkit

اعتبارسنجی YAML با JSON Schema: شبکه امن فایل‌های پیکربندی

جمع‌بندی: فایلی که YAML آن بدون خطا parse می‌شود لزوماً فایل درستی نیست: برای پارسر YAML 1.1 مقدار country: NO رشته نیست، و version: 1.10 بی‌سروصدا به عدد اعشاری 1.1 تبدیل می‌شود. این راهنما توضیح می‌دهد چرا JSON Schema می‌تواند YAML را اعتبارسنجی کند، مسیرهای CLI و ادیتور برای راه‌اندازی، اینکه یک schema چگونه رخداد واقعی کد کشور نروژ را می‌گرفت، و سه محدودیت اعتبارسنجی با schema.

متوسطحدود 6 دقیقه مطالعهانتشار 2026-11-13به‌روزرسانی 2026-11-13
نموداری که اعتبارسنجی فایل‌های پیکربندی YAML با JSON Schema را نشان می‌دهد

نتیجه‌گیری: YAML 1.2 ابرمجموعه‌ی سخت‌گیرانه‌ی JSON است، پس JSON Schema ساختار داده را بعد از parse اعتبارسنجی می‌کند، نه فرمت فایل — schema را یک بار بنویسید و هر دو داده‌ی JSON و YAML را پوشش می‌دهد. دقیقاً به همین دلیل است که رخدادهایی را که پارسر بی‌سروصدا نوع را تغییر می‌دهد می‌گیرد.

yaml.safe_load بدون خطا فقط ثابت می‌کند فایل YAML قانونی است. ثابت نمی‌کند که country: NO هنوز رشته است — زیر پارسر YAML 1.1 خیلی پیش از آنکه کد شما فایل را ببیند، به false تبدیل شده است.

یک: parse بدون خطا ≠ پیکربندی درست — ابتدا یک رخداد واقعی

تیمی در تجارت الکترونیک نروژ را به فهرست کشورهای ارسال اضافه کرد: یک خط، NO، در لیستی در group_vars سیستم Ansible. بازبینی شد، اعتبارسنجی شد، استقرار یافت. یک هفته بعد: صفر سفارش نروژی — فایل JSON روی سرورها حاوی "DK", false, "SE" بود. Ansible فایل‌های متغیرش را با PyYAML، پارسر YAML 1.1، تجزیه می‌کند: NO از همان لحظه‌ی خواندن فایل بولی false شده بود و فیلتر to_json هم وفادارانه همان را نوشت. قالب رندر شد، JSON معتبر بود، کسی گلایه نکرد — فقط سرویس checkout به هر مشتری نروژی پاسخ می‌داد که در لیست نیست، چون NO در فهرست نبود.

وجه مشترک این رخدادها: همه‌ی ابزارهای نحوی سبزند، حال آنکه لایه‌ی داده پیش‌تر غلط است. جدول زیر انحراف نوع‌ها را که با PyYAML 6.0.3 اندازه‌گیری شده نشان می‌دهد؛ پارسرهای 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 ابرمجموعه‌ی سخت‌گیرانه‌ی JSON شود، و پارسر 1.2 همان JSON معمولی را بدون تغییر می‌خواند. هر دو فرمت به همان ساختارهای داده تجزیه می‌شوند، پس پسوند فایل برای اعتبارسنج هیچ معنایی ندارد. کل خط لوله سه گام است:

  1. تجزیه‌ی فایل YAML به اشیاء/آرایه‌ها;
  2. بارگذاری JSON Schema;
  3. اعتبارسنجی داده در برابر schema — خطا یا عبور.

توجه کنید گام اول لازم ندارد YAML را به متن JSON سریالایز و دوباره تجزیه کنید؛ کتابخانه‌ی YAML زبان شما ساختار را مستقیم به اعتبارسنج می‌دهد. خود schema هم می‌تواند به YAML نوشته شود (yq -P schema.json > schema.yaml با یک دستور تبدیل می‌کند)، اما نگه‌داشتن آن در JSON امن‌ترین انتخاب است: سازگاری ابزارها بهتر است و همه‌ی schemaهای کاتالوگ schemastore.org جیسون‌اند.

سه: سه مسیر 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

سه مسیر فقط در گام تجزیه فرق دارند: دو مسیر اول صریح و دومای سطری‌اند؛ خط لوله در یک جریان می‌گذرد؛ و check-jsonschema تبدیل YAML→JSON را درون خودش انجام می‌دهد. فایل schema برای هر سه یکی است.

چهار: اعتبارسنجی زنده در ادیتور: modeline و SchemaStore

افزونه‌ی YAML شرکت Red Hat (بر پایه‌ی yaml-language-server) حدود ۳۰ میلیون نصب در VS Code دارد و از JSON Schema draft-04/07/2019-09/2020-12 پشتیبانی می‌کند. سه راه اتصال:

# گزینه ۱: modeline — نخستین خط فایل به schema اشاره می‌کند
# yaml-language-server: $schema=./schema.json
name: checkout
// گزینه‌های ۲ و ۳: .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 تبدیل می‌شوند و ویژگی‌های required غایب با خط قرمز نشان داده می‌شوند — خطاهای پیکربندی از «دیباگ بعد از استقرار» به «لحظه‌ای که تایپ می‌کنید» منتقل می‌شوند. این همچنین توضیح می‌دهد چرا SchemaStore و نه «استانداردی از schema برای YAML»: YAML استاندارد رسمی schema ندارد و JSON Schema استاندارد بالفعل است.

پنج: 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 بی‌درنگ شکست می‌خورد؛ حتی اگر پارسر آن را "no" با حروف کوچک بخواند، pattern سد راه است. برای سخت‌گیری بیشتر یک لیست سفید enum اضافه کنید. همان schema در CI با مسیرهای CLI بخش سه می‌چرخد و در ادیتور با modeline بخش چهار — یک قرارداد در دو سر.

تقسیم کار با yamllint یک جمله می‌ارزد: قانون truthy در yamllint (فقط true/false پذیرفته می‌شود، هر املا بولی دیگر گزارش می‌شود) بر سبک نگارش فرمان می‌راند و flag: yes را در لایه‌ی lint می‌گیرد؛ JSON Schema بر شکل داده فرمان می‌راند، هر پارسر که باشد. تیمِ آن رخداد سرانجام هر سه را برگزید: گیومه روی رشته‌ها، yamllint truthy در خط لوله، و آزمون رشته‌ی دوحرفی در قالب. دو لایه‌ی دفاع روی هم نمی‌افتند؛ مکمل یکدیگرند.

شش: اعتبارسنجی دسته‌ای مانیفست‌های Kubernetes

خود API Kubernetes در OpenAPI توصیف شده و پروژه‌ی kubernetes-json-schema آن را به JSON Schema استاندارد تبدیل می‌کند. Kubeconform همین مخزن را برای اعتبارسنجی دسته‌ای به کار می‌گیرد: روی لپ‌تاپ ۴ هسته‌ای، ۳۵٫۱۳۹ فایل و ۵۰٫۷۱۴ منبع با kubeconform -ignore-missing-schemas -n 8 -summary در ۶٫۷ ثانیه تمام می‌شود، در برابر ۳۵ ثانیه‌ی kubeval برای همان کار. حرکت استاندارد Helm: اول رندر، بعد اعتبارسنجی:

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 مخزن اختصاصی وصل کرد.

هفت: آنچه اعتبارسنجی با schema نمی‌تواند: سه محدودیت

  1. انحراف نسخه‌ی پارسر در گام تجزیه رخ می‌دهد. schema نتیجه‌ی تجزیه را می‌بیند: NO ای که PyYAML خوانده اکنون false است و schema فقط می‌تواند آن مقدار غلط را با type/pattern محبوس کند. راه‌حل بنیادین همچنان گیومه است؛ از schema تعمیر پارسر انتظار نداشته باشید.
  2. خطاهای منطقی بیرون از محدوده‌اند. غلط تایپی در selector یا selector کیوآ‌ایتی که به label ناموجود اشاره می‌کند — schema شکل می‌شناسد، نه معنا. آنجا سرزمین admission webhooks، سیاست‌های OPA یا kubectl apply --dry-run=server است.
  3. کلیدهای تکراری بی‌سروصدا می‌برند. بسیاری از پارسرهای YAML کلید تکراری را بدون هشدار می‌پذیرند (آخری می‌برد)، پس schema داده‌ای می‌گیرد که یک کلیدش از دست رفته. قانون key-duplicates در yamllint یا hookهای تجزیه همان کشف‌گرها هستند.

چک‌لیست پیش از استقرار: گیومه روی رشته‌های شبیه کد → اجرای yamllint (truthy + key-duplicates) → اعتبارسنجی JSON Schema هم در CI هم در ادیتور → برای منابع کلاستر، --dry-run=server هم اضافه کنید. با این چهار گام، رخداد نروژی بخش یک تا گام دوم خط لوله هم دوام نمی‌آورد.

FAQ

آیا JSON Schema می‌تواند مستقیماً فایل‌های YAML را اعتبارسنجی کند؟

بله — اما داده‌هایی را اعتبارسنجی می‌کند که فایل به آن‌ها تجزیه می‌شود، نه خود فایل. YAML 1.2 ابرمجموعه‌ی سخت‌گیرانه‌ی JSON است، هر دو به همان ساختارها تجزیه می‌شوند، پس یک schema برای JSON و YAML هر دو کار می‌کند. یکی از چهار مسیر را برگزینید — Python، Node، خط لوله‌ی yq یا check-jsonschema — بدون تبدیل دستی فرمت‌ها.

SchemaStore چیست و چگونه استفاده می‌شود؟

schemastore.org یک کاتالوگ JSON Schema (catalog.json) است که schemaهای صدها فایل پیکربندی رایج را گرد آورده: package.json، GitHub workflow، docker-compose و غیره. ادیتورهایی که YAML/JSON را پشتیبانی می‌کنند فایل‌ها را خودکار به این کاتالوگ پیوند می‌زنند، یا می‌توانید URLها را در yaml.schemas دستی نگاشت کنید. schema پروژه‌ی خودتان را هم می‌توان به کاتالوگ فرستاد.

آیا 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 سرور واقعی حرف می‌زند و مشکلات admission webhook و سهمیه‌ها را آشکار می‌کند، اما دسترسی کلاستر می‌خواهد. ترکیب استاندارد: kubeconform در CI، سپس یک گردش --dry-run=server پیش از استقرار — هر دو لایه را نگه دارید.


بعد از نوشتن schema، جیسون تبدیل‌شده از YAML خود را در اعتبارسنج آنلاین JSON جای‌گذاری کنید تا خطاها را اول ببینید؛ برای نوشتن کلیدواژه‌های schema ببینید راهنمای JSON Schema؛ برای نگهبانی schema با تست‌های CI بخوانید آزمون قرارداد JSON Schema؛ برای تبدیل روزانه‌ی JSON↔YAML از مبدل JSON YAML XML استفاده کنید.