تخطي إلى المحتوى
🛠️
Whiz Tools

منسق JSON: تنسيق وتحقق من JSON عبر الإنترنت مجانًا

قم بتنسيق JSON المضغوط فورًا مع المسافات البادئة المناسبة. منسق JSON المجاني عبر الإنترنت يتحقق من بناء الجملة، ويجمّل الكود، ويجعل تصحيح الأخطاء أسرع. يعمل داخل المتصفح مع التنسيق الفوري.

منسق JSON

قم بتنسيق وتجميل JSON الخاص بك باستخدام هذه الأداة البسيطة - يحدث التنسيق تلقائيًا أثناء الكتابة!

ستظهر مخرجات JSON المنسقة هنا تلقائيًا...

حاسبة التحميل...
📚

التوثيق

ما مُنسِّق JSON؟

مُنسِّق JSON هو أداة تأخذ نص JSON ‏(ترميز كائنات JavaScript) وتعيد كتابته باستخدام المسافات البادئة وفواصل الأسطر، من دون تغيير البيانات نفسها. JSON هو تنسيق نصي عادي لتخزين البيانات المهيكلة وإرسالها، ويتكوّن من أزواج من الأسماء والقيم وقوائم. تحفظ البرامج المساحة عادةً بإزالة كل المسافات البيضاء الزائدة، ما ينتج سطرًا واحدًا كثيفًا يصعب على الإنسان قراءته. يضيف المُنسِّق، الذي يُسمّى أيضًا مُجمِّل JSON أو المنسّق الجميل، تلك المسافات البيضاء مجددًا بطريقة متسقة بحيث يصبح الهيكل واضحًا. تنسّق هذه الأداة JSON تلقائيًا أثناء الكتابة أو اللصق. لا يوجد زر للتنسيق؛ إذ يتحدّث الناتج مع كل ضغطة مفتاح. ويمسح زر إعادة الضبط الإدخال، بينما ينسخ زر النسخ النتيجة المنسّقة.

قواعد صياغة JSON

يحدّد JSONَ مواصفةٌ تُسمّى RFC 8259. وله نوعان من الحاويات:

الكائنات تحتوي على أزواج الاسم/القيمة داخل أقواس معقوفة:

1{"name": "John", "age": 30, "city": "New York"}
2

المصفوفات تحتوي على قوائم مرتبة داخل أقواس مربعة:

1["apple", "banana", "cherry"]
2

يجب أن تكون القيمة في JSON واحدةً من ستة أنواع: سلسلة نصية، أو رقم، أو قيمة منطقية (true أو false)، أو null، أو كائن، أو مصفوفة.

تتسبب بعض القواعد في معظم الأخطاء:

  • يجب إحاطة أسماء الخصائص بعلامتي اقتباس مزدوجتين. ‏{name: "John"} غير صالح؛ والصحيح هو {"name": "John"}.
  • يجب أن تستخدم السلاسل النصية علامتي اقتباس مزدوجتين، لا علامتي اقتباس مفردتين.
  • لا يجوز أن تأتي فاصلة بعد العنصر الأخير في كائن أو مصفوفة (لا فواصل زائدة).
  • لا يحتوي JSON على صياغة للتعليقات، رغم أن مظهره ذي الأقواس المعقوفة والمربعة مأخوذ من JavaScript.
  • لا توجد في JSON قيمة undefined. استخدم null للقيمة المفقودة.

من الأخطاء الشائعة لصق حرفية كائن JavaScript بدلًا من JSON. ‏{name: 'John', age: undefined} صالح في JavaScript لكنه غير صالح في JSON. وصيغة JSON هي {"name": "John", "age": null}.

كيف يعمل مُنسِّق JSON هذا؟

تمرّر كثير من مُنسِّقات JSON النص عبر JSON.parse() لبناء كائن JavaScript، ثم تشغّل JSON.stringify() لإعادته إلى نص مع المسافات. ولهذه الرحلة ذهابًا وإيابًا أثر جانبي: أرقام JavaScript هي أعداد فاصلة عائمة مزدوجة الدقة وفق IEEE 754، ولا يمكنها تمثيل كل عدد صحيح بدقة بعد تجاوز 2^53 − 1 (9,007,199,254,740,991). وقد يظهر معرّف مثل 9007199254740993 على شكل 9007199254740992 بعد تلك الرحلة.

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

العملية، خطوةً خطوة:

  1. اقرأ الرمز التالي (كائنًا، أو مصفوفة، أو سلسلة نصية، أو رقمًا، أو true، أو false، أو null).
  2. تحقّق منه مقابل قواعد JSON. ارفضه إذا خالف قاعدة، مثل وجود مفتاح غير موضوع بين علامتي اقتباس أو فاصلة زائدة.
  3. انسخ نص الرمز إلى الناتج من دون تغيير.
  4. أضف فاصل سطر ومسافة بادئة بمقدار 2 مسافتين لكل مستوى من مستويات التداخل داخل كائن أو مصفوفة. ويبقى الكائن أو المصفوفة الفارغ من العناصر في سطر واحد، مثل {} أو [].
  5. كرّر ذلك حتى تتم قراءة الإدخال بالكامل.

تُثبَّت المسافة البادئة عند 2 مسافتين، ولا يوجد إعداد لتغييرها. عندما يكون مربع الإدخال فارغًا، تعرض لوحة الناتج النص البديل "سيظهر JSON المنسّق هنا تلقائيًا...". وإذا خالف الإدخال قاعدة من قواعد JSON، تعرض الأداة الرسالة "JSON غير صالح: يُرجى التحقق من الإدخال" بدلًا من رسالة تقنية من المحلّل تتضمن موضع الحرف بدقة. أما الدالة المضمّنة في المتصفحات JSON.parse() فتُبلغ، على العكس، عن موضع الحرف في نص الخطأ.

مثال محلول

هذا الإدخال المصغّر:

1{"name":"John Doe","age":30,"address":{"street":"123 Main St","city":"Anytown","state":"CA"},"hobbies":["reading","hiking","photography"]}
2

يصبح:

1{
2  "name": "John Doe",
3  "age": 30,
4  "address": {
5    "street": "123 Main St",
6    "city": "Anytown",
7    "state": "CA"
8  },
9  "hobbies": [
10    "reading",
11    "hiking",
12    "photography"
13  ]
14}
15

تكون المسافة البادئة لكل كائن أو مصفوفة متداخلة أكبر بمستوى واحد من المسافة البادئة لأصلها، ولذلك تصبح العلاقة بين address وحقوله الثلاثة واضحةً للوهلة الأولى.

يُبيّن مثال ثانٍ سبب أهمية نسخ القيم الحرفية. هذا الإدخال:

1{"id":9007199254740993}
2

يُنسّق إلى:

1{
2  "id": 9007199254740993
3}
4

تبقى الأرقام تمامًا كما كُتبت. أما المُنسِّق المبني على JSON.parse() متبوعًا بـ JSON.stringify() فسيحوّل ذلك الرقم بصمت إلى 9007199254740992 بدلًا من ذلك.

أخطاء JSON الشائعة

  • اسم خاصية بلا علامات اقتباس: {name: "John"}. الإصلاح: {"name": "John"}.
  • فاصلة زائدة: {"age": 30,}. الإصلاح: أزل الفاصلة قبل القوس المعقوف الختامي.
  • أقواس غير متطابقة: {"data": [1, 2}. الإصلاح: أغلق المصفوفة باستخدام ] قبل إغلاق الكائن.
  • سلسلة نصية غير مغلقة: {"name": "John}. الإصلاح: أضف علامة الاقتباس الختامية المفقودة.
  • علامات اقتباس مفردة: {'name': 'John'}. الإصلاح: استخدم علامات اقتباس مزدوجة.
  • undefined أو NaN أو Infinity: لا واحدة من هذه قيم JSON صالحة. استخدم null أو سلسلة نصية.

من المصادر المتكررة لهذه الأخطاء نسخ كائن مباشرةً من وحدة تحكم المتصفح أو سجل الخادم، إذ يتضمن غالبًا صياغة خاصة بـ JavaScript تحتاج إلى تنظيف قبل أن تصبح JSON صالحًا.

متى يُستخدم مُنسِّق JSON؟

تُستخدم مُنسِّقات JSON غالبًا لفحص استجابات واجهة برمجة التطبيقات، التي تُرسل عادةً بصيغة مصغّرة لتوفير عرض النطاق الترددي. وتُستخدم أيضًا للتحقق يدويًا من ملفات الإعداد مثل package.json أو composer.json، ولقراءة البيانات المنسوخة من وحدة التخزين المحلية للمتصفح أو من وحدة التحكم، وفهم بنية مجموعة بيانات مستلمة من نظام آخر.

طرق أخرى لتنسيق JSON

  • أدوات مطوّري المتصفح: ينسّق Chrome وEdge وFirefox استجابات JSON تلقائيًا في لوحة المعاينة ضمن علامة تبويب الشبكة.
  • محررات الأكواد: ينسّق Visual Studio Code ملف JSON المفتوح باستخدام Alt+Shift+F (أو Shift+Option+F على جهاز Mac). وتوفر معظم المحررات اختصارًا مكافئًا أو إضافة للتنسيق.
  • سطر الأوامر: ينسّق كل من jq (jq . file.json) وأداة Python المضمّنة python -m json.tool file.json JSON من الطرفية.

تضمين تنسيق JSON في الكود

تتضمن معظم لغات البرمجة مكتبة JSON مع خيار للمسافة البادئة. في JavaScript:

1const formatted = JSON.stringify(JSON.parse(rawJson), null, 2);
2

في Python:

1import json
2formatted = json.dumps(json.loads(raw_json), indent=2)
3

يحلّل كلا النهجين النص إلى بنية بيانات أصلية، ثم يعيدان تسلسله مع المسافات. كتابة ذلك بسيطة، لكنه قد يغيّر الأرقام. تخزّن JavaScript كل رقم كعدد مزدوج، ولذلك يعود 9007199254740993 على شكل 9007199254740992. وتحافظ Python على الأعداد الصحيحة بدقة، لأن أعدادها الصحيحة لا حدّ لحجمها، لكنها تعيد كتابة 1.0e2 بصيغة 100.0 وتحول 1e999 إلى Infinity، وهي قيمة غير صالحة في JSON. وغالبًا ما تخزّن التطبيقات التي تحتاج إلى أعداد صحيحة كبيرة بدقة، مثل معرّفات قواعد البيانات، هذه المعرّفات كسلاسل نصية في JSON بدلًا من تخزينها كأرقام.

نبذة قصيرة عن تاريخ JSON

حدّد دوغلاس كروكفورد مواصفة JSON في أوائل عقد 2000، مستمدًا صياغتها من مُنشئات كائنات JavaScript، لكنه جعل استخدامها ممكنًا من أي لغة. وقد أضفى RFC 4627 الطابع الرسمي عليها في 2006. وانتشرت سريعًا لأنها أقصر كتابةً من XML وتطابق مباشرةً كائنات JavaScript، وهو أمر مهم مع بدء تطبيقات الويب في جلب البيانات في الخلفية بدلًا من إعادة تحميل الصفحات كاملةً. وبحلول عقد 2010 أصبح التنسيق الافتراضي لواجهات REST API وقواعد بيانات مثل MongoDB.

الأسئلة الشائعة

ما مُنسِّق JSON؟ أداة تضيف المسافات البادئة وفواصل الأسطر والمسافات إلى نص JSON، بحيث يسهل قراءة بنيته، من دون تغيير البيانات.

هل يغيّر التنسيق البيانات؟ لا. يغيّر التنسيق المسافات البيضاء فقط. تنسخ هذه الأداة كل سلسلة نصية وكل رقم تمامًا كما كُتب، ولذلك تطابق القيم في الناتج المنسّق قيم الإدخال بدقة، بما في ذلك الأرقام الكبيرة جدًا التي لا يمكن تخزينها بدقة كرقم JavaScript.

لماذا يظهر لي خطأ "JSON غير صالح"؟ يخالف الإدخال إحدى قواعد JSON. ومن أسبابه الشائعة أسماء الخصائص غير الموضوعة بين علامتي اقتباس، أو الفاصلة الزائدة، أو علامات الاقتباس المفردة، أو السلسلة النصية غير المغلقة، أو الأقواس غير المتطابقة. لا تعرض هذه الأداة موضع الحرف المحدد للمشكلة؛ وعادةً ما يؤدي التحقق من الإدخال مقابل القواعد المذكورة أعلاه إلى العثور عليها بسرعة.

هل يمكن أن يحتوي JSON على تعليقات؟ لا. فالمواصفة لا تسمح بها. وتضيف تنسيقات مثل JSONC وJSON5 دعم التعليقات إلى صياغة JSON في الحالات التي يكون فيها ذلك مفيدًا، مثل ملفات الإعداد.

ما المسافة البادئة القياسية في JSON؟ المسافتان هما الاصطلاح الأكثر شيوعًا في تطوير الويب، وهما ما تستخدمه هذه الأداة. وتستخدم بعض أدلة الأسلوب أربع مسافات أو علامات جدولة بدلًا من ذلك؛ أما مواصفة JSON نفسها فلا تشترط مسافة بادئة معينة.

ما الفرق بين JSON.parse() وJSON.stringify()؟ تحوّل JSON.parse() سلسلة JSON إلى قيمة JavaScript. أما JSON.stringify() فتفعل العكس، فتحوّل قيمة JavaScript إلى سلسلة JSON، وتقبل وسيطًا للمسافة البادئة من أجل الطباعة المنسّقة. ولا تستخدم هذه الأداة أيًا من الدالتين داخليًا، وهو ما يتيح لها الحفاظ على الأعداد الصحيحة الكبيرة بدقة.

المراجع

  1. RFC 8259 — تنسيق تبادل بيانات ترميز كائنات JavaScript (JSON)
  2. توثيق MDN على الويب: JSON
  3. json.org