"Structured JSON" request bodies for /$query

[ralfhandl]

Detailed proposal for

• /$query with "structured" $filter in JSON body #1977

System Query Options

Filter

Property $filter allows an object value that is a single CSDL JSON expression:

"$filter": {
  "$Eq": [
    { "$Path": "LastName" },
    "P&G"
  ]
}

or

"$filter": "LastName eq 'P&G'"

OrderBy

Property $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:

"$orderby": [
  { "asc": { "$Path": "ReleaseDate" } },
  { "desc": { "$Path": "Rating" } },
  { "asc": { "$Eq": [ { "$Path": "Status" }, "Shipped" ] } }
]

or

"$orderby": "ReleaseDate,Rating desc,Status eq 'Shipped'" 

Compute

Property $compute allows an object where each name-value pair consists of the name of a computed property and a CSDL JSON expression:

"$compute": { 
  "Total": { 
    "$Mul": [
      { "$Path": "Product/Price" },
      { "$Path": "Quantity"}
    ]
  }
}

or

"$compute": "Product/Price mul Quantity as Total" 

Expand

Property $expand 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": [
  "Products",
  { 
    "$orderby": [{ "asc": { "$Path": "ReleaseDate" } }, { "desc": { "$Path": "Rating" } }]
  }
]

or

"$expand": "Products($orderby=ReleaseDate,Rating desc)" 

Select

Property $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:

"$select": [
  "Addresses",
  { 
    "$filter": { "$Function": "startswith", "$Apply": [{ "$Path": "City" }, "H"] },
    "$top": 5,
    "$orderby": [
      { "asc": { "$Path": "Country/Name" } },
      { "asc": { "$Path": "City" } },
      { "asc": { "$Path": "Street" } }
    ]
  },
  "Role"
]

or

"$select": "Addresses($filter=startswith(City,'H');$top=5;$orderby=Country/Name,City,Street),Role" 

Expression as action/function parameter

Function and action parameters are represented by their name and a value that is either a scalar or a CSDL JSON expression object:

"StartDate": { "$Function": "now", "$Apply": [] },
"EndDate": "2024-12-31",
"Approver": { "$Path": "Manager" }

or (note the required suffix @expression to distinguish expression strings from scalar strings):

"StartDate@expression": "now()",
"EndDate": "2024-12-31",
"Approver@expression": "Manager",

Capability Annotation

<Annotation Term="Capabilities.PayloadExpressionSupport">
  <Record>
    <PropertyValue Property="CSDLExpressionsSupported" Bool="true" />
  </Record>
</Annotation>

<Annotation Term="Capabilities.QuerySegmentSupport">
  <Record>
    <PropertyValue Property="SupportedFormats">
      <Collection>
        <String>application/json</String>
      </Collection>
    </PropertyValue>
  </Record>
</Annotation>

[ralfhandl]

@HeikoTheissen to prepare a PR for CSDL JSON on ambiguities between string and duration literals

[HeikoTheissen]

#1987

[mikepizzo]

1. I like defining a structured representation, I'm not sure that I would base it on our CSDL expressions. CSDL expressions were designed for a different purpose, within a different context (model context, versus value context) and I suspect that there are things in CSDL that don't apply (i.e., property paths) and things that I can express in a url expression that I may not be able to express in CSDL expressions (like the new @expression syntax) though I need to do more thinking to confirm). If there are too many differences then it defeats the purpose of trying to use the same parser.
2. For the capability annotation; i like alternative 1 (defining content type parameters) because this also allows the request to explicitly request structured versus the (existing) text version of the query options.

[ralfhandl]

Re 2: could also use a specific media type application/odata-expressions+json

[HeikoTheissen]

A text/markdown document with embedded mermaid diagrams should not have a new media type text/mermaid+markdown, but rather a media type property like text/markdown; embeds=mermaid. If the document also has embedded geojson, that would become text/markdown; embeds=mermaid; embeds=geojson.

It is analogous for application/json payloads that have embedded CSDL expressions (or a new expression syntax).

[ralfhandl]

Remark from Heiko: also use suffix @expression for parameters because action parameters can be complex-typed