CBOR: Generating Numeric Map Labels from Textual EDN

The mapkey<<>> application extension: importing map labels from CDDL

Problem In diagnostic notation examples, authors often would prefer to use text names in place of the integer map keys that are used in a protocol message for efficiency. While the e'' application extension provides a way to associate names with integer data items, the protocol designer must be very careful to use the right name for the kind of map that uses the integer key: Different specifications may use different integer numbers for a key with the same textual name, and even in a single specification there may be homonyms that resolve to different integer values in different kinds of maps (e.g., in , alg is represented by 1 in headers and by 3 in COSE_Key). For example, Figure 4 in contains this example that employs nested maps: To check this example, a human reviewer has to look up the integer labels in the specifications for the different maps employed and translate them to the names of the map keys defined for each type of map. The outer map is a CWT Claims Set (CCS), for which the labels 2 (sub) and 8 (cnf) are defined in and , respectively. Within cnf, the label for COSE_Key is also defined by , while the labels within that map are defined in Section of RFC 9052 . Map keys are also often an extension point, and obtaining their numeric values therefore also may require consulting an IANA registry. The objective of the present proposal is that a specification writer could employ an EDN app-extension that allows the example to read a bit like: > ]]> Note that this example not only uses names for map keys, but also uses names for map values 1 ("OKP") and 4 ("X25519"). Discussion: For use in EDN, the names need to be provided in some form that is a valid CBOR data item. In the example above, this is done in text strings; for increased clarity, it could be done in a more eye-catching way, e.g., as single-quoted (byte) strings or even in an e'...'-like construct.

Solution In many cases, the constants needed to handle the numeric map labels in this example are already available in a CDDL model, or could be easily made available in this way. For the example used in this section, provides CDDL for and , and provides CDDL for its own data types. Note that, to remain useful with extension points where new map keys are defined regularly, there needs to be a way to reference IANA registries for the name-to-integer translation; this is a separate problem for which a potential solution is presented in . This section needs to define where in the CDDL the names to be resolved are looked for; CDDL rule names are one obvious candidate, as are member names for group choices that are often employed for documentation (Figure 2 in shows member names such as "title", "detail", etc.): 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 ]]> This specification defines an app-extension mapkey<<>> with two parameters:

The name of the CDDL rule for the top level (here: Claims-Set), and
an EDN depiction of the data structure where names can be used in place of numeric map keys and values.

Note that the app-extension does not itself define where the CDDL definitions it uses come from. This information needs to come from the context of the example, and there is probably value in establishing a convention.

Application-extension Identifier	Description
mapkey	import map labels from external CDDL

Application-extension Identifier

Description

mapkey

import map labels from external CDDL