JSON غير صالح؟ 7 أخطاء وراء كل رسالة خطأ تقريبًا

«Unexpected token» و«Unexpected end of JSON input» من أكثر رسائل الخطأ التي يراها المطورون. JSON تنسيق صارم، أشد صرامة بكثير من JavaScript التي نشأ منها، ويعود كل فشل تقريبًا إلى واحد من أخطاء قليلة معروفة.

1. فاصلة في النهاية

الفاصلة بعد آخر عنصر في كائن أو مصفوفة هي الخطأ الأول. تقبلها JavaScript، أما معيار JSON فلا.

{"name": "Ana", "age": 31,}   ✗
{"name": "Ana", "age": 31}    ✓

2. علامات اقتباس مفردة و3. مفاتيح بلا علامات اقتباس

يجب أن يكون كل مفتاح وكل نص بين علامتي اقتباس مزدوجتين. ⁦{name: 'Ana'}⁩ صالح في JavaScript لكنه JSON غير صالح، والصحيح ⁦{"name": "Ana"}⁩.

4. التعليقات

لا توجد تعليقات في JSON. ⁦//⁩ و⁦/* */⁩ أخطاء، وهذا يفاجئ من ينسخ من ملف إعدادات مكتوب بصيغة JSON5 أو JSONC، مثل إعدادات VS Code.

5. القيم الخاصة و6. المحارف غير المهرّبة

لا وجود في JSON لـ undefined وNaN وInfinity والدوال؛ استخدم null أو رقمًا. داخل النص تُكتب علامة الاقتباس المزدوجة ⁦\"⁩ والشرطة المائلة العكسية ⁦\\⁩ وفاصل السطر ⁦\n⁩. مسارات Windows فخ كلاسيكي: ⁦"C:\new"⁩ يحتوي على فاصل سطر، لا على شرطة مائلة عكسية يليها الحرف n.

7. أقواس ناقصة أو زائدة

القوس الختامي } أو ] الناقص يظهر عادةً كخطأ في نهاية النص تمامًا، بعيدًا عن موضع المشكلة الحقيقي. تنسيق JSON بإزاحات يكشف فورًا المستوى المكسور.

أخطاء يصعب رؤيتها

بعض JSON غير الصالح يبدو مثاليًا على الشاشة:

• علامات الاقتباس المنحنية. النص المنسوخ من معالج نصوص أو تطبيق محادثة أو عرض تقديمي يحمل غالبًا “ و” بدل علامات الاقتباس المزدوجة المستقيمة. تبدو متشابهة تقريبًا، لكن JSON لا يقبل إلا الحرف " المستقيم.
• علامة ترتيب البايتات (BOM). بعض المحررات في Windows تحفظ الملفات مع حرف غير مرئي في البداية. ‏JSON.parse في JavaScript و json.loads في Python يرفضانه، ويشير الخطأ إلى الموضع 0.
• المسافات غير القابلة للكسر وغيرها من المحارف غير المرئية الملصوقة من صفحات الويب.

JSON صالح لكنه يسبب أخطاء

تكتب json.dumps في Python القيمتين NaN و Infinity افتراضيًا، وترفضهما محللات أخرى؛ مرّر allow_nan=False لاكتشاف ذلك مبكرًا. الأعداد الصحيحة الكبيرة جدًا، مثل معرّفات قواعد البيانات ذات 64 بت، هي JSON صالح لكنها تفقد دقتها في JavaScript بعد 9007199254740991، ولهذا ترسلها واجهات API كثيرة كنصوص. معظم المحللات تقبل المفاتيح المكررة، لكن القيمة الأخيرة تفوز بصمت.

كيف تقرأ رسالة الخطأ

يبلّغ المحلل عن المكان الذي توقف عنده، لا عن مكان خطئك. الفاصلة الناقصة تُذكر عادة في بداية المفتاح التالي، والقوس الختامي الناقص في نهاية المدخلات تمامًا. انظر قبل الموضع المذكور مباشرة.

{
  "name": "Ana"
  "age": 31        ← يُبلَّغ عن الخطأ هنا (السطر 3)
}                   الفاصلة الناقصة في نهاية السطر 2

اعثر على الموضع بالضبط

يتحقق مدقق JSON من 4Dev من نصك وفق معيار JSON ‏(RFC 8259) ويعرض سطر وعمود أول خطأ مع اقتراح للإصلاح. إنه يتحقق من الصياغة لا من المعنى: قد يكون JSON صالحًا ومع ذلك يحتوي على نوع خاطئ أو حقل ناقص بالنسبة لتطبيقك.

افتح مدقق JSON