]> Universität Bremen TZI

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

CBOR codepoints CBOR-based protocols often make use of numbers allocated in a registry. During development of 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. Also, in conjunction with the application-oriented EDN literal e'', a further reduction in editorial processing of CBOR examples around the time of approval can be achieved.

Introduction (Please see abstract.) This document uses "EDN" (extended diagnostic notation) as a shorthand for "CBOR diagnostic notation" as defined in Section of RFC 8949 , extended in , and updated in .

The Problem A CBOR-based protocol might want to define a structure using the Concise Data Definition Language (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 the one shown in EDN in .

EDN 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 } ]]>

EDN example, muddled form

This makes the model and the examples compile/check out even before having allocated the actually desired 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 example: This document uses the keys for a map as an example. Other such constructs involving assigned numbers might also require temporary values for exposition in a specification, e.g., CBOR tags. For the sake of keeping this document short, examples for these are not given. Including examples of other things that generate the need for temporary numbers, like tags, would be good.

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 publication 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:

EDN 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. Note that in , the first column uses the name "CPA-1" for a value that in the rest of the document is assumed to be "-1" (and indicating a preference by the document author for this number); IANA as well as the designated experts involved are expected by the present document to decode this notation.

A "removeInRFC" note to the RFC Editor for could have this approximate contents:

This document uses the CPA (code point allocation) convention described in . For each entry, please remove the prefix "CPA" from the indicated value of the column <REG_COLUMN>, and replace the residue with the value assigned by IANA; perform the same substitution for all other occurrences of the prefix "CPA" in the document. Finally, please remove this note.

A "removeInRFC" note to the RFC Editor for could have this approximate contents:

This document uses the CPA (code point allocation) convention described in . For each item whose key textual identifier has suffix "-CPA", please remove the suffix. Then, consider the residue of the suffix removal, and replace the key numeric identifier with the value assigned by IANA in the <REG_COLUMN_1> of the registry <REG_NAME>, for the entry where the value in the <REG_COLUMN_2> is equal to the residue. Finally, please remove this note.

The RFC editor with IANA would then execute these instructions as shown in and (assuming the unlikely case that all numbers allocated are ten times the number proposed): IANA table, final form

Key value	Name	CDDL Type	Brief description	Reference
-10	title	text / tag38	short, human-readable summary of the problem shape	RFC XXXX
-20	detail	text / tag38	human-readable explanation specific to this occurrence of the problem	RFC XXXX
-30	instance	~uri	URI reference identifying specific occurrence of the problem	RFC XXXX
-40	response-code	uint .size 1	CoAP response code	RFC XXXX
-50	base-uri	~uri	Base URI	RFC XXXX
-60	base-lang	tag38-ltag	Base language tag (see tag38)	RFC XXXX
-70	base-rtl	tag38-direction	Base writing direction (see tag38)	RFC XXXX

EDN example, final form

Documents with Significant Generated Content Depending on Assignments Many documents have examples (which might even involve signatures over the contents) that depend on the assignments in more than the trivial way shown above, and regenerating them may not be easy for the RFC editor to do. Therefore, for these documents we need another step involving the authors: Immediately after allocation, but before the RFC-Editor EDIT step, the authors need to regenerate these examples and other generated content depending on the exact allocations. In the current process, allocation is usually done after IESG approval, after IANA action, so we would need to halt the EDIT step for this regeneration. Alternatively, we could be more aggressive in invoking some kind of IANA Early Allocation process, near the end of the IESG review. One way to do this with current tooling and process is to perform a late form of actual IANA "Early" Allocation. Or we could amend and/or in a more fundamental way. We probably need an indicator in addition to CPA that signifies an example or other text must be regenerated (vs. simply be updated by IANA) when proposed numbers are updated by IANA.

Reducing the editorial workload with CDDL definitions defines a EDN application extension that allows EDN to reference constants defined in a CDDL model, the e'' application extension. If the draft contains a CDDL model that includes definitions of constants that may then be used in EDN, the use of e'' constant references makes it unnecessary to change the constant value in the example when final values are defined for these constants. (This application extension also can make the EDN more readable and less distracting, replacing constructs such as by which removes the need to mention "CPA" and to provide a potentially distracting copy of the value assignment in the example.) The document using the e'' application extension may want to provide a CDDL file with provisional assignments, as in: This file should be clearly labeled as CPA, i.e., not yet assigned and subject to change during allocation.

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:.plus,.cat, and.det for the construction of constants;.abnf/.abnfb for including ABNF (RFC 5234 and RFC 7405) in CDDL specifications; and.feature for indicating the use of a non-basic feature in an instance. The Concise Data Definition Language (CDDL), as defined in RFCs 8610 and 9165, provides an easy and unambiguous way to express structures for protocol messages and data formats that are represented in Concise Binary Object Representation (CBOR) or JSON. This document updates RFC 8610 by addressing related errata reports and making other small fixes for the ABNF grammar defined for CDDL. The Concise Data Definition Language (CDDL), standardized in RFC 8610, provides "control operators" as its main language extension point. RFCs have added to this extension point in both an application-specific and a more general way. The present document defines a number of additional generally applicable control operators for text conversion (bytes, integers, printf-style formatting, and JSON) and for an operation on text. Universität Bremen TZI CBOR-based protocols often make use of numbers allocated in a registry. During development of 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. Also, in conjunction with the application-oriented EDN literal e'', a further reduction in editorial processing of CBOR examples around the time of approval can be achieved. Universität Bremen TZI This document formalizes and consolidates the definition of the Extended Diagnostic Notation (EDN) of the Concise Binary Object Representation (CBOR), addressing implementer experience. Replacing EDN's previous informal descriptions, it updates RFC 8949, obsoleting its Section 8, and RFC 8610, obsoleting its Appendix G. It also specifies and uses registry-based extension points, using one to support text representations of epoch-based dates/times and of IP addresses and prefixes. // (This cref will be removed by the RFC editor:) The present -19 // includes the definition of the cri'' application- extension. cri'' // was previously defined in draft-ietf-core-href; however the latter // document overtook the present document in the approval process. // As the definition of cri'' is dependent on the present document // (and conversely has essentially no dependency on the technical // content of draft-ietf-core-href beyond its mere existence), the // text (including IANA considerations) has been moved here. -19 is // intended for use at the CBOR WG meeting at IETF 124. Universität Bremen TZI The Concise Binary Object Representation (CBOR, RFC 8949) 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. CBOR diagnostic notation (EDN) is widely used to represent CBOR data items in a way that is accessible to humans, for instance for examples in a specification. At the time of writing, EDN did not provide mechanisms for composition of such examples from multiple components or sources. This document uses EDN application extensions to provide two such mechanisms, both of which insert an imported data item into the data item being described in EDN: The e'' application extension provides a way to import data items, particularly constant values, from a CDDL model (which itself has ways to provide composition). The ref'' application extension provides a way to import data items that are described in EDN. 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. This memo documents the process used by the Internet community for the standardization of protocols and procedures. It defines the stages in the standardization process, the requirements for moving a document between stages and the types of documents used during this process. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Advancing a protocol to Draft Standard requires documentation of the interoperation and implementation of the protocol. Historic reports have varied widely in form and level of content and there is little guidance available to new report preparers. This document updates the existing processes and provides more detail on what is appropriate in an interoperability and implementation report. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document updates the Internet Engineering Task Force (IETF) Standards Process defined in RFC 2026. Primarily, it reduces the Standards Process from three Standards Track maturity levels to two. This memo documents an Internet Best Current Practice. This document updates RFC 2026 to no longer use STD 1 as a summary of "Internet Official Protocol Standards". It obsoletes RFC 5000 and requests the IESG to move RFC 5000 (and therefore STD 1) to Historic status. RFC 2026 describes the review performed by the Internet Engineering Steering Group (IESG) on IETF Proposed Standard RFCs and characterizes the maturity level of those documents. This document updates RFC 2026 by providing a current and more accurate characterization of Proposed Standards. This document removes a limit on the number of Area Directors who manage an Area in the definition of "IETF Area". This document updates RFC 2026 (BCP 9) and RFC 2418 (BCP 25). This document requires that the IETF never publish any IETF Stream RFCs without IETF rough consensus. This updates RFC 2026. In RFC 9280, responsibility for the RFC Series moved to the RFC Series Working Group and the RFC Series Approval Board. It is no longer the responsibility of the RFC Editor, and the role of the IAB in the RFC Series is altered. Accordingly, in Section 2.1 of RFC 2026, the sentence "RFC publication is the direct responsibility of the RFC Editor, under the general direction of the IAB" is deleted. This memo describes the process for early allocation of code points by IANA from registries for which "Specification Required", "RFC Required", "IETF Review", or "Standards Action" policies apply. This process can be used to alleviate the problem where code point allocation is needed to facilitate desired or required implementation and deployment experience prior to publication of an RFC, which would normally trigger code point allocation. The procedures in this document are intended to apply only to IETF Stream documents.

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. Michael Richardson pointed out the issues that led to . Carl Wallace provided further comments shining light on the practical aspects of the proposals.