Internet-Draft: JSON Hypertext Application Language (lean format for linking)

The _links field may not be necessary. There is already an HTTP Link header proposal, and is already being used by API's like GitHub's: <a href="http://www.w3.org/Protocols/9707-link-header.html" rel="nofollow">http://www.w3.org/Protocols/9707-link-header.html</a><p>From their examples, this is the equivalent representation:<p><pre><code> Link: &#60;http://www.tld/orders/523&#62;;rel=self, &#60;http://www.tld/warehouse/56&#62;;rel=warehouse, &#60;http://www.tld/invoices/873&#62;;rel=invoice </code></pre> It also allows for multiple Link headers to be sent instead of the comma-separated version.

This seems to be covered by json schema already does it not? <a href="http://tools.ietf.org/html/draft-zyp-json-schema-03" rel="nofollow">http://tools.ietf.org/html/draft-zyp-json-schema-03</a> see section 6 - Hyperschema, which lays out a way of describing which parts of a JSON object contains href links. This seems more elegant to me.

The HAL specification was created by Mike Kelly and a very readable introduction to it is here: <a href="http://stateless.co/hal_specification.html" rel="nofollow">http://stateless.co/hal_specification.html</a><p>We've been using it recently and we like it a lot.

One suggestion that's probably way too late in the game: underscores are often used to indicate privacy, membership, or a special state compared to the non-underscore-prefixed key. I think a dollar-sign prefix might be a better indication of meta-data.

I'm biased but I like my own design better:<p><a href="https://groups.google.com/forum/?fromgroups#!topic/restful-json/jDNhjfh9hfg" rel="nofollow">https://groups.google.com/forum/?fromgroups#!topic/restful-j...</a> (Google Groups breakage; link is meant to go to first post in discussion)<p>Instead of requiring that objects have a special _links property, you can put links anywhere in a JSON structure, just like in a HTML document.<p>Everything of the form<p><pre><code> { "$href": &#60;url&#62; [,"rel": &#60;token&#62;] [,"type": &#60;media-type&#62;] } </code></pre> anywhere in a JSON object is treated as a link.

I love the idea of this being standardized and am immediately thinking that a generic browser of application/hal+json resources would be a great developer tool.<p>I tend to agree with the idea that self should be top-level, but the other thing I'd like to have in the specification is versioning for both the specification itself and the API. How about something like:<p>{ ... "_version": { "hal": &#60;some HAL version string&#62;, "api": &#60;some API version string&#62; }, ... }<p>Thanks for the thought you've obviously put into this ... we'll all benefit eventually!

Like the idea. One suggestion - the value at json._links.self will often be a unique identifier. Maybe some provision can be made for this to live at a top level, like json._id<p>There are strong arguments against that idea I'm sure, but consider the boon to adoption you can get by having the only required thing be a top-level element not a nested attribute

Sorry to be off topic here but is there a standard for laying out specification documents like this that i can read up on? When ever I come across these they are always well thought out and nicely presented. It would be a nice way to present ideas due to the documents feeling well thought out and structured as apposed to a simple idea scribbled down.