Last Call Review of draft-ietf-asdf-sdf-18
review-ietf-asdf-sdf-18-genart-lc-knodel-2024-05-16-00

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.