Fixes #2021

oasis-tcs · Nov 28, 2024 · 196f42d · 196f42d
1 parent ff14732
commit 196f42d
Show file tree

Hide file tree

Showing 7 changed files with 26 additions and 11 deletions.
diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html
@@ -778,7 +778,7 @@ <h3 id="469-control-information-editlink-and-readlink-odataeditlink-and-odatarea
 <h3 id="4610-control-information-etag-odataetag"><a id="ControlInformationetagodataetag" href="#ControlInformationetagodataetag">4.6.10 Control Information: <code>etag</code> (<code>odata.etag</code>)</a></h3>
 </summary>
 <p>The <code>etag</code> control information MAY be applied to an <a href="#Entity">entity</a> or collection in a response. The value of the control information is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity or collection has changed.</p>
-<p>For details on how ETags are used, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts">OData-Protocol, section 11.4.1.1</a>.</p>
+<p>For details on how ETags are used, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts">OData-Protocol, section 11.4.1.1</a>. The special value <code>"@etag": ""</code> has the same meaning as the header <code>If-None-Match: *</code>, see <a href="https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpsertanEntity">OData-Protocol, section 11.4.4</a>.</p>
 <p>The <code>etag</code> control information is ignored in request payloads for single entities and not written in responses if <a href="#metadatanoneodatametadatanone"><code>metadata=none</code></a> is requested.</p>
 </details>
 <details open><summary>

diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
@@ -1047,6 +1047,8 @@ opaque string value that can be used in a subsequent request to
 determine if the value of the entity or collection has changed.
 
 For details on how ETags are used, see [OData-Protocol, section 11.4.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UseofETagsforAvoidingUpdateConflicts).
+The special value `"@etag": ""` has the same meaning as the header `If-None-Match: *`,
+see [OData-Protocol, section 11.4.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#UpsertanEntity).
 
 The `etag` control information is ignored in request payloads for
 single entities and not written in responses if

diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
@@ -584,9 +584,9 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/356">356</a></td>
 </tr>
 <tr class="odd">
-<td>Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request</td>
+<td><a href="#CreateRelatedEntitiesWhenCreatinganEntity">Section 11.4.2.2</a></td>
+<td>Deep-insert response includes at least the properties present in the request</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/363">363</a></td>
-<td></td>
 </tr>
 <tr class="even">
 <td><a href="#UpdateanEntity">Section 11.4.3</a></td>
@@ -599,21 +599,26 @@ <h2 id="11-changes-from-earlier-versions"><a id="ChangesfromEarlierVersions" hre
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/455">455</a></td>
 </tr>
 <tr class="even">
+<td><a href="#UpsertanEntity">Section 11.4.4</a></td>
+<td>Empty <code>@etag</code> to prevent inserts</td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/2021">2021</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://github.com/oasis-tcs/odata-specs/issues/534">534</a></td>
 </tr>
-<tr class="odd">
+<tr class="even">
 <td><a href="#ReplaceaCollectionofEntities">Section 11.4.13</a></td>
 <td>Semantics of <code>continue-on-error</code> when replacing a collection of entities</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/358">358</a></td>
 </tr>
-<tr class="even">
+<tr class="odd">
 <td><a href="#Conformance">Section 12</a></td>
 <td>Allow <code>400 Bad Request</code> in addition to <code>501 Not Implemented</code> for unsupported functionality</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/391">391</a></td>
 </tr>
-<tr class="odd">
+<tr class="even">
 <td><a href="#InteroperableODataClients">Section 12.3</a></td>
 <td>Encoding of plus character in URLs</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/485">485</a></td>
@@ -2563,7 +2568,7 @@ <h3 id="1144-upsert-an-entity"><a id="UpsertanEntity" href="#UpsertanEntity">11.
 <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>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>
+<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> or the <code>@etag</code> control information <a href="https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationetagodataetag">OData-JSON, section 4.6.10</a> is specified with an empty string as value.</p>
 </details>
 <details open><summary>
 <h3 id="1145-delete-an-entity"><a id="DeleteanEntity" href="#DeleteanEntity">11.4.5 Delete an Entity</a></h3>

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
@@ -358,9 +358,10 @@ Section | Feature / Change | Issue
 [Section 10.2](#CollectionofEntities)| Context URLs use parentheses-style keys without percent-encoding| [368](https://github.com/oasis-tcs/odata-specs/issues/368)
 [Section 11.4](#DataModification)| Response code `204 No Content` after successful data modification if requested response could not be constructed| [443](https://github.com/oasis-tcs/odata-specs/issues/443)
 [Section 11.4.2](#CreateanEntity)| Services can validate non-insertable property values in insert payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
-|Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity) Deep-insert response includes at least the properties present in the request| [363](https://github.com/oasis-tcs/odata-specs/issues/363)
+[Section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity)| Deep-insert response includes at least the properties present in the request| [363](https://github.com/oasis-tcs/odata-specs/issues/363)
 [Section 11.4.3](#UpdateanEntity)| Services can validate non-updatable property values in update payloads| [356](https://github.com/oasis-tcs/odata-specs/issues/356)
 [Section 11.4.4](#UpsertanEntity)| Upserts to single-valued non-containment navigation properties| [455](https://github.com/oasis-tcs/odata-specs/issues/455)
+[Section 11.4.4](#UpsertanEntity)| Empty `@etag` to prevent inserts| [2021](https://github.com/oasis-tcs/odata-specs/issues/2021)
 [Section 11.4.9.3](#UpdateaComplexProperty)| Setting a complex property to a different type| [534](https://github.com/oasis-tcs/odata-specs/issues/534)
 [Section 11.4.13](#ReplaceaCollectionofEntities)| Semantics of `continue-on-error` when replacing a collection of entities | [358](https://github.com/oasis-tcs/odata-specs/issues/358)
 [Section 12](#Conformance) | Allow `400 Bad Request` in addition to `501 Not Implemented` for unsupported functionality| [391](https://github.com/oasis-tcs/odata-specs/issues/391)
@@ -4711,7 +4712,8 @@ request. The service MUST NOT treat an update request containing an
 
 A `PUT` or `PATCH` request MUST NOT be treated as an update if an
 [`If-None-Match`](#HeaderIfNoneMatch) header is specified with a value
-of `*`.
+of `*` or the `@etag` control information [OData-JSON, section 4.6.10](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationetagodataetag)
+is specified with an empty string as value.
 
 ### <a id="DeleteanEntity" href="#DeleteanEntity">11.4.5 Delete an Entity</a>
 

diff --git a/odata-json-format/4 Common Characteristics.md b/odata-json-format/4 Common Characteristics.md
@@ -499,6 +499,8 @@ opaque string value that can be used in a subsequent request to
 determine if the value of the entity or collection has changed.
 
 For details on how ETags are used, see [#OData-Protocol#UseofETagsforAvoidingUpdateConflicts].
+The special value `"@etag": ""` has the same meaning as the header `If-None-Match: *`,
+see [#OData-Protocol#UpsertanEntity].
 
 The `etag` control information is ignored in request payloads for
 single entities and not written in responses if

diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md
@@ -36,7 +36,7 @@ Response code `204 No Content` after successful data modification if requested r
 [Section ##CreateanEntity]| 
 Services can validate non-insertable property values in insert payloads| 
 [356](https://github.com/oasis-tcs/odata-specs/issues/356)
-|Section ##CreateRelatedEntitiesWhenCreatinganEntity] 
+[Section ##CreateRelatedEntitiesWhenCreatinganEntity]| 
 Deep-insert response includes at least the properties present in the request| 
 [363](https://github.com/oasis-tcs/odata-specs/issues/363)
 [Section ##UpdateanEntity]| 
@@ -45,6 +45,9 @@ Services can validate non-updatable property values in update payloads|
 [Section ##UpsertanEntity]| 
 Upserts to single-valued non-containment navigation properties| 
 [455](https://github.com/oasis-tcs/odata-specs/issues/455)
+[Section ##UpsertanEntity]| 
+Empty `@etag` to prevent inserts| 
+[2021](https://github.com/oasis-tcs/odata-specs/issues/2021)
 [Section ##UpdateaComplexProperty]| 
 Setting a complex property to a different type| 
 [534](https://github.com/oasis-tcs/odata-specs/issues/534)

diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md
@@ -696,7 +696,8 @@ request. The service MUST NOT treat an update request containing an
 
 A `PUT` or `PATCH` request MUST NOT be treated as an update if an
 [`If-None-Match`](#HeaderIfNoneMatch) header is specified with a value
-of `*`.
+of `*` or the `@etag` control information [#OData-JSON#ControlInformationetagodataetag]
+is specified with an empty string as value.
 
 ### ##subsubsec Delete an Entity