[ceph.git] / ceph / src / jaegertracing / opentelemetry-cpp / third_party / nlohmann-json / doc / mkdocs / docs / features / binary_formats / index.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

- [BSON](bson.md) (Binary JSON),
- [CBOR](cbor.md) (Concise Binary Object Representation),
- [MessagePack](messagepack.md), and
- [UBJSON](ubjson.md) (Universal Binary JSON)

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

## Comparison

### Completeness

| Format      | Serialization                                 | Deserialization                              |
|-------------|-----------------------------------------------|----------------------------------------------|
| 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                                      | complete                                     |
| UBJSON      | complete                                      | complete                                     |

### Binary values

| Format      | Binary values | Binary subtypes |
|-------------|---------------|-----------------|
| BSON        | supported     | supported       |
| CBOR        | supported     | supported       |
| MessagePack | supported     | supported       |
| UBJSON      | not supported | not supported   |

See [binary values](../binary_values.md) for more information.

### Sizes

| Format             | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
|--------------------|-------------|--------------|-------------------|---------------|
| BSON               | 85,8 %      | 95,2 %       | 95,8 %            | 106,7 %       |
| CBOR               | 50,5 %      | 86,3 %       | 68,4 %            | 88,0 %        |
| MessagePack        | 50,6 %      | 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 %        |

Sizes compared to minified JSON value.
Commit	Line	Data
1e59de90 TL	1	# Binary Formats
	2
	3	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
	4
	5	- [BSON](bson.md) (Binary JSON),
	6	- [CBOR](cbor.md) (Concise Binary Object Representation),
	7	- [MessagePack](messagepack.md), and
	8	- [UBJSON](ubjson.md) (Universal Binary JSON)
	9
	10	to efficiently encode JSON values to byte vectors and to decode such vectors.
	11
	12	## Comparison
	13
	14	### Completeness
	15
	16	\| Format \| Serialization \| Deserialization \|
	17	\|-------------\|-----------------------------------------------\|----------------------------------------------\|
	18	\| BSON \| incomplete: top-level value must be an object \| incomplete, but all JSON types are supported \|
	19	\| CBOR \| complete \| incomplete, but all JSON types are supported \|
	20	\| MessagePack \| complete \| complete \|
	21	\| UBJSON \| complete \| complete \|
	22
	23	### Binary values
	24
	25	\| Format \| Binary values \| Binary subtypes \|
	26	\|-------------\|---------------\|-----------------\|
	27	\| BSON \| supported \| supported \|
	28	\| CBOR \| supported \| supported \|
	29	\| MessagePack \| supported \| supported \|
	30	\| UBJSON \| not supported \| not supported \|
	31
	32	See [binary values](../binary_values.md) for more information.
	33
	34	### Sizes
	35
	36	\| Format \| canada.json \| twitter.json \| citm_catalog.json \| jeopardy.json \|
	37	\|--------------------\|-------------\|--------------\|-------------------\|---------------\|
	38	\| BSON \| 85,8 % \| 95,2 % \| 95,8 % \| 106,7 % \|
	39	\| CBOR \| 50,5 % \| 86,3 % \| 68,4 % \| 88,0 % \|
	40	\| MessagePack \| 50,6 % \| 86,0 % \| 68,5 % \| 87,9 % \|
	41	\| UBJSON \| 53,2 % \| 91,3 % \| 78,2 % \| 96,6 % \|
	42	\| UBJSON (size) \| 58,6 % \| 92,3 % \| 86,8 % \| 97,4 % \|
	43	\| UBJSON (size+type) \| 55,9 % \| 92,3 % \| 85,0 % \| 95,0 % \|
	44
	45	Sizes compared to minified JSON value.