JSONPath è un linguaggio di interrogazione per estrarre valori da un documento JSON tramite un percorso — lo stesso ruolo che XPath svolge per XML. Per chi ha lavorato con sistemi della pubblica amministrazione o bancari italiani le cui integrazioni storiche restano basate su XML/SOAP, questa sintassi risulterà familiare.
Sintassi di base
Un'espressione inizia sempre con $, la radice del documento. Da lì, i campi si raggiungono con un punto ($.user.name) o con parentesi quadre ($['user']['name']), e gli elementi di un array tramite indice ($.items[0]).
Selezionare più valori insieme
Il carattere jolly * seleziona tutti gli elementi di un livello, mentre .. è una discesa ricorsiva — trova un campo a qualsiasi profondità senza conoscerne il percorso esatto. Filtri come [?(@.price < 10)] selezionano elementi di un array secondo una condizione simile a un'espressione di programmazione.
A cosa serve
- Estrarre rapidamente un campo da una grande risposta API durante il debug, senza scrivere uno script.
- Filtrare log o eventi in formato JSON secondo una condizione al volo.
- Leggere un valore da un file di configurazione senza scrivere un parser a mano.
JSONPath contro XPath: il classico errore di indicizzazione
Chi proviene da XPath, dove l'indicizzazione dei nodi parte da 1 (book[1] è il primo elemento), spesso sbaglia passando a JSONPath, dove l'indicizzazione parte da 0 — book[1] è già il secondo elemento. Questa sola differenza spiega buona parte degli errori quando si migrano vecchie integrazioni XML/XPath verso API JSON.
Chiavi con punti o spazi
Se il nome di un campo contiene esso stesso un punto, un trattino o uno spazio (ad esempio una chiave letterale "user.name", non campi annidati), la notazione a punti $.user.name diventa ambigua — il parser la legge come i campi annidati user e name. In questo caso la chiave va racchiusa tra parentesi quadre con le virgolette: $['user.name'].