منسّق ومدقّق JSON
نسّق JSON وتحقّق منه وافحصه — مع رسالة خطأ تشير إلى الحرف نفسه.
{
"name": "jaguar",
"speed_kph": 80,
"habitats": [
"rainforest",
"wetland"
],
"conservation": {
"status": "Near Threatened",
"assessed": 2016
},
"nocturnal": null
}JSON صالح
- الحجم
- 145 B
- مضغوط
- 145 B
- المُوفَّر
- 0%
- المفاتيح
- 7
- الكائنات
- 2
- أقصى عمق
- 3
الأخطاء الأربعة
يفشل كل مستند مرفوض تقريباً لسبب من الأسباب القليلة نفسها، والأربعة جميعاً أشياء كانت جافاسكربت ستقبلها. وهنا الفخّ: فـ JSON يبدو كأنه صيغة كائن في جافاسكربت، وهو في الحقيقة مجموعة جزئية منها أشد صرامةً بكثير.
| المكتوب | المشكلة | الصواب |
|---|---|---|
{"a": 1,} | فاصلة زائدة في النهاية | {"a": 1} |
{'a': 1} | علامات اقتباس مفردة | {"a": 1} |
{a: 1} | مفتاح بلا اقتباس | {"a": 1} |
{"a": 1} // note | تعليق | احذفه |
واثنتان أخريان توقعان الناس أقل لكن اكتشافهما أصعب. فـ NaN وInfinity وundefined قيم صالحة في جافاسكربت، وليست أيٌّ منها قيمةً في JSON — والبديل هو null أو نص. كذلك فإن سطراً جديداً حرفياً داخل نص غير صالح؛ إذ يجب أن يكون المحرفين \n.
كيف يبلّغ هذا المدقّق عن الأخطاء
يستحق الشرح لأنه سبب تفضيل منسّق على آخر. فدالة JSON.parse الخاصة بالمتصفح تُستعمل في مسار النجاح، لا في وصف الإخفاق: إذ إن صيغة رسائلها تفصيل تنفيذي تغيّر مرتين في إصدارات V8 الأخيرة. فالمستند المعطوب نفسه يعطي «Unexpected end of JSON input» على نسخة من Node و«Expected ‘,’ or ‘}’ after property value at position 6» على أخرى، وأحياناً لا يعطي موضعاً البتة.
لذا حين يفشل التحليل، تمشي هذه الصفحة على القواعد بنفسها فتبلّغ عن السطر والعمود والمحرف الذي توقفت عنده، مع سهم تحته. والرسالة التي تصلك لا تعتمد على المتصفح الذي تصادف أنك تستعمله.
مشكلة الدقة التي لا يحذّرك منها أحد
هذه تسبب أخطاءً حقيقية ولا تكاد تُذكر. فأعداد JSON تصير أعداد جافاسكربت، وأعداد جافاسكربت أعداد مضاعفة الدقة وفق IEEE 754. والأعداد الصحيحة فوق 2⁵³ — نحو 9.007 كوادريليون — لا يمكن تمثيلها تمثيلاً دقيقاً.
فمعرّف من تسعة عشر رقماً من النوع الذي تنتجه تويتر وديسكورد ومعظم مخططات المعرّفات على طريقة Snowflake سيعود مغيَّراً، في صمت، وبلا خطأ في أي موضع. الصق {"id": 9007199254740993} في المنسّق أعلاه وراقب كيف يتزحزح الرقم الأخير.
والإصلاح يكون في جهة الإنتاج: أرسِل المعرّفات ذات 64 بتاً نصوصاً. وكل واجهة برمجية عضّها هذا الأمر تفعل ذلك الآن.
متى تلجأ إلى شيء آخر
هذه الصفحة لقراءة مستند بين يديك وإصلاحه. وثمة مهمتان مجاورتان هي الأداة الخطأ لهما:
- الاستعلام والتحويل. ذاك
jqفي سطر الأوامر، وهو أيضاً يقرأ تدفقاً بدل تحميل كل شيء في الذاكرة — وهو الجواب الصحيح لأي شيء يتجاوز بضعة ميغابايتات. - فرض شكل معيّن. ذاك JSON Schema، والتحقق من البنية سؤال مختلف عن التحقق من الصياغة. فقد يكون المستند سليم التكوين تماماً وينقصه كل حقل تطلبه واجهتك البرمجية.
ذات صلة
إن وصل ملف JSON مرمّزاً بـ Base64، فكّ ترميزه أولاً. وإن خرج من رمز مميز، فإن فاكّ ترميز JWT يقسم المقطعين ويحلّلهما عنك. وإن كان في طريقه إلى رابط، فإن مرمّز الروابط يبيّن لك أي قواعد التهريب الثلاث تريد.
أسئلة حول JSON
لماذا يفشل ملف JSON عندي وهو يبدو سليماً؟
أربعة أسباب تفسّر ذلك كله تقريباً. فاصلة زائدة قبل قوس الإغلاق، تقبلها جافاسكربت ولا يقبلها JSON. وعلامات اقتباس مفردة بدل المزدوجة. وتعليقات، وليس في JSON صياغة لها أصلاً. ومفاتيح بلا اقتباس — فـ {name: "x"} جافاسكربت صالحة وJSON غير صالح. والمدقّق أعلاه يسمّي لك أياً من هذه وجد، بدل أن يعيد عليك رسالة خطأ المحلّل.
هل من الآمن لصق بيانات إنتاجية هنا؟
في هذه الصفحة نعم — فالتحليل يجري في متصفحك ولا يوجد طلب يمكن أن يحملها. ويمكنك التأكد بمراقبة تبويب الشبكة وأنت تكتب. لكن العادة تستحق الحفاظ عليها عموماً: فـ JSON الذي يصحّحه الناس غالباً استجابة واجهة برمجية حقيقية تحوي سجلات عملاء حقيقيين، وكثير من المنسّقات على الإنترنت ترسله إلى خادم لينجز العمل. تحقّق قبل اللصق، في أي أداة كانت.
هل يمكن أن يحتوي JSON على تعليقات؟
لا. أزالها دوغلاس كروكفورد عمداً، لأن الناس بدأوا يضعون فيها توجيهات للمحلّلات. فإن احتجت تعليقات في ملف إعدادات فالحلول المعتادة هي JSON5 أو JSONC (وهو ما يستعمله VS Code)، أو الاصطلاح — أي مفتاح "_comment" يتجاهله المستهلكون. ولا شيء من ذلك JSON، فالمحلّل الصارم سيرفضها على أي حال.
ماذا يفعل «ترتيب المفاتيح» ولمَ قد أريده؟
يعيد ترتيب مفاتيح كل كائن أبجدياً وبشكل متكرّر داخل التداخلات. وكائنات JSON غير مرتبة بحسب المواصفة، فوثيقتان لا تختلفان إلا في ترتيب المفاتيح متكافئتان — لكن مقارنة النصوص تُظهر كل سطر وكأنه تغيّر. وترتيب الاثنتين قبل المقارنة يختصر ذلك إلى الفروق التي تهمّ فعلاً.
هل هناك حدّ للحجم؟
حدّ متصفحك فقط. فالتحليل يجري داخل الصفحة، لذا فبضعة ميغابايتات لا بأس بها على حاسوب مكتبي وستُتعب هاتفاً قديماً. أما الوثائق الضخمة جداً فالأفضل معالجتها بـ jq في سطر الأوامر، فهو يقرأ تدفقاً بدل أن يحتفظ بالشجرة كلها في الذاكرة.
لماذا يعود عددي الصحيح الكبير خطأً؟
لأن أعداد JSON تصير أعداد جافاسكربت، وهي أعداد مضاعفة الدقة وفق IEEE 754، وهذه تفقد الدقة فوق 2⁵³ — أي نحو 9.007 كوادريليون. فمعرّف من تسعة عشر رقماً على طريقة تويتر أو حقل bigint من قاعدة بيانات سيعود مغيَّراً على نحو خفيّ. وليس هذا خللاً في المنسّق؛ بل هو السبب الذي يجعل الواجهات البرمجية التي تستخدم معرّفات بطول 64 بتاً ترسلها نصوصاً.
آخر مراجعة . وجدت شيئاً لم يعد محدَّثاً؟ أخبِرنا.