Fields query paramter on nested attributes


I have nested attributes in my GET request.
How can I exclude some attributes if I don’t want to get them in the result?
Based on the JSONAPI document, we can use fields with an empty value:

The value of any fields[TYPE] parameter MUST be a comma-separated (U+002C COMMA, “,”) list that refers to the name(s) of the fields to be returned. An empty value indicates that no fields should be returned.

$ curl /users/1234?fields[users]=name,email&fields[address]=

Here, we shouldn’t get address in the response.
But imagine I have 50 attributes in the address (e.g., home, office, branch, …), and I want to exclude only the branch in the address attribute.
So, what’s the best way to achieve it? Something like fields[address][branch]= or fields[address.branch]=?

Based on the document JSON:API — Latest Specification (v1.1), we can’t go with dots (e.g., address.branch) as it’s for relationship. Therefore, we could go with square brackets (e.g., [address][branch]) based on the document:

A “query parameter family” is the set of all query parameters whose name starts with a “base name”, followed by zero or more instances of empty square brackets (i.e. []), square-bracketed legal member names, or square-bracketed dot-separated lists of legal member names. The family is referred to by its base name.

So, the solution would be: fields[address][branch]=

This is not supported by the base specification. It’s one of the many limitations you will run into when using complex data structures such as objects as attribute values. I consider them a foot gun for this reason. I would recommend refactoring the address attribute to a dedicated resource type instead and have a 1-1 relationship to it.

Please note that you can have a resource type, at API layer, which is stored as a JSON (or in any other way) at database layer.

The base specification defines the fields query parameter: JSON:API — Latest Specification (v1.1)

Implementations (as extensions and profiles) are not allowed to alter that definition. What you propose violates the JSON:API specification and will likely cause incompatibilities with existing libraries.

Hi Jelhan,

Thanks for your answer.
I can’t refactor the address attribute as it requires nested attributes. Also, the address attribute was an example, and I have many attributes with nested values, so I can’t create a separate resource for each and their nested. I mean, having nested attributes is not something against the standard. If my solution is against the standard (while I proposed based on the document), why does the document mention the quote I put in my answer?
Maybe I’m getting it wrong. Please guide me about it.

Query parameter families is a concept used by JSON:API base specification and can be used by extension and profiles. fields is a query parameter family.

Query parameter families can have multiple square bracket groups. But the fields query parameter family is defined by the base specification to only have one. Additionally the specification defines the meaning of the value into that square brackets. And allowed values for such a query parameter. Together this defines the processing rules for the fields query parameter family.

Implementations, extensions, and profiles are not allowed to change processing rules defined by the base specification.

This is why I consider attributes with complex values a foot gun: They seem to be a perfect fit on the first look. But you have a hard time as soon as you run into the limitations of those.

Thanks for the answer.
So, can I define a custom query parameter to solve the issue and also not against the JSON:API rules? Something like:


Or for one-level nested values, with a minus to indicate it should be excluded:


Here, phone will appear in the result but not city.

You can define implementation-specific query parameters. But they must include at least one character, which is not a-z. It’s recommended to use an uppercase character (A-Z) to fulfill that requirement. So Exclude would be allowed while exclude is not allowed.

As an alternative you could define an extension and an extension-specific query parameter. This is especially useful if you want to share your standard with others.

You must not alter processing rules for fields query parameter, which is defined by the base specification.