Passa al contenuto principale

2. Defining New Structured Fields

Per specificare un campo HTTP come Structured Field, l'autore deve:

Passi Obbligatori​

1. Fare riferimento normativo a questa specifica​

I destinatari e i produttori del campo devono sapere che si applicano i requisiti di questo documento.

Esempio di testo di riferimento:
"Questo campo e uno Structured Field [RFC8941]."

2. Identificare il tipo di campo​

Determinare se il campo e:

  • Structured Header: puo essere usato solo nella sezione header, il caso comune
  • Structured Trailer: puo essere usato solo nella sezione trailer
  • Structured Field: puo essere usato in entrambe

3. Specificare il tipo di dato di primo livello​

Scegliere uno dei seguenti tipi:

  • List - Sezione 3.1
  • Dictionary - Sezione 3.2
  • Item - Sezione 3.3

4. Definire la semantica del valore del campo​

Spiegare il significato e lo scopo del campo.

5. Specificare vincoli aggiuntivi​

Definire i vincoli sul valore del campo e le conseguenze della loro violazione.

Modello di Definizione​

Di solito, una definizione di campo specifica il tipo di primo livello, List, Dictionary o Item, e poi definisce i tipi ammessi e i vincoli applicabili.

Esempi di vincoli​

Campo di tipo List:

  • Tutti i membri sono Integer
  • Oppure sono ammessi tipi misti

Campo di tipo Item:

  • Sono ammesse solo String
  • Ed e ammessa solo una stringa che inizi con la lettera "Q"
  • Oppure sono ammesse solo stringhe minuscole

Nota importante: le Inner Lists, Sezione 3.1.1, sono valide solo quando la definizione del campo le consente esplicitamente.

Gestione degli Errori​

Quando il parsing fallisce, l'intero campo viene ignorato, vedere la Sezione 4.2; nella maggior parte dei casi, la violazione di vincoli specifici del campo dovrebbe produrre lo stesso effetto.

Comportamento predefinito​

Scenario: il campo e definito come Item e deve essere Integer, ma viene ricevuta una String

Comportamento predefinito: ignorare il campo

Se serve una gestione degli errori diversa, deve essere specificata esplicitamente.

Estensibilita​

Parameters - meccanismo di estensione​

Sia Item sia Inner List consentono Parameters come meccanismo di estensione; questo significa che in futuro i valori possono essere estesi per contenere più informazioni.

Per mantenere la compatibilita in avanti: le specifiche dei campi sono discouraged dal definire la presenza di parametri non riconosciuti come condizione di errore.

"Grease" Parameters​

Per assicurare ulteriormente l'estensibilita futura e incoraggiare i consumatori a usare implementazioni complete del parser, una definizione di campo puo specificare che i mittenti aggiungano parametri "grease".

Strategia di esempio:
--------------------
Una specifica puo stabilire che tutti i parametri conformi allo schema di definizione
siano riservati a questo scopo,
e poi incoraggiarne l'invio in alcune richieste.

Scopo:
------
Questo aiuta a scoraggiare i destinatari dallo scrivere parser
che non considerano i parametri.

Compatibilita in avanti dei Dictionary​

Anche le specifiche che usano Dictionary possono ottenere compatibilita in avanti richiedendo che siano ignorati i membri sconosciuti, insieme ai loro valori e tipi associati. Specifiche successive possono aggiungere altri membri e specificare vincoli appropriati per essi.

Un'estensione di uno Structured Field puo quindi richiedere che, se un destinatario che comprende l'estensione rileva che un valore da essa definito non soddisfa i vincoli, l'intero valore del campo sia ignorato.

Regole sui Vincoli​

Non si possono allentare i requisiti​

Le definizioni dei campi cannot allentare i requisiti di questa specifica, perché ciò ostacolerebbe l'elaborazione da parte di software generico; possono solo aggiungere vincoli ulteriori.

Esempi di vincoli che possono essere aggiunti:

  • Intervalli numerici per Integer e Decimal
  • Formati per String e Token
  • Tipi ammessi nei valori di Dictionary
  • Numero di Item in una List

Applicazione all'intero campo​

Le definizioni dei campi possono applicare questa specifica solo all'intero valore del campo, non a una sua parte.

Limiti Implementativi​

Valori minimi​

Questa specifica definisce valori minimi per lunghezze o quantità delle varie strutture che le implementazioni devono supportare.

Valori massimi​

Nella maggior parte dei casi non specifica dimensioni massime, ma gli autori devono sapere che le implementazioni HTTP impongono vari limiti su:

  • Dimensione di un singolo campo
  • Numero totale di campi
  • Dimensione dell'intera sezione header o trailer

Convenzioni di Denominazione​

Le specifiche possono chiamare il nome di un campo:

  • "structured header name"
  • "structured trailer name"
  • "structured field name"

Il valore di un campo puo essere chiamato:

  • "structured header value"
  • "structured trailer value"
  • "structured field value"

Uso di ABNF​

Le definizioni dei campi sono encouraged a usare le regole ABNF di questa specifica che iniziano con "sf-"; le altre regole di questa specifica non sono pensate per essere usate nelle definizioni dei campi.

Esempio Completo: Header Foo-Example​

42.  Foo-Example Header
  
The Foo-Example HTTP header field conveys information about how
much Foo the message has.
  
Foo-Example is an Item Structured Header [RFC8941].  Its value
MUST be an Integer (Section 3.3.1 of [RFC8941]).  Its ABNF is:
  
      Foo-Example = sf-integer
  
Its value indicates the amount of Foo in the message, and it MUST
be between 0 and 10, inclusive; other values MUST cause the entire
header field to be ignored.
  
The following parameter is defined:
*  A parameter whose key is "foourl", and whose value is a String
   (Section 3.3.3 of [RFC8941]), conveying the Foo URL for the
   message.  See below for processing requirements.
  
"foourl" contains a URI-reference (Section 4.1 of [RFC3986]).  If
its value is not a valid URI-reference, the entire header field
MUST be ignored.  If its value is a relative reference
(Section 4.2 of [RFC3986]), it MUST be resolved (Section 5 of
[RFC3986]) before being used.
  
For example:
  
      Foo-Example: 2; foourl="https://foo.example.com/"

Analisi dell'esempio​

Foo-Example: 2; foourl="https://foo.example.com/"

Parsing:

  • Tipo: Item (Integer)
  • Valore: 2
  • Parametro: foourl="https://foo.example.com/"

Validazione:

  1. Il valore e Integer
  2. Il valore e nell'intervallo 0-10
  3. Il parametro foourl e presente
  4. foourl e un URI valido

Se il valore e 15:

Foo-Example: 15; foourl="https://foo.example.com/"

Risultato: l'intero campo viene ignorato, perché viola il vincolo dell'intervallo 0-10.

Checklist di Definizione​

Quando si definisce un nuovo Structured Field, assicurarsi di:

  • Fare riferimento normativo a RFC 8941
  • Dichiarare chiaramente se il campo e Header, Trailer o Field
  • Specificare il tipo di primo livello, List, Dictionary o Item
  • Definire la semantica del campo
  • Specificare i vincoli di tipo
  • Definire vincoli sull'intervallo dei valori, se applicabile
  • Descrivere i parametri, se presenti
  • Definire la gestione degli errori, se diversa dal comportamento predefinito
  • Considerare la compatibilita in avanti
  • Fornire esempi

Punti Chiave​

  1. Cinque passi obbligatori: riferimento, tipo, tipo dati, semantica, vincoli
  2. Comportamento predefinito rigoroso: fallimento del parsing = campo ignorato
  3. Estensibilita prima di tutto: incoraggiare parametri e ignorare membri sconosciuti
  4. Solo aggiunta di vincoli: non allentare i requisiti di RFC 8941
  5. Campo intero: la specifica si applica all'intero valore del campo
  6. Limiti implementativi: considerare i limiti di dimensione delle implementazioni HTTP