CBOR¶

Incomplete mapping

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:

• simple values (0xE0..0xF3, 0xF8)
• undefined (0xF7)

Tagged items (0xC0..0xDB) are not interpreted either; see the note on tagged items below.

Negative integer overflow

CBOR negative integers (major type 1) are decoded as -1 - n. If the encoded magnitude n is too large for the result to fit into number_integer_t (std::int64_t by default), the result is stored as number_float_t, like a too small integer in JSON text. For example, -18446744073709551616 (0x3B followed by eight 0xFF bytes) is stored as -1.8446744073709552e+19.

Object keys

CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than text strings (major type 3) are rejected with a parse_error.113 exception (or, with allow_exceptions set to false, a discarded value) naming the type of the key that was found, for instance:

[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR object key: only string keys are supported, but found an unsigned integer; last byte: 0x01

This applies to the SAX interface as well, as the key is read before it is passed on. This is a deliberate restriction of the library's JSON value model, not an oversight: formats built on CBOR maps with integer keys, such as COSE (RFC 9052) or CWT (RFC 8392), cannot be read with this library and need a general-purpose CBOR library instead.

A tag in front of a text string key is handled like a tag in front of a value: it is skipped with cbor_tag_handler_t::ignore or cbor_tag_handler_t::store and rejected with the default error. A tag does not turn a key of another type into a text string.

A map with duplicate keys is well-formed, but invalid under RFC 8949, Section 5.3.1. from_cbor accepts it and the last value wins; the SAX interface reports every occurrence.

Ill-formed UTF-8 in text strings

RFC 8949, Section 3.1 requires CBOR text strings (major type 3) to be valid UTF-8 (a string with ill-formed UTF-8 is "well-formed but invalid"), and Section 5.3.1 leaves it up to the decoder whether to verify this, so checking is opt-in: with the error_handler parameter left at keep (the default), from_cbor() accepts a text string (object keys included) whose bytes are not valid UTF-8 and hands them back unchanged. Passing error_handler_t::strict makes from_cbor() check and throw parse_error.113 for ill-formed UTF-8, and replace/ignore sanitize the string instead of keeping it. However, dump() still requires valid UTF-8 and throws type_error.316 for a value read with the default keep handler, unless an error handler is passed that replaces or ignores the ill-formed bytes. to_cbor()'s own error_handler parameter defaults to keep, so such a value is written back unchanged; with strict (the default if JSON_STRICT_BINARY_UTF8 is enabled), it throws the same exception instead. Byte strings (major type 2) are unaffected, since they are not required to hold text.

The chunks of an indefinite-length text string are checked one by one, as required by RFC 8949, Section 3.2.3: a code point cannot be spread over two chunks. With error_handler_t::strict such a string throws parse_error.113; replace and ignore sanitize each chunk on its own.

Tagged items

Tagged items (0xC0..0xDB) will throw a parse error by default. They can be ignored by passing cbor_tag_handler_t::ignore to function from_cbor, in which case the tag is skipped and the enclosed data item is parsed on its own. Passing cbor_tag_handler_t::store to function from_cbor stores tagged byte strings (for bytes 0xd8..0xdb) as binary values with the tag as subtype; other tagged values are read as if the tag were ignored. If several tags precede a byte string, only the tag directly in front of it is stored, and only when it has the form 0xD8..0xDB (a tag 0..23 written as 0xC0..0xD7 is skipped); for example, D8 05 C1 41 AA yields subtype null, whereas C1 D8 05 41 AA yields 5. Tags in front of a text string map key are skipped as well. Note that no tag is ever interpreted: for instance, a text string tagged with tag 0 (date/time) stays a string.