2. Syntax (Sintassi)

Un modello URI è una stringa di caratteri Unicode stampabili che contiene zero o più espressioni di variabili (Variable Expressions) incorporate, ciascuna espressione delimitata da una coppia corrispondente di parentesi graffe (', ').

URI-Template  = *( literals / expression )

Sebbene i modelli (e le implementazioni del processore di modelli) siano descritti sopra in termini di quattro livelli graduali, definiamo la sintassi URI-Template in termini di ABNF per il Level 4. Un processore di modelli limitato ai modelli di livello inferiore PUÒ (MAY) escludere le regole ABNF applicabili solo ai livelli superiori. Tuttavia, è RACCOMANDATO (RECOMMENDED) che tutti i parser implementino la sintassi completa in modo che i livelli non supportati possano essere identificati correttamente come tali all'utente finale.

2.1. Literals (Letterali)

I caratteri al di fuori delle espressioni in una stringa di modello URI sono destinati a essere copiati letteralmente nel riferimento URI se il carattere è consentito in un URI (reserved / unreserved / pct-encoded) o, se non consentito, copiato nel riferimento URI come sequenza di triplette codificate in percentuale corrispondenti alla codifica di quel carattere in UTF-8 [RFC3629].

literals      =  %x21 / %x23-24 / %x26 / %x28-3B / %x3D / %x3F-5B
              /  %x5D / %x5F / %x61-7A / %x7E / ucschar / iprivate
              /  pct-encoded
                   ; qualsiasi carattere Unicode tranne: CTL, SP,
                   ;  DQUOTE, "'", "%" (a parte pct-encoded),
                   ;  "<", ">", "\", "^", "`", "{", "|", "}"

2.2. Expressions (Espressioni)

Le espressioni di modello sono le parti parametrizzate di un modello URI. Ogni espressione contiene un operatore opzionale (Operator) che definisce il tipo di espressione e il suo processo di espansione corrispondente, seguito da un elenco separato da virgole di specificatori di variabili (Variable Specifiers) (nomi di variabili e modificatori di valore opzionali). Se non viene fornito alcun operatore, l'espressione è predefinita all'espansione di variabile semplice di valori non riservati.

expression    =  "{" [ operator ] variable-list "}"
operator      =  op-level2 / op-level3 / op-reserve
op-level2     =  "+" / "#"
op-level3     =  "." / "/" / ";" / "?" / "&"
op-reserve    =  "=" / "," / "!" / "@" / "|"

I caratteri degli operatori sono stati scelti per riflettere ciascuno dei loro ruoli come caratteri riservati nella sintassi generica URI. Gli operatori definiti nella Sezione 3 di questa specifica includono:

• + Stringhe di caratteri riservate (Reserved character strings)
• # Identificatori di frammento con prefisso "#" (Fragment identifiers)
• . Etichette di nome o estensioni con prefisso "." (Name labels or extensions)
• / Segmenti di percorso con prefisso "/" (Path segments)
• ; Nome parametro di percorso o coppie name=value con prefisso ";" (Path parameter name or name=value pairs)
• ? Componente di query che inizia con "?" e consiste di coppie name=value separate da "&" (Query component)
• & Continuazione di coppie &name=value in stile query all'interno di un componente di query letterale (Continuation of query-style pairs)

I caratteri degli operatori uguale ("="), virgola (","), punto esclamativo ("!"), chiocciola ("@") e pipe ("|") sono riservati per estensioni future.

La sintassi dell'espressione esclude specificamente l'uso del dollaro ("$") e delle parentesi ["(" e ")"] in modo che rimangano disponibili per l'uso al di fuori dell'ambito di questa specifica. Ad esempio, un linguaggio di macro potrebbe utilizzare questi caratteri per applicare la sostituzione di macro a una stringa prima che quella stringa venga elaborata come modello URI.

2.3. Variables (Variabili)

Dopo l'operatore (se presente), ogni espressione contiene un elenco di uno o più specificatori di variabili (varspec) separati da virgole. I nomi delle variabili servono a molteplici scopi: documentazione per i tipi di valori previsti, identificatori per associare i valori all'interno di un processore di modelli e la stringa letterale da utilizzare per il nome nelle espansioni name=value (tranne quando si esplode un array associativo). I nomi delle variabili sono sensibili alle maiuscole perché il nome potrebbe essere espanso all'interno di un componente URI sensibile alle maiuscole.

variable-list =  varspec *( "," varspec )
varspec       =  varname [ modifier-level4 ]
varname       =  varchar *( ["."] varchar )
varchar       =  ALPHA / DIGIT / "_" / pct-encoded

Un varname PUÒ (MAY) contenere una o più triplette codificate in percentuale. Queste triplette sono considerate una parte essenziale del nome della variabile e non vengono decodificate durante l'elaborazione. Un varname contenente caratteri codificati in percentuale non è la stessa variabile di un varname con quegli stessi caratteri decodificati. Le applicazioni che forniscono modelli URI dovrebbero essere coerenti nell'uso della codifica percentuale nei nomi delle variabili.

Un'espressione PUÒ (MAY) fare riferimento a variabili sconosciute al processore di modelli o il cui valore è impostato su un valore speciale "undefined (indefinito)" come undef o null. Tali variabili indefinite ricevono un trattamento speciale dal processo di espansione (Sezione 3.2.1).

Un valore di variabile che è una stringa di lunghezza zero non è considerato indefinito; ha il valore definito di una stringa vuota.

Nei modelli Level 4, una variabile può avere un valore composito (Composite Value) sotto forma di lista di valori o array associativo di coppie (name, value). Tali tipi di valore non sono indicati direttamente dalla sintassi del modello, ma hanno un impatto sul processo di espansione (Sezione 3.2.1).

Una variabile definita come valore di lista è considerata indefinita se la lista contiene zero membri. Una variabile definita come array associativo di coppie (name, value) è considerata indefinita se l'array contiene zero membri o se tutti i nomi dei membri nell'array sono associati a valori indefiniti.

2.4. Value Modifiers (Modificatori di valore)

Ciascuna delle variabili in un'espressione di modello Level 4 può avere un modificatore che indica che la sua espansione è limitata a un prefisso della stringa del valore della variabile o che la sua espansione è esplosa come valore composito sotto forma di lista di valori o array associativo di coppie (name, value).

modifier-level4 =  prefix / explode

2.4.1. Prefix Values (Valori di prefisso)

Un modificatore di prefisso (Prefix Modifier) indica che l'espansione della variabile è limitata a un prefisso della stringa del valore della variabile. I modificatori di prefisso sono spesso utilizzati per partizionare uno spazio di identificatori gerarchicamente, come è comune negli indici di riferimento e nello storage basato su hash. Serve anche a limitare il valore espanso a un numero massimo di caratteri. I modificatori di prefisso non sono applicabili alle variabili che hanno valori compositi.

prefix        =  ":" max-length
max-length    =  %x31-39 0*3DIGIT   ; intero positivo < 10000

Il max-length è un intero positivo che si riferisce a un numero massimo di caratteri dall'inizio del valore della variabile come stringa Unicode. Si noti che questa numerazione è in caratteri, non in ottetti, al fine di evitare di dividere tra gli ottetti di un carattere codificato in multi-ottetti o all'interno di una tripletta codificata in percentuale. Se il max-length è maggiore della lunghezza del valore della variabile, viene utilizzata l'intera stringa del valore.

Ad esempio:

Date le assegnazioni di variabili

  var   := "value"
  semi  := ";"

Modello di esempio      Espansione

  `{var}`              value
  {var:20}           value
  {var:3}            val
  {semi}             %3B
  {semi:2}           %3B

2.4.2. Composite Values (Valori compositi)

Un modificatore di esplosione (Explode Modifier) ("*") indica che la variabile deve essere trattata come un valore composito costituito da una lista di valori o da un array associativo di coppie (name, value). Pertanto, il processo di espansione viene applicato a ciascun membro del composito come se fosse elencato come una variabile separata. Questo tipo di specifica di variabile è significativamente meno auto-documentante rispetto alle variabili non esplose, poiché c'è meno corrispondenza tra il nome della variabile e come appare il riferimento URI dopo l'espansione.

explode       =  "*"

Poiché i modelli URI non contengono un'indicazione di tipo o schema, si presume che il tipo per una variabile esplosa sia determinato dal contesto. Ad esempio, il processore potrebbe ricevere valori in una forma che differenzia i valori come stringhe, liste o array associativi. Allo stesso modo, il contesto in cui viene utilizzato il modello (script, linguaggio di markup, linguaggio di definizione dell'interfaccia, ecc.) potrebbe definire regole per associare i nomi delle variabili ai tipi, alle strutture o allo schema.

I modificatori di esplosione migliorano la brevità nella sintassi del modello URI. Ad esempio, una risorsa che fornisce una mappa geografica per un determinato indirizzo stradale potrebbe accettare cento permutazioni su campi per l'input dell'indirizzo, inclusi indirizzi parziali (ad esempio, solo la città o il codice postale). Tale risorsa potrebbe essere descritta come un modello con ogni componente dell'indirizzo elencato in ordine, o con un modello molto più semplice che utilizza un modificatore di esplosione, come in:

/mapper{?address*}

insieme a un contesto che definisce cosa può includere la variabile denominata "address", ad esempio facendo riferimento a qualche altro standard per l'indirizzamento (ad esempio, [UPU-S42]). Un destinatario consapevole dello schema può quindi fornire espansioni appropriate, come:

/mapper?city=Newport%20Beach&state=CA

Il processo di espansione per le variabili esplose dipende sia dall'operatore utilizzato sia dal fatto che il valore composito debba essere trattato come una lista di valori o come un array associativo di coppie (name, value). Le strutture sono elaborate come un array associativo con nomi corrispondenti ai campi nella definizione della struttura e separatori "." utilizzati per indicare la gerarchia dei nomi nelle sottostrutture.

Se una variabile ha una struttura composita e solo alcuni dei campi in quella struttura hanno valori definiti, allora solo le coppie definite sono presenti nell'espansione. Questo può essere utile per modelli che consistono di un gran numero di termini di query potenziali.

Un modificatore di esplosione applicato a una variabile di lista causa l'espansione per ripetere l'espansione di quella variabile secondo l'operatore, una volta per ogni membro della lista.

---