Sparse Fieldsets and Relations (error in example?)


As per the examples GET /articles?include=author&fields[articles]=title,body&fields[people]=name returns:

  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!",
      "body": "The shortest article. Ever."
  "included": [
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"

Is it correct that the author is included here?

I’m asking as the author was not in fields[articles]=title,body.
Note the relationship was not included (as expected) but what is the use of getting the author included?

It feels like an error in the example…


author is the name of the relationship article -> people, but the resource type is people.

The query string starts out with include=author&.... I don’t think it’s explicitly stated, but the most sensible parsing order of the different data shaping capabilities goes include -> filtering / sorting / pagination -> sparse fieldsets.

The relationship, and resource identifier object data is required for processing and full linkage for the response documents, sparse field sets just provides a means to limit the representation clutter to a minimum set in addition to the requirements of the format and provided parameters.

In other words, I look at sparse field sets as a representation post-processor. It isn’t required to be implemented this way of course, but that is the order of precedence I see in the specification.


Yes, author is the relationship name.
As the author is not included in the fields of the articles resource query param (fields[articles]=title,body) the relationship is not included in the response.
But isn’t it strange that it is in the included?

But as you explain it, is also a possible interpretation of the spec.