Re: [httpapi] Linkset feedback

[Herbert Van de Sompel <[e-mail]>]

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