أخطاء JSON الشائعة · 7 دقائق
أخطاء JSON الشائعة وكيف تصلحها باستخدام منسق JSON
دليل عملي للمبتدئين لفهم ملفات JSON وقراءتها خطوة بخطوة، واستخدام منسق JSON لاكتشاف أخطاء الأقواس والفواصل والاقتباسات وبنية البيانات.
مقدمة
قد تتلقى استجابة من واجهة برمجة تطبيقات، أو تفتح ملف إعدادات، أو تنسخ بيانات من خدمة ويب فتجد نصًا طويلًا مكتظًا بالأقواس وعلامات الاقتباس. غالبًا يكون هذا النص بصيغة JSON، وقد يبدو معقدًا لأنه مكتوب في سطر واحد أو يتضمن خطأ صغيرًا يمنع قراءته.
هنا تظهر فائدة منسق JSON. فهو يعيد ترتيب النص بمسافات وأسطر متدرجة، ويجعل العلاقة بين الحقول والقيم واضحة، ويساعد على التحقق من سلامة الصياغة. لكن التنسيق لا يضمن وحده أن البيانات مناسبة لما يحتاجه تطبيقك؛ إذ ينبغي بعده قراءة البنية والقيم بعين ناقدة. يشرح هذا الدليل كيف تفعل ذلك من الصفر، وكيف تميّز بين الخطأ النحوي والخطأ في المحتوى.
ما JSON، وما الذي يمثله؟
JSON اختصار لـ JavaScript Object Notation، وهو تنسيق نصي لتمثيل البيانات المنظمة وتبادلها. يستطيع تمثيل قيم بسيطة مثل النص والرقم والقيمة المنطقية، وكذلك بنيتين أساسيتين: الكائن والمصفوفة 1. لا يلزم أن تكون مبرمجًا لقراءته؛ يكفي أن تفهم العلامات التي تنظّم البيانات.
الكائن: حقول مرتبطة بقيم
يوضع الكائن بين قوسين معقوفين {}. داخله يكون كل اسم حقل بين علامتي اقتباس مزدوجتين، ثم نقطتان رأسيتان، ثم قيمة. مثلًا:
{
"name": "ليان",
"active": true,
"points": 18
}في المثال، name هو اسم الحقل وقيمته نص، وactive قيمة منطقية، وpoints رقم. الفاصلة تفصل بين الحقول، لكنها لا تأتي بعد الحقل الأخير.
المصفوفة: قائمة من القيم
توضع المصفوفة بين قوسين مربعين []. قد تضم نصوصًا أو أرقامًا أو كائنات أو حتى مصفوفات أخرى. المثال الآتي يبيّن قائمة طلبات، وكل عنصر فيها كائن:
{
"orders": [
{"id": 101, "status": "new"},
{"id": 102, "status": "sent"}
]
}ابدأ عند قراءة هذا المثال من orders: قيمته ليست طلبًا واحدًا بل مصفوفة. ثم انتقل إلى كل عنصر بين {} واقرأ حقوله. هذه الطريقة، من الخارج إلى الداخل، تقلل الارتباك مع البيانات المتداخلة.
قواعد سريعة قبل أن تحاول إصلاح أي خطأ
JSON يشبه كائنات JavaScript في مظهره، لكنه أكثر تقييدًا. توضع المفاتيح والنصوص داخل علامات اقتباس مزدوجة، ولا يسمح بالتعليقات أو بالفاصلة الختامية 2. والقيم المنطقية هي true وfalse بأحرف صغيرة، والقيمة الفارغة هي null.
| العنصر | صيغة صحيحة | مثال يحتاج تصحيحًا |
|---|---|---|
| مفتاح أو نص | "city": "الرياض" |
'city': 'الرياض' |
| فصل العناصر | "a": 1, "b": 2 |
"a": 1 "b": 2 |
| آخر عنصر | "a": 1 |
"a": 1, |
| قيمة منطقية | true أو false |
True أو FALSE |
| رقم | 12.5 |
012 أو NaN |
مهم: صحة JSON تعني أن القارئ البرمجي يستطيع تحليل النص. أما صحة المعنى فتعني أن الحقول والقيم تلبي متطلبات النظام الذي سيستخدمها. قد يكون الملف صحيح الصياغة لكنه يحتوي بريدًا إلكترونيًا في حقل رقم الهاتف، أو حالة طلب غير معتمدة.
طريقة عملية لقراءة JSON واكتشاف الأخطاء
الخطوة 1: انسخ البيانات كاملة كما وصلتك
انسخ النص من مصدره دون حذف أقواس أو فواصل أو علامات اقتباس. إن كان جزءًا من رسالة خطأ أو سجل تقني، حدّد بداية JSON ونهايته فقط. يبدأ الكائن عادةً بـ{ وينتهي بـ}، وتبدأ المصفوفة بـ[ وتنتهي بـ]. لا تعدّل النص عشوائيًا قبل معرفة موضع المشكلة.
الخطوة 2: استخدم منسقًا لعرض البنية والتحقق منها
الصق النص في أداة منسق JSON في أدواتي بلس. توضح صفحة الأداة أنها مخصصة لتنسيق JSON والتحقق منه ومراجعته، مما يحوّل البيانات المتراصة إلى عرض أسهل للقراءة. شغّل التنسيق أو التحقق، ثم اقرأ النتيجة أو رسالة الخطأ بدل التخمين.
إذا نجحت العملية، انتقل إلى الخطوة التالية. وإذا ظهرت رسالة تفيد بأن الصياغة غير صالحة، راجع الموضع الذي تشير إليه الرسالة، مع الانتباه إلى أن موضع الاكتشاف قد يكون بعد الخطأ الفعلي مباشرة؛ فالقارئ لا يلاحظ أحيانًا الفاصلة المفقودة إلا حين يصل إلى الحقل التالي.
الخطوة 3: طابق الأقواس من الخارج إلى الداخل
بعد التنسيق، افحص القوس الافتتاحي وما يقابله. كل { يحتاج إلى }، وكل [ يحتاج إلى ]. اتبع المسافة البادئة: عندما تتقدم الأسطر إلى الداخل يبدأ مستوى جديد، وعندما تعود إلى الخارج ينتهي ذلك المستوى.
انظر إلى هذا الخطأ:
{
"user": {
"name": "سارة",
"roles": ["editor", "reviewer"]
}هنا لم يُغلق كائن user قبل إغلاق الكائن الخارجي. أضف } في الموضع المناسب، وراقب نوع القوس؛ إذ إن } لا يغلق [.
الخطوة 4: افحص الفواصل والنقطتين والاقتباسات
لكل زوج "مفتاح": قيمة تحتاج إلى نقطتين بعد المفتاح. وبين الحقول أو عناصر القائمة تحتاج فاصلة. أما النصوص، بما فيها المفاتيح، فتحتاج اقتباسات مزدوجة. مثال غير صالح:
{
"product": "دفتر"
"price": 25,
"available": "true"
}ينقص المثال فاصلة بعد قيمة product. وبعد إضافتها يصبح صحيحًا نحويًا، لكن "true" نص وليست قيمة منطقية. إن كان available حالة نعم/لا، فاكتب true بلا اقتباس. هكذا تميّز بين نوع البيانات وشكلها.
الخطوة 5: اقرأ المسار لا السطر وحده
في البيانات المتداخلة، لا يكفي أن تقول: «قيمة الحالة هي sent». اسأل: لأي طلب؟ اتبع المسار، مثل orders ثم العنصر الثاني ثم status. تشير البرمجة عادةً إلى أول عنصر في المصفوفة بالرقم 0 ثم 1 للثاني. أما حقول الكائن، فالمهم اسمها وعلاقتها بقيمتها لا ترتيبها 1.
الخطوة 6: تحقق من المعنى وفق مصدر البيانات
بعد أن يصبح JSON منسقًا وصالحًا، قارن الحقول بما يتوقعه النظام: هل الرقم معرف أم سعر؟ هل التاريخ مكتوب بالصيغة التي يطلبها التطبيق؟ هل المصفوفة فارغة عمدًا؟ وهل تكررت مفاتيح مثل id داخل الكائن نفسه؟ تنصح مواصفة JSON بأن تكون الأسماء داخل الكائن فريدة، لأن تكرارها قد يؤدي إلى تعامل مختلف بين البرامج 1.
أخطاء شائعة ونصائح تمنع تكرارها
من الأخطاء الشائعة لصق كائن JavaScript بدل JSON: اقتباس مفرد، أو مفتاح بلا اقتباس، أو تعليق مثل // ملاحظة. احذفها عند الحاجة إلى JSON خالص. وتجنب الفاصلة الأخيرة قبل } أو ]، وكذلك undefined وInfinity وNaN، فهي ليست قيم JSON صالحة 2.
احذر كذلك من الأقواس الذكية التي قد يبدلها محرر النصوص، ومن نسخ محرف خفي أو سطر ناقص من رسالة طويلة. احتفظ بنسخة أصلية قبل التعديل، وعدّل خطأ واحدًا في كل مرة ثم أعد التحقق. وإذا بدا الملف سليمًا لكنه يرفض في النظام المقصود، فاطلب أو راجع مواصفة الحقول المتوقعة؛ فالمشكلة قد تكون في نوع القيمة أو اسمها لا في JSON نفسه.
لا تضع كلمات مرور أو رموز وصول حقيقية في أداة عامة أو في لقطة شاشة عند طلب المساعدة. استبدل القيم الحساسة بقيم تجريبية تحافظ على البنية، مثل "token": "REDACTED"، ثم اختبر النسخة المنقحة.
خاتمة
منسق JSON ليس مجرد وسيلة تجميل للنص؛ إنه أداة قراءة وتدقيق أولية. ابدأ بالتحقق من الصياغة، ثم اتبع البنية من الكائن الخارجي إلى القوائم والعناصر الداخلية، وبعدها راجع أنواع القيم ومعناها. بهذه الخطوات ستعرف هل لديك فاصلة مفقودة أو قوس غير مغلق أو بيانات صحيحة شكليًا لكنها لا تطابق المطلوب. ومع التمرين، ستتحول كتلة JSON الطويلة إلى خريطة واضحة يمكن فحصها بثقة.
أسئلة شائعة
هل يجعل تنسيق JSON بياناتي صحيحة تلقائيًا؟
لا. التنسيق يسهّل القراءة، والتحقق يحدد ما إذا كانت الصياغة توافق قواعد JSON. لكن الأداة لا تعرف بالضرورة أن حقلًا باسم email يجب أن يحمل بريدًا صالحًا أو أن حالة الطلب يجب أن تكون ضمن قائمة محددة. لذلك راجع قواعد النظام أو توثيق الواجهة بعد اجتياز التحقق النحوي.
لماذا يظهر الخطأ في سطر مختلف عن السطر الذي عدّلته؟
لأن محلل JSON يقرأ النص بالتتابع. إذا حذفت فاصلة بين حقلين، فقد لا يتأكد من وجود المشكلة إلا عند وصوله إلى بداية الحقل الثاني. ابدأ بالسطر المشار إليه، ثم راجع ما قبله مباشرة: الفاصلة، الاقتباس، النقطتان، والقوس المفتوح أو المغلق.
هل يمكن أن يبدأ ملف JSON بمصفوفة بدل كائن؟
نعم. قد يكون النص كله مصفوفة مثل ["red", "blue"] أو قائمة من كائنات. المصفوفة الصالحة تبدأ بـ[ وتنتهي بـ]، وتفصل عناصرها فواصل. اختر طريقة القراءة المناسبة: في الكائن ابحث عن اسم الحقل، وفي المصفوفة افحص العناصر بالتسلسل.
