Passa al contenuto principale

3. Structured Data Types (Tipi di dati strutturati)

Questa sezione definisce i tipi astratti dei campi strutturati. L'ABNF fornita rappresenta il formato di trasmissione nei valori dei campi HTTP.

Panoramica​

  • Ci sono tre tipi di livello superiore utilizzabili per definire campi HTTP: Lists (liste), Dictionaries (dizionari) e Items (elementi)

  • Lists e Dictionaries sono contenitori; i loro membri possono essere Items o Inner Lists (le Inner Lists sono esse stesse array di Items)

  • Sia Items che Inner Lists possono essere parametrizzati (Parameterized) con coppie chiave-valore

3.1 Lists (Liste)​

Le Lists sono array contenenti zero o più membri, dove ogni membro può essere un Item (sezione 3.3) o una Inner List (sezione 3.1.1), entrambi possono essere parametrizzati (sezione 3.1.2).

Sintassi ABNF​

sf-list       = list-member *( OWS "," OWS list-member )
list-member   = sf-item / inner-list

Descrizione del formato​

Ogni membro è separato da una virgola e spazi bianchi opzionali.

Esempio​

Example-List: sugar, tea, rum

Campo definito come lista di Token

Lista vuota​

Una List vuota è rappresentata non serializzando affatto il campo. Ciò significa che i campi definiti come Lists hanno un valore vuoto per impostazione predefinita.

Suddivisione su più righe​

I membri delle Lists possono essere suddivisi su più righe nella stessa sezione di intestazione o coda (secondo [RFC7230] sezione 3.2.2); ad esempio, i seguenti sono equivalenti:

Example-List: sugar, tea, rum

Equivalente a:

Example-List: sugar, tea
Example-List: rum

Nota: I singoli membri di una List non possono essere suddivisi in modo sicuro tra le righe; vedere la sezione 4.2 per i dettagli.

Requisiti di implementazione​

I parser devono (MUST) supportare Lists contenenti almeno 1024 membri. Le specifiche dei campi possono vincolare i tipi e la cardinalità dei valori di List individuali secondo necessità.

3.1.1 Inner Lists (Liste interne)​

Una Inner List è un array contenente zero o più Items (sezione 3.3). Sia gli Items individuali che l'Inner List stessa possono essere parametrizzati (sezione 3.1.2).

Sintassi ABNF​

inner-list    = "(" *SP [ sf-item *( 1*SP sf-item ) *SP ] ")"
                parameters

Descrizione del formato​

Le Inner Lists sono circondate da parentesi, i loro valori sono separati da uno o più spazi.

Esempio 1: Inner Lists semplici​

Example-List: ("foo" "bar"), ("baz"), ("bat" "one"), ()

Campo definito come lista di liste interne di Strings. Si noti che l'ultimo membro è una Inner List vuota.

Esempio 2: Inner Lists con parametri​

Example-List: ("foo"; a=1;b=2);lvl=5, ("bar" "baz");lvl=1

Campo definito come lista di liste interne con parametri (aventi parametri a due livelli).

Requisiti di implementazione​

I parser devono (MUST) supportare Inner Lists contenenti almeno 256 membri. Le specifiche dei campi possono vincolare i tipi e la cardinalità dei membri di Inner List individuali secondo necessità.

3.1.2 Parameters (Parametri)​

I Parameters sono una mappatura ordinata di coppie chiave-valore associate a un Item (sezione 3.3) o a una Inner List (sezione 3.1.1). Le chiavi sono univoche nell'ambito dei Parameters in cui appaiono, e i valori sono elementi nudi (bare items) (cioè non possono essere essi stessi parametrizzati; vedere sezione 3.3).

Le implementazioni devono (MUST) fornire accesso ai Parameters sia per indice che per chiave. Le specifiche possono (MAY) utilizzare uno dei due metodi di accesso.

Sintassi ABNF​

parameters    = *( ";" *SP parameter )
parameter     = param-key [ "=" param-value ]
param-key     = key
key           = ( lcalpha / "*" )
                *( lcalpha / DIGIT / "_" / "-" / "." / "*" )
lcalpha       = %x61-7A ; a-z
param-value   = bare-item

Descrizione del formato​

  • I parametri sono ordinati nell'ordine di serializzazione
  • Le chiavi dei parametri non possono contenere lettere maiuscole
  • I parametri sono separati dal loro Item o Inner List e dagli altri parametri da punti e virgola

Esempio​

Example-List: abc;a=1;b=2; cde_456, (ghi;jk=4 l);q="9";r=w

Regola speciale per i parametri Boolean​

I parametri con un valore Boolean (vedere sezione 3.3.6) true devono (MUST) omettere quel valore durante la serializzazione.

Esempio:

Example-Integer: 1; a; b=?0

Qui, il parametro a è true, mentre il parametro b è false.

Nota: Questo requisito si applica solo alla serializzazione; i parser devono comunque gestire correttamente i valori true che appaiono nei parametri.

Requisiti di implementazione​

Le implementazioni devono (MUST) supportare elenchi di parametri con almeno 256 parametri. Le specifiche dei campi possono vincolare la cardinalità dei Parameters individuali secondo necessità.

3.2 Dictionaries (Dizionari)​

I Dictionaries sono mappature ordinate di membri denominati, dove il nome di ogni membro è una chiave e il valore è un Item (sezione 3.3) o un array di Inner Lists (sezione 3.1.1). Entrambi possono essere parametrizzati (sezione 3.1.2).

Sintassi ABNF​

sf-dictionary  = dict-member *( OWS "," OWS dict-member )
dict-member    = member-key ( parameters / ( "=" member-value ))
member-key     = key
member-value   = sf-item / inner-list

Descrizione del formato​

  • I membri sono separati da virgole e spazi bianchi opzionali
  • I nomi dei membri devono essere univoci all'interno di quel Dictionary
  • Se vengono parsati nomi di membri duplicati, viene utilizzato solo l'ultimo

Esempio​

Example-Dict: en="Applepie", da=:w4ZibGV0w6ZydGU=:

Campo definito come Dictionary con valori Strings e Byte Sequences.

Regola speciale per i valori Boolean​

I membri di Dictionary con un valore Boolean true (sezione 3.3.6) sono serializzati omettendo il "=" e il suo valore.

Esempio:

Example-Dict: a=?0, b, c; foo=bar

Qui, il valore di b è Boolean true, e il valore di c è anch'esso Boolean true con un parametro foo.

Requisiti di implementazione​

I parser devono (MUST) supportare Dictionaries contenenti almeno 1024 membri. Le specifiche dei campi possono vincolare i tipi e la cardinalità dei valori di Dictionary individuali secondo necessità.

3.3 Items (Elementi)​

Un Item è composto da un elemento nudo (bare item, sezioni 3.3.1 a 3.3.6) e parametri opzionali (sezione 3.1.2).

Sintassi ABNF​

sf-item    = bare-item parameters
bare-item  = sf-integer / sf-decimal / sf-string / sf-token
             / sf-binary / sf-boolean

3.3.1 Integers (Interi)​

Gli Integers sono numeri con un intervallo da -999,999,999,999,999 a 999,999,999,999,999 (inclusi).

Sintassi ABNF​

sf-integer = ["-"] 1*15DIGIT

Esempi​

Example-Integer: 42
Example-Integer: -42
Example-Integer: 0

Requisiti di implementazione​

Le implementazioni devono (MUST) supportare tutti gli Integers nell'intervallo specificato.

3.3.2 Decimals (Decimali)​

I Decimals sono numeri con fino a 3 cifre significative a destra del punto decimale.

Sintassi ABNF​

sf-decimal  = ["-"] 1*12DIGIT "." 1*3DIGIT

Esempi​

Example-Decimal: 4.5
Example-Decimal: -4.5
Example-Decimal: 123.456

Requisiti di implementazione​

  • A sinistra del punto decimale: massimo 12 cifre significative
  • A destra del punto decimale: massimo 3 cifre significative

3.3.3 Strings (Stringhe)​

Le Strings sono sequenze di caratteri ASCII stampabili (VCHAR, SP).

Sintassi ABNF​

sf-string = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E / "\" ( DQUOTE / "\" )) DQUOTE

Escape​

  • Solo il backslash (\) e le virgolette doppie (") possono essere escape
  • Un backslash dopo questi altri caratteri deve causare un fallimento del parsing

Esempi​

Example-String: "hello world"
Example-String: "say \"hi\""

Requisiti di implementazione​

I parser devono (MUST) supportare Strings di almeno 1024 caratteri (dopo la decodifica).

3.3.4 Tokens (Token)​

I Tokens sono brevi parole testuali. Il loro modello astratto è identico alla loro rappresentazione nella serializzazione del valore del campo HTTP.

Sintassi ABNF​

sf-token = ( ALPHA / "*" ) *( tchar / ":" / "/" )

Esempi​

Example-Token: foo123/456
Example-Token: *

Requisiti di implementazione​

I parser devono (MUST) supportare Tokens di almeno 512 caratteri.

3.3.5 Byte Sequences (Sequenze di byte)​

Le Byte Sequences possono essere trasmesse in campi strutturati.

Sintassi ABNF​

sf-binary = ":" *(base64) ":"
base64    = ALPHA / DIGIT / "+" / "/" / "="

Esempio​

Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

Requisiti di implementazione​

I parser devono (MUST) supportare Byte Sequences di almeno 16384 ottetti dopo la decodifica.

3.3.6 Booleans (Booleani)​

I valori Boolean possono essere trasmessi in campi strutturati.

Sintassi ABNF​

sf-boolean = "?" boolean
boolean    = "0" / "1"

Esempi​

Example-Boolean: ?1
Example-Boolean: ?0

Descrizione del formato​

  • I Booleans sono indicati da un carattere "?" iniziale
  • "1" indica true
  • "0" indica false

Comportamento speciale in Dictionary e Parameters​

Nei valori Dictionary (sezione 3.2) e Parameter (sezione 3.1.2), Boolean true è indicato omettendo il valore.

Riepilogo dei tipi di dati​

TipoIntervallo/FormatoEsempio
Integer-999,999,999,999,999 a 999,999,999,999,99942, -100
Decimal12 cifre intere, 3 cifre decimali4.5, -0.123
StringCaratteri ASCII stampabili, max 1024 caratteri"hello world"
TokenAlfanumerico e simboli, max 512 caratterifoo123/456
Byte SequenceCodifica Base64, max 16384 ottetti:SGVsbG8=:
Booleantrue/false?1, ?0