JSON: function "query"

examples/Org.OData.JSON.V1.Schema-sample.json

@@ -19,6 +19,27 @@
         }
     },
     "json.schema.sample": {
+        "$Alias": "this",
+        "container": {
+            "$Kind": "EntityContainer",
+            "Employees": {
+                "$Collection": true,
+                "$Type": "this.Employee"
+            }
+        },
+        "Employee": {
+            "$Kind": "EntityType",
+            "$Key": [
+                "empid"
+            ],
+            "empid": {
+                "$Type": "Edm.Int32"
+            },
+            "resume": {
+                "$Type": "JSON.JSON",
+                "$Nullable": true
+            }
+        },
         "example": {
             "$Kind": "ComplexType",
             "CodeDictionary": {
@@ -37,5 +58,6 @@
                 }
             }
         }
-    }
+    },
+    "$EntityContainer": "json.schema.sample.container"
 }

examples/Org.OData.JSON.V1.Schema-sample.xml

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8" ?>
+<?xml version="1.0" encoding="utf-8"?>
 <edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
   <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
     <edmx:Include Namespace="Org.OData.Core.V1" Alias="Core" />
@@ -7,7 +7,19 @@
     <edmx:Include Namespace="Org.OData.JSON.V1" Alias="JSON" />
   </edmx:Reference>
   <edmx:DataServices>
-    <Schema Namespace="json.schema.sample" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+    <Schema Namespace="json.schema.sample" Alias="this" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+
+      <EntityContainer Name="container">
+        <EntitySet Name="Employees" EntityType="this.Employee" />
+      </EntityContainer>
+
+      <EntityType Name="Employee">
+        <Key>
+          <PropertyRef Name="empid" />
+        </Key>
+        <Property Name="empid" Type="Edm.Int32" Nullable="false" />
+        <Property Name="resume" Type="JSON.JSON" Nullable="true" />
+      </EntityType>
 
       <ComplexType Name="example">
         <Property Name="CodeDictionary" Type="JSON.JSON" Nullable="false">
@@ -22,4 +34,4 @@
 
     </Schema>
   </edmx:DataServices>
-</edmx:Edmx>
+</edmx:Edmx>

vocabularies/Org.OData.JSON.V1.json

@@ -12,7 +12,8 @@
     },
     "Org.OData.JSON.V1": {
         "$Alias": "JSON",
-        "@Core.Description": "Terms for JSON properties",
+        "@Core.Description": "Terms, types, and functions for JSON streams",
+        "@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 convenince [type for JSON streams](#JSON) streams as well as a term for referencing a [JSON Schema](#Schema) describing the structure of the JSON stream. \n\nIn addition it defines two functions for [querying](#query) JSON streams and using a [primitive value](#value) extracted from a JSON stream in common expressions, for example in `$filter`, `$orderby`, or `$compute`.\n\n**Example**\n\nThe `Employees` entity set has a JSON stream 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 stream 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.Links": [
             {
                 "rel": "alternate",
@@ -39,8 +40,64 @@
             ],
             "@Core.RequiresType": "Edm.Stream",
             "@Core.Description": "The JSON Schema for JSON values of the annotated property, parameter, return type, term, or type definition",
-            "@Core.LongDescription": "The schema can be a schema reference, i.e. `{\"$ref\":\"url/of/schemafile#/path/to/schema/within/schemafile\"}`"
+            "@Core.LongDescription": "The schema can be a reference, i.e. `{\"$ref\":\"url/of/schemafile#/path/to/schema/within/schemafile\"}`"
         },
+        "query": [
+            {
+                "$Kind": "Function",
+                "$IsBound": true,
+                "$IsComposable": true,
+                "@Core.Description": "Query a stream value of media type `application/json`, returning a stream value of media type `application/json`",
+                "@Core.LongDescription": "Extracts a JSON value, such as an array, object, or a JSON scalar value (string, number, boolean, or `null`) from the `input` JSON value:\n- If `path` only consists of the root selector followed by member and index selectors, it returns the identified single node within `input`, or `null` if no node is identified. \n- If `path` potentially identifies multiple nodes within `input` (by using descendant, wildcard, union, array subset, or filter selectors), it returns an array containing the identified nodes, or an empty array if no node is identified. \n- If `input` is not a valid JSON value, the function returns `null`.\n- If `path` is `null`, not a valid [JSONPath expression](#Path), or does not match the structure of `input` (for example applying an index selector to a scalar value), the function returns `null`. \n          ",
+                "$Parameter": [
+                    {
+                        "$Name": "input",
+                        "$Type": "JSON.JSON",
+                        "$Nullable": true,
+                        "@Core.Description": "JSON input"
+                    },
+                    {
+                        "$Name": "path",
+                        "$Type": "JSON.Path",
+                        "$Nullable": true,
+                        "@Core.Description": "JSONPath expression to be applied to value of `expr`"
+                    }
+                ],
+                "$ReturnType": {
+                    "$Type": "JSON.JSON",
+                    "$Nullable": true,
+                    "@Core.Description": "JSON value resulting from applying `path` to `input`"
+                }
+            }
+        ],
+        "value": [
+            {
+                "$Kind": "Function",
+                "$IsBound": true,
+                "$IsComposable": true,
+                "@Core.Description": "Query a stream value of media type `application/json`, returning an OData primitive value",
+                "@Core.LongDescription": "Extracts a single OData primitive value from the `input` JSON value:\n- If `path` only consists of the root selector followed by member and index selectors and identifies a single scalar JSON value (string, number, boolean, or `null`) within `input`, it returns the identified single value cast to an OData primitive value (see below).\n- If `path` identifies multiple nodes within `input` (by using descendant, wildcard, union, array subset, or filter selectors), identifies an object or array, or does not identify any node, the function returns `null`.\n- If `input` is not a valid JSON value, the function returns `null`.\n- If `path` is `null`, not a valid [JSONPath expression](#Path), or does not match the structure of `input` (for example applying an index selector to a scalar value), the function returns `null`.\n\nIf a single non-null scalar JSON value is identified by `path` within `input`, the function returns that value as an OData primitive value of type\n- `Edm.String` if the value is a JSON string\n- `Edm.Boolean` if the value is `true` or `false`\n- `Edm.Decimal` with unspecified precision and floating scale if the value is a JSON number\n          ",
+                "$Parameter": [
+                    {
+                        "$Name": "input",
+                        "$Type": "JSON.JSON",
+                        "$Nullable": true,
+                        "@Core.Description": "JSON input"
+                    },
+                    {
+                        "$Name": "path",
+                        "$Type": "JSON.Path",
+                        "$Nullable": true,
+                        "@Core.Description": "JSONPath expression to be applied to value of `expr`"
+                    }
+                ],
+                "$ReturnType": {
+                    "$Type": "Edm.PrimitiveType",
+                    "$Nullable": true,
+                    "@Core.Description": "OData primitive value resulting from applying `path` to `input`"
+                }
+            }
+        ],
         "JSON": {
             "$Kind": "TypeDefinition",
             "$UnderlyingType": "Edm.Stream",
@@ -49,6 +106,12 @@
             "@Core.AcceptableMediaTypes": [
                 "application/json"
             ]
+        },
+        "Path": {
+            "$Kind": "TypeDefinition",
+            "$UnderlyingType": "Edm.String",
+            "@Core.Description": "[JSONPath](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-01) expression",
+            "@Core.LongDescription": "Implementations SHOULD support at least the following subset of JSONPath:\n\nJSONPath | Description | Examples\n---------|-------------|--------\n`$` | Root selector | `$`\n`.` | Member selector | `$.foo`, `$.foo.bar`\n`[]` | Index selector with member name (single- or double-quoted string using JSON escaping rules) or zero-based array index (non-negative base-10 integer) | `$['foo']`, `$.foo[\"bar\"]`, `$.bar[0]`, `$.bar[42]`\n\nImplementations MAY support in addition:\n\nJSONPath | Description | Examples\n---------|-------------|--------\n`[]` | Index selector with negative integer array index (counts from the end of the array) | `$.bar[-1]`\n`..` | Descendant selector: searches for the specified member name recursively and returns an array of all values with this member name | `$..foo`\n`*` | Wildcard selector matching all elements in an object or array | `$.foo.*`, `$.bar[*]`, `$..*`\n`[,]` | Union selector for alternate member names or array indices as a set | `$.foo['bar','baz']`, `$.bar[0,1,2,3,5,7,11]`\n`[start:end]` | Array subset by range of indices (including the item at _start_ and excluding the item at _end_ | `$.bar[2:5]`, same as `$.bar[2,3,4]`\n`[start:]` | Array subset from _start_ to end of array | `$.bar[2:]`\n`[:n]` | The first _n_ array items | `$.bar[:4]`\n`[-n:]` | The last _n_ array items | `$.bar[-3:]`\n`[start:end:step]` | [Array slice selector](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-01#section-3.5.6) |\n`[?()]` | Filter selector | `$.bar[?(@.baz==42)]`\n`()` | Static expression | `$.bar[(@.length-1)]`\n`@` | in expressions: the current node being processed\n\n**References for JSONPath**\n- Current IETF draft: https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base-01\n- Historic site: https://goessner.net/articles/JsonPath/\n- Node.js implementation: https://www.npmjs.com/package/jsonpath\n- Java implementation: https://github.com/json-path/JsonPath\n- Online evaluator: https://jsonpath.com/\n          "
         }
     }
 }