Re: [httpapi] Linkset feedback

[Mark Nottingham <[e-mail]>]

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 <[e-mail]> wrote:
> 
> On Wed, Jul 28, 2021 at 9:27 PM Mark Nottingham <[e-mail]> 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
> [e-mail]
> https://www.ietf.org/mailman/listinfo/httpapi
> 
> 
> -- 
> ==================
> Herbert Van de Sompel
> https://hvdsomp.info
> https://orcid.org/0000-0002-0715-6126

--
Mark Nottingham   https://www.mnot.net/