Align if-match * and if-none-match * with RFC9110

oasis-tcs · Sep 5, 2024 · 34c01a2 · 34c01a2
1 parent d598b13
commit 34c01a2
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 16 deletions.
diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html
@@ -926,19 +926,19 @@ <h3 id="823-header-accept-language"><a name="HeaderAcceptLanguage" href="#Header
 <details open><summary>
 <h3 id="824-header-if-match"><a name="HeaderIfMatch" href="#HeaderIfMatch">8.2.4 Header <code>If-Match</code></a></h3>
 </summary>
-<p>As defined in <a href="#rfc9110">RFC9110</a>, a client MAY include an <code>If-Match</code> header in a request to <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code>. The value of the <code>If-Match</code> request header MUST be an ETag value previously retrieved for the resource, or <code>*</code> to match any value.</p>
-<p>If an operation on an existing resource requires an ETag, (see term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency"><code>Core.OptimisticConcurrency</code></a> in <a href="#ODataVocCore">OData-VocCore</a> and property <code>OptimisticConcurrencyControl</code> of type <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#NavigationPropertyRestriction"><code>Capabilities.NavigationPropertyRestriction</code></a> in <a href="#ODataVocCap">OData-VocCap</a>) and the client does not specify an <code>If-Match</code> request header in a <a href="#DataModification">Data Modification Request</a> or in an <a href="#Actions">Action Request</a> invoking an action bound to the resource, the service responds with a <code>428 Precondition Required</code> and MUST ensure that no observable change occurs as a result of the request.</p>
+<p>As defined in <a href="#rfc9110">RFC9110</a>, a client MAY include an <code>If-Match</code> header in a request to <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code>. The value of the <code>If-Match</code> request header MUST be an ETag value previously retrieved for the resource, or <code>*</code>.</p>
+<p>If modification of an existing resource requires an ETag, (see term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency"><code>Core.OptimisticConcurrency</code></a> in <a href="#ODataVocCore">OData-VocCore</a> and property <code>OptimisticConcurrencyControl</code> of type <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#NavigationPropertyRestriction"><code>Capabilities.NavigationPropertyRestriction</code></a> in <a href="#ODataVocCap">OData-VocCap</a>) and the client does not specify an <code>If-Match</code> request header in a <a href="#DataModification">Data Modification Request</a> or in an <a href="#Actions">Action Request</a> invoking an action bound to the resource, the service responds with a <code>428 Precondition Required</code> and MUST ensure that no observable change occurs as a result of the request.</p>
 <p>If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending <a href="#HeaderETag"><code>ETag</code></a> headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from <a href="#rfc9110">RFC9110</a>.</p>
 <p>If the value does not match the current ETag value of the resource for a <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a>, the service MUST respond with <a href="#ResponseCode412PreconditionFailed"><code>412 Precondition Failed</code></a> and MUST ensure that no observable change occurs as a result of the request. In the case of an <a href="#UpsertanEntity">upsert</a>, if the addressed entity does not exist the provided ETag value is considered not to match.</p>
-<p>An <code>If-Match</code> header with a value of <code>*</code> in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an update and not an insert.</p>
+<p>An <code>If-Match</code> header with a value of <code>*</code> matches any current representation of the resource, and in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an <a href="#UpdateanEntity">update</a> and not an <a href="#CreateanEntity">insert</a>, independent of whether the resource requires an ETag.</p>
 <p>The <code>If-Match</code> header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.</p>
 </details>
 <details open><summary>
 <h3 id="825-header-if-none-match"><a name="HeaderIfNoneMatch" href="#HeaderIfNoneMatch">8.2.5 Header <code>If-None-Match</code></a></h3>
 </summary>
 <p>As defined in <a href="#rfc9110">RFC9110</a>, a client MAY include an <code>If-None-Match</code> header in a request to <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>PATCH</code> or <code>DELETE</code>. The value of the <code>If-None-Match</code> request header MUST be an ETag value previously retrieved for the resource, or <code>*</code>.</p>
 <p>If present, the request MUST only be processed if the specified ETag value does not match the current ETag value of the resource, using the weak comparison function (see <a href="#rfc9110">RFC9110</a>). If the value matches the current ETag value of the resource, then for a <code>GET</code> request, the service SHOULD respond with <a href="#ResponseCode304NotModified"><code>304 Not Modified</code></a>, and for a <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a>, the service MUST respond with <a href="#ResponseCode412PreconditionFailed"><code>412 Precondition Failed</code></a> and MUST ensure that no observable change occurs as a result of the request.</p>
-<p>An <code>If-None-Match</code> header with a value of <code>*</code> in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an <a href="#CreateanEntity">insert</a> and not an <a href="#UpdateanEntity">update</a>.</p>
+<p>An <code>If-None-Match</code> header with a value of <code>*</code> “matches” if there is no current representation of the resource, and in a <code>PUT</code> or <code>PATCH</code> request results in an <a href="#UpsertanEntity">upsert request</a> being processed as an <a href="#CreateanEntity">insert</a> and not an <a href="#UpdateanEntity">update</a>, independent of whether the resource requires an ETag.</p>
 <p>The <code>If-None-Match</code> header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.</p>
 </details>
 <details open><summary>

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md
@@ -1061,9 +1061,9 @@ batch request.
 As defined in [RFC9110](#rfc9110), a client MAY include an
 `If-Match` header in a request to `GET`, `POST`, `PUT`, `PATCH` or
 `DELETE`. The value of the `If-Match` request header MUST be an ETag
-value previously retrieved for the resource, or `*` to match any value.
+value previously retrieved for the resource, or `*`.
 
-If an operation on an existing resource requires an ETag, (see term
+If modification of an existing resource requires an ETag, (see term
 [`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in
 [OData-VocCore](#ODataVocCore) and property
 `OptimisticConcurrencyControl` of type
@@ -1090,9 +1090,10 @@ ensure that no observable change occurs as a result of the request. In
 the case of an [upsert](#UpsertanEntity), if the addressed entity does
 not exist the provided ETag value is considered not to match.
 
-An `If-Match` header with a value of `*` in a `PUT` or `PATCH` request
+An `If-Match` header with a value of `*` matches any current representation of the resource, and in a `PUT` or `PATCH` request
 results in an [upsert request](#UpsertanEntity) being processed as an
-update and not an insert.
+[update](#UpdateanEntity) and not an [insert](#CreateanEntity),
+independent of whether the resource requires an ETag.
 
 The `If-Match` header MUST NOT be specified on a batch request, but MAY
 be specified on individual requests within the batch.
@@ -1115,9 +1116,10 @@ the service MUST respond with
 [`412 Precondition Failed`](#ResponseCode412PreconditionFailed) and MUST
 ensure that no observable change occurs as a result of the request.
 
-An `If-None-Match` header with a value of `*` in a `PUT` or `PATCH`
+An `If-None-Match` header with a value of `*` "matches" if there is no current representation of the resource, and in a `PUT` or `PATCH`
 request results in an [upsert request](#UpsertanEntity) being processed
-as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity).
+as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity),
+independent of whether the resource requires an ETag.
 
 The `If-None-Match` header MUST NOT be specified on a batch request, but
 MAY be specified on individual requests within the batch.

diff --git a/odata-protocol/8 Header Fields.md b/odata-protocol/8 Header Fields.md
@@ -164,9 +164,9 @@ batch request.
 As defined in [RFC9110](#rfc9110), a client MAY include an
 `If-Match` header in a request to `GET`, `POST`, `PUT`, `PATCH` or
 `DELETE`. The value of the `If-Match` request header MUST be an ETag
-value previously retrieved for the resource, or `*` to match any value.
+value previously retrieved for the resource, or `*`.
 
-If an operation on an existing resource requires an ETag, (see term
+If modification of an existing resource requires an ETag, (see term
 [`Core.OptimisticConcurrency`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptimisticConcurrency) in
 [OData-VocCore](#ODataVocCore) and property
 `OptimisticConcurrencyControl` of type
@@ -193,9 +193,10 @@ ensure that no observable change occurs as a result of the request. In
 the case of an [upsert](#UpsertanEntity), if the addressed entity does
 not exist the provided ETag value is considered not to match.
 
-An `If-Match` header with a value of `*` in a `PUT` or `PATCH` request
+An `If-Match` header with a value of `*` matches any current representation of the resource, and in a `PUT` or `PATCH` request
 results in an [upsert request](#UpsertanEntity) being processed as an
-update and not an insert.
+[update](#UpdateanEntity) and not an [insert](#CreateanEntity),
+independent of whether the resource requires an ETag.
 
 The `If-Match` header MUST NOT be specified on a batch request, but MAY
 be specified on individual requests within the batch.
@@ -218,9 +219,10 @@ the service MUST respond with
 [`412 Precondition Failed`](#ResponseCode412PreconditionFailed) and MUST
 ensure that no observable change occurs as a result of the request.
 
-An `If-None-Match` header with a value of `*` in a `PUT` or `PATCH`
+An `If-None-Match` header with a value of `*` "matches" if there is no current representation of the resource, and in a `PUT` or `PATCH`
 request results in an [upsert request](#UpsertanEntity) being processed
-as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity).
+as an [insert](#CreateanEntity) and not an [update](#UpdateanEntity),
+independent of whether the resource requires an ETag.
 
 The `If-None-Match` header MUST NOT be specified on a batch request, but
 MAY be specified on individual requests within the batch.