Subject: [apps-discuss] JSON Hypertext Application Language

From: Mike Kelly <[email-masked]>
Date: Thu, 7 Jun 2012 02:50:27 +0100

Hello,

I've published a draft of a media type for linking with JSON, and
thought it might be of interest to people on this list

http://www.ietf.org/id/draft-kelly-json-hal-00.txt

Feedback welcome..

Best,
Mike

---

From: Martin Thomson <[email-masked]>
Date: Fri, 8 Jun 2012 12:01:43 -0700

> http://www.ietf.org/id/draft-kelly-json-hal-00.txt

Let's test that theory...

I was initially inclined to call this an abomination, but that would
require fairly strong substantiation.  Let's just go with unnecessary.

Some colleagues gave me an overview of an API that uses something very
much like this.  And aside from the initial aesthetic reaction, I have
two complaints:

- _links is almost useless
- _embedded is an unnecessary optimization

Let's first attack the concept of generic linking.  It didn't work for
XML.  Reason: A user of a particular document needs to understand the
semantics attached to a particular link in order to make sense of it
and generic labels rarely work.

For instance, I need to understand that a link labelled "fishCannery"
leads to a resource that describes a fish cannery.  The value added by
_links is limited to signaling to a generic application that the value
of "fishCannery" is not just a string, but a URI.  In practice, none
of the fields other than href are used.

Now, the optimization.  Well, mostly, it's just an optimization.  The
folks I was talking to who used it, used it because they wanted to
save on HTTP requests (or they were using long polling and wanted to
push multiple "events" at the same time).  They had decomposed their
application into resources, then discovered that it was a little slow
when you want to pull multiple linked resources because it added round
trips.  There are better solutions; c.f. httpbis discussion on server
push.

In an HTTP context, embedding messes with caching, cannot be regarded
as authoritative, and doesn't benefit from resource metadata.

So, what's wrong with JSON?

--Martin

p.s. It should be application/<application-specific-name>+hal+json if
you want to get super pedantic on media types, since hal is just
another layer.  c.f. the profile link relation type for a discussion
on why a media type (or subtype marking) might be unnecessary.

---

From: Mike Kelly <[email-masked]>
Date: Fri, 8 Jun 2012 20:36:58 +0100

Hi Martin thanks for sharing your thoughts

The spec is a WIP and you can read the latest version here:
https://raw.github.com/mikekelly/hal-rfc/master/draft-kelly-json-hal-00.txt

further comments inline

> and generic labels rarely work.

Technically, according to the Web Linking specification referenced a
link relation type should either be registered with IANA or a URI.
Exposing an HTML document describing the semantics of the link at its
URI provides an avenue for making sense of a link that clearly can
work. I've written a 'browser' for HAL which lets you surf a HAL API
and allows you to pull up documentation as-you-go for relations that
are URIs.

> of the fields other than href are used.

There is value in that, it allows someone to build a generic link
traversal DSL which you could then apply out of the box to your app
like so:

follow the "fishCannery" link and then
  query the "search" link setting "fish" equal to "tuna"

> trips.

Yes, this is exactly the purpose of _embedded. They are parts of a
representation that actually represent the state of some other,
related, resource rather. Data URIs in links are another way to
achieve something similar but (iirc) they have a size limit, and there
is the obvious issue of human-readability.

> There are better solutions; c.f. httpbis discussion on server
> push.

Don't know enough to comment, sounds dubious that HTTP can eliminate
need for embedding.

> So, what's wrong with JSON?

It doesn't have these linking or embedding semantics. We have no
standard to build re-usable libraries and tooling around, this is an
attempt to establish a base standard without over-complicating the
issue.

> on why a media type (or subtype marking) might be unnecessary.

yes you could use a profile if you were so inclined. Personally, I am
happy to rely on a preceding relation to provide the context/meaning
of a given resource. I don't think this discussion is relevant here
though.

Cheers,
Mike

---

From: Martin Thomson <[email-masked]>
Date: Fri, 8 Jun 2012 14:02:48 -0700

Hi Mike,

As you can probably see, it's unlikely that I'll be a HAL customer.
If I wanted this sort of stuff, I know how to use XML.  That means
that you can choose to assign appropriate weight to this feedback.

> and allows you to pull up documentation as-you-go for relations that

No question, HAL let's you walk the graph, but it takes a human being
to make any sense of anything.  So, as I said, next to useless.

>  query the "search" link setting "fish" equal to "tuna"

How does your generic app know what value to put anywhere?  Again, you
rely on magic (the human ability to infer meaning based on context),
or some content-specific markings with an application that understands
those markings.

I guess that I'm just attacking whole idea of self-describing formats.
 JSON aint one.  That's a feature, not a drawback.

> is the obvious issue of human-readability.

Using data: URIs has another drawback: you don't get to learn the http
URI for the resource.

> Don't know enough to comment, sounds dubious that HTTP can eliminate

Well, it's a real problem.  And people want to solve it.  Doing
something at the HTTP layer makes sense.  So Good For Them.  I'd
prefer not to see further codification of the problem.

> attempt to establish a base standard without over-complicating the

Yeah, one of the real advantages of JSON is that that crap doesn't
exist.  I know how that can be frustrating, but I tend to see that as
a real strength of the format.  I like being able to write:

   var turnip = JSON.parse(input);
   var genus = http.get(turnip.genus);
   return JSON.stringify(genus);

...without being burdened by a framework that is "helping" me.

--Martin

---

From: Graham Klyne <[email-masked]>
Date: Fri, 08 Jun 2012 22:43:17 +0100

I'd be interested to hear how you think JSON-HAL compares with RDF in general 
(http://www.w3.org/standards/techs/rdf) and the JSON-LD encoding of RDF in 
particular (http://json-ld.org/spec/latest/json-ld-syntax/).

My immediate reaction is that there's a lot of overlap, even reinvention, here. 
  RDF has been in development for over 10 years, and there are now many and 
varied tools for working with it.

#g
--

On 07/06/2012 02:50, Mike Kelly wrote:
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss
>

---

From: Mike Kelly <[email-masked]>
Date: Fri, 8 Jun 2012 22:55:14 +0100

On Fri, Jun 8, 2012 at 10:43 PM, Graham Klyne <[email-masked]> wrote:
> I'd be interested to hear how you think JSON-HAL compares with RDF in
> general (http://www.w3.org/standards/techs/rdf) and the JSON-LD encoding of
> RDF in particular (http://json-ld.org/spec/latest/json-ld-syntax/).
>
> My immediate reaction is that there's a lot of overlap, even reinvention,
> here.  RDF has been in development for over 10 years, and there are now many
> and varied tools for working with it.
>

The obvious difference is complexity, HAL is considerably more simple
than JSON-LD; the HAL spec is tiny in comparison.

HAL does no impose any graph model on the resource state, it's just
plain JSON. The only triple'ish things in HAL are links and
embeddings.

Ian Davis actually produced a tool for converting RDF into HAL (with
some loss), but I can't find the link and not even sure if it is still
available.

Cheers,
M

---

From: James M Snell <[email-masked]>
Date: Fri, 8 Jun 2012 18:04:31 -0700

On Fri, Jun 8, 2012 at 2:02 PM, Martin Thomson <[email-masked]> wrote:
>[snip]
>[snip]

I think the most important consideration with this is: what will
developers *actually* do with the additional metadata vs. what they
*are able* to do. There is a distinct, and very practical difference.

Within the Atom format, when we defined the structure of a generic
link, we allowed for all kinds of additional metadata and that model
served as part of the basis for RFC 5988. And while the structure
allows for a great deal of potential use cases, the overall majority
of ACTUAL code focus solely on two attributes: the rel and the href.
Everything else tends to be ignored except in very specific
application cases. It's great that we can enable specific cases, but
we should not assume, necessarily, that a greater capacity for more
metadata is always a good thing.

Within the Activity Streams format (http://activitystrea.ms) there is
also working going on to define a basic mechanism for links within a
JSON Activity Stream. The mechanism I have proposed is very similar to
that seen in HAL except that it skips the object structure for a link
and just goes with Strings containing absolute IRI's. For example:

{
  "totalItems": 10,
  "links": {
    "next": "http://example.org?page=2",
    "previous": "http://example.org?page=1"
  },
  "items": [ ... ]
}

In this case, a developer is already going to have a reasonable
assumption as to what kind of resource the next and previous links
point to; and all the other metadata that is typically associated with
the generic link model simply is not necessary. An application that
understands how to process multi-paged activity streams following this
convention is going to know already to go looking for the next and
previous properties under link so there is no need at all (in this
case) for a "generic browser". The code necessary to support an
implementation of this is going to be very clear and concise.

It comes down to a tradeoff. Either we have a focused, concise,
efficient, minimal serialization that requires more application
specific handling or we have a generic, verbose, less-efficient
serialization that allows more generalized reasoning and browsing.
There are valid arguments for both, for certain, but I can see many
scenarios where HAL will just be way too verbose to be practical.

- James

---

From: Mike Kelly <[email-masked]>
Date: Sat, 9 Jun 2012 08:55:26 +0100

On Sat, Jun 9, 2012 at 2:04 AM, James M Snell <[email-masked]> wrote:
> HAL will just be way too verbose to be practical.

I think 'way too verbose' is overstating the importance of this. You
are the first person to raise this as an issue at all, let alone as a
significant one.

Link Objects are necessary to allow for the "templated" indicator (for
when the link is a URI Template), for including the additional link
params established in the Web Linking RFC, and to provide the
opportunity for extension of link objects in any future types wanting
to extend HAL e.g. by adding additional controls or hints.

Fwiw, I did actually consider also adding a direct string as you have
suggested here but decided against in the interests of
simplicity/consistency, given that the Link Object approach is
unavoidable (for the reasons stated above).

On another note - HAL has been established for a while now (as a less
formal, public specification) and has a growing list of server and
client tooling, seems to me like it would be a win for Activity
Streams to adopt HAL's already established conventions, given that
your recent new proposal is so close to it anyway.

Cheers,
M

---

From: Manuel Simoni <[email-masked]>
Date: Sat, 9 Jun 2012 13:00:03 +0200

> - _embedded is an unnecessary optimization

Disagree vehemently on the first point. Generic links in JSON are as
useful as generic links in HTML.

I agree on the second point. _embedded turns the specification from a
generic linking thing into a quite specific application profile. Maybe
there should be two specifications, one for _links, and one for
_embedded?

Manuel Simoni

---

From: Mike Kelly <[email-masked]>
Date: Sat, 9 Jun 2012 12:05:39 +0100

On Sat, Jun 9, 2012 at 12:00 PM, Manuel Simoni <[email-masked]> wrote:
> generic linking thing into a quite specific application profile.

Hi Manuel,

Embedded representations is a very common approach for reducing HTTP
requests in applications, and it is a form of hypertext so I think it
belongs in HAL.

Cheers,
M

---

From: James M Snell <[email-masked]>
Date: Sat, 9 Jun 2012 09:51:44 -0700

> are the first person to raise this as an issue at all, let alone as a

Deep breath please and consider the *complete* statement I made... which was:

Please allow me to stress the parts where I said, "there are valid
arguments for both" and "I can see many scenarios..."

It would be highly counterproductive to assume that HAL is appropriate
for all possible scenarios; all my feedback was intended to do was
indicate that, for the subset of interesting and relevant cases I've
worked with in the content and activity syndication space, complex
link structures tend towards overkill. That's not to say there's no
place for them, not by any stretch of the imagination.

> to extend HAL e.g. by adding additional controls or hints.

Ok. That all granted, for the majority of cases I've worked with, when
you boil everything down, I still, most often, only need a url and a
rel.

> your recent new proposal is so close to it anyway.

If the HAL spec is being used to address real application problems,
then that's fantastic. For activity streams, my opinions tend to be
driven more by the specific implementation requirements and a desire
to keep things as simple as they possibly can be. My note was merely
intended to provide (hopefully) constructive feedback from the
perspective of someone else who has dealt (many many times) with the
notion of generic linking mechanisms in JSON and XML data formats.
Take it for what it's worth.

- James

---

From: Mike Kelly <[email-masked]>
Date: Sat, 9 Jun 2012 19:39:57 +0100

Hi James,

Thanks for sharing your thoughts, I have some follow up questions in line

> place for them, not by any stretch of the imagination.

To be clear, there's no anxiety or animosity from my end on this - I'm
simply trying to understand why you would pick such emotive language
as "way too verbose to be practical" when all we're really talking
about is a very small difference in design. I understood your
rationale for proposing your slightly optimised alternative for
activity streams. I did (and still don't) understand why you believe
HAL's slightly-less-optimal approach to be so significant as to render
it "way too verbose" and/or "impractical".. at worst it's marginally
sub-optimal for some basic use cases.

> you boil everything down, I still, most often, only need a url and a

A rel and a url are all that is required to produce a valid link with
HAL. This is a valid link object:

{ "foo": { "href": "/bar" } }

Just to re-iterate, HAL's linking conventions have been around for
just under 2 years now, and you are the first person to consider this
a pressing issue.

> Take it for what it's worth.

So, just to clarify.. your desire for simplicity is so strong that a
very minor optimisation that will:

- harm the expressiveness of links
- damage future extensibility
- not benefit from existing libraries

is still 'the right option' for activtity streams over adopting a
design that has existed for almost 2 years, has seen decent adoption
and brings with it a handful of libraries in various programming
languages?

Maybe I've missed something vital but at the moment I do not
understand where you are coming from. Sorry.

Cheers,
M