Merge branch '341/expressions-action-payload' of

[email protected]:oasis-tcs/odata-specs.git into
341/expressions-action-payload

docs/odata-json-format/odata-json-format.html

@@ -334,16 +334,21 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/368">368</a></td>
 </tr>
 <tr class="even">
+<td><a href="#ControlInformationidodataid">Section 4.5.8</a></td>
+<td>Transient entities can be identifiable</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/1928">1928</a></td>
+</tr>
+<tr class="odd">
 <td><a href="#ControlInformationmediaodatamedia">Section 4.5.12</a></td>
 <td><code>mediaContentType</code> can be <code>null</code></td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/536">536</a></td>
 </tr>
-<tr class="odd">
+<tr class="even">
 <td><a href="#StructuralProperty">Section 7</a>, <a href="#InformativeReferences">Section A.2</a></td>
 <td>Removed reference to obsolete version of GeoJSON</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/456">456</a></td>
 </tr>
-<tr class="even">
+<tr class="odd">
 <td><a href="#ActionInvocation">Section 18</a></td>
 <td>Allow common expressions in action payloads</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/341">341</a></td>
@@ -684,9 +689,8 @@ <h3 id="458-control-information-id-odataid"><a name="ControlInformationidodataid
 <li>percent-encoding normalization as defined in section 6 of <a href="#rfc3986">RFC3986</a>.</li>
 </ul>
 <p>Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the <code>id</code> MUST be included if it does not match convention for the localized key values. If the <code>id</code> is represented, it MAY be a <a href="#RelativeURLs">relative URL</a>.</p>
-<p>If the entity is transient (see <a href="#ODataProtocol">OData-Protocol</a>), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 payloads transient entities need not have the <code>id</code> control information, and 4.01 clients MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities.</p>
+<p>If the entity is transient (see <a href="#ODataProtocol">OData-Protocol</a>), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 or greater payloads transient entities need not have the <code>id</code> control information, and clients receiving such payloads MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities. In 4.02 payloads transient entities MAY have the <code>id</code> control information with a non-null URI value, for example to allow solving a circular dependency by injecting an <a href="#EntityReference">entity reference</a> instead of repeating the transient entity. The URI value SHOULD follow the pattern <code>odata:transient:{some-generated-identifier-unique-within-the-response}</code>, and if the transient entity cannot be re-read its <code>readLink</code> control information SHOULD have the <code>null</code> value.</p>
 <p>The <code>id</code> control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.</p>
-<p>Entities with <code>id</code> equal to <code>null</code> cannot be compared to other entities, reread, or updated. If <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is specified and the <code>id</code> is not present in the entity, then the canonical URL MUST be used as the entity-id.</p>
 </details>
 <details open><summary>
 <h3 id="459-control-information-editlink-and-readlink-odataeditlink-and-odatareadlink"><a name="ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink" href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.5.9 Control Information: <code>editLink</code> and <code>readLink</code> (<code>odata.editLink</code> and <code>odata.readLink</code>)</a></h3>

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

@@ -216,6 +216,7 @@ An OData JSON payload may represent:
 Section | Feature / Change | Issue
 --------|------------------|------
 [Section 4.5.1](#ControlInformationcontextodatacontext)| Fragment portion of Context URL is not percent-encoded| [368](https://github.com/oasis-tcs/odata-specs/issues/368)
+[Section 4.5.8](#ControlInformationidodataid)| Transient entities can be identifiable| [1928](https://github.com/oasis-tcs/odata-specs/issues/1928)
 [Section 4.5.12](#ControlInformationmediaodatamedia)| `mediaContentType` can be `null`| [536](https://github.com/oasis-tcs/odata-specs/issues/536)
 [Section 7](#StructuralProperty), [Section A.2](#InformativeReferences)| Removed reference to obsolete version of GeoJSON| [456](https://github.com/oasis-tcs/odata-specs/issues/456)
 [Section 18](#ActionInvocation)| Allow common expressions in action payloads| [341](https://github.com/oasis-tcs/odata-specs/issues/341)
@@ -965,21 +966,20 @@ URL](#RelativeURLs).
 
 If the entity is transient (see [OData-Protocol](#ODataProtocol)), the
 `id` control information MUST appear in OData 4.0 payloads
-and have the `null` value. In 4.01 payloads transient
-entities need not have the `id` control information, and 4.01
-clients MUST treat entities with neither `id` control
+and have the `null` value. In 4.01 or greater payloads transient
+entities need not have the `id` control information, and
+clients receiving such payloads MUST treat entities with neither `id` control
 information nor a full set of key properties as transient entities.
+In 4.02 payloads transient entities MAY have the `id` control information with a non-null URI value,
+for example to allow solving a circular dependency by injecting an
+[entity reference](#EntityReference) instead of repeating the transient entity.
+The URI value SHOULD follow the pattern `odata:transient:{some-generated-identifier-unique-within-the-response}`,
+and if the transient entity cannot be re-read its `readLink` control information SHOULD have the `null` value.
 
 The `id` control information MUST NOT appear for a
 collection. Its meaning in this context is reserved for future versions
 of this specification.
 
-Entities with `id` equal to `null` cannot be
-compared to other entities, reread, or updated. If
-[`metadata=minimal`](#metadataminimalodatametadataminimal)
-is specified and the `id` is not present in the entity, then
-the canonical URL MUST be used as the entity-id.
-
 ### <a name="ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink" href="#ControlInformationeditLinkandreadLinkodataeditLinkandodatareadLink">4.5.9 Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`)</a>
 
 The `editLink` control information contains

docs/odata-protocol/odata-protocol.html

@@ -673,7 +673,7 @@ <h2 id="42-read-urls-and-edit-urls"><a name="ReadURLsandEditURLs" href="#ReadURL
 <details open><summary>
 <h2 id="43-transient-entities"><a name="TransientEntities" href="#TransientEntities">4.3 Transient Entities</a></h2>
 </summary>
-<p>Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. They do not possess an entity-id or an update URL and consequently cannot be updated. A transient entity may have a read URL, which generates a new transient entity using the same algorithm.</p>
+<p>Transient entities are instances of an entity type that are dynamically generated on request and only exist within a response payload. They do not possess an update URL and consequently cannot be updated. A transient entity may have a read URL, which generates a new transient entity using the same algorithm, and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference.</p>
 </details>
 <details open><summary>
 <h2 id="44-default-namespaces"><a name="DefaultNamespaces" href="#DefaultNamespaces">4.4 Default Namespaces</a></h2>
@@ -2403,7 +2403,7 @@ <h3 id="1144-upsert-an-entity"><a name="UpsertanEntity" href="#UpsertanEntity">1
 <p>Upserts are not supported against entities whose keys’ values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.</p>
 <p>Similarly, services MUST fail an update request to the URL of a <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entity</a> that does not yet exist. However, a <code>PUT</code> request to the <em>media edit URL</em> of a media entity does have Upsert semantics, in that the media entity is <a href="#CreateaMediaEntity">created</a> with the specified media stream if it does not already exist, otherwise the media stream of the existing media entity is <a href="#UpdateaMediaEntityStream">updated</a>.</p>
 <p>Singleton entities can be upserted if they are nullable. Services supporting this SHOULD advertise it by annotating the singleton with the term <code>Capabilities.UpdateRestrictions</code> (nested property <code>Upsertable</code> with value <code>true</code>) defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
-<p>Key and other non-updatable properties, as well as dependent properties that are not tied to key properties of the principal entity, MUST be ignored by the service in processing the Upsert request.</p>
+<p>A key property whose value is provided in the request URL SHOULD be omitted from the request body. If key properties are provided in the request URL and the request body with different values, services MUST either fail the request or ignore the value in the request body.</p>
 <p>To ensure that an update request is not treated as an insert, the client MAY specify an <a href="#HeaderIfMatch"><code>If-Match</code></a> header in the update request. The service MUST NOT treat an update request containing an <code>If-Match</code> header as an insert.</p>
 <p>A <code>PUT</code> or <code>PATCH</code> request MUST NOT be treated as an update if an <a href="#HeaderIfNoneMatch"><code>If-None-Match</code></a> header is specified with a value of <code>*</code>.</p>
 </details>

docs/odata-protocol/odata-protocol.md

@@ -618,8 +618,9 @@ one or both of them may differ from convention.
 
 Transient entities are instances of an entity type that are
 dynamically generated on request and only exist within a response payload.
-They do not possess an entity-id or an update URL and consequently cannot be updated.
-A transient entity may have a read URL, which generates a new transient entity using the same algorithm.
+They do not possess an update URL and consequently cannot be updated.
+A transient entity may have a read URL, which generates a new transient entity using the same algorithm,
+and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference.
 
 ## <a name="DefaultNamespaces" href="#DefaultNamespaces">4.4 Default Namespaces</a>
 
@@ -4560,9 +4561,9 @@ supporting this SHOULD advertise it by annotating the singleton with the
 term `Capabilities.UpdateRestrictions` (nested property `Upsertable`
 with value `true`) defined in [OData-VocCap](#ODataVocCap).
 
-Key and other non-updatable properties, as well as dependent properties
-that are not tied to key properties of the principal entity, MUST be
-ignored by the service in processing the Upsert request.
+A key property whose value is provided in the request URL SHOULD be omitted from the request body.
+If key properties are provided in the request URL and the request body with different values,
+services MUST either fail the request or ignore the value in the request body.
 
 To ensure that an update request is not treated as an insert, the client
 MAY specify an [`If-Match`](#HeaderIfMatch) header in the update

odata-json-format/1 Introduction.md

@@ -24,6 +24,9 @@ Section | Feature / Change | Issue
 [Section ##ControlInformationcontextodatacontext]| 
 Fragment portion of Context URL is not percent-encoded| 
 [368](https://github.com/oasis-tcs/odata-specs/issues/368)
+[Section ##ControlInformationidodataid]| 
+Transient entities can be identifiable| 
+[1928](https://github.com/oasis-tcs/odata-specs/issues/1928)
 [Section ##ControlInformationmediaodatamedia]| 
 `mediaContentType` can be `null`| 
 [536](https://github.com/oasis-tcs/odata-specs/issues/536)

odata-json-format/4 Common Characteristics.md

@@ -419,21 +419,20 @@ URL](#RelativeURLs).
 
 If the entity is transient (see [OData-Protocol](#ODataProtocol)), the
 `id` control information MUST appear in OData 4.0 payloads
-and have the `null` value. In 4.01 payloads transient
-entities need not have the `id` control information, and 4.01
-clients MUST treat entities with neither `id` control
+and have the `null` value. In 4.01 or greater payloads transient
+entities need not have the `id` control information, and
+clients receiving such payloads MUST treat entities with neither `id` control
 information nor a full set of key properties as transient entities.
+In 4.02 payloads transient entities MAY have the `id` control information with a non-null URI value,
+for example to allow solving a circular dependency by injecting an
+[entity reference](#EntityReference) instead of repeating the transient entity.
+The URI value SHOULD follow the pattern `odata:transient:{some-generated-identifier-unique-within-the-response}`,
+and if the transient entity cannot be re-read its `readLink` control information SHOULD have the `null` value.
 
 The `id` control information MUST NOT appear for a
 collection. Its meaning in this context is reserved for future versions
 of this specification.
 
-Entities with `id` equal to `null` cannot be
-compared to other entities, reread, or updated. If
-[`metadata=minimal`](#metadataminimalodatametadataminimal)
-is specified and the `id` is not present in the entity, then
-the canonical URL MUST be used as the entity-id.
-
 ### ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`)
 
 The `editLink` control information contains

odata-protocol/1 Introduction.md

@@ -301,8 +301,9 @@ one or both of them may differ from convention.
 
 Transient entities are instances of an entity type that are
 dynamically generated on request and only exist within a response payload.
-They do not possess an entity-id or an update URL and consequently cannot be updated.
-A transient entity may have a read URL, which generates a new transient entity using the same algorithm.
+They do not possess an update URL and consequently cannot be updated.
+A transient entity may have a read URL, which generates a new transient entity using the same algorithm,
+and they may have an entity id if a repeated occurrence in a response needs to be replaced with an entity reference.
 
 ## ##subsec Default Namespaces
 

odata-protocol/11.4 Data Modification.md

@@ -577,9 +577,9 @@ supporting this SHOULD advertise it by annotating the singleton with the
 term `Capabilities.UpdateRestrictions` (nested property `Upsertable`
 with value `true`) defined in [OData-VocCap](#ODataVocCap).
 
-Key and other non-updatable properties, as well as dependent properties
-that are not tied to key properties of the principal entity, MUST be
-ignored by the service in processing the Upsert request.
+A key property whose value is provided in the request URL SHOULD be omitted from the request body.
+If key properties are provided in the request URL and the request body with different values,
+services MUST either fail the request or ignore the value in the request body.
 
 To ensure that an update request is not treated as an insert, the client
 MAY specify an [`If-Match`](#HeaderIfMatch) header in the update