منسق JSON أم مدقق أم عارض أم أداة مقارنة: ماذا تحتاج فعلا؟

أدوات JSON تبدو متشابهة إلى أن تجد نفسك أمام payload مكسور قبل موعد التسليم. Formatter يجعل JSON مقروءا. Validator يخبرك هل الصياغة صحيحة. Viewer يساعدك تتصفح الشجرة. Diff يوضح ما تغير. Path tester يستخرج قيمة محددة. كلها قريبة، لكنها لا تجيب عن نفس السؤال.

JSON موجود في كل مكان: ردود API، ملفات إعدادات، webhooks، logs، exports، feature flags، package files، وبيانات اختبارات. عندما يحدث خطأ، اختيار الأداة الصحيحة يختصر وقتا كبيرا. اختيار الأداة الخطأ يجعلك تشعر أنك تعمل، لكنك لا تقترب من السبب.

هذا الدليل يوضح متى تستخدم كل أداة، وكيف تجمع بينها في workflow عملي.

مثال بسيط

لديك رد API بهذا الشكل:

{"user":{"id":42,"name":"Amina Shah","roles":["admin","editor"],"settings":{"theme":"dark","notifications":true}},"meta":{"request_id":"req_123","duration_ms":84}}

هو JSON صحيح، لكنه مزعج للقراءة. Formatter يحوله إلى:

{
  "user": {
    "id": 42,
    "name": "Amina Shah",
    "roles": ["admin", "editor"],
    "settings": {
      "theme": "dark",
      "notifications": true
    }
  },
  "meta": {
    "request_id": "req_123",
    "duration_ms": 84
  }
}

الآن صار واضحا. لكن التنسيق لم يثبت أن الحقول صحيحة، ولم يقارن الرد برد قديم، ولم يخبرك هل duration_ms يجب أن يكون رقما أو نصا. فقط جعله مقروءا.

JSON Formatter: اجعله مقروءا

Formatter أو Beautifier يرتب JSON بإضافة مسافات وتدرج. وقد يفعل العكس أيضا، أي minify لإزالة المسافات.

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

لكن Formatter لا يفهم نية البيانات. هذا صحيح JSON:

{
  "active": "false"
}

وقد يكون خطأ إذا كانت الواجهة تتوقع:

{
  "active": false
}

الأول نص، والثاني قيمة منطقية. Formatter لن يعترض لأن الصياغة سليمة. لذلك لا تخلط بين "مرتب" و"صحيح حسب النظام".

JSON Validator: هل الصياغة صحيحة؟

Validator يفحص قواعد JSON. يمسك الفواصل الناقصة، الفواصل الزائدة في النهاية، المفاتيح غير الموضوعة بين quotes، single quotes، الأقواس الزائدة، ومشاكل escape.

هذا ليس JSON صحيحا:

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

المفتاح name يحتاج quotes، والفاصلة الأخيرة غير مسموحة في JSON الصارم.

استخدم Validator عندما يرفض API الطلب، أو لا يقرأ التطبيق ملف config، أو نسخت JSON من محادثة أو log وتشعر أن فيه شيئا مكسورا.

لكن Validator لا يعرف قواعد عملك. يمكنه قول إن "age": "30" صحيح، لكنه لا يعرف أن نظامك يريد age كرقم. هنا تحتاج Schema أو validation داخل التطبيق.

JSON Viewer: تصفح الشجرة

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

استخدم Viewer عندما تريد معرفة أين يوجد الحقل، أو عندما تستكشف API جديدا، أو عندما تحتوي المصفوفة على عناصر كثيرة وتريد فهم البنية العامة.

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

Viewer يجيب عن سؤال: أين أجد الشيء؟ وليس: هل تغير؟ أو هل هو صالح؟

JSON Diff: ما الذي تغير؟

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

مثال قديم:

{
  "plan": "pro",
  "limits": {
    "projects": 10
  }
}

مثال جديد:

{
  "plan": "pro",
  "limits": {
    "projects": 25
  }
}

Diff الجيد يريك أن limits.projects تغير من 10 إلى 25.

استخدم Diff لمراجعة ملفات config، مقارنة ردود API بين staging و production، تحديث fixtures، أو فهم لماذا فشل اختبار بعد تغيير.

Text diff العادي قد يصرخ بسبب اختلاف التنسيق فقط. JSON diff الأفضل يقارن البنية والقيم بعد parsing.

JSON Path Tester: استخرج قيمة محددة

JSONPath يساعدك تشير إلى قيمة داخل JSON:

$.user.settings.theme

هذا يستخرج:

"dark"

استخدم Path tester عندما تضبط automation، أو تكتب test، أو تحتاج استخراج قيمة من webhook، أو تريد توثيق مكان حقل داخل payload كبير.

انتبه أن صيغة JSONPath قد تختلف قليلا بين المكتبات. لذلك اختبار path على نفس payload مهم قبل وضعه في الإنتاج.

Converter: حول الصيغة

أحيانا JSON ليس الوجهة النهائية. فريق يريد CSV، أداة config تريد YAML، نظام قديم يريد XML. هنا تستخدم converters.

لكن التحويل ليس سحرا. JSON مسطح على شكل array of objects يتحول إلى CSV بسهولة. JSON متداخل بعمق يحتاج قرارا: ما الصف؟ ما الأعمدة؟ هل نكرر البيانات؟ JSON إلى XML يحتاج root element وقرارات حول العناصر والattributes. JSON إلى YAML أسهل غالبا، لكنه لن يخلق تعليقات لم تكن موجودة.

الترتيب العملي: Validate، ثم Format، ثم افهم البنية، ثم Convert. لا تحول شيئا لا تفهمه.

مقارنة سريعة

غالبا ستستخدم أكثر من أداة في نفس المشكلة. مثلا: API يرفض request. ابدأ بـ Validator. بعد الإصلاح، استخدم Formatter. إذا الرد كبير، افتحه في Viewer. إذا المشكلة ظهرت بعد deploy، استخدم Diff مع رد قديم. إذا تحتاج قيمة في اختبار، استخدم Path tester.

JSON صحيح لا يعني JSON مناسب

هذه نقطة مهمة. Valid JSON يعني أن parser يستطيع قراءته. Correct JSON يعني أنه يطابق ما يتوقعه النظام.

هذا صحيح من ناحية الصياغة:

{
  "price": "19.99",
  "currency": "usd",
  "items": {}
}

لكنه قد يكون خطأ إذا كان API يتوقع:

{
  "price": 19.99,
  "currency": "USD",
  "items": []
}

Validator وحده لا يكفي. تحتاج schema أو توثيق أو اختبارات أو رسالة خطأ واضحة من النظام.

متى يكون التنسيق خطرا؟

Formatting لا يغير البيانات بعد parsing، لكنه يغير النص نفسه. غالبا هذا لا يهم. لكنه يهم في حالات مثل webhook signatures أو hashes مبنية على raw body. إذا كان التوقيع محسوبا على النص الأصلي، فإن إعادة التنسيق قبل التحقق قد تكسر التوقيع.

لذلك عند التعامل مع payload موقع، احتفظ بالنسخة الخام للتحقق، واستخدم نسخة أخرى للقراءة.

Workflows عملية

إذا ظهر خطأ "invalid JSON"، استخدم Validator أولا. لا تضيع وقتا في Diff قبل أن يتأكد parser من القراءة.

إذا الواجهة الأمامية تعطلت بعد تغيير backend، قارن الرد القديم والجديد بـ Diff. ركز على الأنواع والمفاتيح المحذوفة والقيم null.

إذا تحتاج حقل واحد من webhook، افتح payload في Viewer، ثم اكتب JSONPath واختبره.

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

إذا ملف config مقروء لكنه لا يعطي السلوك المتوقع، Validator ليس كافيا. راجع schema أو قواعد التطبيق.

مجموعة أدوات صغيرة تكفي

لا تحتاج عشرين أداة. تحتاج Formatter، Validator، Viewer، Diff، Path tester، وبعض converters. الأهم أن تعرف متى تستخدم كل واحدة.

احتفظ بعينات payload صحيحة للواجهات المهمة. عندما يحدث خطأ، قارن مع known-good بدلا من الاعتماد على الذاكرة. نسق JSON قبل مشاركته في tickets. واكتب schema عندما يكون العقد مهما بين فريقين.

أخطاء تجعل التصحيح أطول

أول خطأ هو تعديل payload الأصلي أثناء التصحيح. إذا كان لديك webhook أو request مهم، احتفظ بنسخة raw قبل أن تنسقه أو تنسخه بين أدوات. بعض المشاكل تعتمد على whitespace أو ترتيب أو body الأصلي، خصوصا في التواقيع.

الخطأ الثاني هو تجاهل الأنواع. كثير من الواجهات تنكسر بسبب فرق صغير بين "42" و 42، أو بين {} و []، أو بين null وحقل غير موجود. عند استخدام Diff، لا تنظر إلى أسماء المفاتيح فقط. راقب النوع أيضا.

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

الخطأ الرابع هو تحويل JSON إلى CSV بسرعة قبل فهم البنية. إذا كان لديك arrays متداخلة، فالتحويل يحتاج قرارا. هل كل عنصر يصبح صفا؟ هل نكرر بيانات الأب؟ هل نضع القيم داخل خلية واحدة؟ لا توجد إجابة عامة، ويجب أن تتفق مع الشخص الذي سيستخدم الملف.

عادة صغيرة مفيدة

عندما تصل إلى حل، احتفظ بالمثال الذي كسر النظام والمثال بعد الإصلاح. ضعه في test أو في توثيق داخلي. JSON bugs تتكرر لأنها تبدو بسيطة، ثم ينسى الفريق السياق. وجود payload حقيقي يوفر وقتا في المرة القادمة.

اكتب أيضا ملاحظات قصيرة بجانب JSONPath أو schema. مثلا: "هذا الحقل قد يكون null عند الحسابات الجديدة" أو "هذه المصفوفة غير مضمونة الترتيب". هذه التفاصيل الصغيرة تمنع اعتمادا خاطئا في الكود.

في النهاية، أدوات JSON ليست بديلة عن الفهم. هي عدسات مختلفة. Formatter عدسة للقراءة، Validator عدسة للصياغة، Viewer عدسة للبنية، Diff عدسة للتغيير، وPath tester عدسة للاستخراج. عندما تعرف أي عدسة تحتاج، يصبح التصحيح أهدأ وأسرع.

كيف تختار؟

اسأل نفسك: هل المشكلة أن JSON لا يقرأ؟ Validator. هل لا أستطيع رؤيته بوضوح؟ Formatter. هل أبحث عن حقل؟ Viewer أو Path tester. هل حدث تغيير؟ Diff. هل أريد تسليمه لشخص يستخدم جدول؟ Converter.

اجعل الإصلاح قابلا للتكرار

بعد أن تصل للحل، لا تتركه في ذاكرتك فقط. احفظ payload قبل وبعد، واكتب ملاحظة قصيرة عن السبب. إذا كان الخطأ في trailing comma، أضف validation في pipeline. إذا كان في نوع حقل، أضف test أو schema. إذا كان في path مستخدم داخل automation، ضع مثالا في التوثيق. الهدف ليس إصلاح JSON اليوم فقط، بل منع نفس المشكلة من العودة بعد أسبوعين باسم مختلف. الأدوات تساعدك ترى المشكلة، لكن الاختبار والتوثيق يمنعانها من الدوران.

ومن الأفضل أن تحفظ أمثلة للحالات الفارغة والحالات الكبيرة، لا المثال المثالي فقط. Payload فيه مصفوفة فارغة، وآخر فيه null, وآخر فيه حقل اختياري غير موجود، تكشف أخطاء كثيرة في الواجهة أو التحويل إلى CSV. عندما تكون هذه الأمثلة جاهزة، يصبح استخدام Diff وViewer أسرع لأنك تعرف ما الطبيعي وما الغريب.

الخلاصة

Formatter يجعل JSON مقروءا. Validator يفحص الصياغة. Viewer يساعدك تتنقل في البنية. Diff يكشف التغييرات. Path tester يستخرج القيم. Converter ينقل البيانات لصيغة أخرى.

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