Reviewer: Mallory Knodel Review result: Ready with Issues I am the assigned Gen-ART reviewer for this draft. The General Area Review Team (Gen-ART) reviews all IETF documents being processed by the IESG for the IETF Chair. Please treat these comments just like any other last call comments. For more information, please see the FAQ at <https://wiki.ietf.org/en/group/gen/GenArtFAQ>. Document: draft-ietf-asdf-sdf-?? Reviewer: Mallory Knodel Review Date: 2024-05-14 IETF LC End Date: 2024-05-22 IESG Telechat date: Not scheduled for a telechat Summary: Clearly a very well considered and important document for internet of things network specifications. Major issues: None. Minor issues: * 1.1. The definition for "Grouping" is unsatisfying. Its definition relies on other terminology that invokes this term, resulting self-referential definitions. "Grouping: An sdfThing or sdfObject, i.e., (directly or indirectly) a combination of Affordances." What, as well, is the relationship to the defined term "Group"? * 1.1. "Affordance" might appear after "Thing". As a general comment, perhaps the terminology section requires a sweep to better organise the order of definitions for improved and easier comprehension. For example, the order of Augmentation Mechanism and Protocol Binding should probably be swapped. * General comment, and 1.1., "object" and "map" are mentioned throughout (almost 200+ together) yet the treatment of the relationship of these two terms in JSON is rather cavalier. For dispelling confusion, suggest entering both as separate terms that clearly indicate they are interchangeable, and when they are not. * 4.2. It is unclear how this description relates to Figure 1. Suggest invoking the relationship to Figure 1 but entirely reworking Figure 1 as a new figure for this section with the example URLs indicated explicitly. Nits/editorial comments: * The capitalisation of terms defined in 1.1. appear inconsistently in the text. * 1. Suggest Conventions as a separate subsection as 1.2. and to include the short paragraph about byte, the one convention expressed already, as well as the BCP 14 text. * 2.1. Parentheticals might be minimised overall, but for example: ** (The third type of affordance [sic] is Events, which are not described in this example.) -- This can just be a sentence. ** ... how (with the exception of the info group) maps that have... -- The parenthetical is both disruptive to the sentence because of where it's placed and also indicates important information as an exception, thereby suggesting it should be its own sentence. * 2.2.2. para 2 -- Parenthetical can be a sentence. * 2.3.3. penultimate para -- "(one or more)" should not be in parenthensis. * et cetera. * 4.5. bullet 2: "The affordance/grouping itself..." since affordance and grouping are two separate terms, suggest "The affordance or grouping itself..." * 4.7. item 1 para 2: Again, unwise to put a SHOULD NOT in a parenthetical. * Suggest referencing RFC8610 when the use of CDDL is first introduced, rather than first in the security considerations and then in the appendix. -- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
