RFC 8742

RFC 8742: Concise Binary Object Representation (CBOR) Sequences 🎀

Title block, the tea ☕

• Series: Internet Engineering Task Force (IETF), Request for Comments: 8742
• Author: C. Bormann, Universität Bremen TZI
• Category: Standards Track
• Date: February 2020
• ISSN: 2070-1721
• Obsoletes/Updates: This title block doesn't list anything it obsoletes or updates, so there's nothing to report there 💅

Abstract ✨

Okay so this doc describes the CBOR Sequence format (CBOR = Concise Binary Object Representation 🦋) and its media type, application/cbor-seq. A CBOR Sequence is literally just any number of encoded CBOR data items stuck together end to end. No fancy wrapper, just vibes and concatenation 🫶

It also defines and registers +cbor-seq as a structured syntax suffix. Structured syntax suffixes let other media types build on top of a base type and make it super clear that's what's happening. Iconic, honestly 👑

Status of This Memo 📜

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community, it got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 🌸 Want more on Internet Standards? Check Section 2 of RFC 7841.

Info about the current status, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8742 💜

Copyright Notice 🌈

Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date. Please actually read these, bestie, because they spell out your rights and restrictions for this doc. Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, per the Simplified BSD License 🙈

Table of Contents 🧚

1.  Introduction
  1.1.  Conventions Used in This Document
2.  CBOR Sequence Format
3.  The "+cbor-seq" Structured Syntax Suffix
4.  Practical Considerations
  4.1.  Specifying CBOR Sequences in Concise Data Definition
        Language (CDDL)
  4.2.  Diagnostic Notation
  4.3.  Optimizing CBOR Sequences for Skipping Elements
5.  Security Considerations
6.  IANA Considerations
  6.1.  Media Type
  6.2.  CoAP Content-Format Registration
  6.3.  Structured Syntax Suffix
7.  References
  7.1.  Normative References
  7.2.  Informative References
Acknowledgements
Author's Address

1. Introduction 🍓

So, the Concise Binary Object Representation (CBOR) [RFC7049] can serialize data in the JSON [RFC8259] data model or in its own slightly bigger data model. When you're serializing a sequence of these values, it's sometimes SO convenient to have a format where you can just concatenate them to get the serialization of the whole sequence. Or where the sequence can keep growing at the end by just tacking on more CBOR data items ✨

This document describes the concept and format of "CBOR Sequences," which are made of zero or more encoded CBOR data items. Consumers (and producers) can handle CBOR Sequences incrementally. You don't need a streaming CBOR parser that can hand out pieces of a data item as they arrive, and you don't need a streaming encoder that builds from substructures piece by piece 🦋

This document defines and registers the application/cbor-seq media type in the "Media Types" registry, along with a Constrained Application Protocol (CoAP) Content-Format identifier. Media type structured syntax suffixes [RFC6838] were introduced so a media type can signal that it's built on another media type as its foundation. CBOR [RFC7049] already defines the +cbor structured syntax suffix. This document defines and registers the +cbor-seq structured syntax suffix in the "Structured Syntax Suffix Registry" 💅

1.1. Conventions Used in This Document 🎀

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Also, in this spec, "byte" is used in its now-customary sense as a synonym for "octet" 🫶

2. CBOR Sequence Format 🧩

Formally, a CBOR Sequence is a sequence of bytes, recursively defined as either of these:

• an empty (zero-length) sequence of bytes
• the sequence of bytes making up an encoded CBOR data item [RFC7049], followed by a CBOR Sequence

In short, concatenating zero or more encoded CBOR data items gives you a CBOR Sequence. (And concatenating zero or more CBOR Sequences also gives you a CBOR Sequence. Iykyk 🌸)

There is no end-of-sequence indicator. If you want one, CBOR-encode an array of the CBOR data model values being encoded, using either a definite or an indefinite length encoding, as a single CBOR data item. That's probably the more appropriate representation in that case 🙈

Unlike JSON Text Sequences [RFC7464], CBOR Sequences do not use a marker between items. That works because CBOR-encoded data items are self-delimiting, so the end can always be calculated. (Fun fact: the early object/array-only form of JSON was self-delimiting too, but that stopped being true once simple values like single numbers became valid JSON documents 💀)

Here's how decoding a CBOR Sequence works:

• If the CBOR Sequence is an empty sequence of bytes, the result is an empty sequence of CBOR data model values.
• Otherwise, you decode a single CBOR data item from the bytes of the CBOR Sequence, and insert the resulting CBOR data model value at the start of the result of repeating this decoding process recursively with the remaining bytes. (So a streaming decoder would deliver zero or more CBOR data model values, each one as soon as its bytes are available. Chef's kiss 👑)

This means that if any data item in the sequence is not well formed, you can't reliably decode the rest of the sequence. (An implementation might recover from some errors in a sequence of bytes that is almost, but not entirely, a well-formed encoded CBOR data item. Handling malformed data is outside the scope of this specification 🙈)

It also means CBOR Sequence format can reliably detect truncation of the bytes making up the last CBOR data item in the sequence, but it can't detect entirely missing CBOR data items at the end. A CBOR Sequence decoder used for streaming can just pause and wait for more data (for example, by suspending and later resuming decoding) if a truncated final item is coming in 🦋

3. The "+cbor-seq" Structured Syntax Suffix 💖

The use case for +cbor-seq is basically the same as for +cbor: a media type SHOULD use it when parsing the bytes of the media type object as a CBOR Sequence is meaningful and at least sometimes isn't just a single CBOR data item. (Without that last qualifier, this sentence is trivially true for any +cbor media type, which of course should keep using +cbor 💅)

So applications that run into a +cbor-seq media type can either use generic processing if all they need is a generic view of the CBOR Sequence, or use generic CBOR Sequence tools for the initial parse and then build their own specific processing on top 🧚

4. Practical Considerations 🌷

4.1. Specifying CBOR Sequences in Concise Data Definition Language (CDDL) 📝

In Concise Data Definition Language (CDDL) [RFC8610], CBOR Sequences are already supported as the contents of byte strings, using the .cborseq control operator (Section 3.8.4 of [RFC8610]) with an array as the controller type:

my-embedded-cbor-seq = bytes .cborseq my-array
my-array = [* my-element]
my-element = my-foo / my-bar

Right now, CDDL doesn't let you use unadorned CBOR Sequences as the top-level subject of a spec. For now, the suggestion is to use an array for the top-level rule (same as with the .cborseq control operator) and add English text explaining that the spec is really about a CBOR Sequence with the elements of the array 🎀

; This defines an array, the elements of which are to be used
; in a CBOR Sequence:
my-sequence = [* my-element]
my-element = my-foo / my-bar

(Future versions of CDDL might offer notation for top-level CBOR Sequences, for example by using a group as the top-level rule in a CDDL spec 🔮)

4.2. Diagnostic Notation 🔍

CBOR diagnostic notation (see Section 6 of [RFC7049]) or extended diagnostic notation (Appendix G of [RFC8610]) also doesn't let you write unadorned CBOR Sequences right now. (The latter does support CBOR Sequences embedded in a byte string, per Appendix G.3 of [RFC8610] 🫶)

In the same spirit as the CDDL recommendation above, this specification recommends enclosing the CBOR data items in an array. In a more informal setting, where the boundaries of the notation are obvious, you can also leave off the outer brackets for the array. Here are those two examples:

[1, 2, 3]

1, 2, 3

Heads up: it's kinda hard to talk about zero-length CBOR Sequences in that second form 💀

4.3. Optimizing CBOR Sequences for Skipping Elements ⚡

In some applications, being able to skip an element efficiently (without decoding its substructure), or fanning elements out to multi-threaded decoding processes efficiently, is of the utmost importance. For those, byte strings (which carry length information in bytes) containing embedded CBOR can be used as the elements of a CBOR Sequence 🏃‍♀️

; This defines an array of CBOR byte strings, the elements of which
; are to be used in a CBOR Sequence:
my-sequence = [* my-element]
my-element = bytes .cbor my-element-structure
my-element-structure = my-foo / my-bar

Within limits, this may also let you recover from elements that aren't internally well formed. The catch is that the sequence of byte strings does still need to be well formed as such 🙈

5. Security Considerations 🚨

Okay bestie, this section is SERIOUS. Read it all 😭

The security considerations of CBOR [RFC7049] apply. This format provides no cryptographic integrity protection of any kind, but it can be combined with security specs like CBOR Object Signing and Encryption (COSE) [RFC8152] to get that protection. (COSE protections can be applied to an entire CBOR Sequence, or to each element of the sequence independently. In the latter case, you might need extra effort if you need to protect the relationship between the elements in the sequence 🔐)

As usual, decoders must operate on input that's assumed to be untrusted. This means decoders MUST fail gracefully in the face of malicious inputs. No exceptions, no crashing out, no drama 💅

6. IANA Considerations 🦋

That's where part 1 ends, bestie. Part 2 picks up right here with the rest of the IANA Considerations and everything after it 🌈

6.1. Media Type 📮

Okay so media types live in the "Media Types" registry [IANA-MEDIA-TYPES], and IANA has officially registered the media type for CBOR Sequence, application/cbor-seq. Here's the full registration, no cap:

Type name: application

Subtype name: cbor-seq

Required parameters: N/A

Optional parameters: N/A

Encoding considerations: binary

Security considerations: See RFC 8742, Section 5.

Interoperability considerations: Described herein.

Published specification: RFC 8742.

Applications that use this media type: Data serialization and
deserialization.

Fragment identifier considerations: N/A

Additional information:

*  Deprecated alias names for this type: N/A

*  Magic number(s): N/A

*  File extension(s): N/A

*  Macintosh file type code(s): N/A

Person & email address to contact for further information:
   cbor@ietf.org

Intended usage: COMMON

Author: Carsten Bormann (cabo@tzi.org)

Change controller: IETF

---

6.2. CoAP Content-Format Registration 🦋

IANA also gave application/cbor-seq a CoAP Content-Format ID 💖. It lives in the "CoAP Content-Formats" subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry [IANA-CORE-PARAMETERS], and it came from the "Expert Review" (0-255) range ([RFC8126]). The ID they picked is shown in Table 1, and it's giving very organized ✨.

+----------------------+----------+----+-----------+
| Media type           | Encoding | ID | Reference |
+======================+==========+====+===========+
| application/cbor-seq | -        | 63 | RFC 8742  |
+----------------------+----------+----+-----------+

          Table 1: CoAP Content-Format ID

---

6.3. Structured Syntax Suffix 🎀

Structured Syntax Suffixes get registered in the "Structured Syntax Suffix Registry", which is maintained at [IANA-STRUCTURED-SYNTAX-SUFFIX]. IANA registered the "+cbor-seq" suffix under [RFC6838] like this:

Name: CBOR Sequence

+suffix: +cbor-seq

References: RFC 8742

Encoding considerations: binary

Fragment identifier considerations: The syntax and semantics of
fragment identifiers specified for +cbor-seq SHOULD be the same as
that specified for "application/cbor-seq".  (At the time of
publication of this document, there is no fragment identification
syntax defined for "application/cbor-seq".)

Now the fragment identifier part is where things get spicy 🌶️. The syntax and semantics for fragment identifiers on any specific "xxx/yyy+cbor-seq" SHOULD be processed like this:

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

And here's the rest of the registration:

Interoperability considerations: n/a

Security considerations: See RFC 8742, Section 5

Contact: CBOR WG mailing list (cbor@ietf.org), or any IESG-
designated successor.

Author/Change controller: IETF

---

7. References 📚

7.1. Normative References

[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-SYNTAX-SUFFIX]
          IANA, "Structured Syntax Suffix Registry",
          <https://www.iana.org/assignments/media-type-structured-
          suffix>.

[RFC2119]  Bradner, S., "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>.

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

[RFC8174]  Leiba, B., "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>.

7.2. Informative References

[RFC6838]  Freed, N., Klensin, J., 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>.

[RFC7464]  Williams, N., "JavaScript Object Notation (JSON) Text
          Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015,
          <https://www.rfc-editor.org/info/rfc7464>.

[RFC8091]  Wilde, E., "A Media Type Structured Syntax Suffix for JSON
          Text Sequences", RFC 8091, DOI 10.17487/RFC8091, February
          2017, <https://www.rfc-editor.org/info/rfc8091>.

[RFC8126]  Cotton, M., Leiba, B., 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>.

[RFC8152]  Schaad, J., "CBOR Object Signing and Encryption (COSE)",
          RFC 8152, DOI 10.17487/RFC8152, July 2017,
          <https://www.rfc-editor.org/info/rfc8152>.

[RFC8259]  Bray, T., Ed., "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]  Birkholz, H., Vigano, C., 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>.

---

Acknowledgements 🫶

This document is mostly generated from [RFC7464] by Nico Williams and [RFC8091] by Erik Wilde, which do a similar but slightly more complicated exercise for JSON [RFC8259]. Laurence Lundblade raised an issue on the CBOR mailing list that pointed out why this document was needed, and Jim Schaad and John Mattsson gave super helpful comments. Iconic behaviour from everyone 👑.

Author's Address 💌

Carsten Bormann
Universität Bremen TZI
Postfach 330440
D-28359 Bremen
Germany

Phone: +49-421-218-63921
Email: cabo@tzi.org