# Understanding sparse-fieldsets in more detail

**URL:** <https://discuss.jsonapi.org/t/understanding-sparse-fieldsets-in-more-detail/1896>\
**Category:** Uncategorized\
**Created:** [March 28, 2020, 5:35pm UTC](https://discuss.jsonapi.org/t/understanding-sparse-fieldsets-in-more-detail/1896 "2020-03-28T17:35:53Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![krz](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/krz/32/28_2.png) [@krz](https://discuss.jsonapi.org/u/krz)\
**Post date:** [March 28, 2020, 5:35pm UTC](https://discuss.jsonapi.org/t/understanding-sparse-fieldsets-in-more-detail/1896/1 "2020-03-28T17:35:53Z")

</div>

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

Lets say I have the following endpoint

```auto
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.

```auto
{
  "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:

```auto
{
  "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.

```auto
{
  "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:

```auto
{
  "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"}
      }
    }
  }]
}

```

---

<div class="post-metadata">

**Author:** ![maark](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/maark/32/184_2.png) [@maark](https://discuss.jsonapi.org/u/maark)\
**Post date:** [March 30, 2020, 11:03pm UTC](https://discuss.jsonapi.org/t/understanding-sparse-fieldsets-in-more-detail/1896/2 "2020-03-30T23:03:09Z")

</div>

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](https://jsonapi.org/format/#document-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](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](https://jsonapi.org/format/#document-resource-objects) in the `included` section of the [compound document](https://jsonapi.org/format/#document-compound-documents).

[https://jsonapi.org/format/#fetching-includes](https://jsonapi.org/format/#fetching-includes)