Make top-level member included optional

[m-bodmer]

According to the JSON API spec http://jsonapi.org/format/#document-top-level:

A document MAY contain any of these top-level members:

• jsonapi: an object describing the server's implementation
• links: a links object related to the primary data.
• included: an array of resource objects that are related to the primary data and/or each other ("included resources").

In my specific use case, I do not want to have an included top-level member.

A suggestion for passing in what I want to have excluded

JSONAPISerializerConfig = {
    attributes: ['id', 'title'],
    exclude: ['included']
}

Then when building the serialized object, see if the property exists in the array of excluded items.

Thoughts?

[SeyZ]

You're totally right. I agree, we have to remove included if there's no compound documents.
I'm not sure about the exclude option. Why not just remove the included if included === [] ?

[m-bodmer]

There can be cases where I have compound documents and I have no need for the included top-level member.

I want to have serialized data like in the following example, but I have no need for the included member and want jsonapi-serializer to not generate it.

{
  "links": {
    "self": "http://example.com/posts",
    "next": "http://example.com/posts?page[offset]=2",
    "last": "http://example.com/posts?page[offset]=10"
  },
  "data": [{
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/posts/1/relationships/author",
          "related": "http://example.com/posts/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/posts/1/relationships/comments",
          "related": "http://example.com/posts/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/posts/1"
    }
  }],
  // Do not need
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

[digia]

Since included should always be an array of resources, checking for included.length would suffice.

Adding "excluded" options could be nice, though it could start to bloat the code. Couldn't you simply not include the comments or people relationship within the data you pass into serialize? Just a thought, trying to keep it simple.

[m-bodmer]

I still would like to see all the relationships. Another example:

JSONAPISerializerConfig = {
  typr: 'posts',
  attributes: ['title', 'author'],
  author: {
    ref: 'id',
    attributes: ['first-name']
  }
}

should produce

{
  "data": [{
    "type": "posts",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan"
    }
  }]
}

I do not need the included links, but still want to see all the author relationships. There are other cases in which I want the included member as well. How would I do this?

[m-bodmer]

I've written a quick sample of what the code could look like:

m-bodmer@71ed647

I agree it would be a bit of code bloat, but could be refactored in the future when more optional resource members are introduced.

[SeyZ]

Fixed with #7