]> Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

CBOR numbers CBOR-based protocols often make use of numbers allocated in a registry. While developing the protocols, those numbers may not yet be available. This impedes the generation of data models and examples that actually can be used by tools. This short draft proposes a common way to handle these situations, without any changes to existing tools. Such changes are very well possible in the future, at which time this draft will be updated.

Introduction (Please see abstract.)

The Problem A CBOR-based protocol might want to define a structure using CDDL , like that in (based on ):

CDDL data model, final form oltext ? &(detail: -2) => oltext ? &(instance: -3) => ~uri ? &(response-code: -4) => uint .size 1 ? &(base-uri: -5) => ~uri ? &(base-lang: -6) => tag38-ltag ? &(base-rtl: -7) => tag38-direction / ... / * (uint .feature "extension") => any } ]]>

The key numbers shown in this structure are likely to be intended for allocation in an IANA section. The key numbers will be used in an example in the specification such as shown in .

CBOR-diag example, final form

However, during development, these numbers are not yet fixed; they are likely to move around as parts of the specification are added or deleted.

The Anti-Pattern What not to do during development:

CDDL data model, muddled form oltext ? "detail" => oltext ? "instance" => ~uri ? "response-code" => uint .size 1 ? "base-uri" => ~uri ? "base-lang" => tag38-ltag ? "base-rtl" => tag38-direction / ... / * (uint .feature "extension") => any } ]]>

CBOR-diag example, muddled form

This makes the model and the examples compile/check out without allocating numbers, but it also leads to several problems:

• It becomes hard to assess what the storage/transmission cost of these structures will be.
• What is being checked in the CI (continuous integration) for the document is rather different from the final form.
• Draft implementations trying to make use of these provisional structures have to cater for text strings, which may not actually be needed in the final form (which might expose specification bugs once numbers are used, too late in the process).
• The work needed to put in the actual numbers, once allocated, is significant and error-prone.
• It is not certain the CI system used during development can interact with the RFC editor's way of editing the document for publication.

What to do during spec development To make the transition to a published document easier, the document is instead written with the convention demonstrated in the following:

CDDL data model, development form oltext ? &(detail-CPA: -2) => oltext ? &(instance-CPA: -3) => ~uri ? &(response-code-CPA: -4) => uint .size 1 ? &(base-uri-CPA: -5) => ~uri ? &(base-lang-CPA: -6) => tag38-ltag ? &(base-rtl-CPA: -7) => tag38-direction / ... / * (uint .feature "extension") => any } ]]>

CPA is short for "code point allocation", and is a reliable search key for finding the places that need to be updated after allocation.An earlier concept for this draft used TBD in place of CPA, as do many draft specifications being worked on today. TBD is better recognized than CPA, but also could be misunderstood to mean further work by the spec developer is required. A document submitted for publications should not really have "TBD" in it. In the IANA section, the table to go into the registry is prepared as follows: IANA table, development form

Key value	Name	CDDL Type	Brief description	Reference
CPA-1	title	text / tag38	short, human-readable summary of the problem shape	RFC XXXX
CPA-2	detail	text / tag38	human-readable explanation specific to this occurrence of the problem	RFC XXXX
CPA-3	instance	~uri	URI reference identifying specific occurrence of the problem	RFC XXXX
CPA-4	response-code	uint .size 1	CoAP response code	RFC XXXX
CPA-5	base-uri	~uri	Base URI	RFC XXXX
CPA-6	base-lang	tag38-ltag	Base language tag (see tag38)	RFC XXXX
CPA-7	base-rtl	tag38-direction	Base writing direction (see tag38)	RFC XXXX

The provisionally made up key numbers will then be used in an example in the specification such as:

CBOR-diag example, development form

A "removeInRFC" note in the draft points the RFC editor to the present document so the RFC editor knows what needs to be done at which point. In the publication process, it is easy to remove the -CPA suffixes and CPA prefixes for the RFC editor while filling in the actual IANA allocated numbers and removing the note.

IANA Considerations This document makes no requests of IANA. However, it specifies a procedure that can be followed during draft development that has a specific role for IANA and the interaction between RFC editor and IANA at important points during this development. This procedure is intended to be as little of an onus as possible, but that is the author's assessment only. IANA feedback is therefore requested.

Security considerations The security considerations of and apply.

References Normative References The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. The present document defines a number of control operators that were not yet ready at the time RFC 8610 was completed: , , and for the construction of constants; / for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and for indicating the use of a non-basic feature in an instance. Informative References This document defines a concise "problem detail" as a way to carry machine-readable details of errors in a Representational State Transfer (REST) response to avoid the need to define new error response formats for REST APIs for constrained environments. The format is inspired by, but intended to be more concise than, the problem details for HTTP APIs defined in RFC 7807.

Acknowledgements This document was motivated by the AUTH48 experience for RFC 9200..RFC 9203. Then, Jaime Jiménez made me finally write this document. Marco Tiloca provided useful comments on an early presentation of this idea.