Subject: Re: [httpapi] Linkset feedback

From: Phil Archer <[email-masked]>
Date: Tue, 17 Aug 2021 15:59:59 +0000

Dear all,

As I'm keen to see Linkset become an RFC I've spent some time today turning each of Mark's points here into issue in the GitHub repo. https://github.com/ietf-wg-httpapi/linkset/issues

Where relevant, I've made my own comments and suggestions.

@herbert, @dret - let me know if there's more I can do to help out here.

Phil

Phil Archer
Director, Web Solutions, GS1
https://www.gs1.org

Meet GS1 Digital Link Developers at
https://groups.google.com/forum/#!forum/gs1-digital-link-developers

https://philarcher.org
+44 (0)7887 767755
@philarcher1
Skype: philarcher

On 29 July 2021 04:27, httpapi 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
[email-masked]
https://www.ietf.org/mailman/listinfo/httpapi

CONFIDENTIALITY / DISCLAIMER: The contents of this e-mail are  confidential and are not to be regarded as a contractual offer or acceptance from GS1 (registered in Belgium). 
If you are not the addressee, or if this has been copied or sent to you in error, you must not use data herein for any purpose, you must delete it, and should inform the sender. 
GS1 disclaims liability for accuracy or completeness, and opinions expressed are those of the author alone. 
GS1 may monitor communications. 
Third party rights acknowledged. 
(c) 2020.

---

From: Herbert Van de Sompel <[email-masked]>
Date: Tue, 17 Aug 2021 18:20:58 +0200

Thanks a lot for your input, Phil. Very helpful.

Erik and I agreed to regroup early September, after our respective
vacations. We will get to all Mark's comments and your feedback then and
hopefully will be able to wrap up the Link Set spec soon.

Greetings

Herbert

On Tue, Aug 17, 2021 at 6:00 PM Phil Archer <phil.archer=
[email-masked]> wrote:

> Dear all,
>
> As I'm keen to see Linkset become an RFC I've spent some time today
> turning each of Mark's points here into issue in the GitHub repo.
> https://github.com/ietf-wg-httpapi/linkset/issues
>
> * 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 -- 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.
>
> * 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,
>
> --
> CONFIDENTIALITY / DISCLAIMER: The contents of this e-mail are
> confidential and are not to be regarded as a contractual offer or
> acceptance from GS1 (registered in Belgium).
> If you are not the addressee, or if this has been copied or sent to you in
> error, you must not use data herein for any purpose, you must delete it,
> and should inform the sender.

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