JSON Pointer, RFC 6901, è una piccola specifica: quattro pagine, una sintassi,
nessuna ambiguità su cosa significa un percorso. Appare dove qualcosa ha
bisogno di fare riferimento a una posizione esatta all'interno di un documento
JSON senza inventare il proprio linguaggio dei percorsi, più spesso all'interno
di JSON Schema e della parola chiave $ref di JSON Schema.
La sintassi, in breve
Un puntatore è una sequenza di token separati da /. /user/name significa
la chiave name all'interno dell'oggetto user. /items/0 significa il
primo elemento dell'array items. La stringa vuota, un puntatore senza
alcun token, significa l'intero documento. Due caratteri necessitano di
escape all'interno di un token: ~1 rappresenta un / letterale, e ~0
rappresenta un ~ letterale, sempre letto in quell'ordine affinché ~01
significhi ~1 invece di /.
Usare il valutatore di JSON Pointer
Incolla un documento, digita un puntatore, e premi Risolvi. Dato
{"a/b":{"c~d":42},"list":["x","y"]}il puntatore /a~1b/c~0d risolve attraverso una chiave che letteralmente
contiene una barra e una chiave che letteralmente contiene una tilde,
restituendo 42. Questa è tutta la ragione per cui esistono gli escape:
senza di essi, una chiave contenente il carattere separatore sarebbe
impossibile da indirizzare.
Cosa ti dice una ricerca fallita
La maggior parte degli strumenti segnala un puntatore fallito come un semplice
“non trovato”, che non è sufficiente per correggerlo in un documento con più
di qualche chiave. Questo ti dice fino a dove è arrivato il puntatore, cosa
ha trovato lì, e quali chiavi ha effettivamente l'oggetto. Chiedere
/a~1b/nope contro lo stesso documento restituisce:
Nessuna chiave “nope” nell'oggetto qui, ha c
d. Risolto fino a /a1b
Questo è sufficiente per vedere l'errore di battitura immediatamente, invece di rileggere l'intero documento per indovinare cosa è andato storto.
Il trattino, e perche non risolve
All'interno di JSON Schema, un trattino come ultimo token di un puntatore
verso un array significa “la posizione dopo l'ultimo elemento”, usato per
l'aggiunta. Da solo, risolvere /items/- contro un documento non nomina un
valore esistente, perché non c'è ancora nulla dove puntare. Il valutatore
spiega questa distinzione invece di trattarla come un errore di analisi
generico.
Dove questo differisce da JSONPath
JSON Pointer nomina una posizione e risolve esattamente a un valore o fallisce. JSONPath è un linguaggio di interrogazione che può corrispondere a più valori contemporaneamente, con wildcards, filtri e fette. Usa un puntatore quando sai esattamente quale valore vuoi; usa JSONPath quando stai cercando valori che corrispondono a una condizione.