Linkset: Media Types and a Link Relation Type for Link Sets
draft-ietf-httpapi-linkset-10

# 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”

What happens if I don't follow the SHOULD in Section 4.1?  Are there interoperability risks?

Section 8.1 should be explicit that the name of the registry it's updating is "Link Relation Type Registry".

In Sections 8.2 and 8.3, "Required Parameters" should be "N/A", not "None", per RFC 6838 Section 5.6.

Section 7.4.3 seems to have a broken url rendering in Figure 17. And Appendix A also
has various clickable links and non-clickable links that seem broken, eg compare the
links to example.com with the ones to id.gs1.org

(at least as rendered at https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-linkset-09)

Section 8:

The language in section 8 is inconsistent between the entries (eg one mentiones IANA, the other
doesn't). It is also common to just write it as if it has been registered, eg "this document
adds the following entry to the IANA xxxx registry:".

Thank you to Donald Eastlake for the SECDIR review.

** Section 4.2.  Given that there is normative guidance around [W3C.REC-json-ld-20140116], please make this reference normative.

** Section 7.4. Editorial.  There are a few examples using live, non-example domains (e.g., Figure 14 with “https://dalgiardino.com/risotto-rice-with-mushrooms/” ).  

** Section 9.  Thanks for citing the Security Considerations of [RFC8288].  Please also add the more generic ones of (Section 7 of) RFC3986.

** Section 9.  As an extension of the idea of links having context, should caution be provided about mixed content (link file or headers is sent over HTTPS but contain HTTP links)?

Thank you for the work put into this document. As I added recently "Link:" to some web properties for HTTP/2 "push", I understand the usefulness of this specification. 

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education), and some nits.

Special thanks to Rich Salz for the shepherd's write-up including the section about the WG consensus even if I regret the absence of intended status justification (even if there is a brief history of the intended status). 

I hope that this helps to improve the document,

Regards,

-éric

As other ADs have noted, I am really puzzled by having two ways to format the same information. The Figures 8 & 10 examples try to explain that when delivering a format there could be a link to the other format, but I find this really weird.

Is there a performance impact when using a different document rather than the Link: in the HTTP header. Does it mean that the web server (Apache, nginx) has also to parse the HTML content and not only the Link: to push content over HTTP/2 ?

## Section 4.2.3

Please use https://example.net rather than http://example.net

## Section 7.3

What is the logic of including the linkset in a Link: header while previous justification of this specification was that some applications cannot generate Link: header?

## Section 9

I trust the security ADs for a careful review but the 3rd party links seems an open door for a DoS if a popular site starts to advertise links to a 3rd party large ressource... The 3rd party then becomes then a victim.

# NITS  

## Section 7.4.2
Please align Figure 16 with the text (possibly a xml2rfc bug).

Thanks for addressing my previous DISCUSS points and most of my COMMENTs.

I retain the original COMMENT text below, unchanged, for posterity (even
though many of the remarks have already been addressed by the authors in
the editor's copy).

=========================================================================

Thanks to Donald Eastlake for the secdir review.
It would be good to see a response to his comments (especially as they
relate to artwork line folding).

The ability to (more easily) provide third-party links seems to be the
main security-relevant consideration for this document, which raises
issues of trust that require serious consideration by applications
consuming such linksets.  I have some more thoughts in the
section-by-section comments.

I made a pull request on github with some editorial suggestions:
https://github.com/ietf-wg-httpapi/linkset/pull/64 .
There is perhaps a non-editorial change in the description of the
"hreflang" JSON representation, though I would argue that in essence it
is editorial since it just brings that definition in line with its sibling
elements' definitions.

Section 4.1

   When converting an "application/linkset" document to a field value
   for the HTTP "Link" header, newline characters SHOULD be removed in
   order to comply with Section 5.5 of [I-D.ietf-httpbis-semantics].

Removed, or replaced by SP?

Section 4.2

   The "application/linkset+json" serialization allows for OPTIONAL
   support of a JSON-LD [W3C.REC-json-ld-20140116] serialization.  This
   can be achieved by adding an appropriate context to the "application/
   linkset+json" serialization using the approach described in
   [W3C.REC-json-ld-20140116].  [...]

Perhaps we want a section reference to [W3C.REC-json-ld-20140116] here, or
to mention specifically the 'http://www.w3.org/ns/json-ld#context' link
relation, to be unambiguous about what behavior we are referencing.

Section 4.2.4.1

   *  "hreflang": The optional and repeatable "hreflang" target
      attribute MUST be represented by an array (even if there only is

Does "repeatable" refer to the abstract notion of hreflang attribute (as
might have been specified in RFC 8288 when it says "multiple hreflang
attributes on a single link-value"), or specifically to the encoding of
the attribute in the JSON representation?  I note that RFC 8259 clearly
states that the behavior of software is unpredictable in the face of
non-unique names in a single object (§4 of RFC 8259), and would be very
surprised if we were proposing to have multiple instances of the
"hreflang" member in a given link target object.  So, I mostly assume that
the "repeatable" part is just indicating that the value is an array, so
that multiple different values can be reflected, and not that the JSON
object member with name "hreflang" is repeatable in the JSON object.

   *  "title": The optional and not repeatable "title" target attribute
      MUST be represented by a "title" member in the link target object,
      and its value MUST be a string that follows the same model as in
      the [RFC8288] syntax.

RFC 8288 says that this string is "in the language indicated by the
Content-Language header field (if present)".  Do we inherit those
semantics as applies to the Content-Language header field on the HTTP
message that conveys the link set as its payload?  Can we make any
provision for cases where linkset documents are reused outside the context
of an HTTP interaction?

Section 4.2.4.2

   *  The character encoding information as prescribed by [RFC8187] is
      not preserved; instead, the content of the internationalized
      attribute is represented in the character encoding used for the
      JSON set of links.

I would be very interested to hear why this is believed to be appropriate
and correct behavior; RFC 8187 was only published 5 years ago and it's
fairly surprising for the field to have shifted so dramatically in so
little time.

Section 4.2.5

   The Web linking model ([RFC8288]) provides for the use of extension
   target attributes as discussed in Section 4.2.4.3.  No other form of
   extensions SHOULD be used.  [...]

This usage of the normative keyword is a somewhat awkward construction,
with the intended sense being a negated directive but the keyword being
the positive keyword.  Perhaps it's worth rephrasing to use "NOT
RECOMMENDED"?

                               This limitation of the JSON format allows
   to unambiguously round trip between links provided in the HTTP "Link"
   header field, sets of links serialized according to the "application/
   linkset" format, and sets of links serialized according to the
   "application/linkset+json" format.

I'm not actually convinced that we can unambiguously roundtrip through all
constructions that make use of the RFC 8187 character-encoding-escaping
mechanism with a JSON encoding that forces "native" encoding (of the
containing document) on all internationalized attributes.  In particular,
I think that the reencoding process would in practice have to pick a
particular normalization form, and originals that were encoded in a
different normalization form would not roundtrip faithfully.

Section 5

The ability to claim that multiple profiles are in use concurrently seems
to set us up for a situation where two profiles have conflicting
requirements and are both listed in the "profile" parameter of a given
message.  Should we say anything about how to handle such a situation as a
message recipient?

   The value of the "profile" parameter MUST be a non-empty list of
   space-separated URIs, each of which identifies specific constraints
   or conventions that apply to the link set document.  Profile URIs MAY
   be registered in the IANA Profile URI Registry in the manner
   specified by [RFC7284].

It's a little unusual to see a stasndards-track document use a registry
established by an ISE document, but I guess there's no point duplicating
it if it gets the job done...

Section 6

   A user agent that follows a "linkset" link MUST be aware that the set
   of links provided by the resource that is the target of the link can
   contain links in which the resource that is the context of the link
   does not participate; it MAY decide to ignore those links.

"MUST be aware" is a pretty hard requirement to enforce -- is software
really even "aware"? :)
Perhaps flipping things around a bit, to a declarative statement that the
set of links can include unrelated stuff and the user agent MUST process
both context and target of each link in the link set independently, and
MAY ignore ones deemed irrelevant, would help.  (E.g., "There is no
requirement that the set of links provided by the resource that is the
target of the link contains only links relating to the resource that is
the context of the link.  User agents MUST process each link in the link
set independently, including processing of link context and link target,
and MAY ignore links from the link set in which the context of the link
(to the link set) does not participate.")

Section 7.4.1

   Figure 14 shows the server's response to the request of Figure 13,
   including a "linkset" link with a "profile" attribute that has the
   Profile URI <https://www.gs1.org/voc/?show=linktypes> as its value.
   Dereferencing that URI yields a profile document that lists all the
   link relation types that a client can expect when requesting the link
   set made discoverable by the "linkset" link.  [...]

I am not sure if this is actually a great example to use.
I followed the profile URI to look at what link relation types that the
profile expects to use, and they all start with "gs1:" as rendered on the
page by my browser.  Since link relation types (per RFC 8288) are either
registered types or URIs to indicate extension types, that seems to
indicate that all these "gs1:activityIdeas", "gs1:allergenInfo", etc.,
would need to be URIs, and thus that "gs1:" would be the URI scheme for
them.  But "gs1" does not seem to be listed as a URI scheme at
https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml which
leaves me wondering if the example in this document is in some sense
"incomplete".  Perhaps the intent is that GS1 is actually using "https"
scheme URIs like https://gs1.org/voc/activityIdeas for the relation types
(as the "gs1:activityIdeas" text on the profile page is a hyperlink that
points to that resource), but there's very little to actually give that
indication to me as a reader.

Section 7.4.3

   Note that the response Figure 16 from the link set resource is
   equivalent to the response shown in Figure 17, which leverages the
   "profile" link relation type defined in [RFC6906].

In general there's a disincentive to provide multiple equivalent ways to
do the same thing, as it tends to require endpoints to implement all
alternatives in order to ensure interoperability.  What's the motivation
for offering both a dedicated link relation type and the media type
parameter for the linkset media types, versus just one or the other?

Section 9

I might consider noting that this specification is strict about certain
JSON elements always being encoded as arrays even when there is only a
single item, which simplifies parsers and provides some modest reduction
in risk as relates to implementation bugs.  It's not a terribly important
consideration, though.

   The security considerations of Web Linking [RFC8288] apply, as long
   as they are not specifically discussing the risks of exposing
   information in HTTP header fields.

The paragraph about '''Link header fields that use the "anchor" parameter
to associate a link's context with another resource cannot be trusted
since they are effectively assertions by a third party that could be
incorrect or malicious [...]''' from 8288 seems particularly relevant and
might be worth highlighting specifically.  (I do see the final bullet
point of this section, that is related.)

   and may not be sufficiently protected.  Ideally, none of the URIs
   exposed in links should be supposed to be "hidden"; instead, if these
   URIs are supposed to be limited to certain users, then technical
   measures should be put in place so that accidentally exposing them
   does not cause any harm.

Here we say "if these URIs are supposed to be limited", but do we mean
"the resources identified by these URIs"?

   *  The Web Linking model always has an "implicit context", which is
      the resource of the HTTP interaction.  This original context can
      be lost or can change when self-contained link representations are
      moved.  Changing the context can change the interpretation of
      links when they have no explicit anchor, or when they use relative
      URIs.  [...]

I feel like it would be appropriate to highlight that changing the context
is likely to change the semantics indicated by the link (and thus break
the intended meaning), such that the default/safe behavior needs to be to
ignore such links unless there is a reliable source of link context
external to the document itself.

   *  The model introduced in this specification supports "3rd party
      links", where one party can provide links that have another
      party's resource as an anchor.  Depending on the link semantics
      and the application context, it is important to verify that there
      is sufficient trust in that 3rd party to allow it to provide these
      links.  [...]

In the vein of my earlier comment, I think it would be helpful to supply
some additional background/context on the topic, maybe in this part of the
text, or maybe elsewhere.  I'm thinking something like:

% There is no fundamental notion of "authority" for a third party to
% provide links about resources other than itself.  In the original
% [RFC8288] Web Linking model, links are provided with an implicit
% context that is the resource providing a link (though an explicit
% context can sometimes be provided instead).  In that model, a resource
% is inherently the authority for its own links, and a certain amount of
% trust can be placed in the provided links.  There is no such inherent
% trust when third-party links are used, and so in order for third-party
% links (as specified in this document) to be trustworthy, an external
% source of trust is needed.  This might be achieved in an out-of-band
% manner, with a given client configured to trust a particular entity to
% provide links about a certain class of resources, or by various implicit
% means.  For example, if a resource provides a link of relation type
% "linkset", that might be seen as a delegation of authority for providing
% trustworty link information to the target of the "linkset" link (subject
% to the caveats in Section 7.1 of [RFC3986] about the lack of reliability
% and consistency of a resource identified by a URI), at least for links
% that relate to the original resource, and [RFC8288] proposes that some
% applications might be willing to treat "share the same authority [URI
% component]" as an indication that a link relating a different resource
% might be trustworthy.  The notion of "trust" in a link is a complicated
% subject, and there is no single approach for it that applies universally
% to all applications.

Section 10

Since RFC 6690 is mentioned only to make a contrast to the mechanisms
defined in this document, it seems better classified as an informative
reference.

Section 11

I agree with Roman that [W3C.REC-json-ld-20140116] is more properly
classified as a normative reference.

Appendix A

(I don't know much about JSON-LD or Dublin Core Terms, so my review of
this part was pretty superficial.)

NITS

Section 4.2.2

   *  Each link context object MAY contain an "anchor" member with a
      value that represents the link context.  If present, this value
      MUST be a URI reference and SHOULD NOT be a relative reference as
      per Section 4.1 of [RFC3986].

It's easy to parse this statement as saying that RFC 3986 is providing
support for the "SHOULD NOT" requirement, whereas we're really just using
it as the reference for "relative reference".  Maybe s/per/defined in/, or
just "relative reference (Section 4.1 of [RFC3986])"?
(The phrasing/construct in question appears later on as well, though I'll
just remark on it once, here.)

This document seems to have unresolved IANA issues.

(Francesca noted the DOWNREFs in her comment.)

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

 * Terms "natively" and "native"; alternatives might be "built-in",
   "fundamental", "ingrained", "intrinsic", "original".

Thanks to Christer Holmberg for their General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/CNdklatSYc9n39gTau8BGlECMio).

-------------------------------------------------------------------------------
All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

Section 4.1. , paragraph 4, nit:
>  format specified here is different than the "application/link-format" forma
>                                     ^^^^
Did you mean "different from"? "Different than" is often considered colloquial
style.

Section 5. , paragraph 4, nit:
> y profile information pertaining to a links set. 7.1. Set of Links Provided a
>                                     ^^^^^^^
The plural noun "links" cannot be used with the article "a". Did you mean "a
link" or "links"?

Reference [RFC5988] to RFC5988, which was obsoleted by RFC8288 (this may be on
purpose).

These URLs in the document can probably be converted to HTTPS:
 * http://www.w3.org/ns/json-ld#context
 * http://purl.org/dc/terms/title
 * http://purl.org/dc/terms/format
 * http://purl.org/dc/terms/language

Hi,

Thanks for this document.

The overriding question that I had when reading this document (and the shepherd writeup) is why are we defining two formats rather than one, given that defining a single format would seem to increase interop and standardization by obviously forcing everyone to do it only one way.

I appreciate that the HTTP Link Document format is simpler, and closer to the "Link" header field, although I note that it is not exactly the same - it still has differences.  I also appreciate that the HTTP Link Document format might be slightly easier for humans to read, but how important it that for a link document?

Hence, I would prefer to see the IETF just standardizing a single format, but don't feel strongly enough to raise a discuss for it.  However, I would suggest trying to expand section 3, or adding another section, to provide more guidance as to when one format should be used in preference to the other.

Regards,
Rob