هل يمكن أن يحتوي JSON على تعليقات
الخلاصة: RFC 8259 ليس فيه صياغة للتعليقات، لذا يجعل `//` وتعليقات الكتل `JSON.parse` يرمي خطأ. استخدم JSON5 أو JSONC، أو حقل `_comment`، أو وصف Schema، أو YAML بدلًا من ذلك.
الخلاصة: لا تضع أبدًا تعليقات في JSON القياسي؛ استخدم JSONC أو JSON5 للتهيئة المحلية التي لا يحررها إلا البشر، وانقل التوضيحات إلى description في JSON Schema عندما يعبر الملف الأنظمة، وانتقل إلى YAML أو TOML بمجرد نمو حجم الحاشية.
لا.
أي محلل متوافق مع المعيار يرفض هذا:
{
"port": 8080 // local development only
}
يبلّغ Chrome برسالة SyntaxError: Unexpected token }. أصاب المحلل /، الذي لا يمكن أن يبدأ أي قيمة JSON، فتوقف.
لماذا تترك المواصفة التعليقات خارجها عن قصد
يعرّف RFC 8259 ست قيم: كائن، ومصفوفة، وعدد، وسلسلة نصية، وtrue/false، وnull. لا يوجد إنتاج للتعليقات.
اقتُرحت التعليقات مبكرًا ورُفضت لسبب ملموس: بمجرد أن تصبح التعليقات قانونية، يستخدمها أحدهم لحمل توجيهات — تضمينات شرطية، ومتغيرات قوالب — فينمو لكل محلل لهجته الخاصة. تنكسر قابلية التشغيل البيني عند أول خطوة. JSON بيانات فقط عن قصد، ولا شيء قابل للتنفيذ بداخله.
أربع طرق للاحتفاظ بملاحظاتك
1. استخدم مجموعة شاملة. JSON5 وJSONC يقبلان نمطي التعليقات. settings.json وtsconfig.json في VS Code هما JSONC.
الكلفة حقيقية: JSON.parse ما زال يرفضهما، وAPIs وخطوط السجلات وقوائم الرسائل تقبل عادة JSON قياسيًا فقط. تعليقك يُسقط بصمت أو يرمي في مكان ما في المصب.
2. ضع الملاحظة في البيانات.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
يعمل في كل مكان، لكنه يلوّث النموذج: كل مستهلك يجب أن يعرف المفاتيح التي يتجاهلها، وتعريف نوعك يكتسب حقلًا ليس بيانات فعلية.
3. استخدم وصف Schema. description مخصص للبشر والأدوات. تعرضه المدققات، ويعرضه المحرر عند مرور المؤشر، ولا يدخل الحمولة أبدًا. هذا الخيار الوحيد الذي يبقى عبر الصيانة طويلة المدى دون كسر التوافق.
4. غيّر تنسيق الملف. إن كان الملف موجودًا ليُحرَّر يدويًا، فـYAML أو TOML يدعمان التعليقات أصليًا. مصارعة JSON هنا جهد مهدر.
الاختيار
| الحالة | الإجابة |
|---|---|
| يُرسل إلى نظام آخر، عبر API أو قائمة انتظار | بلا تعليقات؛ وثّق في Schema أو وثائق خارجية |
| تهيئة يقرأها البشر والمحررون فقط | JSONC، بامتداد .jsonc |
| يحتاج إلى أدوات شاملة وتوضيح مضمّن | JSON قياسي مع description في Schema |
| تهيئة طويلة كثيرة الحاشية | انتقل إلى YAML |
الأسئلة الشائعة
لماذا يلوّث حقل _comment النموذج؟
لأنه يصبح جزءًا من البيانات. كل مستهلك يجب أن يعرف المفاتيح التي يتجاهلها، ويتكسب تعريف النوع حقلًا ليس بيانات أعمال فعلية.
هل يجب أن يكون التوضيح في وصف JSON Schema؟
نعم. يبقى description خارج الحمولة، بينما تعرضه المدققات ويظهره المحرر عند مرور المؤشر، لذا هو الخيار الوحيد الذي يبقى عبر الصيانة طويلة المدى دون كسر التوافق.
هل يمكن لـJSONC أو JSON5 أن يُحلَّلا بـJSON.parse؟
لا. JSON.parse ما زال يرفض التعليقات، وAPIs وخطوط السجلات وقوائم الرسائل تقبل عادة JSON قياسيًا فقط، فيُسقط التعليق أو يرمي في مكان ما في المصب.
الأدوات
- محلل JSON5 — الصق تهيئة فيها تعليقات وشاهد البنية المحلولة
- منسّق ومدقق JSON — يُبلَّغ عن JSON غير القانوني بالسطر والعمود، فيظهر التعليق المخالف بوضوح