/$query with "structured" $filter in JSON body

[ralfhandl]

#371 added JSON request bodies for requests to /$query where system query options can be passed as name-value pairs, restricting the system query option value to a string.

This works fine for service implementations that have a full-fledged query option parser, and it is an implementation hurdle for less fortunate teams.

These would benefit from a "pre-parsed" JSON representation of system query option values, especially for $filter.

Proposal

Allow CSDL JSON expressions as values for $filter.

Define similar "pre-parsed" JSON representations for other system query options:

• $compute allows an object whose names are the dynamic properties to be computed and the values are CSDL JSON expressions
• $orderby allows an array of one-property objects, each object having a property of either asc or desc whose value is a CSDL JSON expression
• $select allows an array of strings containing paths, nested query options are represented as an object of query options using these rules recursively that directly follows the path string it applies to
• $expand similarly allows an array of strings containing paths, nested query options are represented as an object of query options using these rules recursively that directly follows the path string it applies to

Allow this also for action/function parameters whose value is an expression: "StartDate@expression":{...}

Add a Capabilities term to express which media types are supported for /$query, whether @expression is supported, and whether the expressions can be stringy or JSONy.

Example

Already allowed:

POST http://host/service/People/$query
Content-Type: application/json
 
{
  "$filter": "LastName eq 'P&G'",
  "$select": "FirstName,LastName"
}

Allow additionally:

POST http://host/service/People/$query
Content-Type: application/json
 
{
  "$filter": {
    "$Eq": [
      {
        "$Path": "LastName"
      },
      "P&G"
    ]
  },
  "$select": ["FirstName", "LastName"]
}

[ralfhandl]

TC 2024-08-28: nice idea, let's flesh it out in a pull request and then decide whether we want to go that route.

[ralfhandl]

More detailed proposal see

• "Structured JSON" request bodies for /$query #1982

[HeikoTheissen]

Also allow such structured system query options in action payloads?

[ralfhandl]

Query options cannot be passed in action payloads so far, do you want to open an issue for that?

[HeikoTheissen]

Let's wait until there is a requirement for that.