[Updated Mallory’s mail address:] Hi Mallory, thank you for the review, indeed! (And another thank you to Niklas for unpacking the items.) It took us a while to get to work on these comments… Now in PR #172 [172] (merged), with individual commits identified below. [172]: https://github.com/ietf-wg-asdf/SDF/pull/172 > 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.” While the definitions are indeed cyclic, they don’t depend on that cycle. A Grouping really is an sdfThing or an sdfObject, and the latter are both groupings. The meat is in the definitions of the latter two. > What, as well, is the relationship > to the defined term "Group"? Group is a syntactic way of expressing things in JSON. > * 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. Since you made this comment, we have gone through multiple such rounds of reordering. There is no one good order… We now indeed swapped Augmentation Mechanism and Protocol Binding in 9279854 | genart review: swap Augmentation Mechanism and Protocol Binding > * 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. We created another (unnumbered) subsection in 1.1 (now 1.2), Programming Platform Terms in fe4e567 | review: extract Programming Platform Terms This allows to get these terminology conflicts out of the way, at the cost of prolonging the suspense about the actual content of the specification. > * 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. This should be clear from the concept of JSON pointer, which is a must read for this specification. We have added a reference to Section 6 of RFC 6901 at the end of the Section 4.2: eb6e68f | genart review: add ref on how the JSON Pointer becomes a frag id > Nits/editorial comments: > * The capitalisation of terms defined in 1.1. appear inconsistently in the > text. While I can’t claim we are now entirely consistent, we did make a few rounds fixing this. We moved the paragraph explaining our capitalization conventions (recently introduced in PR #164) up to the start of Section 1.1 (now 1.2) and made it more informative: 8cc7d34 | genart review: moved para explaining our capitalization conventions > * 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. This could be done. Now that we have a Programming Platform Terms section, we moved the “byte” up. The rest, slightly streamlined, now forms the content of the unnumbered section “Conventions”: f603d21 | genart review: slightly deflate section "Conventions" > * 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. It can be, but the hint that this is not describing something in the example but something not in the example is quite useful. > ** ... 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. Yes, this was ripe for an editorial round. 6e16d47 | genart review: clean up intro into structure of JSON > * 2.2.2. para 2 -- Parenthetical can be a sentence. Actually, the parenthesis is a short aside; therefore the parenthetical form is appropriate. > * 2.3.3. penultimate para -- "(one or more)" should not be in parenthensis. Correct. 542b05b | genart review: remove unneeded parentheses > * et cetera. > * 4.5. bullet 2: "The affordance/grouping itself..." since affordance and > grouping are two separate terms, suggest "The affordance or grouping > itself..." c44eb63 | genart review: replace / by or > * 4.7. item 1 para 2: Again, unwise to put a SHOULD NOT in a parenthetical. Indeed. debc3d6 | genart review: replace () by , > * Suggest referencing RFC8610 when the use of CDDL is first introduced, > rather than first in the security considerations and then in the appendix. The first reference is now in the new section 1.1 (Structure of This Document). (It is redundantly repeated in Appendix A which is entirely in CDDL.) Thank you again for the many suggestions! Grüße, Carsten -- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
