محوّل YAML ↔ JSON ↔ TOML

إذا فتحت مستودعاً حديثاً على GitHub، ستجد على الأرجح ثلاث صيغ ضبط مختلفة في نفس المشروع: package.jsonبصيغة JSON، .github/workflows/ci.yml بصيغة YAML، و Cargo.toml أو pyproject.toml بصيغة TOML. ليس هذا مصادفة — كل صيغة تخدم حالة استخدام مختلفة، وفهم متى تستخدم كلّاً منها يميّز المهندس المحترف عن المبتدئ.

JSON اخترعها Douglas Crockfordعام 2001 كصيغة تبادل بيانات بين JavaScript والخادم. YAML بدأت عام 2001 أيضاً كصيغة قابلة للقراءة البشرية (YAML Ain't Markup Language). TOML أنشأها Tom Preston-Werner (مؤسس GitHub) عام 2013 لتكون ملف ضبط بسيط لا يحتاج تفكيراً. اليوم، الصيغ الثلاث متعايشة، ولكل واحدة نقاط قوة وضعف واضحة.

JSON هي الأكثر انتشاراً. تدعمها كل لغة برمجة بدون مكتبات خارجية، وتُستخدم في 99% من APIs الحديثة (REST، GraphQL، gRPC-Web). صيغتها صارمة: مفاتيح بين علامتي اقتباس مزدوجتين، فاصلات بين العناصر، أقواس {} للكائنات و[] للمصفوفات.

نقاط القوة: سرعة التحليل (parsers مكتوبة بـ C في كل لغة)، خفيفة الحجم في الإرسال، تدعم Streaming. نقاط الضعف: لا تعليقات، صعبة القراءة عند التداخل العميق، عرضة لأخطاء الفواصل الزائدة (trailing comma)، ولا تدعم تواريخ أصلية.

استخدم JSON في: استجابات API، تخزين بيانات في قواعد NoSQL مثل MongoDB، تبادل رسائل WebSocket، و package.json(مفروض من npm).

YAML تتخلّى عن الأقواس والفواصل لصالح المسافات البادئة (indentation). النتيجة: ملفات تبدو كقوائم نقطية في Word، سهلة القراءة من النظرة الأولى. لهذا اختارتها Kubernetes، Ansible، Docker Compose، GitHub Actions، GitLab CI، Helm، و OpenAPI/Swagger.

نقاط القوة: قابلة للقراءة، تدعم التعليقات بـ #، تدعم المراجع (&, *) لتجنّب التكرار، تدعم Multi-line strings بأنماط مختلفة (|,>). نقاط الضعف: المسافات البادئة هشّة جداً — مسافة واحدة خاطئة تكسر الملف بأكمله، صعبة في التحرير الآلي، عرضة لـ "Norway problem" (NO يُفسَّر كـ boolean false في YAML 1.1)، وتحتاج مكتبة خارجية في معظم اللغات.

استخدم YAML في: ملفات DevOps (Kubernetes manifests, Docker Compose, CI/CD)، توثيق OpenAPI، إعدادات Ansible. تجنّبها في: ملفات الضبط التي يحرّرها مستخدمون نهائيون غير تقنيين، أو الملفات المُولَّدة آلياً (JSON أسهل).

TOML تجمع قابلية القراءة من YAML مع الصرامة من JSON. صيغتها بسيطة: key = value، تواريخ أصلية، و[sections] للتجميع. لا تعتمد على المسافات البادئة، وتدعم التعليقات.

نقاط القوة: لا غموض في التفسير، سهلة الكتابة يدوياً، صارمة مع الأنواع (تفرّق بين 1 و 1.0 و"1")، تدعم تواريخ ISO 8601 أصلية. نقاط الضعف: أقل شعبية، التداخل العميق يصبح verbose، ليست مدعومة أصلياً في معظم اللغات (تحتاج مكتبة).

استخدم TOML في: ملفات ضبط أدوات سطر الأوامر (Cargo.toml لـ Rust، pyproject.toml لـ Python، Hugo)، الإعدادات الثابتة التي نادراً ما تتغيّر، أي ملف ضبط يحتاج تواريخ أو أنواعاً صارمة.

تخيّل ملف ضبط لخادم ويب: اسم المشروع، إصدار، قائمة ميزات، وإعدادات الخادم (host + port). في JSON، نحتاج 7 أسطر مع أقواس وفواصل. في YAML، نحتاج 5 أسطر بدون أي رمز إضافي. في TOML، نحتاج 5 أسطر أيضاً لكن مع [server] صريح.

عند التداخل العميق (5 مستويات أو أكثر)، JSON يصبح كابوساً من الأقواس، YAML يصبح خطيراً من المسافات، TOML يصبح verbose من [section.sub.subsub]. الحل: استخدم الصيغة المناسبة لعمق بياناتك. للضبط البسيط (1-2 مستوى)، TOML الأفضل. للضبط المتوسط (3-4 مستويات)، YAML الأفضل. للبيانات الديناميكية المُولَّدة آلياً، JSON دائماً.

ليست كل البيانات قابلة للتحويل بشكل lossless. JSON لا تدعم التعليقات، لذا تحويل YAML/TOML إلى JSON يفقد جميع التعليقات. YAML تدعم أنواعاً غير موجودة في JSON (مثل المراجع &anchor) — التحويل يفكّكها لكن يفقد النية الأصلية. TOML تدعم تواريخ أصلية، JSON تخزّنها كنصوص.

القاعدة: التحويل من JSON إلى أي صيغة آمن (JSON مجموعة فرعية)، لكن التحويل من YAML/TOML إلى JSON ثم العودة قد يفقد معلومات. إذا كنت تحرّر ملف ضبط مهم، حرّره في صيغته الأصلية دائماً.

الأداة أعلاه تتعامل مع الصيغ الثلاث الشائعة. لحالات نادرة (YAML معقّدة بمراجع متشعّبة، TOML بتواريخ ذات منطقة زمنية)، استخدم مكتبات مخصّصة مثل js-yaml أو@iarna/toml.

مشروع Node.js جديد؟ package.json (مفروض). إعدادات إضافية؟ TOML في ملف منفصل أو JSON. مشروع Rust؟Cargo.toml (مفروض). مشروع Python حديث؟pyproject.toml (PEP 518). نشر على Kubernetes؟ YAML بدون نقاش. CI/CD على GitHub أو GitLab؟ YAML. أداة CLI تحتاج ملف ضبط بسيط؟ TOML. API يرسل بيانات للمتصفّح؟ JSON دائماً.

لا تختر صيغة لأنها "أحدث" أو "أجمل". اختر الصيغة التي يفرضها النظام البيئي (ecosystem) لمشروعك. مقاومة المعيار تكلّف وقتاً ومتاعب للمساهمين الجدد.

ثغرة Billion Laughs (هجمة XML/YAML شهيرة) تُظهر أنّ YAML غير الموثوق خطر: مرجع &a يتوسّع إلى مليار سطر ويُنهك الذاكرة. JSON أكثر أماناً لأنّها لا تَدعم المراجع، لكنّ JSON كبيراً يَستهلك ذاكرةً أيضاً. القاعدة: لا تَستهلك ملفّاً من مصدر خارجيّ بدون تحديد سقف للحجم وعمق التداخل قبل التحليل.

استخدم JSON Schema للتحقّق من بنية JSON قبل الاعتماد عليها. ajv في Node.js و jsonschemaفي Python يَفرضان الأنواع، الحقول المطلوبة، وأنماط النصوص (مثل البريد الإلكترونيّ أو UUID). نفس المنطق لـ YAML عبرkubeval (لملفّات Kubernetes) و actionlint(لـ GitHub Actions). التحقّق المبكّر يكتشف 90% من أخطاء النشر.

للمشاريع العربيّة، انتبه أنّ JSON تَفرض UTF-8 افتراضيّاً، YAML تَدعم UTF-8 و UTF-16 و UTF-32، و TOML تَفرض UTF-8 فقط. عند تخزين نصوص عربيّة، JSON قد تُرمِّز الحروف كـ \u0627\u0644...إن استخدمت إعداداً قديماً. ensure_ascii=False في Python أو JSON.stringify الحديث في JavaScript يَحفظ الحروف العربيّة كما هي ويُقلّل الحجم بالنصف.