diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 00a4e289..29e0dc08 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -1392,6 +1392,7 @@

ETags.

Entities include control information for selected navigation links based on metadata.

diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 16590717..648d0d9e 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -2212,6 +2212,8 @@ collection. Changed entities MUST include all available selected properties that have changed, and MAY include additional properties. +Added or changed entities MAY include [ETags](#ControlInformationetagodataetag). + Entities include control information for selected navigation links based on [`metadata`](#ControllingtheAmountofControlInformationinResponses). diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 444a9395..5e6281da 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -407,9 +407,16 @@

Table of Contents

  • 11.4.10 Managing Members of an Ordered Collection
  • 11.4.11 Positional Inserts
    • -
  • 11.4.12 Update a Collection of Entities
    • -
  • 11.4.13 Update Members of a Collection
    • -
  • 11.4.14 Delete Members of a Collection
    • +
  • 11.4.12 Update a Collection of Entities +
    • +
  • 11.4.13 Replace a Collection of Entities +
    • +
  • 11.4.14 Update Members of a Collection
    • +
  • 11.4.15 Delete Members of a Collection
  • 11.5 Operations

    • A delta payload represents changes to a known state. A delta payload includes added entities, changed entities, and deleted entities, as well as a representation of added and removed relationships.

    +

    Services that support the use of ETags for optimistic concurrency control SHOULD return ETag values for added or changed entities within the delta payload.

    Delta payloads can be requested from the service using a delta link or provided as updates to the service.

    @@ -2600,22 +2613,45 @@

    upserts, and deleted entities as deletions. Non-key properties of deleted entities are ignored. The top-level collection may include added and deleted links, and related entities represented inline are updated according to the rules for treating related entities when updating an entity.

    Clients MAY associate an id with individual nested entities in the request by using the Core.ContentID term defined in OData-VocCore. Services that respond with 200 OK SHOULD annotate the entities in the response using the same Core.ContentID value as specified in the request.

    Services SHOULD advertise support for updating a collection using a delta payload through the DeltaUpdateSupported property of the Capabilities.UpdateRestrictions term, and SHOULD advertise support for returning the Core.ContentID through the ContentIDSupported property of the Capabilities.DeepUpdateSupport term, both defined in OData-VocCap.

    +

    For each entity being updated or removed, clients MAY specify an ETag value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated or removed, or if an ETag is provided when adding or updating an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead report a 412 Precondition Failed error. The special value * can be used to match any existing entity but fail if the entity does not already exist.

    The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes.

    -

    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 header in the response indicating that the continue-on-error preference has been applied. In this case, the delta response payload MUST be returned regardless of the return preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows:

    +
    +

    11.4.12.1 Error Handling when Updating a Collection of Entities

    +     +

    If the continue-on-error preference has not been applied, and the service is unable to apply all of the changes in the request, then it MUST return an error response and MUST NOT apply any of the changes specified in the request payload.

    +

    If the continue-on-error preference has been applied and any errors occur in processing the changes, then a delta response MUST be returned regardless of the return preference and MUST contain at least the failed changes. The service represents failed changes in the delta response as follows:

    If an individual change fails due to a failed dependency, it MUST be annotated with the term Core.DataModificationException and SHOULD specify a responseCode of 424 (Failed Dependency).

    -

    Alternatively, the verb PUT can be used, in which case the request body MUST be the representation of a collection of entities. In this case all entities provided in the request are applied as upserts, and any entities not provided in the request are deleted. In this case, if the continue-on-error preference has been specified, and the request returns a success response code, then a response MUST be returned regardless of the return preference, and MUST contain the full membership and values of the collection as it exists in the service.

    -

    If the continue-on-error preference has not been specified, and the service is unable to apply all of the changes in the request, then it MUST return an error response and MUST NOT apply any of the changes specified in the request payload.

    +
    + +
    +

    11.4.13 Replace a Collection of Entities

    +     +

    Collections of entities can be replaced by submitting a PUT request to the resource path of the collection. The body of the request MUST be the representation of the complete collection of replacement entities. In this case all entities provided in the request are applied as upserts, and any entities not provided in the request are deleted.

    +

    For each entity being updated, clients MAY specify an ETag value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated, or if an ETag is provided for an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead report a 412 Precondition Failed. The special ETag value * can be used to match any existing entity but fail if the entity does not already exist.

    +
    +

    11.4.13.1 Error Handling when Replacing a Collection of Entities

    +     +

    If the continue-on-error preference has not been applied, and the service is unable to apply all of the changes in the request, then it MUST return an error response and MUST NOT apply any of the changes specified in the request payload.

    +

    If the continue-on-error preference has been applied and any errors occur in processing the changes, then a response MUST be returned regardless of the return preference, and MUST contain the full membership and values of the collection as it exists in the service, as follows:

    +
      +
    • Entities missing in the request that cannot be removed from the collection MUST be represented in the response as either entities or entity references, and SHOULD be annotated with the term Core.DataModificationException, see OData-VocCore. If the target collection is an entity set or containment navigation property, then the value of failedOperation MUST be delete, otherwise unlink.
      • +
    • Failed inserts within the request MUST NOT be represented in the response.
      • +
    • Failed updates within the request MUST be represented in the response with their current values and SHOULD be annotated with the term Core.DataModificationException with a failedOperation value of update.
      • +
    • Collections within the request MUST also be represented in the response following these same rules.
      • +
    +
    -

    11.4.13 Update Members of a Collection

    +

    11.4.14 Update Members of a Collection

    Members of a collection can be updated by submitting a PATCH request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the request body describes an update to each member of the collection, not an update to the collection itself.

    The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL.

    @@ -2636,7 +2672,7 @@

    11.4.14 Delete Members of a Collection

    +

    11.4.15 Delete Members of a Collection

    Members of a collection can be deleted by submitting a DELETE request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.

    The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.

    @@ -3375,7 +3411,7 @@

    section 11.4.9.1) or complex (section 11.4.9.3) property (respectively)
  • SHOULD support DELETE to set an individual property to null (section 11.4.9.2)
  • SHOULD support deep inserts (section 11.4.2.2)
    • -
  • MAY support set-based updates (section 11.4.13) or deletes (section 11.4.14) to members of a collection
    • +
  • MAY support set-based updates (section 11.4.14) or deletes (section 11.4.15) to members of a collection

    • diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index b71610bf..6508021e 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -272,8 +272,11 @@ For complete copyright information please see the full Notices section in an App - [11.4.10 Managing Members of an Ordered Collection](#ManagingMembersofanOrderedCollection) - [11.4.11 Positional Inserts](#PositionalInserts) - [11.4.12 Update a Collection of Entities](#UpdateaCollectionofEntities) - - [11.4.13 Update Members of a Collection](#UpdateMembersofaCollection) - - [11.4.14 Delete Members of a Collection](#DeleteMembersofaCollection) + - [11.4.12.1 Error Handling when Updating a Collection of Entities](#ErrorHandlingwhenUpdatingaCollectionofEntities) + - [11.4.13 Replace a Collection of Entities](#ReplaceaCollectionofEntities) + - [11.4.13.1 Error Handling when Replacing a Collection of Entities](#ErrorHandlingwhenReplacingaCollectionofEntities) + - [11.4.14 Update Members of a Collection](#UpdateMembersofaCollection) + - [11.4.15 Delete Members of a Collection](#DeleteMembersofaCollection) - [11.5 Operations](#Operations) - [11.5.1 Binding an Operation to a Resource](#BindinganOperationtoaResource) - [11.5.2 Applying an Operation to Members of a Collection](#ApplyinganOperationtoMembersofaCollection) @@ -356,6 +359,7 @@ Section | Feature / Change | Issue [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) [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) [Section 12.3](#InteroperableODataClients) | Encoding of plus character in URLs | [485](https://github.com/oasis-tcs/odata-specs/issues/485) @@ -3989,6 +3993,8 @@ A delta payload represents changes to a known state. A delta payload includes added entities, changed entities, and deleted entities, as well as a representation of added and removed relationships. +Services that support the use of [ETags](#UseofETagsforAvoidingUpdateConflicts) for optimistic concurrency control SHOULD return ETag values for added or changed entities within the delta payload. + Delta payloads can be [requested](#RequestingChanges) from the service using a delta link or provided as updates to the service. @@ -5019,60 +5025,74 @@ through the `ContentIDSupported` property of the [`Capabilities.DeepUpdateSupport`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepUpdateSupportType) term, both defined in [OData-VocCap](#ODataVocCap). +For each entity being updated or removed, clients MAY specify an [ETag](#UseofETagsforAvoidingUpdateConflicts) value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated or removed, or if an ETag is provided when adding or updating an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead [report](#ErrorHandlingwhenUpdatingaCollectionofEntities) a `412 Precondition Failed` error. The special value `*` can be used to match any existing entity but fail if the entity does not already exist. + The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes. -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 +#### 11.4.12.1 Error Handling when Updating a Collection of Entities + +If the `continue-on-error` preference has not been applied, and the +service is unable to apply all of the changes in the request, then it +MUST return an error response and MUST NOT apply any of the changes +specified in the request payload. + +If the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference has been applied and any errors occur in processing the changes, then a delta response 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: -- Failed deletes in the request MUST be -represented in the response as either entities or entity references, -annotated with the term `Core.DataModificationException`, see +- Failed deletes in the request MUST be represented in the response as either entities or entity references, annotated with the term `Core.DataModificationException`, see [OData-VocCore](#ODataVocCore). If the deleted entity specified a reason -of `deleted`, the value of `failedOperation` MUST be `delete`, otherwise -`unlink`. +of `deleted`, or the target collection is an entity set or containment navigation property, +then the value of `failedOperation` MUST be `delete`, otherwise `unlink`. - Failed inserts within the request MUST be represented in the response as deleted entities annotated with the term `Core.DataModificationException` with a `failedOperation` value of `insert`. -- Failed updates within the request SHOULD -be annotated in the response with the term `Core.DataModificationException` -with a `failedOperation` value of `update`. -- Failed added links within the request -MUST represented in the response as deleted links annotated with the term -`Core.DataModificationException` with a `failedOperation` value of -`link`. -- Failed deleted links within the request -MUST represented in the response as added links annotated with the term -`Core.DataModificationException` with a `failedOperation` value of -`unlink`. -- Collections within the request MUST be -represented in the response as a collection with the current values and -membership of the collection as it exists in the service after -processing the request. +- Failed updates within the request SHOULD be annotated in the response with the term `Core.DataModificationException` with a `failedOperation` value of `update`. +- Failed added links within the request MUST be represented in the response as deleted links annotated with the term `Core.DataModificationException` with a `failedOperation` value of `link`. +- Failed deleted links within the request MUST be represented in the response as added links annotated with the term `Core.DataModificationException` with a `failedOperation` value of `unlink`. +- Delta collections within the request are returned as delta collections in the response, according to these same rules. +- Collections within the request are represented as collections in the response according to the rules specified in [Replace a Collection of Entities](#ErrorHandlingwhenReplacingaCollectionofEntities). If an individual change fails due to a failed dependency, it MUST be annotated with the term [`Core.DataModificationException`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DataModificationException) and SHOULD specify a `responseCode` of `424` ([Failed Dependency](#ResponseCode424FailedDependency)). -Alternatively, the verb `PUT` can be used, in which case the request -body MUST be the representation of a collection of entities. In this +### 11.4.13 Replace a Collection of Entities + +Collections of entities can be replaced by submitting a `PUT` request +to the resource path of the collection. The body of the request MUST be +the representation of the complete collection of replacement entities. In this case all entities provided in the request are applied as [upserts](#UpsertanEntity), and any entities not provided in the request -are deleted. In this case, if the `continue-on-error` preference has -been specified, and the request returns a success response code, then a -response MUST be returned regardless of the -[`return`](#Preferencereturnrepresentationandreturnminimal) preference, and MUST -contain the full membership and values of the collection as it exists in -the service. +are deleted. -If the `continue-on-error` preference has not been specified, and the +For each entity being updated, clients MAY specify an [ETag](#UseofETagsforAvoidingUpdateConflicts) +value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated, or if an ETag is provided for an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead [report](#ErrorHandlingwhenReplacingaCollectionofEntities) + a `412 Precondition Failed`. The special ETag value `*` can be used to match any existing entity but fail if the entity does not already exist. + +#### 11.4.13.1 Error Handling when Replacing a Collection of Entities + +If the `continue-on-error` preference has not been applied, and the service is unable to apply all of the changes in the request, then it MUST return an error response and MUST NOT apply any of the changes specified in the request payload. -### 11.4.13 Update Members of a Collection +If the `continue-on-error` preference has been applied and any errors occur in processing the changes, then a response MUST be returned regardless of the +[`return`](#Preferencereturnrepresentationandreturnminimal) preference, and MUST +contain the full membership and values of the collection as it exists in +the service, as follows: +- Entities missing in the request that cannot be removed from the collection MUST be represented in the response as either entities or entity references, +and SHOULD be annotated with the term `Core.DataModificationException`, see +[OData-VocCore](#ODataVocCore). If the target collection is an entity set or containment navigation property, then the value of `failedOperation` MUST be `delete`, otherwise `unlink`. +- Failed inserts within the request MUST NOT be represented in the response. +- Failed updates within the request MUST be represented in the response with +their current values and SHOULD be annotated with the term `Core.DataModificationException` +with a `failedOperation` value of `update`. +- Collections within the request MUST also be represented in the response following these same rules. + +### 11.4.14 Update Members of a Collection Members of a collection can be updated by submitting a `PATCH` request to the URL constructed by appending `/$each` to the resource path of the @@ -5129,7 +5149,7 @@ service is unable to update all of the members identified by the request, then it MUST return an error response and MUST NOT apply any updates. -### 11.4.14 Delete Members of a Collection +### 11.4.15 Delete Members of a Collection Members of a collection can be deleted by submitting a `DELETE` request to the URL constructed by appending `/$each` to the resource path of the @@ -6553,8 +6573,8 @@ or upsert operation that returns `204 No Content` ([section 8.3.4](#HeaderODataE 31. SHOULD support `DELETE` to set an individual property to null ([section 11.4.9.2](#SetaValuetoNull)) 32. SHOULD support deep inserts ([section 11.4.2.2](#CreateRelatedEntitiesWhenCreatinganEntity)) -33. MAY support set-based updates ([section 11.4.13](#UpdateMembersofaCollection)) or deletes -([section 11.4.14](#DeleteMembersofaCollection)) to members of a collection +33. MAY support set-based updates ([section 11.4.14](#UpdateMembersofaCollection)) or deletes +([section 11.4.15](#DeleteMembersofaCollection)) to members of a collection ### 12.1.2 OData 4.0 Intermediate Conformance Level diff --git a/odata-json-format/15 Delta Payload.md b/odata-json-format/15 Delta Payload.md index 28670b6b..339682b5 100644 --- a/odata-json-format/15 Delta Payload.md +++ b/odata-json-format/15 Delta Payload.md @@ -128,6 +128,8 @@ collection. Changed entities MUST include all available selected properties that have changed, and MAY include additional properties. +Added or changed entities MAY include [ETags](#ControlInformationetagodataetag). + Entities include control information for selected navigation links based on [`metadata`](#ControllingtheAmountofControlInformationinResponses). diff --git a/odata-protocol/1 Introduction.md b/odata-protocol/1 Introduction.md index 97b8f2d7..69541b92 100644 --- a/odata-protocol/1 Introduction.md +++ b/odata-protocol/1 Introduction.md @@ -39,6 +39,7 @@ Upserts to single-valued non-containment navigation properties| [Section ##UpdateaComplexProperty]| Setting a complex property to a different type| [534](https://github.com/oasis-tcs/odata-specs/issues/534) +[Section ##ReplaceaCollectionofEntities]| Semantics of `continue-on-error` when replacing a collection of entities | [358](https://github.com/oasis-tcs/odata-specs/issues/358) [Section ##Conformance] | Allow `400 Bad Request` in addition to `501 Not Implemented` for unsupported functionality| [391](https://github.com/oasis-tcs/odata-specs/issues/391) [Section ##InteroperableODataClients] | Encoding of plus character in URLs | [485](https://github.com/oasis-tcs/odata-specs/issues/485) diff --git a/odata-protocol/11 Data Service Requests.md b/odata-protocol/11 Data Service Requests.md index d3e1ae1e..a447ab8e 100644 --- a/odata-protocol/11 Data Service Requests.md +++ b/odata-protocol/11 Data Service Requests.md @@ -1434,5 +1434,9 @@ A delta payload represents changes to a known state. A delta payload includes added entities, changed entities, and deleted entities, as well as a representation of added and removed relationships. +Services that support the use of [ETags](#UseofETagsforAvoidingUpdateConflicts) +for optimistic concurrency control SHOULD return ETag values for added or changed entities +within the delta payload. + Delta payloads can be [requested](#RequestingChanges) from the service using a delta link or provided as updates to the service. diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 25ff840c..ce0b7739 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -1040,59 +1040,96 @@ through the `ContentIDSupported` property of the [`Capabilities.DeepUpdateSupport`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Capabilities.V1.md#DeepUpdateSupportType) term, both defined in [OData-VocCap](#ODataVocCap). +For each entity being updated or removed, clients MAY specify an [ETag](#UseofETagsforAvoidingUpdateConflicts) value obtained from a previous request. +If an ETag is provided that does not match the ETag value of the entity being updated or removed, +or if an ETag is provided when adding or updating an entity that does not currently exist, +then services that support ETags MUST NOT apply the change and instead +[report](#ErrorHandlingwhenUpdatingaCollectionofEntities) a `412 Precondition Failed` error. +The special value `*` can be used to match any existing entity but fail if the entity does not already exist. + The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes. -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 +#### ##subsubsubsec Error Handling when Updating a Collection of Entities + +If the `continue-on-error` preference has not been applied, and the +service is unable to apply all of the changes in the request, then it +MUST return an error response and MUST NOT apply any of the changes +specified in the request payload. + +If the [`continue-on-error`](#Preferencecontinueonerrorodatacontinueonerror) preference +has been applied and any errors occur in processing the changes, then a delta response 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: -- Failed deletes in the request MUST be -represented in the response as either entities or entity references, -annotated with the term `Core.DataModificationException`, see +- Failed deletes in the request MUST be represented in the response as either entities +or entity references, annotated with the term `Core.DataModificationException`, see [OData-VocCore](#ODataVocCore). If the deleted entity specified a reason -of `deleted`, the value of `failedOperation` MUST be `delete`, otherwise -`unlink`. +of `deleted`, or the target collection is an entity set or containment navigation property, +then the value of `failedOperation` MUST be `delete`, otherwise `unlink`. - Failed inserts within the request MUST be represented in the response as deleted entities annotated with the term `Core.DataModificationException` with a `failedOperation` value of `insert`. -- Failed updates within the request SHOULD -be annotated in the response with the term `Core.DataModificationException` -with a `failedOperation` value of `update`. -- Failed added links within the request -MUST represented in the response as deleted links annotated with the term -`Core.DataModificationException` with a `failedOperation` value of -`link`. -- Failed deleted links within the request -MUST represented in the response as added links annotated with the term -`Core.DataModificationException` with a `failedOperation` value of -`unlink`. -- Collections within the request MUST be -represented in the response as a collection with the current values and -membership of the collection as it exists in the service after -processing the request. +- Failed updates within the request SHOULD be annotated in the response with +the term `Core.DataModificationException` with a `failedOperation` value of `update`. +- Failed added links within the request MUST be represented in the response as +deleted links annotated with the term `Core.DataModificationException` +with a `failedOperation` value of `link`. +- Failed deleted links within the request MUST be represented in the response as +added links annotated with the term `Core.DataModificationException` +with a `failedOperation` value of `unlink`. +- Delta collections within the request are returned as delta collections in the +response, according to these same rules. +- Collections within the request are represented as collections in the response +according to the rules specified in [Replace a Collection of Entities](#ErrorHandlingwhenReplacingaCollectionofEntities). If an individual change fails due to a failed dependency, it MUST be annotated with the term [`Core.DataModificationException`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#DataModificationException) and SHOULD specify a `responseCode` of `424` ([Failed Dependency](#ResponseCode424FailedDependency)). -Alternatively, the verb `PUT` can be used, in which case the request -body MUST be the representation of a collection of entities. In this +### ##subsubsec Replace a Collection of Entities + +Collections of entities can be replaced by submitting a `PUT` request +to the resource path of the collection. The body of the request MUST be +the representation of the complete collection of replacement entities. In this case all entities provided in the request are applied as [upserts](#UpsertanEntity), and any entities not provided in the request -are deleted. In this case, if the `continue-on-error` preference has -been specified, and the request returns a success response code, then a -response MUST be returned regardless of the -[`return`](#Preferencereturnrepresentationandreturnminimal) preference, and MUST -contain the full membership and values of the collection as it exists in -the service. +are deleted. -If the `continue-on-error` preference has not been specified, and the +For each entity being updated, clients MAY specify an [ETag](#UseofETagsforAvoidingUpdateConflicts) +value obtained from a previous request. If an ETag is provided that does not match the ETag +value of the entity being updated, or if an ETag is provided for an entity that does not +currently exist, then services that support ETags MUST NOT apply the +change and instead [report](#ErrorHandlingwhenReplacingaCollectionofEntities) + a `412 Precondition Failed`. The special ETag value `*` can be used to match any existing entity + but fail if the entity does not already exist. + +#### ##subsubsubsec Error Handling when Replacing a Collection of Entities + +If the `continue-on-error` preference has not been applied, and the service is unable to apply all of the changes in the request, then it MUST return an error response and MUST NOT apply any of the changes specified in the request payload. +If the `continue-on-error` preference has been applied and any errors occur +in processing the changes, then a response MUST be returned regardless of the +[`return`](#Preferencereturnrepresentationandreturnminimal) preference, and MUST +contain the full membership and values of the collection as it exists in +the service, as follows: +- Entities missing in the request that cannot be removed from the collection +MUST be represented in the response as either entities or entity references, +and SHOULD be annotated with the term `Core.DataModificationException`, see +[OData-VocCore](#ODataVocCore). If the target collection is an entity set or +containment navigation property, then the value of `failedOperation` MUST be +`delete`, otherwise `unlink`. +- Failed inserts within the request MUST NOT be represented in the response. +- Failed updates within the request MUST be represented in the response with +their current values and SHOULD be annotated with the term `Core.DataModificationException` +with a `failedOperation` value of `update`. +- Collections within the request MUST also be represented in the response +following these same rules. + ### ##subsubsec Update Members of a Collection Members of a collection can be updated by submitting a `PATCH` request