JSON أم TOML أم YAML أم CSON: اختيار صيغة الإعداد

الخلاصة: استخدم JSON للتبادل الآلي، واختر TOML أو YAML للإعداد الذي يصونه البشر وفق المنظومة (YAML لـ Kubernetes وCI، وTOML للبنى المسطحة أو التواريخ الأصلية)؛ ولا تلجأ إلى JSONC إلا عندما لا تكون متأكدًا من دعم القارئ للهجة.

وُجد JSON للآلات التي تتبادل البيانات؛ أما ملف الإعداد فيكتبه البشر للبشر. اخلط الاثنين وستحصل على config.json لا يستطيع حمل تعليق ولا يجرؤ أحد على تقليمه.

1. ابدأ بنوعين مختلفين من الملفات

لا يتشارك تبادل البيانات والإعداد الهدف نفسه، حتى إن كان الشخص نفسه يكتب الاثنين غالبًا على الجهاز ذاته.

يسجل JSON نقاطًا شبه كاملة في العمود الأيسر: قواعد أدنى، ومحلل في كل لغة، وغياب التعليقات يعني غياب مشكلة "انحراف التعليق عن القيمة". أما في العمود الأيمن، فصرامته احتكاك محض: لا تعليقات، لا فواصل زائدة، لا تواريخ، والنص متعدد الأسطر يجب طيّه إلى سطر واحد بـ \n.

2. المتنافسون الأربعة وصياغتهم

• JSON: معرف في RFC 8259 وECMA-404، بستة أنواع قيم بالضبط: كائن ومصفوفة ونص وعدد وقيمة منطقية وnull. إنه معيار التبادل الفعلي والصيغة الوحيدة التي لا تحتاج إلى قرار اختيار.
• TOML: أنشأه Tom Preston-Werner، ونُشر الإصدار v1.0.0 في يناير 2021. هدفه المعلن صيغة إعداد أدنى بدلالات واضحة تُقابل جدول تجزئة بلا التباس. ويستخدمه Cargo.toml وpyproject.toml افتراضيًا.
• YAML: المواصفة الحالية 1.2.2. الإزاحة البادئة تعبر عن التسلسل الهرمي، ويدعم التعليقات والمراسي والمستندات المتعددة. تعتمد عليه manifests الخاصة بـ Kubernetes وGitHub Actions وAnsible، بكلفة مواصفة كبيرة وفروق في التنفيذ.
• CSON: CoffeeScript Object Notation، يكتب الإعداد باستخدام حرفيات كائن CoffeeScript. استخدمه config.cson في Atom. يدعم التعليقات والمفاتيح غير المقتبسة والفواصل الزائدة، لكن منظومته لم تغادر عالم JavaScript أبدًا.

2.1 مقارنة القدرات

خليتان تستحقان ملاحظة. لا يملك TOML null، وهو أكثر إخفاق شيوعًا عند التحويل من JSON. ويعني سلوك "التاريخ الأصلي" في YAML أن محلل 1.1 يحوّل 2026-10-31 إلى كائن تاريخ تلقائيًا، فينحرف النوع عبر اللغات.

3. التعليقات: نقطة ضعف JSON الوحيدة

الاستنتاج أولًا: إن كان الإنسان هو من يصون الملف ويحتاج إلى شرح سبب قيمة ما، فلا تستخدم JSON القياسي.

هناك أربعة مسارات عملية، مرتبة بحسب درجة تدخلها:

1. انتقل إلى JSONC، وهو JSON قياسي مع تعليقات وفواصل زائدة. يستخدمه settings.json وtsconfig.json في VS Code. الكلفة أن القارئ يجب أن يستخدم محللًا مدركًا للتعليقات مثل jsonc-parser؛ أما JSON.parse العادي فيفشل. التفاصيل في JSON5 وJSONC: JSON مع تعليقات.
2. أبقِ مستندًا مرافقًا. يبقى config.json مقروءًا آليًا، بينما يشرح config.md معنى كل حقل وسبب حمل تلك القيمة. يعيش الاثنان في الدليل نفسه ويتغيران في الإيداع نفسه.
3. ضع الشروح في المخطط. تستطيع الكلمتان المفتاحيتان description و$comment في JSON Schema توثيق الحقول، لكن المخططات نادرًا ما تُشحن مع إعداد وقت التشغيل، فقد لا يراها قارئ الإعداد أبدًا.
4. انتقل إلى TOML أو YAML، لتوفر الصيغة نفسها تعليقات يفهمها كل محلل.

复制{
  // ثابت على 8080: يقرأ سكربت بناء الواجهة هذا المنفذ من أجل الوكيل
  "port": 8080,
  // عطّل المراقبة لتجنب استنزاف inodes في CI
  "watch": false
}

يبقى JSONC لهجة: يبقى الامتداد .json، لكن بعض الأدوات فقط تفهمه. وعندما تغادر البيانات الفريق أو تعبر حدود خدمة، يجب توثيق الحد بين JSONC وJSON القياسي.

4. التواريخ والنصوص متعددة الأسطر: أرض TOML الأصلية

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

复制title = "json-toolkit"
created = 2026-10-31T09:00:00+08:00
description = """
A JSON toolkit for developers.
Every operation runs locally in the browser.
"""

المعلومات نفسها في JSON يجب أن تخفض التاريخ إلى نص وتهرب فواصل الأسطر:

复制{
  "title": "json-toolkit",
  "created": "2026-10-31T09:00:00+08:00",
  "description": "A JSON toolkit for developers.\nEvery operation runs locally in the browser."
}

في JSON، "created" مجرد نص يشبه التاريخ صدفة، فمعلومات النوع يجب أن تعيش في عقد حقل: يجب أن يتفق الطرفان على أن الحقل دائمًا RFC 3339. أما TOML فيمنح المحلل كائن تاريخ فعليًا دون اتفاق كلامي.

يستطيع YAML حمل نص متعدد الأسطر أيضًا، لكن نمطي الكتلة يعنيان أمرين مختلفين: يحفظ | فواصل الأسطر بينما يطويها > إلى مسافات. اختر الخاطئ فينهار عنوان أو عبارة SQL في سطر واحد، وهو خطأ يصعب اكتشافه جدًا في المراجعة.

5. الأعداد: الفرق الأكثر تجاهلًا

لا تضع مواصفة JSON حدًا لدقة الأعداد، لكن RFC 8259 يحذر أيضًا من أن التشغيل البيني يكون آمنًا أكثر عندما تُعامل الأعداد كـ double من IEEE 754. في JavaScript، تفقد الأعداد الصحيحة فوق 2^53 - 1 دقتها بصمت:

复制JSON.parse('{"id":9007199254740993}').id
// 9007199254740992: الرقم الأخير اختفى

يشترط TOML معالجة الأعداد الصحيحة 64-بت الموقعة بلا فقد، ويرمي خطأً بدلًا من الاقتطاع بصمت؛ أما الأعداد العشرية فتتبع binary64 وقد تكون أيضًا inf أو nan. يحمل YAML 1.1 عبئًا أقدم: يُحلل 1:30 كـ 90 (ستينيًا)، وتقبل القيم المنطقية yes وno وon وoff. ومن هنا "مشكلة النرويج" الشهيرة، حيث يصبح رمز الدولة NO هو false.

للنقود، لا تعتمد على الفاصلة العائمة في أي من هذه الصيغ أبدًا: استخدم وحدات صغرى صحيحة أو نصوصًا أو نوعًا عشريًا في قاعدة البيانات. يُغطى التنسيق والدقة بعمق أكبر في حدود التحويل بين JSON وYAML وXML.

6. الجداول والتداخل: حدود TOML الصلبة

يعبّر TOML عن التداخل بالجداول ومصفوفات الجداول:

复制[server]
port = 8080

[[routes]]
path = "/parse"
method = "POST"

[[routes]]
path = "/minify"
method = "POST"

له حدان صلبان يجب معرفتهما قبل التحويل:

• جذر مستند TOML جدول، فمستند JSON مستواه الأعلى مصفوفة (مثل [1, 2, 3]) لا تمثيل TOML قانونيًا له؛ يجب تغليفه كـ {"items": [...]}؛
• لا يملك TOML null، فحقل null في JSON يجب إما حذفه أو استبداله بسلسلة فارغة أو قيمة علامة، مع دفع الدلالات إلى المستهلك.

YAML هو العكس: عمق التداخل غير محدود، والمراسي مع مفاتيح الدمج يمكنها إعادة استخدام الأجزاء:

复制defaults: &defaults
  retries: 3
  timeoutMs: 5000

server:
  <<: *defaults
  port: 8080

المراسي قدرة خاصة بـ YAML وخسارة مؤكدة عند التحويل: لا تملك JSON صياغة مراجع، فالملف الموسع ينمو ولا يسجل شيء أن القسمين كانا الإعداد نفسه.

7. الاختيار بحسب السياق

قاعدة عملية واحدة: دع المنظومة تختار صيغة الإعداد، لا التفضيل الشخصي. كتابة Rust تعني Cargo.toml، والنشر إلى Kubernetes يعني YAML، وبناء إضافة VS Code يعني JSONC. فقط في مشروع جديد بلا قيود منظومة يكون "أيها أجمل كتابةً" سؤالًا حقيقيًا.

8. حدود التحويل

تضمن أدوات التحويل القيم، لا التعليقات أبدًا. لذا لا تصمم خط أنابيب ثنائي الاتجاه حيث "JSON هو المصدر وYAML ناتج بناء". إما ولّد في اتجاه واحد فقط، أو صُن ملف مصدر واحدًا.

9. قائمة الفحص

• [ ] وثّق أي أنواع الملفات تستخدم أي صيغة، واسرد اللهجات المسموحة؛
• [ ] فضّل TOML أو YAML للإعداد الذي يصونه البشر، وJSON للتبادل الآلي؛
• [ ] خزّن التواريخ في JSON كنصوص RFC 3339 وعلّم الصيغة في المخطط؛
• [ ] مثّل النقود والأعداد الصحيحة فوق 2^53 كنصوص أو وحدات صغرى، لا كأعداد عشرية؛
• [ ] تحقق من كل صيغة في CI بمحللها الخاص، ولا تستخدم JSON.parse لـ YAML أبدًا؛
• [ ] رحّل الصيغ في اتجاه واحد فقط، واحذف الملف القديم حتى لا ينحرف الاثنان.

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

لماذا يفشل تحويل JSON إلى TOML في بعض الحقول؟

لا يملك TOML null، وجذر مستند TOML جدول، فحقل null في JSON يجب حذفه أو استبداله بسلسلة فارغة أو قيمة علامة، والمصفوفة في المستوى الأعلى يجب تغليفها كـ {"items": [...]}. كما تُفقد التعليقات وأنواع التاريخ وinf/nan عند الحركة في الاتجاه المعاكس، ولهذا ينبغي أن يكون التحويل أحادي الاتجاه.

هل أُبقي ملفي إعداد بصيغتين مختلفتين؟

لا. تضمن أدوات التحويل القيم لكن لا التعليقات أبدًا، فخط أنابيب حيث "JSON هو المصدر وYAML ناتج بناء" سينحرف. إما ولّد في اتجاه واحد فقط، أو صُن ملف مصدر واحدًا واحذف القديم بعد الترحيل.

كيف أضيف تعليقات إلى ملف إعداد JSON؟

لا يملك JSON القياسي تعليقات. يمكنك الانتقال إلى JSONC (لهجة VS Code، وتُقرأ بـ jsonc-parser)، أو إبقاء مستند مرافق يشرح كل حقل، أو الانتقال إلى TOML أو YAML. أما الملفات المرسلة إلى أنظمة أخرى فينبغي أن تبقى JSON قياسيًا، مع عيش الشروح في التوثيق أو مخطط.

هل TOML أم YAML أفضل لإعداد التطبيقات؟

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

لماذا يتحول NO إلى false في YAML؟

يعامل YAML 1.1 yes وno وon وoff وy وn كقيم منطقية، فيُحلل رمز دولة النرويج NO كـ false. هذه "مشكلة النرويج". تجنبها باستخدام تنفيذ يتبع YAML 1.2، أو باقتباس كل نص قد يُفسر خطأً.

هل ما زال CSON يستحق الاستخدام؟

لا للمشاريع الجديدة. يعتمد CSON على منظومة CoffeeScript، وتدعمه أدوات مصانة قليلة، ودعمه في المحررات وCI محدود؛ وبعد توقف صيانة Atom تقلصت حالات استخدامه أكثر. إن كان لدى مشروع إعداد CSON أصلًا، فجدول ترحيلًا لمرة واحدة إلى JSON أو TOML أو YAML بدلًا من إضافة المزيد منه.