Subject: Re: [httpapi] JSON serialization for Web Linking

From: Erik Wilde <[email-masked]>
Date: Sun, 1 Nov 2020 10:25:35 +0100

hello.

On 2020-10-31 23:06, Evert Pot wrote:
>  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.

that's true. we focus on the header field as defined in RFC 8288, not on 
how to represent web links *anywhere*.

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

indeed, our goal is not to define reusable components (something like a 
microsyntax) to embed in other schemas. our goal is to define 
representations for sets of links.

>     Messaging matters, and the
>     linkset document does not really talk about this.

afaict, it doesn't seem like we're ever creating the assumption that 
we're providing a representation for web links *everywhere*. we're just 
defining two representations of link header fields, which are sets of links.

>     The fact that it
>     does define a Web Linking serialization seems more like a
>     side-effect that a core goal.

it's the only goal of the draft, but not in the context you're looking 
for. we're really not doing much more than taking the model defined in 
RFC 8288, and defining a JSON representation for it.

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

i think this really is the main issue here. you're looking for a way to 
represent links *anywhere* (in JSON). we're just looking at the RFC 8288 
model of the link header field, and how to represent that one in JSON.

it's not that we're only supporting document-wide links. you can still 
add fragment identifiers. but yes, our focus is to represent "link 
documents" (which we call linksets), and not an embeddable schema component.

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

true, but that's because we're aligning the JSON model as closely as 
possible with the RFC 8288 syntax (with a bit of tweaking to make it 
more JSON-LD friendly).

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

yes, there seems to be a difference in goals.

cheers,

dret.

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

---

From: Darrel Miller <[email-masked]>
Date: Sun, 15 Nov 2020 22:26:45 +0000

Hey Evert,

While I agree it would be great if there were a common way of serializing links across media types, I’m concerned we are going to head down a path of bikeshedding.  I remember a lot of debates when HAL chose to use an object to serialize links instead of an array.  There were valid arguments for both the array form and the object form.  It is a warning sign for me that these two drafts take the opposite approaches.

My other concern is it seems like the intent of the draft is to try and standardize a concept that will then be used by other media types and frameworks. Your draft does declare the application/links+json but that seems like a secondary goal of the spec.  While I understand the desire to create standard building blocks for JSON documents, such a mechanism doesn’t exists within HTTP.  It seems more closely related to efforts like schema.org.

Darrel

From: Erik Wilde<mailto:[email-masked]>
Sent: November 1, 2020 4:25 AM
To: Evert Pot<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Re: [httpapi] JSON serialization for Web Linking

hello.

cheers,

dret.

--
erik wilde | mailto:[email-masked] |
            | https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdret.net%2Fnetdret&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7C2e2dc11771b44d20ac4508d87e481d24%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637398195489389983%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=feZ6JYqYquPZ1psTSmQFVgIjf6xt%2FGfK0pX5FZRF5ws%3D&amp;reserved=0    |
            | https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Ftwitter.com%2Fdret&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7C2e2dc11771b44d20ac4508d87e481d24%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637398195489389983%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=Hlc9DlHdvdRHmlXRMb48V76dvWtZDMhdZePL8bwkwWU%3D&amp;reserved=0    |

--
httpapi mailing list
[email-masked]
https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.ietf.org%2Fmailman%2Flistinfo%2Fhttpapi&amp;data=04%7C01%7CDarrel.Miller%40microsoft.com%7C2e2dc11771b44d20ac4508d87e481d24%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637398195489389983%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C1000&amp;sdata=P9l5F3I%2Bm4sbp83%2FR4VL36DyXw5BJpKAlzjgen0S1zM%3D&amp;reserved=0

---

From: Evert Pot <[email-masked]>
Date: Sun, 15 Nov 2020 17:57:00 -0500

Hi Darrel,

On 2020-11-15 5:26 p.m., Darrel Miller wrote:
>
> Hey Evert,
>
> While I agree it would be great if there were a common way of 
> serializing links across media types, I’m concerned we are going to 
> head down a path of bikeshedding.  I remember a lot of debates when 
> HAL chose to use an object to serialize links instead of an array.  
> There were valid arguments for both the array form and the object 
> form.  It is a warning sign for me that these two drafts take the 
> opposite approaches.
>
I 100% agree, it would be better if the two drafts used the same format.

> My other concern is it seems like the intent of the draft is to try 
> and standardize a concept that will then be used by other media types 
> and frameworks. Your draft does declare the application/links+json but 
> that seems like a secondary goal of the spec.  While I understand the 
> desire to create standard building blocks for JSON documents, such a 
> mechanism doesn’t exists within HTTP.  It seems more closely related 
> to efforts like schema.org.
>
>
I think it's definitely fair to say that this draft does not directly 
tie to HTTP, and more to JSON in a more general way. I thought this 
could be a good place to submit it here nonetheless. The group is 
described as "Building Blocks for HTTP APIs", and given that many HTTP 
APIs are ultimately going to be using JSON, and there's a good chance 
they would want to encode a link, it feels like the perfect building block.

My hope is that afterwards, json-links may be extended to get other 
formats to rfc status, such as:

https://tools.ietf.org/html/draft-nottingham-json-home-06
https://tools.ietf.org/html/draft-nottingham-link-hint-02

There's so many efforts in this space that will have a need for this. I 
hope we can look past things like the array/object bike-shedding and get 
behind something that is generally good enough.

If taking out the bits around "application/links+json" and 
document-level links gives this a higher chance of success, I think this 
is worth it.

Evert