أخطاء JSON الشائعة: لماذا يفشل الملف وكيف تصلحه؟

JSON لا يقرأ نيتك. قد يكون الملف واضحًا بالنسبة لك، لكن فاصلة بعد آخر عنصر أو علامة اقتباس مفردة تكفي لإيقاف التحليل. التعامل الجيد مع الخطأ يبدأ من القواعد، لا من التجربة العشوائية.

المرجع IETF RFC 8259 يحدد JSON كصيغة تبادل بيانات نصية ويعرض قواعدها النحوية واعتبارات التشغيل البيني. ECMA-404 يصف بناء الصيغة نفسه من جهة ECMA International. عندما نريد معرفة هل تركيب معين JSON صحيح أم مجرد نص يشبهه، هذان مرجعان أصليان. [المصدر: IETF RFC 8259] [المصدر: ECMA-404]

أخطاء الصياغة التي توقف التحليل

هذه المجموعة تجمع أخطاء صغيرة في الشكل، لكنها كافية لجعل JSON غير صالح حتى لو كان المقصود واضحًا للإنسان.

الفاصلة الأخيرة: خطأ صغير وواضح بعد أن تراه

{
  "name": "Nora",
  "age": 29,
}

{
  "name": "Nora",
  "age": 29
}

المشكلة أن بعض لغات البرمجة أو الأدوات تتسامح مع trailing commas في سياقات أخرى. لذلك نسخ كائن من JavaScript ثم وضعه كما هو داخل ملف JSON قد يفشل رغم أن الشكل يبدو مألوفًا.

علامات الاقتباس المفردة ليست بديلًا

{
  'city': 'Rabat'
}

{
  "city": "Rabat"
}

هذا ليس اختيارًا تجميليًا. إذا قبل برنامج ما single quotes فهو إما يقرأ صيغة موسعة أو يحول المدخل قبل التحليل، لكنه لم يعد يتعامل مع JSON القياسي كما هو.

اسم الخاصية نفسه يجب أن يكون string

{
  name: "Yasmine"
}

{
  "name": "Yasmine"
}

التعليقات داخل JSON القياسي غير موجودة

كتابة // comment أو /* comment */ داخل الملف ليست جزءًا من صيغة JSON القياسية. إذا كنت تحتاج شرحًا، ضعه خارج الملف أو ضمن بنية البيانات فقط عندما يكون النظام المستهدف يتوقع تلك الخاصية.

{
  "enabled": true // إعداد تجريبي
}

{
  "enabled": true,
  "_note": "إعداد تجريبي"
}

القوس الناقص قد يجعل رسالة الخطأ تظهر بعيدًا عنه

في ملف طويل، قوس مفقود في منتصف كائن أو مصفوفة قد لا ينكشف فورًا. المحلل يستمر حتى يصل إلى موضع لم يعد قادرًا على تفسيره، لذلك السطر الذي تشير إليه الرسالة ليس دائمًا بداية المشكلة.

قيم ونصوص تحتاج انتباهًا خاصًا

بعد إصلاح الفواصل والأقواس، تظهر فئة ثانية من الأخطاء: قيم تبدو طبيعية لكنها تحتاج تمثيلًا دقيقًا داخل JSON.

علامة الاقتباس داخل النص تحتاج Escape

إذا احتوى النص نفسه على علامة اقتباس مزدوجة، يجب تمثيلها بطريقة لا تجعل المحلل يظن أن السلسلة انتهت. RFC 8259 يحدد escape sequences للنصوص، ومنها الاقتباس وbackslash والسطر الجديد والتبويب، إضافة إلى تمثيل محارف Unicode بصيغة U+hex المناسبة للتبادل النصي.

{
  "message": "قال "مرحبا""
}

{
  "message": "قال \"مرحبا\""
}

الأرقام ليست منطقة مفتوحة أيضًا

القواعد القياسية لا تقبل NaN أو Infinity كأرقام JSON. كما أن الرقم لا يبدأ بصفر إضافي مثل 01، باستثناء الصفر نفسه. الجزء العشري والأسّي لهما بناء محدد.

true وfalse وnull بحروف صغيرة كما هي

القيم الحرفية في JSON هي true وfalse وnull. كتابة True أو NULL تجعل النص خارج القواعد القياسية.

هذا النوع من الأخطاء يمر على العين بسهولة لأن الإنسان يفهم المقصود. المحلل لا يجامل؛ يطابق الصيغة.

تكرار اسم الخاصية: قد يمر التحليل وتبقى المشكلة

RFC 8259 ينص على أن أسماء الخصائص داخل الكائن ينبغي أن تكون فريدة. عندما يتكرر المفتاح، سلوك البرامج قد يختلف: برنامج يحتفظ بالقيمة الأخيرة، برنامج آخر يعرض أكثر من قيمة، وثالث يتصرف بطريقة مختلفة.

الترميز ومحارف النص

قد تكون البنية سليمة ومع ذلك يظهر النص مشوهًا أو يفشل التحليل بسبب ترميز أو محارف تحكم. هنا المشكلة ليست في القوس أو الفاصلة.

UTF-8 مهم خصوصًا عندما تدخل العربية في الصورة

RFC 8259 يطلب استخدام UTF-8 لتبادل JSON بين الأنظمة خارج البيئات المغلقة. إذا فُسرت البايتات بترميز آخر، قد تحصل على أحرف عربية مشوهة بينما البنية النحوية للملف سليمة.

لا تعالج النص المشوه بإضافة escapes عشوائية. تأكد أولًا أن المصدر والحفظ والقراءة يستخدمون UTF-8 بصورة صحيحة.

المحارف التحكمية داخل النص يجب أن تكون مهروبة

RFC 8259 لا يسمح بوضع محارف التحكم U+0000 إلى U+001F مباشرة داخل string. إذا احتجت سطرًا جديدًا أو تبويبًا، استخدم تمثيل الهروب المناسب مثل \n أو \t. المشكلة تظهر كثيرًا عندما يُنسخ نص خام من ملف أو حقل متعدد الأسطر ثم يُلصق داخل JSON يدويًا.

إذا رأيت ملفًا يبدو سليمًا لكن المحلل يرفض قيمة نصية طويلة، افحص وجود أسطر جديدة أو محارف تحكم غير مهروبة داخلها. أحيانًا الخطأ غير مرئي تقريبًا في المحرر.

قيود التطبيق ليست دائمًا قيود JSON

JSON لا يشترط أن يبدأ دائمًا بكائن أو مصفوفة

RFC 8259 يعرّف JSON text بأنه قيمة JSON مُسلسلة. هذا يعني أن القيمة العليا يمكن أن تكون كائنًا أو مصفوفة أو نصًا أو رقمًا أو true أو false أو null. بعض الأنظمة القديمة كانت تتوقع object أو array فقط، لذلك قد تجد تطبيقًا يرفض قيمة عليا صالحة وفق المعيار بسبب قيود التطبيق نفسه.

هذه نقطة مهمة عند التشخيص: فشل نظام معين في قبول JSON لا يثبت دائمًا أن النص مخالف للمعيار. أحيانًا النظام يفرض schema أو قيدًا إضافيًا فوق JSON نفسه.

الأرقام الكبيرة قد تكون صالحة نحويًا وغير آمنة للتبادل

RFC 8259 يلفت الانتباه إلى اختلاف حدود ودقة الأرقام بين البرامج، ويذكر أن الأعداد الصحيحة ضمن المجال من -(2^53)+1 إلى (2^53)-1 تحقق توافقًا دقيقًا واسعًا مع التطبيقات التي تستخدم IEEE 754 binary64، وهو شائع جدًا في البرمجيات.

إذا أرسلت رقم تعريف ضخمًا جدًا كرقم، قد يقرأه طرف آخر بدقة مختلفة. في الأنظمة التي تتعامل مع معرفات طويلة لا تحتاج حسابًا رياضيًا، قد يكون تمثيلها كنص أكثر أمانًا بحسب تصميم الـAPI نفسه. هنا لا توجد قاعدة واحدة لكل مشروع؛ ارجع إلى توثيق النظام الذي تتكامل معه.

طريقة عملية للتشخيص

سلم تصحيح يمنعك من مطاردة عشرة أخطاء معًا

أحيانًا المشكلة ليست في JSON الذي كتبته أصلًا

تطلب Endpoint وتتوقع JSON، لكن الخادم يرجع صفحة HTML بسبب خطأ أو صفحة تسجيل دخول. بعدها يفشل التحليل وتبدأ أنت بالبحث عن فاصلة ناقصة في مكان لا علاقة له بالمشكلة.

انظر إلى أول جزء من الاستجابة وإلى رمز HTTP قبل أن تعدل الملف. هذه عادة بسيطة، لكنها توفر وقتًا حقيقيًا.

ECMA-404 وRFC 8259: نفس الصيغة من زاويتين

ECMA-404 يعرّف بناء JSON بصورة مختصرة من جهة ECMA International. RFC 8259 يحدد JSON كصيغة تبادل بيانات على الإنترنت ويضيف اعتبارات مهمة للتوافق والترميز والأمن.

لهذا أعتمد الاثنين هنا: ECMA-404 للتركيب الأساسي، وRFC 8259 للتفاصيل العملية التي تؤثر عندما تمر البيانات بين أنظمة مختلفة.

نجاح التحليل لا يعني أن البيانات نفسها صحيحة

قد يكون JSON صالحًا نحويًا لكنه يحتوي تاريخًا خاطئًا، نوع بيانات غير متوقع، قيمة ناقصة، أو معرفًا لا وجود له. هناك سؤالان منفصلان:

• هل النص JSON صالح؟
• هل البيانات صحيحة بالنسبة للتطبيق؟

الأداة تساعدك في السؤال الأول. السؤال الثاني يحتاج معرفة الـschema أو الـAPI أو النظام الذي سيستهلك البيانات.

مثال واقعي: خطأ واحد يولد ثلاث رسائل

لديك كائن داخله مصفوفة، ونسيت علامة اقتباس في قيمة نصية. قد ترى رسالة عن نهاية غير متوقعة، ثم عن فاصلة، ثم عن قوس. إصلاح الاقتباس الأول قد يمحو الرسائل الثلاث. لهذا لا تصلح كل ما يظهر دفعة واحدة.

في التصحيح، التسلسل أهم من السرعة: أول خطأ حقيقي، ثم إعادة فحص، ثم الخطأ التالي إن بقي.