Re: [Cbor] 🔔 WGLC on draft-ietf-cbor-7049bis-09

[Francesca Palombini <[e-mail]>]

Hi,

With a small delay, I just finished reviewing the CBOR specification v-09, reading top to bottom. In general, I am happy with the document, and only have minor/editorial suggestions, plus some questions on formulation.

Carsten and Paul, feel free to let me know if anything was addressed by recent updates.

Thanks,
Francesca

--
Questions:

* Section 3.4.7

While reading this again, I realized that CBOR sequences cannot be tagged, as by definition they are not one data item. I think being able to tag CBOR sequence with the self-describing tag in the scenario described in this section would be good.

* Section 4.2.2

Second to last sub-bullet: "If a protocol includes a field that can express integers..."

I noted an inconcistency here with the text on preferred encoding preferring using maj types 0 and 1 (see text in section 3.4.4. "The preferred encoding of an integer...")

* Section 9.5

Considering the Apps Area Working Group does not exist anymore, should the contact here being updated?



Minor/Editorials

* Contributing

It might be good to put in a note for the RFC Editor to remove this section.

* Section 1.1, Point 2, sub-bullet 1

For readability, I would put an example of "very small amount of code" number directly in the text, in the parenthesis when mentioning class 1 constrained nodes.

* Section 1.1, Point 4, sub-bullet 1

"and by implementation complexity maintining a lower bound" does not read correctly to me. Am I missing something?

* Section 1.1, Point 5, sub-bullet 1

I would suggest to add "for example for devices of class 1" as an example of what "reasonably frugal in CPU" means.

* Section 1.2

The term "representation format" is only used in this section twice, everywhere else "encoded data item" is used. I would go ahead and remove this formulation, and only use encoded data item. This would also make the part on decoder and encoder more symmetric (right now Decoder talks about "encoded data item" and Encoder talks about "represetnation format").

* Section 1.2, "Valid: "

This paragraph talks about "semantic restrictions that apply to CBOR data items"; it would be good to add a hint on where these are defined in the specification.

* Section 2

"A simple value, identified by a number between 0 and 255, but distinct from that number"

I had to read this sentence several times to understand that the part "but distinct from that number" is meant to note to the reader that the value of the item is not the number it's identified by. I would formulate as written here, rather than as it is now. ("Note that the value of the item is not the number it's identified by")

* Section 3.1, Major type 4

The text states that arrays can also be called sequences. With the publication of CBOR Sequences, can we remove this statement, as sequences are (although related) different things?

* Section 3.1, Major type 5

Using underscoring to highlight a term (in this case "pairs") should be explained in terminology.

* Section 3.1, Major type 6

To be consistent with other major types, it might be good to shortly mention ranges for tags here.

* Section 3.2

While the motivation for arrays and maps is obvious, I would have appreciated some more text on motivation (or an example of use case) where indefinite-length strings are useful.

* Section 3.2.3

I don't understand the link between the previous sentence and this one:

"   Note that this implies that the bytes of a single UTF-8 character
   cannot be spread between chunks: a new chunk can only be started at a
   character boundary."

Nor am I sure of the meaning of the term "spread" here.

* Section 3.3

Re-appearance of the term "sequence", which I would still avoid.

* Table 4

I would have explicitely stated what data items where allowed for each tag number, rather than writing multiple.

* Section 3.4.4

The term "preferred encoding" appears here for the first time without any reference or introduction.

* Section 3.4.5

"while the mantissa also can be" -> "while the mantissa can also be"

* Section 3.4.5

Expand NaN on first appearance here (instead of 5.6.1)

* Section 4.2.2

"may want to exclude them from interchange, interchanging"

I would reformulate this.

* Section 4.2.3

Capitalize section title

* Section 4.2.3

First paragraph: please add a reference to 4.2.1 when talking about core deterministic encoding requirements.

* Section 5.4

"A generic encoder also may want" -> "A generic encoder may also want"

* Section 5.6

"Duplicate keys are also prohibited by CBOR decoders that
   enforce validity (Section 5.4)."

I have a slight problem with the term "prohibited by" decoders... Decoders do not prohibit, at most they do not accept.

* Section 5.6

"except to specify that some, orders are disallowed" -> remove comma

* Section 7.1, last sub-bullet

Please reference section 7.2.

* Section 8.1

I like examples. I would have liked an example for the second paragraph of this section.

* Appendix G

"this may not be actually be an error" -> "this may not actually be an error"