1. The representation must be able to unambiguously encode most common data formats used in Internet standards.
   • It must represent a reasonable set of basic data types and structures using binary encoding. "Reasonable" here is largely influenced by the capabilities of JSON, with the major addition of binary byte strings. The structures supported are limited to arrays and trees; loops and lattice-style graphs are not supported.
   • There is no requirement that all data formats be uniquely encoded; that is, it is acceptable that the number "7" might be encoded in multiple different ways.
2. The code for an encoder or decoder must be able to be compact in order to support systems with very limited memory, processor power, and instruction sets.
   • An encoder and a decoder need to be implementable in a very small amount of code (for example, in class 1 constrained nodes as defined in [RFC 7228]).
   • The format should use contemporary machine representations of data (for example, not requiring binary-to-decimal conversion).
3. Data must be able to be decoded without a schema description.
   • Similar to JSON, encoded data should be self-describing so that a generic decoder can be written.
4. The serialization must be reasonably compact, but data compactness is secondary to code compactness for the encoder and decoder.
   • "Reasonable" here is bounded by JSON as an upper bound in size and by the implementation complexity, which limits the amount of effort that can go into achieving that compactness. Using either general compression schemes or extensive bit-fiddling violates the complexity goals.
5. The format must be applicable to both constrained nodes and high-volume applications.
   • This means it must be reasonably frugal in CPU usage for both encoding and decoding. This is relevant both for constrained nodes and for potential usage in applications with a very high volume of data.
6. The format must support all JSON data types for conversion to and from JSON.
   • It must support a reasonable level of conversion as long as the data represented is within the capabilities of JSON. It must be possible to define a unidirectional mapping towards JSON for all types of data.
7. The format must be extensible, and the extended data must be decodable by earlier decoders.
   • The format is designed for decades of use.
   • The format must support a form of extensibility that allows fallback so that a decoder that does not understand an extension can still decode the message.
   • The format must be able to be extended in the future by later IETF standards.

Data item:

A single piece of CBOR data. The structure of a data item maycontain zero, one, or more nested data items. The term is used bothfor the data item in representation format and for the abstract ideathat can be derived from that by a decoder; the former can beaddressed specifically by using the term "encoded data item".

Decoder:

A process that decodes a well-formed encoded CBOR data item and makes it available to anapplication. Formally speaking, a decoder contains a parser tobreak up the input using the syntax rules of CBOR, as well as asemantic processor to prepare the data in a form suitable to theapplication.

Encoder:

A process that generates the (well-formed) representation format of a CBOR dataitem from application information.

Data Stream:

A sequence of zero or more data items, not further assembled into alarger containing data item (see [RFC 8742] for one application).The independent data items that makeup a data stream are sometimes also referred to as "top-level dataitems".

Well-formed:

A data item that follows the syntactic structure of CBOR. Awell-formed data item uses the initial bytes and the byte stringsand/or data items that are implied by their values as defined inCBOR and does not include following extraneous data. CBOR decodersby definition only return contents from well-formed data items.

Valid:

A data item that is well-formed and also follows the semanticrestrictions that apply to CBOR data items (Section 5.3).

Expected:

Besides its normal English meaning, the term "expected" is used todescribe requirements beyond CBOR validity that an application hason its input data. Well-formed (processable at all), valid (checkedby a validity-checking generic decoder), and expected (checked by theapplication) form a hierarchy of layers of acceptability.

Stream decoder:

A process that decodes a data stream and makes each of the dataitems in the sequence available to an application as they arereceived.

• an integer in the range -2⁶⁴..2⁶⁴-1 inclusive
• a simple value, identified by a number between 0 and 255, but distinct from that number itself
• a floating-point value, distinct from an integer, out of the set representable by IEEE 754 binary64 (including non-finites) [IEEE754]
• a sequence of zero or more bytes ("byte string")
• a sequence of zero or more Unicode code points ("text string")
• a sequence of zero or more data items ("array")
• a mapping (mathematical function) from zero or more data items ("keys") each to a data item ("values"), ("map")
• a tagged data item ("tag"), comprising a tag number (an integer in the range 0..2⁶⁴-1) and the tag content (a data item)

• false, true, null, and undefined (simple values identified by 20..23, Section 3.3)
• integer and floating-point values with a larger range and precision than the above (tag numbers 2 to 5, Section 3.4)
• application data types such as a point in time or date/time string defined in RFC 3339 (tag numbers 1 and 0, Section 3.4)

Less than 24:

The argument's value is the value of the additional information.

24, 25, 26, or 27:

The argument's value is held in the following 1, 2, 4, or 8 bytes,respectively, in network byte order. For major type 7 andadditional information value 25, 26, 27, these bytes are not used asan integer argument, but as a floating-point value (seeSection 3.3).

28, 29, 30:

These values are reserved for future additions to the CBOR format.In the present version of CBOR, the encoded item is not well-formed.

31:

No argument value is derived.If the major type is 0, 1, or 6, the encoded item is notwell-formed. For major types 2 to 5, the item's length isindefinite, and for major type 7, the byte does not constitute a dataitem at all but terminates an indefinite-length item; all aredescribed in Section 3.2.

Major type 0:

An unsigned integer in the range 0..2⁶⁴-1 inclusive. The value of theencoded item is the argument itself. For example, theinteger 10 is denoted as the one byte 0b000_01010 (major type 0,additional information 10). The integer 500 would be 0b000_11001(major type 0, additional information 25) followed by the two bytes0x01f4, which is 500 in decimal.

Major type 1:

A negative integer in the range -2⁶⁴..-1 inclusive. The value ofthe item is -1 minus the argument. For example, the integer-500 would be 0b001_11001 (major type 1, additional information 25)followed by the two bytes 0x01f3, which is 499 in decimal.

Major type 2:

A byte string. The number of bytes in the string is equal to theargument. For example, a bytestring whose length is 5 would have an initial byte of 0b010_00101(major type 2, additional information 5 for the length), followed by5 bytes of binary content. A byte string whose length is 500 wouldhave 3 initial bytes of 0b010_11001 (major type 2, additionalinformation 25 to indicate a two-byte length) followed by the twobytes 0x01f4 for a length of 500, followed by 500 bytes of binarycontent.

Major type 3:

A text string (Section 2) encoded as UTF-8[RFC 3629]. The number of bytes in the string is equal to theargument. A string containing an invalid UTF-8 sequence iswell-formed but invalid (Section 1.2). This type is provided forsystems that need to interpret or display human-readable text, andallows the differentiation between unstructured bytes and text thathas a specified repertoire (that of Unicode) and encoding (UTF-8). In contrast to formatssuch as JSON, the Unicode characters in this type are neverescaped. Thus, a newline character (U+000A) is always represented ina string as the byte 0x0a, and never as the bytes 0x5c6e (thecharacters "\" and "n") nor as 0x5c7530303061 (the characters "\","u", "0", "0", "0", and "a").

Major type 4:

An array of data items. In other formats, arrays are also called lists, sequences, ortuples (a "CBOR sequence" is something slightly different, though [RFC 8742]).The argument is the number of data items in thearray. Items in anarray do not need to all be of the same type. For example, an arraythat contains 10 items of any type would have an initial byte of0b100_01010 (major type 4, additional information 10 for thelength) followed by the 10 remaining items.

Major type 5:

A map of pairs of data items. Maps are also called tables,dictionaries, hashes, or objects (in JSON). A map is comprised ofpairs of data items, each pair consisting of a key that isimmediately followed by a value. The argument is the numberof pairs of data items in the map. Forexample, a map that contains 9 pairs would have an initial byte of0b101_01001 (major type 5, additional information 9 for thenumber of pairs) followed by the 18 remaining items. The first itemis the first key, the second item is the first value, the third itemis the second key, and so on. Because items in a map come in pairs,their total number is always even: a map that contains an oddnumber of items (no value data present after the last key data item) is not well-formed.A map that has duplicate keys may bewell-formed, but it is not valid, and thus it causes indeterminatedecoding; see also Section 5.6.

Major type 6:

A tagged data item ("tag") whose tag number, an integer in the range0..2⁶⁴-1 inclusive, is the argument andwhose enclosed data item (tag content) is the single encoded data item that follows the head.See Section 3.4.

Major type 7:

Floating-point numbers and simple values, as well as the "break"stop code. See Section 3.3.

• Tag number 32 is for URIs, as defined in [RFC 3986]. If the text string doesn't match the URI-reference production, the string is invalid.
• Tag numbers 33 and 34 are for base64url- and base64-encoded text strings, respectively, as defined in [RFC 4648]. If any of the following apply:
  • the encoded text string contains non-alphabet characters or only 1 alphabet character in the last block of 4 (where alphabet is defined by Section 5 of RFC 4648 for tag number 33 and Section 4 of RFC 4648 for tag number 34), or
  • the padding bits in a 2- or 3-character block are not 0, or
  • the base64 encoding has the wrong number of padding characters, or
  • the base64url encoding has padding characters,
  the string is invalid.
• Tag number 36 is for MIME messages (including all headers), as defined in [RFC 2045]. A text string that isn't a valid MIME message is invalid. (For this tag, validity checking may be particularly onerous for a generic decoder and might therefore not be offered. Note that many MIME messages are general binary data and therefore cannot be represented in a text string; [IANA.cbor-tags] lists a registration for tag number 257 that is similar to tag number 36 but uses a byte string as its tag content.)

• Preferred serialization MUST be used. In particular, this means that arguments (see Section 3) for integers, lengths in major types 2 through 5, and tags MUST be as short as possible, for instance:
  • 0 to 23 and -1 to -24 MUST be expressed in the same byte as the major type;
  • 24 to 255 and -25 to -256 MUST be expressed only with an additional uint8_t;
  • 256 to 65535 and -257 to -65536 MUST be expressed only with an additional uint16_t;
  • 65536 to 4294967295 and -65537 to -4294967296 MUST be expressed only with an additional uint32_t.
  Floating-point values also MUST use the shortest form that preserves the value, e.g., 1.5 is encoded as 0xf93e00 (binary16) and 1000000.5 as 0xfa49742408 (binary32). (One implementation of this is to have all floats start as a 64-bit float, then do a test conversion to a 32-bit float; if the result is the same numeric value, use the shorter form and repeat the process with a test conversion to a 16-bit float. This also works to select 16-bit float for positive and negative Infinity as well.)
• Indefinite-length items MUST NOT appear. They can be encoded as definite-length items instead.
• The keys in every map MUST be sorted in the bytewise lexicographic order of their deterministic encodings. For example, the following keys are sorted correctly:
  1. 10, encoded as 0x0a.
  2. 100, encoded as 0x1864.
  3. -1, encoded as 0x20.
  4. "z", encoded as 0x617a.
  5. "aa", encoded as 0x626161.
  6. [100], encoded as 0x811864.
  7. [-1], encoded as 0x8120.
  8. false, encoded as 0xf4.

• Although IEEE floating-point values can represent both positive and negative zero as distinct values, the application might not distinguish these and might decide to represent all zero values with a positive sign, disallowing negative zero. (The application may also want to restrict the precision of floating-point values in such a way that there is never a need to represent 64-bit -- or even 32-bit -- floating-point values.)
• If a protocol includes a field that can express floating-point values, with a specific data model that declares integer and floating-point values to be interchangeable, the protocol's deterministic encoding needs to specify whether, for example, the integer 1.0 is encoded as 0x01 (unsigned integer), 0xf93c00 (binary16), 0xfa3f800000 (binary32), or 0xfb3ff0000000000000 (binary64). Example rules for this are:
  1. Encode integral values that fit in 64 bits as values from major types 0 and 1, and other values as the preferred (smallest of 16-, 32-, or 64-bit) floating-point representation that accurately represents the value,
  2. Encode all values as the preferred floating-point representation that accurately represents the value, even for integral values, or
  3. Encode all values as 64-bit floating-point representations.
  Rule 1 straddles the boundaries between integers and floating-point values, and Rule 3 does not use preferred serialization, so Rule 2 may be a good choice in many cases.
• If NaN is an allowed value, and there is no intent to support NaN payloads or signaling NaNs, the protocol needs to pick a single representation, typically 0xf97e00. If that simple choice is not possible, specific attention will be needed for NaN handling.
• Subnormal numbers (nonzero numbers with the lowest possible exponent of a given IEEE 754 number format) may be flushed to zero outputs or be treated as zero inputs in some floating-point implementations. A protocol's deterministic encoding may want to specifically accommodate such implementations while creating an onus on other implementations by excluding subnormal numbers from interchange, interchanging zero instead.
• The same number can be represented by different decimal fractions, by different bigfloats, and by different forms under other tags that may be defined to express numeric values. Depending on the implementation, it may not always be practical to determine whether any of these forms (or forms in the basic generic data model) are equivalent. An application protocol that presents choices of this kind for the representation format of numbers needs to be explicit about how the formats for deterministic encoding are to be chosen.

1. If two keys have different lengths, the shorter one sorts earlier;
2. If two keys have the same length, the one with the lower value in (bytewise) lexical order sorts earlier.

1. 10, encoded as 0x0a.
2. -1, encoded as 0x20.
3. false, encoded as 0xf4.
4. 100, encoded as 0x1864.
5. "z", encoded as 0x617a.
6. [-1], encoded as 0x8120.
7. "aa", encoded as 0x626161.
8. [100], encoded as 0x811864.

1. Replace the problematic item with an error marker and continue with the next item, or
2. Issue an error and stop processing altogether.

Duplicate keys in a map:

Generic decoders (Section 5.2) make data available to applicationsusing the native CBOR data model. That data model includes maps(key-value mappings with unique keys), not multimaps (key-valuemappings where multiple entries can have the same key). Thus, ageneric decoder that gets a CBOR map item that has duplicate keyswill decode to a map with only one instance of that key, or it mightstop processing altogether. On the other hand, a "streamingdecoder" may not even be able to notice. See Section 5.6 for morediscussion of keys in maps.

Invalid UTF-8 string:

A decoder might or might not want to verify that the sequence ofbytes in a UTF-8 string (major type 3) is actually valid UTF-8 andreact appropriately.

Inadmissible type for tag content:

Tag numbers (Section 3.4) specify what type of data item is supposed to beused as their tag content; for example, the tag numbers for unsigned or negative bignums aresupposed to be put on byte strings. A decoder that decodes thetagged data item into a native representation (a native big integerin this example) is expected to check the type of the data itembeing tagged. Even decoders that don't have such nativerepresentations available in their environment may perform the checkon those tags known to them and react appropriately.

Inadmissible value for tag content:

The type of data item may be admissible for a tag's content, but thespecific value may not be; e.g., a value of "yesterday" is notacceptable for the content of tag 0, even though it properly is atext string. A decoder that normally ingests such tags intoequivalent platform types might present this tag to the applicationin a similar way to how it would present a tag with an unknown tagnumber (Section 5.4).

• It can report an error (and not return data). Note that treating this case as an error can cause ossification and is thus not encouraged. This error is not a validity error, per se. This kind of error is more likely to be raised by a decoder that would be performing validity checking if this were a known case.
• It can emit the unknown item (type, value, and, for tags, the decoded tagged data item) to the application calling the decoder, and then give the application an indication that the decoder did not recognize that tag number or simple value.

• Not accept maps with duplicate keys (that is, enforce validity for maps, see also Section 5.4). These generic decoders are universally useful. An application may still need to perform its own duplicate checking based on application rules (for instance, if the application equates integers and floating-point values in map key positions for specific maps).
• Pass all map entries to the application, including ones with duplicate keys. This requires that the application handle (check against) duplicate keys, even if the application rules are identical to the generic data model rules.
• Lose some entries with duplicate keys, e.g., deliver only the final (or first) entry out of the entries with the same key. With such a generic decoder, applications may get different results for a specific key on different runs, and with different generic decoders, which value is returned is based on generic decoder implementation and the actual order of keys in the map. In particular, applications cannot validate key uniqueness on their own as they do not necessarily see all entries; they may not be able to use such a generic decoder if they need to validate key uniqueness. These generic decoders can only be used in situations where the data source and transfer always provide valid maps; this is not possible if the data source and transfer can be attacked.

• An integer (major type 0 or 1) becomes a JSON number.
• A byte string (major type 2) that is not embedded in a tag that specifies a proposed encoding is encoded in base64url without padding and becomes a JSON string.
• A UTF-8 string (major type 3) becomes a JSON string. Note that JSON requires escaping certain characters (RFC 8259, Section 7): quotation mark (U+0022), reverse solidus (U+005C), and the "C0 control characters" (U+0000 through U+001F). All other characters are copied unchanged into the JSON UTF-8 string.
• An array (major type 4) becomes a JSON array.
• A map (major type 5) becomes a JSON object. This is possible directly only if all keys are UTF-8 strings. A converter might also convert other keys into UTF-8 strings (such as by converting integers into strings containing their decimal representation); however, doing so introduces a danger of key collision. Note also that, if tags on UTF-8 strings are ignored as proposed below, this will cause a key collision if the tags are different but the strings are the same.
• False (major type 7, additional information 20) becomes a JSON false.
• True (major type 7, additional information 21) becomes a JSON true.
• Null (major type 7, additional information 22) becomes a JSON null.
• A floating-point value (major type 7, additional information 25 through 27) becomes a JSON number if it is finite (that is, it can be represented in a JSON number); if the value is non-finite (NaN, or positive or negative Infinity), it is represented by the substitute value.
• Any other simple value (major type 7, any additional information value not yet discussed) is represented by the substitute value.
• A bignum (major type 6, tag number 2 or 3) is represented by encoding its byte string in base64url without padding and becomes a JSON string. For tag number 3 (negative bignum), a "~" (ASCII tilde) is inserted before the base-encoded value. (The conversion to a binary blob instead of a number is to prevent a likely numeric overflow for the JSON decoder.)
• A byte string with an encoding hint (major type 6, tag number 21 through 23) is encoded as described by the hint and becomes a JSON string.
• For all other tags (major type 6, any other tag number), the tag content is represented as a JSON value; the tag number is ignored.
• Indefinite-length items are made definite before conversion.

• JSON numbers without fractional parts (integer numbers) are represented as integers (major types 0 and 1, possibly major type 6, tag number 2 and 3), choosing the shortest form; integers longer than an implementation-defined threshold may instead be represented as floating-point values. The default range that is represented as integer is -2⁵³+1..2⁵³-1 (fully exploiting the range for exact integers in the binary64 representation often used for decoding JSON [RFC 7493]). A CBOR-based protocol, or a generic converter implementation, may choose -2³²..2³²-1 or -2⁶⁴..2⁶⁴-1 (fully using the integer ranges available in CBOR with uint32_t or uint64_t, respectively) or even -2³¹..2³¹-1 or -2⁶³..2⁶³-1 (using popular ranges for two's complement signed integers). (If the JSON was generated from a JavaScript implementation, its precision is already limited to 53 bits maximum.)
• Numbers with fractional parts are represented as floating-point values, performing the decimal-to-binary conversion based on the precision provided by IEEE 754 binary64. The mathematical value of the JSON number is converted to binary64 using the roundTiesToEven procedure in Section 4.3.1 of [IEEE754]. Then, when encoding in CBOR, the preferred serialization uses the shortest floating-point representation exactly representing this conversion result; for instance, 1.5 is represented in a 16-bit floating-point value (not all implementations will be capable of efficiently finding the minimum form, though). Instead of using the default binary64 precision, there may be an implementation-defined limit to the precision of the conversion that will affect the precision of the represented values. Decimal representation should only be used on the CBOR side if that is specified in a protocol.

the "simple" space (values in major type 7):

Of the 24 efficient(and 224 slightly less efficient) values, only a small number havebeen allocated. Implementations receiving an unknown simple dataitem may easily be able to process it as such, given that the structure ofthe value is indeed simple. The IANA registry inSection 9.1 is the appropriate way to address theextensibility of this codepoint space.

the "tag" space (values in major type 6):

The total codepoint spaceis abundant; only a tiny part of it hasbeen allocated. However, not all of these codepoints are equallyefficient: the first 24 only consume a single ("1+0") byte, andhalf of them have already been allocated. The next 232 values onlyconsume two ("1+1") bytes, with nearly a quarter already allocated.These subspaces need some curation to last for a few more decades.Implementations receiving an unknown tag number can choose toprocess just the enclosed tag content or, preferably, toprocess the tag as an unknown tag number wrapping thetag content. The IANA registry in Section 9.2 is the appropriate way toaddress the extensibility of this codepoint space.

the "additional information" space:

An implementation receiving anunknown additional information value has no way to continue decoding,so allocating codepoints in this space is a major step beyond justexercising an extension point. There arealso very few codepoints left. See also Section 7.2.

• Data item
• Semantics (short form)

• Point of contact
• Description of semantics (URL) -- This description is optional; the URL can point to something like an Internet-Draft or a web page.

Type name:

application

Subtype name:

cbor

Required parameters:

n/a

Optional parameters:

n/a

Encoding considerations:

Binary

Security considerations:

See Section 10 of RFC 8949.

Interoperability considerations:

n/a

Published specification:

RFC 8949

Applications that use this media type:

Many

Additional information:

Magic number(s):

n/a

File extension(s):

.cbor

Macintosh file type code(s):

n/a

Person & email address to contact for further information:

IETF CBOR Working Group (cbor@ietf.org) or IETF Applications and Real-Time Area (art@ietf.org)

Intended usage:

COMMON

Restrictions on usage:

none

Author:

IETF CBOR Working Group (cbor@ietf.org)

Change controller:

The IESG (iesg@ietf.org)

Media Type:

application/cbor

Encoding:

-

ID:

60

Reference:

RFC 8949

Name:

Concise Binary Object Representation (CBOR)

+suffix:

+cbor

References:

RFC 8949

Encoding Considerations:

CBOR is a binary format.

Interoperability Considerations:

n/a

Fragment Identifier Considerations:

The syntax and semantics of fragment identifiers specified for +cbor SHOULD be as specified for "application/cbor". (At publication of RFC 8949, there is no fragment identification syntax defined for "application/cbor".)

The syntax and semantics for fragment identifiers for a specific "xxx/yyy+cbor" SHOULD be processed as follows:

• For cases defined in +cbor, where the fragment identifier resolves per the +cbor rules, then process as specified in +cbor.
• For cases defined in +cbor, where the fragment identifier does not resolve per the +cbor rules, then process as specified in "xxx/yyy+cbor".
• For cases not defined in +cbor, then process as specified in "xxx/yyy+cbor".

Security Considerations:

See Section 10 of RFC 8949.

Contact:

IETF CBOR Working Group (cbor@ietf.org) orIETF Applications and Real-Time Area (art@ietf.org)

Author/Change Controller:

IETF

[C]

International Organization for Standardization, "Information technology - Programming languages - C", ISO/IEC 9899:2018, June 2018,
<https://www.iso.org/standard/74528.html>.

[Cplusplus20]

International Organization for Standardization, "Programming languages - C++", ISO/IEC DIS 14882, ISO/IEC ISO/IEC JTC1 SC22 WG21 N 4860, March 2020,
<https://isocpp.org/files/papers/N4860.pdf>.

[IEEE754]

IEEE, "IEEE Standard for Floating-Point Arithmetic", IEEE Std 754-2019, DOI 10.1109/IEEESTD.2019.8766229,
<https://ieeexplore.ieee.org/document/8766229>.

[RFC2045]

N. Freed, and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, DOI 10.17487/RFC2045, November 1996,
<https://www.rfc-editor.org/info/rfc2045>.

[RFC2119]

S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.

[RFC3339]

G. Klyne, and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.

[RFC3629]

F. Yergeau, "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, November 2003,
<https://www.rfc-editor.org/info/rfc3629>.

[RFC3986]

T. Berners-Lee, R. Fielding, and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>.

[RFC4287]

M. Nottingham, and R. Sayre, "The Atom Syndication Format", RFC 4287, DOI 10.17487/RFC4287, December 2005,
<https://www.rfc-editor.org/info/rfc4287>.

[RFC4648]

S. Josefsson, "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
<https://www.rfc-editor.org/info/rfc4648>.

[RFC8126]

M. Cotton, B. Leiba, and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.

[RFC8174]

B. Leiba, "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017,
<https://www.rfc-editor.org/info/rfc8174>.

[TIME_T]

The Open Group, "The Open Group Base Specifications", IEEE Std 1003.1, 2018,
<https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_16>.

[ASN.1]

International Telecommunication Union, "Information Technology - ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)", ITU-T Recommendation X.690, 2015,
<https://www.itu.int/rec/T-REC-X.690-201508-I/en>.

[BSON]

Various, "BSON - Binary JSON",
<http://bsonspec.org/>.

[CBOR-TAGS]

C Bormann, "Notable CBOR Tags", Internet-Draft draft-bormann-cbor-notable-tags-02, June 2020,
<https://tools.ietf.org/html/draft-bormann-cbor-notable-tags-02>.

[ECMA262]

Ecma International, "ECMAScript 2020 Language Specification", June 2020,
<https://www.ecma-international.org/publications/standards/Ecma-262.htm>.

[Err3764]

RFC Errata, "Erratum ID 3764",
<https://www.rfc-editor.org/errata/eid3764>.

[Err3770]

RFC Errata, "Erratum ID 3770",
<https://www.rfc-editor.org/errata/eid3770>.

[Err4294]

RFC Errata, "Erratum ID 4294",
<https://www.rfc-editor.org/errata/eid4294>.

[Err4409]

RFC Errata, "Erratum ID 4409",
<https://www.rfc-editor.org/errata/eid4409>.

[Err4963]

RFC Errata, "Erratum ID 4963",
<https://www.rfc-editor.org/errata/eid4963>.

[Err4964]

RFC Errata, "Erratum ID 4964",
<https://www.rfc-editor.org/errata/eid4964>.

[Err5434]

RFC Errata, "Erratum ID 5434",
<https://www.rfc-editor.org/errata/eid5434>.

[Err5763]

RFC Errata, "Erratum ID 5763",
<https://www.rfc-editor.org/errata/eid5763>.

[Err5917]

RFC Errata, "Erratum ID 5917",
<https://www.rfc-editor.org/errata/eid5917>.

[IANA.cbor-simple-values]

IANA, "Concise Binary Object Representation (CBOR) Simple Values",
<https://www.iana.org/assignments/cbor-simple-values>.

[IANA.cbor-tags]

IANA, "Concise Binary Object Representation (CBOR) Tags",
<https://www.iana.org/assignments/cbor-tags>.

[IANA.core-parameters]

IANA, "Constrained RESTful Environments (CoRE) Parameters",
<https://www.iana.org/assignments/core-parameters>.

[IANA.media-types]

IANA, "Media Types",
<https://www.iana.org/assignments/media-types>.

[IANA.structured-suffix]

IANA, "Structured Syntax Suffixes",
<https://www.iana.org/assignments/media-type-structured-suffix>.

[MessagePack]

S. Furuhashi, "MessagePack",
<https://msgpack.org/>.

[PCRE]

P. Hazel, "PCRE - Perl Compatible Regular Expressions",
<https://www.pcre.org/>.

[RFC0713]

J. Haverty, "MSDTP-Message Services Data Transmission Protocol", RFC 713, DOI 10.17487/RFC0713, April 1976,
<https://www.rfc-editor.org/info/rfc713>.

[RFC6838]

N. Freed, J. Klensin, and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.

[RFC7049]

C. Bormann, and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013,
<https://www.rfc-editor.org/info/rfc7049>.

[RFC7228]

C. Bormann, M. Ersue, and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, DOI 10.17487/RFC7228, May 2014,
<https://www.rfc-editor.org/info/rfc7228>.

[RFC7493]

T. Bray, "The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015,
<https://www.rfc-editor.org/info/rfc7493>.

[RFC7991]

P. Hoffman, "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016,
<https://www.rfc-editor.org/info/rfc7991>.

[RFC8259]

T. Bray, "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.

[RFC8610]

H. Birkholz, C. Vigano, and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019,
<https://www.rfc-editor.org/info/rfc8610>.

[RFC8618]

J. Dickinson, J. Hague, S. Dickinson, T. Manderson, and J. Bond, "Compacted-DNS (C-DNS): A Format for DNS Packet Capture", RFC 8618, DOI 10.17487/RFC8618, September 2019,
<https://www.rfc-editor.org/info/rfc8618>.

[RFC8742]

C. Bormann, "Concise Binary Object Representation (CBOR) Sequences", RFC 8742, DOI 10.17487/RFC8742, February 2020,
<https://www.rfc-editor.org/info/rfc8742>.

[RFC8746]

C. Bormann, "Concise Binary Object Representation (CBOR) Tags for Typed Arrays", RFC 8746, DOI 10.17487/RFC8746, February 2020,
<https://www.rfc-editor.org/info/rfc8746>.

[SIPHASH_LNCS]

J. Aumasson, and D. Bernstein, "SipHash: A Fast Short-Input PRF", DOI 10.1007/978-3-642-34931-7_28, 2012,
<https://doi.org/10.1007/978-3-642-34931-7_28>.

[SIPHASH_OPEN]

J. Aumasson, and D.J. Bernstein, "SipHash: a fast short-input PRF",
<https://www.aumasson.jp/siphash/siphash.pdf>.

[YAML]

O. Ben-Kiki, C. Evans, and I.d. Net, "YAML Ain't Markup Language (YAML[TM]) Version 1.2", October 2009,
<https://www.yaml.org/spec/1.2/spec.html>.

• the pseudocode does not "fail";
• after execution of the pseudocode, no bytes are left in the input (except in streaming applications).

• take(n) reads n bytes from the input data and returns them as a byte string. If n bytes are no longer available, take(n) fails.
• uint() converts a byte string into an unsigned integer by interpreting the byte string in network byte order.
• Arithmetic works as in C.
• All variables are unsigned integers of sufficient range.

well_formed(breakable = false) {
  // process initial bytes
  ib = uint(take(1));
  mt = ib >> 5;
  val = ai = ib & 0x1f;
  switch (ai) {
    case 24: val = uint(take(1)); break;
    case 25: val = uint(take(2)); break;
    case 26: val = uint(take(4)); break;
    case 27: val = uint(take(8)); break;
    case 28: case 29: case 30: fail();
    case 31:
      return well_formed_indefinite(mt, breakable);
  }
  // process content
  switch (mt) {
    // case 0, 1, 7 do not have content; just use val
    case 2: case 3: take(val); break; // bytes/UTF-8
    case 4: for (i = 0; i < val; i++) well_formed(); break;
    case 5: for (i = 0; i < val*2; i++) well_formed(); break;
    case 6: well_formed(); break;     // 1 embedded data item
    case 7: if (ai == 24 && val < 32) fail(); // bad simple
  }
  return mt;                    // definite-length data item
}

well_formed_indefinite(mt, breakable) {
  switch (mt) {
    case 2: case 3:
      while ((it = well_formed(true)) != -1)
        if (it != mt)           // need definite-length chunk
          fail();               //    of same type
      break;
    case 4: while (well_formed(true) != -1); break;
    case 5: while (well_formed(true) != -1) well_formed(); break;
    case 7:
      if (breakable)
        return -1;              // signal break out
      else fail();              // no enclosing indefinite
    default: fail();            // wrong mt
  }
  return 99;                    // indefinite-length data item
}

void encode_sint(int64_t n) {
  uint64t ui = n >> 63;    // extend sign to whole length
  unsigned mt = ui & 0x20; // extract (shifted) major type
  ui ^= n;                 // complement negatives
  if (ui < 24)
    *p++ = mt + ui;
  else if (ui < 256) {
    *p++ = mt + 24;
    *p++ = ui;
  } else
       ...

1. unambiguous encoding of most common data formats from Internet standards
2. code compactness for encoder or decoder
3. no schema description needed
4. reasonably compact serialization
5. applicability to constrained and unconstrained applications
6. good JSON conversion
7. extensibility

Too much data:

There are input bytes left that were not consumed.This is only an error if the application assumed that the inputbytes would span exactly one data item. Where the applicationuses the self-delimiting nature of CBOR encoding to permitadditional data after the data item, as is done in CBORsequences [RFC 8742], for example, the CBOR decoder can simplyindicate which part of the input has not been consumed.

Too little data:

The input data available would need additionalbytes added at their end for a complete CBOR data item. This mayindicate the input is truncated; it is also a common error whentrying to decode random data as CBOR. For someapplications, however, this may not actually be an error, as theapplication may not be certain it has all the data yet and canobtain or wait for additional input bytes. Some ofthese applications may have an upper limit for how much additionaldata can appear; here the decoder may be able to indicate that theencoded CBOR data item cannot be completed within this limit.

Syntax error:

The input data are not consistent with therequirements of the CBOR encoding, and this cannot be remedied byadding (or removing) data at the end.

• a reserved value is used for additional information (28, 29, 30)
• major type 7, additional information 24, value < 32 (incorrect)
• incorrect substructure of indefinite-length byte string or text string (may only contain definite-length strings of the same major type)
• "break" stop code (major type 7, additional information 31) occurs in a value position of a map or except at a position directly in an indefinite-length item where also another enclosed data item could occur
• additional information 31 used with major type 0, 1, or 6

End of input in a head:

18, 19, 1a, 1b, 19 01, 1a 01 02, 1b 01 02 0304 05 06 07, 38, 58, 78, 98, 9a 01 ff 00, b8, d8, f8, f9 00, fa 0000, fb 00 00 00

Definite-length strings with short data:

41, 61, 5a ff ff ff ff 00,5b ff ff ff ff ff ff ff ff 01 02 03, 7a ff ff ff ff 00, 7b 7f ff ffff ff ff ff ff 01 02 03

Definite-length maps and arrays not closed with enough items:

81, 8181 81 81 81 81 81 81 81, 82 00, a1, a2 01 02, a1 00, a2 00 00 00

Tag number not followed by tag content:

c0

Indefinite-length strings not closed by a "break" stop code:

5f 41 00, 7f 61 00

Indefinite-length maps and arrays not closed by a "break" stop code:

9f, 9f 01 02, bf, bf 01 02 01 02, 81 9f, 9f 80 00, 9f 9f 9f 9f 9f ffff ff ff, 9f 81 9f 81 9f 9f ff ff ff

Subkind 1:

Reserved additional information values:

1c, 1d, 1e, 3c, 3d, 3e, 5c,5d, 5e, 7c, 7d, 7e, 9c, 9d, 9e, bc, bd, be, dc, dd, de, fc, fd, fe,

Subkind 2:

Reserved two-byte encodings of simple values:

f8 00, f8 01, f8 18, f8 1f

Subkind 3:

Indefinite-length string chunks not of the correct type:

5f 00 ff,5f 21 ff, 5f 61 00 ff, 5f 80 ff, 5f a0 ff, 5f c0 00 ff, 5f e0 ff, 7f41 00 ff

Indefinite-length string chunks not definite length:

5f 5f 41 00 ff ff, 7f 7f 61 00 ff ff

Subkind 4:

Break occurring on its own outside of an indefinite-length item:

ff

Break occurring in a definite-length array or map or a tag:

81 ff,82 00 ff, a1 ff, a1 ff 00, a1 00 ff, a2 00 00 ff, 9f 81 ff, 9f 82 9f81 9f 9f ff ff ff ff

Break in an indefinite-length map that would lead to an odd number of items (break in a value position):

bf 00 ff, bf 00 00 00 ff

Subkind 5:

Major type 0, 1, 6 with additional information 31:

1f, 3f, df

• the use of new xml2rfc functionality [RFC 7991];
• more explanation of the notation used;
• the update of references, e.g., from RFC 4627 to [RFC 8259], from CNN-TERMS to [RFC 7228], and from the 5.1 edition to the 11th edition of [ECMA262]; the addition of a reference to [IEEE754] and importation of required definitions; the addition of references to [C] and [Cplusplus20]; and the addition of a reference to [RFC 8618] that further illustrates the discussion in Appendix E;
• in the discussion of diagnostic notation (Section 8), the "Extended Diagnostic Notation" (EDN) defined in [RFC 8610] is now mentioned, the gap in representing NaN payloads is now highlighted, and an explanation of representing indefinite-length strings with no chunks has been added (Section 8.1);
• the addition of this appendix.

Carsten Bormann

Paul Hoffman