CBOR.js - JavaScript API
(dCBOR Version)
Abstract
This document describes a JavaScript API for encoding and decoding data in the
CBOR format. Through platform independent definitions of deterministic encoding and
a textual representation of CBOR data, compatible implementations could,
together with the rich set of data types offered by CBOR, provide
a viable alternative for applications that currently use JSON.
Table of Contents
1. Introduction
This document describes a JavaScript API for encoding and decoding data in the
CBOR [RFC8949
] format.
The API loosely mimics the "JSON" object by exposing a single global object,
unsurprisingly named "CBOR".
To minimize the need for application developers having detailed knowledge of CBOR,
the CBOR.js API provides a set of high level wrapper objects.
The wrapper objects are used for encoding CBOR data items,
as well as being the result of CBOR decoding.
The CBOR.js API provides some specific features including:
Note: in this specification CBOR data items are subsequently referred to as CBOR objects.
2. CBOR Wrapper Objects
This section describes the wrapper objects and their specific methods.
Note that using the "new" operator with the wrapper objects
is flagged as an error.
The following table lists the wrapper objects and their relation to
the CBOR objects supported by this specification:
See also Common Wrapper Methods.
2.1. CBOR.Int
| Syntax | CBOR.Int(value) |
|---|
| Description | Constructor. Creates a CBOR integer wrapper object.
See also Integer Numbers. |
|---|
|
| Parameter | Type | Description |
|---|
value | Number | Integer to be wrapped. |
|
| Returns | Description |
|---|
CBOR.Int | Wrapper object. |
2.1.1. CBOR.Int Methods
2.1.1.1. getInt()
| Syntax | getInt() |
|---|
| Description | Reads CBOR integer.
See also getBigInt(). |
|---|
|
| Returns | Description |
|---|
Number | Decoded integer. |
2.2. CBOR.BigInt
| Syntax | CBOR.BigInt(value) |
|---|
| Description | Constructor. Creates a CBOR big integer wrapper object.
See also Integer Numbers. |
|---|
|
| Parameter | Type | Description |
|---|
value | BigInt | Big integer to be wrapped. |
|
| Returns | Description |
|---|
CBOR.BigInt | Wrapper object. |
2.2.1. CBOR.BigInt Methods
2.2.1.1. getBigInt()
| Syntax | getBigInt() |
|---|
| Description | Reads CBOR big integer.
Note: this method is also supported by
CBOR.Int. This is necessary because
the CBOR decoder uses the size of a decoded integer value as the sole mechanism for
selecting between creating a CBOR.Int or a
CBOR.BigInt wrapper object. |
|---|
|
| Returns | Description |
|---|
BigInt | Decoded big integer. |
2.3. CBOR.Float
| Syntax | CBOR.Float(value) |
|---|
| Description | Constructor. Creates a CBOR floating point wrapper object.
See also Floating Point Numbers. |
|---|
|
| Parameter | Type | Description |
|---|
value | Number | Floating point number to be wrapped. |
|
| Returns | Description |
|---|
CBOR.Float | Wrapper object. |
2.3.1. CBOR.Float Methods
2.3.1.1. getFloat()
| Syntax | getFloat() |
|---|
| Description | Reads CBOR floating point object. |
|---|
|
| Returns | Description |
|---|
Number | Decoded floating point number. |
2.3.2. CBOR.Float Properties
2.3.2.1. length
| Name | Type | Description |
|---|
length | Number | Length in bytes of the underlying CBOR IEEE 754 type. |
2.4. CBOR.String
| Syntax | CBOR.String(textString) |
|---|
| Description | Constructor. Creates a CBOR text string wrapper object. |
|---|
|
| Parameter | Type | Description |
|---|
textString | String | String to be wrapped. |
|
| Returns | Description |
|---|
CBOR.String | Wrapper object. |
2.4.1. CBOR.String Methods
2.4.1.1. getString()
| Syntax | getString() |
|---|
| Description | Reads CBOR text string. |
|---|
|
| Returns | Description |
|---|
String | Decoded text string. |
2.5. CBOR.Bytes
| Syntax | CBOR.Bytes(byteString) |
|---|
| Description | Constructor. Creates a CBOR byte string wrapper object. |
|---|
|
| Parameter | Type | Description |
|---|
byteString | Uint8Array | Binary data to be wrapped. |
|
| Returns | Description |
|---|
CBOR.Bytes | Wrapper object. |
2.5.1. CBOR.Bytes Methods
2.5.1.1. getBytes()
| Syntax | getBytes() |
|---|
| Description | Reads CBOR byte string. |
|---|
|
| Returns | Description |
|---|
Uint8Array | Decoded byte string. |
2.6. CBOR.Boolean
| Syntax | CBOR.Boolean(value) |
|---|
| Description | Constructor. Creates a CBOR boolean wrapper object. |
|---|
|
| Parameter | Type | Description |
|---|
value | Boolean | Boolean to be wrapped. |
|
| Returns | Description |
|---|
CBOR.Boolean | Wrapper object. |
2.6.1. CBOR.Boolean Methods
2.6.1.1. getBoolean()
| Syntax | getBoolean() |
|---|
| Description | Reads CBOR boolean. |
|---|
|
| Returns | Description |
|---|
Boolean | Decoded boolean. |
2.7. CBOR.Null
| Syntax | CBOR.Null() |
|---|
| Description | Constructor. Creates a CBOR null wrapper object.
See also isNull(). |
|---|
|
| Returns | Description |
|---|
CBOR.Null | Wrapper object. |
2.8. CBOR.Array
| Syntax | CBOR.Array() |
|---|
| Description | Constructor. Creates a CBOR array wrapper object. |
|---|
|
| Returns | Description |
|---|
CBOR.Array | Wrapper object. |
2.8.1. CBOR.Array Methods
2.8.1.1. add()
| Syntax | add(object) |
|---|
| Description | Adds CBOR wrapper object to the array. |
|---|
|
| Parameter | Type | Description |
|---|
object | CBOR.Wrapper | Object to be appended to the current array. |
|
| Returns | Description |
|---|
this | Current object. |
2.8.1.2. get()
| Syntax | get(index) |
|---|
| Description | Fetches CBOR wrapper object.
If index is out of range, an exception is thrown. |
|---|
|
| Parameter | Type | Description |
|---|
index | Number | Index (0..length-1) of object. |
|
| Returns | Description |
|---|
CBOR.Wrapper | Retrieved object. |
2.8.1.3. toArray()
| Syntax | toArray() |
|---|
| Description | Copies array. |
|---|
|
| Returns | Description |
|---|
Array | Shallow array copy of current CBOR.Wrapper objects |
2.8.1.4. getArray()
| Syntax | getArray() |
|---|
| Description | Get array object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing array elements. |
|---|
|
| Returns | Description |
|---|
CBOR.Array | Current object. |
2.8.2. CBOR.Array Properties
2.8.2.1. length
| Name | Type | Description |
|---|
length | Number | Number of objects in the array. |
2.9. CBOR.Map
| Syntax | CBOR.Map() |
|---|
| Description | Constructor. Creates a CBOR map wrapper object. |
|---|
|
| Returns | Description |
|---|
CBOR.Map | Wrapper object. |
2.9.1. CBOR.Map Methods
2.9.1.1. set()
| Syntax | set(key, value) |
|---|
| Description | Sets map entry.
If key is already defined, an exception is thrown.
Note: key order is of no importance since
Deterministic Encoding
performs the required map sorting automatically. |
|---|
|
| Parameter | Type | Description |
|---|
key | CBOR.Wrapper | Key (name) wrapper object. |
value | CBOR.Wrapper | Value wrapper object. |
|
| Returns | Description |
|---|
this | Current object. |
2.9.1.2. get()
| Syntax | get(key) |
|---|
| Description | Gets map entry.
If key is undefined, an exception is thrown. |
|---|
|
| Parameter | Type | Description |
|---|
key | CBOR.Wrapper | Key (name) wrapper object. |
|
| Returns | Description |
|---|
CBOR.Wrapper | Retrieved object. |
2.9.1.3. getConditional()
| Syntax | getConditional(key, defaultValue) |
|---|
| Description | Gets map entry conditionally. |
|---|
|
| Parameter | Type | Description |
|---|
key | CBOR.Wrapper | Key (name) wrapper object. |
defaultValue | CBOR.Wrapper | Value to return if key does not exist.
defaultValue may be null. |
|
| Returns | Description |
|---|
CBOR.Wrapper | Retrieved or default object. |
2.9.1.4. containsKey()
| Syntax | containsKey(key) |
|---|
| Description | Checks map for key presence. |
|---|
|
| Parameter | Type | Description |
|---|
key | CBOR.Wrapper | Key (name) wrapper object. |
|
| Returns | Description |
|---|
Boolean | true or false. |
2.9.1.5. remove()
| Syntax | remove(key) |
|---|
| Description | Removes map entry.
If key is undefined, an exception is thrown. |
|---|
|
| Parameter | Type | Description |
|---|
key | CBOR.Wrapper | Key (name) wrapper object. |
|
| Returns | Description |
|---|
CBOR.Wrapper | Removed object (value component). |
2.9.1.6. getKeys()
| Syntax | getKeys() |
|---|
| Description | Get map keys. |
|---|
|
| Returns | Description |
|---|
Array | Shallow array copy of current CBOR.Wrapper map keys |
2.9.1.7. getMap()
| Syntax | getMap() |
|---|
| Description | Get map object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing map keys. |
|---|
|
| Returns | Description |
|---|
CBOR.Map | Current object. |
2.9.2. CBOR.Map Properties
2.9.2.1. length
| Name | Type | Description |
|---|
length | Number | Number of map entries. |
2.10. CBOR.Tag
| Syntax | CBOR.Tag(tagNumber, object) |
|---|
| Description | Constructor. Creates a CBOR tag wrapper object. |
|---|
|
| Parameter | Type | Description |
|---|
tagNumber | BigInt | Tag number. |
object | CBOR.Wrapper | Object to be wrapped in a tag. |
|
| Returns | Description |
|---|
CBOR.Tag | Wrapper object. |
2.10.1. CBOR.Tag Methods
2.10.1.1. getTagNumber()
| Syntax | getTagNumber() |
|---|
| Description | Reads CBOR tag number. |
|---|
|
| Returns | Description |
|---|
BigInt | Decoded tag number. |
2.10.1.2. getTaggedObject()
| Syntax | getTaggedObject() |
|---|
| Description | Reads tagged CBOR object. |
|---|
|
| Returns | Description |
|---|
CBOR.Wrapper | Retrieved object. |
2.10.1.3. getTag()
| Syntax | getTag() |
|---|
| Description | Get tag object.
Note: this method is redundant due to the dynamic nature of the JavaScript
typing system. However, if you intend using
checkForUnread(),
this method must be called before accessing the tag object. |
|---|
|
| Returns | Description |
|---|
CBOR.Tag | Current object. |
3. Common Wrapper Methods
The CBOR wrapper objects
support a set of common methods, described in this sub section.
3.1. encode()
| Syntax | encode() |
|---|
| Description | Encodes this object.
|
|---|
|
| Returns | Description |
|---|
Uint8Array | CBOR encoded data. |
3.2. clone()
| Syntax | clone() |
|---|
| Description | Creates a new instance of this object, initialized
with the original CBOR content. |
|---|
|
| Returns | Description |
|---|
CBOR.Wrapper | Copy of object. |
3.3. equals()
| Syntax | equals(object) |
|---|
| Description | Compares this object with another object with respect to CBOR data. |
|---|
|
| Parameter | Type | Description |
|---|
object | CBOR.Wrapper | The object to compare with. |
|
| Returns | Description |
|---|
Boolean | true if this object is equal to object,
otherwise false. |
3.4. toDiag()
| Syntax | toDiag(prettyPrint) |
|---|
| Description | Renders this object in Diagnostic Notation.
In similarity to encode(), this method always produce
data in Deterministic Encoding, irrespective to how
the data was created.
See also: toString(). |
|---|
|
| Parameter | Type | Description |
|---|
prettyPrint | Boolean | If prettyPrint is true,
additional white space is inserted between elements to make the result
easier to read. |
|
| Returns | Description |
|---|
String | Textual version of the wrapped CBOR content. |
3.5. toString()
| Syntax | toString() |
|---|
| Description | Renders this object in Diagnostic Notation.
Equivalent to calling toDiag()
with a true argument. |
|---|
|
| Returns | Description |
|---|
String | Textual version of the wrapped CBOR content. |
3.6. isNull()
| Syntax | isNull() |
|---|
| Description | Checks for CBOR null.
Note: if checkForUnread()
is used, the current object will only be regarded as "read"
if it actually is a CBOR null item. |
|---|
|
| Returns | Description |
|---|
Boolean | Returns true if the current object
holds a CBOR null item, otherwise false
is returned. |
3.7. checkForUnread()
| Syntax | checkForUnread() |
|---|
| Description | Checks if the current object including possible child objects has been read
(like calling getInt()).
If any of the associated objects have not been read, an exception will be thrown.
The purpose of this method is to detect possible misunderstandings between parties
using CBOR based protocols. Together with the strict type checking performed
by the CBOR.js API, a programmatic counterpart to schema based processing
can be achieved.
Note that array get(),
map get(), and
tag getTaggedObject()
only locate objects,
and thus do not count as "read".
Also see
getArray(),
getMap(),
getTag(), and
scan(). |
|---|
|
| Returns | Description |
|---|
this | Current object. |
3.8. scan()
| Syntax | scan() |
|---|
| Description | Scans current object as well as possible child objects
in order to make them appear as "read".
This is only meaningful in conjunction with
checkForUnread(). |
|---|
|
| Returns | Description |
|---|
this | Current object. |
4. Decoding CBOR
CBOR decoding comes in two flavors, binary and
Diagnostic Notation.
Both decoders store the result in the same set of CBOR.Wrapper objects,
used for encoding CBOR data.
This section lists the decoder methods.
4.1. CBOR.decode()
| Syntax | CBOR.decode(cbor) |
|---|
| Description | Decodes a CBOR object.
This method assumes that the CBOR data adheres to
Deterministic Encoding,
otherwise exceptions will be thrown.
Any additional data after the CBOR object will also cause
exceptions to be thrown. |
|---|
|
| Parameter | Type | Description |
|---|
cbor | Uint8Array | The data (bytes) to be decoded. |
|
| Returns | Description |
|---|
CBOR.Wrapper | CBOR wrapper object. |
4.2. CBOR.initExtended()
| Syntax | CBOR.initExtended(cbor, sequenceFlag, nonDeterministic) |
|---|
| Description | Initiates an extended CBOR decoder.
This decoding method presumes that the actual
decoding is performed by one or more (for sequences only) calls to
CBOR.decodeExtended(). |
|---|
|
| Parameter | Type | Description |
|---|
cbor | Uint8Array | The data (bytes) to be decoded. |
sequenceFlag | Boolean | If true, CBOR.decodeExtended()
will return immediately after decoding a CBOR object, otherwise
any additional data after the CBOR object will cause exceptions to be thrown. |
nonDeterministic | Boolean | If true the decoder will accept CBOR code
which violates the Deterministic Encoding rules.
This option may be needed for dealing with "legacy"
CBOR implementations. |
|
| Returns | Description |
|---|
Decoder | Internal decoder object for usage with
CBOR.decodeExtended(). |
4.3. CBOR.decodeExtended()
| Syntax | CBOR.decodeExtended(decoder) |
|---|
| Description | Decodes a CBOR object.
If the sequenceFlag in the call to
CBOR.initExtended()
is true, each call to
CBOR.decodeExtended()
causes the internal decoder to move to the next (possible but unprocessed) CBOR object.
When there is no more data to decode, null is returned. |
|---|
|
| Parameter | Type | Description |
|---|
decoder | Decoder | Internal decoder object. |
|
| Returns | Description |
|---|
CBOR.Wrapper | CBOR wrapper object or null. |
4.4. CBOR.diagDecode()
| Syntax | CBOR.diagDecode(cborText) |
|---|
| Description | Decodes a CBOR object provided in Diagnostic Notation.
See also CBOR.diagDecodeSequence(). |
|---|
|
| Parameter | Type | Description |
|---|
cborText | String | CBOR in textual format. |
|
| Returns | Description |
|---|
CBOR.Wrapper | CBOR wrapper object. |
4.5. CBOR.diagDecodeSequence()
| Syntax | CBOR.diagDecodeSequence(cborText) |
|---|
| Description | Decodes a CBOR object provided in Diagnostic Notation.
Unlike CBOR.diagDecode(),
this method also accepts CBOR sequences, using a comma
character (',') as a separator. |
|---|
|
| Parameter | Type | Description |
|---|
cborText | String | CBOR in textual format. |
|
| Returns | Description |
|---|
Array | Array holding one or more CBOR wrapper objects. |
5. Utility Methods
The following utility methods are unrelated to CBOR but have been included
here because they are a part of the current CBOR.js implementation.
5.1. CBOR.addArrays()
| Syntax | CBOR.addArrays(a, b) |
|---|
| Description | Adds two arrays. |
|---|
|
| Parameter | Type | Description |
|---|
a | Uint8Array | First array. |
b | Uint8Array | Second array. |
|
| Returns | Description |
|---|
Uint8Array | Concatenation of array a and b. |
5.2. CBOR.compareArrays()
| Syntax | CBOR.compareArrays(a, b) |
|---|
| Description | Compares two arrays lexicographically. |
|---|
|
| Parameter | Type | Description |
|---|
a | Uint8Array | First array. |
b | Uint8Array | Second array. |
|
| Returns | Description |
|---|
Number | If a and b are identical,
0 is retuned.
If a > b,
a positive number is returned.
If a < b,
a negative number is returned. |
5.3. CBOR.toHex()
| Syntax | CBOR.toHex(byteArray) |
|---|
| Description | Encodes binary data to hexadecimal. |
|---|
|
| Parameter | Type | Description |
|---|
byteArray | Uint8Array | Zero or more bytes to be encoded. |
|
| Returns | Description |
|---|
String | Hexadecimal encoded data. |
5.4. CBOR.fromHex()
| Syntax | CBOR.fromHex(hexString) |
|---|
| Description | Decodes hexadecimal data into binary. |
|---|
|
| Parameter | Type | Description |
|---|
hexString | String | String with zero or more hexadecimal pairs. Each pair represents one byte. |
|
| Returns | Description |
|---|
Uint8Array | The resulting binary (bytes). |
5.5. CBOR.toBase64Url()
| Syntax | CBOR.toBase64Url(byteArray) |
|---|
| Description | Encodes binary data to base64Url. |
|---|
|
| Parameter | Type | Description |
|---|
byteArray | Uint8Array | Zero or more bytes to be encoded. |
|
| Returns | Description |
|---|
String | Base64Url encoded data. |
5.6. CBOR.fromBase64Url()
| Syntax | CBOR.fromBase64Url(base64) |
|---|
| Description | Decodes base64Url encoded data into binary.
Note that this method is permissive; it accepts
base64 encoded data as well as data with or without
'=' padding. |
|---|
|
| Parameter | Type | Description |
|---|
base64 | String | String in base64Url notation. The string may be empty. |
|
| Returns | Description |
|---|
Uint8Array | The resulting binary (bytes). |
6. JavaScript Number Considerations
Since JavaScript natively only supports Number (backed
by 64-bit IEEE 754 floating point data), and BigInt
(offering unlimited integers), it is important to understand how these
number types are mapped to CBOR which offers
two variants of integers and three variants of floating point types.
6.1. Integer Numbers
Due to the Number.MAX_SAFE_INTEGER limitation, CBOR documents and
protocols using integer elements where the magnitude may exceed
253
-1, must
for such elements turn to BigInt,
otherwise run-time errors may occur when accessing integer data using
getInt() or
during creation of integers using
CBOR.Int().
That is, for creation of such integers,
CBOR.BigInt()
is the proper solution, while access requires
getBigInt().
Note that the selection between CBOR.BigInt()
and CBOR.Int() only affects the maximum
numeric range with respect to JavaScript, not the CBOR encoding.
The selection between the CBOR unsigned and negative
integer variants is dealt with by the CBOR.js implementation;
transparent to the API.
6.2. Floating Point Numbers
Although CBOR encoding depends on 16, 32, and 64-bit IEEE 754
variants, the CBOR.js implementation makes this
transparent; the API only exposes the Number type.
See also CBOR.Float().
7. Diagnostic Notation
Creating CBOR data in diagnostic notation (as described in section 8 of RFC 8949),
is provided by the toString() method.
However, through the CBOR.diagDecode()
method, CBOR data may also be provided in diagnostic (textual) notation,
making CBOR useful for local "config" and test data files as well.
The following table shows how CBOR objects should be represented in
diagnostic notation:
| CBOR Object | Syntax | Notes | Description |
|---|
|
/ comment text / |
8 |
Multi-line comment.
Multi-line comments are treated as whitespace and may thus also be used
between CBOR objects.
|
# comment text |
7, 8 |
Single-line comment.
Single-line comments are terminated by a newline character ('\n') or EOF.
Single-line comments may also terminate lines holding regular CBOR items.
|
// comment text |
| integer |
{sign}{0b|0o|0x}n |
1, 2 |
Arbitrary sized integers without fractional components or exponents.
See also CBOR integer encoding.
For input data in diagnostic notation, binary, octal, and hexadecimal notation
is also supported by prepending numbers with 0b, 0o, and 0x respectively.
The latter also permit arbitrary insertions of '_' characters between digits to
enable grouping of data like 0b100_000000001.
|
| bignum |
| floating point |
{sign}n.n{e±n} |
1, 2 |
Floating point values
must include a decimal point and an optional exponent.
See also CBOR floating point encoding.
|
NaN |
|
Not a number.
See also CBOR floating point encoding.
|
{sign}Infinity |
2 |
Infinity.
See also CBOR floating point encoding.
|
| byte string |
h'hex data' |
3, 6 |
Byte data provided in hexadecimal notation.
Each byte must be represented by two hexadecimal digits.
|
b64'base64 data' |
3, 6, 8 |
Byte data provided in base64 or base64URL notation.
Padding with '=' characters is optional.
|
'text' |
4, 5, 8 |
Byte data provided as UTF-8 encoded text. |
<< object >> |
8 |
Construct holding a CBOR object which is subsequently embedded in a byte string. |
| text string |
"text"
| 4, 5 |
UTF-8 encoded text string. |
| true |
true |
|
Boolean value. |
| false | false |
| null |
null |
|
Null value. |
| array |
[ objects ] |
|
Array with zero or more comma separated CBOR objects. |
| map |
{ key:value } |
|
Map with zero or more comma separated key/value pairs.
Keys and values are expressed as CBOR objects.
|
| tag |
n( object ) |
1 |
Tag holding a CBOR object. |
|
, |
8 |
Separator character for CBOR sequences. |
- The letter n in the Syntax column denotes one or more digits.
- The optional {sign} must be a single hyphen (
'-') character.
-
Whitespace characters
(
' ', '\t', '\r', '\n')
inside of string quotes are ignored.
-
Whitespace characters
(
'\t', '\r', '\n')
inside of string quotes become a part of the text.
To avoid getting newline characters ('\n')
included in multi-line text strings,
a line continuation marker consisting of a backslash ('\')
immediately preceding the newline may be used.
-
Text strings may also include JavaScript compatible escape sequences
(
'\'', '\"', '\\',
'\b', '\f', '\n',
'\r', '\t', '\uhhhh').
- Zero-length strings (
'') return byte strings of length zero.
- The IETF have yet to define a single line comment.
-
Only applicable for input.
That is, toString() does not produce this item.
8. Deterministic Encoding
Note: This section has not yet been updated to match dCBOR.
While there are different ways you can encode certain CBOR objects,
this is non-trivial to support in a generic platform API without
adding complexity and that for little provable gain.
Therefore the CBOR.js API defines specific (non-variant)
encodings, aka "Deterministic Encoding". The chosen encoding
model is compatible with most existing CBOR decoders.
However, to not limit CBOR.js to new applications only,
deterministic encoding checking may optionally be turned off
for accepting input from "legacy" CBOR encoders.
The encoding scheme adheres to section 4.2 of RFC 8949, but adds
a few constraints (denoted by RFC+), where the RFC offers choices.
The encoding rules are as follows:
-
RFC: Integers, represented by the integer and
bignum types, must use the integer
type if the value is between
-2
64
and 264
-1,
otherwise the bignum type must be used.
The following table holds a few sample values and their proper CBOR encoding:
| Value | Encoding |
|---|
| 0 | 00 |
| -1 | 20 |
| 255 | 18ff |
| 256 | 190100 |
| -256 | 38ff |
| -257 | 390100 |
| 1099511627775 | 1b000000ffffffffff |
| 18446744073709551615 | 1bffffffffffffffff |
| 18446744073709551616 | c249010000000000000000 |
| -18446744073709551616 | 3bffffffffffffffff |
| -18446744073709551617 | c349010000000000000000 |
Note that integers must not be supplied with
leading zero bytes (like 1900ff) unless the
CBOR representation offers no alternative (like 1b000000ffffffffff).
Note that the integer encoding scheme above does not always return the
most compact representation; the value
1099511627775
(0xffffffffff)
would actually yield two bytes less using the bignum type.
-
RFC+: Floating point data must use the shortest IEEE 754
variant and associated CBOR encoding.
The following table holds floating point values needing special considerations
as well as a small set of "edge cases":
| Value | Encoding |
|---|
| 0.0 | f90000 |
| -0.0 | f98000 |
| Infinity | f97c00 |
| -Infinity | f9fc00 |
| NaN | f97e00 |
| Assorted Edge Cases |
|---|
| -5.960464477539062e-8 | fbbe6fffffffffffff |
| -5.9604644775390625e-8 | f98001 |
| -5.960464477539064e-8 | fbbe70000000000001 |
| -5.960465188081798e-8 | fab3800001 |
| 0.00006097555160522461 | f903ff |
| 65504.0 | f97bff |
| 65504.00390625 | fa477fe001 |
| 65536.0 | fa47800000 |
| 10.559998512268066 | fa4128f5c1 |
| 10.559998512268068 | fb40251eb820000001 |
| 3.4028234663852886e+38 | fa7f7fffff |
| 3.402823466385289e+38 | fb47efffffe0000001 |
| 1.401298464324817e-45 | fa00000001 |
| 1.1754942106924411e-38 | fa007fffff |
| 5.0e-324 | fb0000000000000001 |
| -1.7976931348623157e+308 | fbffefffffffffffff |
Note that NaN "signaling" (like f97e01),
must be flagged as an error.
Note that the shortest encoding may result in subnormal
numbers like f98001.
-
RFC+: Floating point and integer objects must be treated as distinct types
regardless of their numeric value, which is compliant with
Rule 2 in section 4.2.2 as well
as with the table in Appendix A of RFC 8949.
-
RFC: Map keys must be sorted in the bytewise lexicographic
order of their deterministic encoding.
Duplicate keys must be rejected.
-
RFC+: Since CBOR encoding according to this specification
maintains type and data uniqueness, there are no specific restrictions or
tests needed in order to determine map key equivalence.
As an example, the floating point numbers 0.0 and
-0.0, and the integer number 0
represent the distinct keys
f90000, f98000, and 00 respectively.
-
RFC+: Deterministic CBOR according to this specification
may also be provided in
Diagnostic Notation.
9. Version
Version: pre-release 2023-08-01