Managing CBOR numbers in Internet-Drafts
Internet-Draft draft-bormann-cbor-draft-numbers-03
Carsten Bormann
Universität Bremen TZI
Postfach 330440
Bremen
D-28359
Germany
+49-421-218-63921
cabo@tzi.org
29 February 2024
CBOR numbers
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.) [RFC8949] [I-D.bormann-cbor-e-ref]
The Problem
A CBOR-based protocol might want to define a structure using CDDL [RFC8610][RFC9165], like that in Figure 1 (based on [RFC9290]):
CDDL data model, final form

problem-details = {
  ? &(title: -1) => 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 Figure 2.
CBOR-diag example, final form

{
  / title /         -1: "title of the error",
  / detail /        -2: "detailed information about the error",
  / instance /      -3: "coaps://pd.example/FA317434",
  / response-code / -4: 128, / 4.00 /
  4711: {
     / ... /
  }
}

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

problem-details = {
  ? "title" => 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

{
  "title": "title of the error",
  "detail": "detailed information about the error",
  "instance-code": "coaps://pd.example/FA317434",
  "response-code": 128, / 4.00 /
  4711: {
     / ... /
  }
}

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

problem-details = {
  ? &(title-CPA: -1) => 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:
CBOR-diag example, development form

{
  / title-CPA /         -1: "title of the error",
  / detail-CPA /        -2: "detailed information about the error",
  / instance-CPA /      -3: "coaps://pd.example/FA317434",
  / response-code-CPA / -4: 128, / 4.00 /
  4711: {
     / ... /
  }
}

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 Table 1, 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 Table 1 could have this approximate contents:
This document uses the CPA (code point allocation) convention described in [I-D.bormann-cbor-draft-numbers]. 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 Figure 6 could have this approximate contents:
This document uses the CPA (code point allocation) convention described in [I-D.bormann-cbor-draft-numbers]. 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 Table 2 and Figure 7 (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
CBOR-diag example, final form

{
  / title /         -10: "title of the error",
  / detail /        -20: "detailed information about the error",
  / instance /      -30: "coaps://pd.example/FA317434",
  / response-code / -40: 128, / 4.00 /
  4711: {
     / ... /
  }
}

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 [BCP9] and/or [BCP100] 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
[I-D.bormann-cbor-e-ref] defines a CBOR diagnostic notation application extension that allows CBOR diagnostic notation 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 CBOR diagnostic notation, 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 CBOR diagnostic notation more readable and less distracting, replacing constructs such as

/ title-CPA / -1

by

e'title'

which removes the need to mention "CPA" and to provide a potentially distracting copy of the value assignment in the example.)
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 [RFC8610] and [RFC8949] apply.
References
Normative References
[RFC8949]

Concise Binary Object Representation (CBOR)
C. Bormann
P. Hoffman
December 2020
STD 94
RFC 8949
DOI 10.17487/RFC8949
[RFC8610]

Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures
H. Birkholz
C. Vigano
C. Bormann
June 2019
RFC 8610
DOI 10.17487/RFC8610
[RFC9165]

Additional Control Operators for the Concise Data Definition Language (CDDL)
C. Bormann
December 2021
RFC 9165
DOI 10.17487/RFC9165
[I-D.bormann-cbor-draft-numbers]

Managing CBOR numbers in Internet-Drafts
Carsten Bormann
Universität Bremen TZI
2 September 2023
Internet-Draft draft-bormann-cbor-draft-numbers-02
[I-D.bormann-cbor-e-ref]

External References to Values in CBOR Diagnostic Notation (EDN)
Carsten Bormann
Universität Bremen TZI
29 February 2024
Internet-Draft draft-bormann-cbor-e-ref-00
Informative References
[RFC9290]

Concise Problem Details for Constrained Application Protocol (CoAP) APIs
T. Fossati
C. Bormann
October 2022
RFC 9290
DOI 10.17487/RFC9290
[RFC2026]

The Internet Standards Process -- Revision 3
S. Bradner
October 1996
BCP 9
RFC 2026
DOI 10.17487/RFC2026
[RFC5657]

Guidance on Interoperation and Implementation Reports for Advancement to Draft Standard
L. Dusseault
R. Sparks
September 2009
BCP 9
RFC 5657
DOI 10.17487/RFC5657
[RFC6410]

Reducing the Standards Track to Two Maturity Levels
R. Housley
D. Crocker
E. Burger
October 2011
BCP 9
RFC 6410
DOI 10.17487/RFC6410
[RFC7100]

Retirement of the "Internet Official Protocol Standards" Summary Document
P. Resnick
December 2013
BCP 9
RFC 7100
DOI 10.17487/RFC7100
[RFC7127]

Characterization of Proposed Standards
O. Kolkman
S. Bradner
S. Turner
January 2014
BCP 9
RFC 7127
DOI 10.17487/RFC7127
[RFC7475]

Increasing the Number of Area Directors in an IETF Area
S. Dawkins
March 2015
BCP 9
RFC 7475
DOI 10.17487/RFC7475
[RFC8789]

IETF Stream Documents Require IETF Rough Consensus
J. Halpern, Ed.
E. Rescorla, Ed.
June 2020
BCP 9
RFC 8789
DOI 10.17487/RFC8789
[RFC9282]

Responsibility Change for the RFC Series
B. Rosen
June 2022
BCP 9
RFC 9282
DOI 10.17487/RFC9282
[RFC7120]

Early IANA Allocation of Standards Track Code Points
M. Cotton
January 2014
BCP 100
RFC 7120
DOI 10.17487/RFC7120
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 Section 4.1. Carl Wallace provided further comments shining light on the practical aspects of the proposals.