أداة اختبار JSONPath

ما JSONPath؟

‏JSONPath لغة استعلام لـ JSON، كما أن XPath لغة استعلام لـ XML. فتعبير مثل ‎$.store.book[?@.price < 10].title‎ يغوص في المستند ويستخرج ما تريد: كل كتاب دون العشرة، وعنوانه وحده. وتظهر في Kubernetes وkubectl، وفي إعدادات التكامل المستمر، وفي مسارات السجلات، وفي بوابات الواجهات البرمجية، وفي كثير جدًا من المكتبات التي احتاجت طريقة تقول بها أي جزء من الحمولة تقصد.

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

وقد غيّر RFC 9535 ذلك في فبراير 2024. وهذه الأداة تشغّل تنفيذًا حقيقيًا لذلك المعيار: ألصق استعلامًا ومستندًا فتحصل على العقد المطابِقة، والمسار المعياري لكل واحدة، وقولًا فصلًا في أن الترتيب الذي تراه مضمون أم لا.

كيفية الاستخدام

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

ما يحسمه المعيار، والشيئان اللذان لا يحسمهما

والخبر النافع هو مقدار ما يثبّته RFC 9535. فعبارة implementation-defined لا ترد فيه ولا مرة. ترتيب الاجتياز النازل، ودلالة الشرائح ذات الخطوة السالبة، وما تفعله المقارنة حين لا يحدّد أحد طرفيها شيئًا: كل ذلك محدَّد وقابل للاختبار.

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

والثاني مقطع يحمل أكثر من محدِّد، مثل ‎[0,0]‎ أو ‎[*,*]‎. فذلك ينتج كل عقدة مطابقة مرةً لكل محدِّد — مكرَّرةً حقًا لا مدموجة — والتشابك بينها غير مثبَّت. وهذا يستحق المعرفة لأن المواصفة تتكلف التصريح بأن التنفيذات التي تعيد تلك العقدة مرة واحدة غير مطابقة. فإن كنت تعوّل على مكتبة تدمج المكرَّرات، فذلك السلوك ليس هو المعيار.

والقاعدة التي تخالفها أكثر التنفيذات القديمة هي قاعدة الأنواع. فالمقارنة لا تكون إلا بين قيمة حرفية، أو استعلام مفرد — لا يحدّد أكثر من عقدة واحدة — أو دالة تعيد قيمة. ومن ثم فـ ‎$[?@.* == 1]‎ خطأ نحوي، لا مقارنة لا تطابق شيئًا في صمت. والمسار الذي لا يحدّد شيئًا ينتج قيمة خاصة اسمها Nothing لا تساوي إلا نفسها: فمساران غائبان يتساويان، بينما المسار الغائب ليس أصغر من عدد ولا أكبر منه. ويلزم من اشتقاق المواصفة نفسها للعوامل أن المسارين الغائبين يتساويان أو يقلّان أيضًا.

كيف قوبل هذا المحرك، وما لا يثبته ذلك

يصحب RFC 9535 مجموعةَ اختبارات مطابقة رسمية، وهي تحوّل مدى جودة أي تنفيذ إلى رقم. وهي 703 اختبارات يجتازها هذا المحرك كلها. وذلك الرقم يُتحقَّق منه أثناء البناء، فلا يمكن أن يتعفّن في صمت.

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

والدرجة الكاملة لا تبرهن الصحة، وهذا البناء خير مثال. فالمواصفة لا تعرّف إلا عاملَي مقارنة وتشتق الباقي، فيكون «أ أصغر أو يساوي ب» معناه «أ أصغر من ب أو أ يساوي ب». ولما كان Nothing يساوي Nothing، وجب أن يكون Nothing أصغر أو يساوي Nothing كذلك. وقد كانت نسخة مكتوبة يدويًا من ذلك العامل تعيد false، وسجّلت مجموعةُ المطابقة 703 من 703 والعلّة قائمة، لأن المتن لا يغطي تلك الحالة. وإنما التقطتها فحوص منفصلة مشتقة من نص المواصفة لا من اختباراتها.

والحدود التي يجدر ذكرها: تحلّل الأداة مستندك بمحلّل JSON الخاص بالمتصفح، فالعدد الأكبر من أن يسعه double يصل مقرَّبًا قبل أن يراه الاستعلام أصلًا؛ وللمعيار كلام كثير عن الأعداد القابلة للتشغيل البيني، ولا شيء منه ينقذ قيمةً ضاعت عند التحليل. والتعابير النمطية داخل match وsearch تتبع RFC 9485، وهو مجموعة جزئية صغيرة بلا مجموعات التقاط ولا استباق ولا إحالات خلفية؛ والنمط الذي يستعملها ليس I-Regexp صالحًا، والدالة معرَّفة لتعيد false لا لتخطئ.

لماذا هي مجانية؟

يعمل المحرك داخل متصفحك. وتحليل استعلام واجتياز مستند لا يكلّفان شيئًا على جهازك أنت، فلا خادم يُدفع ثمنه ولا حساب يُنشأ.

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