Merge branch 'main' into 402/key-values-in-upserts-along-navigation-p…

…roperties

docs/odata-json-format/odata-json-format.html

@@ -679,7 +679,7 @@ <h3 id="458-control-information-id-odataid"><a name="ControlInformationidodataid
 <li>percent-encoding normalization as defined in section 6 of <a href="#rfc3986">RFC3986</a>.</li>
 </ul>
 <p>Note that the entity-id MUST be invariant across languages, so if key values are language dependent then the <code>id</code> MUST be included if it does not match convention for the localized key values. If the <code>id</code> is represented, it MAY be a <a href="#RelativeURLs">relative URL</a>.</p>
-<p>If the entity is transient (i.e. cannot be read or updated), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 payloads transient entities need not have the <code>id</code> control information, and 4.01 clients MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities.</p>
+<p>If the entity is transient (see <a href="#ODataProtocol">OData-Protocol</a>), the <code>id</code> control information MUST appear in OData 4.0 payloads and have the <code>null</code> value. In 4.01 payloads transient entities need not have the <code>id</code> control information, and 4.01 clients MUST treat entities with neither <code>id</code> control information nor a full set of key properties as transient entities.</p>
 <p>The <code>id</code> control information MUST NOT appear for a collection. Its meaning in this context is reserved for future versions of this specification.</p>
 <p>Entities with <code>id</code> equal to <code>null</code> cannot be compared to other entities, reread, or updated. If <a href="#metadataminimalodatametadataminimal"><code>metadata=minimal</code></a> is specified and the <code>id</code> is not present in the entity, then the canonical URL MUST be used as the entity-id.</p>
 </details>

docs/odata-json-format/odata-json-format.md

@@ -962,7 +962,7 @@ if it does not match convention for the localized key values. If the
 `id` is represented, it MAY be a [relative
 URL](#RelativeURLs).
 
-If the entity is transient (i.e. cannot be read or updated), the
+If the entity is transient (see [OData-Protocol](#ODataProtocol)), the
 `id` control information MUST appear in OData 4.0 payloads
 and have the `null` value. In 4.01 payloads transient
 entities need not have the `id` control information, and 4.01

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>
@@ -653,7 +658,7 @@ <h1 id="4-service-model"><a name="ServiceModel" href="#ServiceModel">4 Service M
 <h2 id="41-entity-ids-and-entity-references"><a name="EntityIdsandEntityReferences" href="#EntityIdsandEntityReferences">4.1 Entity-Ids and Entity References</a></h2>
 </summary>
 <p>Whereas entities within an entity set are uniquely identified by their key values, entities are also uniquely identified by a durable, opaque, globally unique <em>entity-id</em>. The entity-id MUST be an IRI as defined in <a href="#rfc3987">RFC3987</a> and MAY be expressed in payloads, headers, and URLs as a relative reference as appropriate. While the client MUST be prepared to accept any IRI, services MUST use valid URIs in this version of the specification since there is currently no lossless representation of an IRI in the <a href="#HeaderODataEntityId"><code>EntityId</code></a> header.</p>
-<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <strong>OData-URL</strong> as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs"><code>Core.DereferenceableIDs</code></a> term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource <code>$entity</code> provides a general mechanism for <a href="#ResolvinganEntityId">resolving an entity-id</a> into an entity representation.</p>
+<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="#ODataURL">OData-URL</a> as its entity-id, but clients cannot assume the entity-id can be used to locate the entity unless the <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DereferenceableIDs"><code>Core.DereferenceableIDs</code></a> term is applied to the entity container, nor can the client assume any semantics from the structure of the entity-id. The canonical resource <code>$entity</code> provides a general mechanism for <a href="#ResolvinganEntityId">resolving an entity-id</a> into an entity representation.</p>
 <p>Services that use the standard URL conventions for entity-ids annotate their entity container with the term <a href="https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#ConventionalIDs"><code>Core.ConventionalIDs</code></a>, see <a href="#ODataVocCore">OData-VocCore</a>.</p>
 <p><em>Entity references</em> refer to an entity using the entity’s entity-id.</p>
 </details>
@@ -663,7 +668,7 @@ <h2 id="42-read-urls-and-edit-urls"><a name="ReadURLsandEditURLs" href="#ReadURL
 <p>The read URL of an entity is the URL that can be used to read the entity.</p>
 <p>The edit URL of an entity is the URL that can be used to update or delete the entity.</p>
 <p>The edit URL of a property is the edit URL of the entity with appended segment(s) containing the path to the property.</p>
-<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <strong>OData-URL</strong> for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.</p>
+<p>Services are strongly encouraged to use the canonical URL for an entity as defined in <a href="#ODataURL">OData-URL</a> for both the read URL and the edit URL of an entity, with a cast segment to the type of the entity appended to the canonical URL if the type of the entity is derived from the declared type of the entity set. However, clients cannot assume this convention and must use the links specified in the payload according to the appropriate format as the two URLs may be different from one another, or one or both of them may differ from convention.</p>
 </details>
 <details open><summary>
 <h2 id="43-transient-entities"><a name="TransientEntities" href="#TransientEntities">4.3 Transient Entities</a></h2>
@@ -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>
@@ -2613,7 +2619,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>