HyperJSON has 2 elements:
1) Hyperlinks
{ "$href": <url> [,"rel": <token>] [,"type": <media-type>] }
Everywhere a JSON document references a resource, it would use a hyperlink.
Example from a fictitious weblog API:
{ "type": "blog-post",
"url": { "$href": "http://example.com/blog/22", type: "text/html" },
"links": [ { "$href": "http://example.com/blog", "rel": "parent" },
{ "$href": "http://example.com/blog/23", "rel": "next" } ] }
The purpose of hyperlinks is to enable generic agents to extract
hyperlinks from arbitrary JSON, simply by traversing the JSON
structure and collecting all objects with a $href member.
2) Anchor properties
"$a": <token>
Every object in a JSON document that should be addressable using a
#-fragment identifier would use an anchor property.
For example, a friends list:
[ { "name": "John", "$a": "a1" },
{ "name": "Peter", "$a": "peter" } ]
The purpose of anchors is to be able to select subresources inside the
representation of a "parent" resource.
If the friends list is at http://example.com/friends, John would be
addressable as http://example.com/friends#a1, and Peter as
http://example.com/friends#peter.
This design comes from a recent discussion [1] with Kris Zyp; you
should read it for arguments for and against such a solution.
Manuel
[1] http://groups.google.com/group/restful-json/browse_thread/thread/14e4246922e4f1dc
Manuel Simoni wrote:
> HyperJSON is a strawman proposal for adding HTML-like hyperlinks and
> targetting of subelements to JSON.
>
I agree with name, I have been meaning to start using the term
"HyperJSON" to refer to these efforts as well, it seems like the most
natural shortening of what we are after, hypertext enabled JSON. I've
already commented on the other stuff...
Kris
>
> HyperJSON is a strawman proposal for adding HTML-like hyperlinks and
> targetting of subelements to JSON.
>
> HyperJSON has 2 elements:
>
> 1) Hyperlinks
>
> { "$href": <url> [,"rel": <token>] [,"type": <media-type>] }
>
> Everywhere a JSON document references a resource, it would use a
> hyperlink.
> Example from a fictitious weblog API:
>
> { "type": "blog-post",
> "url": { "$href": "http://example.com/blog/22", type: "text/html" },
> "links": [ { "$href": "http://example.com/blog", "rel": "parent" },
> { "$href": "http://example.com/blog/23", "rel":
> "next" } ] }
>
> The purpose of hyperlinks is to enable generic agents to extract
> hyperlinks from arbitrary JSON, simply by traversing the JSON
> structure and collecting all objects with a $href member.
This is a good start. See my attempt at http://www.subbu.org/blog/2008/10/generalized-linking
for a more comprehensive version.
> 2) Anchor properties
>
> "$a": <token>
>
> Every object in a JSON document that should be addressable using a
> #-fragment identifier would use an anchor property.
> For example, a friends list:
>
> [ { "name": "John", "$a": "a1" },
> { "name": "Peter", "$a": "peter" } ]
>
> The purpose of anchors is to be able to select subresources inside the
> representation of a "parent" resource.
>
> If the friends list is at http://example.com/friends, John would be
> addressable as http://example.com/friends#a1, and Peter as
> http://example.com/friends#peter.
Could you describe what you mean by "select subresources". Who is
selecting those subresources? The client?
Subbu
---
http://subbu.org
Yes, the client.
It would be exactly like in HTML: to get
http://example.com/friends#peter, the client would retrieve
http://example.com/friends and then search for an object whose "$a"
property equals "peter".