JSON Toolkit

التحقق من صحة YAML باستخدام JSON Schema: شبكة أمان لملفات الإعداد

الخلاصة: ملف YAML الذي يُحلَّل بلا أخطاء ليس ملفاً صحيحاً بالضرورة: القيمة country: NO ليست سلسلة بالنسبة لمحلل YAML 1.1، وقيمة version: 1.10 تتحول بصمت إلى العدد العشري 1.1. يشرح هذا الدليل لماذا يستطيع JSON Schema التحقق من صحة YAML، ومسارات CLI والمحرر لإعداده، وكيف كان مخطط ما سيلتقط الحادثة الحقيقية لرمز الدولة النرويجية، والقيود الثلاث للتحقق بالمخطط.

متوسطقراءة نحو 6 دقيقةنُشر في 2026-11-13حُدِّث في 2026-11-13
رسم يوضح التحقق من صحة ملفات إعداد YAML باستخدام JSON Schema

الخلاصة: YAML 1.2 مجموعة عليا صارمة من JSON، لذا يتحقق JSON Schema من بنية البيانات بعد التحليل، لا من تنسيق الملف — اكتب المخطط مرة واحدة وسنغطي بيانات JSON وYAML معاً. ولهذا بالضبط يستطيع التقاط الحوادث التي يغيّر فيها المحلل النوع بصمت.

إن نجاح yaml.safe_load دون أخطاء يثبت فقط أن الملف نص YAML سليم. لا يثبت أن country: NO ما تزال سلسلة — تحت محلل YAML 1.1 أصبحت false منذ زمن قبل أن يرىها كودك.

أولاً: التحليل بلا أخطاء ≠ إعداد صحيح — لنبدأ بحادثة حقيقية

أضاف فريق تجارة إلكترونية النرويج إلى قائمة دول التوصيل: سطر واحد، NO، في قائمة داخل group_vars في Ansible. راجع، وتحقق، وانشر. وبعد أسبوع: صفر طلبات نرويجية — كان ملف JSON على الخوادم يحوي "DK", false, "SE". يحلل Ansible ملفات متغيراته عبر PyYAML، وهو محلل YAML 1.1: تحولت NO إلى القيمة المنطقية false لحظة قراءة الملف، وكتبها مرشّح to_json بأمانة. قُدّم القالب، وكان JSON صالحاً، ولم يشتكِ أحد — فقط خدمة الدفع واصلت رفض كل عميل نرويجي لأن 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"

العلاج الجذري: ضع علامات تنصيص حول كل سلسلة تشبه الكود. لكن التنصيص يقوم على الذاكرة البشرية؛ المخطط يقوم على الفحص الآلي — لهذا يستحق YAML مخطط JSON.

ثانياً: لماذا يستطيع JSON Schema أن يحكم YAML

تقول مواصفة YAML 1.2 بصراحة: كان الهدف الرئيسي من 1.2 أن تصبح YAML مجموعة عليا صارمة من JSON، ويقرأ محلل 1.2 الـ JSON العادي دون تعديل. كلا التنسيقين يُحلَّل إلى البنى البياناتية نفسها، لذا امتداد الملف لا معنى له أمام المدقق. خط الأنابيب كله ثلاث خطوات:

  1. تحليل ملف YAML إلى كائنات ومصفوفات؛
  2. تحميل JSON Schema؛
  3. التحقق من البيانات مقابل المخطط — أخطاء أو نجاح.

لاحظ أن الخطوة الأولى لا تقتضي تحويل YAML إلى نص JSON ثم تحليله من جديد؛ تمرر مكتبة YAML في لغتك البنية مباشرة إلى المدقق. يمكن كتابة المخطط نفسه بـ YAML أيضاً (yq -P schema.json > schema.yaml يحوّله بأمر واحد)، لكن إبقاؤه بصيغة JSON هو الخيار الأسلم: توافق أدوات أفضل، وجميع مخططات فهرس schemastore.org بجيسون.

ثالثاً: ثلاثة مسارات CLI تعمل منذ اليوم

لنأخذ config.yaml يفرض فيها المخطط وجود name وversion، ويشترط شكل semver وقائمة countries كمصفوفة سلاسل من حرفين كبيرين:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

بايثون (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 داخلياً. ملف المخطط واحد للجميع.

رابعاً: التحقق الفوري في المحرر: modeline وSchemaStore

يحقق امتداد YAML من Red Hat (المبني على yaml-language-server) نحو 30 مليون تثبيت في VS Code ويدعم JSON Schema draft-04/07/2019-09/2020-12. ثلاث طرق للربط:

# الطريقة 1: modeline — السطر الأول من الملف يشير إلى المخطط
# yaml-language-server: $schema=./schema.json
name: checkout
// الطريقتان 2 و3: .vscode/settings.json، حسب اسم الملف أو النمط
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

الخيار yaml.schemaStore.enable مفعّل افتراضياً: الملفات المألوفة مثل package.json وسير عمل GitHub وdocker-compose تُربط تلقائياً بفهرس schemastore.org دون أي إعداد. تتحول حقول description في المخطط إلى تلميحات إكمال وتلميحات معلقة، وتُشطب الخصائص required المفقودة بخط أحمر — تنتقل أخطاء الإعداد من «تصحيح بعد النشر» إلى «لحظة الكتابة نفسها». يفسر هذا أيضاً لماذا SchemaStore لا «معيار مخططات لـ YAML»: ليس لـ YAML معيار رسمي للمخططات، وJSON Schema هو المعيار الفعلي.

خامساً: كيف كان مخطط ما سيلتقط مشكلة النرويج

نعود إلى حادثة NO في القسم الأول. نمنح countries مخططاً على مستوى العنصر:

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

القيمة false التي ينتجها PyYAML ليست سلسلة، فيسقط type: string فوراً؛ وحتى لو قرأها محللٌ ما "no" بأحرف صغيرة، يمنعها pattern. لمزيد من الصرامة أضف قائمة بيضاء enum. يدير المخطط نفسه في CI عبر مسارات CLI للقسم الثالث وفي المحرر عبر modeline للقسم الرابع — عقد واحد في الطرفين.

تقسيم العمل مع yamllint يستحق جملة: قاعدة truthy في yamllint (تقبل true/false فقط، وكل تهجئة منطقية أخرى تُبلّغ عنها) تحكم أسلوب الكتابة وتلتقط flag: yes في طبقة الفحص؛ بينما يحكم JSON Schema شكل البيانات أياً كان المحلل. تبنى فريق الحادثة الثلاثة كلها في النهاية: تنصيص على السلاسل، وyamllint truthy في خط الأنابيب، وتأكيد سلسلة من حرفين في القالب. طبقتا الدفاع لا تتداخلان؛ بل يكمل كل منهما الأخرى.

سادساً: التحقق الدفعي من بيانات Kubernetes

توصف واجهة Kubernetes البرمجية نفسها بـ OpenAPI، ويحوّل مشروع kubernetes-json-schema تلك إلى JSON Schema قياسي. يستخدم Kubeconform هذا السجل للتحقق الدفعي: على حاسوب بأربعة أنوية تُنجَز 35,139 ملفاً و50,714 مصدراً بأمر kubeconform -ignore-missing-schemas -n 8 -summary في 6.7 ثانية، مقابل 35 ثانية لـ kubeval على المهمة ذاتها. الخطوة القياسية في Helm: قدّم أولاً ثم تحقق:

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

يَرفض -strict الحقول غير المعرفة في المخطط (تظهر الأخطاء المطبعية مبكراً)؛ ويمكن تجاوز مصادر CRD بخيار -ignore-missing-schemas أو توصيل سجل مخصص عبر -schema-location.

سابعاً: ما لا يستطيع التحقق بالمخطط فعله: ثلاثة قيود

  1. انزلاق نسخة المحلل يقع في خطوة التحليل. يرى المخطط ناتج التحليل فقط: القيمة NO التي قرأها PyYAML أصبحت false، والمخطط لا يملك إلا حبس هذه القيمة الخاطئة عبر type/pattern. العلاج الجذري يظل التنصيص؛ لا تنتظر من مخطط أن يصلح محلاً.
  2. الأخطاء المنطقية خارج المحيط. خطأ مطبعي في selector أو محدد K8s يشير إلى تسمية غير موجودة — المخطط يعرف الأشكال لا الدلالة. ذلك مجال admission webhooks وسياسات OPA أو kubectl apply --dry-run=server.
  3. المفاتيح المكررة تتفوق بصمت. يقبل كثير من محللات YAML المفاتيح المكررة دون تحذير (الأخيرة تفوز)، فيصل المخطط إلى بيانات فقدت مفتاحاً بالفعل. تبقى قاعدة key-duplicates في yamllint أو معلّقات التحليل هي الكواشف.

قائمة فحص قبل النشر: تنصيص على السلاسل التي تشبه الكود → تشغيل yamllint (truthy + key-duplicates) → التحقق بـ JSON Schema في CI وفي المحرر معاً → لمصادر الكلاستر أضف --dry-run=server. بهذه الخطوات الأربع لا تتجاوز حادثة النرويج في القسم الأول الخطوة الثانية من خط الأنابيب.

FAQ

هل يتحقق JSON Schema من ملفات YAML مباشرة؟

نعم — لكنه يتحقق من البيانات التي يُحلَّل إليها الملف، لا من الملف ذاته. YAML 1.2 مجموعة عليا صارمة من JSON وكلاهما يُحلَّل إلى البنى نفسها، فمخطط واحد يخدم JSON وYAML. اختر واحداً من أربعة مسارات — Python أو Node أو خط أنابيب yq أو check-jsonschema — دون تحويل التنسيقات يدوياً.

ما هو SchemaStore وكيف يُستخدم؟

schemastore.org فهرس لمخططات JSON (catalog.json) يجمع مخططات مئات ملفات الإعداد الشائعة: package.json وسير عمل GitHub وdocker-compose وغيرها. تربط المحررات الداعمة لـ YAML/JSON الملفات بهذا الفهرس تلقائياً، أو يمكنك ربط عناوين URL يدوياً في yaml.schemas. كما يمكنك تقديم مخطط مشروعك إلى الفهرس.

هل يتداخل yamllint مع JSON Schema؟

لا. يفحص yamllint أسلوب الكتابة (المسافات البادئة، طول الأسطر، truthy، المفاتيح المكررة) على مستوى النص؛ ويفحص JSON Schema بنية البيانات (الأنواع، required، enum، pattern) على مستوى البيانات. استخدمت قائمة إصلاحات حادثة النرويج كليهما: تلتقط قاعدة truthy تهجئات مثل flag: yes، بينما يلتقط المخطط قيمة false وجدت طريقها إلى مصفوفة سلاسل.

لـ Kubernetes: kubeconform أم kubectl dry-run؟

حرفتان مختلفتان. يعمل Kubeconformat دون اتصال ودفعياً وبلا كلاستر، ومكانه في CI لالتقاط الأخطاء البنيوية؛ يتحدث dry-run=server إلى خادم API حقيقي ويكشف مشاكل admission webhook والحصص، لكنه يقتضي الوصول إلى الكلاستر. التركيبة القياسية: kubeconform في CI ثم دورة --dry-run=server قبل النشر — أبقِ الطبقتين.


بعد كتابة مخططك، الصق JSON المحوَّل من YAML في أداة التحقق من JSON عبر الإنترنت لترى الأخطاء أولاً؛ لكتابة كلمات المخطط المفتاحية انظر دليل JSON Schema؛ لجعل مخططك محروساً باختبارات CI اقرأ اختبار العقود بـ JSON Schema؛ ولتحويل JSON↔YAML اليومي استخدم محوّل JSON YAML XML.