Passa al contenuto principale

RFC 6570 - Modelli URI

  • Stato: Proposed Standard
  • Pubblicato: March 2012
  • Stream: IETF
  • Errata: Nessun errata

Sommario (Abstract)​

Un modello URI (URI Template) è una sequenza compatta di caratteri per descrivere un insieme di identificatori di risorse uniformi (Uniform Resource Identifiers) attraverso l'espansione di variabili. Questa specifica definisce la sintassi dei modelli URI e il processo per espandere un modello URI in un riferimento URI, insieme alle linee guida per l'uso dei modelli URI su Internet.

Indice (Contents)​

  • 1. Introduction (Introduzione)
    • 1.1. Overview (Panoramica)
    • 1.2. Levels and Expression Types (Livelli e tipi di espressione)
    • 1.3. Design Considerations (Considerazioni di progettazione)
    • 1.4. Limitations (Limitazioni)
    • 1.5. Notational Conventions (Convenzioni notazionali)
    • 1.6. Character Encoding and Unicode Normalization (Codifica dei caratteri e normalizzazione Unicode)
  • 2. Syntax (Sintassi)
    • 2.1. Literals (Letterali)
    • 2.2. Expressions (Espressioni)
    • 2.3. Variables (Variabili)
    • 2.4. Value Modifiers (Modificatori di valore)
      • 2.4.1. Prefix Values (Valori di prefisso)
      • 2.4.2. Composite Values (Valori compositi)
  • 3. Expansion (Espansione)
    • 3.1. Literal Expansion (Espansione letterale)
    • 3.2. Expression Expansion (Espansione di espressioni)
      • 3.2.1. Variable Expansion (Espansione di variabili)
      • 3.2.2. Simple String Expansion: {var} (Espansione di stringa semplice)
      • 3.2.3. Reserved Expansion: {+var} (Espansione di caratteri riservati)
      • 3.2.4. Fragment Expansion: {#var} (Espansione di frammento)
      • 3.2.5. Label Expansion with Dot-Prefix: {.var} (Espansione di etichetta con prefisso punto)
      • 3.2.6. Path Segment Expansion: {/var} (Espansione di segmento di percorso)
      • 3.2.7. Path-Style Parameter Expansion: {;var} (Espansione di parametro stile percorso)
      • 3.2.8. Form-Style Query Expansion: {?var} (Espansione di query stile modulo)
      • 3.2.9. Form-Style Query Continuation: {&var} (Continuazione di query stile modulo)
  • 4. Security Considerations (Considerazioni sulla sicurezza)
  • 5. Acknowledgments (Riconoscimenti)
  • 6. References (Riferimenti)
    • 6.1. Normative References (Riferimenti normativi)
    • 6.2. Informative References (Riferimenti informativi)

Appendici (Appendices)​

Risorse correlate​

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.

3. Expansion (Espansione)​

Il processo di espansione del modello URI consiste nel scansionare la stringa del modello dall'inizio alla fine, copiando i caratteri letterali e sostituendo ogni espressione con il risultato dell'applicazione dell'operatore dell'espressione al valore di ogni variabile nominata nell'espressione. Il valore di ogni variabile DEVE (MUST) essere formato prima dell'espansione del modello.

Questa sezione definisce i requisiti di espansione per ogni aspetto della grammatica del modello URI. Un algoritmo non normativo per il processo di espansione nel suo insieme è fornito nell'Appendice A.

Se un processore di modelli incontra una sequenza di caratteri al di fuori di un'espressione che non corrisponde alla grammatica <URI-Template>, allora l'elaborazione del modello DOVREBBE (SHOULD) cessare, il risultato del riferimento URI DOVREBBE (SHOULD) contenere la parte espansa del modello seguita dal resto non espanso, e la posizione e il tipo di errore DOVREBBERO (SHOULD) essere indicati all'applicazione chiamante.

Se viene rilevato un errore in un'espressione, come un operatore o un modificatore di valore che il processore di modelli non riconosce o non supporta ancora, o se viene trovato un carattere non consentito dalla grammatica <expression>, allora le parti non elaborate dell'espressione DOVREBBERO (SHOULD) essere copiate nel risultato non espanse, l'elaborazione del resto del modello DOVREBBE (SHOULD) continuare, e la posizione e il tipo di errore DOVREBBERO (SHOULD) essere indicati all'applicazione chiamante.

Se si verifica un errore, il risultato restituito potrebbe non essere un riferimento URI valido; sarà una stringa di modello incompletamente espansa destinata solo a scopi diagnostici.

3.1. Literal Expansion (Espansione letterale)​

Se il carattere letterale è consentito ovunque nella sintassi URI (unreserved / reserved / pct-encoded), viene copiato direttamente nella stringa di risultato. Altrimenti, l'equivalente codificato in percentuale del carattere letterale viene copiato nella stringa di risultato codificando prima il carattere come la sua sequenza di ottetti in UTF-8 e poi codificando ogni ottetto come un tripletto codificato in percentuale.

3.2. Expression Expansion (Espansione di espressione)​

Ogni espressione è indicata da un carattere di parentesi graffa aperta ("{") e continua fino alla successiva parentesi graffa chiusa ("}"). Le espressioni non possono essere annidate.

Un'espressione viene espansa determinando il suo tipo di espressione e quindi seguendo il processo di espansione di quel tipo per ogni varspec separato da virgola nell'espressione. I modelli di Livello 1 sono limitati all'operatore predefinito (espansione di valore di stringa semplice) e una singola variabile per espressione. I modelli di Livello 2 sono limitati a un singolo varspec per espressione.

Il tipo di espressione è determinato osservando il primo carattere dopo la parentesi graffa aperta. Se il carattere è un operatore, si memorizza il tipo di espressione associato a quell'operatore per decisioni di espansione successive e si passa al carattere successivo per l'elenco delle variabili. Se il primo carattere non è un operatore, il tipo di espressione è l'espansione di stringa semplice e il primo carattere è l'inizio dell'elenco delle variabili.

Gli esempi nelle sottosezioni seguenti utilizzano le seguenti definizioni di valori di variabili:

count := ("one", "two", "three")
dom   := ("example", "com")
dub   := "me/too"
hello := "Hello World!"
half  := "50%"
var   := "value"
who   := "fred"
base  := "http://example.com/home/"
path  := "/foo/bar"
list  := ("red", "green", "blue")
keys  := [("semi",";"),("dot","."),("comma",",")]
v     := "6"
x     := "1024"
y     := "768"
empty := ""
empty_keys  := []
undef := null

3.2.1. Variable Expansion (Espansione di variabile)​

Una variabile indefinita (Sezione 2.3) non ha valore ed è ignorata dal processo di espansione. Se tutte le variabili in un'espressione sono indefinite, l'espansione dell'espressione è la stringa vuota.

L'espansione di variabile di un valore definito e non vuoto risulta in una sottostringa di caratteri URI consentiti. Come descritto nella Sezione 1.6, il processo di espansione è definito in termini di punti di codice Unicode al fine di garantire che i caratteri non ASCII siano codificati in percentuale in modo coerente nel riferimento URI risultante. Un modo per un processore di modelli di ottenere un'espansione coerente è transcodificare la stringa del valore in UTF-8 (se non è già UTF-8) e quindi trasformare ogni ottetto che non è nell'insieme consentito nel tripletto codificato in percentuale corrispondente.

L'insieme consentito per una data espansione dipende dal tipo di espressione: le espansioni riservate ("+") e di frammento ("#") consentono all'insieme di caratteri nell'unione di (unreserved / reserved / pct-encoded) di passare senza codifica percentuale, mentre tutti gli altri tipi di espressione consentono solo ai caratteri non riservati di passare senza codifica percentuale. Si noti che il carattere percentuale ("%") è consentito solo come parte di un tripletto codificato in percentuale e solo per l'espansione riservata/frammento: in tutti gli altri casi, un carattere di valore "%" DEVE (MUST) essere codificato in percentuale come "%25" dall'espansione di variabile.

Se una variabile appare più di una volta in un'espressione o all'interno di più espressioni di un modello URI, il valore di quella variabile DEVE (MUST) rimanere statico durante l'intero processo di espansione (cioè, la variabile deve avere lo stesso valore ai fini del calcolo di ogni espansione). Tuttavia, se caratteri riservati o tripletti codificati in percentuale appaiono nel valore, saranno codificati in percentuale da alcuni tipi di espressione e non da altri.

Per una variabile che è un valore di stringa semplice, l'espansione consiste nell'aggiungere il valore codificato alla stringa di risultato. Un modificatore di esplosione non ha effetto. Un modificatore di prefisso limita l'espansione ai primi max-length caratteri del valore decodificato. Se il valore contiene caratteri multi-ottetto o codificati in percentuale, è necessario prestare attenzione a evitare di dividere il valore a metà carattere: contare ogni punto di codice Unicode come un carattere.

Per una variabile che è un array associativo, l'espansione dipende sia dal tipo di espressione che dalla presenza di un modificatore di esplosione. Se non c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere una concatenazione separata da virgole di ogni coppia (name, value) che ha un valore definito. Se c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere ogni coppia che ha un valore definito come "name=value" o, se il valore è la stringa vuota e il tipo di espressione non indica parametri in stile modulo (cioè, non un tipo "?" o "&"), semplicemente "name". Entrambe le stringhe name e value sono codificate nello stesso modo dei valori di stringa semplici. Una stringa di separatore viene aggiunta tra le coppie definite secondo il tipo di espressione, come definito dalla seguente tabella:

Tipo    Separatore
       ","     (predefinito)
  +     ","
  #     ","
  .     "."
  /     "/"
  ;     ";"
  ?     "&"
  &     "&"

Per una variabile che è un valore di lista, se non c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere una concatenazione separata da virgole di ogni valore membro della lista che ha un valore definito, come valore di un singolo nome per quella variabile. Se c'è un modificatore di esplosione, l'espansione consiste nell'aggiungere ogni valore membro della lista che ha un valore definito come valore separato con il nome di quella variabile, o, per i tipi di espressione che non hanno variabili nominate (nessun ";", "?" o "&"), semplicemente aggiungere ogni valore separato dal separatore specifico del tipo.

Un modificatore di prefisso su un valore di lista o valore di array associativo non ha effetto.

3.2.2. Simple String Expansion: {var} (Espansione di stringa semplice)​

L'espansione di stringa semplice è il tipo di espressione predefinito quando non viene fornito alcun operatore.

Per ogni variabile definita nell'elenco delle variabili, eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato. Se più di una variabile ha un valore definito, aggiungere una virgola (",") alla stringa di risultato come separatore tra le espansioni di variabili.

Modello di esempio    Espansione

  `{var}`              value
  {hello}            Hello%20World%21
  {half}             50%25
  O{empty}X          OX
  O{undef}X          OX
  {x,y}              1024,768
  {x,hello,y}        1024,Hello%20World%21,768
  ?{x,empty}         ?1024,
  ?{x,undef}         ?1024
  ?{undef,y}         ?768
  {var:3}            val
  {var:30}           value
  {list}             red,green,blue
  {list*}            red,green,blue
  {keys}             semi,%3B,dot,.,comma,%2C
  {keys*}            semi=%3B,dot=.,comma=%2C

3.2.3. Reserved Expansion: {+var} (Espansione riservata)​

L'espansione riservata, indicata dall'operatore più ("+") per i modelli di Livello 2 e superiori, è identica all'espansione di stringa semplice tranne che i valori sostituiti possono anche contenere tripletti codificati in percentuale e caratteri nell'insieme riservato.

Per ogni variabile definita nell'elenco delle variabili, eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme (unreserved / reserved / pct-encoded). Se più di una variabile ha un valore definito, aggiungere una virgola (",") alla stringa di risultato come separatore tra le espansioni di variabili.

Modello di esempio         Espansione

  {+var}                value
  {+hello}              Hello%20World!
  {+half}               50%25

  {base}index           http%3A%2F%2Fexample.com%2Fhome%2Findex
  {+base}index          http://example.com/home/index
  O{+empty}X            OX
  O{+undef}X            OX

  {+path}/here          /foo/bar/here
  here?ref={+path}      here?ref=/foo/bar
  {+x,hello,y}          1024,Hello%20World!,768
  {+path,x}/here        /foo/bar,1024/here
  {+path:6}/here        /foo/b,1024/here
  {+list}               red,green,blue
  {+list*}              red,green,blue
  {+keys}               semi,;,dot,.,comma,,
  {+keys*}              semi=;,dot=.,comma=,

3.2.4. Fragment Expansion: {#var} (Espansione di frammento)​

L'espansione di frammento, indicata dall'operatore cancelletto ("#") per i modelli di Livello 2 e superiori, è identica all'espansione riservata tranne che un carattere cancelletto (delimitatore di frammento) viene prima aggiunto alla stringa di risultato se una qualsiasi delle variabili è definita.

Modello di esempio    Espansione

  {#var}             #value
  {#hello}           #Hello%20World!
  {#half}            #50%25
  foo{#empty}        foo#
  foo{#undef}        foo
  {#x,hello,y}       #1024,Hello%20World!,768
  {#path,x}/here     #/foo/bar,1024/here
  {#path:6}/here     #/foo/b/here
  {#list}            #red,green,blue
  {#list*}           #red,green,blue
  {#keys}            #semi,;,dot,.,comma,,
  {#keys*}           #semi=;,dot=.,comma=,

3.2.5. Label Expansion with Dot-Prefix: {.var} (Espansione di etichetta con prefisso punto)​

L'espansione di etichetta, indicata dall'operatore punto (".") per i modelli di Livello 3 e superiori, è utile per descrivere spazi URI con nomi di dominio variabili o selettori di percorso (ad esempio, estensioni di file).

Per ogni variabile definita nell'elenco delle variabili, aggiungere "." alla stringa di risultato e quindi eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.

Poiché "." è nell'insieme non riservato, un valore che contiene un "." ha l'effetto di aggiungere più etichette.

Modello di esempio    Espansione

  {.who}             .fred
  {.who,who}         .fred.fred
  {.half,who}        .50%25.fred
  www{.dom*}         www.example.com
  X{.var}            X.value
  X{.empty}          X.
  X{.undef}          X
  X{.var:3}          X.val
  X{.list}           X.red,green,blue
  X{.list*}          X.red.green.blue
  X{.keys}           X.semi,%3B,dot,.,comma,%2C
  X{.keys*}          X.semi=%3B.dot=..comma=%2C
  X{.empty_keys}     X
  X{.empty_keys*}    X

3.2.6. Path Segment Expansion: {/var} (Espansione di segmento di percorso)​

L'espansione di segmento di percorso, indicata dall'operatore barra ("/") nei modelli di Livello 3 e superiori, è utile per descrivere gerarchie di percorsi URI.

Per ogni variabile definita nell'elenco delle variabili, aggiungere "/" alla stringa di risultato e quindi eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.

Si noti che il processo di espansione per l'espansione di segmento di percorso è identico a quello dell'espansione di etichetta a parte la sostituzione di "/" invece di ".". Tuttavia, a differenza di ".", un "/" è un carattere riservato e sarà codificato in percentuale se trovato in un valore.

Modello di esempio    Espansione

  {/who}             /fred
  {/who,who}         /fred/fred
  {/half,who}        /50%25/fred
  {/who,dub}         /fred/me%2Ftoo
  {/var}             /value
  {/var,empty}       /value/
  {/var,undef}       /value
  {/var,x}/here      /value/1024/here
  {/var:1,var}       /v/value
  {/list}            /red,green,blue
  {/list*}           /red/green/blue
  {/list*,path:4}    /red/green/blue/%2Ffoo
  {/keys}            /semi,%3B,dot,.,comma,%2C
  {/keys*}           /semi=%3B/dot=./comma=%2C

3.2.7. Path-Style Parameter Expansion: {;var} (Espansione di parametro in stile percorso)​

L'espansione di parametro in stile percorso, indicata dall'operatore punto e virgola (";") nei modelli di Livello 3 e superiori, è utile per descrivere parametri di percorso URI, come "path;property" o "path;name=value".

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere ";" alla stringa di risultato;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, allora:
    • aggiungere il nome della variabile (codificato come se fosse una stringa letterale) alla stringa di risultato;
    • se il valore della variabile non è vuoto, aggiungere "=" alla stringa di risultato;
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {;who}             ;who=fred
  {;half}            ;half=50%25
  {;empty}           ;empty
  {;v,empty,who}     ;v=6;empty;who=fred
  {;v,bar,who}       ;v=6;who=fred
  {;x,y}             ;x=1024;y=768
  {;x,y,empty}       ;x=1024;y=768;empty
  {;x,y,undef}       ;x=1024;y=768
  {;hello:5}         ;hello=Hello
  {;list}            ;list=red,green,blue
  {;list*}           ;list=red;list=green;list=blue
  {;keys}            ;keys=semi,%3B,dot,.,comma,%2C
  {;keys*}           ;semi=%3B;dot=.;comma=%2C

3.2.8. Form-Style Query Expansion: {?var} (Espansione di query in stile modulo)​

L'espansione di query in stile modulo, indicata dall'operatore punto interrogativo ("?") nei modelli di Livello 3 e superiori, è utile per descrivere un intero componente di query opzionale.

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere "?" alla stringa di risultato se questo è il primo valore definito o aggiungere "&" successivamente;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, aggiungere il nome della variabile (codificato come se fosse una stringa letterale) e un carattere uguale ("=") alla stringa di risultato; e,
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {?who}             ?who=fred
  {?half}            ?half=50%25
  {?x,y}             ?x=1024&y=768
  {?x,y,empty}       ?x=1024&y=768&empty=
  {?x,y,undef}       ?x=1024&y=768
  {?var:3}           ?var=val
  {?list}            ?list=red,green,blue
  {?list*}           ?list=red&list=green&list=blue
  {?keys}            ?keys=semi,%3B,dot,.,comma,%2C
  {?keys*}           ?semi=%3B&dot=.&comma=%2C

3.2.9. Form-Style Query Continuation: {&var} (Continuazione di query in stile modulo)​

La continuazione di query in stile modulo, indicata dall'operatore ampersand ("&") nei modelli di Livello 3 e superiori, è utile per descrivere coppie opzionali &name=value in un modello che contiene già un componente di query letterale con parametri fissi.

Per ogni variabile definita nell'elenco delle variabili:

  • aggiungere "&" alla stringa di risultato;
  • se la variabile ha un valore di stringa semplice o non viene fornito alcun modificatore di esplosione, aggiungere il nome della variabile (codificato come se fosse una stringa letterale) e un carattere uguale ("=") alla stringa di risultato; e,
  • eseguire l'espansione di variabile, come definito nella Sezione 3.2.1, con i caratteri consentiti che sono quelli nell'insieme non riservato.
Modello di esempio    Espansione

  {&who}             &who=fred
  {&half}            &half=50%25
  ?fixed=yes{&x}     ?fixed=yes&x=1024
  {&x,y,empty}       &x=1024&y=768&empty=
  {&x,y,undef}       &x=1024&y=768

  {&var:3}           &var=val
  {&list}            &list=red,green,blue
  {&list*}           &list=red&list=green&list=blue
  {&keys}            &keys=semi,%3B,dot,.,comma,%2C
  {&keys*}           &semi=%3B&dot=.&comma=%2C

4. Security Considerations (Considerazioni sulla sicurezza)​

Un modello URI non contiene contenuto attivo o eseguibile. Tuttavia, potrebbe essere possibile creare URI imprevisti se un attaccante ottiene il controllo del modello o dei valori delle variabili all'interno di un'espressione che consente caratteri riservati nell'espansione. In entrambi i casi, le considerazioni sulla sicurezza sono determinate in gran parte da chi fornisce il modello, chi fornisce i valori da utilizzare per le variabili all'interno del modello, in quale contesto di esecuzione si verifica l'espansione (client o server) e dove vengono utilizzati gli URI risultanti.

Questa specifica non limita dove possono essere utilizzati i modelli URI. Le implementazioni attuali esistono all'interno di framework di sviluppo lato server e all'interno di JavaScript lato client per collegamenti o moduli calcolati.

All'interno dei framework, i modelli di solito fungono da guide per indicare dove i dati potrebbero verificarsi in URI successivi (al momento della richiesta) nelle richieste client. Pertanto, le preoccupazioni sulla sicurezza non riguardano i modelli stessi, ma piuttosto il modo in cui il server estrae ed elabora i dati forniti dall'utente in una normale richiesta Web.

All'interno delle implementazioni lato client, un modello URI ha molte delle stesse proprietà dei moduli HTML, tranne per il fatto che è limitato ai caratteri URI e potrebbe essere incluso nei valori dei campi di intestazione HTTP invece che solo nel contenuto del corpo del messaggio. Si dovrebbe prestare attenzione per garantire che stringhe di riferimento URI potenzialmente pericolose, come quelle che iniziano con "javascript:", non appaiano nell'espansione a meno che sia il modello che i valori non siano forniti da una fonte affidabile.

Altre considerazioni sulla sicurezza sono le stesse di quelle per gli URI, come descritto nella Sezione 7 di [RFC3986].

Appendix A. Implementation Hints (Suggerimenti per l'implementazione)​

Le sezioni normative sull'espansione descrivono ogni operatore con un processo di espansione separato per chiarezza descrittiva. Nelle implementazioni effettive, ci aspettiamo che le espressioni vengano elaborate da sinistra a destra utilizzando un algoritmo comune che ha solo variazioni minori nel processo per operatore. Questa appendice non normativa descrive uno di questi algoritmi.

Inizializzare una stringa di risultato vuota e il suo stato non di errore.

Scansionare il modello e copiare i letterali nella stringa di risultato (come nella Sezione 3.1) fino a quando un'espressione è indicata da un "{", un errore è indicato dalla presenza di un carattere non letterale diverso da "{", o il modello termina. Quando termina, restituire la stringa di risultato e il suo stato di errore o non errore corrente.

  • Se viene trovata un'espressione, scansionare il modello fino al successivo "}" ed estrarre i caratteri tra le parentesi graffe.
  • Se il modello termina prima di un "}", quindi aggiungere il "{" e i caratteri estratti alla stringa di risultato e restituire con uno stato di errore che indica che l'espressione è malformata.

Esaminare il primo carattere dell'espressione estratta per un operatore.

  • Se l'espressione è terminata (cioè è "{}"), viene trovato un operatore sconosciuto o non implementato, o il carattere non è nell'insieme varchar (Sezione 2.3), quindi aggiungere "{", l'espressione estratta e "}" alla stringa di risultato, ricordare che il risultato è in uno stato di errore, e quindi tornare a scansionare il resto del modello.
  • Se viene trovato un operatore conosciuto e implementato, memorizzare l'operatore e saltare al carattere successivo per iniziare la varspec-list.
  • Altrimenti, memorizzare l'operatore come NUL (espansione di stringa semplice).

Utilizzare la seguente tabella di valori per determinare il comportamento di elaborazione per operatore di tipo di espressione. La voce per "first" è la stringa da aggiungere per prima al risultato se una qualsiasi delle variabili dell'espressione è definita. La voce per "sep" è il separatore da aggiungere al risultato prima di qualsiasi seconda (o successiva) espansione di variabile definita. La voce per "named" è un booleano per indicare se l'espansione include il nome della variabile o della chiave quando non viene fornito alcun modificatore di esplosione. La voce per "ifemp" è una stringa da aggiungere al nome se il suo valore corrispondente è vuoto. La voce per "allow" indica quali caratteri consentire non codificati all'interno dell'espansione del valore: (U) significa che qualsiasi carattere non nell'insieme non riservato sarà codificato; (U+R) significa che qualsiasi carattere non nell'unione di (unreserved / reserved / pct-encoding) sarà codificato; e, per entrambi i casi, ogni carattere non consentito viene prima codificato come la sua sequenza di ottetti in UTF-8 e quindi ogni ottetto viene codificato come un tripletto codificato in percentuale.

┌──────────────────────────────────────────────────────────────┐
│          NUL     +      .       /       ;      ?      &      #│
├──────────────────────────────────────────────────────────────┤
│ first │  ""     ""     "."     "/"     ";"    "?"    "&"    "#"│
│ sep   │  ","    ","    "."     "/"     ";"    "&"    "&"    "," │
│ named │ false  false  false   false   true   true   true   false│
│ ifemp │  ""     ""     ""      ""      ""     "="    "="    ""  │
│ allow │   U     U+R     U       U       U      U      U     U+R │
└──────────────────────────────────────────────────────────────┘

Con la tabella sopra in mente, elaborare la lista di variabili come segue:

Per ogni varspec, estrarre un nome di variabile e un modificatore opzionale dall'espressione scansionando la lista di variabili fino a quando viene trovato un carattere non nell'insieme varname o viene raggiunta la fine dell'espressione.

  • Se è la fine dell'espressione e il varname è vuoto, tornare a scansionare il resto del modello.
  • Se non è la fine dell'espressione e l'ultimo carattere trovato indica un modificatore ("" o ":"), ricordare quel modificatore. Se è un'esplosione (""), scansionare il carattere successivo. Se è un prefisso (":"), continuare a scansionare i successivi da uno a quattro caratteri per il max-length rappresentato come intero decimale e quindi, se non è ancora la fine dell'espressione, scansionare il carattere successivo.
  • Se non è la fine dell'espressione e l'ultimo carattere trovato non è una virgola (","), aggiungere "{", l'operatore memorizzato (se presente), il varname e modificatore scansionati, l'espressione rimanente e "}" alla stringa di risultato, ricordare che il risultato è in uno stato di errore, e quindi tornare a scansionare il resto del modello.

Cercare il valore per il nome di variabile scansionato, e quindi

  • Se il varname è sconosciuto o corrisponde a una variabile con un valore indefinito (Sezione 2.3), quindi passare al varspec successivo.
  • Se questa è la prima variabile definita per questa espressione, aggiungere la stringa first per questo tipo di espressione alla stringa di risultato e ricordare che è stato fatto. Altrimenti, aggiungere la stringa sep alla stringa di risultato.
  • Se il valore di questa variabile è una stringa, allora
    • se named è true, aggiungere il varname alla stringa di risultato utilizzando lo stesso processo di codifica dei letterali, e
      • se il valore è vuoto, aggiungere la stringa ifemp alla stringa di risultato e passare al varspec successivo;
      • altrimenti, aggiungere "=" alla stringa di risultato.
    • se è presente un modificatore di prefisso e la lunghezza del prefisso è inferiore alla lunghezza della stringa del valore in numero di caratteri Unicode, aggiungere quel numero di caratteri dall'inizio della stringa del valore alla stringa di risultato, dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow, prestando attenzione a non dividere caratteri multi-ottetto o tripletti codificati in percentuale che rappresentano un singolo punto di codice Unicode;
    • altrimenti, aggiungere il valore alla stringa di risultato dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow.
  • altrimenti se non viene fornito alcun modificatore di esplosione, allora
    • se named è true, aggiungere il varname alla stringa di risultato utilizzando lo stesso processo di codifica dei letterali, e
      • se il valore è vuoto, aggiungere la stringa ifemp alla stringa di risultato e passare al varspec successivo;
      • altrimenti, aggiungere "=" alla stringa di risultato; e
    • se il valore di questa variabile è una lista, aggiungere ogni membro della lista definito alla stringa di risultato, dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow, con una virgola (",") aggiunta al risultato tra ogni membro della lista definito;
    • se il valore di questa variabile è un array associativo o qualsiasi altra forma di struttura accoppiata (name, value), aggiungere ogni coppia con un valore definito alla stringa di risultato come "name,value", dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow, con una virgola (",") aggiunta al risultato tra ogni coppia definita.
  • altrimenti se viene fornito un modificatore di esplosione, allora
    • se named è true, allora per ogni membro della lista definito o coppia dell'array (name, value) con un valore definito, fare:
      • se questo non è il primo membro/valore definito, aggiungere la stringa sep alla stringa di risultato;
      • se questa è una lista, aggiungere il varname alla stringa di risultato utilizzando lo stesso processo di codifica dei letterali;
      • se questa è una coppia, aggiungere il name alla stringa di risultato utilizzando lo stesso processo di codifica dei letterali;
      • se il membro/valore è vuoto, aggiungere la stringa ifemp alla stringa di risultato; altrimenti, aggiungere "=" e il membro/valore alla stringa di risultato, dopo aver codificato in percentuale qualsiasi carattere membro/valore che non è nell'insieme allow.
    • altrimenti se named è false, allora
      • se questa è una lista, aggiungere ogni membro della lista definito alla stringa di risultato, dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow, con la stringa sep aggiunta al risultato tra ogni membro della lista definito.
      • se questo è un array di coppie (name, value), aggiungere ogni coppia con un valore definito alla stringa di risultato come "name=value", dopo aver codificato in percentuale qualsiasi carattere che non è nell'insieme allow, con la stringa sep aggiunta al risultato tra ogni coppia definita.

Quando la lista di variabili per questa espressione è esaurita, tornare a scansionare il resto del modello.