json/docs/mkdocs/docs/api/basic_json/binary_t.md

nlohmann::basic_json::binary_t

using binary_t = byte_container_with_subtype<BinaryType>;

This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type 2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.

Additionally, as an implementation detail, the subtype of the binary data is carried around as a std::uint64_t, which is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is incompatible with each other, and it is up to the user to translate between them). The subtype is added to BinaryType via the helper type byte_container_with_subtype.

CBOR's RFC 8949 describes this type as:

Major type 2: A byte string. The number of bytes in the string is equal to the argument.

MessagePack's documentation on the bin type family describes this type as:

Bin format family stores a byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.

BSON's specifications describe several binary types; however, this type is intended to represent the generic binary type which has the description:

Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and tools.

None of these impose any limitations on the internal representation other than the basic unit of storage be some type of array whose parts are decomposable into bytes.

The default representation of this binary format is a #!cpp std::vector<std::uint8_t>, which is a very common way to represent a byte array in modern C++.

Template parameters

BinaryType

container type to store arrays

Although not formally expressed as a C++ concept, BinaryType must be default-constructible, copy/move-constructible, and support push_back(), .data(), and .size(), because byte_container_with_subtype derives directly from it. Its value_type must additionally be exactly one byte wide (e.g., std::uint8_t/char/std::byte): the binary serializers (CBOR, MessagePack, BSON, UBJSON) read and write the container's raw bytes via reinterpret_cast, which is only correct for byte-sized elements — a container like #!cpp std::vector<std::intptr_t> will not work as BinaryType. The elements must be stored contiguously, and the binary readers additionally require resize() and operator[]. See Template Parameter Requirements for the full list.

Notes

Default type

The default values for BinaryType is #!cpp std::vector<std::uint8_t>.

Supported byte types

#!cpp std::vector<std::uint8_t>, #!cpp std::vector<char>, and #!cpp std::vector<std::byte> are supported. Regardless of which of them is configured, dump writes the bytes as the numbers 0..255.

Custom BinaryType behavior

When a custom BinaryType is configured (other than the default #!cpp std::vector<std::uint8_t>), you can assign values of that type directly to a basic_json instance, and they will automatically be recognized as binary values rather than arrays:

using custom_json = nlohmann::ordered_json::with_binary_t<std::vector<std::byte>>;

std::vector<std::byte> data{std::byte{1}, std::byte{2}, std::byte{3}};
custom_json j = data;  // Creates a binary value, not an array
assert(j.is_binary());

// Round-tripping works seamlessly
auto extracted = j.get<std::vector<std::byte>>();
assert(extracted == data);

This automatic type detection is a convenience feature that only applies to custom (non-default) BinaryType configurations. The default nlohmann::json continues to treat #!cpp std::vector<std::uint8_t> as arrays for backward compatibility.

Storage

Binary Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of the type #!cpp binary_t* must be dereferenced.

Notes on subtypes

• CBOR

  • Binary values are represented as byte strings. Subtypes are written as tags.

• MessagePack

  • If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1, fixext2, fixext4, fixext8, fixext16) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is then written as the signed 8-bit ext type: subtypes 128 to 255 map to the negative (reserved) ext types, and on reading the ext type is exposed as an unsigned subtype from 0 to 255.
  • If no subtype is given, the bin family (bin8, bin16, bin32) is used.

• BSON

  • If a subtype is given, it is used and added as an unsigned 8-bit integer.
  • If no subtype is given, the generic binary subtype 0x00 is used.

Examples

??? example

The following code shows that `binary_t` is by default, a typedef to
`#!cpp nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>`.
 
```cpp
--8<-- "examples/binary_t.cpp"
```

Output:

```json
--8<-- "examples/binary_t.output"
```

See also

• Binary values - how binary values and subtypes are handled
• Binary formats - formats that can store binary values
• byte_container_with_subtype - container type used by binary values

Version history

• Added in version 3.8.0. Changed the type of subtype to std::uint64_t in version 3.10.0.
• Fixed dump, std::hash, and to_ubjson for byte types that are not integers (e.g., #!cpp std::byte) in version 3.13.0. dump now writes the bytes of a signed byte type (e.g., #!cpp char) as 0..255 rather than as negative numbers.