JSONPath to język zapytań do pobierania wartości z dokumentu JSON za pomocą ścieżki — pełni tę samą rolę co XPath dla XML. Dla osób pracujących z polskimi systemami administracji publicznej lub bankowości, gdzie integracje wciąż często opierają się na XML/SOAP, ta składnia będzie znajoma.
Podstawowa składnia
Wyrażenie zawsze zaczyna się od $, czyli korzenia dokumentu. Stamtąd do pól dociera się kropką ($.user.name) lub nawiasami kwadratowymi ($['user']['name']), a do elementów tablicy — przez indeks ($.items[0]).
Wybieranie kilku wartości naraz
Symbol wieloznaczny * wybiera wszystkie elementy na danym poziomie, a .. to zejście rekurencyjne — znajduje pole na dowolnej głębokości bez znajomości dokładnej ścieżki. Filtry takie jak [?(@.price < 10)] wybierają elementy tablicy według warunku przypominającego wyrażenie programistyczne.
Do czego to się przydaje
- Szybkie wyciągnięcie jednego pola z dużej odpowiedzi API podczas debugowania, bez pisania skryptu.
- Filtrowanie logów lub zdarzeń w formacie JSON według warunku na bieżąco.
- Odczytanie wartości z pliku konfiguracyjnego bez pisania własnego parsera.
JSONPath kontra XPath: klasyczny błąd o jeden indeks
Osoby przechodzące z XPath, gdzie indeksowanie węzłów zaczyna się od 1 (book[1] to pierwszy element), często mylą się przy JSONPath, gdzie indeksowanie zaczyna się od 0 — book[1] to już drugi element. Sama ta różnica odpowiada za sporą część błędów przy migracji starych integracji XML/XPath do API JSON.
Klucze z kropkami lub spacjami
Jeśli nazwa pola sama zawiera kropkę, myślnik lub spację (na przykład dosłowny klucz "user.name", a nie zagnieżdżone pola), notacja kropkowa $.user.name staje się niejednoznaczna — parser odczyta ją jako zagnieżdżone pola user i name. W takim przypadku klucz trzeba ująć w nawiasy kwadratowe z cudzysłowem: $['user.name'].