Subject: [httpapi] linkset: use of "absolute URIs", corner cases, formatting

From: Christian Amsüss <[email-masked]>
Date: Mon, 14 Jun 2021 16:13:53 +0200

Hello linkset authors,

I've had a read through draft-ietf-httpapi-linkset-02 in the context of
CoRE work on embedded-usable resource metadata (in the course of which I
spent quite some time battling RFC6690).

Absolute URIs
-------------

In the current draft I noticed the term "absolute URIs" used in several
occasions to refer to URI references that are only URIs and not relative
references. It is regrettable that RFC3986 provides no good language to
keep these apart, or (more precisely) that it has become commonplace to
use the term "URI" also for URI references. The term "Absolute URI",
somewhat counter-intuitively, does not refer to a URI that is not
relative, but more strictly to one that has no fragment identifier.
(Makes sense for how it's used in HTTP requests, but not in links).

Figure 2 gives a concrete example of a URI that is a (full) URI but not
an absolute URI:  https://example.org/resource1#comment=1

I therefore suggest that all references to "absolute URIs (as defined in
Section 4.3 of [RFC3986])" be replaced with text that conveys the intent
of having a URI and not a relative reference.

Multi-rel links
---------------

Links do occasionally (albeit in what I assume to be a deprecatd
corner case) use multiple rel values in combination; rel="alternate
stylesheet" is the typical legacy example (where the combination of rels
has meaning), rel="start http://example.net/relation/other" is what
RFC8288 gives.

I understand 4.2.2 "For each distinct relation type" to refer to each
type individually (with white-space splitting of the Link header's rel
value) -- but then, which of these do the target attribtues get attached
to? The first? All?

(And what does that mean for round-tripping?)

Empty link params
-----------------

The RFC8288 ABNF describes link-params as having an optional value
token; for example, in CoAP we often annotate observable resources as
</status>;obs;ct=0 where the obs attribute has no value.

RFC8288 equates these to empty-string values in its appendix B.3 items 7
and 8.

As this document is quite explicit about the "if absent, set as
empty-string" behavior on href and anchor, it may be helpful to point
this out in 4.2.4.3 "Extension Target Attributes".

Round-tripping and sequence
---------------------------

Round-tripping between JSON and Link header format may part of the
sequence of links as well as target attributes; the partial ordering of
elemnts of the same anchor and relation is preserved, as is the partial
ordering of values to like-named attributes, but the order between
different attributes is lost to JSON objects' unordered nature and to
the aggregation of alike keys. (For example, bot ;foo=bar;a=b;foo=baz
and ;foo=bar;foo=baz;a=b become the same JSON even if the JSON processor
could preserve the sequence of object attributes, and the same as
;a=b;foo=bar;foo=baz if not).

This is consistent with my understanding of link equivalence, but may be
worth pointing out.

rel=linkset vs. more generic "see also"
---------------------------------------

The to-be-defined linkset relation does, by its description,
characterize the target as "providing more information about" the
context, but does so in a very technology specific way.

I'm unaware of any registered "see-also" relation (but frequently see
rdfs:seeAlso in the semantic web world), but such a generic link would
IMO present the same information more cleanly if accompanied by a
;type="application/linkset" or ;type="application/linkset+json"
attribute -- especially given that the type information is already
present in the example.

Please consider a more generic name. The IANA description can even stay
as it is, or be generalized a bit (from "set of links" to "metadata").

Formatting
----------

In an unrelated note, you may want to check the figure with the German
"nächstes Kapitel" which shows as "nachstes Kapitel" in the rendered
text. The figure may need to be declared as artwork for the character to
be shown correctly after rendering through xml2rfc.

Best regards
Christian

-- 
To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom

---

From: Erik Wilde <[email-masked]>
Date: Tue, 15 Jun 2021 09:31:00 +0200

hello christian.

thanks for the detailed feedback!

> Absolute URIs

good point. https://github.com/ietf-wg-httpapi/linkset/issues/17 
captures this issue.

my proposal is to say "non-relative URI" which seems to be the best 
option since it says what we mean without conflicting with RFC 3986. 
please feel free to add your preference to the issue.

> Multi-rel links

RFC 8288 makes it clear that it's simply a syntax variant to list links 
separately or use the "space-separated shortcut".

"The rel parameter can, however, contain multiple link relation types. 
When this occurs, it establishes multiple links that share the same 
context, target, and target attributes."

this implies that all of the link's data applies to all links 
established by multiple rel values. do you disagree?

> (And what does that mean for round-tripping?)

this syntactic variant cannot be round-tripped. which is fine, we 
certainly don't strive to represent every syntax detail.

> Empty link params

this may make sense to add. anybody else having an opinion? if so, 
please add an issue so that we can track it. thanks!

> Round-tripping and sequence

it seems to me that if we list everything that is not round-tripped, we 
create a lot of noise and little information. we could add some general 
language about this in section 4.2, though. if anybody thinks that would 
add value, please raise an issue. thanks!

> rel=linkset vs. more generic "see also"

it's not "more information about", it's more specifically "a set of web 
links in which the resource is participating".

> as it is, or be generalized a bit (from "set of links" to "metadata").

we've discussed this and believe that being more specific about the 
linked resource providing web links makes sense. we have specific 
scenarios (section 3) which really are about links, and not just generic 
"other info about the resource" scenarios.

> Formatting

https://github.com/ietf-wg-httpapi/linkset/commit/19e8c8c26d35391862dddeb3470c1c1755c84381#diff-21c61f895fd508e08595960d4f6f7d351019bc380b60c492530a3a7c4ea58f17 
fixes this issue.

thanks for your feedback. i have created one issue and have answered the 
remaining issues inline. if you feel that they do need more discussion, 
please open issues, so that we can have targeted discussions for each.

thanks again and cheers,

dret.

-- 
erik wilde | mailto:[email-masked] |
            | http://dret.net/netdret    |
            | http://twitter.com/dret    |

---

From: Christian Amsüss <[email-masked]>
Date: Tue, 15 Jun 2021 10:17:18 +0200

Hi,

> > Multi-rel links
> > ---------------
> > [...] -- but then, which of these do the target attribtues get attached
> > to? The first? All?
>
> "The rel parameter can, however, contain multiple link relation types. When
> this occurs, it establishes multiple links that share the same context,
> target, and target attributes."
> 
> this implies that all of the link's data applies to all links established by
> multiple rel values. do you disagree?

Thanks, the section of 8288 is pretty explicit -- so it may just be
worth pointing out that such links can multiply in size when expressed
in linkset. (Think of what `</>;rel="a b c d e f g h i j k l m n o p
q";foo="hello multiplication factor"` would look like). Plus, a
back-converter should be advised to aggregate links that only differ in
their rel.

I don't see any much better way, though.

> language about this in section 4.2, though. if anybody thinks that would add
> value, please raise an issue. thanks!

Maybe then it's more practical to describe what *is* round-tripped (that
is, the information can be round-tripped, but serialization details
including order can't).

> [...]
> we've discussed this and believe that being more specific about the linked
> resource providing web links makes sense. we have specific scenarios
> (section 3) which really are about links, and not just generic "other info
> about the resource" scenarios.

I fail to see the difference; in
</foo>;rel=hasMoreInfo;type=application/linkset, the type says that
thiis is a set of web links, and the hasMoreInfo strongly implies (no
less strongly thatn rel=linkset would) that the link context is
mentioned in there.

If that further discussion is on record anywhere, I'm happy to read up
to understand the difference point, but just from Section 3 I don't, and
still see rel=linkset to nail down two orthogonal aspects of a link
relation where one aspect is already covered by another target
attribute.

BR
c

-- 
Build a man a fire, and he'll be warm for a day. Set a man on fire, and
he'll be warm for the rest of his life.
  -- Terry Pratchett (attributed)

---

From: Erik Wilde <[email-masked]>
Date: Tue, 15 Jun 2021 17:00:17 +0200

hello christian.

On 2021-06-15 10:17, Christian Amsüss wrote:
> q";foo="hello multiplication factor"` would look like).

you're right about this example, but this scenario looks so extremely 
unlikely to happen for web links that i don't think we need to cover it 
as a specific example.

> Plus, a

that's up to them, as far as i am concerned. maybe i would do this when 
implementing one, but that's really up to personal preferences, as both 
ways are semantically equivalent.

> is, the information can be round-tripped, but serialization details

do you think this should be mentioned explicitly? if so, please let us 
know in an issue and possibly point out where you think this information 
should be included. thanks!

> less strongly thatn rel=linkset would) that the link context is

i am not quite following you. hasMoreInfo is not a type that exists. 
we're about web linking. we want to be able to link to sets of links. 
those can be linksets as defined by us, or by other specs (such as the 
CoRE spec).

link relations are about linking because you expect a certain affordance 
(as in this case: i want to find more links about that resource). the 
media type (if provided) then says how this represented. it may not be 
provided, or could be content-negotiated. pushing everything into the 
media type (and therefore requiring it and making the link relation type 
essentially pointless) to me seems like an anti-pattern for web linking.

> relation where one aspect is already covered by another target

https://datatracker.ietf.org/doc/html/rfc8288#section-2.1 is the best i 
can provide here. there is a history of separating the "what" to find 
aspect (link relation type) from the "how" aspect of how it is 
represented (media type). we simply follow that general pattern.

thanks and cheers,

dret.