Passa al contenuto principale

4. Conversione di dati tra CBOR e JSON

Questa sezione fornisce consigli non normativi sulla conversione tra CBOR e JSON. Le implementazioni dei convertitori sono libere di usare i consigli qui riportati che preferiscono.

Vale la pena notare che un testo JSON è una sequenza di caratteri, non una sequenza codificata di byte, mentre un elemento dati CBOR è costituito da byte, non da caratteri.

4.1. Conversione da CBOR a JSON​

La maggior parte dei tipi in CBOR ha analoghi diretti in JSON. Tuttavia, alcuni non ne hanno, e chi implementa un convertitore da CBOR a JSON deve considerare cosa fare in quei casi. I seguenti consigli non normativi li gestiscono convertendoli in un unico valore sostitutivo, come un null JSON.

  • Un intero (tipo principale 0 o 1) diventa un numero JSON.

  • Una stringa di byte (tipo principale 2) che non è incorporata in un tag che specifica una codifica proposta viene codificata in base64url senza padding e diventa una stringa JSON.

  • Una stringa UTF-8 (tipo principale 3) diventa una stringa JSON. Si noti che JSON richiede l'escape di determinati caratteri (RFC 4627, Sezione 2.5): virgolette (U+0022), reverse solidus (U+005C) e i "caratteri di controllo C0" (da U+0000 a U+001F). Tutti gli altri caratteri vengono copiati invariati nella stringa UTF-8 JSON.

  • Un array (tipo principale 4) diventa un array JSON.

  • Una mappa (tipo principale 5) diventa un oggetto JSON. Ciò è possibile direttamente solo se tutte le chiavi sono stringhe UTF-8. Un convertitore potrebbe anche convertire altre chiavi in stringhe UTF-8 (ad esempio convertendo gli interi in stringhe contenenti la loro rappresentazione decimale); tuttavia, ciò introduce un pericolo di collisione delle chiavi.

  • False (tipo principale 7, informazioni aggiuntive 20) diventa un false JSON.

  • True (tipo principale 7, informazioni aggiuntive 21) diventa un true JSON.

  • Null (tipo principale 7, informazioni aggiuntive 22) diventa un null JSON.

  • Un valore in virgola mobile (tipo principale 7, informazioni aggiuntive da 25 a 27) diventa un numero JSON se è finito (cioè, se può essere rappresentato in un numero JSON); se il valore non è finito (NaN, o Infinity positivo o negativo), è rappresentato dal valore sostitutivo.

  • Qualsiasi altro valore semplice (tipo principale 7, qualsiasi valore delle informazioni aggiuntive non ancora discusso) è rappresentato dal valore sostitutivo.

  • Un bignum (tipo principale 6, valore di tag 2 o 3) è rappresentato codificando la sua stringa di byte in base64url senza padding e diventa una stringa JSON. Per il valore di tag 3 (bignum negativo), un "~" (tilde ASCII) è inserito prima del valore codificato in base. (La conversione in un blob binario invece che in un numero serve a prevenire un probabile overflow numerico per il decoder JSON.)

  • Una stringa di byte con un suggerimento di codifica (tipo principale 6, valore di tag da 21 a 23) è codificata come descritto e diventa una stringa JSON.

  • Per tutti gli altri tag (tipo principale 6, qualsiasi altro valore di tag), l'elemento CBOR incorporato è rappresentato come un valore JSON; il valore del tag è ignorato.

  • Gli elementi a lunghezza indefinita sono resi definiti prima della conversione.

4.2. Conversione da JSON a CBOR​

Tutti i valori JSON, una volta decodificati, si mappano direttamente in uno o più valori CBOR. Come per qualsiasi tipo di generazione di CBOR, devono essere prese decisioni riguardo alla rappresentazione dei numeri. In una conversione suggerita:

  • I numeri JSON senza parte frazionaria (numeri interi) sono rappresentati come interi (tipi principali 0 e 1, possibilmente tipo principale 6 con valore di tag 2 e 3), scegliendo la forma più breve; gli interi più lunghi di una soglia definita dall'implementazione (che di solito è di 32 o 64 bit) possono invece essere rappresentati come valori in virgola mobile. (Se il JSON è stato generato da un'implementazione JavaScript, la sua precisione è già limitata a un massimo di 53 bit.)

  • I numeri con parte frazionaria sono rappresentati come valori in virgola mobile. Preferibilmente, si usa la rappresentazione in virgola mobile esatta più breve; ad esempio, 1.5 è rappresentato in un valore in virgola mobile a 16 bit (non tutte le implementazioni saranno però in grado di trovare efficientemente la forma minima). Può esserci un limite di precisione definito dall'implementazione che influenzerà la precisione dei valori rappresentati. La rappresentazione decimale dovrebbe essere usata solo se ciò è specificato in un protocollo.

CBOR è stato progettato per fornire in generale una codifica più compatta di JSON. Una strategia di implementazione che potrebbe venire in mente è eseguire una codifica da JSON a CBOR sul posto in un unico buffer. Questa strategia dovrebbe considerare attentamente una serie di casi patologici, come il fatto che alcune stringhe rappresentate senza o con pochissimi escape e più lunghe (o molto più lunghe) di 255 byte potrebbero espandersi quando codificate come stringhe UTF-8 in CBOR. Analogamente, alcune delle rappresentazioni in virgola mobile binarie potrebbero causare un'espansione a partire da alcune brevi rappresentazioni decimali (1.1, 1e9) in JSON. Questo può essere difficile da ottenere correttamente, e le eventuali vulnerabilità che ne derivano potrebbero essere sfruttate da un attaccante.