Subject: [Cbor] Working Group Last Call on draft-ietf-cbor-cddl-04

From: Barry Leiba <[email-masked]>
Date: Mon, 13 Aug 2018 17:38:06 -0400

(Re-sending this, because I meant to change the subject line and
forgot to, and it's too easy to miss a WGLC that doesn't have an
explicit subject.)

The chairs are starting a working group last call on this document,
ending on Wednesday, 22 August.  Everyone, please check this version
out and let us know if there's something that's still missed.  Also
let us know if you think it's ready to go.

Jeffrey and Carsten are already discussing Jeffrey's issue with the
"can produce" terminology, so that's good....

Barry

On Fri, Aug 10, 2018 at 8:16 AM,  <[email-masked]> wrote:
>
> A New Internet-Draft is available from the on-line Internet-Drafts directories.
> This draft is a work item of the Concise Binary Object Representation Maintenance and Extensions WG of the IETF.
>
>         Title           : Concise data definition language (CDDL): a notational convention to express CBOR and JSON data structures
>         Authors         : Henk Birkholz
>                           Christoph Vigano
>                           Carsten Bormann
>         Filename        : draft-ietf-cbor-cddl-04.txt
>         Pages           : 59
>         Date            : 2018-08-10
>
> Abstract:
>    This document proposes a notational convention to express CBOR data
>    structures (RFC 7049).  Its main goal is to provide an easy and
>    unambiguous way to express structures for protocol messages and data
>    formats that use CBOR or JSON.
>
>
> The IETF datatracker status page for this draft is:
> https://datatracker.ietf.org/doc/draft-ietf-cbor-cddl/
>
> There are also htmlized versions available at:
> https://tools.ietf.org/html/draft-ietf-cbor-cddl-04
> https://datatracker.ietf.org/doc/html/draft-ietf-cbor-cddl-04
>
> A diff from the previous version is available at:
> https://www.ietf.org/rfcdiff?url2=draft-ietf-cbor-cddl-04
>
>
> Please note that it may take a couple of minutes from the time of submission
> until the htmlized version and diff are available at tools.ietf.org.
>
> Internet-Drafts are also available by anonymous FTP at:
> ftp://ftp.ietf.org/internet-drafts/
>
> _______________________________________________
> CBOR mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/cbor

---

From: Jim Schaad <[email-masked]>
Date: Mon, 20 Aug 2018 22:41:11 -0700

Section 2.1 -  the following could probably be made simpler:
   each of which can be a
   name/value pair or a more complex group expression composed of name/
   value pairs.

Perhaps - each of which can be a name/value pair or a group.

Section 2.1 - for clarity suggest:
	s/group is  important, as it is the information/ group is important,
as the sequence is the information/

Section 2.1 - It is unclear for Figure 1 if the term 'right' is being used
in the sense of directly or in the sense of correctly.

Section 2.1 - I still suggest adding the parens rather than have an implicit
group definition in figure 1 for better clarity.  Either that or reverse the
order of Figure 2 and Figure 3 so that you define a group first and then do
in an implicit manner.  I really don't like the order of presentation of
these figures.  They should be in the order of education that the order of
common usage - this is a teaching document.  (Thus 2, 3, 4, 1 is my
preferred order.)

Section 2.1.2 - According to the text in the syntax section the following is
legal
    Group = ( high:low

	The start is optional, the end is optional.  Nothing is said about
pairing.

Section 2.1.2 - third bullet - the third case that a colon is ok would be if
the key is never going to be used (i.e. a group for an array)

Section 2.2.1 - para #2 - sentence 1 - you seem to be missing some type of
transition or jump before the reference to appendix B

Appendix B - per the grammar the following is legal
    s /= "string"
    s //= (foo:bar)

This is because all of the assign operators are in a single rule rather than
being broken up according to  if a type or a group assignment is being made.

Section 2.2.2.1  In the last paragraph, did you intend to say the right hand
side no the left hand side?  I do not believe that the following would ever
be legal.
    min .. max = 5

Section 2.2.3 - The description in the first paragraph does not appear to
match the ABNF syntax.  Nor from the description would I know how to deal
with encoding some of the options.
 Per the text - the following appear to be legal 
     f1 = #(tstr) ;   optionally followed by major type option not positive
if the additional info is optional
     f2 = #.999(tstr)  ; optional major type followed by additional info
     f3 = #1.22(tstr)  ; no restriction on the value of the major type

There is nothing in the description that talks about when the parens would
be used and when thy are omitted.

Section 3.1 - What should the behavior be for a hex value which for which |
val | % 2 == 1?  Don't' see anything that says that the length must be even.
Not a problem for B64 if one assumes that trailing equals are optional.

Section 3.5.1 -  Example PersonalData - it says that the first and family
names are a map of text strings, but I think they are just text strings
unless my eyes are deceiving me.

Section 3.8 - I am not sure what is meant by combining multiple controls on
a single target.  I assume that the syntax "(target .control-operator1
controller1) .control-operator2 controller2" is allowed.  In what way would
this not normally be equivalent and should this be discussed in the
document?

Section 3.8.6 - the order of the controls and the description of the
constraint do not match in order.  Current text says that .gt is "equal to"

Section 3.9 - the rule that definitions for socket names MUST be
augmentations conflicts with the previous rule which says that the first
definition could use '='.

Section 5 - I think that it would be good to add some text about extension
points.  If nothing else they make the security analysis for an application
that uses them more difficult.  This is esp. true given that we have no
agreement on how things do or do not match when using extension points and
anys.

Section 6 - Are there any requirements that the Expert Reviewer should apply
to the syntax to make sure that the resulting items will all be able to be
parsed?  Specifically something like .operator X Y might cause problems.

Appendix A -  Better text might be "This appendix is intentionally left
empty." As text of the appendix.  This is not necessary if there is an
expectation that the appendixes are going to be renumbered during
publication.  You should also include a comment to the RFC Editor about the
fact that you want to keep this appendix section and why.  I would expect
the IESG to complain about this.

Appendix C - You say that the order of the rules is significant in to cases,
but I have no idea what those two cases are.

s/his point/this point/

 jim

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 21 Aug 2018 11:36:59 +0200

Hi Jim,

thank you!

I have prepared a new version at

https://cbor-wg.github.io/cddl/draft-ietf-cbor-cddl.html
http://gg.gg/cddl-editor-diff

> common usage - this is a teaching document.  (Thus 2, 3, 4, 1 is my

Hmm, the current sequence is the result of acting on an earlier comment that
the examples (which were then closer to the sequence you suggest) where starting with an uncommon case.
If more people have an opinion on this, I’d like to hear that.

> being broken up according to  if a type or a group assignment is being made.

Right.  (This example actually triggers a bug in the cddl tool, thank you.)
The grammar allows a bit more than is semantically meaningful.
Do you think this is a big problem?
I have split assign into assignt and assigng, but I’m not sure I like that very much.

> side no the left hand side?  I do not believe that the following would ever

This is about the LHS of the range operator, not of the whole rule.  Clarified.

> Not a problem for B64 if one assumes that trailing equals are optional.

(That is actually a problem for b64 as well, because the length cannot be 1
modulo 4.)  Clarified a bit.

> this not normally be equivalent and should this be discussed in the

This was a comment about a limitation of the CDDL tool; we don't need
that comment.  (The example you give is indeed allowed by CDDL.)

> parsed?  Specifically something like .operator X Y might cause problems.

The registration cannot add syntax, it only can add control operators
that use the existing syntax.

> the IESG to complain about this.

Good point.  Filled the gap with the examples (as Appendix H).

> but I have no idea what those two cases are.

Hmm, text for those two cases is in the appendix:

# The first rule defines the semantics of the entire specification; […]

# The creation of the type choices and group choices from the
# right hand sides of rules is the other case where rule order can be significant.

Do we need to clarify that more?

Grüße, Carsten

---

From: Jim Schaad <[email-masked]>
Date: Tue, 21 Aug 2018 19:32:30 -0700

> -----Original Message-----
> From: Carsten Bormann <[email-masked]>
> Sent: Tuesday, August 21, 2018 2:37 AM
> To: Jim Schaad <[email-masked]>
> Cc: [email-masked]
> Subject: Re: [Cbor] Working Group Last Call on draft-ietf-cbor-cddl-04
> 
> Hi Jim,
> 
> thank you!
> 
> > Section 2.1 - I still suggest adding the parens rather than have an
> > implicit group definition in figure 1 for better clarity.  Either that
> > or reverse the order of Figure 2 and Figure 3 so that you define a
> > group first and then do in an implicit manner.  I really don't like
> > the order of presentation of these figures.  They should be in the
> > order of education that the order of common usage - this is a teaching
> > document.  (Thus 2, 3, 4, 1 is my preferred order.)
> 
> > This is because all of the assign operators are in a single rule
> > rather than being broken up according to  if a type or a group assignment is
> being made.
> 
> Right.  (This example actually triggers a bug in the cddl tool, thank you.) The
> grammar allows a bit more than is semantically meaningful.

I found this while looking at trying to make a version of the grammar that would work as LALR(n).  (I doubt that I will get this mail out before the call tomorrow.)  I guess the question is one of should the grammar be correct or does it just need to be good enough.

> 
> > Section 2.2.2.1  In the last paragraph, did you intend to say the
> > right hand side no the left hand side?  I do not believe that the
> > following would ever be legal.
> >    min .. max = 5
> 

Looks fine

> 
> > Section 3.1 - What should the behavior be for a hex value which for
> > which | val | % 2 == 1?  Don't' see anything that says that the length must be
> even.

That helps - and avoids the question of the hex string being right or left padded.

> 
> > Section 3.8 - I am not sure what is meant by combining multiple
> > controls on a single target.  I assume that the syntax "(target
> > .control-operator1
> > controller1) .control-operator2 controller2" is allowed.  In what way
> > would this not normally be equivalent and should this be discussed in
> > the document?
> 
> This was a comment about a limitation of the CDDL tool; we don't need that
> comment.  (The example you give is indeed allowed by CDDL.)
> 
> > Section 6 - Are there any requirements that the Expert Reviewer should
> > apply to the syntax to make sure that the resulting items will all be
> > able to be parsed?  Specifically something like .operator X Y might cause
> problems.
> 
> The registration cannot add syntax, it only can add control operators that use
> the existing syntax.
> 
> > Appendix A -  Better text might be "This appendix is intentionally
> > left empty." As text of the appendix.  This is not necessary if there
> > is an expectation that the appendixes are going to be renumbered
> > during publication.  You should also include a comment to the RFC
> > Editor about the fact that you want to keep this appendix section and
> > why.  I would expect the IESG to complain about this.
> 
> > Appendix C - You say that the order of the rules is significant in to
> > cases, but I have no idea what those two cases are.
> 
> # The creation of the type choices and group choices from the # right hand
> sides of rules is the other case where rule order can be significant.

I don't even know what that sentence says.

> Do we need to clarify that more?

Yes I think that you do.  I would like to get a mention of what the second rule is right after saying that there are two cases where it is significant.   Having to fish a long ways down in the text to find the second example makes things difficult.

Jim

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 22 Aug 2018 14:29:47 +0200

On Aug 22, 2018, at 04:32, Jim Schaad <[email-masked]> wrote:
> I don’t even know what that sentence says.

The example is:

A /= a
A /= b
A /= c

The order of the rules matters, because the order in the resulting choice matters:

A = a / b / c

> Yes I think that you do.  I would like to get a mention of what the second rule is right after saying that there are two cases where it is significant.   Having to fish a long ways down in the text…

OK, I cleaned this up a bit in the commit https://github.com/cbor-wg/cddl/commit/ca3a044 — I hope that helps.

Grüße, Carsten

---

From: Jim Schaad <[email-masked]>
Date: Wed, 22 Aug 2018 07:48:49 -0700

That fixes my issue.

> Sent: Wednesday, August 22, 2018 5:30 AM
> >> # The creation of the type choices and group choices from the # right
> >> hand sides of rules is the other case where rule order can be significant.
> >
> > Yes I think that you do.  I would like to get a mention of what the second rule
> is right after saying that there are two cases where it is significant.   Having to
> fish a long ways down in the text to find the second example makes things
> difficult.
> 
> OK, I cleaned this up a bit in the commit https://github.com/cbor-
> wg/cddl/commit/ca3a044 — I hope that helps.
> 
> Grüße, Carsten