Network Working Group                                         C. Bormann
Internet-Draft                                    Universität Bremen TZI
Intended status: Informational                             13 March 2023
Expires: 14 September 2023

                Managing CBOR numbers in Internet-Drafts
                  draft-bormann-cbor-draft-numbers-01

Abstract

   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.

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 14 September 2023.

Copyright Notice

   Copyright (c) 2023 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

Bormann                 Expires 14 September 2023               [Page 1]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

   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  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  The Problem . . . . . . . . . . . . . . . . . . . . . . . . .   2
   3.  The Anti-Pattern  . . . . . . . . . . . . . . . . . . . . . .   3
   4.  What to do during spec development  . . . . . . . . . . . . .   4
     4.1.  Documents with Significant Generated Content Depending on
           Assignments . . . . . . . . . . . . . . . . . . . . . . .   7
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
   6.  Security considerations . . . . . . . . . . . . . . . . . . .   8
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .   9
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .   9

1.  Introduction

   (Please see abstract.)  [RFC8949]

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
   }

                   Figure 1: CDDL data model, final form

Bormann                 Expires 14 September 2023               [Page 2]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

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

                  Figure 2: 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.

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

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
   }

                  Figure 3: CDDL data model, muddled form

Bormann                 Expires 14 September 2023               [Page 3]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

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

                 Figure 4: CBOR-diag 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.

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:

Bormann                 Expires 14 September 2023               [Page 4]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

   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
   }

                Figure 5: CDDL data model, development form

   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:

Bormann                 Expires 14 September 2023               [Page 5]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

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

                   Table 1: IANA table, development form

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

Bormann                 Expires 14 September 2023               [Page 6]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

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

               Figure 6: 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.

   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.

4.1.  Documents with Significant Generated Content Depending on
      Assignments

   Many documents have examples (which might even involve signatures
   overf 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.

Bormann                 Expires 14 September 2023               [Page 7]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

   // We probably need a indicator in addition to CPA that signifies an
   // example or other text must be regenerated (vs. simply be updated
   // by IANA).

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.

7.  References

7.1.  Normative References

   [RFC8610]  Birkholz, H., Vigano, C., and C. Bormann, "Concise Data
              Definition Language (CDDL): A Notational Convention to
              Express Concise Binary Object Representation (CBOR) and
              JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610,
              June 2019, <https://www.rfc-editor.org/rfc/rfc8610>.

   [RFC8949]  Bormann, C. and P. Hoffman, "Concise Binary Object
              Representation (CBOR)", STD 94, RFC 8949,
              DOI 10.17487/RFC8949, December 2020,
              <https://www.rfc-editor.org/rfc/rfc8949>.

   [RFC9165]  Bormann, C., "Additional Control Operators for the Concise
              Data Definition Language (CDDL)", RFC 9165,
              DOI 10.17487/RFC9165, December 2021,
              <https://www.rfc-editor.org/rfc/rfc9165>.

7.2.  Informative References

   [BCP100]   Cotton, M., "Early IANA Allocation of Standards Track Code
              Points", BCP 100, RFC 7120, January 2014.

   [BCP9]     Bradner, S., "The Internet Standards Process -- Revision
              3", BCP 9, RFC 2026, October 1996.

              Dusseault, L. and R. Sparks, "Guidance on Interoperation
              and Implementation Reports for Advancement to Draft
              Standard", BCP 9, RFC 5657, September 2009.

Bormann                 Expires 14 September 2023               [Page 8]
Internet-Draft  Managing CBOR numbers in Internet-Drafts      March 2023

              Housley, R., Crocker, D., and E. Burger, "Reducing the
              Standards Track to Two Maturity Levels", BCP 9, RFC 6410,
              October 2011.

              Resnick, P., "Retirement of the "Internet Official
              Protocol Standards" Summary Document", BCP 9, RFC 7100,
              December 2013.

              Kolkman, O., Bradner, S., and S. Turner, "Characterization
              of Proposed Standards", BCP 9, RFC 7127, January 2014.

              Dawkins, S., "Increasing the Number of Area Directors in
              an IETF Area", BCP 9, RFC 7475, March 2015.

              Halpern, J., Ed. and E. Rescorla, Ed., "IETF Stream
              Documents Require IETF Rough Consensus", BCP 9, RFC 8789,
              June 2020.

              Rosen, B., "Responsibility Change for the RFC Series",
              BCP 9, RFC 9282, June 2022.

   [RFC9290]  Fossati, T. and C. Bormann, "Concise Problem Details for
              Constrained Application Protocol (CoAP) APIs", RFC 9290,
              DOI 10.17487/RFC9290, October 2022,
              <https://www.rfc-editor.org/rfc/rfc9290>.

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

   Carsten Bormann
   Universität Bremen TZI
   Postfach 330440
   D-28359 Bremen
   Germany
   Phone: +49-421-218-63921
   Email: cabo@tzi.org

Bormann                 Expires 14 September 2023               [Page 9]