منسّق YAML وأداة التحقق منه

كيفية استخدام منسّق YAML

1. الصق YAML في خانة الإدخال، مثل ملف بيان Kubernetes أو ملف Docker Compose أو مسار CI.
2. انقر تحقق لفحص البنية. وتُبلَّغ الأخطاء مع السطر والعمود اللذين توقف عندهما المحلِّل.
3. انقر تنسيق لإعادة طباعة المستند بمسافات بادئة واقتباس متسقين.
4. انقر تحويل إلى JSON لترى البيانات نفسها بصيغة JSON.
5. انسخ النتيجة إلى مشروعك.

تحلّل الأداة YAML 1.2 باستخدام مكتبة js-yaml مفتوحة المصدر، بالكامل داخل متصفحك. ولا تُرفع ملفاتك ولا تُخزَّن في أي مكان، وهذا مهم حين تحتوي على أسماء مضيفين أو بيانات اعتماد أو أسرار أخرى.

ما هو YAML؟

YAML («YAML Ain't Markup Language») صيغة لتسلسل البيانات سهلة القراءة للبشر. فبدل الأقواس والأقواس المعقوفة تستخدم المسافات البادئة لإظهار البنية، وشرطة (-) لعناصر القوائم، وأزواج key: value للتعيينات. كما تدعم التعليقات بـ #، والسلاسل متعددة الأسطر، والمراسي والأسماء المستعارة لإعادة استخدام القيم.

منذ YAML 1.2 صُمّمت الصيغة لتكون مجموعة شاملة لـ JSON، لذا فإن أي مستند JSON صالح تقريبًا هو أيضًا YAML صالح. وهذا يسهّل الانتقال بين الاثنين: فـ YAML مريح في الكتابة اليدوية، بينما JSON هو ما تتبادله معظم واجهات API والبرامج.

ولأن المسافات البيضاء ذات معنى، فقد تغيّر مسافة واحدة في غير موضعها بنية ملف YAML دون أن تُظهر أي خطأ. والتحقق وإعادة التنسيق يكشفان كيف يقرأ المحلِّل مستندك فعلًا، وهو غالبًا أسرع طريق للعثور على خطأ خفي.

أخطاء YAML الشائعة وكيفية إصلاحها

علامات Tab في المسافات البادئة. يمنع YAML استخدام محارف Tab للمسافات البادئة. استبدلها بمسافات؛ ومعظم المحررات تستطيع فعل ذلك تلقائيًا.

مسافات بادئة غير متسقة. يجب أن تتحاذى العناصر الواقعة في المستوى نفسه تمامًا. في هذا المثال، أُزيحت image مسافة واحدة أكثر من اللازم:

containers:
  - name: web
     image: nginx:1.27

حاذِها مع name:

containers:
  - name: web
    image: nginx:1.27

مسافة ناقصة بعد النقطتين. يُقرأ port:8080 على أنه سلسلة نصية عادية واحدة، لا مفتاح له قيمة. اكتب port: 8080.

محارف خاصة في سلاسل بلا علامات اقتباس. القيمة التي تبدأ بـ * أو & أو ! أو @ أو { أو [، أو التي تحتوي على : أو #، تحتاج إلى علامات اقتباس:

message: "Error: disk full"
pattern: "*.log"

مفاتيح مكررة. لا يجوز أن يحتوي التعيين على المفتاح نفسه مرتين. وتحتفظ بعض المحلِّلات بالقيمة الأخيرة بصمت؛ أما أداة التحقق فتنبّه إليه لتلاحظه.

الأنواع الضمنية: المفاجأة الكلاسيكية في YAML

يخمّن YAML أنواع القيم التي بلا علامات اقتباس. ففي المخطط الأساسي لـ YAML 1.2، تكون true وfalse قيمًا منطقية، وتكون null و~ قيمة فارغة، وما يبدو كأرقام يكون أرقامًا. أما محلِّلات YAML 1.1 الأقدم فقد ذهبت أبعد وعدّت yes وno وon وoff قيمًا منطقية، وهكذا تحوّل رمز البلد NO الخاص بالنرويج إلى false في حادثة مشهورة. ولا تزال الأدوات تختلف هنا، فضع علامات اقتباس حول كل ما يجب أن يبقى سلسلة نصية:

نصائح وأفضل الممارسات

• استخدم مسافتين لكل مستوى؛ فهذا هو الأسلوب الأكثر شيوعًا في ملفات Kubernetes وAnsible وGitHub Actions.
• استخدم | للنص متعدد الأسطر حين تهم فواصل الأسطر (السكربتات والشهادات)، واستخدم > حين ينبغي أن تُطوى الأسطر في فقرة واحدة.
• التحويل إلى JSON طريقة موثوقة لتأكيد البنية: فإذا وقعت قيمة في كائن خاطئ، يجعل ناتج JSON ذلك واضحًا. وللتحويل ذهابًا وإيابًا، استخدم محوّل JSON ↔ YAML.
• هل تحتاج إلى ترتيب JSON بعد ذلك؟ يستطيع منسّق JSON وأداة التحقق منه ترتيب المفاتيح وتصغيره.

الأسئلة الشائعة

هل JSON صالح كـ YAML؟

من الناحية العملية، نعم. فقد جرت مواءمة YAML 1.2 بحيث تكون مستندات JSON صالحة كـ YAML، ولهذا يمكنك لصق JSON في هذه الأداة وستحلّله.

لماذا لا يسمح YAML بعلامات Tab؟

تُعرض علامات Tab بعروض مختلفة في المحررات المختلفة، فقد لا تكون المسافة البادئة التي تبدو متحاذية كذلك فعلًا. وتمنع المواصفة استخدام Tab للمسافات البادئة لإبقاء البنية غير ملتبسة.

لماذا أزال التنسيق تعليقاتي؟

يحلّل المنسّق YAML إلى بيانات ثم يطبعه من جديد. والتعليقات ليست بيانات، لذلك لا تنجو من هذه الدورة. وتُحَلّ المراسي والأسماء المستعارة أثناء التحليل، فقد تعود موسَّعة أو بأسماء مولَّدة.

أي إصدار من YAML تدعمه هذه الأداة؟

تستخدم js-yaml التي تتبع YAML 1.2. والملفات المكتوبة لمحلِّلات YAML 1.1 تعمل عادةً، لكن قيمًا مثل yes وno تُعامَل كسلاسل نصية.

آخر تحديث 2026-10-17