Re: [Cbor] Getting diagnostic notation examples in drafts under control

[Wolf McNally <[e-mail]>]

Carsten,

I was wondering about the right way to declare CBOR tag values in a single place and then use them as symbols throughout the rest of my CDDL. For example, something like:

```cddl
tag-my-struct = #6.123456

; …

my-struct = tag-my-struct(
    bstr .size 32
)
```

~ Wolf

> On Feb 26, 2024, at 12:31 PM, Carsten Bormann <[e-mail]> wrote:
> 
> In diagnostic notation examples used during development of a draft,
> authors often use text strings for the constants they need, even
> though they actually mean a placeholder for a later, to-be-registered
> integer.
> 
> I just reviewed draft-ietf-ace-oscore-gm-admin, where this is rampant:
> 
>      {
>          "group_mode" : true,
>          "gp_enc_alg" : 10,
>                "hkdf" : 5
>      }
> 
> All the map keys shown here that look like text strings are actually
> intended to be integers (which at this point still need to be
> assigned).
> (There are also integers, without explanation what they mean.)
> 
> This is a problem, as the examples are not machine-readable (well,
> they are, but they mean the wrong thing in half of the places without
> any warning that this is so).
> 
> At IETF 118, I gave a brief concept presentation for an application
> extension to CBOR diagnostic mode that I called e’’.
> (The name `e` could stand for enum value, or external constant, etc.
> You choose :-)
> 
> I have implemented this now in the cbor-diag tools.
> 
> First, you need a CDDL file (we’ll call gmadmin.cddl in our example)
> that gives the actual values for the constants, as in:
> 
>   group_mode = 33
>   gp_enc_alg = 34
>   hkdf = 31
>   HMAC-256-256 = 5
>   AES-CCM-16-64-128 = 10
> 
> This can be a complete CDDL file, no need to limit it to constants.
> You can set this up with your TBD values of the constants to be
> assigned, and once they are, you only need to update them in one place.
> 
> Then, you can write the diagnostic notation example in the draft like
> this (let’s call this gmadmin.diag):
> 
>      {
>          e'group_mode' : true,
>          e'gp_enc_alg' : e'HMAC-256-256',
>                e'hkdf' : e'AES-CCM-16-64-128'
>      }
> 
> The diag2x.rb tools can correctly read and interpret this; so for example
> after setting
> 
>   export CBOR_DIAG_CDDL=gmadmin.cddl
> 
> applying diag2diag.rb to gmadmin.diag spits out:
> 
> $ diag2diag.rb -ae gmadmin.diag
> {33: true, 34: 10, 31: 5}
> 
> You need to enable the application extension `e` (-ae), which you can
> install via:
> 
>  gem install cbor-diag-e cddlc
> 
> (cbor-diag-e uses cddlc internally, so it must be in PATH.)
> 
> The details of this little tool are certainly up for discussion, but it
> really does work for me already.
> 
> In the long run, this works best if edn-literal is approved (hint,
> hint), and the `e''` extension is registered.
> 
> Until then, each document using this scheme can simply use boilerplate
> such as:
> 
> In the CBOR diagnostic notation used in this document, constructs of
> the form `e’somename'` are replaced by the value assigned to
> `somename` in CDDL in figure 0815.
> E.g., `{e'group_mode': "bar"}` stands for `{33: "bar"}`.
> [Choose 0815, group_mode and 33 along the lines of the figure with the
> CDDL included.]
> 
> Should I write an Internet-Draft for this?
> 
> Grüße, Carsten
> 
> 
> _______________________________________________
> CBOR mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/cbor