ODATA-1588 (#176)

Fixes https://issues.oasis-open.org/browse/ODATA-1588
oasis-tcs · Jan 17, 2024 · 4f9bd05 · 4f9bd05
1 parent 790a10e
commit 4f9bd05
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 8 deletions.
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
@@ -498,6 +498,11 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1609">ODATA-1609</a></td>
 </tr>
 <tr class="even">
+<td><a href="#UpsertanEntity">Section 11.4.4</a></td>
+<td>Upserts to single-valued non-containment navigation properties</td>
+<td><a href="https://issues.oasis-open.org/browse/ODATA-1588">ODATA-1588</a></td>
+</tr>
+<tr class="odd">
 <td><a href="#UpdateaComplexProperty">Section 11.4.9.3</a></td>
 <td>Setting a complex property to a different type</td>
 <td><a href="https://issues.oasis-open.org/browse/ODATA-1472">ODATA-1472</a></td>
@@ -1896,7 +1901,13 @@ <h4 id="11431-update-related-entities-when-updating-an-entity"><a name="UpdateRe
 <p>On failure, the service MUST NOT apply any of the changes specified in the request.</p>
 <h3 id="1144-upsert-an-entity"><a name="UpsertanEntity" href="#UpsertanEntity">11.4.4 Upsert an Entity</a></h3>
 <p>An upsert occurs when the client sends an <a href="#UpdateanEntity">update request</a> to a valid URL that identifies a single entity that does not yet exist. In this case the service MUST handle the request as a <a href="#CreateanEntity">create entity request</a> or fail the request altogether.</p>
-<p>Upserts are not supported against <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entities</a>, single-valued non-containment navigation properties, or 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>Upserts to single-valued navigation properties are possible for</p>
+<ul>
+<li>containment navigation properties,</li>
+<li>non-containment navigation properties with a navigation property binding, or</li>
+<li>payloads including a context URL specifying the entity set or contained collection of entities in which the new entity is to be created.</li>
+</ul>
+<p>Upserts are not supported against <a href="#RequestingtheMediaStreamofaMediaEntityusingvalue">media entities</a> or 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>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>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>

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
@@ -347,6 +347,7 @@ resource representations that are exchanged using OData.
 Section | Feature / Change | Issue
 --------|------------------|------
 [Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)
+[Section 11.4.4](#UpsertanEntity)|  Upserts to single-valued non-containment navigation properties| [ODATA-1588](https://issues.oasis-open.org/browse/ODATA-1588)
 [Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [ODATA-1472](https://issues.oasis-open.org/browse/ODATA-1472)
 
 ## <a name="Glossary" href="#Glossary">1.2 Glossary</a>
@@ -4521,11 +4522,16 @@ that does not yet exist. In this case the service MUST handle the
 request as a [create entity request](#CreateanEntity) or fail the
 request altogether.
 
+Upserts to single-valued navigation properties are possible for
+- containment navigation properties,
+- non-containment navigation properties with a navigation property binding, or
+- payloads including a context URL specifying the entity set or
+  contained collection of entities in which the new entity is to be created.
+
 Upserts are not supported against [media
-entities](#RequestingtheMediaStreamofaMediaEntityusingvalue), single-valued
-non-containment navigation properties, or 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.
+entities](#RequestingtheMediaStreamofaMediaEntityusingvalue)
+or 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.
 
 Singleton entities can be upserted if they are nullable. Services
 supporting this SHOULD advertise it by annotating the singleton with the

diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md
@@ -29,6 +29,9 @@ Section | Feature / Change | Issue
 [Section ##DataModification]| 
 Response code `204 No Content` after successful data modification if requested response could not be constructed| 
 [ODATA-1609](https://issues.oasis-open.org/browse/ODATA-1609)
+[Section ##UpsertanEntity]| 
+ Upserts to single-valued non-containment navigation properties| 
+[ODATA-1588](https://issues.oasis-open.org/browse/ODATA-1588)
 [Section ##UpdateaComplexProperty]| 
 Setting a complex property to a different type| 
 [ODATA-1472](https://issues.oasis-open.org/browse/ODATA-1472)

diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md
@@ -544,10 +544,16 @@ that does not yet exist. In this case the service MUST handle the
 request as a [create entity request](#CreateanEntity) or fail the
 request altogether.
 
+Upserts to single-valued navigation properties are possible for
+- containment navigation properties,
+- non-containment navigation properties with a navigation property binding, or
+- payloads including a context URL specifying the entity set or
+  contained collection of entities in which the new entity is to be created.
+
 Upserts are not supported against [media
-entities](#RequestingtheMediaStreamofaMediaEntityusingvalue), single-valued
-non-containment navigation properties, or entities whose keys values are
-generated by the service. Services MUST fail an update request to a URL
+entities](#RequestingtheMediaStreamofaMediaEntityusingvalue)
+or 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.
 
 Singleton entities can be upserted if they are nullable. Services