[Cbor] Iotdir telechat review of draft-ietf-cbor-7049bis-14
Eve Schooler via Datatracker <email@example.com> Tue, 08 September 2020 19:11 UTC
Received: from ietfa.amsl.com (localhost [IPv6:::1]) by ietfa.amsl.com (Postfix) with ESMTP id A121D3A0E0F; Tue, 8 Sep 2020 12:11:50 -0700 (PDT)
Content-Type: text/plain; charset="utf-8"
From: Eve Schooler via Datatracker <firstname.lastname@example.org>
Cc: email@example.com, firstname.lastname@example.org, email@example.com, firstname.lastname@example.org
Reply-To: Eve Schooler <email@example.com>
Date: Tue, 08 Sep 2020 12:11:50 -0700
Subject: [Cbor] Iotdir telechat review of draft-ietf-cbor-7049bis-14
List-Id: "Concise Binary Object Representation \(CBOR\)" <cbor.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/cbor>, <mailto:firstname.lastname@example.org?subject=unsubscribe>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/cbor>, <mailto:email@example.com?subject=subscribe>
X-List-Received-Date: Tue, 08 Sep 2020 19:11:51 -0000
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).
- [Cbor] Iotdir telechat review of draft-ietf-cbor-… Eve Schooler via Datatracker