كيف تستخدم منسّق JSON
- الصق JSON في مربع الإدخال، أو اكتبه مباشرة.
- اختر نمط المسافة البادئة: مسافتان أو 4 مسافات أو علامات الجدولة.
- انقر تنسيق لعرض JSON بشكل منسّق وسهل القراءة، أو تصغير لإزالة كل المسافات البيضاء الاختيارية.
- إذا كان الإدخال غير صالح، تعرض أداة التحقق رسالة الخطأ مع السطر والعمود اللذين فشل عندهما التحليل.
- وإن أردت، فعّل ترتيب المفاتيح لترتيب مفاتيح الكائنات أبجديًا، أو حوّل النتيجة إلى YAML أو CSV.
- انسخ الناتج والصقه حيث تحتاج إليه.
يعمل كل شيء داخل متصفحك: لا يُرفع JSON الخاص بك إلى أي خادم ولا يُخزَّن، لذا يمكنك تنسيق استجابات API وملفات الإعدادات والسجلات التي تحتوي على بيانات خاصة بأمان.
ما هو JSON ولماذا تنسّقه؟
JSON (JavaScript Object Notation) صيغة بيانات نصية خفيفة، موحّدة في RFC 8259 وECMA-404. وتتكوّن من ستة أنواع فقط من القيم: الكائنات ({})، والمصفوفات ([])، والسلاسل النصية، والأرقام، والقيمتان المنطقيتان true وfalse، وnull. وبفضل بساطتها تستخدمها تقريبًا كل واجهات REST API، والكثير من ملفات الإعدادات، وعدد لا يُحصى من مسارات معالجة السجلات.
لا تهتم الآلات بالمسافات البيضاء، لذا كثيرًا ما يُصغَّر JSON المُرسل عبر الشبكة في سطر واحد. وهذا فعّال، لكنه يكاد يستحيل على الإنسان قراءته. ويضيف التنسيق فواصل أسطر ومسافة بادئة متّسقة، فترى التداخل بنظرة واحدة، وتلاحظ الحقل الناقص، وتقارن بين مستندين في عرض الفروقات (diff). أما التصغير فيفعل العكس، ويفيد حين تريد تضمين JSON في طلب ما أو تقليل حجم البيانات المرسلة.
أخطاء JSON الشائعة وكيف تصلحها
JSON أكثر صرامة من القيم الحرفية للكائنات في JavaScript. وهذه هي الأخطاء التي تلتقطها أداة التحقق أكثر من غيرها:
| المشكلة | غير صالح | صالح |
|---|---|---|
| فاصلة زائدة في النهاية | [1, 2, 3,] | [1, 2, 3] |
| علامات اقتباس مفردة | {'name': 'Ada'} | {"name": "Ada"} |
| مفتاح بدون علامات اقتباس | {name: "Ada"} | {"name": "Ada"} |
| التعليقات | // note أو /* note */ | احذفها، أو استخدم حقلًا باسم "_comment" |
| قيم ليست من JSON | undefined، NaN، Infinity | null أو سلسلة نصية |
| أصفار بادئة | {"id": 007} | {"id": 7} أو "007" |
يبدو المقطع المعطوب النموذجي المنسوخ من شيفرة JavaScript هكذا:
{
name: 'Ada Lovelace',
born: 1815, // year
languages: ['English', 'French',],
}أما JSON المصحَّح فيضع كل مفتاح وكل سلسلة نصية بين علامتي اقتباس مزدوجتين، ويحذف التعليق، ويزيل الفاصلتين الزائدتين:
{
"name": "Ada Lovelace",
"born": 1815,
"languages": ["English", "French"]
}ومن الأسباب الشائعة الأخرى علامات الاقتباس المزدوجة غير المهرَّبة أو فواصل الأسطر الخام داخل السلاسل النصية (استخدم \" و\n)، وحرف شارد بعد القوس الختامي. وعندما يبدو الموضع المُبلَّغ عنه خاطئًا، فافحص السطر الذي يسبقه مباشرة: فالفاصلة الناقصة لا تُكتشف عادةً إلا عندما يصل المحلّل إلى القيمة التالية.
نصائح وأفضل الممارسات
- اختر مسافة بادئة واحدة والتزم بها. المسافتان هما العُرف الأكثر شيوعًا في مشاريع JavaScript، والمسافات الأربع شائعة في أدوات Python. والاتّساق أهم من الاختيار نفسه.
- رتّب المفاتيح قبل المقارنة. كائنات JSON غير مرتّبة، لذا قد يبدو مستندان متكافئان مختلفين. وترتيب المفاتيح يجعل الفروقات في أنظمة التحكم في الإصدارات والمقارنات أنظف بكثير.
- انتبه إلى الأرقام الكبيرة جدًا. يخزّن JavaScript الأرقام بصيغة الفاصلة العائمة 64-bit، لذا قد تفقد الأعداد الصحيحة الأكبر من 9,007,199,254,740,991 (253 − 1) دقتها عند تحليلها في المتصفح. أرسل المعرّفات الكبيرة كسلاسل نصية.
- استخدم UTF-8. يشترط RFC 8259 ترميز UTF-8 في JSON المتبادل بين الأنظمة.
- حوّل الصيغة حين يفيد ذلك. يناسب CSV مصفوفة مسطّحة من الكائنات تريد فتحها في جدول بيانات؛ أما YAML فأسهل في التحرير اليدوي. وللتحويل في الاتجاهين، جرّب محوّل JSON ↔ YAML أو محوّل CSV ↔ JSON.
الأسئلة الشائعة
هل يسمح JSON بالتعليقات؟
لا. لا يسمح RFC 8259 ولا ECMA-404 بالتعليقات. وتقبل بعض الأدوات صيغًا موسّعة مثل JSONC أو JSON5، لكن المحلّل القياسي سيرفضها. احذف التعليقات قبل التحقق، أو انقل الملاحظات إلى حقل عادي.
لماذا يكون JSON الخاص بي غير صالح مع أنه يعمل في JavaScript؟
تسمح القيم الحرفية للكائنات في JavaScript بعلامات الاقتباس المفردة، والمفاتيح بدون علامات اقتباس، والفواصل الزائدة في النهاية، والتعليقات، وقيم مثل undefined. ولا يسمح JSON بأي منها. استخدم JSON.stringify() في الشيفرة لإنتاج JSON صالح بدلًا من كتابته يدويًا.
هل يغيّر التنسيق بياناتي؟
لا يغيّر التنسيق والتصغير إلا المسافات البيضاء بين الرموز؛ فتبقى المفاتيح والقيم وترتيب المصفوفات كما هي. أما ترتيب المفاتيح فيعيد ترتيب أعضاء الكائنات، وهذا لا يغيّر المعنى لأن كائنات JSON غير مرتّبة.
ما الفرق بين التنسيق والتحقق؟
يتأكد التحقق من أن النص مكتوب بصياغة JSON صحيحة. أما التنسيق فيعيد طباعة JSON الصالح بمسافة بادئة سهلة القراءة. ويتحقق المنسّق أولًا، لذا لا يمكنك تنسيق مستند يتعذّر تحليله.
هل يمكنني تحويل JSON متداخل إلى CSV؟
CSV جدول مسطّح، لذا يعمل على أفضل وجه مع مصفوفة من الكائنات تتشارك المفاتيح نفسها. ولا يوجد مقابل مباشر في CSV للكائنات والمصفوفات المتداخلة، وعادةً ما تُسطَّح أو تُحوَّل إلى نص متسلسل في خلية واحدة.
آخر تحديث