ContentID references in actions

docs/odata-json-format/odata-json-format.md

@@ -3483,6 +3483,55 @@ Content-Length: ###
 ```
 :::
 
+::: example
+Example 59: Given a sales quotation with items for coffee, sugar and paper,
+invoke an action to create a sales order for sugar and paper
+and add a 10% discount for the sugar.
+
+```json
+POST /service/$batch HTTP/1.1
+Host: host
+OData-Version: 4.01
+Content-Type: application/json
+Content-Length: ###
+
+{
+  "requests": [
+    {
+      "id": "1",
+      "method": "post",
+      "url": "/service/SalesQuotation(68)/self.CreateSalesOrder",
+      "headers": {
+        "accept": "application/json"
+      },
+      "body": {
+        "Items": [
+          {"Product": "Sugar", "@Core.ContentID": "I1"},
+          {"Product": "Paper"}
+        ]
+      }
+    },
+    {
+      "id": "2",
+      "dependsOn": [ "1" ],
+      "method": "post",
+      "url": "$I1/Discounts",
+      "headers": {
+        "accept": "application/json"
+      },
+      "body": {
+        "Percent": 10,
+        "Reason": "voucher"
+      }
+    }
+  ]
+}
+```
+
+In the response to the action invocation the sales order item for the sugar is annotated
+with `"@Core.ContentID": "I1"`. The POST request can reference this item without knowing its key.
+:::
+
 ## <a name="ProcessingaBatchRequest" href="#ProcessingaBatchRequest">19.5 Processing a Batch Request</a>
 
 All requests in an atomicity group represent a single change unit. A
@@ -3577,7 +3626,7 @@ request. Especially: URLs in responses MUST NOT contain
 `$`-prefixed request identifiers.
 
 ::: example
-Example 59: referencing the batch request [example 55](#batchRequest) above, assume all
+Example 60: referencing the batch request [example 55](#batchRequest) above, assume all
 the requests except the final query request succeed. In this case the
 response would be
 ```json
@@ -3635,7 +3684,7 @@ to the next link MAY result in a `202 Accepted` response with a
 `location` header pointing to a new status monitor resource.
 
 ::: example
-Example 60: referencing the [example 55](#batchRequest) above again, assume that the
+Example 61: referencing the [example 55](#batchRequest) above again, assume that the
 request is sent with the `respond-async` preference. This
 results in a `202` response pointing to a status monitor resource:
 ```json
@@ -3725,7 +3774,7 @@ asynchronously executed individual request with a `status` of
 individual status monitor resource, and optionally a `retry-after` header.
 
 ::: example
-Example 61: the first individual request is processed asynchronously,
+Example 62: the first individual request is processed asynchronously,
 the second synchronously, the batch itself is processed synchronously
 ```json
 HTTP/1.1 200 OK
@@ -3788,7 +3837,7 @@ the annotations for the value appear next to the `value`
 property and are not prefixed with a property name.
 
 ::: example
-Example 62:
+Example 63:
 ```json
 {
   "@context": "http://host/service/$metadata#Customers",
@@ -3898,7 +3947,7 @@ Error responses MAY contain [annotations](#InstanceAnnotations) in
 any of its JSON objects.
 
 ::: example
-Example 63:
+Example 64:
 ```json
 {
   "error": {
@@ -3947,7 +3996,7 @@ header-appropriate way:
   [RFC8259](#rfc8259), section 7)
 
 ::: example
-Example 64: note that this is one HTTP header line without any line
+Example 65: note that this is one HTTP header line without any line
 breaks or optional whitespace
 ```json
 OData-error: {"code":"err123","message":"Unsupported

docs/odata-protocol/odata-protocol.html

@@ -2913,7 +2913,7 @@ <h3 id="1175-referencing-the-etag-of-an-entity"><a name="ReferencingtheETagofanE
 <details open><summary>
 <h3 id="1176-referencing-values-from-response-bodies"><a name="ReferencingValuesfromResponseBodies" href="#ReferencingValuesfromResponseBodies">11.7.6 Referencing Values from Response Bodies</a></h3>
 </summary>
-<p>Services MAY support using values from a response body in the query part of the URL or in the request body of subsequent requests. A value reference can consist of a <code>$</code> character followed by the identifier of the preceding request, then the referenced value is the value represented by the response body of that preceding request. Alternatively, a value reference can consist of a <code>$</code> character followed by the value of an instance annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> (see <a href="#ODataVocCore">OData-VocCore</a>) that occurs in the payload of the preceding request as described in <a href="#CreateRelatedEntitiesWhenCreatinganEntity">section 11.4.2.2</a> and <a href="#UpdateRelatedEntitiesWhenUpdatinganEntity">section 11.4.3.1</a>, then the referenced value is the corresponding value in the response, which the service SHOULD annotate with the same <code>Core.ContentID</code> value.</p>
+<p>Services MAY support using values from a response body in the query part of the URL or in the request body of subsequent requests. A value reference can consist of a <code>$</code> character followed by the identifier of the preceding request, then the referenced value is the value represented by the response body of that preceding request. Alternatively, a value reference can consist of a <code>$</code> character followed by the value of an instance annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> (see <a href="#ODataVocCore">OData-VocCore</a>) that occurs in the payload of the preceding request as described in <a href="#CreateRelatedEntitiesWhenCreatinganEntity">section 11.4.2.2</a> and <a href="#UpdateRelatedEntitiesWhenUpdatinganEntity">section 11.4.3.1</a> or in a preceding action payload as in the example in <a href="#ODataJSON">OData-JSON, section 19.4</a>, then the referenced value is the corresponding value in the response, which the service SHOULD annotate with the same <code>Core.ContentID</code> value.</p>
 <p>In both cases, if the referenced value is a collection, the value reference MAY be followed by a <code>collectionNavigationExpr</code>, as defined in <a href="#ODataABNF">OData-ABNF</a>, that is evaluated relative to the referenced value. Otherwise the value reference MAY be followed by a forward slash and a <code>memberExpr</code> that is evaluated relative to the referenced value.</p>
 <p>If the <code>$</code>-prefixed identifier is identical to the name of a predefined literal for query expressions (<code>$it</code>, <code>$root</code>, or other literals defined according to the <a href="#HeaderODataVersion"><code>OData-Version</code></a> of the protocol specified in the request), then the predefined literal is used. This collision can be avoided by e.g. using only numeric identifiers.</p>
 </details>

docs/odata-protocol/odata-protocol.md

@@ -5873,7 +5873,8 @@ reference can consist of a `$` character followed by the value of an instance an
 [`Core.ContentID`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID)
 (see [OData-VocCore](#ODataVocCore)) that occurs in the payload of the preceding request
 as described in [section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) and
-[section 11.4.3.1](#UpdateRelatedEntitiesWhenUpdatinganEntity),
+[section 11.4.3.1](#UpdateRelatedEntitiesWhenUpdatinganEntity) or in a preceding action payload
+as in the example in [OData-JSON, section 19.4](#ODataJSON),
 then the referenced value is the corresponding value in the response,
 which the service SHOULD annotate with the same `Core.ContentID` value.
 

odata-json-format/19 Batch Requests and Responses.md

@@ -303,6 +303,55 @@ Content-Length: ###
 ```
 :::
 
+::: example
+Example ##ex: Given a sales quotation with items for coffee, sugar and paper,
+invoke an action to create a sales order for sugar and paper
+and add a 10% discount for the sugar.
+
+```json
+POST /service/$batch HTTP/1.1
+Host: host
+OData-Version: 4.01
+Content-Type: application/json
+Content-Length: ###
+
+{
+  "requests": [
+    {
+      "id": "1",
+      "method": "post",
+      "url": "/service/SalesQuotation(68)/self.CreateSalesOrder",
+      "headers": {
+        "accept": "application/json"
+      },
+      "body": {
+        "Items": [
+          {"Product": "Sugar", "@Core.ContentID": "I1"},
+          {"Product": "Paper"}
+        ]
+      }
+    },
+    {
+      "id": "2",
+      "dependsOn": [ "1" ],
+      "method": "post",
+      "url": "$I1/Discounts",
+      "headers": {
+        "accept": "application/json"
+      },
+      "body": {
+        "Percent": 10,
+        "Reason": "voucher"
+      }
+    }
+  ]
+}
+```
+
+In the response to the action invocation the sales order item for the sugar is annotated
+with `"@Core.ContentID": "I1"`. The POST request can reference this item without knowing its key.
+:::
+
 ## ##subsec Processing a Batch Request
 
 All requests in an atomicity group represent a single change unit. A

odata-protocol/11.7 Batch Requests.md

@@ -151,7 +151,8 @@ reference can consist of a `$` character followed by the value of an instance an
 [`Core.ContentID`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID)
 (see [OData-VocCore](#ODataVocCore)) that occurs in the payload of the preceding request
 as described in [section ##CreateRelatedEntitiesWhenCreatinganEntity] and
-[section ##UpdateRelatedEntitiesWhenUpdatinganEntity],
+[section ##UpdateRelatedEntitiesWhenUpdatinganEntity] or in a preceding action payload
+as in the example in [OData-JSON, section 19.4](#ODataJSON),
 then the referenced value is the corresponding value in the response,
 which the service SHOULD annotate with the same `Core.ContentID` value.