Reference example, don't copy it

oasis-tcs · Apr 18, 2024 · 38c4827 · 38c4827
1 parent f232900
commit 38c4827
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 46 deletions.
diff --git a/vocabularies/Org.OData.JSON.V1.json b/vocabularies/Org.OData.JSON.V1.json
@@ -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(path='$.lastname') eq 'Doe'\n      &$orderby=resume/JSON.valueNumber(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.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` (see [CSDL JSON](../examples/Org.OData.JSON.V1.Schema-sample.json) or [CSDL XML](../examples/Org.OData.JSON.V1.Schema-sample.xml)).\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.valueNumber(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",

diff --git a/vocabularies/Org.OData.JSON.V1.md b/vocabularies/Org.OData.JSON.V1.md
@@ -12,19 +12,7 @@ In addition it defines two functions for [querying](#query) JSON data and using
 
 **Example**
 
-The `Employees` entity set has a JSON data property `resume`:
-```json
-"container": {
-  "$Kind": "EntityContainer",
-  "Employees": { "$Collection": true, "$Type": "this.Employee" }
-},
-"Employee": {
-  "$Kind": "EntityType",
-  "$Key": ["empid"],
-  "empid": { "$Type": "Edm.Int32" },
-  "resume": { "$Type": "JSON.JSON", "$Nullable": true }
-}
-```
+The `Employees` entity set has a JSON data property `resume` (see [CSDL JSON](../examples/Org.OData.JSON.V1.Schema-sample.json) or [CSDL XML](../examples/Org.OData.JSON.V1.Schema-sample.xml)).
 
 One of its entities has a `resume` value of
 ```json
@@ -70,13 +58,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#L119:~: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#L127:~:text=<Function%20Name="-,query,-")
 
 Query a stream value of media type `application/json`, returning a stream value of media type `application/json`
 
@@ -89,13 +77,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#L156:~:text=<Function%20Name="-,query,-")|[JSON?](#JSON)|JSON value resulting from applying `path` to `input`
+**[input](./Org.OData.JSON.V1.xml#L137:~:text=<Function%20Name="-,query,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
+[path](./Org.OData.JSON.V1.xml#L140:~:text=<Function%20Name="-,query,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
+[&rarr;](./Org.OData.JSON.V1.xml#L144:~:text=<Function%20Name="-,query,-")|[JSON?](#JSON)|JSON value resulting from applying `path` to `input`
 
 
 <a name="value"></a>
-### [value](./Org.OData.JSON.V1.xml#L162:~:text=<Function%20Name="-,value,-")
+### [value](./Org.OData.JSON.V1.xml#L150:~:text=<Function%20Name="-,value,-")
 
 Query a stream value of media type `application/json`, returning a string
 
@@ -107,13 +95,13 @@ Extracts a single OData primitive value from the `input` JSON value and casts it
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[input](./Org.OData.JSON.V1.xml#L171:~:text=<Function%20Name="-,value,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
-[path](./Org.OData.JSON.V1.xml#L174:~:text=<Function%20Name="-,value,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
-[&rarr;](./Org.OData.JSON.V1.xml#L178:~:text=<Function%20Name="-,value,-")|String?|String value resulting from applying `path` to `input`
+**[input](./Org.OData.JSON.V1.xml#L159:~:text=<Function%20Name="-,value,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
+[path](./Org.OData.JSON.V1.xml#L162:~:text=<Function%20Name="-,value,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
+[&rarr;](./Org.OData.JSON.V1.xml#L166:~:text=<Function%20Name="-,value,-")|String?|String value resulting from applying `path` to `input`
 
 
 <a name="valueNumber"></a>
-### [valueNumber](./Org.OData.JSON.V1.xml#L183:~:text=<Function%20Name="-,valueNumber,-")
+### [valueNumber](./Org.OData.JSON.V1.xml#L171:~:text=<Function%20Name="-,valueNumber,-")
 
 Query a stream value of media type `application/json`, returning a number
 
@@ -122,13 +110,13 @@ Like [`value`](#value), but casts the extracted value to an `Edm.Decimal` with u
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[input](./Org.OData.JSON.V1.xml#L189:~:text=<Function%20Name="-,valueNumber,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
-[path](./Org.OData.JSON.V1.xml#L192:~:text=<Function%20Name="-,valueNumber,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
-[&rarr;](./Org.OData.JSON.V1.xml#L195:~:text=<Function%20Name="-,valueNumber,-")|Decimal?|Numeric value resulting from applying `path` to `input`
+**[input](./Org.OData.JSON.V1.xml#L177:~:text=<Function%20Name="-,valueNumber,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
+[path](./Org.OData.JSON.V1.xml#L180:~:text=<Function%20Name="-,valueNumber,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
+[&rarr;](./Org.OData.JSON.V1.xml#L183:~:text=<Function%20Name="-,valueNumber,-")|Decimal?|Numeric value resulting from applying `path` to `input`
 
 
 <a name="valueBoolean"></a>
-### [valueBoolean](./Org.OData.JSON.V1.xml#L199:~:text=<Function%20Name="-,valueBoolean,-")
+### [valueBoolean](./Org.OData.JSON.V1.xml#L187:~:text=<Function%20Name="-,valueBoolean,-")
 
 Query a stream value of media type `application/json`, returning a Boolean
 
@@ -137,19 +125,19 @@ Like [`value`](#value), but casts the extracted value to an `Edm.Boolean`.
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[input](./Org.OData.JSON.V1.xml#L205:~:text=<Function%20Name="-,valueBoolean,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
-[path](./Org.OData.JSON.V1.xml#L208:~:text=<Function%20Name="-,valueBoolean,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
-[&rarr;](./Org.OData.JSON.V1.xml#L211:~:text=<Function%20Name="-,valueBoolean,-")|Boolean?|Boolean value resulting from applying `path` to `input`
+**[input](./Org.OData.JSON.V1.xml#L193:~:text=<Function%20Name="-,valueBoolean,-")**|[JSON?](#JSON)|**Binding parameter:** JSON input
+[path](./Org.OData.JSON.V1.xml#L196:~:text=<Function%20Name="-,valueBoolean,-")|[Path?](#Path)|JSONPath expression to be applied to value of `expr`
+[&rarr;](./Org.OData.JSON.V1.xml#L199:~:text=<Function%20Name="-,valueBoolean,-")|Boolean?|Boolean value resulting from applying `path` to `input`
 
 
 <a name="JSON"></a>
-## [JSON](./Org.OData.JSON.V1.xml#L216:~:text=<TypeDefinition%20Name="-,JSON,-")
+## [JSON](./Org.OData.JSON.V1.xml#L204:~:text=<TypeDefinition%20Name="-,JSON,-")
 **Type:** Stream
 
 Textual data of media type `application/json`
 
 <a name="Path"></a>
-## [Path](./Org.OData.JSON.V1.xml#L227:~:text=<TypeDefinition%20Name="-,Path,-")
+## [Path](./Org.OData.JSON.V1.xml#L215:~:text=<TypeDefinition%20Name="-,Path,-")
 **Type:** String
 
 [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535) expression

diff --git a/vocabularies/Org.OData.JSON.V1.xml b/vocabularies/Org.OData.JSON.V1.xml
@@ -57,19 +57,7 @@ In addition it defines two functions for [querying](#query) JSON data and using
 
 **Example**
 
-The `Employees` entity set has a JSON data property `resume`:
-```json
-"container": {
-  "$Kind": "EntityContainer",
-  "Employees": { "$Collection": true, "$Type": "this.Employee" }
-},
-"Employee": {
-  "$Kind": "EntityType",
-  "$Key": ["empid"],
-  "empid": { "$Type": "Edm.Int32" },
-  "resume": { "$Type": "JSON.JSON", "$Nullable": true }
-}
-```
+The `Employees` entity set has a JSON data property `resume` (see [CSDL JSON](../examples/Org.OData.JSON.V1.Schema-sample.json) or [CSDL XML](../examples/Org.OData.JSON.V1.Schema-sample.xml)).
 
 One of its entities has a `resume` value of
 ```json