Re: [httpapi] Linkset feedback

Mark, all,

Erik and I went through the issues Mark raised and have added proposals for
resolution at https://github.com/ietf-wg-httpapi/linkset/issues.

Thanks again to Phil for adding Mark's issues to the GitHub repo and for
adding feedback!

Greetings

Herbert

On Wed, Jul 28, 2021 at 9:27 PM Mark Nottingham <mnot@mnot.net> wrote:

> I went through the link set draft; apologies for the delay. Feedback
> below; most of it is editorial.
>
>
> * Abstract- - '...sets of links as stand-alone resources.' This doesn't
> agree with the HTTP definition of 'resource'; recommend dropping this
> phrase.
>
> * 1. Introduction (and elsewhere) -- it would be nice if this clearly said
> it was defining a _serialiation_ of links, to leverage the terminology
> established in 8288.
>
> * 1. Introduction -- it might be good to mention the nature of the two
> seralisations defined; the reader doesn't find that out until section 3
> right now, where it's discussed obliquely.
>
> * 3. Scenarios -- usually sections like this are called something like
> "Use Cases"
>
> * 3. Scenarios -- it feels like this section could be tightened up; it's
> fairly long for the amount of content here
>
> * 4. Document Formats for Sets of Links -- 'In both serializations for
> link sets defined here, inverse links SHOULD be represented as direct links
> using the "rel" construct and by switching the position of the resources
> involved in the link.' -- is this always true? I.e., for every link
> relation, is it the case that the inverse relation's semantics in total are
> expressed by merely reversing the subject and object? Also, this doesn't
> feel like a SHOULD (which is for interoperability).
>
> * 4.1. HTTP Link Document Format: application/linkset -- it would be good
> if this said something explicitly about whether newlines are allowed, and
> gave an example.
>
> * 4.2.1 Set of Links -- '... the "link context object" (see Section 4.2.2)
> - MUST be used to represent links' -- this is an awkward MUST; usually this
> is just stated ('is'). (this applies to several other requirements below;
> generally, requirements are used to specify what behaviours are necessary
> for interoperability, not to merely define protocol elements).
>
> * 4.2.1 Set of Links -- '... MUST have "linkset" as its sole member' --
> does this imply that if there is any other member present, a receiving
> implementation is required to error?
>
> * 4.2.2 Link Context Object -- 'SHOULD NOT be a relative reference' --
> what are the consequences of violating this SHOULD NOT?
>
> * 4.2.4.1. Target Attributes Defined by Web Linking -- this refers to
> 3.4.1 of 8288, which defines a *different* serialisation of web links - the
> Link HTTP header field. It should refer to section 2 of 8288, which defines
> the abstract model of web linking, since this is a new serialisation. As
> such, this section isn't really necessary; all target attributes are just
> target attributes in the abstract model.
>
> * 4.2.4.2. Internationalised Target Attributes -- as per above, this
> section is not necessary. Internationalisation of those values is a
> specific feature to enable non-ascii titles in the Link header
> serialisation; it's not necessary in a JSON serialisation.
>
> * 4.2.4.3. Extension Target Attributes -- this section should be folded
> into 4.2.4.
>
> * 5. The "profile" attribute for media types to Represent Sets of Links --
> It'd be really helpful to have an example here. Also, they're media type
> _parameters_, not attributes.
>
> * Appendix A - Has the 'http://www.iana.org/assignments/relation/' URI
> been discussed? I note that it isn't HTTPS, and it currently redirects to
> another URI. Did you consider a 'urn:ietf:params' URI?
>
> Cheers,
>
> --
> Mark Nottingham   https://www.mnot.net/
>
> --
> httpapi mailing list
> httpapi@ietf.org
> https://www.ietf.org/mailman/listinfo/httpapi
>

-- 
==================
Herbert Van de Sompel
https://hvdsomp.info
https://orcid.org/0000-0002-0715-6126