باختصار: يملك JSON قواعد صغيرة وصارمة — الأخطاء التي تكسر المحلل (فواصل زائدة، مفاتيح بلا علامات اقتباس، علامات اقتباس مفردة) غير مرئية في البيانات المصغّرة لكنها واضحة بعد التنسيق. معرفة قواعد البنية الحقيقية تحوّل "واجهة برمجة التطبيقات أعادت خطأ" إلى إصلاح من ثانيتين. اقرن هذا الدليل مع Encoding Converter وCharacter Counter وText Difference وAI Hidden Characters.
تنسيق JSON يعني إضافة مسافات بيضاء ومسافات بادئة لجعل بنيته قابلة للقراءة؛ التحقق من صحته يعني فحص أن تلك البنية تتبع فعليًا القواعد المحددة في RFC 8259. JSON المصغّر — الشكل المضغوط بلا مسافات الذي تنقله واجهات البرمجة فعليًا — صحيح لكن غير قابل للقراءة؛ يعكس المنسّق ذلك دون تغيير البيانات.
قواعد البنية التي تهم فعليًا
يجب أن تكون مفاتيح JSON سلاسل بعلامات اقتباس مزدوجة — {name: "قيمة"} غير صالح، فقط {"name": "قيمة"} يُحلَّل بشكل صحيح. علامات الاقتباس المفردة غير صالحة أبدًا للسلاسل أو المفاتيح، على عكس حرفيات كائنات JavaScript، التي تقيّد بنية JSON بها عمدًا. الفاصلة الزائدة بعد العنصر الأخير في مصفوفة أو كائن — ["a", "b",] — تجعل JSON غير صالح، حتى لو كانت غير ضارة (أو حتى مطلوبة كاصطلاح) في لغات أخرى، وهي أحد الأسباب الأكثر شيوعًا لفشل تحليل JSON المُحرَّر يدويًا.
لماذا "يبدو صحيحًا" ليس مثل صالح
يمكن أن يكون مستند JSON غير قابل للتمييز بصريًا عن مستند صالح ومع ذلك يفشل في التحليل — قوس معقوف ختامي مفقود في نهاية بنية متداخلة كبيرة، علامة اقتباس منحنية (“) ملصقة من معالج نصوص بدلًا من علامة اقتباس مستقيمة "، أو تعليق شارد (لا يملك JSON أي بنية تعليقات على الإطلاق، على عكس JSON5 أو JSONC) ستكسر كلها محللًا صارمًا بينما تبدو سليمة للوهلة الأولى. لهذا بالضبط يساعد التنسيق قبل النظر: المسافة البادئة الصحيحة تجعل قوسًا غير مغلق واضحًا بصريًا، بكسر نمط التداخل المتوقع.
التنسيق مقابل التحقق من صحة المخطط
يتحقق المنسّق من أن JSON صحيح نحويًا — أقواس متوازنة، سلاسل بعلامات اقتباس صحيحة، لا فواصل زائدة. لا يتحقق مما إذا كانت البيانات منطقية: هل حقل يُفترض أن يكون رقمًا هو في الواقع سلسلة نصية، أو هل حقل مطلوب مفقود. تلك مسألة منفصلة، ويتعامل معها التحقق باستخدام JSON Schema، الذي يفحص البنية والأنواع مقابل تعريف مخطط بدلًا من مجرد التحقق من أن JSON نفسه مصاغ جيدًا.
سير عمل لJSON فوضوي أو معطوب
- ألصق JSON الخام — مصغّرًا أو معطوبًا أو غير ذلك — في منسّق أولًا.
- إذا تم تحليله، راجع البنية ذات المسافة البادئة بحثًا عن الحقل أو القيمة التي تبحث عنها فعليًا.
- إذا فشل التحليل، تحقق أولًا من موقع الخطأ: تُبلغ معظم المحللات عن سطر/عمود، يشير عادةً مباشرةً إلى فاصلة أو قوس أو علامة اقتباس مفقودة.
- انتبه خصيصًا للفواصل الزائدة وعلامات الاقتباس الذكية عندما يكون المصدر مكتوبًا يدويًا أو ملصقًا من محرر غير برمجي.
أخطاء شائعة يجب تجنبها
- افتراض أن مسافة بادئة تبدو صالحة تعني JSON صالحًا — التنسيق والتحليل خطوتان منفصلتان.
- إضافة فاصلة زائدة بدافع العادة من JavaScript أو Python، حيث غالبًا ما تُتساهل معها.
- لصق JSON من معالج نصوص والحصول على علامات اقتباس ذكية منحنية بدلًا من مستقيمة.
- الخلط بين "يُنسَّق دون خطأ" و"يطابق المخطط الذي تتوقعه واجهة البرمجة" — هذان فحصان مختلفان.
معظم أخطاء JSON هي حرف محدد في مكان محدد — القيمة الحقيقية للمنسّق هي جعل ذلك المكان مرئيًا بدلًا من تركك تفحص سطرًا واحدًا متواصلًا للعثور عليه.