6. Notation diagnostique
CBOR est un format d'échange binaire. Pour faciliter la documentation et le débogage, et en particulier pour faciliter la communication entre les entités coopérant au débogage, cette section définit une notation diagnostique simple lisible par un humain. Tout échange réel se fait toujours dans le format binaire.
Notons qu'il s'agit véritablement d'un format de diagnostic ; il n'est pas destiné à être analysé syntaxiquement. Par conséquent, aucune définition formelle (comme en ABNF) n'est donnée dans ce document. (Les implémenteurs à la recherche d'un format textuel pour représenter des éléments de données CBOR dans des fichiers de configuration peuvent aussi vouloir envisager YAML [YAML].)
La notation diagnostique est librement basée sur JSON tel qu'il est défini dans la RFC 4627, en l'étendant là où c'est nécessaire.
La notation emprunte la syntaxe JSON pour les nombres (entiers et à virgule flottante), True (>true<), False (>false<), Null (>null<), les chaînes UTF-8, les tableaux et les tables (les tables sont appelées objets dans JSON ; la notation diagnostique étend JSON ici en autorisant tout élément de données en position de clé). Undefined s'écrit >undefined< comme dans JavaScript. Les nombres à virgule flottante non finis Infinity, -Infinity et NaN s'écrivent exactement comme dans cette phrase (c'est aussi une manière dont ils peuvent être écrits en JavaScript, bien que JSON ne les autorise pas). Un élément étiqueté s'écrit comme un nombre entier pour l'étiquette suivi de l'élément entre parenthèses ; par exemple, une date RFC 3339 (ISO 8601) pourrait être notée comme :
0("2013-03-21T20:04:00Z")
ou le temps relatif équivalent comme
1(1363896240)
Les chaînes d'octets sont notées dans l'un des encodages de base, sans bourrage, entourées de guillemets simples, préfixées par >h< pour base16, >b32< pour base32, >h32< pour base32hex, >b64< pour base64 ou base64url (les encodages réels ne se recouvrent pas, de sorte que la chaîne reste non ambiguë). Par exemple, la chaîne d'octets 0x12345678 pourrait s'écrire h'12345678', b32'CI2FM6A', ou b64'EjRWeA'.
Les valeurs simples non attribuées sont données sous la forme « simple() » avec l'entier approprié entre les parenthèses. Par exemple, « simple(42) » indique le type majeur 7, valeur 42.
6.1. Indicateurs d'encodage
Il est parfois utile d'indiquer dans la notation diagnostique laquelle de plusieurs représentations alternatives a été effectivement utilisée ; par exemple, un élément de données écrit >1.5< par un décodeur diagnostique pourrait avoir été encodé comme un flottant en demi-précision, simple précision ou double précision.
La convention pour les indicateurs d'encodage est que tout ce qui commence par un tiret bas et tous les caractères suivants qui sont alphanumériques ou un tiret bas est un indicateur d'encodage, et peut être ignoré par quiconque ne s'intéresse pas à cette information. Les indicateurs d'encodage sont toujours optionnels.
Un tiret bas unique peut être écrit après l'accolade ouvrante d'une table ou le crochet ouvrant d'un tableau pour indiquer que l'élément de données a été représenté au format de longueur indéfinie. Par exemple, [_ 1, 2] contient un indicateur qu'une représentation de longueur indéfinie a été utilisée pour représenter l'élément de données [1, 2].
Un tiret bas suivi d'un chiffre décimal n indique que l'élément précédent (ou, pour les tableaux et les tables, l'élément commençant par le crochet ou l'accolade précédent) a été encodé avec une valeur d'information additionnelle de 24+n. Par exemple, 1.5_1 est un nombre à virgule flottante en demi-précision, tandis que 1.5_3 est encodé en double précision. Cet indicateur d'encodage n'est pas montré dans l'Appendix A. (Notons que l'indicateur d'encodage « _ » est donc une abréviation de la forme complète « _7 », qui n'est pas utilisée.)
À titre de cas spécial, les chaînes d'octets et les textes de longueur indéfinie peuvent être notés sous la forme (_ h'0123', h'4567') et (_ "foo", "bar").