Merge branch 'main' into json-format/transient-entities

docs/odata-protocol/odata-protocol.html

@@ -508,31 +508,36 @@ <h2 id="11-changes-from-earlier-versions"><a name="ChangesfromEarlierVersions" h
 </thead>
 <tbody>
 <tr class="odd">
+<td><a href="#Preferencecontinueonerrorodatacontinueonerror">Section 8.2.8.3</a></td>
+<td>Responses that include errors MUST include the Preference-Applied header <code>with continue-on-error</code> set to <code>true</code></td>
+<td><a href="https://github.com/oasis-tcs/odata-specs/issues/1965">1965</a></td>
+</tr>
+<tr class="even">
 <td><a href="#CollectionofEntities">Section 10.2</a></td>
 <td>Context URLs use parentheses-style keys without percent-encoding</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/368">368</a></td>
 </tr>
-<tr class="even">
+<tr class="odd">
 <td><a href="#DataModification">Section 11.4</a></td>
 <td>Response code <code>204 No Content</code> after successful data modification if requested response could not be constructed</td>
 <td><a href="https://github.com/oasis-tcs/odata-specs/issues/443">443</a></td>
 </tr>
-<tr class="odd">
+<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://github.com/oasis-tcs/odata-specs/issues/455">455</a></td>
 </tr>
-<tr class="even">
+<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="#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="even">
+<tr class="odd">
 <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>
@@ -937,6 +942,7 @@ <h4 id="8283-preference-continue-on-error-odatacontinue-on-error"><a name="Prefe
 </summary>
 <p>The <code>continue-on-error</code> preference on a <a href="#BatchRequests">batch request</a> is used to request whether, upon encountering a request within the batch that returns an error, the service return the error for that request and continue processing additional requests within the batch (if specified with an implicit or explicit value of <code>true</code>), or rather stop further processing (if specified with an explicit value of <code>false</code>). The syntax of the <code>continue-on-error</code> preference is defined in <a href="#ODataABNF">OData-ABNF</a>.</p>
 <p>The <code>continue-on-error</code> preference can also be used on a <a href="#UpdateaCollectionofEntities">delta update</a>, <a href="#UpdateMembersofaCollection">set-based update</a>, or <a href="#DeleteMembersofaCollection">set-based delete</a> to request that the service continue attempting to process changes after receiving an error.</p>
+<p>If the service encounters any errors processing the request and returns a successful response code, then it MUST include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> response header containing the <code>continue-on-error</code> preference with an explicit value of <code>true</code>.</p>
 <p>A service MAY specify support for the <code>continue-on-error</code> preference using an annotation with term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchContinueOnErrorSupported"><code>Capabilities.BatchContinueOnErrorSupported</code></a>, see <a href="#ODataVocCap">OData-VocCap</a>.</p>
 <p>The <code>continue-on-error</code> preference SHOULD NOT be applied to individual requests within a batch.</p>
 <p>Note: The <code>continue-on-error</code> preference was named <code>odata.continue-on-error</code> in OData version 4.0. Services that support the<code> continue-on-error</code> preference SHOULD also support <code>odata.continue-on-error</code> for OData 4.0 clients and clients SHOULD use <code>odata.continue-on-error</code> for compatibility with OData 4.0 services.</p>
@@ -1060,7 +1066,7 @@ <h3 id="831-header-asyncresult"><a name="HeaderAsyncResult" href="#HeaderAsyncRe
 <h3 id="832-header-etag"><a name="HeaderETag" href="#HeaderETag">8.3.2 Header <code>ETag</code></a></h3>
 </summary>
 <p>A response MAY include an <code>ETag</code> header, see <a href="#rfc9110">RFC9110</a>. Services MUST include this header if they require an ETag to be specified when modifying the resource.</p>
-<p>Services MUST support specifying the value returned in the <code>ETag</code> header in an <a href="#HeaderIfNoneMatch"><code>If-None-Match</code></a> header of a subsequent <a href="#RequestingData">Data Request</a> for the resource. Clients MUST specify the value returned in the <code>ETag</code> header, or star (<code>*</code>), in an <a href="#HeaderIfMatch"><code>If-Match</code></a> header of a subsequent <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a> in order to apply <a href="#UseofETagsforAvoidingUpdateConflicts">optimistic concurrency</a> control in updating, deleting, or invoking an action bound to the resource.</p>
+<p>Services MUST support specifying the value returned in the <code>ETag</code> header in an <a href="#HeaderIfNoneMatch"><code>If-None-Match</code></a> header of a subsequent <a href="#RequestingData">Data Request</a> for the resource. Clients MUST specify the value returned in the <code>ETag</code> header, or star (<code>*</code>), in an <a href="#HeaderIfMatch"><code>If-Match</code></a> header of a subsequent <a href="#DataModification">Data Modification Request</a> or <a href="#Actions">Action Request</a> in order to apply <a href="#UseofETagsforAvoidingUpdateConflicts">optimistic concurrency control</a> in updating, deleting, or invoking an action bound to the resource.</p>
 <p>As OData allows multiple formats for representing the same structured information, services SHOULD use weak ETags that only depend on the representation-independent entity state. A strong ETag MUST change whenever the representation of an entity changes, so it has to depend on the <a href="#HeaderContentType"><code>Content-Type</code></a>, the <a href="#HeaderContentEncoding"><code>Content-Encoding</code></a>, and potentially other characteristics of the response.</p>
 <p>An <code>ETag</code> header MAY also be returned on a <a href="#MetadataDocumentRequest">metadata document request</a> or <a href="#ServiceDocumentRequest">service document request</a> to allow the client subsequently to make a conditional request for the metadata or service document. Clients can also compare the value of the <code>ETag</code> header returned from a metadata document request to the metadata ETag returned in a response in order to verify the version of the metadata used to generate that response.</p>
 <p>The <code>ETag</code> header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.</p>
@@ -2595,7 +2601,7 @@ <h3 id="11412-update-a-collection-of-entities"><a name="UpdateaCollectionofEntit
 <p>Clients MAY associate an id with individual nested entities in the request by using the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> term defined in <a href="#ODataVocCore">OData-VocCore</a>. Services that respond with <a href="#ResponseCode200OK"><code>200 OK</code></a> SHOULD annotate the entities in the response using the same <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> value as specified in the request.</p>
 <p>Services SHOULD advertise support for updating a collection using a delta payload through the <code>DeltaUpdateSupported</code> property of the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#UpdateRestrictionsType"><code>Capabilities.UpdateRestrictions</code></a> term, and SHOULD advertise support for returning the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ContentID"><code>Core.ContentID</code></a> through the <code>ContentIDSupported</code> property of the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepUpdateSupportType"><code>Capabilities.DeepUpdateSupport</code></a> term, both defined in <a href="#ODataVocCap">OData-VocCap</a>.</p>
 <p>The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes.</p>
-<p>If the <a href="#Preferencecontinueonerrorodatacontinueonerror"><code>continue-on-error</code></a> preference has been specified and any errors occur in processing the changes, then a delta response MUST be returned regardless of the <a href="#Preferencereturnrepresentationandreturnminimal"><code>return</code></a> preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows:</p>
+<p>If the client requests <code>continue-on-error</code> behavior and the service encounters any errors while processing the request, then it MUST either fail the entire request without applying any changes or include a <a href="#HeaderPreferenceApplied"><code>Preference-Applied</code></a> header in the response indicating that the <a href="#Preferencecontinueonerrorodatacontinueonerror"><code>continue-on-error</code></a> preference has been applied. In this case, the delta response payload MUST be returned regardless of the <a href="#Preferencereturnrepresentationandreturnminimal"><code>return</code></a> preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows:</p>
 <ul>
 <li>Failed deletes in the request MUST be represented in the response as either entities or entity references, annotated with the term <code>Core.DataModificationException</code>, see <a href="#ODataVocCore">OData-VocCore</a>. If the deleted entity specified a reason of <code>deleted</code>, the value of <code>failedOperation</code> MUST be <code>delete</code>, otherwise <code>unlink</code>.</li>
 <li>Failed inserts within the request MUST be represented in the response as deleted entities annotated with the term <code>Core.DataModificationException</code> with a <code>failedOperation</code> value of <code>insert</code>.</li>

docs/odata-protocol/odata-protocol.md

@@ -351,6 +351,7 @@ resource representations that are exchanged using OData.
 
 Section | Feature / Change | Issue
 --------|------------------|------
+[Section 8.2.8.3](#Preferencecontinueonerrorodatacontinueonerror) | Responses that include errors MUST include the Preference-Applied header `with continue-on-error` set to `true` | [1965](https://github.com/oasis-tcs/odata-specs/issues/1965)
 [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.4](#UpsertanEntity)| Upserts to single-valued non-containment navigation properties| [455](https://github.com/oasis-tcs/odata-specs/issues/455)
@@ -1328,6 +1329,8 @@ The `continue-on-error` preference can also be used on a
 [set-based delete](#DeleteMembersofaCollection) to request that the service
 continue attempting to process changes after receiving an error.
 
+If the service encounters any errors processing the request and returns a successful response code, then it MUST include a [`Preference-Applied`](#HeaderPreferenceApplied) response header containing the `continue-on-error` preference with an explicit value of `true`.
+
 A service MAY specify support for the `continue-on-error` preference
 using an annotation with term
 [`Capabilities.BatchContinueOnErrorSupported`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#BatchContinueOnErrorSupported),
@@ -1667,8 +1670,8 @@ Request](#RequestingData) for the resource. Clients MUST specify the
 value returned in the `ETag` header, or star (`*`), in an
 [`If-Match`](#HeaderIfMatch) header of a subsequent [Data Modification
 Request](#DataModification) or [Action Request](#Actions) in order to
-apply [optimistic concurrency](#UseofETagsforAvoidingUpdateConflicts)
-control in updating, deleting, or invoking an action bound to the
+apply [optimistic concurrency control](#UseofETagsforAvoidingUpdateConflicts)
+in updating, deleting, or invoking an action bound to the
 resource.
 
 As OData allows multiple formats for representing the same structured
@@ -5018,8 +5021,7 @@ term, both defined in [OData-VocCap](#ODataVocCap).
 The response, if requested, is a delta payload, in the same structure
 and order as the request payload, representing the applied changes.
 
-If the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference has been specified and any errors
-occur in processing the changes, then a delta response MUST be returned
+If the client requests `continue-on-error` behavior and the service encounters any errors while processing the request, then it MUST either fail the entire request without applying any changes or include a [`Preference-Applied`](#HeaderPreferenceApplied)  header in the response indicating that the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference has been applied. In this case, the delta response payload MUST be returned
 regardless of the [`return`](#Preferencereturnrepresentationandreturnminimal)
 preference and MUST contain at least the failed changes. The service
 represents failed changes in the delta response as follows: