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

[Ballot comment]
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:".

[Ballot 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”

[Ballot comment]
Bringing this back after the second IETF Last Call to cover the 2 downref that were missed with the first LC. All COMMENTs from IESG evaluation have been addressed by the authors in v-09.

[Ballot comment]
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  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.)

The following Last Call announcement was sent out (ends 2022-03-28):

From: The IESG
To: IETF-Announce
CC: draft-ietf-httpapi-linkset@ietf.org, francesca.palombini@ericsson.com, httpapi-chairs@ietf.org, httpapi@ietf.org, rsalz@akamai.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Linkset: Media Types and a Link Relation Type for Link Sets) to Proposed Standard


The IESG has received a request from the Building Blocks for HTTP APIs WG
(httpapi) to consider the following document: - 'Linkset: Media Types and a
Link Relation Type for Link Sets'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2022-03-28. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This specification defines two formats and respective media types for
  representing sets of links as stand-alone documents.  One format is
  JSON-based, the other aligned with the format for representing links
  in the HTTP "Link" header field.  This specification also introduces
  a link relation type to support discovery of sets of links.

Note to Readers

  Please discuss this draft on the "Building Blocks for HTTP APIs"
  mailing list (https://www.ietf.org/mailman/listinfo/httpapi).

  Online access to all versions and files is available on GitHub
  (https://github.com/ietf-wg-httpapi/linkset).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset/



No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc6906: The 'profile' Link Relation Type (Informational - Independent Submission)
    rfc7284: The Profile URI Registry (Informational - Independent Submission)

Third Last Call was requested after discussion within the IESG - as the two downrefs which were missed in the previous LC are to Independent stream documents (hence with no IETF consensus), the IESG believes it is better to repeat the Last Call including these downrefs.

[Ballot comment]
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.

[Ballot discuss]
Since the downrefs that were omitted from the IETF Last Call announcement
are to documents published on the ISE stream, I would like to ensure that
the IESG specifically discusses that fact, as we determine whether or not
an additional IETF LC (corrected to indicate the downrefs) is needed.
If we knew that the referenced mechanisms already had IETF consensus, I
would be much less concerned about having the IESG approve the downrefs
without further community consultation.

I'd also like to have the authors double-check the Content-Length in the
HTTP response in Figure 10 (Section 7.2); my (admittedly hacky)
methodology produces a length of 1246 in contrast to the listed length of
1349.

[Ballot comment]
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  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.)

[Ballot comment]
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)?

[Ballot comment]
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).

> (1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

This document is Proposed Standard and is reflected on the title page.

>(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

>Technical Summary:
>Document Quality:
>Personnel:

This specification defines two formats and respective media types for
representing sets of links as stand-alone documents.  One format is
JSON-based, the other aligned with the format for representing links
in the HTTP "Link" header field.  This specification also introduces
a link relation type to support discovery of sets of links. This is intended
to be used when RFC 8288 links are not usable, and delivering a set of links
as a stand-alone document is preferable.

This is a product of the HTTPAPI working group.

The document had detailed review from many WG members and while there
was some discussion, there was nothing especially controversial, nor rough
points in any consensus issues.

There are several implementations existing and planned. These are noted in
Appendix B of the draft, which will be removed before publication as an RFC.

This was originally set to be Informational, but following a question
from one of the Directorate reviews, and confirmation on the mailing
list, this document was changed to Proposed Standard.

The shepherd for this document was Rich Salz; the responsible AD is Francesca
Palombini.

>(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

There are two old RFC references which can be fixed during AUTH48 or earlier:
6982 -> 7942 and 5988 -> 8288.

The JSON samples have data after the opening brace, but that's also can be
fixed in AUTH48 :)

I re-read the document carefully and it is ready for publication. It does a
nice job providing use cases and motivation for this work.

>(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.  In particular Julian Reschke (noted HTTP RFC editor) provided a detailed
review.

>(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

It might be useful to have the HTTP WG look at this. Given the overlap of
the groups's memberships, and the reviews it is already had, I am pretty
confident that no new issues will be raised.

>(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

Absolutely none.

>(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes, both authors said they are not aware of any IPR.

>(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

>(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Low-level general agreement. All agree this is a worthwhile problem to
address. Nobody objected to any decisions made while writing the document.

>(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

>(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

See #3 above.

>(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The IANA considerations section (8) identifies one link relation and two media
types. Those applications, in the draft, appear to be complete.

>(13) Have all references within this document been identified as either normative or informative?

Yes.

>(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are none.

>(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.  UPDATED MARCH 1:

When the document was changed from Informational to Proposed Standard, and resubmitted, two downward references were created and not caught by the tooling:
  ** Downref: Normative reference to an Informational RFC: RFC 6906
  [RFC6906]  Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
              DOI 10.17487/RFC6906, March 2013,
              .
  ** Downref: Normative reference to an Informational RFC: RFC 7284
  [RFC7284]  Lanthaler, M., "The Profile URI Registry", RFC 7284,
              DOI 10.17487/RFC7284, June 2014,
              .


>(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

I would suggest that this gets an "Updates 8288" mention.

>(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

The draft proposes three additions to existing registries and the additions
look complete. Once the responsible AD is satisfied with the draft, we could
ask the registrars to review them.

>(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new registries.

>(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

doc-nits but the rest is text. I tried to carefully read the JSON examples.

>(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

The draft has no YANG in it.

[Ballot comment]
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

[Ballot comment]
Lars rightfully noted that two Downref (not in the downref registry) escaped the IETF Last Call automatically generated text:

  ** Downref: Normative reference to an Informational RFC: RFC 6906
  [RFC6906]  Wilde, E., "The 'profile' Link Relation Type", RFC 6906,
              DOI 10.17487/RFC6906, March 2013,
              .

  ** Downref: Normative reference to an Informational RFC: RFC 7284
  [RFC7284]  Lanthaler, M., "The Profile URI Registry", RFC 7284,
              DOI 10.17487/RFC7284, June 2014,
              .

In conformance with https://www.ietf.org/rfc/rfc8067.html, I believe there is no need for starting another LC for the document including these references, and I ask the rest of the IESG to pay particular attention to the appropriateness of these two downward references, as part of their IESG evaluation.

[Ballot comment]
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

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-httpapi-linkset-08. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are three actions which we must complete.

First, in the Link Relation Types registry on the Link Relations registry page located at:

https://www.iana.org/assignments/link-relations/

a new registration is to be made as follows:

Relation name: linkset
Description: The link target of a link with the "linkset" relation type provides a set of links, including links in which the link context of the link participates.
Reference: [ RFC-to-be ]

As this document requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

Second, in the application namespace of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new registration is to be made as follows:

Name: application/linkset
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Third, also in the application namespace of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new registration is to be made as follows:

Name: application/linkset+json
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Lead IANA Services Specialist

The following Last Call announcement was sent out (ends 2022-02-22):

From: The IESG
To: IETF-Announce
CC: draft-ietf-httpapi-linkset@ietf.org, francesca.palombini@ericsson.com, httpapi-chairs@ietf.org, httpapi@ietf.org, rsalz@akamai.com
Reply-To: last-call@ietf.org
Sender:
Subject: Second Last Call:  (Linkset: Media Types and a Link Relation Type for Link Sets) to Proposed Standard


The IESG has received a request from the Building Blocks for HTTP APIs WG
(httpapi) to consider the following document: - 'Linkset: Media Types and a
Link Relation Type for Link Sets'
  as Proposed Standard

This second Last Call is specifically on the intended RFC status change, which
was set to Informational in the previous Last Call and changed to Proposed
Standard following feedback from the community.

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2022-02-22. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This specification defines two formats and respective media types for
  representing sets of links as stand-alone documents.  One format is
  JSON-based, the other aligned with the format for representing links
  in the HTTP "Link" header field.  This specification also introduces
  a link relation type to support discovery of sets of links.

Note to Readers

  Please discuss this draft on the "Building Blocks for HTTP APIs"
  mailing list (https://www.ietf.org/mailman/listinfo/httpapi).

  Online access to all versions and files is available on GitHub
  (https://github.com/ietf-wg-httpapi/linkset).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset/



No IPR declarations have been submitted directly on this I-D.

> (1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

This document is Proposed Standard and is reflected on the title page.

>(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

>Technical Summary:
>Document Quality:
>Personnel:

This specification defines two formats and respective media types for
representing sets of links as stand-alone documents.  One format is
JSON-based, the other aligned with the format for representing links
in the HTTP "Link" header field.  This specification also introduces
a link relation type to support discovery of sets of links. This is intended
to be used when RFC 8288 links are not usable, and delivering a set of links
as a stand-alone document is preferable.

This is a product of the HTTPAPI working group.

The document had detailed review from many WG members and while there
was some discussion, there was nothing especially controversial, nor rough
points in any consensus issues.

There are several implementations existing and planned. These are noted in
Appendix B of the draft, which will be removed before publication as an RFC.

This was originally set to be Informational, but following a question
from one of the Directorate reviews, and confirmation on the mailing
list, this document was changed to Proposed Standard.

The shepherd for this document was Rich Salz; the responsible AD is Francesca
Palombini.

>(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

There are two old RFC references which can be fixed during AUTH48 or earlier:
6982 -> 7942 and 5988 -> 8288.

The JSON samples have data after the opening brace, but that's also can be
fixed in AUTH48 :)

I re-read the document carefully and it is ready for publication. It does a
nice job providing use cases and motivation for this work.

>(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.  In particular Julian Reschke (noted HTTP RFC editor) provided a detailed
review.

>(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

It might be useful to have the HTTP WG look at this. Given the overlap of
the groups's memberships, and the reviews it is already had, I am pretty
confident that no new issues will be raised.

>(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

Absolutely none.

>(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes, both authors said they are not aware of any IPR.

>(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

>(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Low-level general agreement. All agree this is a worthwhile problem to
address. Nobody objected to any decisions made while writing the document.

>(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

>(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

See #3 above.

>(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The IANA considerations section (8) identifies one link relation and two media
types. Those applications, in the draft, appear to be complete.

>(13) Have all references within this document been identified as either normative or informative?

Yes.

>(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are none.

>(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

>(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

I would suggest that this gets an "Updates 8288" mention.

>(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

The draft proposes three additions to existing registries and the additions
look complete. Once the responsible AD is satisfied with the draft, we could
ask the registrars to review them.

>(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new registries.

>(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

doc-nits but the rest is text. I tried to carefully read the JSON examples.

>(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

The draft has no YANG in it.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-httpapi-linkset-06. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that, upon approval of this document, there are three actions which we must complete.

First, in the Link Relation Types registry on the Link Relations registry page located at:

https://www.iana.org/assignments/link-relations/

a new registration is to be made as follows:

Relation name: linkset
Description: The link target of a link with the "linkset" relation type provides a set of links, including links in which the link context of the link participates.
Reference: [ RFC-to-be ]
Notes:

As this document requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. This review must be completed before the document's IANA state can be changed to "IANA OK."

Second, in the application namespace of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new registration is to be made as follows:

Name: application/linkset
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

Third, also in the application namespace of the Media Types registry located at:

https://www.iana.org/assignments/media-types/

a new registration is to be made as follows:

Name: application/linkset+json
Template: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Lead IANA Services Specialist

The following Last Call announcement was sent out (ends 2022-01-19):

From: The IESG
To: IETF-Announce
CC: draft-ietf-httpapi-linkset@ietf.org, francesca.palombini@ericsson.com, httpapi-chairs@ietf.org, httpapi@ietf.org, rsalz@akamai.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (Linkset: Media Types and a Link Relation Type for Link Sets) to Informational RFC


The IESG has received a request from the Building Blocks for HTTP APIs WG
(httpapi) to consider the following document: - 'Linkset: Media Types and a
Link Relation Type for Link Sets'
  as Informational RFC

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2022-01-19. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This specification defines two formats and respective media types for
  representing sets of links as stand-alone documents.  One format is
  JSON-based, the other aligned with the format for representing links
  in the HTTP "Link" header field.  This specification also introduces
  a link relation type to support discovery of sets of links.

Note to Readers

  Please discuss this draft on the "Building Blocks for HTTP APIs"
  mailing list (https://www.ietf.org/mailman/listinfo/httpapi).

  Online access to all versions and files is available on GitHub
  (https://github.com/ietf-wg-httpapi/linkset).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpapi-linkset/



No IPR declarations have been submitted directly on this I-D.

> (1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

This document is a Informational and is reflected on the title page.

>(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

>Technical Summary:
>Document Quality:
>Personnel:

This specification defines two formats and respective media types for
representing sets of links as stand-alone documents.  One format is
JSON-based, the other aligned with the format for representing links
in the HTTP "Link" header field.  This specification also introduces
a link relation type to support discovery of sets of links. This is intended
to be used when RFC 8288 links are not usable, and delivering a set of links
as a stand-alone document is preferable.

This is a product of the HTTPAPI working group.

The document had detailed review from many WG members and while there
was some discussion, there was nothing especially controversial, nor rough
points in any consensus issues.

There are several implementations existing and planned. These are noted in
Appendix B of the draft, which will be removed before publication as an RFC.

The shepherd for this document was Rich Salz; the responsible AD is Francesca
Palombini.

>(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

There are two old RFC references which can be fixed during AUTH48 or earlier:
6982 -> 7942 and 5988 -> 8288.

The JSON samples have data after the opening brace, but that's also can be
fixed in AUTH48 :)

I re-read the document carefully and it is ready for publication. It does a
nice job providing use cases and motivation for this work.

>(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.  In particular Julian Reschke (noted HTTP RFC editor) provided a detailed
review.

>(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

It might be useful to have the HTTP WG look at this. Given the overlap of
the groups's memberships, and the reviews it is already had, I am pretty
confident that no new issues will be raised.

>(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

Absolutely none.

>(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes, both authors said they are not aware of any IPR.

>(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

>(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Low-level general agreement. All agree this is a worthwhile problem to
address. Nobody objected to any decisions made while writing the document.

>(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

>(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

See #3 above.

>(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The IANA considerations section (8) identifies one link relation and two media
types. Those applications, in the draft, appear to be complete.

>(13) Have all references within this document been identified as either normative or informative?

Yes.

>(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are none.

>(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

>(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

I would suggest that this gets an "Updates 8288" mention.

>(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

The draft proposes three additions to existing registries and the additions
look complete. Once the responsible AD is satisfied with the draft, we could
ask the registrars to review them.

>(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new registries.

>(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

doc-nits but the rest is text. I tried to carefully read the JSON examples.

>(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

The draft has no YANG in it.

> (1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

This document is a Informational and is reflected on the title page.

>(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

>Technical Summary:
>Document Quality:
>Personnel:

This specification defines two formats and respective media types for
representing sets of links as stand-alone documents.  One format is
JSON-based, the other aligned with the format for representing links
in the HTTP "Link" header field.  This specification also introduces
a link relation type to support discovery of sets of links. This is intended
to be used when RFC 8288 links are not usable, and delivering a set of links
as a stand-alone document is preferable.

This is a product of the HTTPAPI working group.

The document had detailed review from many WG members and while there
was some discussion, there was nothing especially controversial, nor rough
points in any consensus issues.

There are several implementations existing and planned. These are noted in
Appendix B of the draft, which will be removed before publication as an RFC.

The shepherd for this document was Rich Salz; the responsible AD is Francesca
Palombini.

>(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

There are two old RFC references which can be fixed during AUTH48 or earlier:
6982 -> 7942 and 5988 -> 8288.

The JSON samples have data after the opening brace, but that's also can be
fixed in AUTH48 :)

I re-read the document carefully and it is ready for publication. It does a
nice job providing use cases and motivation for this work.

>(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

No.  In particular Julian Reschke (noted HTTP RFC editor) provided a detailed
review.

>(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

It might be useful to have the HTTP WG look at this. Given the overlap of
the groups's memberships, and the reviews it is already had, I am pretty
confident that no new issues will be raised.

>(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

Absolutely none.

>(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes, both authors said they are not aware of any IPR.

>(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No.

>(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

Low-level general agreement. All agree this is a worthwhile problem to
address. Nobody objected to any decisions made while writing the document.

>(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No.

>(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

See #3 above.

>(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

The IANA considerations section (8) identifies one link relation and two media
types. Those applications, in the draft, appear to be complete.

>(13) Have all references within this document been identified as either normative or informative?

Yes.

>(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

There are none.

>(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

No.

>(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

I would suggest that this gets an "Updates 8288" mention.

>(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 8126).

The draft proposes three additions to existing registries and the additions
look complete. Once the responsible AD is satisfied with the draft, we could
ask the registrars to review them.

>(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new registries.

>(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, YANG modules, etc.

doc-nits but the rest is text. I tried to carefully read the JSON examples.

>(20) If the document contains a YANG module, has the module been checked with any of the recommended validation tools (https://trac.ietf.org/trac/ops/wiki/yang-review-tools) for syntax and formatting validation? If there are any resulting errors or warnings, what is the justification for not fixing them at this time? Does the YANG module comply with the Network Management Datastore Architecture (NMDA) as specified in RFC8342?

The draft has no YANG in it.