[httpapi] John Scudder's No Objection on draft-ietf-httpapi-linkset-09: (with COMMENT)

[John Scudder via Datatracker <[e-mail]>]

John Scudder has entered the following ballot position for
draft-ietf-httpapi-linkset-09: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)


Please refer to https://www.ietf.org/about/groups/iesg/statements/handling-ballot-positions/ 
for more information about how to handle DISCUSS and COMMENT positions.


The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset/



----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

# COMMENTS

Thank you for including the “implementation status” section, it provided
helpful context for me. It’s a little regrettable from that point of view that
the section will be removed; in slightly different form it might make a nice
addition to the “use cases” section, making the abstract use cases more
concrete. (I’m not strongly advocating that you make this change, just
mentioning the thought.)

## Section 2

   This specification uses the terms "link context" and "link target" as
   defined in [RFC8288].

Since I’m not a subject area expert, I went to RFC 8288 to find these
definitions. There are none worthy of the name, and this made me sad.  It seems
that “link context” must be a term of art so familiar to those in the know that
they don’t even perceive that it needs definition. This isn’t a flaw in the
present document, but in RFC 8288; still, I’d prefer that the present document
not make the claim that RFC 8288 provides a definition, when it doesn’t. The
statement in §4 that 8288 has an abstract model for a link, seems more accurate.

You could rewrite as “This specification uses the terms “link context” and
“link target” in the same manner RFC 8288 does” and that would work for me.

## Section 4:

      The format defined in Section 4.1 is near identical to the field

Should be “near-identical” or (preferably) “nearly identical”. (Same comment
applies to the first sentence of §4.1.)

      value of the HTTP "Link" header field as specified in Web Linking
      Section 3 of [RFC8288].

While RFC 8288 is indeed titled “Web Linking” this expansion of the title,
juxtaposed with the section number, makes the sentence scan in a misleading
way. I suggest just removing the title of the RFC (so: “… as specified in
Section 3 of [RFC8288]”) or alternately, qualifying the title and adding
parentheses (so: “… as specified in the Web Linking RFC (Section 3 of
[RFC8288])”). My own preference is for the first option.

   As a result, implementers of link sets should strive to make them
   self-contained by following the recommendations provided below.

This is pretty nitty, but I suggest “… strive to make them self-contained by
adhering to the following recommendations.” The point of the rewrite being that
“below” indicates the recommendations could be anywhere in the remainder of the
spec, whereas following means “I’m about to tell you what they are”. The change
to “adhering” is just to avoid the awkwardness of “following… following”.

# NITS

## Section 4.2.4.2:

   *  An internationalized target attribute is represented as a member
      of the link context object with the same name (including the *) of
      the attribute.

Should be “as the attribute” not “of the attribute”.

## Section 4.2.4.3:

   *  An extension target attribute is represented as a member of the
      link target object with the same name of the attribute, including
      the * if applicable.

Same as above, should be “as the attribute” not “of the attribute”.

## Appendix A:

   Figure 19 shows the response of an HTTP GET against the URI of a link

“response to”