HyperJSON strawman

107 views
Skip to first unread message

Manuel Simoni

unread,
Oct 30, 2008, 1:32:17 PM10/30/08
to restfu...@googlegroups.com
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.

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

Kris Zyp

unread,
Oct 30, 2008, 1:36:56 PM10/30/08
to restfu...@googlegroups.com

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

Subbu Allamaraju

unread,
Oct 30, 2008, 1:38:22 PM10/30/08
to restfu...@googlegroups.com

On Oct 30, 2008, at 10:32 AM, Manuel Simoni wrote:

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

Manuel Simoni

unread,
Oct 30, 2008, 1:41:55 PM10/30/08
to restfu...@googlegroups.com

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

Reply all
Reply to author
Forward
0 new messages