JSON Siren vs. HAL Representations

hal.json

{
  "_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
}

siren.json

{
  "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" }
  ]
}

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.

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

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

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?

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.

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.

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)

@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

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

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.

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