Understanding sparse-fieldsets in more detail

1

Im trying to understand sparse-fieldsets. Unfortunately, couldnt find the answer at https://jsonapi.org/examples/#sparse-fieldsets and other sources online

Lets say I have the following endpoint

GET /articles?include=author HTTP/1.1

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}
  1. When I do: GET /articles?include=author&fields[people]=name

Is it supposed to return data.attributes and data.relationships? i.e.

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
      }
    }
  ]
}

Or should it return as:

{
  "data": [{
    "type": "articles",
    "id": "1"
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
      }
    }
  ]
}
  1. If I do: GET /articles?fields[people]=name (without include)

Should the result still return with included?. i.e.

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
      }
    }
  ]
}

Or:

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }]
}
2
  1. You don’t show the relationships since the author field is not mentioned in the fieldset. See the comment in parentheses in the following quote of the specification. The attributes would only containt name.

Note: Because compound documents require full linkage (except when relationship linkage is excluded by sparse fieldsets), intermediate resources in a multi-part path must be returned along with the leaf nodes. For example, a response to a request for comments.author should include comments as well as the author of each of those comments .

https://jsonapi.org/format/#fetching-includes

  1. To is up to you. You include resources whenever you want, but if the include parameter is present, you must include the corresponding resources or return an error. You can’t simply ignore it. If you support the parameter and the client defines it, then you must follow it.

An endpoint MAY return resources related to the primary data by default.
An endpoint MAY also support an include request parameter to allow the client to customize which related resources should be returned.
If an endpoint does not support the include parameter, it MUST respond with 400 Bad Request to any requests that include it.
If an endpoint supports the include parameter and a client supplies it, the server MUST NOT include unrequested resource objects in the included section of the compound document.

https://jsonapi.org/format/#fetching-includes