مدقق ومُجمّل JSON

مدقق ومُجمّل JSON أداة مجانية تتحقق من صحة بنية JSON، وتنسّق المحتوى الصحيح لتسهيل قراءة تركيبه.

ما فائدة التحقق من JSON وتجميله؟

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

صياغة JSON أكثر صرامة من صياغة كائنات JavaScript. يجب وضع أسماء الخصائص بين علامتي اقتباس مزدوجتين، ولا يجوز استخدام علامتي اقتباس مفردتين مع السلاسل النصية، كما لا يُسمح بفاصلة زائدة في نهاية الكائنات أو المصفوفات. كذلك لا تشمل مواصفات JSON التعليقات أو undefined أو NaN أو Infinity.

تستخدم هذه الأداة الدالة json_decode في PHP على الخادم. ينتقل إدخالك إلى الخادم عبر HTTPS ولا يُخزّن. وبما أن البيانات تغادر جهازك، فاحذف كلمات المرور ورموز الوصول والبيانات الشخصية إذا كانت قواعد معالجة البيانات في مؤسستك لا تسمح بإرسالها إلى خادم خارجي.

كيف أتحقق من JSON وأجمّله؟

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

1. انسخ الاستجابة الأولية أو كتلة الإعدادات أو أي قيمة JSON أخرى، من دون تسميات وحدة التحكم المحيطة بها.
2. الصقها في حقل JSON مع الحفاظ على علامات الاقتباس ومحارف الهروب.
3. شغّل التحقق، ثم راجع النتيجة المنسقة أو رسالة الخطأ المعروضة.
4. إذا فشل التحقق، فأصلح أول مشكلة واضحة في الصياغة ثم شغّله مجددا. قد تؤدي علامة اقتباس واحدة مفقودة إلى تفسير عدة محارف لاحقة بطريقة خاطئة.

محارف المسافات البيضاء الأربعة المسموح بها بين رموز JSON هي المسافة (U+0020)، وعلامة الجدولة (U+0009)، وتغذية السطر (U+000A)، والرجوع إلى أول السطر (U+000D). لا تؤثر هذه المحارف في البيانات، لذا يمكن إضافتها أو حذفها من دون تغييرها. أما المسافات البيضاء داخل سلسلة نصية مقتبسة فهي جزء من البيانات ويجب ألا تتغير. وتظل علامات الترقيم داخل السلاسل محفوظة أيضا، مع ضرورة استخدام تسلسل الهروب المناسب لعلامات الاقتباس والشرطات المائلة العكسية ومحارف التحكم.

كيف أقرأ نتيجة التحقق؟

تعني النتيجة الناجحة أن PHP استطاعت فك الإدخال باعتباره JSON. أما الفشل فيعني أن المحلل لم يتمكن من تفسيره بوصفه قيمة JSON واحدة كاملة وصحيحة. بعد ذلك، يُظهر التجميل بوضوح مستويات التداخل وحدود الكائنات والمصفوفات الصحيحة.

من الأسباب الشائعة لفشل التحقق:

• وجود فاصلة زائدة قبل } أو ]؛
• عدم وضع اسم خاصية بين علامتي اقتباس، كما في {name: "Ada"}؛
• استخدام علامتي اقتباس مفردتين مع السلاسل النصية؛
• غياب فاصلة بين الخصائص أو عناصر المصفوفة؛
• وجود علامة اقتباس مزدوجة أو شرطة مائلة عكسية غير مسبوقة بمحرف هروب داخل سلسلة نصية؛
• عدم اكتمال كائن أو مصفوفة أو سلسلة نصية؛
• إدخال UTF-8 غير صالح أو وجود محرف تحكم خام داخل سلسلة نصية؛
• بدء الجزء الصحيح بأصفار غير ضرورية، مثل 01 أو -01، أو استخدام قيم ليست من JSON مثل NaN.

الحقل الفارغ ليس JSON صالحا. في المقابل، تُعد القيمة المنفردة مثل 42 أو true أو null أو "hello" قيمة JSON صحيحة، حتى إن لم تكن كائنا أو مصفوفة. وقد يتجاوز المحتوى شديد التداخل أيضا حد التداخل الذي يسمح به مفكك JSON.

التحقق من الصياغة لا يؤكد توافق البيانات مع عقد واجهة API. فقد يكون المستند JSON صالحا، لكنه يحتوي على سلسلة نصية في موضع يتوقع فيه التطبيق رقما، أو يفتقد خاصية مطلوبة، أو يستخدم تنسيق تاريخ غير مقبول. استخدم JSON Schema أو عمليات التحقق على مستوى التطبيق لهذه المتطلبات.

أمثلة تطبيقية على JSON

إدخال مضغوط صالح:

{"name":"Ada","active":true,"roles":["admin","editor"]}

تعرض النتيجة بعد التجميل الخصائص وعناصر المصفوفة في مستويات منفصلة ذات مسافات بادئة. وتظل القيم، بالترتيب، سلسلة نصية وقيمة منطقية ومصفوفة. يغيّر التنسيق طريقة العرض، لا أنواع البيانات الأساسية.

إدخال غير صالح بسبب فاصلة زائدة:

{"name":"Ada","active":true,}

يفشل هذا الإدخال لأن JSON لا يسمح بوضع فاصلة بعد الخاصية الأخيرة. احذف تلك الفاصلة ليصبح الكائن صالحا.

يمكن أن تظهر الأحرف ذات العلامات والنصوص غير اللاتينية مباشرة داخل سلاسل JSON عندما يكون الإدخال بترميز UTF-8 صالح. على سبيل المثال، {"city":"Zürich","greeting":"こんにちは"} صالح. كما تمثل صيغة الهروب في JSON، مثل \u00fc، طريقة صحيحة أخرى لكتابة بعض محارف Unicode، مع ضرورة استخدام أزواج بديلة للمحارف الواقعة خارج المستوى الأساسي متعدد اللغات.

متى لا يكون تجميل JSON مفيدا؟

لا حاجة إلى تجميل JSON إذا كانت آلة فقط ستقرأه، ولم تكن هناك حاجة إلى مراجعته بشريا أو عبر نظام التحكم في الإصدارات. تزيد المسافات البادئة وفواصل الأسطر الإضافية عدد البايتات المنقولة، لذلك تُرسل استجابات بيئات الإنتاج غالبا بصيغة مضغوطة.

كما لا توجد فائدة كبيرة من تصغير JSON إذا كان مضغوطا بالفعل. لن يؤدي تكرار التصغير إلى تقصير أسماء الخصائص الثابتة أو قيم السلاسل النصية، وسيؤدي تغيير تلك القيم إلى تغيير البيانات. وإذا كنت تتعامل مع JavaScript مخصص للنشر بدلا من بيانات JSON، فاستخدم مصغر JS.

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

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

هل يمكن أن يحتوي JSON على تعليقات؟

لا. لا تتضمن مواصفات JSON القياسية صياغة للتعليقات، لذا يؤدي كل من // comment و/* comment */ إلى فشل التحقق. إذا احتجت إلى تعليقات داخل ملف إعدادات، فاستخدم تنسيقا يدعمها صراحة، أو احذفها قبل تمرير المحتوى إلى محلل JSON صارم.

هل تُرفض أسماء الخصائص المكررة؟

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

هل أستطيع التحقق من ملف JSON Lines؟

ليس باعتباره مستند JSON واحدا. يحتوي JSON Lines، المعروف أيضا باسم NDJSON، على قيمة JSON مستقلة في كل سطر، بينما يتوقع محلل JSON العادي قيمة واحدة في المستوى الأعلى. تحقّق من كل سطر على حدة، أو حوّل السجلات إلى مصفوفة JSON واحدة.

هل ترتيب خصائص كائن JSON مهم؟

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

لماذا يفشل ملف JSON رغم أنه يبدو صحيحا؟

قد تؤدي علامة ترتيب بايتات غير مرئية، أو بيانات UTF-8 مشوهة، أو محرف تحكم غير مسبوق بمحرف هروب، إلى فشل نص يبدو صحيحا. وقد يضيف النسخ من الطرفية أيضا بادئات مثل تسميات الحالة أو الطوابع الزمنية. افحص البايتات الأولية، أو افتح الملف في محرر يستطيع إظهار الترميز ومحارف التحكم.

فحوص أخيرة

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