Notable CBOR Tags

1.1. Terminology

The definitions of [STD94] apply. Specifically: The term "byte" is used in its now customary sense as a synonym for "octet"; "byte strings" are CBOR data items carrying a sequence of zero or more (binary) bytes, while "text strings" are CBOR data items carrying a sequence of zero or more Unicode code points, encoded in UTF-8 [STD63]. Where bit arithmetic is explained, this document uses the notation familiar from the programming language C ([C], including C++14's 0bnnn binary literals [Cplusplus20]), except that superscript notation (example for two to the power of 64: 2⁶⁴) denotes exponentiation; in the plain text version of this document, superscript notation is rendered in paragraph text by C-incompatible surrogate notation as seen in this example. Ranges expressed using .. are inclusive of the limits given. Type names such as "int", "bigint" or "decfrac" are taken from Appendix D of [RFC8610], the Concise Data Definition Language (CDDL).¶

2.1. Tags Related to Those Defined in RFC 7049

Separately registered tags that are directly related to the tags predefined in RFC 7049 include:¶

• Tag 63, registered by this document (Section 11), is a parallel to tag 24, with the single difference that its byte string tag content carries a CBOR Sequence [RFC8742] instead of a single CBOR data item.¶

• Tag 257, registered by Peter Occil with a specification in http://peteroupc.github.io/CBOR/binarymime.html, is a parallel to tag 36, except that the tag content is a byte string, which therefore can also carry binary MIME messages as per [RFC2045].¶

• Tag 21065, being registered by this document (Section 11), is a parallel to tag 35, with the difference that its text string tag content carries an I-Regexp regular expression [RFC9485] instead of a regexp of a more unspecified flavor. Companion tag 21066, being registered by Joe Hildebrand with a specification in https://github.com/hildjj/cbor-specs/blob/main/regexp.md, is the equivalent for JavaScript (ECMA262), but besides the regular expression itself also can include the regular expression flags as a separate item.¶

2.2. Tags from RFC 7049 not listed in RFC 8949

Appendix G.3 of [STD94] states:¶

Tag 35 is not defined by this document; the registration based on the definition in RFC 7049 remains in place.¶

The reason for this exclusion is that the definition of Tag 35 in Section 2.4.4.3 of [RFC7049], leaves too much open to ensure interoperability:¶

Tag 35 is for regular expressions in Perl Compatible Regular Expressions (PCRE) / JavaScript syntax [ECMA262].¶

Not only are two partially incompatible specifications given for the semantics, JavaScript regular expressions have also developed significantly within the decade since JavaScript 5.1 (which was referenced as "ECMA262" by [RFC7049]), making it less reliable to assume that a producing application will manage to stay within that 2011 subset.¶

Nonetheless, the registration is in place, so it is available for applications that simply want to mark a text string as being a regular expression roughly of the PCRE/Javascript flavor families. See also Tag 21065 and 21066 above.¶

3.1. COSE

CBOR Object Signing and Encryption (COSE) is defined in a number of RFCs. [RFC8152] was the initial specification, set up the registries, and populated them with an initial set of assignments. A revision split this specification into the data structure definitions RFC9052, an Internet Standard [STD96], and a separate document defining the representation for the algorithms employed [RFC9053], which is expected to be updated more frequently than the COSE format itself. [RFC9054] added a separate set of algorithms for cryptographic hash functions (Hash functions have been a component of some [RFC9053] combined algorithms but weren't assigned separate codepoints). A revised COSE counter signature structure was defined in RFC9338, another part of [STD96]; this also defines a tag for these.¶

Standard_COSE_Hash<alg, value> =
    #6.<hashmiddle .plus (alg .within directhash)>(value)
General_COSE_Hash<alg, value> = #6.<hashmiddle>([
    hashAlg: alg .within (int .ne directhash  / tstr),
    hashValue: value .within bstr ])
hashmiddle = 18556
directhash = (-256 .. -1) / (1 .. 255)

18540(
 h'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9')

=============== NOTE: '\' line wrapping per RFC 8792 ================

d9 486c                                 # tag(18540)
   58 20                                # bytes(32)
      \
     b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

18556([-4711, h'1234123412341234123412341234123412341234'])

3.2. RFC 8392 (CWT)

[RFC8392] defines the CBOR Web Token (CWT), making use of COSE to define a CBOR variant of the JOSE Web Token (JWT), [RFC7519], a standardized security token that has found use in the area of web applications, but is not technically limited to those.¶

4.1. YANG-CBOR

YANG [RFC7950] is a data modeling language originally designed in the context of the Network Configuration Protocol (NETCONF) [RFC6241], now widely used for modeling management and configuration information. [RFC7950] defines an XML-based representation format, and [RFC7951] defines a JSON-based [RFC8259] representation format for YANG.¶

YANG-CBOR [RFC9254] is a representation format for YANG data in CBOR.¶

5.1. DOTS

DDoS Open Threat Signaling (DOTS) defines tag number 271 for the DOTS signal channel object in [RFC9132].¶

5.2. RAINS

As an example for how experimental protocols can make use of CBOR tag definitions, the RAINS (Another Internet Naming Service) Protocol Specification defines tag number 15309736 for a RAINS Message [I-D.trammell-rains-protocol]. (The seemingly random tag number was chosen so that, when represented as an encoded CBOR tag argument, it contains the Unicode character "雨" (U+96E8) in UTF-8, which represents rain in a number of languages.)¶

6.1. Advanced arithmetic

A number of tags have been registered for arithmetic representations beyond those built into CBOR and defined by tags in [RFC7049]. These are all documented under http://peteroupc.github.io/CBOR/; the last pathname component for the URL is given in Table 5.¶

CBOR's basic generic data model (Section 2 of [STD94]) has a number system with limited-range integers (major types 0 and 1: -2⁶⁴..2⁶⁴-1) and floating point numbers that cover binary16, binary32, and binary64 (including non-finites) from [IEEE754]. With the tags defined with [RFC7049], the extended generic data model (Section 2.1 of [STD94]) adds unlimited-range integers (tag numbers 2 and 3, "bigint" in CDDL) as well as floating point values using the bases 2 (tag number 5, "bigfloat") and 10 (tag number 4, "decfrac").¶

This pre-defined number system has a number of limitations that are addressed in three of the tags discussed here:¶

• Tag number 30 allows the representation of rational numbers as a ratio of two integers: a numerator (usually written as the top part of a fraction), and a denominator (the bottom part), where both integers can be limited-range basic and unlimited-range integers. The mathematical value of a rational number is the numerator divided by the denominator. This tag can express all numbers that the extended generic data model of [RFC7049] can express, except for non-finites [IEEE754]; it also can express rational numbers that cannot be expressed with denominators that are a power of 2 or a power of 10.¶

  For example, the rational number 1/3 is encoded:¶

    d8 1e      ---- Tag 30
       82      ---- Array length 2
          01   ---- 1
          03   ---- 3
  

  ¶

  Many programming languages have built-in support for rational numbers or support for them is included in their standard libraries; tag number 30 is a way for these platforms to interchange these rational numbers in CBOR.¶

• Tag numbers 4 and 5 are limited in the range of the (base 10 or base 2) exponents by the limited-range integers in the basic generic data model. Tag numbers 264 and 265 are exactly equivalent to 4 and 5, respectively, but also allow unlimited-range integers as exponents. While applications for floating point numbers with exponents outside the CBOR basic integer range are limited, tags 264 and 265 allow unlimited roundtripping with other formats that allow very large or very small exponents, such as those JSON [RFC8259] can provide if the limitations of I-JSON [RFC7493] do not apply.¶

The tag numbers 268..270 extend these tags further by providing a way to express non-finites within a tag with this number. This does not increase the expressiveness of the data model (the non-finites can already be expressed using major type 7 floating point numbers), but does allow both finite and non-finite values to carry the same tag. In most applications, a choice that includes some of the three tags 30, 264, 265 for finite values and major type 7 floating point values for non-finites (as well as possibly other parts of the CBOR number system) will be the preferred solution.¶

This document suggests using the CDDL typenames defined in Figure 2 for the three most useful tag numbers in this section.¶

rational = #6.30([numerator: integer, denominator: integer .ne 0])
rational_of<N,D> = #6.30([numerator: N, denominator: D])
; the value 1/3 can be notated as rational_of<1, 3>

extended_decfrac = #6.264([e10: integer, m: integer])
extended_bigfloat = #6.265([e2: integer, m: integer])

6.2. Variants of undefined

https://github.com/svaarala/cbor-specs/blob/master/cbor-absent-tag.rst defines tag 31 to be applied to the CBOR value Undefined (0xf7), slightly modifying its semantics to stand for an absent value in a CBOR Array.¶

(TO DO: Obtain permission to copy the definitions here.)¶

6.3. Typed and Homogeneous Arrays

[RFC8746] defines tags for various kinds of arrays. A summary is reproduced in Table 6.¶

7.1. Human-readable Text

Tag 38 was originally registered by Peter Occil in http://peteroupc.github.io/CBOR/langtags.html; it has since been adopted and extended in Appendix A of [RFC9290], where a detailed definition of the tag and a few simple examples for its use are provided.¶

The problem that this tag was designed to solve is that text strings often need additional information to be properly presented to a human. While Unicode (and the UTF-8 form of Unicode used in CBOR) define the characters, additional information about the human language in use and the writing direction appropriate for the text given are often required.¶

The need to provide language information with text has been well-known for a while and led to a common form for this information, the language tag, defined in [BCP47].¶

Less well-known is the need to provide separate directionality information as well. The need for this information is demonstrated in [W3C-STRINGS-BIDI], which points out that it is "actually a bad idea to rely on language information to apply direction" and points out further reference information on this. [W3C-BIDI-USE-CASES] shows more examples for language tags and directionality, while [W3C-UBA-BASICS] provides an introduction to the way browsers, where "the order of characters in memory (logical) is not the same as the order in which they are displayed (visual)", "produce the correct order at the time of display" (Unicode Bidirectional Algorithm).¶

Tag 38 meets the requirements of its specific application in [RFC9290], which could be summarized as: Supplying the necessary information to present isolated, linear, comparatively small pieces of human-readable text. It neither addresses more complex requirements of specific languages such as [W3C-SIMPLE-RUBY], nor does it address requirements for more complex structure in texts such as emphasis, lists, or tables. These more complex requirements are typically met by specific media types such as HTML [HTML].¶

7.2. Extended Time Formats

Additional tag definitions have been provided for date and time values.¶

Note that tags 100 and 1004 are for calendar dates that are not anchored to a specific time zone; they are meant to specify calendar dates as perceived by humans, e.g. for use in personal identification documents. Converting such a calendar date into a specific point in time needs the addition of a time-of-day (for which a CBOR tag is outstanding) and timezone information (also outstanding). Alternatively, a calendar date plus timezone information can be converted into a time period (range of time values given by the starting and the ending time); note that these time periods are not always exactly 24 h (86400 s) long.¶

[RFC8943] does not suggest CDDL [RFC8610] type names for the two tags. We suggest copying the definitions in Figure 3 into application-specific CDDL as needed.¶

caldate = #6.100(int); calendar date as # of days from 1970-01-01
tcaldate = #6.1004(tstr); calendar date as RFC 3339 full-date string

Tag 1001 extends tag 1 by additional information (such as picosecond resolution) and allows the use of Decimal and Bigfloat numbers for the time.¶

8.1. Perl

(These are actually not as Perl-specific as the title of this section suggests. See also the penultimate paragraph of Section 3.4 of [STD94].)¶

These are all documented under http://cbor.schmorp.de/; the last pathname component is given in Table 10.¶

(TO DO: Obtain permission to copy the definitions here.)¶

8.2. JSON

(TO DO: Obtain permission to copy the definitions here.)¶

Tag number 262 has been registered to identify byte strings that carry embedded JSON text (https://github.com/toravir/CBOR-Tag-Specs/blob/master/embeddedJSON.md).¶

Tag number 275 can be used to identify maps that contain keys that are all of type Text String, as they would occur in JSON (https://github.com/ecorm/cbor-tag-text-key-map).¶

8.3. Weird text encodings

(TO DO: Obtain permission to copy the definitions here.)¶

Some variants of UTF-8 are in use in specific areas of application. Tags have been registered to be able to carry around strings in these variants in case they are not also valid UTF-8 and can therefore not be represented as a CBOR text string (https://github.com/svaarala/cbor-specs/blob/master/cbor-nonutf8-string-tags.rst).¶

9.1. Enumerated Alternative Data Items

(Original Text for this section was contributed by Duncan Coutts and Michael Peyton Jones; all errors are the author's.)¶

A set of CBOR tag numbers has been allocated (Section 11) for encoding data composed of enumerated alternatives:¶

The tags defined in this section are for encoding data that can be in one of a number of different enumerated forms.¶

For example data representing the result of some action might be either a failure with some failure detail, or a success with some result. In this example there are two cases, the failure case and the success case, and we can enumerate them as 0 and 1.¶

In general the number of alternatives, and what data is expected in each alternative case is entirely application dependent.¶

The tags defined in this specification allow the encoding of any number of alternatives, but provide compact encoding for the common cases of low numbers of alternatives:¶

• Alternatives 0..6 can be encoded in 2 bytes;¶

• Alternatives 7..127 can be encoded in 3 bytes;¶

• Alternatives 128+ can be encoded in 3-12 bytes.¶

There are no special considerations for deterministic encoding Section 4.2 of [STD94]: The case numbers covered by each tag do not overlap; particularly, tag 101 encoding starts where the more compact special encodings for 0..6 and 7..127 end.¶

For cases 0..6 and 7..127, the tag value indicates the value of the alternative. For cases 128+, a single tag number is used with an enclosed two-element array that contains the case number and the value of the alternative.¶

result = #6.121([int, text])
       / #6.122(bytes)

121([3, "the printer is on fire"])

122(h'ff00')

-- A data type representing simple arithmetic expressions

data Expr = Lit Int -- integer literal
| Add Expr Expr -- addition
| Sub Expr Expr -- subtraction
| Neg Expr -- unary negation
| Mul Expr Expr -- multiplication
| Div Expr Expr -- integer division

; A data type representing simple arithmetic expressions

expr = 121(int)          ; integer literal
     / 122([expr, expr]) ; addition
     / 123([expr, expr]) ; subtraction
     / 124(expr)         ; unary negation
     / 125([expr, expr]) ; multiplication
     / 126([expr, expr]) ; integer division

10.1. Invalid Tag

The present document registers tag numbers 65535, 4294967295, and 18446744073709551615 (16-bit 0xffff, 32-bit 0xffffffff, and 64-bit 0xffffffffffffffff) as Invalid Tags, tags that are always invalid, independent of the tag content provided. The purpose of these tag number registrations is to enable the tag numbers to be reserved for internal use by implementations to note the absence of a tag on a data item where a tag could also be expected with that data item as tag content.¶

The Invalid Tags are not intended to ever occur in interchanged CBOR data items. Generic CBOR decoder implementations are encouraged to raise an error if an Invalid Tag occurs in a CBOR data item even if there is no validity checking implemented otherwise.¶