JSONPath, bir yol üzerinden JSON belgesinden değer çıkaran bir sorgu dilidir — XML için XPath'in gördüğü işi görür. Entegrasyonları hâlâ XML/SOAP tabanlı olan Türkiye'deki kamu veya bankacılık sistemleriyle çalışmış olanlar için bu söz dizimi tanıdık gelecektir.
Temel söz dizimi
Bir ifade her zaman belgenin kökünü temsil eden $ ile başlar. Oradan alanlara nokta ile ($.user.name) veya köşeli parantezle ($['user']['name']) erişilir, dizi elemanlarına ise indeksle ($.items[0]) erişilir.
Birden fazla değeri aynı anda seçmek
* karakteri belirli bir seviyedeki tüm elemanları seçer, .. ise özyinelemeli iniştir — tam yolu bilmeden belgenin herhangi bir derinliğindeki alanı bulur. [?(@.price < 10)] gibi filtreler, bir programlama ifadesine benzeyen bir koşula göre dizi elemanlarını seçer.
Ne işe yarar
- Hata ayıklama sırasında büyük bir API yanıtından tek bir alanı script yazmadan hızlıca çekmek.
- JSON formatındaki logları veya olayları anında bir koşula göre filtrelemek.
- Bir yapılandırma dosyasından elle bir ayrıştırıcı yazmadan değer okumak.
JSONPath'e karşı XPath: klasik indeks hatası
Düğüm indekslemesinin 1'den başladığı XPath'ten gelenler (book[1] ilk elemandır), indekslemenin 0'dan başladığı JSONPath'e geçince genellikle yanılır — book[1] artık ikinci elemandır. Sadece bu fark, eski XML/XPath entegrasyonları JSON API'lere taşınırken ortaya çıkan hataların önemli bir kısmını açıklar.
Nokta veya boşluk içeren anahtarlar
Bir alan adının kendisi nokta, tire veya boşluk içeriyorsa (iç içe alanlar yerine "user.name" gibi harfi harfine bir anahtar), nokta gösterimi $.user.name belirsiz hâle gelir — ayrıştırıcı bunu iç içe geçmiş user ve name alanları olarak okur. Bu durumda anahtar, tırnak içinde köşeli parantez kullanılarak yazılmalıdır: $['user.name'].