Subject: [core] draft-ietf-core-links-json-01 review

From: "FOSSATI, Thomas (Thomas)" <[email-masked]>
Date: Tue, 11 Mar 2014 17:52:05 +0000

Hi Carsten,

we wanted to use the format in JSON link I-D for HTTP-CoAP proxy discovery.

So I took a look at it, and this is my brief review.

=-=-=-=

Both Abstract and Introduction say “[…] may be useful to represent these
collections in JSON”.  Perhaps worth adding some text to better
substantiate its useful-ness over RFC5988 serialisation?  I guess one of
the main motivations for preferring JSON over Link is the increased "web
API friendliness" (i.e. no added parsing cost for extracting link
information, format homogenisation, etc.).  Is it correct?

On the same topic: I find the argument given in the second para of the
Introduction -- ie. the "proactively try to stop formats' proliferation"
function of this spec — not very compelling.   But this might just be me
:-)

Also I think that it'd be nice to give the reader enough context to
understand how JSON link differs from other similar proposals (JSON
formats JSON-LD, JSON Reference, HAL, etc.) and why it is a better choice
than any of those for our use case.

Re: the implicit vs explicit rel="hosts" in Section 2, I'd be inclined to
add it explicitly because in the wider web it can’t be assumed, but would
love to hear from you and/or  others for reasons why it shouldn't.

In section 2.1, it'd be nice to have examples that show the less obvious
bits, e.g. multi-valued attribute to array, escape chars, etc.

=-=-=-=

That said, the doc is in pretty good shape!  Any plan for an updated
version?

Cheers, t

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 11 Mar 2014 22:34:52 +0100

Hi Thomas,

thank you for the review.

> information, format homogenisation, etc.).  Is it correct?

This is a very short draft, and I wouldn’t want to load it with text that second-guesses when it is better to use link-format and when it is better to convert to JSON.  But yes, friendliness to the Big Web is the main point of this specification.   Implicitly there is also a normative effect on application-internal APIs to link-format – ideally, the programmer no longer has to guess how link-format documents are represented internally.

I’ll try to add some, but not too much, text to this effect.

> function of this spec — not very compelling.   But this might just be me

This is mostly about the above-mentioned implicit effect.

> than any of those for our use case.

The current text is mentioning MNOT11.  Again, I wouldn’t want to expand this too much.
It may be worth to add explanation on the difference between “Linking from JSON” (which JSON-LD is about) and “JSON representation of links”, which this is about.

> love to hear from you and/or  others for reasons why it shouldn’t.

Great question.  My assumption so far was that both the link-format and the links-json consumer operate from the same semantics, so the two representations only differ in syntax.
The alternative, adding a semantic transform, may make the JSON easier to process without knowledge of the link-format semantics, but adds roundtripping headaches.  Is it worth it?

> bits, e.g. multi-valued attribute to array, escape chars, etc.

Very good point!

I’ll update the draft in the next 5 days or so based on this input.

Previously, we said that we wanted to wait with advancing this draft until we have more implementation experience.
I think it is worth checking if there are now more implementations, and, if yes, and assuming they don’t reveal groundbreaking flaws, going for a WGLC soon.  (This would also allow us to stay reasonably close to our Jan 2014 milestone for this.)

Grüße, Carsten

---

From: "FOSSATI, Thomas (Thomas)" <[email-masked]>
Date: Wed, 12 Mar 2014 09:50:43 +0000

>I’ll try to add some, but not too much, text to this effect.

Great, thanks.

>It may be worth to add explanation on the difference between “Linking
>from JSON” (which JSON-LD is about) and “JSON representation of links”,
>which this is about.

I’d avoid referencing mnot's blog, and would rather add the pointer for
the JSON-LD W3C’s TR?

>Great question.  My assumption so far was that both the link-format and
>the links-json consumer operate from the same semantics, so the two
>representations only differ in syntax.
>The alternative, adding a semantic transform, may make the JSON easier to
>process without knowledge of the link-format semantics, but adds
>roundtripping headaches.  Is it worth it?

What do you mean exactly by “roundtripping headaches”?

Looking at our use case (HTTP-CoAP proxy discovery), I don’t see any
problem in wasting ~10 bytes on the unconstrained side of the proxy to
make the relation explicit.

>Previously, we said that we wanted to wait with advancing this draft
>until we have more implementation experience.
>I think it is worth checking if there are now more implementations, and,
>if yes, and assuming they don’t reveal groundbreaking flaws, going for a
>WGLC soon.  (This would also allow us to stay reasonably close to our Jan
>2014 milestone for this.)

Thank you very much; I’m looking forward for the update.

And BTW, do you think it’d be sensible to specify JSON link as the
RECOMMENDED serialisation format for the HC proxy discovery mechanism in
the http-mapping I-D?

Cheers