[Bug] JSON:API Multiple Filters on Same Relationship Path Fail with 400 Error

[theorenck]

Description and expected behavior

Description

When attempting to use multiple filter parameters on the same relationship path in our ZenStack REST API (which implements the JSON:API specification v1.1), the request fails with a 400 Bad Request error and the message "Invalid filter".

For example, when trying to filter clients by both the financial plan type of their allocations AND the professional's name associated with those allocations using this request:

/api/v1/rest/client?include=allocations.professional,organization&filter[allocations][financialPlan]=PER_SESSION&filter[allocations][professional][name]=John Smith

The API returns:

{
    "errors": [
        {
            "status": 400,
            "code": "invalid-filter",
            "title": "Invalid filter"
        }
    ]
}

However, if only one of these filters is used, the request works correctly.

Expected Behavior

According to the JSON:API v1.1 specification, multiple filter parameters targeting the same relationship path should be combined with AND logic. The API should properly handle both dot notation (filter[allocations.financialPlan]) and bracket notation (filter[allocations][professional][name]) for filter paths.

The request should successfully return clients that have allocations with both:

1. A financial plan type of "PER_SESSION" AND
2. A professional with the name "John Smith"

This functionality is critical for implementing complex filtering scenarios in our application that require filtering on multiple aspects of related entities.

Technical Details

The issue is in the buildFilter method of the ZenStack REST API handler, which fails to properly merge multiple filters targeting the same relationship path. The fix involves implementing a map-based approach to store filters by their root path and a recursive merging algorithm to combine them correctly.

I've PNPM patched it for now, but I'd love to contribute my solution ❤️. I'm sharing it as a gist for now:
https://gist.github.com/theorenck/94b36365a57d6028bf176b542fb99e75

Environment (please complete the following information):

• ZenStack version: [2.11.5]
• Prisma version: [6.3.1]
• Database type: [Postgresql]

Additional context
This issue breaks compliance with the JSON:API v1.1 specification in several ways:

1. Lack of support for multiple filters on the same relationship path:
   According to the JSON:API Filtering section, the server "MAY support filtering as described below" and "Servers SHOULD use the filter parameter family for filtering operations." Our implementation fails to properly handle multiple filter parameters on the same relationship path.

2. Inconsistent support for dot notation:
   The JSON:API Query Parameter section states that implementations MAY support both bracket notation and dot notation for nested parameters. Our implementation supports bracket notation but fails when dot notation is used alongside bracket notation for the same relationship path.

3. Misleading error message:
   The error message "Invalid filter" is misleading because it suggests that the filter syntax itself is incorrect, when in fact the filters are syntactically valid according to the specification. The issue is with the server's inability to merge multiple filters targeting the same relationship path.

4. Inconsistent behavior:
   The fact that each filter works individually but fails when combined indicates an inconsistency in the implementation that violates the principle of predictable behavior expected from a RESTful API.

The fix involves modifying the buildFilter method in the ZenStack REST API handler to properly support both dot notation and bracket notation, and to correctly merge multiple filters targeting the same relationship path using a map-based approach and a recursive merging algorithm.