6. Diagnostische Notation
CBOR ist ein binäres Austauschformat. Um die Dokumentation und das Debuggen zu erleichtern und insbesondere die Kommunikation zwischen Einheiten, die beim Debuggen zusammenarbeiten, zu unterstützen, definiert dieser Abschnitt eine einfache, für Menschen lesbare diagnostische Notation. Der tatsächliche Austausch erfolgt immer im Binärformat.
Es sei darauf hingewiesen, dass dies wirklich ein Diagnoseformat ist; es ist nicht dazu gedacht, geparst zu werden. Daher wird in diesem Dokument keine formale Definition (wie in ABNF) angegeben. (Implementierer, die ein textbasiertes Format zur Darstellung von CBOR-Datenelementen in Konfigurationsdateien suchen, können auch YAML [YAML] in Betracht ziehen.)
Die diagnostische Notation basiert lose auf JSON, wie es in RFC 4627 definiert ist, und erweitert es dort, wo es nötig ist.
Die Notation übernimmt die JSON-Syntax für Zahlen (ganze Zahlen und Gleitkommazahlen), True (>true<), False (>false<), Null (>null<), UTF-8-Strings, Arrays und Maps (Maps werden in JSON Objekte genannt; die diagnostische Notation erweitert JSON hier, indem sie ein beliebiges Datenelement an der Schlüsselposition zulässt). Undefined wird wie in JavaScript als >undefined< geschrieben. Die nicht-endlichen Gleitkommazahlen Infinity, -Infinity und NaN werden genau wie in diesem Satz geschrieben (dies ist auch eine Art, wie sie in JavaScript geschrieben werden können, obwohl JSON sie nicht zulässt). Ein mit einem Tag versehenes Element wird als ganze Zahl für den Tag geschrieben, gefolgt vom Element in Klammern; beispielsweise könnte ein Datum nach RFC 3339 (ISO 8601) wie folgt notiert werden:
0("2013-03-21T20:04:00Z")
oder die äquivalente relative Zeit als
1(1363896240)
Byte-Zeichenfolgen werden in einer der Basis-Kodierungen notiert, ohne Padding, in einfache Anführungszeichen eingeschlossen, mit vorangestelltem >h< für base16, >b32< für base32, >h32< für base32hex, >b64< für base64 oder base64url (die tatsächlichen Kodierungen überlappen nicht, sodass die Zeichenfolge eindeutig bleibt). Beispielsweise könnte die Byte-Zeichenfolge 0x12345678 als h'12345678', b32'CI2FM6A' oder b64'EjRWeA' geschrieben werden.
Nicht zugewiesene einfache Werte werden als "simple()" mit der entsprechenden ganzen Zahl in den Klammern angegeben. Beispielsweise bezeichnet "simple(42)" den Haupttyp 7, Wert 42.
6.1. Kodierungsindikatoren
Mitunter ist es nützlich, in der diagnostischen Notation anzugeben, welche von mehreren alternativen Darstellungen tatsächlich verwendet wurde; beispielsweise könnte ein Datenelement, das von einem Diagnose-Decoder als >1.5< geschrieben wird, als Gleitkommazahl mit halber, einfacher oder doppelter Genauigkeit kodiert worden sein.
Die Konvention für Kodierungsindikatoren lautet: Alles, was mit einem Unterstrich beginnt, gefolgt von allen Zeichen, die alphanumerisch oder ein Unterstrich sind, ist ein Kodierungsindikator und kann von jedem ignoriert werden, der an dieser Information nicht interessiert ist. Kodierungsindikatoren sind immer optional.
Ein einzelner Unterstrich kann nach der öffnenden geschweiften Klammer einer Map oder der öffnenden eckigen Klammer eines Arrays geschrieben werden, um anzuzeigen, dass das Datenelement im Format mit unbestimmter Länge dargestellt wurde. Beispielsweise enthält [_ 1, 2] einen Indikator dafür, dass eine Darstellung mit unbestimmter Länge verwendet wurde, um das Datenelement [1, 2] darzustellen.
Ein Unterstrich, gefolgt von einer Dezimalziffer n, zeigt an, dass das vorangehende Element (oder, bei Arrays und Maps, das Element, das mit der vorangehenden Klammer beginnt) mit einem Wert der zusätzlichen Informationen von 24+n kodiert wurde. Beispielsweise ist 1.5_1 eine Gleitkommazahl mit halber Genauigkeit, während 1.5_3 mit doppelter Genauigkeit kodiert ist. Dieser Kodierungsindikator wird in Anhang A nicht gezeigt. (Hinweis: Der Kodierungsindikator "_" ist damit eine Abkürzung der Vollform "_7", die nicht verwendet wird.)
Als Sonderfall können Byte- und Text-Zeichenfolgen unbestimmter Länge in der Form (_ h'0123', h'4567') und (_ "foo", "bar") notiert werden.