Filter on (nested) relationship attribute?


Keeping in mind that the jsonapi spec clearly notes that it is agnostic about filtering strategies,
the recommended section provides some help regarding implementing search:

Furthermore, multiple filters can be applied to a single request:

GET /comments?filter[post]=1,2&filter[author]=12

What would be recommended way to filter on attributes of the relationships like

Personally I don’t like all the square brackets so I would prefer something like filter[]=John,
but looking at the rest of the spec probably something like filter[author][name]=John is closer.
In this forum I also saw examples like: filter[author:name]=John.

What do you think is best, and would it be a good idea to document this in the recommended section?

Another I’m wondering is how to filter on nested relationships. Image the author has a nationality relationship with a alpha2-code attribute.
Filtering on this using dots could look like:

Using dots this could look like filter[author.nationality.alpha2-code]=NL.

Using square brackets it could look like: filter[author][nationality][alpha2-code]=NL.

What are your opinions?


Thinking about this again. For inclusion of related resources the spec mentions:

The value of the include parameter MUST be a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names.

Meaning a dot should be used to form a relationship path.
In that case I think it would also be good to use a dot in the filter field paths.

So probably filter[]=John is the most consistent as well.


I would also recommend including the operator on the filter:

  • filter[][eq]=John
  • filter[][not-eq]=John


Yes the operator like filter[][eq]=John could be a good extension.
With only filter[]=John meaning an implicit [eq].