Defining media types with CBOR and CDDL

1.1. Terminology

Although this document is not an IETF Standards Track publication, it adopts the conventions for normative language to provide clarity of instructions to the implementer. 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.¶

2.1. The +cbor structured syntax suffix for CBOR data items

Section 9.5 of [RFC8949] registers a "structured syntax suffix" of +cbor for media types based on a single encoded CBOR data item.¶

The idea of a structured syntax suffix is that processors that do not know the specific semantics of a cbor-based media type can still process its syntactical structure once they recognize that the media type name ends in +cbor. While the usefulness of that often does not extend beyond diagnostics and debugging, this is still a valid motivation. Also, some generic processing schemes such as [I-D.ietf-cbor-packed] may be directly applicable to all +cbor-suffixed media types.¶

For example, SenML, in Section 6 of [RFC8428], defines a media type application/senml+cbor, among its related media types such as application/senml+json.¶

2.2. The +cbor-seq structured syntax suffix for CBOR sequences

Section 3 of [RFC8742] says:¶

[...] the "+cbor-seq" structured syntax suffix [...] SHOULD be used by a media type when the result of parsing the bytes of the media type object as a CBOR Sequence is meaningful and is at least sometimes not just a single CBOR data item. (Without the qualification at the end, this sentence this sentence is trivially true for any +cbor media type, which of course should continue to use the "+cbor" structured syntax suffix.)¶

application/missing-blocks+cbor-seq, as registered in Section 12.2 of [I-D.ietf-core-new-block], is an example.¶

2.3. Getting the media type registration

The media type registration template defined in [RFC6838] is full of historic arcana that is not often fully explained in that RFC. Appendix A defines a hypothetical media type application/foo+cbor.¶

A few aspects warrant further discussion:¶

• The Encoding considerations are often used in a way that is different from the intention in Section 4.8 of [RFC6838], which is a simple selection between "binary" and various alternatives that are now all obsolete.¶
• At the time of writing this, the Fragment identifier considerations are mostly irrelevant for CBOR; just in case we do come up with a fragment identifier syntax (based on [I-D.ietf-jsonpath-base]?), the boilerplate given in Appendix A can be used.¶
• The Intended Usage is always COMMON, except for OBSOLETE or LIMITED USE specifications. The latter case can probably best be elaborated as "call us before you use this". A Restrictions on usage field is provided to possibly reduce the number of phone calls in this case; otherwise that field is "N/A".¶
• [RFC6838] has fields Author and Change Controller. For IETF documents, the latter is always the IETF, as represented by the IESG (but see Appendix A).¶

2.4. Getting a Content-Format number registration

As per Section 12.3 of [RFC7252], a content format number registration requires an existing media-type registration, which you therefore need to do first (or at least in parallel). A Content-Format registration needs two additional pieces of information:¶

• Is there a content-coding (erroneously called "Encoding" in Section 12.3 of [RFC7252]) to be applied? This is usually the identity content-coding (usually registered as -), or it can be a compression scheme such as deflate [RFC1951], br (brotli, [RFC7932]), etc. For CBOR data items, traditional data compression does not often make a lot of sense (but it might, for large data items). An example for a content-format in the Content-Formats subregistry of the CoRE Parameters registry [IANA.core-parameters] that does have a non-identity content-coding is 11060, which is application/cbor with deflate content-coding.¶
• Which number range should the registration go into? Section 12.3 of [RFC7252] provides four ranges¶

A.1. Registration of Media Type application/foo+cbor

IANA is requested to register the following media type [RFC6838]:¶

Type name:

application¶

Subtype name:

foo+cbor¶

Required parameters:

N/A¶

Optional parameters:

N/A¶

Encoding considerations:

binary¶

Security considerations:

See the Security Considerations section of RFCXXXX.¶

Interoperability considerations:

N/A¶

Published specification:

RFCXXXX¶

Applications that use this media type:

(short description)¶

Fragment identifier considerations:

The syntax and semantics of fragment identifiers specified for application/multipart-core are as specified for application/cbor. (At publication of this document, there is no fragment identification syntax defined for application/cbor.)¶

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: iesg@ietf.org¶

Intended usage:

COMMON¶

Restrictions on usage:

N/A¶

Author:

FOO WG¶

Change controller:

IESG¶

Provisional registration? (standards tree only):

no¶