Sideline resources

[ericelliott]

Siren has built-in support for entity embedding. Is there a good standard way to sideline entities, rather than including them inline?

{
  "title": "example",
  "class": "orders",
  "entities": [
    {
      "properties": {
        "customerId": "foo"
      }
    }
  ],
  "sideline": {
    "foo": {
      "properties": {
        "id": "foo",
        "name": "George"
      }
    }
  }
}

[apsoto]

What's sideline? Example?

[kevinswiber]

@dilvie Is this still an open issue for you? I'm not entirely sure what sidelining offers over embedding. Perhaps you can elaborate.

[ericelliott]

Sidelining reduces duplicate content. For example, if the same resource needs to be included many times in a payload, you can sideline it and refer to it by ID instead of including it embedded in every entity that needs it.

The mechanism needs better specification and examples.

[zdennis]

Has any more thought went into this? I agree with a mechanism for reaching @ericelliot's stated goal, but I'm not sold on the name. It doesn't seem very intuitive. Why not just call it embedded?

[grollinger]

One way to deal with this would be to include the full representation only once and use embedded links everywhere else. Though that would require intelligent handling on server as well as client side.

[ericelliott]

@rollingthunder That is the definition of sidelined resources.

@zdennis:

"I'm not sold on the name. It doesn't seem very intuitive. Why not just call it embedded?"

Embedded resources refer to resources that are used in-line. The purpose of sidelining is to include the resource only once in the JSON. See "Responsive APIs" from my book, "Programming JavaScript Applications"

[zdennis]

@ericelliott, I understand what the purpose of sidelining is (hence my original comment stating I support your stated goal), I just don't think sideline is the right word for the job.

Embedded resources refer to resources that are used in-line. The purpose of sidelining is to include the resource only once in the JSON.

I don't believe these two things are not mutually exclusive. You have embedded resources (sub-entities and such) and you need a way to store those resources once. The storage container needs a name. Sideline seems devoid of communicating anything about the data being stored or its relationship to other resources in the document.

I think embedded may be a more intuitive term than sideline as it implies the relationship of the data to other resources in the document, but I'm not suggesting it's the right term either.

[ericelliott]

@zdennis - whether you agree or not that sideline is the right word, embed is commonly used to refer to data that is embedded inline, rather than referred to by reference inline.

I believe sideline is a good term because it clearly states an alternative to inline.

Sideline seems devoid of communicating anything about the data being stored or its relationship to other resources in the document.

The container is just a container. It should be devoid of communicating anything about the data being stored or its relationship to other resources in the document. Communicating relationships is a function of the links themselves, since different entities might have different relationships to the sidelined content.

[grollinger]

@ericelliott

That is the definition of sidelined resources.

The point I was trying to make was that the spec already allows this. We have support for embedded representations and embedded links. Granted, there will be some repetition where rel is concerned, but you don't have to repeatedly transmit the complete representation.

[ericelliott]

The point I was trying to make was that the spec already allows this. We have support for embedded representations and embedded links.

Are in-document links supported in the Siren spec? How did I miss that?

[mdemuth]

Since much of this spec is a direct translation from html to json, I would suggest adding an optional id field to entities and use fragment links: i.e self-url-of-root-entity#embedded-id just like anchors. And by the way an ID is the defining characteristic of an entity and as such should not be included in the properties section of an entity.

[xogeny]

I just wanted to add that I’ve had use cases for sideline resources. I’m not sure if it makes sense in the context of Siren or whether perhaps and entirely different media type may be better.

I also wanted to add that not only can sidelining avoid duplicate content, it is also the only way I can see to deal with recursion for embedded resources.