Subject: [Cbor] Review of draft-ietf-cbor-cddl -02

From: Jim Schaad <[email-masked]>
Date: Mon, 12 Mar 2018 00:39:06 +0000

I wish I could say that this document was ready to roll out, but I really
can't.

1.  The order of presentation in 2.1 does not really highlight groups.  A
better order would be Figure 2, Figure 3, Figure 3a (figure is missing a
label) and Figure 1.  That is start by talking about the group (hey it is
the major concept here isn't it) and then how to use it and then how it can
be implicit.  Starting w/ the implicit version makes it confusing about what
a group is.

2.  Talking about binding of operators would make delivery in section 2.2 a
much clearer example.   I first looked at this and assumed that the binding
of a GROUP CHOICE would tie to a group.  Thus 
delivery = (
                   street: tstr, ? number: uint, (city //
                   po-box: uint),( city //
                   per-pickup: true) )

                   city = (
                   name: tstr, zip-code: uint
                   )

Which is wrong, but w/o the needed input or parentheses is not unreasonable.
Just adding the parens, while cluttered, makes sense as you then know what
groups are being referred to.

3.  Section 3.2 - I really which that occurrences were placed at a tighter
scope level than group.  The current binding level produces some surprises
to users that I think are not desirable.   The discussion in section 3.11
should be promoted to highlight that this is going to be a problem for
people.  The fact that 
	group9 = ( a / + b / c)

This would seem to be very obvious, it applies only to be, but that is
wrong.  So have a discussion here where people are going to look for one.

4.  Section 3.5 - There seems to be an order problem with cuts that needs to
be clarified.  Consider the following:

	map44 =  {
                      ? "option-key" ^ => int,
                       * tstr => any,
                       ? "option2-key" ^ => tstr,
                      ? "option-key" ^=> tstr
             }

>From the rules as I read them, option-key is restricted to being an int.
This is matched in order going from top to bottom.   There can never be an
option-key that is a tstr because there was already an option-key label that
had been processed.  A good compiler would produce an error in this case.
The label option2-key is never going to be matched because it was already
matched with the tstr wild card before it was matched.

The issue with option-key being in the list twice is going to be a potential
problem where two groups accidently produce add on modules to a base module
with the same label in map44.  The order in which these two add on modules
is processed (or if only one is processed) is going to produce different
grammars that all allow for the option-key label to be present, but not
cross usable because of the type issue.

5. Section 3.7 - It is not clear from the text if one should be able to
apply a ~ twice to an element.  The grammar does not appear to support the
idea of applying a ~ to tagged value as in time.  "time" is a type name and
not a group name.

6. Section 3.10 - from the text I cannot tell if generics are restricted to
types or if they can be used for both types and groups.

7.  Section 3.11 - When "fixing" the third example, using parens makes more
sense to me than using a group operator.   I am not sure why
    group4a = ((+a) / b / c)
is not one of the examples that is show.  There is no reason to go to the
less clear group choice operator.

8.  Table 1 is missing the ~ operator.

9.  I don't really understand why you made the "use with JSON" section to be
part of appendix E rather than a top level appendix.  Perhaps setup as ---
here are the differences and then a section w/ the JSON specific standard
prelude.  

10.  I see there are 10 Editorial Comments that have yet to be resolved.

Jim