[Cbor] Getting diagnostic notation examples in drafts under control

[Carsten Bormann <[e-mail]>]

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