CBOR JavaScript API

CBOR.js - JavaScript API

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.

1. Introduction

2. CBOR Wrapper Objects

2.1. CBOR.Int

2.1.1. CBOR.Int Methods

2.1.1.1. getInt()

2.1.1.2. getBigInt()

2.2. CBOR.BigInt

2.2.1. CBOR.BigInt Methods

2.2.1.1. getBigInt()

2.3. CBOR.Float

2.3.1. CBOR.Float Methods

2.3.1.1. getFloat()

2.3.2. CBOR.Float Properties

2.3.2.1. length

2.4. CBOR.String

2.4.1. CBOR.String Methods

2.4.1.1. getString()

2.5. CBOR.Bytes

2.5.1. CBOR.Bytes Methods

2.5.1.1. getBytes()

2.6. CBOR.Boolean

2.6.1. CBOR.Boolean Methods

2.6.1.1. getBoolean()

2.7. CBOR.Null

2.8. CBOR.Array

2.8.1. CBOR.Array Methods

2.8.2. CBOR.Array Properties

2.8.2.1. length

2.9. CBOR.Map

2.9.1. CBOR.Map Methods

2.9.1.1. set()

2.9.1.2. get()

2.9.1.3. getConditional()

2.9.1.4. containsKey()

2.9.1.5. remove()

2.9.1.6. getKeys()

2.9.1.7. getMap()

2.9.1.8. setSortingMode()

2.9.2. CBOR.Map Properties

2.9.2.1. length

2.10. CBOR.Tag

2.10.1. CBOR.Tag Methods

2.10.1.1. getTagNumber()

2.10.1.2. getTaggedObject()

2.10.1.3. getTag()

3. Common Wrapper Methods

3.7. checkForUnread()

3.8. scan()

4. Decoding CBOR

4.1. CBOR.decode()

4.2. CBOR.initExtended()

4.3. CBOR.decodeExtended()

4.4. CBOR.diagDecode()

4.5. CBOR.diagDecodeSequence()

5. Utility Methods

5.1. CBOR.addArrays()

5.2. CBOR.compareArrays()

5.3. CBOR.toHex()

5.4. CBOR.fromHex()

5.5. CBOR.toBase64Url()

5.6. CBOR.fromBase64Url()

6. JavaScript Number Considerations

6.1. Integer Numbers

6.2. Floating Point Numbers

7. Diagnostic Notation

8. Deterministic Encoding

9. Version

1. Introduction

This document describes a JavaScript API for encoding and decoding data in the CBOR [RFC8949 link

] 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:

Deterministic Encoding
Diagnostic Notation encoder and decoder
Strict type checking of arguments
Optional: check for unread elements

Note: in this specification CBOR data items are subsequently referred to as CBOR objects.

Although this document describes a JavaScript API, it could also serve as a guide for CBOR implementations for other software platforms, with the goal of creating the foundation for cross platform interoperability. Due to this consideration, the level of CBOR support provided by the API is of the type "general purpose", avoiding constructs that are specific to JavaScript, like undefined and typed arrays beyond Uint8Array.

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:

CBOR Object	Wrapper Object	JavaScript
`integer`	CBOR.Int	`Number` [1]
`bignum`	CBOR.BigInt	`BigInt` [1]
`floating point`	CBOR.Float	`Number` [2]
`byte string`	CBOR.Bytes	`Uint8Array`
`text string`	CBOR.String	`String`
`true/false`	CBOR.Boolean	`Boolean`
`null`	CBOR.Null
`array`	CBOR.Array
`map`	CBOR.Map
`tag`	CBOR.Tag

See also Integer Numbers.
See also Floating Point Numbers.

Note that this implementation does not support CBOR "simple" values beyond true, false, null, and the three floating point variants.

2.1. CBOR.Int

Parameter	Type	Description
Syntax	`CBOR.Int(value)`
Description	Constructor. Creates a CBOR integer wrapper object. See also Integer Numbers.

`value`	`Number`	Integer to be wrapped.

Returns	Description
`CBOR.Int`	Wrapper object.

2.1.1. CBOR.Int Methods

2.1.1.1. getInt()

Returns	Description
Syntax	`getInt()`
Description	Reads CBOR integer in the range of `-2⁵³-1` to `2⁵³-1`. See also getBigInt().

`Number`	Decoded integer.

2.1.1.2. getBigInt()

Returns	Description
Syntax	`getBigInt()`
Description	Reads CBOR integer of any size. See also Integer Numbers.

`BigInt`	Decoded big integer.

2.2. CBOR.BigInt

Parameter	Type	Description
Syntax	`CBOR.BigInt(value)`
Description	Constructor. Creates a CBOR big integer wrapper object. See also Integer Numbers.

`value`	`BigInt`	Big integer to be wrapped.

Returns	Description
`CBOR.BigInt`	Wrapper object.

2.2.1. CBOR.BigInt Methods

2.2.1.1. getBigInt()

Returns	Description
Syntax	`getBigInt()`
Description	Reads CBOR integer of any size. See also Integer Numbers.

`BigInt`	Decoded big integer.

2.3. CBOR.Float

Parameter	Type	Description
Syntax	`CBOR.Float(value)`
Description	Constructor. Creates a CBOR floating point wrapper object. See also Floating Point Numbers.

`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()

Returns	Description
Syntax	`getFloat()`
Description	Reads CBOR floating point object.

`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

Parameter	Type	Description
Syntax	`CBOR.String(textString)`
Description	Constructor. Creates a CBOR text string wrapper object.

`textString`	`String`	String to be wrapped.

Returns	Description
`CBOR.String`	Wrapper object.

2.4.1. CBOR.String Methods

2.4.1.1. getString()

Returns	Description
Syntax	`getString()`
Description	Reads CBOR text string.

`String`	Decoded text string.

2.5. CBOR.Bytes

Parameter	Type	Description
Syntax	`CBOR.Bytes(byteString)`
Description	Constructor. Creates a CBOR byte string wrapper object.

`byteString`	`Uint8Array`	Binary data to be wrapped.

Returns	Description
`CBOR.Bytes`	Wrapper object.

2.5.1. CBOR.Bytes Methods

2.5.1.1. getBytes()

Returns	Description
Syntax	`getBytes()`
Description	Reads CBOR byte string.

`Uint8Array`	Decoded byte string.

2.6. CBOR.Boolean

Parameter	Type	Description
Syntax	`CBOR.Boolean(value)`
Description	Constructor. Creates a CBOR boolean wrapper object.

`value`	`Boolean`	Boolean to be wrapped.

Returns	Description
`CBOR.Boolean`	Wrapper object.

2.6.1. CBOR.Boolean Methods

2.6.1.1. getBoolean()

Returns	Description
Syntax	`getBoolean()`
Description	Reads CBOR boolean.

`Boolean`	Decoded boolean.

2.7. CBOR.Null

Returns	Description
Syntax	`CBOR.Null()`
Description	Constructor. Creates a CBOR `null` wrapper object. See also isNull().

`CBOR.Null`	Wrapper object.

2.8. CBOR.Array

Returns	Description
Syntax	`CBOR.Array()`
Description	Constructor. Creates a CBOR array wrapper object.

`CBOR.Array`	Wrapper object.

2.8.1. CBOR.Array Methods

2.8.1.1. add()

Parameter	Type	Description
Syntax	`add(object)`
Description	Adds CBOR wrapper object to the array.

`object`	`CBOR.Wrapper`	Object to be appended to the current array.

Returns	Description
`this`	Current object.

2.8.1.2. get()

Parameter	Type	Description
Syntax	`get(index)`
Description	Fetches CBOR wrapper object. If `index` is out of range, an exception is thrown.

`index`	`Number`	Index `(0..length-1)` of object.

Returns	Description
`CBOR.Wrapper`	Retrieved object.

2.8.1.3. toArray()

Returns	Description
Syntax	`toArray()`
Description	Copies array.

`[...]`	JavaScript array holding a copy of current `CBOR.Wrapper` objects.

2.8.1.4. getArray()

Returns	Description
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.

`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

Returns	Description
Syntax	`CBOR.Map()`
Description	Constructor. Creates a CBOR map wrapper object.

`CBOR.Map`	Wrapper object.

2.9.1. CBOR.Map Methods

2.9.1.1. set()

Parameter	Type	Description
Syntax	`set(key, value)`
Description	Sets map entry. If `key` entry is already defined, an exception is thrown. Note: `key` order is of no importance since Deterministic Encoding performs the required map sorting automatically. See also setSortingMode() and CBOR.initExtended().

`key`	`CBOR.Wrapper`	Key (name) wrapper object.
`value`	`CBOR.Wrapper`	Value wrapper object.

Returns	Description
`this`	Current object.

2.9.1.2. get()

Parameter	Type	Description
Syntax	`get(key)`
Description	Gets map entry. If `key` entry is undefined, an exception is thrown.

`key`	`CBOR.Wrapper`	Key (name) wrapper object.

Returns	Description
`CBOR.Wrapper`	Retrieved object.

2.9.1.3. getConditional()

Parameter	Type	Description
Syntax	`getConditional(key, defaultValue)`
Description	Gets map entry conditionally.

`key`	`CBOR.Wrapper`	Key (name) wrapper object.
`defaultValue`	`CBOR.Wrapper`	Value to return if `key` entry is undefined. `defaultValue` may be `null`.

Returns	Description
`CBOR.Wrapper`	Retrieved or default object.

2.9.1.4. containsKey()

Parameter	Type	Description
Syntax	`containsKey(key)`
Description	Checks map for key presence.

`key`	`CBOR.Wrapper`	Key (name) wrapper object.

Returns	Description
`Boolean`	`true` or `false`.

2.9.1.5. remove()

Parameter	Type	Description
Syntax	`remove(key)`
Description	Removes map entry. If `key` entry is undefined, an exception is thrown.

`key`	`CBOR.Wrapper`	Key (name) wrapper object.

Returns	Description
`CBOR.Wrapper`	Removed object (value component).

2.9.1.6. getKeys()

Returns	Description
Syntax	`getKeys()`
Description	Get map keys.

`[...]`	JavaScript array holding a copy of current `CBOR.Wrapper` map keys.

2.9.1.7. getMap()

Returns	Description
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.

`CBOR.Map`	Current object.

2.9.1.8. setSortingMode()

Parameter	Type	Description
Syntax	`setSortingMode(preSortedKeys)`
Description	Sets the current sorting mode of the CBOR.Map() object during set() operations. Typical usage: `let map = CBOR.Map().setSortingMode(true)` This method may be called multiple times which could be useful if you have a moderate set of unsorted meta data keys combined with a sorted large table-like set of keys. Note that this method has no effect on decoding operations.

`preSortedKeys`	`Boolean`	If `true`, keys must be provided in (CBOR wise) ascending order which can improve performance for maps having a huge number of keys. Improper key order will cause an exception to be thrown. By default map keys are sorted internally.

Returns	Description
`this`	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

Parameter	Type	Description
Syntax	`CBOR.Tag(tagNumber, object)`
Description	Constructor. Creates a CBOR tag wrapper object.

`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()

Returns	Description
Syntax	`getTagNumber()`
Description	Reads CBOR tag number.

`BigInt`	Decoded tag number.

2.10.1.2. getTaggedObject()

Returns	Description
Syntax	`getTaggedObject()`
Description	Reads tagged CBOR object.

`CBOR.Wrapper`	Retrieved object.

2.10.1.3. getTag()

Returns	Description
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.

`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()

Returns	Description
Syntax	`encode()`
Description	Encodes this object. Note: this method always return CBOR data using Deterministic Encoding.

`Uint8Array`	CBOR encoded data.

3.2. clone()

Returns	Description
Syntax	`clone()`
Description	Creates a new instance of this object, initialized with the original CBOR content.

`CBOR.Wrapper`	Copy of object.

3.3. equals()

Parameter	Type	Description
Syntax	`equals(object)`
Description	Compares this object with another object with respect to CBOR data.

`object`	`CBOR.Wrapper`	The object to compare with.

Returns	Description
`Boolean`	`true` if this object is equal to `object`, otherwise `false`.

3.4. toDiag()

Parameter	Type	Description
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().

`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()

Returns	Description
Syntax	`toString()`
Description	Renders this object in Diagnostic Notation. Equivalent to calling toDiag() with a `true` argument.

`String`	Textual version of the wrapped CBOR content.

3.6. isNull()

Returns	Description
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. See also CBOR.Null().

`Boolean`	Returns `true` if the current object holds a CBOR `null` item, otherwise `false` is returned.

3.7. checkForUnread()

Returns	Description
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().

`this`	Current object.

3.8. scan()

Returns	Description
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().

`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()

Parameter	Type	Description
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.

`cbor`	`Uint8Array`	The data (bytes) to be decoded.

Returns	Description
`CBOR.Wrapper`	CBOR wrapper object.

4.2. CBOR.initExtended()

Parameter	Type	Description
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().

`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. The flag disables the strict map sorting requirement and the preferred serialization of numbers (=shortest).

Returns	Description
`Decoder`	Internal decoder object for usage with CBOR.decodeExtended().

4.3. CBOR.decodeExtended()

Parameter	Type	Description
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.

`decoder`	`Decoder`	Internal decoder object.

Returns	Description
`CBOR.Wrapper`	CBOR wrapper object or `null`.

4.4. CBOR.diagDecode()

Parameter	Type	Description
Syntax	`CBOR.diagDecode(cborText)`
Description	Decodes a CBOR object provided in Diagnostic Notation. See also CBOR.diagDecodeSequence().

`cborText`	`String`	CBOR in textual format.

Returns	Description
`CBOR.Wrapper`	CBOR wrapper object.

4.5. CBOR.diagDecodeSequence()

Parameter	Type	Description
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.

`cborText`	`String`	CBOR in textual format.

Returns	Description
`[...]`	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()

Parameter	Type	Description
Syntax	`CBOR.addArrays(a, b)`
Description	Adds two arrays.

`a`	`Uint8Array`	First array.
`b`	`Uint8Array`	Second array.

Returns	Description
`Uint8Array`	Concatenation of array `a` and `b`.

5.2. CBOR.compareArrays()

Parameter	Type	Description
Syntax	`CBOR.compareArrays(a, b)`
Description	Compares two arrays lexicographically.

`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()

Parameter	Type	Description
Syntax	`CBOR.toHex(byteArray)`
Description	Encodes binary data to hexadecimal.

`byteArray`	`Uint8Array`	Zero or more bytes to be encoded.

Returns	Description
`String`	Hexadecimal encoded data.

5.4. CBOR.fromHex()

Parameter	Type	Description
Syntax	`CBOR.fromHex(hexString)`
Description	Decodes hexadecimal data into binary.

`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()

Parameter	Type	Description
Syntax	`CBOR.toBase64Url(byteArray)`
Description	Encodes binary data to base64Url.

`byteArray`	`Uint8Array`	Zero or more bytes to be encoded.

Returns	Description
`String`	Base64Url encoded data.

5.6. CBOR.fromBase64Url()

Parameter	Type	Description
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.

`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 protocols using integer elements where the magnitude may exceed 2⁵³-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(), which for convenience reasons is supported by both of the integer wrapper types.

Note that selecting CBOR.BigInt() or CBOR.Int() only affects the maximum numeric range with respect to JavaScript limits, not the CBOR encoding. During CBOR decoding, the selection between CBOR.BigInt() and CBOR.Int() is governed by the decoded value with respect to JavaScript limits.

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.

Due to the Deterministic Encoding scheme used by CBOR.js, CBOR data can be bidirectionally converted between its native (binary) format and diagnostic notation without getting corrupted. Note though that text-binary-text "roundtrips" do not necessarily return identical text: 0x10 used as diagnostic notation input will return 16 as diagnostic notation output.

The following table shows how CBOR objects should be represented in diagnostic notation:

CBOR Object	Syntax	Notes	Description
	`/` comment text `/`	7	Multi-line comment. Multi-line comments are treated as whitespace and may thus also be used between CBOR objects.
	`#` comment text	7	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.
`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`	{sign}{`0b`\|`0o`\|`0x`}n	1, 2
`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, 7	Byte data provided in base64 or base64URL notation. Padding with `'='` characters is optional.
	`'`text`'`	4, 5, 7	Byte data provided as UTF-8 encoded text.
	`<<` object `>>`	7	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`		Boolean value.
`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.
	`,`	7	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.
Only applicable for input. That is, toString() does not produce this item.

8. Deterministic Encoding

This section is primarily targeting implementers of CBOR tools.

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+: Floating point and integer objects must be treated as distinct types regardless of their numeric value. This is compliant with Rule 2 in section 4.2.2 of RFC 8949.

RFC: Integers, represented by the integer and bignum types, must use the integer type if the value is between -2⁶⁴ and 2⁶⁴-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.960464477539063e-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.4012986313726115e-45`	`fb36a0000020000000`
`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: 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: 1.0.3, 2023-12-05

CBOR.js - JavaScript API

Abstract

Table of Contents

1. Introduction

2. CBOR Wrapper Objects

2.1. CBOR.Int

2.1.1. CBOR.Int Methods

2.1.1.1. getInt()

2.1.1.2. getBigInt()

2.2. CBOR.BigInt

2.2.1. CBOR.BigInt Methods

2.2.1.1. getBigInt()

2.3. CBOR.Float

2.3.1. CBOR.Float Methods

2.3.1.1. getFloat()

2.3.2. CBOR.Float Properties

2.3.2.1. length

2.4. CBOR.String

2.4.1. CBOR.String Methods

2.4.1.1. getString()

2.5. CBOR.Bytes

2.5.1. CBOR.Bytes Methods

2.5.1.1. getBytes()

2.6. CBOR.Boolean

2.6.1. CBOR.Boolean Methods

2.6.1.1. getBoolean()

2.7. CBOR.Null

2.8. CBOR.Array

2.8.1. CBOR.Array Methods

2.8.1.1. add()

2.8.1.2. get()

2.8.1.3. toArray()

2.8.1.4. getArray()

2.8.2. CBOR.Array Properties

2.8.2.1. length

2.9. CBOR.Map

2.9.1. CBOR.Map Methods

2.9.1.1. set()

2.9.1.2. get()

2.9.1.3. getConditional()

2.9.1.4. containsKey()

2.9.1.5. remove()

2.9.1.6. getKeys()

2.9.1.7. getMap()

2.9.1.8. setSortingMode()

2.9.2. CBOR.Map Properties

2.9.2.1. length

2.10. CBOR.Tag

2.10.1. CBOR.Tag Methods

2.10.1.1. getTagNumber()

2.10.1.2. getTaggedObject()

2.10.1.3. getTag()

3. Common Wrapper Methods

3.1. encode()

3.2. clone()

3.3. equals()

3.4. toDiag()

3.5. toString()

3.6. isNull()

3.7. checkForUnread()

3.8. scan()

4. Decoding CBOR

4.1. CBOR.decode()

4.2. CBOR.initExtended()

4.3. CBOR.decodeExtended()

4.4. CBOR.diagDecode()

4.5. CBOR.diagDecodeSequence()

5. Utility Methods

5.1. CBOR.addArrays()

5.2. CBOR.compareArrays()

5.3. CBOR.toHex()

5.4. CBOR.fromHex()

5.5. CBOR.toBase64Url()

5.6. CBOR.fromBase64Url()

6. JavaScript Number Considerations

6.1. Integer Numbers

6.2. Floating Point Numbers

7. Diagnostic Notation

8. Deterministic Encoding

9. Version