Skip to content

Commit

Permalink
name=value syntax for function calls
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralfhandl
ralfhandl committed Mar 14, 2024
1 parent e2ac582 commit 24d78ab
Show file tree
Hide file tree
Showing 3 changed files with 74 additions and 46 deletions.
2 changes: 1 addition & 1 deletion vocabularies/Org.OData.JSON.V1.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"Org.OData.JSON.V1": {
"$Alias": "JSON",
"@Core.Description": "Terms, types, and functions for JSON data",
"@Core.LongDescription": "OData [stream properties](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ManagingStreamProperties) allow embedding data of arbitrary media types,\nand the OData JSON format allows [direct embedding of JSON data](https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_StreamProperty) in request and response payloads.\n\nThis vocabulary defines a convenience [type for JSON data](#JSON) as well as a term for referencing a [JSON Schema](#Schema) describing the structure of the JSON data.\n\nIn addition it defines two functions for [querying](#query) JSON data and using a [primitive value](#value) extracted from JSON data in common expressions, for example in `$filter`, `$orderby`, or `$compute`.\n\n**Example**\n\nThe `Employees` entity set has a JSON data property `resume`:\n```json\n\"container\": {\n \"$Kind\": \"EntityContainer\",\n \"Employees\": { \"$Collection\": true, \"$Type\": \"this.Employee\" }\n},\n\"Employee\": {\n \"$Kind\": \"EntityType\",\n \"$Key\": [\"empid\"],\n \"empid\": { \"$Type\": \"Edm.Int32\" },\n \"resume\": { \"$Type\": \"JSON.JSON\", \"$Nullable\": true }\n}\n```\n\nOne of its entities has a `resume` value of\n```json\n{ \n \"ssn\": \"1234\", \n \"lastname\": \"Doe\", \n \"address\": {\n \"zipcode\": \"10022\", \n \"street\": \"ABC st\"\n },\n \"experience\": \"excellent\"\n}\n```\n\nThis allows to filter and sort by values in that resume, and extract parts of the resume as a dynamic JSON data property\n```http\nGET http://www.example.com/mycompany/Employees\n ?$filter=resume/JSON.value('$.lastname') eq 'Doe'\n &$orderby=resume/JSON.value('$.experience')\n &$compute=resume/JSON.query('$.address') as address\n &$expand=address\n```\nreceiving\n```json\n{ \n \"@odata.context\": \"$metadata#Employees\", \n \"value\": [ \n {\n \"empid\": 4711,\n \"address\": {\n \"zipcode\": \"10022\", \n \"street\": \"ABC st\"\n }\n },\n ...\n ]\n}\n```\n ",
"@Core.LongDescription": "OData [stream properties](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ManagingStreamProperties) allow embedding data of arbitrary media types,\nand the OData JSON format allows [direct embedding of JSON data](https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_StreamProperty) in request and response payloads.\n\nThis vocabulary defines a convenience [type for JSON data](#JSON) as well as a term for referencing a [JSON Schema](#Schema) describing the structure of the JSON data.\n\nIn addition it defines two functions for [querying](#query) JSON data and using a [primitive value](#value) extracted from JSON data in common expressions, for example in `$filter`, `$orderby`, or `$compute`.\n\n**Example**\n\nThe `Employees` entity set has a JSON data property `resume`:\n```json\n\"container\": {\n \"$Kind\": \"EntityContainer\",\n \"Employees\": { \"$Collection\": true, \"$Type\": \"this.Employee\" }\n},\n\"Employee\": {\n \"$Kind\": \"EntityType\",\n \"$Key\": [\"empid\"],\n \"empid\": { \"$Type\": \"Edm.Int32\" },\n \"resume\": { \"$Type\": \"JSON.JSON\", \"$Nullable\": true }\n}\n```\n\nOne of its entities has a `resume` value of\n```json\n{ \n \"ssn\": \"1234\", \n \"lastname\": \"Doe\", \n \"address\": {\n \"zipcode\": \"10022\", \n \"street\": \"ABC st\"\n },\n \"experience\": \"excellent\"\n}\n```\n\nThis allows to filter and sort by values in that resume, and extract parts of the resume as a dynamic JSON data property\n```http\nGET http://www.example.com/mycompany/Employees\n ?$filter=resume/JSON.value(path='$.lastname') eq 'Doe'\n &$orderby=resume/JSON.value(path='$.experience')\n &$compute=resume/JSON.query(path='$.address') as address\n &$expand=address\n```\nreceiving\n```json\n{ \n \"@odata.context\": \"$metadata#Employees\", \n \"value\": [ \n {\n \"empid\": 4711,\n \"address\": {\n \"zipcode\": \"10022\", \n \"street\": \"ABC st\"\n }\n },\n ...\n ]\n}\n```\n ",
"@Core.Links": [
{
"rel": "alternate",
Expand Down
28 changes: 14 additions & 14 deletions vocabularies/Org.OData.JSON.V1.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,9 @@ One of its entities has a `resume` value of
This allows to filter and sort by values in that resume, and extract parts of the resume as a dynamic JSON data property
```http
GET http://www.example.com/mycompany/Employees
?$filter=resume/JSON.value('$.lastname') eq 'Doe'
&$orderby=resume/JSON.value('$.experience')
&$compute=resume/JSON.query('$.address') as address
?$filter=resume/JSON.value(path='$.lastname') eq 'Doe'
&$orderby=resume/JSON.value(path='$.experience')
&$compute=resume/JSON.query(path='$.address') as address
&$expand=address
```
receiving
Expand All @@ -70,13 +70,13 @@ receiving

Term|Type|Description
:---|:---|:----------
[Schema](./Org.OData.JSON.V1.xml#L131:~:text=<Term%20Name="-,Schema,-")|[JSON](#JSON)|<a name="Schema"></a>The JSON Schema for JSON values of the annotated media entity type, property, parameter, return type, term, or type definition<br>The schema can be a reference, i.e. `{"$ref":"url/of/schemafile#/path/to/schema/within/schemafile"}`
[Schema](./Org.OData.JSON.V1.xml#L151:~:text=<Term%20Name="-,Schema,-")|[JSON](#JSON)|<a name="Schema"></a>The JSON Schema for JSON values of the annotated media entity type, property, parameter, return type, term, or type definition<br>The schema can be a reference, i.e. `{"$ref":"url/of/schemafile#/path/to/schema/within/schemafile"}`


## Functions

<a name="query"></a>
### [query](./Org.OData.JSON.V1.xml#L139:~:text=<Function%20Name="-,query,-")
### [query](./Org.OData.JSON.V1.xml#L160:~:text=<Function%20Name="-,query,-")

Query a stream value of media type `application/json`, returning a stream value of media type `application/json`

Expand All @@ -89,13 +89,13 @@ Extracts a JSON value, such as an array, object, or a JSON scalar value (string,

Parameter|Type|Description
:--------|:---|:----------
**[input](./Org.OData.JSON.V1.xml#L149:~:text=<Function%20Name="-,query,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
[path](./Org.OData.JSON.V1.xml#L152:~:text=<Function%20Name="-,query,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
[&rarr;](./Org.OData.JSON.V1.xml#L155:~:text=<Function%20Name="-,query,-")|[JSON?](#JSON)|JSON value resulting from applying `path` to `input`
**[input](./Org.OData.JSON.V1.xml#L171:~:text=<Function%20Name="-,query,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
[path](./Org.OData.JSON.V1.xml#L174:~:text=<Function%20Name="-,query,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
[&rarr;](./Org.OData.JSON.V1.xml#L178:~:text=<Function%20Name="-,query,-")|[JSON?](#JSON)|JSON value resulting from applying `path` to `input`


<a name="value"></a>
### [value](./Org.OData.JSON.V1.xml#L160:~:text=<Function%20Name="-,value,-")
### [value](./Org.OData.JSON.V1.xml#L184:~:text=<Function%20Name="-,value,-")

Query a stream value of media type `application/json`, returning an OData primitive value

Expand All @@ -113,19 +113,19 @@ If a single non-null scalar JSON value is identified by `path` within `input`, t

Parameter|Type|Description
:--------|:---|:----------
**[input](./Org.OData.JSON.V1.xml#L175:~:text=<Function%20Name="-,value,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
[path](./Org.OData.JSON.V1.xml#L178:~:text=<Function%20Name="-,value,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
[&rarr;](./Org.OData.JSON.V1.xml#L181:~:text=<Function%20Name="-,value,-")|PrimitiveType?|OData primitive value resulting from applying `path` to `input`
**[input](./Org.OData.JSON.V1.xml#L200:~:text=<Function%20Name="-,value,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
[path](./Org.OData.JSON.V1.xml#L203:~:text=<Function%20Name="-,value,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
[&rarr;](./Org.OData.JSON.V1.xml#L207:~:text=<Function%20Name="-,value,-")|PrimitiveType?|OData primitive value resulting from applying `path` to `input`


<a name="JSON"></a>
## [JSON](./Org.OData.JSON.V1.xml#L186:~:text=<TypeDefinition%20Name="-,JSON,-")
## [JSON](./Org.OData.JSON.V1.xml#L213:~:text=<TypeDefinition%20Name="-,JSON,-")
**Type:** Stream

Textual data of media type `application/json`

<a name="Path"></a>
## [Path](./Org.OData.JSON.V1.xml#L197:~:text=<TypeDefinition%20Name="-,Path,-")
## [Path](./Org.OData.JSON.V1.xml#L224:~:text=<TypeDefinition%20Name="-,Path,-")
**Type:** String

[JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) expression
Expand Down
Loading

0 comments on commit 24d78ab

Please sign in to comment.