6. Notazione diagnostica
CBOR è un formato binario di interscambio. Per facilitare la documentazione e il debug, e in particolare per facilitare la comunicazione tra le entità che cooperano nel debug, questa sezione definisce una semplice notazione diagnostica leggibile dall'uomo. Tutti gli scambi effettivi avvengono sempre nel formato binario.
Si noti che questa è davvero una notazione diagnostica; non è destinata a essere analizzata sintatticamente. Pertanto, in questo documento non viene fornita alcuna definizione formale (come in ABNF). (Gli implementatori che cercano un formato basato su testo per rappresentare elementi dati CBOR in file di configurazione possono anche prendere in considerazione YAML [YAML].)
La notazione diagnostica si basa liberamente su JSON così come definito nel RFC 4627, estendendolo dove necessario.
La notazione riprende la sintassi JSON per i numeri (interi e in virgola mobile), True (>true<), False (>false<), Null (>null<), le stringhe UTF-8, gli array e le mappe (le mappe sono chiamate oggetti in JSON; la notazione diagnostica estende JSON qui consentendo qualsiasi elemento dati nella posizione di chiave). Undefined è scritto >undefined< come in JavaScript. I numeri in virgola mobile non finiti Infinity, -Infinity e NaN sono scritti esattamente come in questa frase (questo è anche un modo in cui possono essere scritti in JavaScript, sebbene JSON non li consenta). Un elemento con tag è scritto come un numero intero per il tag seguito dall'elemento tra parentesi; per esempio, una data RFC 3339 (ISO 8601) potrebbe essere notata come:
0("2013-03-21T20:04:00Z")
oppure il tempo relativo equivalente come
1(1363896240)
Le stringhe di byte sono notate in una delle codifiche in base, senza padding, racchiuse tra virgolette singole, precedute da >h< per base16, >b32< per base32, >h32< per base32hex, >b64< per base64 o base64url (le codifiche effettive non si sovrappongono, quindi la stringa rimane non ambigua). Ad esempio, la stringa di byte 0x12345678 potrebbe essere scritta h'12345678', b32'CI2FM6A' o b64'EjRWeA'.
I valori simple non assegnati sono indicati come "simple()" con l'intero appropriato tra parentesi. Ad esempio, "simple(42)" indica il tipo principale 7, valore 42.
6.1. Indicatori di codifica
A volte è utile indicare nella notazione diagnostica quale di diverse rappresentazioni alternative è stata effettivamente utilizzata; ad esempio, un elemento dati scritto >1.5< da un decoder diagnostico potrebbe essere stato codificato come float in mezza precisione, precisione singola o doppia precisione.
La convenzione per gli indicatori di codifica è che qualsiasi cosa che inizi con un carattere di sottolineatura e tutti i caratteri successivi che siano alfanumerici o un carattere di sottolineatura, è un indicatore di codifica, e può essere ignorata da chiunque non sia interessato a questa informazione. Gli indicatori di codifica sono sempre opzionali.
Un singolo carattere di sottolineatura può essere scritto dopo la parentesi graffa di apertura di una mappa o la parentesi quadra di apertura di un array per indicare che l'elemento dati è stato rappresentato in formato a lunghezza indefinita. Ad esempio, [_ 1, 2] contiene un indicatore che è stata utilizzata una rappresentazione a lunghezza indefinita per rappresentare l'elemento dati [1, 2].
Un carattere di sottolineatura seguito da una cifra decimale n indica che l'elemento precedente (o, per array e mappe, l'elemento che inizia con la parentesi quadra o graffa precedente) è stato codificato con un valore di additional information pari a 24+n. Ad esempio, 1.5_1 è un numero in virgola mobile a mezza precisione, mentre 1.5_3 è codificato in doppia precisione. Questo indicatore di codifica non è mostrato nell'Appendice A. (Si noti che l'indicatore di codifica "_" è quindi un'abbreviazione della forma completa "_7", che non è utilizzata.)
Come caso speciale, le stringhe di byte e di testo di lunghezza indefinita possono essere notate nella forma (_ h'0123', h'4567') e (_ "foo", "bar").