YAML مقابل JSON مقابل TOML: متى تستخدم كل تنسيق إعدادات

كل مشروع يصطدم في نهاية المطاف بمشكلة الإعدادات. تحتاج إلى تخزين بيانات اعتماد قاعدة البيانات، وتعريف بيئات النشر، وصف خط أنابيب CI، أو ربط التبعيات — ولا بد أن يختار أحدهم تنسيقاً. JSON؟ YAML؟ TOML؟ يبدو الاختيار اعتباطياً حتى تقع في مشكلة بسببه.

ملفات Docker Compose بتنسيق YAML. package.json بتنسيق JSON. ملف تبعيات Rust (Cargo.toml) بتنسيق TOML. حزم Python (pyproject.toml) بتنسيق TOML. سير عمل GitHub Actions بتنسيق YAML. هذا ليس عشوائياً — فاز كل تنسيق في معركة التبني ضمن نطاقه لأسباب محددة. فهم هذه الأسباب يتيح لك اتخاذ قرار مدروس بدلاً من الاكتفاء بـ"ما استخدمه القالب".

هذا المقال دليل لاتخاذ القرار. بنهايته، ستعرف المقايضات الحقيقية لكل تنسيق، وسترى بالضبط المخاطر الخفية في YAML التي تسببت في حوادث في بيئات الإنتاج، وسيكون لديك إطار واضح للاختيار.

السلف المشترك: ملفات INI

قبل الغوص في المنافسين المعاصرين، يستحق الأمر قضاء ثلاثين ثانية على ملفات INI — التنسيق الذي يتفاعل معه الثلاثة بطريقة ما.

ملفات INI تبدو هكذا:

[database]
host = localhost
port = 5432
name = mydb
 
[server]
port = 8080
debug = true

بسيطة، قابلة للقراءة البشرية، تدعم الأقسام والتعليقات. المشاكل بالقدر ذاته من البساطة: لا مواصفة قياسية (كل محلل يفسر الحالات الحدية بشكل مختلف)، ولا هياكل متداخلة تتجاوز مستوى واحد، ولا مصفوفات، ولا أنواع صريحة. كل شيء سلسلة نصية ما لم يقرر تطبيقك غير ذلك.

كانت ملفات INI مقبولة لـphp.ini عام 1997. لكنها لا تكفي لوصف نشر Kubernetes عام 2026. غير أنها حددت الأهداف الصحيحة — قابلية التحرير البشري والتعليقات — التي إما ورثتها التنسيقات الحديثة أو تخلت عنها.

JSON: اللغة المشتركة للبيانات

جرى توحيد JSON (JavaScript Object Notation) في أوائل الألفية الثالثة وأصبح التنسيق السلكي السائد للواجهات البرمجية. تأتي قوته من قيوده.

ما يتقنه JSON

يمتلك JSON ستة أنواع قيم فقط: سلسلة نصية، ورقم، وقيمة منطقية، وnull، ومصفوفة، وكائن. المواصفة لا تقبل التأويل. كل محلل JSON متوافق سيحلل الوثيقة ذاتها بشكل متطابق. لا مفاجآت.

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "ssl": true
  },
  "allowed_origins": ["https://example.com", "https://api.example.com"],
  "timeout_ms": null
}

نوع port هو رقم بشكل لا يقبل الجدل. ssl قيمة منطقية بلا التباس. allowed_origins مصفوفة من السلاسل النصية بشكل قاطع. لا يمكن لمحلل JSON أن يسيء قراءة هذا.

JSON أيضاً في كل مكان. كل لغة برمجة لديها محلل JSON في مكتبتها القياسية. المتصفحات تحلله بشكل أصلي. قواعد بيانات كـPostgreSQL لديها أعمدة JSON أصلية. إنه تنسيق أدنى قاسم مشترك لتبادل البيانات بين الأنظمة التي لا تشترك في وقت تشغيل.

ما يُخفق فيه JSON للإعدادات

لا يمتلك JSON صياغة للتعليقات. هذا قرار تصميمي متعمد من Douglas Crockford (مؤلف JSON)، بحجة أن التعليقات في تنسيقات البيانات تشجع الناس على وضع توجيهات تحليل فيها، مما يفسد قابلية نقل التنسيق.

هذا مبدأ مقبول لاستجابات الواجهة البرمجية. لكنه مشكلة جدية لملفات الإعدادات. ملفات الإعدادات تحتاج إلى تعليقات. أنت بحاجة لشرح سبب كون timeout_ms يساوي 30000 وليس 10000. تحتاج لتحديد الحقول الآمنة للتغيير. تحتاج لترك ملاحظة تقول "لا تضبط هذا فوق 100 في بيئة الاختبار".

الحلول البديلة كلها سيئة. بعض الفرق تستخدم حقول "_comment". بعضها يستخدم JSON5 (مجموعة شاملة مع تعليقات) وتتمنى أن أدواتها تتعامل معه. بعضها يستخدم JSONC (JSON مع تعليقات، اشتهر بـsettings.json في VS Code). لا شيء من هذه يعد JSON قياسياً.

JSON أيضاً مطوّل للإعدادات. الفواصل الزائدة غير مسموح بها، مما يسبب أخطاء نحوية مستمرة عند إعادة ترتيب الحقول. كل مفتاح سلسلة نصية يستلزم علامات اقتباس مزدوجة. لا توجد صياغة للسلاسل النصية متعددة الأسطر — يجب الإفلات من أمر shell طويل في سطر واحد.

JSON ينتمي إلى: استجابات الواجهة البرمجية، تبادل البيانات بين الخدمات، ملفات بيان الحزم التي تكتبها الآلات أساساً (package.json، composer.json)، وفي أي مكان تحتاج فيه إلى تناسق تحليل مضمون عبر أنظمة غير متجانسة.

يمكنك التحقق من صحة JSON عبر الإنترنت لاكتشاف أخطاء الصياغة قبل أن تصل إلى تطبيقك — وهذا أهم مما قد تتوقع، إذ يكسر محلل JSON كلياً بسبب فاصلة واحدة مفقودة أو قوس زائد.

YAML: القوة والخطر

صُمم YAML (YAML Ain't Markup Language) ليكون البديل الصديق للإنسان عن XML. إنه معبّر وقابل للقراءة ومستخدم على نطاق واسع في أدوات DevOps. لكنه أيضاً أخطر تنسيق إعدادات شائع الاستخدام.

ما يتقنه YAML

يتيح YAML التعليقات (#). يستنتج أنواع القيم غير المقتبسة، فتستطيع كتابة port: 5432 بدلاً من "port": 5432. يدعم السلاسل النصية متعددة الأسطر بصياغة نظيفة تشبه heredoc. إنه موجز: يحل الإزاحة محل الأقواس المعقوفة والمربعة.

database:
  host: localhost
  port: 5432
  ssl: true
 
allowed_origins:
  - https://example.com
  - https://api.example.com
 
# هذا تعليق يشرح سبب ارتفاع قيمة المهلة الزمنية
timeout_ms: 30000

لإعدادات CI/CD — GitHub Actions وGitLab CI وCircleCI — قدرة YAML على التعبير عن الهياكل المتداخلة بشكل نظيف مع التعليقات مفيدة فعلاً. ملف سير عمل GitHub Actions كثيراً ما يمتد لمئات الأسطر مع شروط متداخلة واستراتيجيات matrix وكتل متغيرات البيئة. JSON سيكون غير قابل للقراءة. TOML سيكون محرجاً للهياكل المتداخلة بعمق.

مخاطر YAML الخفية

استنتاج نوع البيانات في YAML هو حيث تسوء الأمور. يفحص المحلل القيم غير المقتبسة ويقرر نوعها. القرارات التي يتخذها ليست دائماً ما تتوقعه.

مشكلة النرويج. في YAML 1.1 (وهو ما تطبقه معظم المحللات — وليس YAML 1.2)، يُحلَّل NO المجرد باعتباره القيمة المنطقية false. وكذلك no وNo وn وN وfalse وFalse وFALSE وoff وOff وOFF. قائمة رموز الدول ISO 3166-1 تتضمن NO للنرويج. ملف إعدادات يحتوي على قائمة رموز دول سيحوّل النرويج صامتاً إلى false.

# YAML 1.1 — ما يراه المحلل فعلياً
country: NO        # → false (قيمة منطقية)
enabled: yes       # → true (قيمة منطقية)
mode: on           # → true (قيمة منطقية)
debug: off         # → false (قيمة منطقية)

الحل هو اقتباس كل ما يجب أن يكون سلسلة نصية: country: "NO". لكن جاذبية YAML كلها أنك لا تحتاج إلى اقتباس الأشياء. اشتراط الاقتباس لتجنب المفاجآت يقوّض ميزة قابلية قراءة التنسيق.

الأعداد الثمانية. في YAML 1.1، رقم يبدأ بـ0 يُعامَل كرقم ثماني. أذونات الملفات كثيراً ما تُكتب بالنظام الثماني: chmod: 0755. يقرأ محلل YAML 0755 باعتباره الرقم العشري 493، وليس 755. لقد كسر هذا سكربتات نشر حقيقية.

# YAML 1.1 — التفسير الثماني
file_mode: 0755    # → 493 (المكافئ العشري للثماني 0755)

غموض السلاسل النصية متعددة الأسطر. يوفر YAML صياغات متعددة للسلاسل متعددة الأسطر — الكتلة الحرفية (|)، والكتلة المطوية (>)، والمضمنة. تتصرف بشكل مختلف فيما يخص السطور الجديدة والمسافات البيضاء الزائدة والإزاحة. اختيار النوع الخاطئ ينتج بصمت السلسلة النصية الخاطئة.

# الكتلة الحرفية — تحافظ على السطور الجديدة
command: |
  npm install
  npm run build
 
# الكتلة المطوية — تصبح السطور الجديدة مسافات (مفيد للنصوص الطويلة)
description: >
  This is a long description that will be
  folded into a single line with spaces.

علامات التبويب مقابل المسافات. لا يسمح YAML بأحرف علامة التبويب للإزاحة. محرر يُدخل علامات التبويب صامتاً سينتج خطأ تحليل — أو الأسوأ، تحليلاً مختلفاً حسب إعداد توقف علامة التبويب.

أصلح YAML 1.2 كثيراً من هذه المشاكل (بما فيها قائمة القيم المنطقية)، لكن معظم الأدوات لا تزال تطبق الإصدار 1.1. عندما تستخدم YAML، أنت تكتب للمحلل الذي تشحنه سلسلة أدواتك، الذي قد يتوافق أو لا يتوافق مع افتراضاتك.

TOML: مُصمَّم للإعدادات

أُنشئ TOML (Tom's Obvious Minimal Language) عام 2013 من قِبَل Tom Preston-Werner (المؤسس المشارك لـGitHub) تحديداً ليكون تنسيق ملف إعدادات يستطيع البشر كتابته والآلات تحليله بلا غموض.

ما يتقنه TOML

يمتلك TOML أنواعاً صريحة وغير ملتبسة. السلسلة النصية دائماً مقتبسة. الرقم دائماً رقم. القيمة المنطقية دائماً true أو false (بأحرف صغيرة، بلا مرادفات). لا يوجد استنتاج نوع من القيم المجردة، لذا لا توجد مشكلة النرويج.

[database]
host = "localhost"
port = 5432
ssl = true
 
allowed_origins = [
  "https://example.com",
  "https://api.example.com",
]
 
# هذا تعليق يشرح سبب ارتفاع قيمة المهلة الزمنية
timeout_ms = 30000

يمتلك TOML دعماً متكاملاً للتواريخ والأوقات (publishedAt = 2026-04-04)، بينما يتركها JSON وYAML كسلاسل نصية تحللها التطبيقات بنفسها.

رؤوس الأقسام ([database]، [[servers]]) صريحة وقابلة للقراءة. المفاتيح ذات النقاط (database.host = "localhost") تتيح التعبير عن القيم المتداخلة بشكل مضمّن. مصفوفة الجداول ([[servers]]) تمنحك صياغة نظيفة لقائمة الكائنات.

[[servers]]
name = "production"
host = "prod.example.com"
port = 443
 
[[servers]]
name = "staging"
host = "staging.example.com"
port = 443

مواصفة TOML دقيقة ومُصدَرة بإصدارات. كل محلل TOML متوافق ينتج النتيجة ذاتها للمدخل ذاته.

أين يقصر TOML

يعمل TOML جيداً للتداخل الضحل إلى المعتدل. للهياكل المتداخلة بعمق — كتلك التي تظهر في ملفات بيان Kubernetes أو كتب تشغيل Ansible — تصبح صياغة رأس القسم متكررة. يتوسع تداخل YAML المستند إلى الإزاحة بشكل أكثر طبيعية لستة أو سبعة مستويات عمق.

يمتلك TOML أيضاً دعماً أقل للأدوات مقارنة بـJSON أو YAML. معظم اللغات لديها مكتبات TOML ممتازة، لكن دعم المحرر (تمييز الصياغة والتحقق والإكمال التلقائي) أقل اتساقاً من دعم JSON.

جدول المقارنة

إطار اتخاذ القرار

بمجرد استبعاد لغة التسويق، يتلخص الاختيار في ثلاثة أسئلة.

هل هذا أساساً مولَّد آلياً أم مكتوب بشرياً؟

إذا كان الملف مولَّداً بالكود ومستهلَكاً بالكود — استجابة واجهة برمجية، أو أداة بناء، أو إدخال ذاكرة تخزين مؤقت متسلسل — استخدم JSON. إنه الأكثر قابلية للنقل، والأكثر قابلية للتحليل، ودعم الأدوات شامل. لا تحتاج إلى تعليقات في ملف لا يقرأه إنسان. ضغط ملفات JSON هذه قبل نقلها عبر الشبكة يمكن أن يقلل حجم الحمولة بشكل ملموس.

إذا كان إنسان يكتب هذا الملف ويحرره بانتظام — إعدادات مشروع، أو وصف بيئة، أو بيان أداة — فالتعليقات غير قابلة للتفاوض. هذا يستبعد JSON الخالص.

هل تتحكم في سلسلة الأدوات؟

إذا كنت مقيداً بنظام بيئي يفرض تنسيقاً — Kubernetes يتطلب YAML، GitHub Actions يتطلب YAML، Cargo يتطلب TOML، package.json هو JSON — فلا يوجد قرار يجب اتخاذه. استخدم ما يتوقعه النظام البيئي.

إذا كنت تصمم أداة جديدة أو ملف إعدادات جديداً من الصفر، فلديك خيار حقيقي.

ما عمق التداخل، وما مدى تسامح فريقك مع الأخطاء الخفية؟

YAML معبّر لكنه هش. فريق يكتب YAML بعناية، ويقتبس كل السلاسل النصية، ويشغّل أداة فحص، ويفهم الفرق بين 1.1 و1.2 يمكنه استخدامه بأمان. فريق يتحرك بسرعة، ولديه إعدادات محررات متنوعة، ولا يشغّل فحص YAML في CI سيصطدم في نهاية المطاف بمشكلة النرويج أو خطأ الأرقام الثمانية في الإنتاج.

TOML هو الخيار الأكثر أماناً للإعدادات المكتوبة بشرياً عندما تتحكم في التنسيق. الأنواع الصريحة تعني أن خطأ المحلل يظهر في وقت التحليل، وليس في وقت التشغيل عندما تحولت النرويج إلى false وفشل منطق علامة الميزة لديك صامتاً.

مرجع سريع

• استجابة واجهة برمجية أو تبادل بيانات بين الخدمات: JSON
• ملف بيان حزمة (مكتوب أساساً بالآلة): JSON
• Kubernetes، Docker Compose، GitHub Actions، Ansible: YAML (ليس خياراً)
• ملف إعدادات مشروع جديد تصممه: TOML
• مشروع Rust: TOML (Cargo.toml)
• مشروع Python: TOML (pyproject.toml)
• إعدادات تطبيق قديم باحتياجات مفتاح-قيمة بسيطة: INI (أو الانتقال إلى TOML)

التحقق من صحة ملفات الإعدادات

أخطاء الصياغة في ملفات الإعدادات من أكثر الأخطاء إحباطاً للتشخيص — التطبيق يفشل في البدء، رسالة الخطأ مبهمة، والخطأ حرف واحد في غير مكانه.

لـJSON، يمكنك التحقق من صحة JSON وطباعته بشكل أنيق عبر الإنترنت لاكتشاف الأخطاء فوراً. لصق ملف إعدادات JSON في أداة التحقق قبل الإيداع يستغرق خمس ثوانٍ ويمنع فئة من إخفاقات CI. لسير عمل JSON الأعمق — الضغط للإنتاج، ومقارنة تغييرات الإعدادات بين البيئات — راجع دليلنا حول كيفية التحقق من صحة JSON وضغطه وطباعته بشكل أنيق.

لـYAML، yamllint هو أداة فحص CLI القياسية. تشغيله في CI ليس اختيارياً إذا كان فريقك يكتب YAML للإنتاج. لـTOML، تشحن معظم نظم بيئة اللغات أداة تحقق مدمجة (cargo check تتحقق من Cargo.toml ضمنياً؛ python -c "import tomllib; tomllib.load(open('pyproject.toml', 'rb'))" تتحقق من أي ملف TOML مباشرة).

التنسيق عقد

أياً كان التنسيق الذي تختاره، يصبح عقداً مع كل مطور وأداة تلمس مشروعك. تغييره لاحقاً مؤلم — ليس مستحيلاً، لكنه مؤلم. استغرق الانتقال من setup.cfg وsetup.py إلى pyproject.toml في نظام Python البيئي سنوات ولم يكتمل بعد.

اختر بتدبر. JSON عندما تكون الآلات المستهلك الرئيسي وقابلية النقل حيوية. YAML عندما يفرضه النظام البيئي أو عندما تحتاج الهياكل المتداخلة بعمق إلى أن تكون قابلة للقراءة. TOML عندما يكتب البشر الملف، والصحة مهمة، وتريد أن يكتشف المحلل الغموض في وقت القراءة بدلاً من ظهوره كخطأ وقت تشغيل بعد ستة أشهر.

تنسيق الإعدادات ليس مجرد تنسيق ملف. إنه بيان حول من يحرر الملف، وما الأدوات التي تعالجه، ومدى ثقتك بالتحويل الضمني للأنواع. اصنع هذا البيان بقصد.

تحتاج إلى التحقق من صحة ملف إعدادات JSON الآن؟ جرب FileCrank JSON Viewer — الصق JSON الخاص بك، واكتشف الأخطاء فوراً، واطبعه بشكل أنيق لتسهيل القراءة.