3. Specification of the CBOR Encoding (Spezifikation der CBOR-Codierung)

Ein CBOR-Datenelement (Abschnitt 2) wird zu oder von einer Byte-Zeichenfolge codiert oder decodiert, die ein wohlgeformtes codiertes Datenelement trägt, wie in diesem Abschnitt beschrieben. Die Codierung ist in Tabelle 7 in Anhang B zusammengefasst, indiziert nach dem Anfangsbyte. Ein Encoder MUSS nur wohlgeformte codierte Datenelemente erzeugen. Ein Decoder DARF NICHT ein decodiertes Datenelement zurückgeben, wenn er auf eine Eingabe trifft, die kein wohlgeformtes codiertes CBOR-Datenelement ist (dies schmälert nicht die Nützlichkeit von Diagnose- und Wiederherstellungstools, die möglicherweise einige Informationen aus einem beschädigten codierten CBOR-Datenelement verfügbar machen).

Das Anfangsbyte jedes codierten Datenelements enthält sowohl Informationen über den Haupttyp (Major Type, die höherwertigen 3 Bits, beschrieben in Abschnitt 3.1) als auch zusätzliche Informationen (Additional Information, die niederwertigen 5 Bits). Mit wenigen Ausnahmen beschreibt der Wert der zusätzlichen Informationen, wie eine vorzeichenlose Ganzzahl "Argument" geladen wird:

Kleiner als 24: Der Wert des Arguments ist der Wert der zusätzlichen Informationen.

24, 25, 26 oder 27: Der Wert des Arguments wird in den folgenden 1, 2, 4 oder 8 Bytes gehalten, jeweils in Netzwerk-Byte-Reihenfolge. Für Haupttyp 7 und zusätzliche Informationswerte 25, 26, 27 werden diese Bytes nicht als Ganzzahl-Argument verwendet, sondern als Gleitkommawert (siehe Abschnitt 3.3).

28, 29, 30: Diese Werte sind für zukünftige Ergänzungen des CBOR-Formats reserviert. In der aktuellen Version von CBOR ist das codierte Element nicht wohlgeformt.

31: Es wird kein Argumentwert abgeleitet. Wenn der Haupttyp 0, 1 oder 6 ist, ist das codierte Element nicht wohlgeformt. Für Haupttypen 2 bis 5 ist die Länge des Elements unbestimmt, und für Haupttyp 7 stellt das Byte überhaupt kein Datenelement dar, sondern beendet ein Element unbestimmter Länge; alle sind in Abschnitt 3.2 beschrieben.

Das Anfangsbyte und alle zusätzlichen Bytes, die zur Konstruktion des Arguments verbraucht werden, werden zusammen als Kopf (head) des Datenelements bezeichnet.

Die Bedeutung dieses Arguments hängt vom Haupttyp ab. Zum Beispiel ist im Haupttyp 0 das Argument der Wert des Datenelements selbst (und im Haupttyp 1 wird der Wert des Datenelements aus dem Argument berechnet); in Haupttyp 2 und 3 gibt es die Länge der Zeichenfolgendaten in Bytes an, die folgen; und in Haupttypen 4 und 5 wird es verwendet, um die Anzahl der eingeschlossenen Datenelemente zu bestimmen.

Wenn die codierte Bytefolge vor dem Ende eines Datenelements endet, ist dieses Element nicht wohlgeformt. Wenn die codierte Bytefolge nach dem Decodieren des äußersten codierten Elements noch Bytes übrig hat, ist diese Codierung kein einzelnes wohlgeformtes CBOR-Element. Abhängig von der Anwendung kann der Decoder die Codierung entweder als nicht wohlgeformt behandeln oder einfach den Beginn der verbleibenden Bytes der Anwendung identifizieren.

Eine CBOR-Decoder-Implementierung kann auf einer Sprungtabelle mit allen 256 definierten Werten für das Anfangsbyte basieren (Tabelle 7). Ein Decoder in einer eingeschränkten Implementierung kann stattdessen die Struktur des Anfangsbytes und der folgenden Bytes für kompakteren Code verwenden (siehe Anhang C für einen groben Eindruck, wie dies aussehen könnte).

3.1. Major Types (Haupttypen)

Das Folgende listet die Haupttypen und die zusätzlichen Informationen und anderen Bytes auf, die mit dem Typ verbunden sind.

Haupttyp 0: Eine vorzeichenlose Ganzzahl im Bereich 0..2^(64)-1 einschließlich. Der Wert des codierten Elements ist das Argument selbst. Zum Beispiel wird die Ganzzahl 10 als das eine Byte 0b000_01010 (Haupttyp 0, zusätzliche Information 10) bezeichnet. Die Ganzzahl 500 wäre 0b000_11001 (Haupttyp 0, zusätzliche Information 25) gefolgt von den zwei Bytes 0x01f4, was 500 im Dezimalsystem ist.

Haupttyp 1: Eine negative Ganzzahl im Bereich -2^(64)..-1 einschließlich. Der Wert des Elements ist -1 minus das Argument. Zum Beispiel wäre die Ganzzahl -500 0b001_11001 (Haupttyp 1, zusätzliche Information 25) gefolgt von den zwei Bytes 0x01f3, was 499 im Dezimalsystem ist.

Haupttyp 2: Eine Byte-Zeichenfolge (Byte String). Die Anzahl der Bytes in der Zeichenfolge ist gleich dem Argument. Zum Beispiel hätte eine Byte-Zeichenfolge mit der Länge 5 ein Anfangsbyte von 0b010_00101 (Haupttyp 2, zusätzliche Information 5 für die Länge), gefolgt von 5 Bytes Binärinhalt.

Haupttyp 3: Eine Textzeichenfolge (Text String, Abschnitt 2), codiert als UTF-8 [RFC3629]. Die Anzahl der Bytes in der Zeichenfolge ist gleich dem Argument. Eine Zeichenfolge, die eine ungültige UTF-8-Sequenz enthält, ist wohlgeformt, aber ungültig (Abschnitt 1.2). Dieser Typ wird für Systeme bereitgestellt, die menschenlesbaren Text interpretieren oder anzeigen müssen, und ermöglicht die Unterscheidung zwischen unstrukturierten Bytes und Text, der ein spezifiziertes Repertoire (das von Unicode) und eine Codierung (UTF-8) hat.

Haupttyp 4: Ein Array von Datenelementen. In anderen Formaten werden Arrays auch Listen, Sequenzen oder Tupel genannt (eine "CBOR-Sequenz" ist etwas etwas anderes, siehe [RFC8742]). Das Argument ist die Anzahl der Datenelemente im Array. Elemente in einem Array müssen nicht alle vom gleichen Typ sein.

Haupttyp 5: Eine Map von Paaren von Datenelementen. Maps werden auch Tabellen, Wörterbücher, Hashes oder Objekte genannt (in JSON). Eine Map besteht aus Paaren von Datenelementen, wobei jedes Paar aus einem Schlüssel besteht, auf den unmittelbar ein Wert folgt. Das Argument ist die Anzahl der Paare von Datenelementen in der Map.

Haupttyp 6: Ein getaggtes Datenelement ("Tag"), dessen Tag-Nummer, eine Ganzzahl im Bereich 0..2^(64)-1 einschließlich, das Argument ist und dessen eingeschlossenes Datenelement (Tag-Inhalt, tag content) das einzelne codierte Datenelement ist, das dem Kopf folgt. Siehe Abschnitt 3.4.

Haupttyp 7: Gleitkommazahlen und einfache Werte (Simple Values), sowie der "break"-Stoppcode. Siehe Abschnitt 3.3.

Diese acht Haupttypen führen zu einer einfachen Tabelle, die zeigt, welche der 256 möglichen Werte für das Anfangsbyte eines Datenelements verwendet werden (Tabelle 7).

Haupttyp	Bedeutung	Inhalt
0	vorzeichenlose Ganzzahl N	-
1	negative Ganzzahl -1-N	-
2	Byte-Zeichenfolge	N Bytes
3	Textzeichenfolge	N Bytes (UTF-8-Text)
4	Array	N Datenelemente (Elemente)
5	Map	2N Datenelemente (Schlüssel/Wert-Paare)
6	Tag der Nummer N	1 Datenelement
7	einfach/float	-

Tabelle 1: Überblick über die Verwendung bestimmter Längen von CBOR-Haupttypen (N = Argument)

3.2. Indefinite Lengths for Some Major Types (Unbestimmte Längen für Einige Haupttypen)

Vier CBOR-Elemente (Arrays, Maps, Byte-Zeichenfolgen und Textzeichenfolgen) können mit einer unbestimmten Länge unter Verwendung des zusätzlichen Informationswerts 31 codiert werden. Dies ist nützlich, wenn die Codierung des Elements beginnen muss, bevor die Anzahl der Elemente innerhalb des Arrays oder der Map oder die Gesamtlänge der Zeichenfolge bekannt ist.

Arrays und Maps unbestimmter Länge werden anders behandelt als Zeichenfolgen unbestimmter Länge (Byte-Zeichenfolgen und Textzeichenfolgen).

3.2.1. The "break" Stop Code (Der "break"-Stoppcode)

Der "break"-Stoppcode wird mit Haupttyp 7 und zusätzlichem Informationswert 31 (0b111_11111) codiert. Er ist selbst kein Datenelement: er ist nur ein syntaktisches Merkmal zum Schließen eines Elements unbestimmter Länge.

3.3. Floating-Point Numbers and Values with No Content (Gleitkommazahlen und Werte ohne Inhalt)

Haupttyp 7 ist für zwei Arten von Daten: Gleitkommazahlen und "einfache Werte" (Simple Values), die keinen Inhalt benötigen. Jeder Wert der 5-Bit zusätzlichen Informationen im Anfangsbyte hat seine eigene separate Bedeutung, wie in Tabelle 3 definiert.

5-Bit-Wert	Semantik
0..23	Einfacher Wert (Wert 0..23)
24	Einfacher Wert (Wert 32..255 im folgenden Byte)
25	IEEE 754 Halbpräzisions-Float (16 Bits folgen)
26	IEEE 754 Einzelpräzisions-Float (32 Bits folgen)
27	IEEE 754 Doppelpräzisions-Float (64 Bits folgen)
28-30	Reserviert, nicht wohlgeformt in diesem Dokument
31	"break"-Stoppcode für Elemente unbestimmter Länge

Tabelle 3: Werte für zusätzliche Informationen in Haupttyp 7

Wert	Semantik
0..19	(nicht zugewiesen)
20	false
21	true
22	null
23	undefined
24..31	(reserviert)
32..255	(nicht zugewiesen)

Tabelle 4: Einfache Werte

3.4. Tagging of Items (Tagging von Elementen)

In CBOR kann ein Datenelement von einem Tag umschlossen werden, um ihm zusätzliche Semantik zu geben, wie durch eine Tag-Nummer (tag number) eindeutig identifiziert. Der Tag ist Haupttyp 6, sein Argument (Abschnitt 3) gibt die Tag-Nummer an, und er enthält ein einzelnes eingeschlossenes Datenelement, den Tag-Inhalt (tag content).

IANA führt ein Register von Tag-Nummern, wie in Abschnitt 9.2 beschrieben. Tabelle 5 bietet eine Liste von Tag-Nummern, die in [RFC7049] definiert wurden.

Tag	Datenelement	Semantik
0	Textzeichenfolge	Standard-Datum/Zeit-Zeichenfolge
1	Ganzzahl oder Float	Epochenbasiertes Datum/Zeit
2	Byte-Zeichenfolge	Vorzeichenlose große Zahl
3	Byte-Zeichenfolge	Negative große Zahl
4	Array	Dezimalbruch
5	Array	Großer Float
21	(beliebig)	Erwartete Konvertierung zu base64url-Codierung
22	(beliebig)	Erwartete Konvertierung zu base64-Codierung
23	(beliebig)	Erwartete Konvertierung zu base16-Codierung
24	Byte-Zeichenfolge	Codiertes CBOR-Datenelement
32	Textzeichenfolge	URI
33	Textzeichenfolge	base64url
34	Textzeichenfolge	base64
36	Textzeichenfolge	MIME-Nachricht
55799	(beliebig)	Selbstbeschreibendes CBOR

Tabelle 5: In RFC 7049 Definierte Tag-Nummern