JSON أوسع صيغ التبادل انتشارًا على الويب: ردود واجهات البرمجة، وملفات الإعداد، وتصدير البيانات. وهو مقروء للبشر لكنه صارم جدًا أيضًا، وتكفي فاصلة منسية أو زائدة لتجعله غير مقروء لبرنامج. يشرح هذا الدليل قواعده وكيفية تشخيص الخطأ والانتقال من صيغة إلى أخرى دون إتلاف البيانات.
القواعد التي ينبغي معرفتها
يحتوي مستند JSON كائنات ({"key": value}) ومصفوفات ([1, 2, 3]) ونصوصًا وأعدادًا وtrue وfalse وnull. لا شيء غير ذلك. وهذه القواعد تفسر تقريبًا كل خطأ:
- المفاتيح والنصوص تستخدم علامات اقتباس مزدوجة. علامات الاقتباس المفردة ('a') غير صالحة.
- لا فاصلة بعد العنصر الأخير في كائن أو مصفوفة.
- لا تعليقات. لا // ولا /* */ في JSON.
- لا قيم خاصة مثل NaN أو Infinity أو undefined.
- يجب أن توضع المفاتيح بين علامات اقتباس، بخلاف كائنات JavaScript.
التنسيق والتحقق خطوة بخطوة
- الصق JSON في منسّق JSON أو أفلت ملفًا (25 مليون حرف كحد أقصى). يُنسَّق فورًا بمسافتين أو 4 مسافات أو علامة جدولة، ويمكن فرز المفاتيح أبجديًا في كل المستويات.
- تصفح النتيجة شيفرة ملونة أو شجرة قابلة للطي؛ وفي المستند الكبير تفتح الشجرة المستويات المفيدة فقط وتعرض القوائم الطويلة على دفعات من 100.
- عند الخطأ اقرأ الرسالة: السطر والعمود ومقتطف بعلامة تشير إلى الموضع والسبب المرجح (فاصلة زائدة، علامات اقتباس مفردة، مفتاح بلا اقتباس، تعليق، NaN).
لماذا الأعداد الكبيرة فخ
تمثّل JavaScript كل الأعداد أعدادًا عائمة بدقة مضاعفة: فبعد 9,007,199,254,740,991 (2⁵³ − 1) لا تُمثَّل الأعداد الصحيحة بدقة. فالمعرّف 12345678901234567890 إذا قرأه ثم أعاد كتابته برنامج JavaScript صار 12345678901234567000. ومعظم الأدوات تمر بهذه المحطة دون أن تقول. أما أدواتنا فتنسخ الأعداد كما كتبتها: معرّف من 20 رقمًا أو 92.50 أو 1E5 لا تتغير. وإن كانت بياناتك تحتوي معرّفات طويلة فالأفضل إرسالها نصوصًا.
أخطاء شائعة
- نسخ كائن JavaScript (مفاتيح بلا اقتباس، علامات اقتباس مفردة) على أنه JSON.
- ترك فاصلة بعد العنصر الأخير، عادة من لغات أخرى.
- لصق JSON بتعليقات من ملف إعداد (JSONC) في أداة تشترط JSON صارمًا.
- فتح CSV في Excel بلا BOM ورؤية الحروف المشكولة أو العربية تالفة.
- تحويل معرّفات أطول من 15 رقمًا بأداة تقرّبها.
حدود ينبغي الاعتراف بها
- 25 مليون حرف كحد أقصى: وما بعد ذلك استخدم أداة سطر أوامر.
- المفاتيح المكررة تُرصد وتُحفظ، لكن معناها يختلف بين القارئات: تجنبها.
- CSV صيغة مسطحة: وتحويل JSON شديد التداخل يفقده سهولة القراءة.
الأسئلة الشائعة
لماذا يُرفض JSON الخاص بي وهو يعمل في JavaScript؟
لأن كائن JavaScript يقبل مفاتيح بلا اقتباس وعلامات اقتباس مفردة وفواصل أخيرة، وكلها ممنوعة في JSON.
هل تُرسل بياناتي إلى أي مكان؟
لا. يجري التنسيق والتحقق والتحويل في متصفحك.
كيف أمنع Excel من تنفيذ صيغة مخفية في CSV؟
يسبق محوّلنا كل نص يبدأ بـ = أو + أو - أو @ بفاصلة عليا. أما الأعداد الحقيقية فلا تُمسّ.
هل يمكن وضع تعليقات في JSON؟
لا. وللإعداد المعلَّق استخدم YAML أو صيغة مشتقة مثل JSONC التي ترفضها أدوات JSON الصارمة.
أي مسافة بادئة أختار؟
مسافتان هي العرف الأكثر انتشارًا في الويب؛ و4 مسافات أو علامة جدولة شائعة أيضًا. هي مسألة عرف فريق؛ ولا يتغير معنى البيانات.