CBOR

Concise Binary Object Representation (CBOR) is a binary data serialization format loosely based on JSON. Like JSON it allows the transmission of data objects that contain name–value pairs, but in a more concise manner. This increases processing and transfer speeds at the cost of human-readability. It is defined in IETF RFC 8949.[1]

CBOR

Filename extension	.cbor
Internet media type	application/cbor
Type of format	Data interchange
Standard	RFC 8949
Open format?	Yes
Website	cbor.io

Amongst other uses, it is the recommended data serialization layer for the CoAP Internet of Things protocol suite[2] and the data format on which COSE messages are based. It is also used in the Client-to-Authenticator Protocol (CTAP) within the scope of the FIDO2 project.[3]

Specification of the CBOR encoding

CBOR encoded data is seen as a stream of data items. E.g.

CBOR data	Data item 1				Data item 2				Data item X...
Byte count	1 byte (CBOR data item header)		Variable	Variable	1 byte (CBOR data item header)		Variable	Variable	etc...
Structure	Major type	Additional information	Payload length (optional)	Data payload (optional)	Major type	Additional information	Payload length (optional)	Data payload (optional)	etc...
Bit count	3 Bits	5 Bits	8 Bits × variable	8 Bits × variable	3 Bits	5 Bits	8 Bits × variable	8 Bits × variable	etc..

Major type and additional type handling in each data item

Each data item behaviour is defined by the major type and additional type. The major type is used for selecting the main behaviour or type of each data item.

The additional type is additional information whose exact behaviour is dependent on the major type value.

Tiny Field Encoding

Byte count	1 byte (CBOR data item header)
Structure	Major type	Additional information (Value)
Bit count	3 Bits	5 Bits

Short Field Encoding

Byte count	1 byte (CBOR data item header)		Variable
Structure	Major type	Additional information	Value
Bit count	3 Bits	5 Bits	8 Bits × (Value_Field_Byte_Count)

Long Field Encoding

Byte count	1 byte (CBOR data item header)		Variable	Variable
Structure	Major type	Additional information (Size Of Length Field)	Payload length (Length Of Value Field)	Value
Bit count	3 Bits	5 Bits	8 Bits × (Length_Field_Byte_Count)	8 Bits × (Value_Field_Byte_Count)

CBOR data item header

The table below illustrates how the CBOR data item header works.

Major type	Major type value		Additional type value (unsigned)	Additional type meaning	Item Size In Bytes	Field Encoding Type
Positive/Unsigned integer	0	0b000	The 5-bit additional information is either the integer itself (for additional information values 0 through 23) or the length of additional data.
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the data value. Thus keeping a compact size.	1	Tiny
			24	Next byte is uint8_t in data value section	2	Short
			25	Next 2 bytes uint16_t in data value section	3	Short
			26	Next 4 bytes is uint32_t in data value section	5	Short
			27	Next 8 bytes is uint64_t in data value section	9	Short
			...	...	...	...
			31	...	...	...
Negative integer	1	0b001	The encoding follows the rules for unsigned integers (major type 0), except that the value is then -1 minus the encoded unsigned integer.
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the data value. Thus keeping a compact size.	1	Tiny
			24	Next byte is uint8_t in data value section	2	Short
			25	Next 2 bytes uint16_t in data value section	3	Short
			26	Next 4 bytes is uint32_t in data value section	5	Short
			27	Next 8 bytes is uint64_t in data value section	9	Short
			...	...	...	...
			31	...	...	...
Byte string	2	0b010	The string's length in bytes is represented following the rules for positive integers (major type 0).
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the data length specifier. Thus keeping a compact size.	up to 1+23	Short
			24	Next byte is uint8_t for payload length	up to 2+2^8-1	Long
			25	Next 2 bytes uint16_t for payload length	up to 3+2^16-1	Long
			26	Next 4 bytes is uint32_t for payload length	up to 5+2^32-1	Long
			27	Next 8 bytes is uint64_t for payload length	up to 9+2^64-1	Long
			...	...	...	...
			31	Start of Indefinite String: Concatenation of definite-length strings, till next corresponding "Break" Code.	1	Tiny
Text string	3	0b011	A text string, specifically a string of Unicode characters that is encoded as UTF-8 [RFC3629].
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the data length specifier. Thus keeping a compact size.	up to 1+23	Short
			24	Next byte is uint8_t for payload length	up to 2+2^8-1	Long
			25	Next 2 bytes uint16_t for payload length	up to 3+2^16-1	Long
			26	Next 4 bytes is uint32_t for payload length	up to 5+2^32-1	Long
			27	Next 8 bytes is uint64_t for payload length	up to 9+2^64-1	Long
			...	...	...	...
			31	Start of Indefinite String: Concatenation of definite-length strings, till next corresponding "Break" Code.	1	Tiny
Array of data items	4	0b100	Arrays are also called lists, sequences, or tuples. The length denotes the number of data items in array rather than the byte length.
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the item count specifier. Thus keeping a compact size.	1	Tiny
			24	Next byte is uint8_t for payload length	2	Short
			25	Next 2 bytes uint16_t for payload length	3	Short
			26	Next 4 bytes is uint32_t for payload length	5	Short
			27	Next 8 bytes is uint64_t for payload length	9	Short
			...	...	...	...
			31	Start of Indefinite Array till next corresponding "Break" Code.	1	Tiny
Map of pairs of data items	5	0b101	A map of pairs of data items. Maps are also called tables, dictionaries, hashes, or objects (in JSON). The length denotes the number of pairs of data items rather than the byte length. Every map entry takes two data items in sequential order, a key data item and a value data item.
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the item count specifier. Thus keeping a compact size.	1	Tiny
			24	Next byte is uint8_t for payload length	2	Short
			25	Next 2 bytes uint16_t for payload length	3	Short
			26	Next 4 bytes is uint32_t for payload length	5	Short
			27	Next 8 bytes is uint64_t for payload length	9	Short
			...	...	...	...
			31	Start of indefinite map till next corresponding "break" code.	1	Tiny
Semantic tag	6	0b110	Used for optional semantic tagging of other major types
			Value Field represents Tag ID: Refer to https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml for the semantic meaning of each tag.
			0 to 23 (0x0 to 0x17) (0b00000 to 0b10111)	Used directly as the data value. Thus keeping a compact size.	1	Tiny
			24	Next byte is uint8_t in data value section	2	Short
			25	Next 2 bytes uint16_t in data value section	3	Short
			26	Next 4 bytes is uint32_t in data value section	5	Short
			27	Next 8 bytes is uint64_t in data value section	9	Short
			...	...	...	...
			31	...	1	...
Primitives e.g. break, float, simple values	7	0b111	floating-point numbers and simple data types that need no content, as well as the "break" stop code[4]
			0..19	(Unassigned)	1	Tiny
			20	False	1	Tiny
			21	True	1	Tiny
			22	Null	1	Tiny
			23	Undefined	1	Tiny
			24	Next Byte is uint8_t as Simple value (value 32..255)	2	Short
			25	Next 2 Bytes uint16_t as IEEE 754 half-precision float	3	Short
			26	Next 4 Bytes is uint32_t as IEEE 754 single-precision float	5	Short
			27	Next 8 Bytes is uint64_t as IEEE 754 double-precision float	9	Short
			28	Unassigned
			29
			30
			31	"break" stop code for indefinite-length items	1	Tiny

• Byte = 8 bits

Primitives (Major type = 7)

The primitives major type has a major type value of 7. It is used for simple data types, common complex float types, as well as control code.

	Major type	Additional value	Extra bytes (if required)
Bytes	0		1	2	3	4	5	6	7	8
Bit size	3 bits	5 bits	8	8	8	8	8	8	8	8
Simple value 0 to 23 (value X)	7	X=0...23	Not used
Simple value 24 to 255 (value X)	7	24	X=32...255	Not used
IEEE 754 half-precision float (16 bits follow)	7	25	16 bits IEEE 754		Not used
IEEE 754 single-precision float (32 bits follow)	7	26	32 bits IEEE 754				Not used
IEEE 754 double-precision float (64 bits follow)	7	27	64 bits IEEE 754
Break from indefinite array or map	7	31	Not used

Break control code (Additional type value = 31)

This is a meta value, that is used in conjunction with arrays and maps set to indefinite length mode. This indicates to the CBOR parser to close the corresponding map or array level.

IEEE 754 Floats (Additional type value = 25 or 26 or 27)

This allows for storing floats, encoded as IEEE 754 float values.

Simple value

Most simple values are either unassigned or reserved for future improvements.

However these are defined.

Simple value	Semantic
20	Boolean false
21	Boolean true
22	Null
23	Undefined

Semantic Tag Registration

IANA has created the CBOR tags registry, located in https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml . Registration must contain these template.

Semantic tag type	Range	Template
		Data item	Semantic description (Short Form)	Point of contact	Description of semantics (URL)
Standard actions	0–23	Required	Required	N/A	N/A
Specification required	24–255	Required	Required	N/A	N/A
First Come First Served	256–18446744073709551615	Required	Required	Required	Description is optional. The URL can point to an Internet-Draft or a web page.

https://www.rfc-editor.org/rfc/rfc8949.html#name-cbor-tags-registry

Implementations

Name	Primary author	Language	License	Source	Remarks
cbor-js	Patrick Gansterer	JavaScript	MIT	https://github.com/paroga/cbor-js
node-cbor	Joe Hildebrand	JavaScript	MIT	https://github.com/hildjj/node-cbor
CBOREncode	Pavel Gulbin	PHP	PHP	https://github.com/2tvenom/CBOREncode
cbor	Faye Amacker	Go	MIT	https://github.com/fxamacker/cbor	Safe & fast, CBOR tags, float64/32/16, duplicate map key detection, API is encoding/json + toarray & keyasint struct tags, Canonical CBOR, CTAP2, fuzz tested.
cbor	Pavel Gulbin	Go	WTFPL	https://github.com/2tvenom/cbor
cbor_go	Brian Olson	Go	APL 2.0	https://github.com/brianolson/cbor_go
go-codec	Ugorji Nwoke	Go	MIT	https://godoc.org/github.com/ugorji/go/codec	Also handles JSON, MsgPack and BinC.
serde_cbor	Pyfisch	Rust	MIT or APL 2.0	https://github.com/pyfisch/cbor
cbor-codec	Toralf Wittner	Rust	MPL 2.0	https://twittner.gitlab.io/cbor-codec/cbor/
SwiftCBOR	[email protected]	Swift	Unlicense	https://github.com/myfreeweb/SwiftCBOR
CBOR.jl	Saurav Sachidanand	Julia	MIT	https://github.com/saurvs/CBOR.jl
Lua-CBOR	Kim Alvefur	Lua	MIT	https://www.zash.se/lua-cbor.html
org.conman.cbor	Sean Conner	Lua	LGPL-3	https://github.com/spc476/CBOR
cbor_py	Brian Olson	Python	APL 2.0	https://github.com/brianolson/cbor_py
flynn	Fritz Conrad Grimpen	Python	MIT	https://github.com/fritz0705/flynn
cbor2	Alex Grönholm	Python	MIT	https://github.com/agronholm/cbor2
CBOR::Free	Felipe Gasper	Perl	Artistic & GPL	https://metacpan.org/pod/CBOR::Free
CBOR::PP	Felipe Gasper	Perl	Artistic & GPL	https://metacpan.org/pod/CBOR::PP
CBOR::XS	Marc Lehmann	Perl	GPL-3	https://metacpan.org/pod/CBOR::XS
cbor-ruby	Sadayuki Furuhashi Carsten Bormann	Ruby	APL 2.0	https://github.com/cabo/cbor-ruby
libcbor-ruby	Pavel Kalvoda	Ruby	MIT	https://github.com/PJK/libcbor-ruby	Binding to libcbor.
cbor-erlang	Jihyun Yu	Erlang	BSD-3-clause	https://github.com/yjh0502/cbor-erlang
excbor	Carsten Bormann	Elixir	not specified, ask the author	https://github.com/cabo/excbor
CBOR	R. Kyle Murphy	Haskell	LGPL-3	https://github.com/orclev/CBOR
borc	Joe Hildebrand Friedel Ziegelmayer	JavaScript	MIT	https://github.com/dignifiedquire/borc	Fork of node-cbor.
borc-refs	Joe Hildebrand Friedel Ziegelmayer Sandro Hawke	JavaScript	MIT	https://github.com/sandhawke/borc-refs	Fork of borc.
CBOR	Peter Occil	C#	Public domain software	https://github.com/peteroupc/CBOR	Also handles JSON.
Dahomey.Cbor	Michaël Catanzariti	C#	MIT License	https://github.com/dahomey-technologies/Dahomey.Cbor
Jackson	Tatu Saloranta	Java	APL-2.0	https://github.com/FasterXML/jackson-dataformats-binary/tree/master/cbor	Also handles other formats.
cbor-java	Constantin Rack	Java	APL-2.0	https://github.com/c-rack/cbor-java
jacob	J.W. Janssen	Java	APL-2.0	https://github.com/jawi/jacob
kotlinx.serialization	JetBrains	Kotlin	APL-2.0	https://github.com/Kotlin/kotlinx.serialization	Supports cross-platform
cn-cbor	Joe Hildebrand Carsten Bormann	C	MIT	https://github.com/cabo/cn-cbor
cbor-cpp	Stanislav Ovsyannikov	C++	APL-2.0	https://github.com/naphaso/cbor-cpp
cppbor	David Preece	C++	BSD	https://github.com/rantydave/cppbor	Uses C++17 variants.
libcbor	Pavel Kalvoda	C	MIT	https://github.com/PJK/libcbor
tinycbor	Intel	C	MIT	https://github.com/01org/tinycbor
NanoCBOR	Koen Zandberg	C	LGPL	https://github.com/bergzand/NanoCBOR	Used by RIOT-OS
cbor-d	Andrey Penechko	D	Boost 1.0	https://github.com/MrSmith33/cbor-d
clj-cbor	Greg Look	Clojure	Unlicense	https://github.com/greglook/clj-cbor
JSON for Modern C++	Niels Lohmann	C++	MIT	https://github.com/nlohmann/json	Also handles JSON and MsgPack.
borabora	Christoph Engelbert	Java	APL-2.0	https://github.com/noctarius/borabora
lua-ConciseSerialization	François Perrad	Lua	MIT	https://web.archive.org/web/20170322112326/https://fperrad.github.io/lua-ConciseSerialization/
flunn	Fritz Conrad Grimpen Sokolov Yura	Python	MIT	https://pypi.python.org/pypi/flunn
cbor-qt	Anton Dutov	C++	Public domain	https://github.com/anton-dutov/cbor-qt
QCborValue	Qt Project	C++	LGPL	https://doc.qt.io/qt-5/qcborvalue.html	Part of the Qt framework since version 5.12
cbor11	Jakob Varmose Bentzen	C++	Public domain	https://github.com/jakobvarmose/cbor11
cborcpp	Alex Nekipelov	C++	MIT	https://github.com/nekipelov/cborcpp
GoldFish	Vincent Lascaux	C++	MIT	https://github.com/OneNoteDev/GoldFish
Library-Arduino-Cbor	Juanjo Tara	C++	APL-2.0	https://github.com/jjtara/Library-Arduino-Cbor
cborg	Duncan Coutts	Haskell	BSD-3-clause	https://github.com/well-typed/cborg
cbor	Steve Hamblett	Dart	MIT	https://github.com/shamblett/cbor
borer	Mathias Doenitz	Scala	MPL 2.0	https://github.com/sirthias/borer	Also handles JSON.
nim_cbor	Emery Hemingway	Nim	MIT	https://git.sr.ht/~ehmry/nim_cbor
ciborium	Nathaniel McCallum Mark Bestavros Enarx Team	Rust	Apache 2.0	https://github.com/enarx/ciborium

See also

• Comparison of binary data serialization formats

References

1. "CBOR — Concise Binary Object Representation | Overview".
2. "CoAP — Constrained Application Protocol | Overview".
3. "FIDO2 Project". FIDO Alliance. Retrieved 2018-05-11.
4. RFC 8949. doi:10.17487/RFC8949.

External links

• Online tool to convert from CBOR binary to textual representation and back.