Managing CBOR numbers in Internet-Drafts

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 1 September 2024.¶

Copyright Notice

Copyright (c) 2024 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) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

(Please see abstract.) [RFC8949] [I-D.bormann-cbor-e-ref]¶

2. The Problem

A CBOR-based protocol might want to define a structure using CDDL [RFC8610][RFC9165], like that in Figure 1 (based on [RFC9290]):¶

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.¶

{
  / 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.¶

3. The Anti-Pattern

What not to do during development:¶

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
}

{
  "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.¶

4. 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.¶

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

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

{
  / 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):¶

{
  / 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: {
     / ... /
  }
}

/ title-CPA / -1

e'title'

5. 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.¶

6. Security considerations

The security considerations of [RFC8610] and [RFC8949] apply.¶

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.¶

Author's Address