كيف تصلح JSON غير صالح: أكثر 8 أخطاء شيوعًا

قواعد JSON في 30 ثانية

يشبه JSON ‏(JavaScript Object Notation) لغة JavaScript، لكنه أكثر صرامة بكثير:

• يجب أن تكون المفاتيح نصوصًا بين علامات اقتباس مزدوجة.
• تستخدم النصوص علامات الاقتباس المزدوجة فقط.
• يمكن أن تكون القيمة نصًا أو رقمًا أو true أو false أو null أو كائنًا أو مصفوفة.
• تُفصل العناصر بفواصل، دون فاصلة بعد العنصر الأخير.
• لا تعليقات، ولا undefined، ولا دوال.

اعثر على الخطأ بسرعة

1. افتح منسّق JSON ومدققه المجاني.
2. الصق JSON أو أفلت ملف ‎.json.
3. إذا كان غير صالح، يظهر الخطأ مع رقم السطر والعمود، فانتقل إليه مباشرة.
4. جرّب زر الإصلاح الذي يصلح تلقائيًا الفواصل الزائدة وعلامات الاقتباس المفردة والمفاتيح بلا علامات اقتباس والتعليقات.
5. نسّق النتيجة بمسافتين أو 4 مسافات أو علامات جدولة، واستكشفها في العرض الشجري.

1. الفواصل الزائدة في النهاية

// ❌ غير صالح
{ "name": "Ana", "age": 31, }

// ✅ صالح
{ "name": "Ana", "age": 31 }

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

2. علامات الاقتباس المفردة

// ❌ غير صالح
{ 'name': 'Ana' }

// ✅ صالح
{ "name": "Ana" }

3. المفاتيح بلا علامات اقتباس

// ❌ غير صالح
{ name: "Ana" }

// ✅ صالح
{ "name": "Ana" }

4. التعليقات

// ❌ غير صالح
{
  // إعدادات المستخدم
  "theme": "dark"
}

لا يدعم JSON القياسي التعليقات. تقبل بعض الأدوات صيغة "JSONC" ‏(JSON مع تعليقات)، مثل ملفات إعدادات VS Code، لكن معظم المحللات لا تقبلها. احذف التعليقات أو ضع ملاحظاتك في حقل مثل "_comment".

5. فواصل ناقصة بين العناصر

// ❌ غير صالح
{ "a": 1 "b": 2 }

// ✅ صالح
{ "a": 1, "b": 2 }

يحدث ذلك عادةً عند إضافة سطر جديد ونسيان الفاصلة في السطر السابق. ويُبلَّغ عن الخطأ عند بداية العنصر التالي.

6. أقواس ناقصة أو غير متطابقة

// ❌ غير صالح: المصفوفة لم تُغلق
{ "tags": ["a", "b" }

كثيرًا ما تعني أخطاء مثل "Unexpected end of JSON input" أن قوس إغلاق } أو ] مفقود، أو أن النص قُطع. وتنسيق JSON بمسافات بادئة يجعل فحص البنية سهلًا.

7. قيم غير صالحة

// ❌ غير صالح
{ "price": NaN, "date": undefined, "big": 1e999, "hex": 0xFF, "zip": 01234 }

// ✅ صالح
{ "price": null, "date": null, "hex": 255, "zip": "01234" }

لا يمكن أن تبدأ أرقام JSON بأصفار، ولا أن تُكتب بالنظام السداسي عشري، ولا أن تكون NaN أو Infinity. احفظ القيم مثل الرموز البريدية وأرقام الهواتف كنصوص للحفاظ على الأصفار في بدايتها.

8. حروف غير مُهرَّبة داخل النصوص

// ❌ غير صالح
{ "path": "C:\Users\ana", "quote": "She said "hi"" }

// ✅ صالح
{ "path": "C:\\Users\\ana", "quote": "She said \"hi\"" }

يجب تهريب الشرطات المائلة العكسية وعلامات الاقتباس المزدوجة داخل النصوص بشرطة مائلة عكسية. ويجب كتابة فواصل الأسطر الحقيقية داخل النص بالصيغة \n.

أخطاء ليست مشكلات JSON في الحقيقة

• "Unexpected token < in JSON at position 0": استلمت HTML بدلًا من JSON. ربما أعادت الواجهة البرمجية صفحة خطأ أو إعادة توجيه إلى صفحة تسجيل الدخول. تحقق من رمز الحالة والرابط.
• "Unexpected end of JSON input" مع استجابة فارغة: لم يرسل الخادم شيئًا. افحص الطلب لا المحلل.
• حروف غير مرئية: علامة ترتيب البايتات (BOM) أو علامات اقتباس منحنية ملصوقة من معالج نصوص. أعد كتابة علامات الاقتباس، أو احفظ الملف بترميز UTF-8 دون BOM.

امنع أخطاء JSON من البداية

• لا تبنِ JSON يدويًا في الكود أبدًا. استخدم JSON.stringify() في JavaScript أو json.dumps() في Python.
• استخدم محررًا يتحقق من JSON مثل VS Code، الذي يضع خطًا تحت الأخطاء أثناء الكتابة.
• تحقق من بيانات الواجهات البرمجية مقابل JSON Schema في اختباراتك.
• رتّب المفاتيح قبل مقارنة ملفي JSON، حتى لا تُظهر الفروقات إلا التغييرات الحقيقية.

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

لماذا يعمل JSON في JavaScript لكن لا يعمل مع JSON.parse؟

تسمح الكائنات الحرفية في JavaScript بعلامات الاقتباس المفردة والمفاتيح بلا علامات اقتباس والفواصل الزائدة والتعليقات، أما JSON فلا. لذا يفشل كود يبدو سليمًا في ملف ‎.js عند تحليله كـ JSON.

هل يمكن أن يحتوي JSON على تعليقات؟

ليس وفق المعيار. تسمح بها صيغ مثل JSONC وJSON5، لكن فقط مع المحللات التي تدعم هذه الصيغ.

هل من الآمن لصق استجابات الواجهات البرمجية في منسّق أونلاين؟

فقط إذا كان لا يرفع بياناتك. منسّقنا يحلل كل شيء في متصفحك، فتبقى الرموز المميزة والبيانات الشخصية على جهازك.

الخلاصة

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