Subject: [httpapi] JSON serialization for Web Linking

From: Evert Pot <[email-masked]>
Date: Fri, 30 Oct 2020 16:42:40 -0400

Hi all,

I would like to bring contribute this draft to the group:

https://tools.ietf.org/html/draft-pot-json-link

I realize it has overlap with a draft submitted earlier here:

https://tools.ietf.org/html/draft-wilde-linkset-07

However, I feel draft-pot-json-link serves a more general use-case and 
has a more specific scope. If accepted, I think draft-wilde-linkset 
could potentially refer to this serialization.

I think it could be helpful to have a single RFC to point to as /the/ 
way to serialize a link,. Linkset also attempts this, but I worry the 
other features (prescribing a media-type, linksets, the non-JSON 
serialization) might detract people from adopting the draft for their 
own format due to a potentially perceived larger psychological buy-in.

The next JSON:API format will adopt draft-pot-json-link as their link 
serialization, which means a large number of clients and servers will 
eventually use this specific format.

Evert

---

From: Erik Wilde <[email-masked]>
Date: Sat, 31 Oct 2020 09:34:50 +0100

hello evert.

> could potentially refer to this serialization.

adding some context: the linkset work started in 2016, starting with the 
explicit goal of creating media types for RFC 8288 web links:

https://datatracker.ietf.org/doc/draft-wilde-linkset/

since then, we've had 11 draft versions (across two I-D names) and quite 
a bit of community participation and discussion:

https://github.com/dret/I-D/issues?q=label%3Alinkset

> own format due to a potentially perceived larger psychological buy-in.

i am not quite sure why that would happen. we do define a JSON 
serialization that people can use while ignoring everything else (but 
there isn't actually that much else). we spent considerable effort to 
raise awareness, to make the serialization JSON-LD friendly, and as a 
result we have implementations in the field.

> eventually use this specific format.

i'd like to propose a different route: if the goal is to unify JSON web 
links (which i agree is a good goal to have), then let's look at what 
doesn't work in the existing linkset serialization that JSON:API does 
need. we're still open for suggestions and feedback (even though it 
would be unfortunate to make any breaking changes at this point).

cheers,

dret.

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

---

From: Evert Pot <[email-masked]>
Date: Sat, 31 Oct 2020 18:06:40 -0400

Hi Erik,

> i'd like to propose a different route: if the goal is to unify JSON 
> web links (which i agree is a good goal to have), then let's look at 
> what doesn't work in the existing linkset serialization that JSON:API 
> does need. we're still open for suggestions and feedback (even though 
> it would be unfortunate to make any breaking changes at this point).

This is what doesn't really work for me in linkset, as it is written today:

 1. The focus is in linkset is on the linkset use-case and media-type. I
    think useful to splice out specifically a JSON serialization for
    weblinks. Even if linkset does define /a/ serialization of Web
    links, I think its helpful to have something that's more focused
    specifically on solving this problem. Messaging matters, and the
    linkset document does not really talk about this. The fact that it
    does define a Web Linking serialization seems more like a
    side-effect that a core goal.
 2. linkset only describes document-wide links, which makes this
    incompatible with situations where you'd want to describe links that
    are not on the top-level of the document. Links, like in HTML, could
    appear deeper inside JSON documents and if we're proposing a
    standard way to serialize a link in JSON, it's nice to be able to
    support this case as well.
 3. In linkset, links must always appear in a nested object, because
    there is no 'rel' property on a specific link, which makes this at
    least more clumsy to use in contexts where you just need to embed a
    singular link.

If linkset is out in the wild, and you don't see a strong enough reason 
to make changes, I would still hope this group considers adopting 
json-link as well, as I think it's a useful building block for future 
standards. There's no reason different serializations can co-exist, and 
our goals I think are different.

Of course I would love to convince you to adopt the general 
serialization, but I don't think it's strictly required for the success 
of each proposal.

Evert