Subject: Re: [httpapi] Linkset feedback

From: Herbert Van de Sompel <[email-masked]>
Date: Wed, 6 Oct 2021 08:42:09 -0600

On Wed, Jul 28, 2021 at 9:27 PM Mark Nottingham <[email-masked]> wrote:

> I went through the link set draft; apologies for the delay. Feedback
> below; most of it is editorial.
>
>
Mark, we dealt with your feedback and published a new version of the I-D at
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html . Below,
I provide pointers to sections affected by handling it.

One - IMO - significant issue remains to be addressed, not by the Link Set
specification, but in general, i.e. it not being possible to express
IANA-registered link relation types as HTTP URIs. Several people, including
myself, expressed their frustration with that regard in the context of the
discussion https://github.com/ietf-wg-httpapi/linkset/issues/45. Some
digging around revealed that this issue was also discussed in
https://github.com/mnot/I-D/issues/140; both you and my Link Set co-author
Erik were involved in that discussion. I was wondering whether this might
be something that could be picked up by the HTTPAPI working group. After
all, the capability to express IANA-registered link relation types would
generally increase interoperability between semantic and non-semantic
applications.

Greetings

Herbert

>
> * Abstract- - '...sets of links as stand-alone resources.' This doesn't
> agree with the HTTP definition of 'resource'; recommend dropping this
> phrase.
>
>
Addressed by using "documents" instead of "resources".

* 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.
>
>
See
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-introduction

> * 3. Scenarios -- usually sections like this are called something like
> "Use Cases"
>
>
Section renamed "Uses Cases and Motivation", see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-use-cases-and-motivation

> * 3. Scenarios -- it feels like this section could be tightened up; it's
> fairly long for the amount of content here
>
>
We have not changed the content of the section because of lack of
inspiration.

> * 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).
>

Changed "SHOULD" to "may", see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-document-formats-for-sets-o

>
> * 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.
>
>
Wording added to allow newlines, see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-http-link-document-format-a

> * 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).
>
>
This "MUST be" and some similar ones were replaced by "is", see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-set-of-links

> * 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?
>
>
Discussed in https://github.com/ietf-wg-httpapi/linkset/issues/41:

* In order for a document to have the application/linkset+json media type,
it indeed must only have "linkset" as its sole member. A JSON document can
have a "linkset" member (as defined in the spec) as well as other members,
but then it's not an application/linkset+json document.

* As a result of the discussion changed the JSON Extensibility section to
allow but not encourage "foreign" members of the "linkset" member, see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-extensibility

> * 4.2.2 Link Context Object -- 'SHOULD NOT be a relative reference' --
> what are the consequences of violating this SHOULD NOT?
>
>
Motivation for not using relative references is explicit in:

* 4th paragraph of
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-http-link-document-format-a

* 3rd paragraph of
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-document-format-applic

> * 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.
>

Changed reference, see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-link-target-attributes

> * 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.
>
>
We did not change/remove these sections because they are considered
valuable for implementers, see
https://github.com/ietf-wg-httpapi/linkset/issues/43

> * 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.
>
>
* Changed "attribute" to "parameter", see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-the-profile-paramter-for-me

* Introduced "profile" attribute for "linkset" links, see last paragraph of
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-the-linkset-relation-type-f

* Introduced new "Link Set Profiles" examples section, see
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-link-set-profiles
. Thanks to Phil Archer for help with this.

> * 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?
>
>
Appendix A was revised to use an example that does not use IANA-registered
link relation types in order to avoid the problem that IANA-registered link
relation types can not be expressed as HTTP URIs, see my note at the start
of this mail. See
https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-ld-context
. Thanks to Phil Archer for help with this.

> Cheers,
>
> --
> Mark Nottingham   https://www.mnot.net/
>
> --
> httpapi mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/httpapi
>

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

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 7 Oct 2021 12:01:54 +1100

See also
  https://github.com/protocol-registries/link-relations/issues/25

As I mention there, IANA is (AIUI) considering exposing a JSON format for *all* registries. If JSON-LD / Linked Web folks want to give them input, we should arrange a way to do that. Chairs, maybe we should ask our AD to facilitate that coordination?

Cheers,

> On 7 Oct 2021, at 1:42 am, Herbert Van de Sompel <[email-masked]> wrote:
> 
> I went through the link set draft; apologies for the delay. Feedback below; most of it is editorial.
> 
> 
> Mark, we dealt with your feedback and published a new version of the I-D at https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html . Below, I provide pointers to sections affected by handling it.
> 
> One - IMO - significant issue remains to be addressed, not by the Link Set specification, but in general, i.e. it not being possible to express IANA-registered link relation types as HTTP URIs. Several people, including myself, expressed their frustration with that regard in the context of the discussion https://github.com/ietf-wg-httpapi/linkset/issues/45. Some digging around revealed that this issue was also discussed in https://github.com/mnot/I-D/issues/140; both you and my Link Set co-author Erik were involved in that discussion. I was wondering whether this might be something that could be picked up by the HTTPAPI working group. After all, the capability to express IANA-registered link relation types would generally increase interoperability between semantic and non-semantic applications.
> 
> Greetings
> 
> Herbert
>  
> 
> * 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.
> 
> 
> See https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-introduction
>  
> * 3. Scenarios -- usually sections like this are called something like "Use Cases"
> 
> 
> Section renamed "Uses Cases and Motivation", see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-use-cases-and-motivation
>  
> * 3. Scenarios -- it feels like this section could be tightened up; it's fairly long for the amount of content here
> 
> 
> We have not changed the content of the section because of lack of inspiration.
>  
> * 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).
> 
> Changed "SHOULD" to "may", see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-document-formats-for-sets-o
>  
> 
> * 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. 
> 
> 
> Wording added to allow newlines, see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-http-link-document-format-a
>  
> * 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).
> 
> 
> This "MUST be" and some similar ones were replaced by "is", see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-set-of-links
>  
> * 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?
> 
> 
> * In order for a document to have the application/linkset+json media type, it indeed must only have "linkset" as its sole member. A JSON document can have a "linkset" member (as defined in the spec) as well as other members, but then it's not an application/linkset+json document.
> 
> * As a result of the discussion changed the JSON Extensibility section to allow but not encourage "foreign" members of the "linkset" member, see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-extensibility
>  
> * 4.2.2 Link Context Object -- 'SHOULD NOT be a relative reference' -- what are the consequences of violating this SHOULD NOT?
> 
> 
> * 4th paragraph of https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-http-link-document-format-a
> 
> * 3rd paragraph of https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-document-format-applic
>  
> * 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. 
> 
> Changed reference, see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-link-target-attributes
>  
> * 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.
> 
> 
> We did not change/remove these sections because they are considered valuable for implementers, see https://github.com/ietf-wg-httpapi/linkset/issues/43
>  
> * 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.
> 
> 
> * Changed "attribute" to "parameter", see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-the-profile-paramter-for-me
> 
> * Introduced "profile" attribute for "linkset" links, see last paragraph of https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-the-linkset-relation-type-f
> 
> * Introduced new "Link Set Profiles" examples section, see https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-link-set-profiles . Thanks to Phil Archer for help with this.
>  
> * 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?
> 
> 
> Appendix A was revised to use an example that does not use IANA-registered link relation types in order to avoid the problem that IANA-registered link relation types can not be expressed as HTTP URIs, see my note at the start of this mail. See https://www.ietf.org/archive/id/draft-ietf-httpapi-linkset-04.html#name-json-ld-context . Thanks to Phil Archer for help with this.
> 
>  
> Cheers,
> 
> --