Sparse Fieldsets and Relations (error in example?)


#1

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…


#2

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.


#3

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.