Filtering/querying (deep) relationships - a proposal for a syntax

JSON:API currently lacks a standard for filtering/querying data included through relationships, as opposed to GraphQL which has this firmly specified.

Consider the following API:

  • GET /authors to get all resources of type author
  • Resource author has relationship articles which is to-many article
  • Resource article has attribute isDraft: boolean

Now consider the following request:

  • “Give me all authors who have draft articles, and include their draft articles”.

There are two filters here:

  • The filter on the author list (filtering on a related resource’s attribute)
  • The filter on the included articles

Here is a syntax that might be able to confer the necessary distinction:

GET /authors

The meaning of the two filters would be:

  • filter[articles.isDraft]=true means "only return authors who have articles with isDraft=true"
  • filter[articles][isDraft]=true means "for any included articles from the articles relationship, only return those with isDraft=true"

In other words:

  • The first (of two) pair of brackets indicate what to filter (if not present, filter top-level data)
  • The second (or only) pair of brackets indicate how to filter, using dot notation for filtering on related resources

As far as I can see, this syntax is general enough to be nested artibrarily on any level. For example, filter[articles.comments][]=John&include=articles.comments means "for each article, include only those comments that have name=John"

Does this make sense? Could this syntax be a clear, general, and consistent way to support filters on nested relationships?