1# CBOR 2 3The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. 4 5!!! abstract "References" 6 7 - [CBOR Website](http://cbor.io) - the main source on CBOR 8 - [CBOR Playground](http://cbor.me) - an interactive webpage to translate between JSON and CBOR 9 - [RFC 7049](https://tools.ietf.org/html/rfc7049) - the CBOR specification 10 11## Serialization 12 13The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049): 14 15JSON value type | value/range | CBOR type | first byte 16--------------- | ------------------------------------------ | ---------------------------------- | --------------- 17null | `null` | Null | 0xF6 18boolean | `true` | True | 0xF5 19boolean | `false` | False | 0xF4 20number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B 21number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A 22number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39 23number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38 24number_integer | -24..-1 | Negative integer | 0x20..0x37 25number_integer | 0..23 | Integer | 0x00..0x17 26number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18 27number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 28number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A 29number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B 30number_unsigned | 0..23 | Integer | 0x00..0x17 31number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18 32number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 33number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A 34number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B 35number_float | *any value representable by a float* | Single-Precision Float | 0xFA 36number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB 37string | *length*: 0..23 | UTF-8 string | 0x60..0x77 38string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78 39string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79 40string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A 41string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B 42array | *size*: 0..23 | array | 0x80..0x97 43array | *size*: 23..255 | array (1 byte follow) | 0x98 44array | *size*: 256..65535 | array (2 bytes follow) | 0x99 45array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A 46array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B 47object | *size*: 0..23 | map | 0xA0..0xB7 48object | *size*: 23..255 | map (1 byte follow) | 0xB8 49object | *size*: 256..65535 | map (2 bytes follow) | 0xB9 50object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA 51object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB 52binary | *size*: 0..23 | byte string | 0x40..0x57 53binary | *size*: 23..255 | byte string (1 byte follow) | 0x58 54binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59 55binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A 56binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B 57 58Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string, 59see "binary" cells in the table above. 60 61!!! success "Complete mapping" 62 63 The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. 64 65!!! info "NaN/infinity handling" 66 67 If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`. 68 69!!! info "Unused CBOR types" 70 71 The following CBOR types are not used in the conversion: 72 73 - UTF-8 strings terminated by "break" (0x7F) 74 - arrays terminated by "break" (0x9F) 75 - maps terminated by "break" (0xBF) 76 - byte strings terminated by "break" (0x5F) 77 - date/time (0xC0..0xC1) 78 - bignum (0xC2..0xC3) 79 - decimal fraction (0xC4) 80 - bigfloat (0xC5) 81 - expected conversions (0xD5..0xD7) 82 - simple values (0xE0..0xF3, 0xF8) 83 - undefined (0xF7) 84 - half-precision floats (0xF9) 85 - break (0xFF) 86 87!!! info "Tagged items" 88 89 Binary subtypes will be serialized as tagged items. See [binary values](../binary_values.md#cbor) for an example. 90 91??? example 92 93 ```cpp 94 --8<-- "examples/to_cbor.cpp" 95 ``` 96 97 Output: 98 99 ```c 100 --8<-- "examples/to_cbor.output" 101 ``` 102 103## Deserialization 104 105The library maps CBOR types to JSON value types as follows: 106 107CBOR type | JSON value type | first byte 108---------------------- | --------------- | ---------- 109Integer | number_unsigned | 0x00..0x17 110Unsigned integer | number_unsigned | 0x18 111Unsigned integer | number_unsigned | 0x19 112Unsigned integer | number_unsigned | 0x1A 113Unsigned integer | number_unsigned | 0x1B 114Negative integer | number_integer | 0x20..0x37 115Negative integer | number_integer | 0x38 116Negative integer | number_integer | 0x39 117Negative integer | number_integer | 0x3A 118Negative integer | number_integer | 0x3B 119Byte string | binary | 0x40..0x57 120Byte string | binary | 0x58 121Byte string | binary | 0x59 122Byte string | binary | 0x5A 123Byte string | binary | 0x5B 124UTF-8 string | string | 0x60..0x77 125UTF-8 string | string | 0x78 126UTF-8 string | string | 0x79 127UTF-8 string | string | 0x7A 128UTF-8 string | string | 0x7B 129UTF-8 string | string | 0x7F 130array | array | 0x80..0x97 131array | array | 0x98 132array | array | 0x99 133array | array | 0x9A 134array | array | 0x9B 135array | array | 0x9F 136map | object | 0xA0..0xB7 137map | object | 0xB8 138map | object | 0xB9 139map | object | 0xBA 140map | object | 0xBB 141map | object | 0xBF 142False | `false` | 0xF4 143True | `true` | 0xF5 144Null | `null` | 0xF6 145Half-Precision Float | number_float | 0xF9 146Single-Precision Float | number_float | 0xFA 147Double-Precision Float | number_float | 0xFB 148 149!!! warning "Incomplete mapping" 150 151 The mapping is **incomplete** in the sense that not all CBOR types can be converted to a JSON value. The following CBOR types are not supported and will yield parse errors: 152 153 - date/time (0xC0..0xC1) 154 - bignum (0xC2..0xC3) 155 - decimal fraction (0xC4) 156 - bigfloat (0xC5) 157 - expected conversions (0xD5..0xD7) 158 - simple values (0xE0..0xF3, 0xF8) 159 - undefined (0xF7) 160 161!!! warning "Object keys" 162 163 CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected. 164 165!!! warning "Tagged items" 166 167 Tagged items will throw a parse error by default. They can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`. They can be stored by passing `cbor_tag_handler_t::store` to function `from_cbor`. 168 169??? example 170 171 ```cpp 172 --8<-- "examples/from_cbor.cpp" 173 ``` 174 175 Output: 176 177 ```json 178 --8<-- "examples/from_cbor.output" 179 ``` 180