Aller au contenu principal

3. Structured Data Types (Types de données structurées)

Cette section définit les types abstraits des champs structurés. L'ABNF fourni représente le format de transmission dans les valeurs de champs HTTP.

Aperçu​

  • Il existe trois types de niveau supérieur utilisables pour définir des champs HTTP : Lists (listes)、Dictionaries (dictionnaires) et Items (éléments)

  • Lists et Dictionaries sont des conteneurs ; leurs membres peuvent être des Items ou des Inner Lists (Inner Lists sont elles-mêmes des tableaux d'Items)

  • Items et Inner Lists peuvent tous deux être paramétrés (Parameterized) avec des paires clé-valeur

3.1 Lists (Listes)​

Les Lists sont des tableaux contenant zéro ou plusieurs membres, chaque membre pouvant être un Item (section 3.3) ou une Inner List (section 3.1.1), tous deux pouvant être paramétrés (section 3.1.2).

Syntaxe ABNF​

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

Description du format​

Chaque membre est séparé par une virgule et un espace blanc optionnel.

Exemple​

Example-List: sugar, tea, rum

Champ défini comme liste de Tokens

Liste vide​

Une List vide est représentée en ne sérialisant pas du tout le champ. Cela signifie que les champs définis comme Lists ont une valeur vide par défaut.

Fractionnement multi-lignes​

Les membres des Lists peuvent être fractionnés sur plusieurs lignes dans la même section d'en-tête ou de pied de page (selon [RFC7230] section 3.2.2) ; par exemple, les lignes suivantes sont équivalentes :

Example-List: sugar, tea, rum

Équivalent à :

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

Note : Les membres individuels d'une List ne peuvent pas être fractionnés en toute sécurité entre les lignes ; voir section 4.2 pour plus de détails.

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Lists contenant au moins 1024 membres. Les spécifications de champs peuvent contraindre les types et la cardinalité des valeurs de List individuelles selon les besoins.

3.1.1 Inner Lists (Listes internes)​

Une Inner List est un tableau contenant zéro ou plusieurs Items (section 3.3). Les Items individuels et l'Inner List elle-même peuvent tous deux être paramétrés (section 3.1.2).

Syntaxe ABNF​

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

Description du format​

Les Inner Lists sont entourées de parenthèses, leurs valeurs sont séparées par un ou plusieurs espaces.

Exemple 1 : Inner Lists simples​

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

Champ défini comme liste de listes internes de Strings. Notez que le dernier membre est une Inner List vide.

Exemple 2 : Inner Lists avec paramètres​

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

Champ défini comme liste de listes internes avec paramètres (ayant des paramètres à deux niveaux).

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Inner Lists contenant au moins 256 membres. Les spécifications de champs peuvent contraindre les types et la cardinalité des membres d'Inner List individuels selon les besoins.

3.1.2 Parameters (Paramètres)​

Les Parameters sont un mappage ordonné de paires clé-valeur associées à un Item (section 3.3) ou à une Inner List (section 3.1.1). Les clés sont uniques dans la portée des Parameters dans lesquels elles apparaissent, et les valeurs sont des éléments nus (bare items) (c'est-à-dire qu'elles ne peuvent pas elles-mêmes être paramétrées ; voir section 3.3).

Les implémentations doivent (MUST) fournir un accès aux Parameters par index et par clé. Les spécifications peuvent (MAY) utiliser l'une ou l'autre méthode d'accès.

Syntaxe 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

Description du format​

  • Les paramètres sont ordonnés dans l'ordre de sérialisation
  • Les clés de paramètres ne peuvent pas contenir de lettres majuscules
  • Les paramètres sont séparés de leur Item ou Inner List et des autres paramètres par des points-virgules

Exemple​

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

Règle spéciale pour les paramètres Boolean​

Les paramètres avec une valeur Boolean (voir section 3.3.6) true doivent (MUST) omettre cette valeur lors de la sérialisation.

Exemple :

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

Ici, le paramètre a est true, tandis que le paramètre b est false.

Note : Cette exigence ne s'applique qu'à la sérialisation ; les parseurs doivent toujours traiter correctement les valeurs true apparaissant dans les paramètres.

Exigences d'implémentation​

Les implémentations doivent (MUST) prendre en charge les listes de paramètres avec au moins 256 paramètres. Les spécifications de champs peuvent contraindre la cardinalité des Parameters individuels selon les besoins.

3.2 Dictionaries (Dictionnaires)​

Les Dictionaries sont des mappages ordonnés de membres nommés, où le nom de chaque membre est une clé et la valeur est soit un Item (section 3.3), soit un tableau d'Inner Lists (section 3.1.1). Les deux peuvent être paramétrés (section 3.1.2).

Syntaxe 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

Description du format​

  • Les membres sont séparés par des virgules et des espaces blancs optionnels
  • Les noms de membres doivent être uniques dans ce Dictionary
  • Si des noms de membres en double sont parsés, seul le dernier est utilisé

Exemple​

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

Champ défini comme Dictionary avec des valeurs Strings et Byte Sequences.

Règle spéciale pour les valeurs Boolean​

Les membres de Dictionary avec une valeur Boolean true (section 3.3.6) sont sérialisés en omettant le "=" et sa valeur.

Exemple :

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

Ici, la valeur de b est Boolean true, et la valeur de c est également Boolean true avec un paramètre foo.

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Dictionaries contenant au moins 1024 membres. Les spécifications de champs peuvent contraindre les types et la cardinalité des valeurs de Dictionary individuelles selon les besoins.

3.3 Items (Éléments)​

Un Item est composé d'un élément nu (bare item, sections 3.3.1 à 3.3.6) et de paramètres optionnels (section 3.1.2).

Syntaxe ABNF​

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

3.3.1 Integers (Entiers)​

Les Integers sont des nombres avec une plage de -999,999,999,999,999 à 999,999,999,999,999 (inclus).

Syntaxe ABNF​

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

Exemples​

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

Exigences d'implémentation​

Les implémentations doivent (MUST) prendre en charge tous les Integers dans la plage spécifiée.

3.3.2 Decimals (Décimaux)​

Les Decimals sont des nombres avec jusqu'à 3 chiffres significatifs à droite du point décimal.

Syntaxe ABNF​

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

Exemples​

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

Exigences d'implémentation​

  • À gauche du point décimal : maximum 12 chiffres significatifs
  • À droite du point décimal : maximum 3 chiffres significatifs

3.3.3 Strings (Chaînes)​

Les Strings sont des séquences de caractères ASCII imprimables (VCHAR, SP).

Syntaxe ABNF​

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

Échappement​

  • Seuls le backslash (\) et les guillemets doubles (") peuvent être échappés
  • Un backslash après ces autres caractères doit provoquer un échec du parsing

Exemples​

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

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Strings d'au moins 1024 caractères (après décodage).

3.3.4 Tokens (Jetons)​

Les Tokens sont de courts mots textuels. Leur modèle abstrait est identique à leur représentation dans la sérialisation de valeur de champ HTTP.

Syntaxe ABNF​

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

Exemples​

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

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Tokens d'au moins 512 caractères.

3.3.5 Byte Sequences (Séquences d'octets)​

Les Byte Sequences peuvent être transmises dans des champs structurés.

Syntaxe ABNF​

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

Exemple​

Example-ByteSequence: :cHJldGVuZCB0aGlzIGlzIGJpbmFyeSBjb250ZW50Lg==:

Exigences d'implémentation​

Les parseurs doivent (MUST) prendre en charge les Byte Sequences d'au moins 16384 octets après décodage.

3.3.6 Booleans (Booléens)​

Les valeurs Boolean peuvent être transmises dans des champs structurés.

Syntaxe ABNF​

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

Exemples​

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

Description du format​

  • Les Booleans sont indiqués par un caractère "?" initial
  • "1" indique true
  • "0" indique false

Comportement spécial dans Dictionary et Parameters​

Dans les valeurs Dictionary (section 3.2) et Parameter (section 3.1.2), Boolean true est indiqué en omettant la valeur.

Résumé des types de données​

TypePlage/FormatExemple
Integer-999,999,999,999,999 à 999,999,999,999,99942, -100
Decimal12 chiffres entiers, 3 chiffres décimaux4.5, -0.123
StringCaractères ASCII imprimables, max 1024 caractères"hello world"
TokenAlphanumérique et symboles, max 512 caractèresfoo123/456
Byte SequenceEncodage Base64, max 16384 octets:SGVsbG8=:
Booleantrue/false?1, ?0
Dernière mise à jour le