Position on sparse fieldsets

[cmars]

It may be necessary / useful for a client to request only a subset of attributes on a resource, especially when paging through a high volume of them.

JSON API provides for this with sparse fieldsets.

We need to document our position on these. My thinking is currently:

• Drop the square-bracket notation for reasons already stated in the docs: they're ugly (forces "percent" URL encoding, hard to read and write) and unnecessary (we don't allow compound documents, so there's no need to differentiate type)
• If fields is not defined as a parameter, resource does not support sparse fieldsets and returns everything.
• If fields is defined as a parameter:
  • It must be style: form, explode: false. This defines a comma-separated []string like ?fields=a,b,c.
  • No fields parameter present in the request means I'm not filtering fields, so "give me everything"
  • ?fields= means "I don't want any fields at all" (empty or omitted attributes)

[cmars]

What about sparse fields in nested attributes?

We might use a dot notation for this. Given a resource like:

data: {
  id: some-id,
  type: some-type,
  attributes: {
    package: {
      name: "lodash",
      version: "1.0.3",
      dependencies: [{
        name: "nodash",
        version: "2.0.1",
      }, {
        name: "slodash",
        version: "4.2.7",
      }],
    }}}

?fields=package yields the full nested contents of the package property.
?fields=package.name yields only the name property in in the package property object.
?fields=package.name,package.dependencies..name yields only:

• The name in each package object.
• The name in each dependencies array's item, in each package object.
  Like this:

data: {
  id: some-id,
  type: some-type,
  attributes: {
    package: {
      name: "lodash",
      dependencies: [{
        name: "nodash",
      }, {
        name: "slodash",
      }],
    }}}

This resembles JSON Path, without the leading $.. Which gives me some pause for concern, as I'm not sure we want to invite a full JSON Path implementation here, or even advertise it as such.

[cmars]

I think instead of fields, attributes might be a better name for this. This is going to be a reserved query parameter name.