3. Specification of the CBOR Encoding (Spécification de l'Encodage CBOR)
Un élément de données CBOR (Section 2) est encodé vers ou décodé depuis une chaîne d'octets portant un élément de données encodé bien formé comme décrit dans cette section. L'encodage est résumé dans le tableau 7 de l'annexe B, indexé par l'octet initial. Un encodeur DOIT produire uniquement des éléments de données encodés bien formés. Un décodeur NE DOIT PAS retourner un élément de données décodé lorsqu'il rencontre une entrée qui n'est pas un élément de données CBOR encodé bien formé (cela ne nuit pas à l'utilité des outils de diagnostic et de récupération qui pourraient rendre disponibles certaines informations d'un élément de données CBOR encodé endommagé).
L'octet initial de chaque élément de données encodé contient à la fois des informations sur le type majeur (Major Type, les 3 bits de poids fort, décrits dans la Section 3.1) et des informations supplémentaires (Additional Information, les 5 bits de poids faible). À quelques exceptions près, la valeur des informations supplémentaires décrit comment charger un entier non signé "argument":
Moins de 24: La valeur de l'argument est la valeur des informations supplémentaires.
24, 25, 26 ou 27: La valeur de l'argument est contenue dans les 1, 2, 4 ou 8 octets suivants, respectivement, dans l'ordre des octets réseau. Pour le type majeur 7 et les valeurs d'informations supplémentaires 25, 26, 27, ces octets ne sont pas utilisés comme argument entier, mais comme valeur à virgule flottante (voir Section 3.3).
28, 29, 30: Ces valeurs sont réservées pour de futurs ajouts au format CBOR. Dans la version actuelle de CBOR, l'élément encodé n'est pas bien formé.
31: Aucune valeur d'argument n'est dérivée. Si le type majeur est 0, 1 ou 6, l'élément encodé n'est pas bien formé. Pour les types majeurs 2 à 5, la longueur de l'élément est indéfinie, et pour le type majeur 7, l'octet ne constitue pas du tout un élément de données mais termine un élément de longueur indéfinie; tous sont décrits dans la Section 3.2.
L'octet initial et tous les octets supplémentaires consommés pour construire l'argument sont collectivement appelés tête (head) de l'élément de données.
La signification de cet argument dépend du type majeur. Par exemple, dans le type majeur 0, l'argument est la valeur de l'élément de données lui-même (et dans le type majeur 1, la valeur de l'élément de données est calculée à partir de l'argument); dans les types majeurs 2 et 3, il donne la longueur des données de chaîne en octets qui suivent; et dans les types majeurs 4 et 5, il est utilisé pour déterminer le nombre d'éléments de données inclus.
Si la séquence encodée d'octets se termine avant la fin d'un élément de données, cet élément n'est pas bien formé. Si la séquence encodée d'octets contient encore des octets restants après que l'élément encodé le plus externe est décodé, cet encodage n'est pas un seul élément CBOR bien formé. Selon l'application, le décodeur peut soit traiter l'encodage comme non bien formé, soit simplement identifier le début des octets restants à l'application.
Une implémentation de décodeur CBOR peut être basée sur une table de saut avec toutes les 256 valeurs définies pour l'octet initial (Tableau 7). Un décodeur dans une implémentation contrainte peut au lieu utiliser la structure de l'octet initial et des octets suivants pour un code plus compact (voir l'Annexe C pour une impression approximative de ce à quoi cela pourrait ressembler).
3.1. Major Types (Types Majeurs)
Ce qui suit liste les types majeurs et les informations supplémentaires et autres octets associés au type.
Type majeur 0: Un entier non signé dans la plage 0..2^(64)-1 inclus. La valeur de l'élément encodé est l'argument lui-même. Par exemple, l'entier 10 est désigné comme l'octet unique 0b000_01010 (type majeur 0, informations supplémentaires 10). L'entier 500 serait 0b000_11001 (type majeur 0, informations supplémentaires 25) suivi des deux octets 0x01f4, soit 500 en décimal.
Type majeur 1: Un entier négatif dans la plage -2^(64)..-1 inclus. La valeur de l'élément est -1 moins l'argument. Par exemple, l'entier -500 serait 0b001_11001 (type majeur 1, informations supplémentaires 25) suivi des deux octets 0x01f3, soit 499 en décimal.
Type majeur 2: Une chaîne d'octets (Byte String). Le nombre d'octets dans la chaîne est égal à l'argument. Par exemple, une chaîne d'octets dont la longueur est 5 aurait un octet initial de 0b010_00101 (type majeur 2, informations supplémentaires 5 pour la longueur), suivi de 5 octets de contenu binaire.
Type majeur 3: Une chaîne de texte (Text String, Section 2) encodée en UTF-8 [RFC3629]. Le nombre d'octets dans la chaîne est égal à l'argument. Une chaîne contenant une séquence UTF-8 invalide est bien formée mais invalide (Section 1.2). Ce type est fourni pour les systèmes qui doivent interpréter ou afficher du texte lisible par l'homme, et permet la différenciation entre les octets non structurés et le texte qui a un répertoire spécifié (celui d'Unicode) et un encodage (UTF-8).
Type majeur 4: Un tableau (Array) d'éléments de données. Dans d'autres formats, les tableaux sont également appelés listes, séquences ou tuples (une "séquence CBOR" est quelque chose de légèrement différent, voir [RFC8742]). L'argument est le nombre d'éléments de données dans le tableau. Les éléments d'un tableau n'ont pas besoin d'être tous du même type.
Type majeur 5: Une carte (Map) de paires d'éléments de données. Les cartes sont également appelées tables, dictionnaires, hachages ou objets (en JSON). Une carte est composée de paires d'éléments de données, chaque paire consistant en une clé immédiatement suivie d'une valeur. L'argument est le nombre de paires d'éléments de données dans la carte.
Type majeur 6: Un élément de données étiqueté ("étiquette", Tag) dont le numéro d'étiquette, un entier dans la plage 0..2^(64)-1 inclus, est l'argument et dont l'élément de données inclus (contenu d'étiquette, tag content) est l'élément de données encodé unique qui suit la tête. Voir Section 3.4.
Type majeur 7: Nombres à virgule flottante et valeurs simples (Simple Values), ainsi que le code d'arrêt "break". Voir Section 3.3.
Ces huit types majeurs conduisent à un tableau simple montrant lesquelles des 256 valeurs possibles pour l'octet initial d'un élément de données sont utilisées (Tableau 7).
| Type Majeur | Signification | Contenu |
|---|---|---|
| 0 | entier non signé N | - |
| 1 | entier négatif -1-N | - |
| 2 | chaîne d'octets | N octets |
| 3 | chaîne de texte | N octets (texte UTF-8) |
| 4 | tableau | N éléments de données |
| 5 | carte | 2N éléments de données (paires clé/valeur) |
| 6 | étiquette de numéro N | 1 élément de données |
| 7 | simple/flottant | - |
Tableau 1: Aperçu de l'Utilisation de Longueur Définie des Types Majeurs CBOR (N = Argument)
3.2. Indefinite Lengths for Some Major Types (Longueurs Indéfinies pour Certains Types Majeurs)
Quatre éléments CBOR (tableaux, cartes, chaînes d'octets et chaînes de texte) peuvent être encodés avec une longueur indéfinie en utilisant la valeur d'informations supplémentaires 31. Ceci est utile si l'encodage de l'élément doit commencer avant que le nombre d'éléments à l'intérieur du tableau ou de la carte, ou la longueur totale de la chaîne, ne soit connu.
Les tableaux et cartes de longueur indéfinie sont traités différemment des chaînes de longueur indéfinie (chaînes d'octets et chaînes de texte).
3.2.1. The "break" Stop Code (Le Code d'Arrêt "break")
Le code d'arrêt "break" est encodé avec le type majeur 7 et la valeur d'informations supplémentaires 31 (0b111_11111). Ce n'est pas lui-même un élément de données: c'est juste une caractéristique syntaxique pour fermer un élément de longueur indéfinie.
3.3. Floating-Point Numbers and Values with No Content (Nombres à Virgule Flottante et Valeurs sans Contenu)
Le type majeur 7 est pour deux types de données: les nombres à virgule flottante et les "valeurs simples" (Simple Values) qui n'ont pas besoin de contenu. Chaque valeur des informations supplémentaires de 5 bits dans l'octet initial a sa propre signification séparée, comme défini dans le Tableau 3.
| Valeur 5 Bits | Sémantique |
|---|---|
| 0..23 | Valeur simple (valeur 0..23) |
| 24 | Valeur simple (valeur 32..255 dans l'octet suivant) |
| 25 | Flottant Demi-Précision IEEE 754 (16 bits suivent) |
| 26 | Flottant Simple Précision IEEE 754 (32 bits suivent) |
| 27 | Flottant Double Précision IEEE 754 (64 bits suivent) |
| 28-30 | Réservé, pas bien formé dans ce document |
| 31 | Code d'arrêt "break" pour éléments de longueur indéfinie |
Tableau 3: Valeurs pour Informations Supplémentaires dans le Type Majeur 7
| Valeur | Sémantique |
|---|---|
| 0..19 | (non assigné) |
| 20 | false |
| 21 | true |
| 22 | null |
| 23 | undefined |
| 24..31 | (réservé) |
| 32..255 | (non assigné) |
Tableau 4: Valeurs Simples
3.4. Tagging of Items (Étiquetage des Éléments)
Dans CBOR, un élément de données peut être entouré d'une étiquette (tag) pour lui donner une sémantique supplémentaire, identifiée de manière unique par un numéro d'étiquette (tag number). L'étiquette est le type majeur 6, son argument (Section 3) indique le numéro d'étiquette, et elle contient un seul élément de données inclus, le contenu d'étiquette (tag content).
IANA maintient un registre des numéros d'étiquettes comme décrit dans la Section 9.2. Le Tableau 5 fournit une liste des numéros d'étiquettes qui ont été définis dans [RFC7049].
| Étiquette | Élément de Données | Sémantique |
|---|---|---|
| 0 | chaîne de texte | Chaîne date/heure standard |
| 1 | entier ou flottant | Date/heure basée sur l'époque |
| 2 | chaîne d'octets | Grand nombre non signé |
| 3 | chaîne d'octets | Grand nombre négatif |
| 4 | tableau | Fraction décimale |
| 5 | tableau | Grand flottant |
| 21 | (tout) | Conversion attendue vers encodage base64url |
| 22 | (tout) | Conversion attendue vers encodage base64 |
| 23 | (tout) | Conversion attendue vers encodage base16 |
| 24 | chaîne d'octets | Élément de données CBOR encodé |
| 32 | chaîne de texte | URI |
| 33 | chaîne de texte | base64url |
| 34 | chaîne de texte | base64 |
| 36 | chaîne de texte | Message MIME |
| 55799 | (tout) | CBOR auto-décrit |
Tableau 5: Numéros d'Étiquettes Définis dans RFC 7049