3. Specification of the CBOR Encoding (Specifica della Codifica CBOR)
Un elemento di dati CBOR (Sezione 2) viene codificato verso o decodificato da una stringa di byte che trasporta un elemento di dati codificato ben formato come descritto in questa sezione. La codifica è riassunta nella Tabella 7 nell'Appendice B, indicizzata dal byte iniziale. Un encoder DEVE produrre solo elementi di dati codificati ben formati. Un decoder NON DEVE restituire un elemento di dati decodificato quando incontra un input che non è un elemento di dati CBOR codificato ben formato (questo non sminuisce l'utilità degli strumenti diagnostici e di recupero che potrebbero rendere disponibili alcune informazioni da un elemento di dati CBOR codificato danneggiato).
Il byte iniziale di ciascun elemento di dati codificato contiene sia informazioni sul tipo principale (Major Type, i 3 bit di ordine superiore, descritti nella Sezione 3.1) sia informazioni aggiuntive (Additional Information, i 5 bit di ordine inferiore). Con poche eccezioni, il valore delle informazioni aggiuntive descrive come caricare un intero senza segno "argomento":
Meno di 24: Il valore dell'argomento è il valore delle informazioni aggiuntive.
24, 25, 26 o 27: Il valore dell'argomento è contenuto nei successivi 1, 2, 4 o 8 byte, rispettivamente, in ordine di byte di rete. Per il tipo principale 7 e i valori di informazioni aggiuntive 25, 26, 27, questi byte non sono usati come argomento intero, ma come valore in virgola mobile (vedere Sezione 3.3).
28, 29, 30: Questi valori sono riservati per aggiunte future al formato CBOR. Nella versione attuale di CBOR, l'elemento codificato non è ben formato.
31: Non viene derivato alcun valore di argomento. Se il tipo principale è 0, 1 o 6, l'elemento codificato non è ben formato. Per i tipi principali da 2 a 5, la lunghezza dell'elemento è indefinita, e per il tipo principale 7, il byte non costituisce affatto un elemento di dati ma termina un elemento di lunghezza indefinita; tutti sono descritti nella Sezione 3.2.
Il byte iniziale e tutti i byte aggiuntivi consumati per costruire l'argomento sono collettivamente chiamati testa (head) dell'elemento di dati.
Il significato di questo argomento dipende dal tipo principale. Ad esempio, nel tipo principale 0, l'argomento è il valore dell'elemento di dati stesso (e nel tipo principale 1, il valore dell'elemento di dati è calcolato dall'argomento); nei tipi principali 2 e 3, fornisce la lunghezza dei dati della stringa in byte che seguono; e nei tipi principali 4 e 5, viene utilizzato per determinare il numero di elementi di dati racchiusi.
Se la sequenza codificata di byte termina prima della fine di un elemento di dati, quell'elemento non è ben formato. Se la sequenza codificata di byte ha ancora byte rimanenti dopo che l'elemento codificato più esterno è decodificato, quella codifica non è un singolo elemento CBOR ben formato. A seconda dell'applicazione, il decoder può trattare la codifica come non ben formata o semplicemente identificare l'inizio dei byte rimanenti all'applicazione.
Un'implementazione di decoder CBOR può essere basata su una tabella di salto con tutti i 256 valori definiti per il byte iniziale (Tabella 7). Un decoder in un'implementazione vincolata può invece utilizzare la struttura del byte iniziale e dei byte seguenti per un codice più compatto (vedere Appendice C per un'impressione approssimativa di come potrebbe apparire).
3.1. Major Types (Tipi Principali)
Quanto segue elenca i tipi principali e le informazioni aggiuntive e altri byte associati al tipo.
Tipo principale 0: Un intero senza segno nell'intervallo 0..2^(64)-1 incluso. Il valore dell'elemento codificato è l'argomento stesso. Ad esempio, l'intero 10 è denotato come il singolo byte 0b000_01010 (tipo principale 0, informazioni aggiuntive 10). L'intero 500 sarebbe 0b000_11001 (tipo principale 0, informazioni aggiuntive 25) seguito dai due byte 0x01f4, che è 500 in decimale.
Tipo principale 1: Un intero negativo nell'intervallo -2^(64)..-1 incluso. Il valore dell'elemento è -1 meno l'argomento. Ad esempio, l'intero -500 sarebbe 0b001_11001 (tipo principale 1, informazioni aggiuntive 25) seguito dai due byte 0x01f3, che è 499 in decimale.
Tipo principale 2: Una stringa di byte (Byte String). Il numero di byte nella stringa è uguale all'argomento. Ad esempio, una stringa di byte la cui lunghezza è 5 avrebbe un byte iniziale di 0b010_00101 (tipo principale 2, informazioni aggiuntive 5 per la lunghezza), seguito da 5 byte di contenuto binario.
Tipo principale 3: Una stringa di testo (Text String, Sezione 2) codificata come UTF-8 [RFC3629]. Il numero di byte nella stringa è uguale all'argomento. Una stringa contenente una sequenza UTF-8 non valida è ben formata ma non valida (Sezione 1.2). Questo tipo è fornito per i sistemi che devono interpretare o visualizzare testo leggibile dall'uomo e consente la differenziazione tra byte non strutturati e testo che ha un repertorio specificato (quello di Unicode) e una codifica (UTF-8).
Tipo principale 4: Un array di elementi di dati. In altri formati, gli array sono anche chiamati liste, sequenze o tuple (una "sequenza CBOR" è qualcosa di leggermente diverso, vedere [RFC8742]). L'argomento è il numero di elementi di dati nell'array. Gli elementi in un array non devono essere tutti dello stesso tipo.
Tipo principale 5: Una mappa (Map) di coppie di elementi di dati. Le mappe sono anche chiamate tabelle, dizionari, hash o oggetti (in JSON). Una mappa è composta da coppie di elementi di dati, ogni coppia costituita da una chiave immediatamente seguita da un valore. L'argomento è il numero di coppie di elementi di dati nella mappa.
Tipo principale 6: Un elemento di dati etichettato ("tag") il cui numero di tag, un intero nell'intervallo 0..2^(64)-1 incluso, è l'argomento e il cui elemento di dati racchiuso (contenuto del tag, tag content) è il singolo elemento di dati codificato che segue la testa. Vedere Sezione 3.4.
Tipo principale 7: Numeri in virgola mobile e valori semplici (Simple Values), nonché il codice di arresto "break". Vedere Sezione 3.3.
Questi otto tipi principali portano a una tabella semplice che mostra quali dei 256 valori possibili per il byte iniziale di un elemento di dati vengono utilizzati (Tabella 7).
| Tipo Principale | Significato | Contenuto |
|---|---|---|
| 0 | intero senza segno N | - |
| 1 | intero negativo -1-N | - |
| 2 | stringa di byte | N byte |
| 3 | stringa di testo | N byte (testo UTF-8) |
| 4 | array | N elementi di dati (elementi) |
| 5 | mappa | 2N elementi di dati (coppie chiave/valore) |
| 6 | tag di numero N | 1 elemento di dati |
| 7 | semplice/float | - |
Tabella 1: Panoramica dell'Uso di Lunghezza Definita dei Tipi Principali CBOR (N = Argomento)
3.2. Indefinite Lengths for Some Major Types (Lunghezze Indefinite per Alcuni Tipi Principali)
Quattro elementi CBOR (array, mappe, stringhe di byte e stringhe di testo) possono essere codificati con una lunghezza indefinita utilizzando il valore di informazioni aggiuntive 31. Questo è utile se la codifica dell'elemento deve iniziare prima che il numero di elementi all'interno dell'array o della mappa, o la lunghezza totale della stringa, sia noto.
Gli array e le mappe di lunghezza indefinita sono trattati in modo diverso rispetto alle stringhe di lunghezza indefinita (stringhe di byte e stringhe di testo).
3.2.1. The "break" Stop Code (Il Codice di Arresto "break")
Il codice di arresto "break" è codificato con il tipo principale 7 e il valore di informazioni aggiuntive 31 (0b111_11111). Non è esso stesso un elemento di dati: è solo una caratteristica sintattica per chiudere un elemento di lunghezza indefinita.
3.3. Floating-Point Numbers and Values with No Content (Numeri in Virgola Mobile e Valori senza Contenuto)
Il tipo principale 7 è per due tipi di dati: numeri in virgola mobile e "valori semplici" (Simple Values) che non necessitano di alcun contenuto. Ogni valore delle informazioni aggiuntive a 5 bit nel byte iniziale ha il proprio significato separato, come definito nella Tabella 3.
| Valore 5 Bit | Semantica |
|---|---|
| 0..23 | Valore semplice (valore 0..23) |
| 24 | Valore semplice (valore 32..255 nel byte seguente) |
| 25 | Float Mezza Precisione IEEE 754 (seguono 16 bit) |
| 26 | Float Precisione Singola IEEE 754 (seguono 32 bit) |
| 27 | Float Doppia Precisione IEEE 754 (seguono 64 bit) |
| 28-30 | Riservato, non ben formato in questo documento |
| 31 | Codice di arresto "break" per elementi di lunghezza indefinita |
Tabella 3: Valori per Informazioni Aggiuntive nel Tipo Principale 7
| Valore | Semantica |
|---|---|
| 0..19 | (non assegnato) |
| 20 | false |
| 21 | true |
| 22 | null |
| 23 | undefined |
| 24..31 | (riservato) |
| 32..255 | (non assegnato) |
Tabella 4: Valori Semplici
3.4. Tagging of Items (Etichettatura degli Elementi)
In CBOR, un elemento di dati può essere racchiuso da un tag per dargli una semantica aggiuntiva, identificata in modo univoco da un numero di tag (tag number). Il tag è il tipo principale 6, il suo argomento (Sezione 3) indica il numero di tag e contiene un singolo elemento di dati racchiuso, il contenuto del tag (tag content).
IANA mantiene un registro dei numeri di tag come descritto nella Sezione 9.2. La Tabella 5 fornisce un elenco di numeri di tag definiti in [RFC7049].
| Tag | Elemento di Dati | Semantica |
|---|---|---|
| 0 | stringa di testo | Stringa data/ora standard |
| 1 | intero o float | Data/ora basata su epoca |
| 2 | stringa di byte | Grande numero senza segno |
| 3 | stringa di byte | Grande numero negativo |
| 4 | array | Frazione decimale |
| 5 | array | Grande float |
| 21 | (qualsiasi) | Conversione attesa a codifica base64url |
| 22 | (qualsiasi) | Conversione attesa a codifica base64 |
| 23 | (qualsiasi) | Conversione attesa a codifica base16 |
| 24 | stringa di byte | Elemento di dati CBOR codificato |
| 32 | stringa di testo | URI |
| 33 | stringa di testo | base64url |
| 34 | stringa di testo | base64 |
| 36 | stringa di testo | Messaggio MIME |
| 55799 | (qualsiasi) | CBOR auto-descritto |
Tabella 5: Numeri di Tag Definiti in RFC 7049