Hi Mallory,
thanks for the review!
I’ve unwrapped the comments but have made no other edits to them.
<start of unwrapped section>
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.
<end of unwrapped section>
Cheers,
Niklas, for the chairs
On 2024-05-16, 18:41, "Mallory Knodel via Datatracker" <nore...@ietf.org> wrote:
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://eur02.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwiki.ietf.org%2Fen%2Fgroup%2Fgen%2FGenArtFAQ&data=05%7C02%7Cniklas.widell%40ericsson.com%7C568ba0aeb3b94003743c08dc75c70425%7C92e84cebfbfd47abbe52080c6b87953f%7C0%7C0%7C638514744827068481%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C0%7C%7C%7C&sdata=n3d6QDaUN63allZpzc1Ujsmrl1R3EQzlewMSL5waYZk%3D&reserved=0<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
_______________________________________________
Gen-art mailing list -- gen-art@ietf.org
To unsubscribe send an email to gen-art-le...@ietf.org
