Aller au contenu principal

2. Définition de nouveaux champs structurés (Defining New Structured Fields)

Pour spécifier un champ HTTP comme champ structuré, son auteur doit :

Étapes obligatoires​

1. Référencer normativement cette spécification​

Les destinataires et les générateurs du champ doivent savoir que les exigences de ce document s'appliquent.

Exemple de texte de référence :
"Ce champ est un champ structuré [RFC8941]."

2. Identifier le type de champ​

Déterminer si le champ est :

  • Structured Header (en-tête structuré) : utilisable uniquement dans la section d'en-tête (cas courant)
  • Structured Trailer (pied de page structuré) : utilisable uniquement dans la section de pied de page
  • Structured Field (champ structuré) : utilisable dans les deux

3. Spécifier le type de données de niveau supérieur​

Choisir l'un des types suivants :

  • List (liste) - section 3.1
  • Dictionary (dictionnaire) - section 3.2
  • Item (élément) - section 3.3

4. Définir la sémantique de la valeur du champ​

Expliquer la signification et l'utilisation du champ.

5. Spécifier les contraintes supplémentaires​

Définir les contraintes sur les valeurs du champ et les conséquences en cas de violation de ces contraintes.

Modèles de définition​

En général, une définition de champ spécifie le type de niveau supérieur (List, Dictionary ou Item), puis définit les types autorisés et les contraintes.

Exemples de contraintes​

Champ de type List :

  • Tous les membres sont des Integer
  • Ou types mixtes

Champ de type Item :

  • Uniquement des String
  • Et uniquement des chaînes commençant par la lettre « Q »
  • Ou uniquement des chaînes en minuscules

Note importante : Les Inner Lists (listes internes, section 3.1.1) ne sont valides que si la définition du champ les autorise explicitement.

Gestion des erreurs​

Lorsque l'analyse échoue, le champ entier est ignoré (voir section 4.2) ; dans la plupart des cas, la violation des contraintes spécifiques au champ devrait produire le même effet.

Comportement par défaut​

Scénario : le champ est défini comme Item et doit être un Integer, mais une String est reçue

Comportement par défaut : ignorer le champ

Si un traitement d'erreur différent est nécessaire, il doit être explicitement spécifié.

Extensibilité​

Parameters (paramètres) - mécanisme d'extension​

Les Item et les Inner List autorisent tous deux des paramètres comme mécanisme d'extensibilité ; cela signifie que les valeurs peuvent être étendues à l'avenir pour accueillir plus d'informations.

Pour maintenir la compatibilité ascendante : les spécifications de champs déconseillent (discouraged) de définir la présence de paramètres non reconnus comme une condition d'erreur.

Paramètres « Grease » (paramètres de graissage)​

Pour assurer davantage l'extensibilité future et encourager les consommateurs à utiliser des implémentations d'analyseur complètes, les définitions de champs peuvent spécifier que les expéditeurs ajoutent des paramètres « grease ».

Exemple de stratégie :
---------
La spécification peut stipuler que tous les paramètres conformes au modèle de définition
sont réservés à cet usage, puis encourager leur envoi dans certaines requêtes.

Objectif :
----
Cela aide à décourager les destinataires d'écrire des analyseurs qui ne tiennent pas compte des paramètres.

Compatibilité ascendante des Dictionary​

Les spécifications utilisant des Dictionary peuvent également assurer la compatibilité ascendante en exigeant que la présence de membres inconnus et leurs valeurs et types associés soient ignorés. Les spécifications ultérieures peuvent ajouter des membres supplémentaires et spécifier les contraintes appropriées.

Une extension de champ structuré peut alors exiger que : si un destinataire comprenant l'extension trouve que les valeurs définies ne satisfont pas les contraintes, il ignore la valeur entière du champ.

Règles de contraintes​

Impossible d'assouplir les exigences​

Les définitions de champs ne peuvent pas (cannot) assouplir les exigences de cette spécification, car cela entraverait le traitement par des logiciels génériques ; elles **ne peuvent qu'**ajouter des contraintes supplémentaires.

Exemples de contraintes pouvant être ajoutées :

  • Plages de valeurs numériques pour Integer et Decimal
  • Format pour String et Token
  • Types autorisés dans les valeurs de Dictionary
  • Nombre d'Item dans une List

Application à l'ensemble du champ​

Les définitions de champs ne peuvent utiliser cette spécification que pour la valeur entière du champ, et non pour une partie de celle-ci.

Limites d'implémentation​

Valeurs minimales​

Cette spécification définit des valeurs minimales pour la longueur ou le nombre de diverses structures prises en charge par les implémentations.

Valeurs maximales​

Dans la plupart des cas, elle ne spécifie pas de taille maximale, mais les auteurs doivent être conscients que les implémentations HTTP imposent diverses limites sur :

  • La taille d'un champ individuel
  • Le nombre total de champs
  • La taille totale de la section d'en-tête ou de pied de page

Conventions de nommage​

Les spécifications peuvent désigner les noms de champs comme :

  • « structured header name (nom d'en-tête structuré) »
  • « structured trailer name (nom de pied de page structuré) »
  • « structured field name (nom de champ structuré) »

Les valeurs de champs peuvent être désignées comme :

  • « structured header value (valeur d'en-tête structurée) »
  • « structured trailer value (valeur de pied de page structurée) »
  • « structured field value (valeur de champ structurée) »

Utilisation de l'ABNF​

Les définitions de champs sont encouragées (encouraged) à utiliser les règles ABNF commençant par « sf- » dans cette spécification ; les autres règles de cette spécification ne sont pas destinées à être utilisées dans les définitions de champs.

Exemple complet : en-tête 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/"

Analyse de l'exemple​

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

Analyse :

  • Type : Item (Integer)
  • Valeur : 2
  • Paramètre : foourl="https://foo.example.com/"

Validation :

  1. La valeur est un Integer ✓
  2. La valeur est dans la plage 0-10 ✓
  3. Le paramètre foourl est présent ✓
  4. foourl est un URI valide ✓

Si la valeur est 15 :

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

Résultat : le champ entier est ignoré (violation de la contrainte de plage 0-10)

Liste de vérification (Checklist)​

Lors de la définition d'un nouveau champ structuré, s'assurer de :

  • Référencer normativement la RFC 8941
  • Préciser si le champ est Header/Trailer/Field
  • Spécifier le type de niveau supérieur (List/Dictionary/Item)
  • Définir la sémantique du champ
  • Spécifier les contraintes de type
  • Définir les contraintes de plage de valeurs (si applicable)
  • Décrire les paramètres (si présents)
  • Définir la gestion des erreurs (si différente du comportement par défaut)
  • Considérer la compatibilité ascendante
  • Fournir des exemples

Points clés (Key Takeaways)​

  1. Cinq étapes obligatoires : référence, type, type de données, sémantique, contraintes
  2. Comportement par défaut strict : échec d'analyse = ignorer le champ
  3. Extensibilité en priorité : encourager l'utilisation de paramètres et ignorer les membres inconnus
  4. Uniquement ajouter des contraintes : impossible d'assouplir les exigences de la RFC 8941
  5. Champ complet : la spécification s'applique à la valeur entière du champ
  6. Limites d'implémentation : tenir compte des limites de taille des implémentations HTTP
Dernière mise à jour le