json/features/binary_formats.md

Binary Formats

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance, over a network. Hence, the library supports

• BJData (Binary JData),
• BON8 (Binary Object Notation 8),
• BSON (Binary JSON),
• CBOR (Concise Binary Object Representation),
• MessagePack, and
• UBJSON (Universal Binary JSON)

to efficiently encode JSON values to byte vectors and to decode such vectors.

Comparison

Completeness

Format	Serialization	Deserialization
BJData	complete	incomplete: no column-major ND-arrays, no Draft 4 SoA/extension types
BON8	incomplete: no unsigned integers above int64	complete
BSON	incomplete: top-level value must be an object	incomplete, but all JSON types are supported
CBOR	complete	incomplete, but all JSON types are supported
MessagePack	complete	incomplete, but all JSON types are supported
UBJSON	complete	complete

Binary values

Format	Binary values	Binary subtypes
BJData	supported (Draft 3 only)	not supported
BON8	not supported	not supported
BSON	supported	supported
CBOR	supported	supported
MessagePack	supported	supported
UBJSON	not supported	not supported

See binary values for more information.

Sizes

Format	canada.json	twitter.json	citm_catalog.json	jeopardy.json
BJData	53.2 %	91.1 %	78.1 %	96.6 %
BJData (size)	58.6 %	92.1 %	86.7 %	97.4 %
BJData (size+type)	58.6 %	92.1 %	86.5 %	97.4 %
BON8	50.5 %	83.8 %	63.5 %	87.5 %
BSON	85.8 %	95.2 %	95.8 %	106.7 %
CBOR	50.5 %	86.3 %	68.4 %	88.0 %
MessagePack	50.5 %	86.0 %	68.5 %	87.9 %
UBJSON	53.2 %	91.3 %	78.2 %	96.6 %
UBJSON (size)	58.6 %	92.3 %	86.8 %	97.4 %
UBJSON (size+type)	55.9 %	92.3 %	85.0 %	95.0 %

Size of each test file in each format, in percent of the minified JSON value; the smallest size per file is printed in bold. The (size) and (size+type) rows are written with the `use_size` and `use_type` options of [`to_bjdata`](../../api/basic_json/to_bjdata.md) and [`to_ubjson`](../../api/basic_json/to_ubjson.md).

​JData 53.2 %; B​ON8 50.5 %; B​SON 85.8 %; C​BOR 50.5 %; MessagePack 50.5 %; U​BJSON 53.2 %. Smallest: B​ON8 and C​BOR and MessagePack. canada.json 0 % 50 % B​JData B​ON8 B​SON C​BOR MessagePack U​BJSON minified J​SON = 100 % 100 % 53.2 % 50.5 % 85.8 % 50.5 % 50.5 % 53.2 %

​JData 91.1 %; B​ON8 83.8 %; B​SON 95.2 %; C​BOR 86.3 %; MessagePack 86 %; U​BJSON 91.3 %. Smallest: B​ON8. twitter.json 0 % 50 % B​JData B​ON8 B​SON C​BOR MessagePack U​BJSON minified J​SON = 100 % 100 % 91.1 % 83.8 % 95.2 % 86.3 % 86.0 % 91.3 %

​JData 78.1 %; B​ON8 63.5 %; B​SON 95.8 %; C​BOR 68.4 %; MessagePack 68.5 %; U​BJSON 78.2 %. Smallest: B​ON8. citm_catalog.json 0 % 50 % B​JData B​ON8 B​SON C​BOR MessagePack U​BJSON minified J​SON = 100 % 100 % 78.1 % 63.5 % 95.8 % 68.4 % 68.5 % 78.2 %

​JData 96.6 %; B​ON8 87.5 %; B​SON 106.7 %; C​BOR 88 %; MessagePack 87.9 %; U​BJSON 96.6 %. Smallest: B​ON8. jeopardy.json 0 % 50 % B​JData B​ON8 B​SON C​BOR MessagePack U​BJSON minified J​SON = 100 % 100 % 96.6 % 87.5 % 106.7 % 88.0 % 87.9 % 96.6 %

The table above as charts: size per base format relative to minified JSON (vertical line at 100 %); the smallest format per file is drawn in a stronger colour than the others. The size and size+type variants of BJData and UBJSON are omitted here; see the table.

See also

• cbor_tag_handler_t - how CBOR tags are handled when parsing
• JSON_STRICT_BINARY_UTF8 - reject ill-formed UTF-8 in strings
• Binary values - binary values and subtypes
• to_cbor - / from_cbor, to_msgpack / from_msgpack, to_bson / from_bson, to_ubjson / from_ubjson, to_bjdata / from_bjdata, to_bon8 / from_bon8 - the conversion functions
• Parsing untrusted input - harden an application that parses untrusted binary data
• SAX interface - decode binary formats without building a value