JSON: التنسيق والتحقق وإصلاح الأخطاء الأكثر شيوعًا

رسالة «JSON غير صالح» (Unexpected token أو SyntaxError: JSON.parse) هي أكثر رسائل الخطأ تكرارًا في حياة أي مطور أو محلل بيانات أو مسؤول تكامل أنظمة. يعود هذا الإحباط المتكرر إلى أن صيغة JSON — رغم مظهرها البسيط المشابه لكائنات JavaScript — تفرض قواعد قياسية صارمة لا تتسامح مع أي خطأ، حتى لو كان مجرد فاصلة زائدة غير مقصودة قبل قوس إغلاق، أو علامة اقتباس مفردة بدل المزدوجة.

لماذا تختلف قواعد JSON عن كائنات JavaScript العادية؟

نشأت صيغة JSON (JavaScript Object Notation) في الأصل كصيغة مشتقة من JavaScript لتبادل البيانات النصية، لكنها اليوم مستقلة تمامًا وتعتمدها كافة لغات البرمجة (Python، Go، PHP، C#، Java). ولكي تستطيع لغة مثل Go أو Rust تفكيك النص بدقة وكفاءة دون الحاجة إلى محرك جافاسكربت كامل، تم تقييد بنية JSON بقواعد نحوية حدية صارمة بموجب المعيار RFC 8259، مما يجعل أي تساهل نصي في الكود البرمجي العادي خطأً جسيمًا يؤدي إلى رفض الملف بالكامل.

القواعد الست التي تكسر معظم ملفات JSON

1. علامات الاقتباس المزدوجة حصراً: يجب إحاطة المفاتيح والنصوص بعلامتي اقتباس مزدوجتين فقط ("). استخدام علامات الاقتباس المفردة ('key': 'value') أو الشرطة المائلة المائلة للخلف (Backticks) يكسر الملف فوراً.
2. منع الفاصلة الأخيرة الزائدة (Trailing Commas): في كثير من لغات البرمجة الحديثة يُسمح بترك فاصلة بعد العنصر الأخير لتسهيل مراجعة الفروقات في Git، لكن في معيار JSON، وضع فاصلة قبل قوس الإغلاق `}` أو `]` يُعد خطأً نحويًا قطعيًا لأن المحلل يتوقع عنصرًا تاليًا.
3. الحظر التام للتعليقات: لا تسمح مواصفة JSON بالتعليقات من أي نوع سواء كانت تعليقات سطرية `//` أو تعليقات كتلية `/* */`. إذا كنت بحاجة لتعليقات في ملفات إعدادات، فإن بدائل مثل JSONC أو YAML أو TOML هي الأنسب.
4. القيم المدعومة محددة بدقة: القيم المسموح بها هي فقط: السلاسل النصية (Strings)، الأرقام (Numbers)، الكائنات (Objects)، المصفوفات (Arrays)، القيم المنطقية (true / false)، والقيمة الفارغة (null). لا وجود للقيم `undefined` أو الدوال (Functions) أو التواريخ الخام بدون تنصيص.
5. المفاتيح يجب أن تكون نصوصًا: على خلاف كائنات JS حيث يمكن كتابة `{age: 30}`، يجب أن يكون المفتاح دائمًا محاطًا باقتباس مزدوج: `{"age": 30}`.
6. التعامل مع المحارف الخاصة والأرقام الكبيرة: النصوص التي تحتوي على أسطر جديدة أو علامات اقتباس داخلية يجب تهريبها بشرطة مائلة عكسية (مثل `\"` و `\n`). كما أن الأرقام العشرية التي تبدأ بنقطة مثل `.5` أو تنتهي بنقطة `5.` غير صالحة ويجب كتابتها `0.5` أو `5.0`.

كيف تقرأ رسائل الخطأ وتصلحها في ثوانٍ؟

عندما يفشل تحليل ملف يحتوي على آلاف الأسطر، لا تراجع الكود يدويًا سطرًا بسطر. رسالة الخطأ الصادرة من محرك التحليل تُحدد بدقة أو تقريبًا «الموقع بالأحرف» (Character Position). تقوم أداتنا بحساب رقم السطر ورقم العمود تلقائيًا من موقع الحرف وتوضيح السياق المحيط به:

• إذا أشار المحلل إلى الخطأ عند قوس إغلاق `}` أو `]`، فالسبب بنسبة 95% هو فاصلة زائدة في السطر الذي يسبقه مباشرة.
• إذا كانت الرسالة «Unexpected token ' in JSON at position...»، فالسبب هو استخدام اقتباس مفرد بدل المزدوج.
• إذا كانت الرسالة «Unexpected token /»، فهناك تعليق برمجي غير مسموح تم لصقه في البيانات.

التنسيق الجمالي (Pretty Print) مقابل الضغط (Minification)

كلا النمطين يحافظان على المحتوى والبيانات نفسها دون تغيير؛ الفرق هندسي ووظيفي بحت:

• التنسيق المنظم (Beautify / Pretty Print): يضيف مسافات بادئة (Indentation) بمقدار مسافتين وأسطرًا جديدة لكل مستوى تفرع. هذا يجعله مثاليًا للعين البشرية، ولأغراض تصحيح الأخطاء (Debugging)، والتدقيق البرمجي، وكتابة التوثيق التقني.
• الضغط الجذري (Minification): يزيل كافة المسافات البيضاء والأسطر غير المفيدة، مما يقلل حجم نقل الملف عبر الشبكة (Payload Size) بنسبة تتراوح بين 20% إلى 40%، وهو الخيار القياسي عند إرسال واستقبال ردود واجهات البرمجية REST APIs وتخزين الكاش في Redis.

الحفاظ التام على محارف Unicode واللغة العربية

في بعض المنصات القديمة، يؤدي تمرير النصوص العربية إلى تشويهها أو تحويلها إلى رموز سداسية عشرية هرمية مثل `\u0623\u062d\u0645\u062f`. تم تصميم أداتنا لدعم معيار UTF-8 الكامل محليًا؛ فيظل النص العربي صريحًا ومقروءًا وطبيعيًا في كلا وضعي التنسيق والضغط دون أي هروب غير ضروري للمحارف العربية.

أمان البيانات والخصوصية الصارمة

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