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

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

A couple of more quick comments.

*  In appendix B - The ANBF has 

   grpent = [occur S] [memberkey S] type optcom
          / [occur S] groupname [genericarg] optcom ; preempted by above
          / [occur S] "(" S group S ")" optcom

The last option in the rule is redundant.  "(" group ")" will be reduced to
a type via type2 => type1 => type so this is not needed.

*  Security considerations

Having played around with some of the grammar and looking at things, I
believe that there needs to be a security consideration around the following
issue.  You can really do harm to yourself when writing a grammar.  There
are tons of things that can be expressed that are going to lead to confusion
on the part of other readers and implementers.  Writing a complex grammar is
going to lead to incorrect implementations.  When writing down a CDDL
grammar, keep it as simple as possible while still expressing the needed
language.   

*  A note needs to be added to section 3.5 on one of the dangers of using a
bareword as a member name.  If you are writing a grammar that is intended to
be extended by having people append additional information to the current
module, one can unexpectedly change the grammar when using a barewood as a
new module may define the barewood as a type.  (Potentially 5 levels down.)

Example

X = (  ipaddr : ipv6Address / ipv4Address }

The next module then defines

Ipaddr = [? macAddress, tstr, ipv4Address / ipv6Address]

The bareword member name has now been converted into a type.

Jim

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 12 Mar 2018 08:24:39 +0100

Hi Jim,

thanks for the additional comments.

(I just returned from a two-week vacation and I’m processing mail in a mix of SJN/LIFO.)

> On Mar 12, 2018, at 07:35, Jim Schaad <[email-masked]> wrote:
> 

In the CDDL spec

Foo = {
  ? ( k1: int, k2: bytes )
  k3: float
}

The second line does not match the grpent’s first alternative with “type”, so the third alternative for grpent is actually needed.

However, maybe it is worth pointing out in the text that the second line in

Foo = {
  ? ( Bar )
  k3: float
}

Bar = (k1: int, k2: bytes)

is indeed matched the way you describe; the ABNF grammar cannot always reliably distinguish between groups and types (and any type does serve as a keyless single-entry group anyway), so some semantic check is needed in a tool.

> grammar, keep it as simple as possible while still expressing the needed

This point indeed cannot be stressed enough.  (It is rather obvious to people who have witnessed what happens when people start speccing away in languages like ASN.1…)  Just because CDDL makes it easier to handle complexity in a specification, that does not make that complexity somehow less bad (except on the level of the humans having to grasp the complex structure while reading the spec).

> The bareword member name has now been converted into a type.

That is not what happens: A bareword stays a bare word, even if a rule is added that uses the same word.

Tools should probably **warn** when this happens (keep a list of barewords that are in use, warn if any rule has the same name as the bareword), but it is not an error exactly for the reason you point out: unrelated use in a different part of the spec.

Is there any text that should be fixed to make the intended behavior more obvious?

Grüße, Carsten

---

From: Jim Schaad <[email-masked]>
Date: Mon, 12 Mar 2018 07:57:21 +0000

> -----Original Message-----
> From: Carsten Bormann <[email-masked]>
> Sent: Monday, March 12, 2018 7:25 AM
> To: Jim Schaad <[email-masked]>
> Cc: [email-masked]; [email-masked]
> Subject: Re: Review comments draft-ietf-cbor-cddl-02
> 
> Hi Jim,
> 
> > The last option in the rule is redundant.  "(" group ")" will be
> > reduced to a type via type2 => type1 => type so this is not needed.
> 
> In the CDDL spec
> 
> Foo = {
>   ? ( k1: int, k2: bytes )
>   k3: float
> }
> 
> The second line does not match the grpent’s first alternative with “type”, so
> the third alternative for grpent is actually needed.

--- Yuck -- { vs ( is sometimes hard to see esp if the font is small.

> is indeed matched the way you describe; the ABNF grammar cannot always
> reliably distinguish between groups and types (and any type does serve as a
> keyless single-entry group anyway), so some semantic check is needed in a
> tool.
> 
> > believe that there needs to be a security consideration around the
> > following issue.  You can really do harm to yourself when writing a
> > grammar.  There are tons of things that can be expressed that are
> > going to lead to confusion on the part of other readers and
> > implementers.  Writing a complex grammar is going to lead to incorrect
> > implementations.  When writing down a CDDL grammar, keep it as simple
> as possible while still expressing the needed
> > language.
> 
> This point indeed cannot be stressed enough.  (It is rather obvious to people
> who have witnessed what happens when people start speccing away in
> languages like ASN.1…)  Just because CDDL makes it easier to handle
> complexity in a specification, that does not make that complexity somehow
> less bad (except on the level of the humans having to grasp the complex
> structure while reading the spec).

I am not worried about the complexity of the spec, I am worried about the complexity of the CDDL.  These are very different issues.

> 
> 
> > *  A note needs to be added to section 3.5 on one of the dangers of
> > using a bareword as a member name.  If you are writing a grammar that
> > is intended to be extended by having people append additional
> > information to the current module, one can unexpectedly change the
> > grammar when using a barewood as a new module may define the
> barewood
> > as a type.  (Potentially 5 levels down.)
> >
> > Example
> >

I have completely missed how this would be true.  Are you saying that

X = { five : int }
five = 5

is not the same as

X = { 5 : int }

How does the checker know when a rule that uses the same word is "added" vs in the base specification?

Jim

> 
> Tools should probably **warn** when this happens (keep a list of
> barewords that are in use, warn if any rule has the same name as the
> bareword), but it is not an error exactly for the reason you point out:
> unrelated use in a different part of the spec.
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 12 Mar 2018 10:44:18 +0100

> 
> — Yuck -- { vs ( is sometimes hard to see esp if the font is small.

Right — we have experienced this effect as well.
There are some “programmers’ fonts” that focus on distinction of characters; it is best to use one of those with CDDL (or for any kind of work with computer languages beyond COBOL, actually).

(We also discussed the alternative of making the distinction more heavy in the CDDL grammar — this would lose the recognizability of { and [ for people thinking in diagnostic notation/JSON.)

> I am not worried about the complexity of the spec, I am worried about the complexity of the CDDL.  These are very different issues.

Thanks — my mind latched on the other issue too fast.
Pointing this one out is also useful.  
Do we want to provide some specific considerations here (what to avoid, how to phrase things in a simpler way)?  (I tend to think such a “style guide” would become very long quickly and probably should go into a separate document.)

> I have completely missed how this would be true.  Are you saying that

Yes, and I think the draft is also saying this.
We could add an example explicitly calling this out.

> How does the checker know when a rule that uses the same word is “added" vs in the base specification?

It doesn’t, so any message about a bareword looking like an existing rule name always will be a warning only.

Grüße, Carsten

---

From: Jeffrey Yasskin <[email-masked]>
Date: Mon, 12 Mar 2018 16:23:22 +0000

On Mon, Mar 12, 2018 at 2:44 AM Carsten Bormann <[email-masked]> wrote:

> There are some “programmers’ fonts” that focus on distinction of
> characters; it is best to use one of those with CDDL (or for any kind of
> work with computer languages beyond COBOL, actually).
>
> (We also discussed the alternative of making the distinction more heavy in
> the CDDL grammar — this would lose the recognizability of { and [ for
> people thinking in diagnostic notation/JSON.)
>
> >
> > I am not worried about the complexity of the spec, I am worried about
> the complexity of the CDDL.  These are very different issues.
>
> Do we want to provide some specific considerations here (what to avoid,
> how to phrase things in a simpler way)?  (I tend to think such a “style
> guide” would become very long quickly and probably should go into a
> separate document.)
>
> >

Specifically, to use a type, you have to use the `=>` form. Using `:`
forces either a bareword or a value. This is somewhat described in
https://tools.ietf.org/html/draft-ietf-cbor-cddl-02#section-3.5.1 with

> "an identifier that is followed by a colon can be directly used as the
text string for a member key ...
> all the types defined can be used in a keytype position by following them
with a double arrow."

but because that's phrased as a tutorial instead of a specification, it's
not clear exactly what the rules are. The grammar is a little more clear:

> memberkey = type1 S ["^" S] "=>"
>             / bareword S ":"
>             / value S ":"

But since a grammar only describes syntax, not semantics, it's plausible
that implementations will pick Jim's interpretation, and interpret an id
before a colon as a type instead of a bareword.
<https://www.ietf.org/mailman/listinfo/cbor>

Jeffrey

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 12 Mar 2018 17:56:27 +0100

Now https://github.com/cbor-wg/cddl/issues/10

Grüße, Carsten