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 58 59!!! success "Complete mapping" 60 61 The mapping is **complete** in the sense that any JSON value type can be converted to a CBOR value. 62 63!!! info "NaN/infinity handling" 64 65 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`. 66 67!!! info "Unused CBOR types" 68 69 The following CBOR types are not used in the conversion: 70 71 - UTF-8 strings terminated by "break" (0x7F) 72 - arrays terminated by "break" (0x9F) 73 - maps terminated by "break" (0xBF) 74 - byte strings terminated by "break" (0x5F) 75 - date/time (0xC0..0xC1) 76 - bignum (0xC2..0xC3) 77 - decimal fraction (0xC4) 78 - bigfloat (0xC5) 79 - expected conversions (0xD5..0xD7) 80 - simple values (0xE0..0xF3, 0xF8) 81 - undefined (0xF7) 82 - half-precision floats (0xF9) 83 - break (0xFF) 84 85!!! info "Tagged items" 86 87 Binary subtypes will be serialized as tagged items. See [binary values](../binary_values.md#cbor) for an example. 88 89??? example 90 91 ```cpp 92 --8<-- "examples/to_cbor.cpp" 93 ``` 94 95 Output: 96 97 ```c 98 --8<-- "examples/to_cbor.output" 99 ``` 100 101## Deserialization 102 103The library maps CBOR types to JSON value types as follows: 104 105CBOR type | JSON value type | first byte 106---------------------- | --------------- | ---------- 107Integer | number_unsigned | 0x00..0x17 108Unsigned integer | number_unsigned | 0x18 109Unsigned integer | number_unsigned | 0x19 110Unsigned integer | number_unsigned | 0x1A 111Unsigned integer | number_unsigned | 0x1B 112Negative integer | number_integer | 0x20..0x37 113Negative integer | number_integer | 0x38 114Negative integer | number_integer | 0x39 115Negative integer | number_integer | 0x3A 116Negative integer | number_integer | 0x3B 117Byte string | binary | 0x40..0x57 118Byte string | binary | 0x58 119Byte string | binary | 0x59 120Byte string | binary | 0x5A 121Byte string | binary | 0x5B 122UTF-8 string | string | 0x60..0x77 123UTF-8 string | string | 0x78 124UTF-8 string | string | 0x79 125UTF-8 string | string | 0x7A 126UTF-8 string | string | 0x7B 127UTF-8 string | string | 0x7F 128array | array | 0x80..0x97 129array | array | 0x98 130array | array | 0x99 131array | array | 0x9A 132array | array | 0x9B 133array | array | 0x9F 134map | object | 0xA0..0xB7 135map | object | 0xB8 136map | object | 0xB9 137map | object | 0xBA 138map | object | 0xBB 139map | object | 0xBF 140False | `false` | 0xF4 141True | `true` | 0xF5 142Null | `null` | 0xF6 143Half-Precision Float | number_float | 0xF9 144Single-Precision Float | number_float | 0xFA 145Double-Precision Float | number_float | 0xFB 146 147!!! warning "Incomplete mapping" 148 149 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: 150 151 - date/time (0xC0..0xC1) 152 - bignum (0xC2..0xC3) 153 - decimal fraction (0xC4) 154 - bigfloat (0xC5) 155 - expected conversions (0xD5..0xD7) 156 - simple values (0xE0..0xF3, 0xF8) 157 - undefined (0xF7) 158 159!!! warning "Object keys" 160 161 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. 162 163!!! warning "Tagged items" 164 165 Tagged items will throw a parse error by default. However, they can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`. 166 167??? example 168 169 ```cpp 170 --8<-- "examples/from_cbor.cpp" 171 ``` 172 173 Output: 174 175 ```json 176 --8<-- "examples/from_cbor.output" 177 ``` 178