Clarify key values in upsert along navigation properties (#1924)

- [x] Fixes #402

---------

Co-authored-by: Heiko Theißen <[email protected]>

docs/odata-protocol/odata-protocol.html

@@ -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

@@ -4561,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-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