2.1. Overview (Panoramica)

Una JSONPath expression (espressione) è una stringa che, applicata a un valore JSON (l'query argument, argomento dell'interrogazione), seleziona zero o più nodi dell'argomento e produce questi nodi come nodelist.

Un'interrogazione DEVE essere codificata usando UTF-8. La grammatica per le interrogazioni fornita in questo documento assume che la sua forma UTF-8 sia prima decodificata in valori scalari Unicode come descritto in [RFC3629]; sono possibili approcci di implementazione che conducono a un risultato equivalente.

Una stringa da usare come interrogazione JSONPath deve essere well-formed (ben formata) e valid (valida). Una stringa è un'interrogazione JSONPath ben formata se è conforme alla sintassi ABNF in questo documento. Un'interrogazione JSONPath ben formata è valida se soddisfa anche entrambi i requisiti semantici posti da questo documento, che sono i seguenti:

I numeri interi nell'interrogazione JSONPath rilevanti per l'elaborazione JSONPath (ad esempio valori di indice e passi) DEVONO essere nell'intervallo dei valori interi esatti definiti in Internet JSON (I-JSON) (vedere Sezione 2.2 di [RFC7493]), vale a dire nell'intervallo [-(2^53)+1, (2^53)-1].
Gli usi delle function extensions (estensioni di funzione) DEVONO essere well-typed (ben tipizzati), come descritto nella Sezione 2.4.3.

Un'implementazione JSONPath DEVE segnalare un errore per qualsiasi interrogazione che non sia ben formata e valida. La correttezza formale e la validità delle interrogazioni JSONPath sono indipendenti dal valore JSON a cui l'interrogazione è applicata. Non possono essere segnalati ulteriori errori relativi alla correttezza formale e alla validità di un'interrogazione JSONPath durante l'applicazione dell'interrogazione a un valore. Ciò separa chiaramente gli errori di correttezza formale/validità nell'interrogazione da disallineamenti che possono in realtà derivare da difetti nei dati.

I disallineamenti tra la struttura attesa da un'interrogazione valida e la struttura trovata nei dati possono portare a risultati di interrogazione vuoti, che possono essere inattesi e indicare bug nell'una o nell'altra. Le implementazioni JSONPath potrebbero quindi voler fornire diagnostica allo sviluppatore dell'applicazione che aiuti a trovare la causa di risultati vuoti.

Ovviamente, un'implementazione può ancora fallire durante l'esecuzione di un'interrogazione JSONPath, ad esempio per esaurimento delle risorse, ma ciò non è modellato in questo documento. Tuttavia, l'implementazione NON DEVE malfunzionare silenziosamente. In particolare, se un'interrogazione JSONPath valida è valutata rispetto a un valore strutturato la cui dimensione è troppo grande per elaborare correttamente l'interrogazione (ad esempio richiedendo l'elaborazione di numeri che cadono fuori dall'intervallo di valori esatti), l'implementazione DEVE fornire un'indicazione di overflow.

(I lettori familiari con il modello di errore HTTP possono essere richiamati agli errori di tipo 400 quando riflettono su correttezza formale e validità, e possono riconoscere l'esaurimento delle risorse e errori correlati come paragonabili agli errori di tipo 500.)

2.1.1. Syntax (Sintassi)

Sintatticamente, un'interrogazione JSONPath consiste in un root identifier (identificatore radice) ($), che rappresenta una nodelist che contiene il nodo radice dell'argomento dell'interrogazione, seguito da una sequenza eventualmente vuota di segments (segmenti).

jsonpath-query      = root-identifier segments
segments            = *(S segment)

B                   = %x20 /    ; Space
                      %x09 /    ; Horizontal tab
                      %x0A /    ; Line feed or New line
                      %x0D      ; Carriage return
S                   = *B        ; optional blank space

La sintassi e la semantica dei segmenti sono definite nella Sezione 2.5.

2.1.2. Semantics (Semantica)

In questo documento, la semantica di un'interrogazione JSONPath definisce i risultati richiesti e non prescrive il funzionamento interno di un'implementazione. Questo documento può descrivere la semantica in modo procedurale passo dopo passo; tuttavia, tali descrizioni sono normative solo nel senso che qualsiasi implementazione DEVE produrre un risultato identico ma non nel senso che gli implementatori siano tenuti a usare gli stessi algoritmi.

La semantica è che un'interrogazione valida è eseguita rispetto a un valore (l'argomento dell'interrogazione) e produce una nodelist (vale a dire una lista di zero o più nodi del valore).

L'interrogazione è un identificatore radice seguito da una sequenza di zero o più segmenti, ciascuno dei quali è applicato al risultato dell'identificatore radice o del segmento precedente e fornisce input al segmento successivo. Questi risultati e input hanno la forma di nodelist.

La nodelist risultante dall'identificatore radice contiene un singolo nodo (l'argomento dell'interrogazione). La nodelist risultante dall'ultimo segmento è presentata come risultato dell'interrogazione. A seconda dell'API specifica, può essere presentata come array dei valori JSON ai nodi, come array di Normalized Paths che referenziano i nodi, o entrambi, o qualche altra rappresentazione desiderata dall'implementazione. Nota: una nodelist vuota è un risultato di interrogazione valido.

Un segmento opera su ciascuno dei nodi nella sua nodelist di input a turno, e le nodelist risultanti sono concatenate nell'ordine della nodelist di input da cui sono state derivate per produrre il risultato del segmento. Un nodo può essere selezionato più di una volta e compare quel numero di volte nella nodelist. I nodi duplicati non vengono rimossi.

Un segmento sintatticamente valido NON DEVE produrre errori durante l'esecuzione dell'interrogazione. Ciò significa che alcune operazioni che potrebbero essere considerate errate, come l'uso di un indice fuori dall'intervallo di un array, semplicemente risultano in meno nodi selezionati. (Ulteriore discussione di questa proprietà si trova nell'introduzione della Sezione 2.1.)

Come conseguenza di questo approccio, se uno qualsiasi dei segmenti produce una nodelist vuota, l'intera interrogazione produce una nodelist vuota.

Se la semantica di un'interrogazione dà a un'implementazione la scelta di produrre più ordinamenti possibili, una particolare implementazione può produrre ordinamenti distinti in esecuzioni successive dell'interrogazione.

2.1.3. Example (Esempio)

Considerare questo esempio. Con l'argomento dell'interrogazione {"a":[{"b":0},{"b":1},{"c":2}]}, l'interrogazione $.a[*].b seleziona la seguente lista di nodi (qui denotati dai loro valori): 0, 1.

L'interrogazione consiste in $ seguito da tre segmenti: .a, [*], e .b.

Prima, $ produce una nodelist costituita solo dall'argomento dell'interrogazione.

Poi, .a seleziona da qualsiasi nodo di input oggetto e seleziona il nodo di qualsiasi valore di membro del nodo di input corrispondente al nome di membro "a". Il risultato è di nuovo una lista contenente un singolo nodo: [{"b":0},{"b":1},{"c":2}].

Poi, [*] seleziona tutti gli elementi dal nodo array di input. Il risultato è una lista di tre nodi: {"b":0}, {"b":1}, e {"c":2}.

Infine, .b seleziona da qualsiasi nodo di input oggetto con un nome di membro b e seleziona il nodo del valore di membro del nodo di input corrispondente a quel nome. Il risultato è una lista contenente 0, 1. Ciò è la concatenazione di tre liste: due di lunghezza uno contenenti 0, 1, rispettivamente, e una di lunghezza zero.