Subject: [Last-Call] Iotdir telechat review of draft-ietf-cbor-7049bis-14

From: Eve Schooler via Datatracker <[email-masked]>
Date: Tue, 08 Sep 2020 12:11:50 -0700

Reviewer: Eve Schooler
Review result: Ready with Nits

The document is very thorough. In places, it provides a lot of detail upfront
that seems like it could be deferred until later sections and closer to the
topics at hand. For consistency and accuracy, the document would benefit from
review by the authors of the usage of may and must, capitalized or not, and
alternate terms (e.g., "does not", "can", "cannot", "might", etc.) that may
require replacement by those recommended by [RFC2119][RFC8174]. Explicit use of
"recommended" advice and usages could be beneficial. Given the length and
coverage of the spec, and given that this was a first read of the spec by this
reviewer, below are suggestions for additional forward/backward pointers to
sections where topics are mentioned (as I found myself flipping forward or
backward in the doc, in search of the first mention or deeper discussion), for
places where subsections and table names could use reconciling, for consistent
use of double quotes that highlight special terms, and a few places where
clarifications could help readability. The examples throughout are great,
though there are some places where examples are missing. It is also helpful
when a section includes an explanation of the primary purpose for a feature
(for example, tags are explained well on page 20, last paragraph); these kinds
of explanations are not always present. The linkage to IoT is given in the
document as advice for constrained node processing, though it would be
interesting -  now that the IoT Edge includes constrained as well as less
constrained nodes - to evaluate if there is also relevance for lower latency
IoT scenarios.

Page 8, after second bullet append: (Section 3.3)
Page 8, after 3rd bullet append: (Section 3.3)
Page 8, after last bullet append: (Section 3.4)
Page 8, dangling reference: ("map") --> considered a CBOR "map"
Page 8, first mention: tag content --> "tag content"
Page 9, major types are mentioned in multiple places at the end of Section 2 as
examples, but they aren't introduced until Section 3. Page 9, Table 7 --> Table
7 (Appendix B) Page 9, first defined: major type --> "major type" Page 9, first
mention: additional information --> "additional information" Page 11, top of
the page, the text reads, "both are described in Section 3.2", but there are
more than 2 types mentioned. Page 12, Major type 3: unclear what "specified
repertoire" means, unclear how to parse the "or" in the last sentence (never or
in addition), explicit example missing. Page 14, last paragraph of subsection
3.2 lead-in: maps --> maps (Section 3.2.2) Page 14, last paragraph of
subsection 3.2 lead-in: strings --> strings (Section 3 .2.3). Page 14, section
3.2.1, 2nd paragraph, hard to understand. Defer this information to the
following subsubsections where it will make more sense, after the nuances have
been explained. Page 17, section 3.2.4, lead-in sentence: indefinite length -->
indefinite-length Page 21: header for 3rd column in Table 5: Semantics --> Tag
content semantics Page 22: seems odd that tags 25 and  29 are given as examples
but do not appear in the table. Perhaps a reference to IANA.cbor-tags needs
inclusion nearby in the text, or the discussion of special serialization
considerations deferred to Section 4, which is focused on CBOR Serialization
Considerations. Alternatively perhaps the content of both paragraphs that come
after Table 5 are placed in their own table, which could focus on tags defined
elsewhere but that warrant some explanation here. Page 23: unclear what "civil
time" means. Perhaps include an in-line definition along the lines of "mean
solar time plus 12 hour". Page 23, paragraph 3: why use parentheses to explain
that "POSIX time is also known as UNIX Epoch time"? Epoch time is the name of
this section, so it is not a parenthetical statement. Page 23, paragraph 3:
what is the significance of the 2106 date? Page 29, first mention: preferred
encoding --> "preferred encoding" (to mimic the definitions in this section of
"preferred encoder", "variant encoder", "variation-tolerant decoder") Page 29,
3rd paragraph in section 4.1: there be said --> therefore be said Page 38,
section 5.5 and 5.6: doublecheck usage of may/can/MAY, MUST,
might/should/SHOULD Page 42: are free to use --> MAY use Page 44: last sentence
in section 6.2 - make sure the details of this vulnerability are mentioned or
cross-referenced in section 10 on Security. Page 48, section 9.2, first
paragraph: been defined --> been defined since then. Page 48, section 9.2: is
it customary to include the template for registration with the IANA? A template
is not given for section 9.1. Page 57, Appendix A: This appendix is called
"Examples". It seems like it should be called more specifically "Example
Diagnostic Notation" or "Examples of Encoded CBOR Data Items" (the same as the
name of the table). Page 61, Appendix B: This appendix is called "Jump Table".
It seems like it should be called more specifically "Jump Table for Initial
Byte" (same as the name of the table).