Introduce the included extension

[somdoron]

Provide an alternative to the top-level included member. The advantage of this approach is that it is easier for the consumer of the API to fetch the included data (instead of searching for it in the included member).

The disadvantage is, that a resource may be embedded more than once.

[gabesullice]

@somdoron, I think an extension that embeds related resource objects would make many JSON:API users happy.

At this very moment, I don't think we're ready to adopt another extension into jsonapi.org, but that should not stop you from publishing this elsewhere in the interim. We will be making recommendations on jsonapi.org in the coming week about how we think extensions should be publicized and distributed.

---

As for the content of this extension, it makes me very happy to see the community running with the idea of extensions. I'm glad the namespace language worked for you and that you've incorporated it correctly 👍

I think I would suggest three changes:

1. Choose a different namespace than included since that already has a specific meaning in the spec. Perhaps embed?
2. Define a new query parameter instead of altering the processing rules for the existing include query parameter (extensions are not allowed to do this anyway). Perhaps ?embed:related=author?
3. Instead of adding three new members, why not write the language such that you're embedding the data member of the document linked to by the related link. I think you probably were trying to avoid duplicating type and id, but that's a little silly considering that the extension will probably end up causing lots of duplicated content ;) With that said, you could easily avoid this by saying that the data and embed:data members are mutually exclusive. I.e. if embed:data is present, data should be omitted and vice versa.

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "embed:data": {
          "type": "people",
          "id": "9",
          "attributes": {
            "firstName": "Dan",
            "lastName": "Gebhardt",
            "twitter": "dgeb"
          },
          "links": {
            "self": "http://example.com/people/9"
          }
        },
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        }
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  },
  "links": {
    "self": "http://example.com/articles/1?embed:related=author"
  }
}

My biggest concern with this extension would be in keeping the the dot-separated relationship syntax of the include query parameter, instead of limiting it to depth 1. The problem of duplicates will get exponentially worse with longer include paths. Implementers will have to be very careful not to write infinite looping code and/or not to exceed memory capacity. A "considerations" section at the bottom of the spec would probably be useful so you can point out implementation pitfalls.

[freddrake]

I'm not convinced there's an issue with having to search included for resources, since a vaguely reasonable client library can make retrieval of relationships consistent.

---

If something like @gabesullice's embed:data is allowed but not required, duplication can be avoided as well: the first reference to a resource that isn't primary data can use embed:data, and subsequent references can use a resource identifier object. This breaks down a bit for to-many relationships, since data contains a list of resource identifier objects.