HAL JSON - is it allowed by the standard to have multiple levels of embeds?

Question

I was wondering if it is allowed to have more _embed elements inside _embed elements in JSON, or if the idea is to only have one level?

See example of normal HAL:

{
"_links": {
    "self": { "href": "/orders" },
    "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],
    "next": { "href": "/orders?page=2" },
    "ea:find": {
        "href": "/orders{?id}",
        "templated": true
    },
    "ea:admin": [{
        "href": "/admins/2",
        "title": "Fred"
    }, {
        "href": "/admins/5",
        "title": "Kate"
    }]
},
"currentlyProcessing": 14,
"shippedToday": 20,
"_embedded": {
    "ea:order": [{
        "_links": {
            "self": { "href": "/orders/123" },
            "ea:basket": { "href": "/baskets/98712" },
            "ea:customer": { "href": "/customers/7809" }
        },
        "total": 30.00,
        "currency": "USD",
        "status": "shipped"
    }, {
        "_links": {
            "self": { "href": "/orders/124" },
            "ea:basket": { "href": "/baskets/97213" },
            "ea:customer": { "href": "/customers/12369" }
        },
        "total": 20.00,
        "currency": "USD",
        "status": "processing"
    }]
}

}

and what the question is about (notice that the second embed is a child of the first one):

{
   "_links" : {
     "self" : {
     "href" : "http://localhost:8090/fs/rest/roles/roleDefinition=Z1407031312513158080GIVMZ"
     }
   },
   "_embedded" : {
      "roles" : [ {
      "_links" : {
          "self" : {
               "href" : "http://localhost:8090/fs/rest/roles/Z1407031312513168080XCAKL"
           }
       },
       "id" : "Z1407031312513168080XCAKL",
        "_embedded" : {
             "roleDefinition" : {
              "_links" : {
              "self" : {
               "href" : "http://localhost:8090/fs/rest/roledefinitions/Z1407031312513158080GIVMZ"
        (rest ommitted)

Illustration of multiple levels of embedded resources

Myself I am reading the documentation at http://stateless.co/hal_specification.html as that an embedded resource is the same as a normal resource and therefore it can again contain embedded resources?

score 0 · Answer 1 · edited Oct 07 '21 at 07:27

I also faced this question. seems like the answer is yes or no.

since the embedded resource can be

full, partial or inconsistent version

, it is up to the implementor if you use the _embedded tag, or directly embed the resource.

In my opinion it is best to return the embedded resource just as you would when they use the link. consumers of the api may already have parsers written to handle the embedded resource, (which would also normally include the _embedded tag)

https://datatracker.ietf.org/doc/html/draft-kelly-json-hal-06#section-4.1.2

4.1.2. _embedded

The reserved "_embedded" property is OPTIONAL

It is an object whose property names are link relation types (as
defined by [RFC5988]) and values are either a Resource Object or an
array of Resource Objects.

Embedded Resources MAY be a full, partial, or inconsistent version of the representation served from the target URI.

HAL JSON - is it allowed by the standard to have multiple levels of embeds?

1 Answers1