JSONPath لغة استعلام لاستخراج قيم من مستند JSON عبر مسار، وهي تؤدي للـJSON نفس الدور الذي تؤديه XPath لـXML — وهو ما يجعل صيغتها مألوفة لمن عمل سابقًا مع أنظمة حكومية أو مصرفية عربية بُنيت على XML/SOAP قبل انتقالها إلى واجهات JSON.
الصيغة الأساسية
يبدأ أي تعبير بالرمز $ الذي يمثل جذر المستند. بعده تُقرأ الحقول إما بنقطة ($.user.name) أو بأقواس مربعة ($['user']['name'])، وعناصر المصفوفة بالفهرس ($.items[0]).
اختيار عدة قيم دفعة واحدة
الرمز * يختار كل العناصر في مستوى معيّن، بينما .. هو نزول متكرر (recursive descent) يجد الحقل على أي عمق دون معرفة مساره الدقيق. الفلاتر مثل [?(@.price < 10)] تختار عناصر المصفوفة وفق شرط يشبه تعبيرًا برمجيًا.
لماذا نحتاج هذا
- استخراج حقل معين بسرعة من استجابة API كبيرة أثناء تصحيح الأخطاء، دون كتابة سكربت.
- تصفية سجلات أو أحداث بصيغة JSON وفق شرط مباشرة.
- قراءة قيمة من ملف إعدادات دون كتابة محلّل (parser) يدويًا.
JSONPath مقابل XPath: خطأ فهرسة شائع
من انتقل من XPath، حيث تبدأ فهرسة العناصر من 1 (فـbook[1] هو العنصر الأول)، يقع غالبًا في خطأ عند استخدام JSONPath، حيث تبدأ الفهرسة من 0 — أي أن book[1] هو العنصر الثاني فعليًا. هذا الفرق وحده مسؤول عن جزء لا بأس به من الأخطاء عند ترحيل تكاملات XML/XPath القديمة إلى واجهات JSON.
المفاتيح التي تحوي نقاطًا أو مسافات
إذا كان اسم الحقل نفسه يحتوي نقطة أو شرطة أو مسافة (مثل مفتاح حرفي "user.name" وليس حقولًا متداخلة)، فإن الترميز بالنقاط $.user.name يصبح ملتبسًا — إذ يقرأه المحلّل على أنه حقلان متداخلان user وname. في هذه الحالة يجب وضع المفتاح بين أقواس مربعة مع علامات اقتباس: $['user.name'].