Managing CBOR codepoints in Internet-Drafts

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.