Skip to content

Instantly share code, notes, and snippets.

@kevinswiber
Created July 7, 2012 14:56
Show Gist options
  • Save kevinswiber/3066768 to your computer and use it in GitHub Desktop.
Save kevinswiber/3066768 to your computer and use it in GitHub Desktop.
JSON Siren vs. HAL Representations
{
"_links": {
"self": { "href": "/orders" },
"next": { "href": "/orders?page=2" },
"find": { "href": "/orders{?id}", "templated": true }
},
"_embedded": {
"orders": [{
"_links": {
"self": { "href": "/orders/123" },
"basket": { "href": "/baskets/98712" },
"customer": { "href": "/customers/7809" }
},
"total": 30.00,
"currency": "USD",
"status": "shipped",
},{
"_links": {
"self": { "href": "/orders/124" },
"basket": { "href": "/baskets/97213" },
"customer": { "href": "/customers/12369" }
},
"total": 20.00,
"currency": "USD",
"status": "processing"
}]
},
"currentlyProcessing": 14,
"shippedToday": 20
}
{
"class": "orders",
"properties": {
"currentlyProcessing": 14,
"shippedToday": 20
},
"entities": [
{
"class": "order list-item",
"rel": "order",
"properties": {
"total": 30.00,
"currency": "USD",
"status": "shipped"
},
"entities": [
{ "rel": "basket", "href": "/baskets/98712" },
{ "rel": "customer", "href": "/customers/7809" }
],
"links": [{ "rel": "self", "href": "/orders/123" }]
},
{
"class": "order list-item",
"rel": "order",
"properties": {
"total": 20.00,
"currency": "USD",
"status": "processing"
},
"entities": [
{ "rel": "basket", "href": "/baskets/98713" },
{ "rel": "customer", "href": "/customers/12369" }
],
"links": [{ "rel": "self", "href": "/orders/124" }]
}
],
"actions": [{
"class": "find-order",
"href": "/orders",
"fields": [{ "name": "id", "type": "number" }]
}],
"links": [
{ "rel": "self", "href": "/orders" },
{ "rel": "next", "href": "/orders?page=2" }
]
}
@kevinswiber
Copy link
Author

The example HAL document comes from the most recent HAL draft: http://tools.ietf.org/html/draft-kelly-json-hal-03#section-6

I added some class values to the Siren equivalent. Those values are not part of the translation between formats.

@kevinswiber
Copy link
Author

Oh, and I suppose I should put a link to Siren in here, as well: https://github.com/kevinswiber/siren

@iwek
Copy link

iwek commented Jan 9, 2013

Which one do you prefer? It would be great if you could also include JSON+Collection representation or hm-json.

@mtiller
Copy link

mtiller commented Mar 4, 2013

I just recently came across these various formats (HAL, Siren, Collection+JSON and hm-json).

I just want to say, I think there is some awesome work being done in this space. It would be great to see some of these options fold into each other, but I'm guessing that won't happen for various reasons.

I wonder, has anybody really analyzed the underlying data models to see if there is a common underlying data model that could be used to internally that would allow them all to be rendered from a given instance of the data model?

@mikekelly
Copy link

hey @mtiller, HAL is basically that abstract model, hal+json and hal+xml are just serializations of it. The model is very simple:

  • A document represents a resource
  • A resource has properties, links, and embedded resources

It was actually intended as a basic baseline hypermedia type on which other more complex types could be built. Instead it seems that most people were happier with the simplicity of hal on its own, and that people trying to come up with more complicated types had their own opinions on how links and embedded-ness should be represented which were strong enough to require reinventing the wheel.

fwiw, I'm working on a more complicated media type which does actually extend hal to add some form controls.

@cappelaere
Copy link

Is a "class" a string as in provide example or must be an array as in spec (spec says "MUST") ? [or can be either but spec needs to not say MUST]
Same question for rels.
Many thanks.

@tobnee
Copy link

tobnee commented Jun 23, 2014

A minor issue with the HAL resource is that it is not valid JSON because of this comma at the line end (the draft has the same issue)

@zdennis
Copy link

zdennis commented Aug 15, 2014

@cappelaere, it looks like this was created one month before @kevinswiber moved class and rel to be arrays so it's likely an out of date aspect of this gist. kevinswiber/siren@9972c84

@redben
Copy link

redben commented Sep 2, 2014

In my opinion HAL is the most straightforward... well apart from the _embeded concept which can become cumbersome sometimes. So I like HAL - _embeded !

@nduane
Copy link

nduane commented Feb 11, 2015

The SIREN representation doesn't seem equivalent to the HAL one. The HAL representation has an embedded representation called "orders" which is an array of orders. The SIREN representation has two embedded resources, unfortunately unnamed, which are order list-item.

@kirkins
Copy link

kirkins commented Dec 29, 2016

Anyone know which json standard has become most popular? I'm writing a bunch of json schema for various multimedia apps but standardization among units is lacking. Will probably go with something closer to Siren.

You may find this useful and/or interesting: http://json-schema.org/latest/json-schema-core.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment