Thanks for the feedback, Julian. I've incorporated into source; responses below where necessary.
> On 12 May 2017, at 4:16 am, Julian Reschke <julian.reschke@xxxxxx> wrote:
>
> Here's my feedback, mainly editorial nits...:
>
> Additionally, the following rules are included from [RFC3986]: URI
> and URI-Reference; from [RFC6838]: type-name and subtype-name; from
> [W3C.CR-css3-mediaqueries-20090915]: media_query_list; and from
> [RFC5646]: Language-Tag.
>
> That doesn't work, as "_" is not a legal ABNF character.
>
> 2. Links
>
> In this specification, a link is a typed connection between two
> resources, and is comprised of:
>
> o A _link context_,
>
> o a _link relation type_ (Section 2.1),
>
> o a _link target_, and
>
> o optionally, _target attributes_ (Section 2.2).
>
> It might be good to add forward references for "link context" and "link target" as well.
Context and target are explained directly below the list; they don't have their own sections in the generic model.
> Finally, links are consumed by _link applications_. Generally, an
> application will define the link relation type(s) it uses, along with
> the serialisation(s) that they might occur within. For example, the
> application "Web browsing" looks for the "stylesheet" link relation
> type in the HTML link serialisation, whereas the application
> "AtomPub" uses the "edit" and "edit-media" link relations.
>
> Actually, one popular browser also looks for the stylesheet link relation in the "Link" header field...
True, but that's not specified behaviour, AIUI.
> Relation types are not to be confused with media types [RFC6838];
>
> Media types are defined in RFC 2046; RFC 6838 is mainly about media type registrations.
>
> they do not identify the format of the representation that results
> when the link is dereferenced. Rather, they only describe how the
> current context is related to another resource.
>
> o *Reference*: Reference to the document that specifies the link
> relation type, preferably including a URI that can be used to
> retrieve a copy of the document. An indication of the relevant
> section(s) MAY also be included, but is not required.
>
> s/MAY/can/
>
> Note that relation types can be registered by third parties
> (including the Expert(s)), if the Expert(s) determine that an
> unregistered relation type is widely deployed and not likely to be
> registered in a timely manner.
>
> maybe s/registered/registed otherwise/?
I did "...not likely to be registered in a timely manner otherwise."
> 2.1.1.2. Registration Request Processing
>
> Relation types are registered on the advice of a Designated Expert
> (appointed by the IESG or their delegate), with a Specification
> Required (using terminology from [RFC5226]).
>
> s/[RFC5226]/Section 4.1 of [RFC5226]/
>
>
> 2.2. Target Attributes
>
> This specification does not attempt to coordinate the name of target
> attributes, their cardinality or use. Serialisations SHOULD
> coordinate their target attributes to avoid conflicts in semantics or
> syntax.
>
> I'm not sure who's the audience for this SHOULD, and how to implement it. For instance, shouldn't this spec do this for the header field serialization?
The audience is people creating or maintaining serialisations; I've clarified the language.
The header field serialisation has, effectively; it was designed to be compatible with existing serialisations (HTML first, with Atom succeeding it, since Link pre-dated it, even though it wasn't specified).
> 3. Link Serialisation in HTTP Headers
>
> s/Headers/Header fields/
>
> This specification defines the link-params "rel", "anchor", "rev",
> "hreflang", "media", "title", "title*", and "type"; see Section 3.2,
> Section 3.3 and Section 3.4.
>
> s/Section 3.2, Section 3.3 and Section 3.4/Sections 3.2, 3.3, and 3.4/
That's hard to automate; I think we can fix that at the RFC editor stage.
> 3.1. Link Target
>
> Each link-value conveys one target IRI as a URI-Reference (after
> conversion to one, if necessary; see [RFC3987], Section 3.1) inside
> angle brackets ("<>"). If the URI-Reference is relative, parsers
> MUST resolve it as per [RFC3986], Section 5. Note that any base IRI
> from the message's content is not applied.
>
> Maybe s/base IRI from the message's content/base IRI appearing inside the message's content/
>
> 3.2. Link Context
>
> By default, the context of a link conveyed in the Link header field
> is identity of the representation it is associated with, as defined
> in [RFC7231], Section 3.1.4.1, serialised as a URI.
>
> Broken sentence: "is identity".
>
> The ABNF for the "anchor" parameter's value is:
>
> URI-Reference
>
> s/URI-Reference/URI-Reference; Section 4.1 of [RFC3986]/
>
> Note that depending on HTTP status code and response headers, the
> link context might be "anonymous" (i.e., no link context is
> available). For example, this is the case on a 404 response to a GET
> request.
>
> I understand this is identical in RFC 5988, but where does this actually come from? It basically restricts use of anchor-less link header fields 2xx responses, right?
<http://httpwg.org/specs/rfc7231.html#identifying.payload>, referenced just a few paragraphs earlier.
> 3.3. Relation Type
>
> The ABNF for the "rel" and "rev" parameters' values is:
>
> relation-type *( 1*SP relation-type )
>
> where:
>
> relation-type = reg-rel-type | ext-rel-type
>
> Finally I can use this link https://www.youtube.com/watch?v=LbK-g8tKnoc in LC feedback!
Source:
https://github.com/mnot/I-D/issues/33#issuecomment-260825416
Do you have any further suggestions?
> reg-rel-type = LOALPHA *( LOALPHA | DIGIT | "." | "-" )
> ext-rel-type = URI
>
> s/URI/URI; Section 3 of [RFC3986]/
>
> Note that extension relation types are REQUIRED to be absolute URIs
> in Link headers, and MUST be quoted if they contain a semicolon (";")
>
> s/headers/header fields/
>
> or comma (",") (as these characters are used as delimiters in the
> header field itself).
>
> There are more characters legal in URIs but illegal in token -- so maybe phrasing it like this can cause confusion. Maybe "MUST be quoted when they contain characters not allowed in tokens, such as ...."?
>
> 3.4.1. Serialisation-Defined Attributes
>
> The ABNF for the "type" parameter's value is:
>
> type-name "/" subtype-name
>
> (maybe point to https://tools.ietf.org/html/rfc6838#section-4.2 here)
>
> 3.5. Link Header Field Examples
>
> Maybe add an example for multiple Link header field instances in a single message?
>
> 4.1. Link HTTP Header Field Registration
>
> Header field: Link
> Applicable protocol: http
> Status: standard
> Author/change controller:
> IETF (iesg@xxxxxxxx)
> Internet Engineering Task Force
> Specification document(s):
> [RFC&rfc.number;]
>
> s/[RFC&rfc.number;]/this document/
>
>
> 4.2. Link Relation Type Registry
>
> Each published document will be at a URL mutually agreed to by IANA
> and the Expert(s), and IANA will set HTTP response headers on them as
> (reasonably) requested by the Expert(s).
>
> Wow. Does IANA know that we want to configure their web server?
We're talking about it. Data, metadata -- what's the difference?
> 5. Security Considerations
>
> Link applications ought to consider the attack vectors opened by
> automatically following, trusting, or otherwise using links gathered
> from HTTP headers. In particular, Link header fields that use the
>
> s/headers/header fields/
>
> "anchor" parameter to associate a link's context with another
> resource are to be treated with due caution.
>
> The Link header field makes extensive use of IRIs and URIs. See
> [RFC3987] for security considerations relating to IRIs. See
> [RFC3986] for security considerations relating to URIs. See
> [RFC7230] for security considerations relating to HTTP headers.
>
> s/headers/header fields/
>
> 7.1. Normative References
>
> [W3C.CR-css3-mediaqueries-20090915]
> Lie, H., Celik, T., Glazman, D., and A. Kesteren, "Media
> Queries", World Wide Web Consortium CR CR-css3-
> mediaqueries-20090915, September 2009,
> <http://www.w3.org/TR/2009/CR-css3-mediaqueries-20090915>.
>
> Need to update to <https://www.w3.org/TR/2012/REC-css3-mediaqueries-20120619/>.
>
> [W3C.REC-html5-20141028]
> Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
> Navara, E., O'Connor, T., and S. Pfeiffer, "HTML5",
> World Wide Web Consortium Recommendation REC-
> html5-20141028, October 2014,
> <http://www.w3.org/TR/2014/REC-html5-20141028>.
>
> Broken escape in author name.
Hmm.
> A.1. Link Serialisation in HTML
>
> HTML5 ([W3C.REC-html5-20141028]) Section 4.8 defines modern HTML
>
> "Section 4.8 of HTML5"
>
> links. That document links to the Microformats Wiki as a registry;
> over time, the IANA registry ought to mirror its contents, and
> ideally eventually replace it (although that depends on the HTML
> community).
>
>
> Appendix B. Algorithm for Parsing Link Headers
>
> Given a HTTP header field-value "field_value" as a string assuming
> ASCII encoding, the following algorithm can be used to parse it into
> the model described by this specification:
>
> This part is a bit scary -- I don't know how to review it. It might be better to have code in an actual programming language, and a set of tests for it.
That's not current practice for the intended audience, and shipping code makes it more likely that it will be used as a "reference implementation." This is marked as explicitly non-normative, and the precedence is clear.
It has been reviewed (and improved) by others, FWIW. If we find problems, we do have errata.
> 1. Let "links" be an empty list.
>
> 2. Create "link_strings" by splitting "field_value" on ","
> characters, excepting "," characters within quoted strings as per
>
> I have my doubts that people will be able to translate it into actually correct code. To detect whether something is inside a quoted-string essentially requires running a parser; the prose here suggests that this is not necessary.
I reluctantly agree. I'll need to rework the algorithm to address this; please stand by.
> It also should mention that there might be multiple instances of field_value.
The algorithm is for parsing a single field-value...
--
Mark Nottingham https://www.mnot.net/