From 0e77d05e81110508bd87846062b7219a1bcff7c2 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 18 Aug 2023 10:59:21 +0200 Subject: [PATCH 1/2] ODATA-1472 --- docs/odata-protocol/odata-protocol.html | 5 +++-- docs/odata-protocol/odata-protocol.md | 12 +++++++++--- odata-protocol/11.4 Data Modification.md | 14 +++++++++++--- 3 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index efb0fe964..3d1eb4a9f 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -1788,7 +1788,7 @@

To update an individual entity, the client makes a PATCH or PUT request to a URL that identifies the entity. Services MAY restrict updates only to requests addressing the edit URL of the entity.

Services SHOULD support PATCH as the preferred means of updating an entity. PATCH provides more resiliency between clients and services by directly modifying only those values specified by the client.

-

The semantics of PATCH, as defined in RFC5789, is to merge the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of the corresponding property in the entity or complex type. Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties.

+

The semantics of PATCH, as defined in RFC5789, is to merge the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of the corresponding property in the entity or complex type. Complex properties are updated by applying PATCH semantics recursively, see also section 11.4.9.3. Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties.

Services MAY additionally support PUT but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance, such as open or added properties, or properties not specified in metadata. Services that support PUT MUST replace all values of structural properties with those specified in the request body. Missing non-key, updatable structural properties not defined as dependent properties within a referential constraint MUST be set to their default values. Omitting a non-nullable property with no service-generated or default value from a PUT request results in a 400 Bad Request error. Missing dynamic structural properties MUST be removed or set to null.

For requests with an OData-Version header with a value of 4.01 or greater, the media stream of a media entity can be updated by specifying the base64url-encoded representation of the media stream as a virtual property $value.

Updating a dependent property that is tied to a key property of the principal entity through a referential constraint updates the relationship to point to the entity with the specified key value. If there is no such entity, the update fails.

@@ -1945,8 +1945,9 @@

Updating a primitive property or a complex property with a null value also sets the property to null.

11.4.9.3 Update a Complex Property

-

A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the target complex type.

+

A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the target complex type or one of its derived types.

The service MUST directly modify only those properties of the complex type specified in the payload of the PATCH request.

+

A complex-typed property can be set to different type in a PATCH request by specifying a different type in the update payload. Properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.

The service MAY additionally support clients sending a PUT request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the request body and set all unspecified properties to their default value.

Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

Services MUST return an error if the property is not updatable.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index a21c32f45..d408b7910 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -4237,8 +4237,10 @@ the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of -the corresponding property in the entity or complex type. Missing -properties of the containing entity or complex property, including +the corresponding property in the entity or complex type. +Complex properties are updated by applying `PATCH` semantics recursively, +see also [section 11.4.9.3](#UpdateaComplexProperty). +Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties. @@ -4755,11 +4757,15 @@ property to null. A successful `PATCH` request to the edit URL for a complex typed property updates that property. The request body MUST contain a single -valid representation for the target complex type. +valid representation for the target complex type or one of its derived types. The service MUST directly modify only those properties of the complex type specified in the payload of the `PATCH` request. +A complex-typed property can be set to different type in a `PATCH` request by specifying a different type in the update payload. +Properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). +Other properties of the original type are discarded. + The service MAY additionally support clients sending a `PUT` request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index c08b936db..6771e8092 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -313,8 +313,10 @@ the content in the request payload with the entity's current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of -the corresponding property in the entity or complex type. Missing -properties of the containing entity or complex property, including +the corresponding property in the entity or complex type. +Complex properties are updated by applying `PATCH` semantics recursively, +see also [section ##UpdateaComplexProperty]. +Missing properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties. @@ -831,11 +833,17 @@ property to null. A successful `PATCH` request to the edit URL for a complex typed property updates that property. The request body MUST contain a single -valid representation for the target complex type. +valid representation for the target complex type or one of its derived types. The service MUST directly modify only those properties of the complex type specified in the payload of the `PATCH` request. +A complex-typed property can be set to different type in a `PATCH` request +by specifying a different type in the update payload. +Properties shared through inheritance, as well as dynamic properties, +are retained (unless overwritten by new values in the payload). +Other properties of the original type are discarded. + The service MAY additionally support clients sending a `PUT` request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the From 6e178d12abe10b7cdd8b7ee4e080d3dac0c10bf4 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 25 Oct 2023 18:40:38 +0200 Subject: [PATCH 2/2] Rephrased --- docs/odata-protocol/odata-protocol.html | 4 ++-- docs/odata-protocol/odata-protocol.md | 6 +++--- odata-protocol/11.4 Data Modification.md | 7 +++---- 3 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index 872224e5f..2d92c379b 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -1945,9 +1945,9 @@

Updating a primitive property or a complex property with a null value also sets the property to null.

11.4.9.3 Update a Complex Property

-

A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the target complex type or one of its derived types.

+

A successful PATCH request to the edit URL for a complex typed property updates that property. The request body MUST contain a single valid representation for the declared type of the complex property or one of its derived types.

The service MUST directly modify only those properties of the complex type specified in the payload of the PATCH request.

-

A complex-typed property can be set to different type in a PATCH request by specifying a different type in the update payload. Properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.

+

If a complex-typed property is set to a different type in a PATCH request, properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.

The service MAY additionally support clients sending a PUT request to a URL that specifies a complex type. In this case, the service MUST replace the entire complex property with the values specified in the request body and set all unspecified properties to their default value.

Upon successful completion the service responds with either 200 OK or 204 No Content. The client may request that the response SHOULD include a body by specifying a Prefer header with a value of return=representation.

Services MUST return an error if the property is not updatable.

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index d1c224326..38e8c16a1 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -4762,13 +4762,13 @@ property to null. A successful `PATCH` request to the edit URL for a complex typed property updates that property. The request body MUST contain a single -valid representation for the target complex type or one of its derived types. +valid representation for the declared type of the complex property or one of its derived types. The service MUST directly modify only those properties of the complex type specified in the payload of the `PATCH` request. -A complex-typed property can be set to different type in a `PATCH` request by specifying a different type in the update payload. -Properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). +If a complex-typed property is set to a different type in a `PATCH` request, +properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded. The service MAY additionally support clients sending a `PUT` request to diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index de8789f54..52f2f81bf 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -833,14 +833,13 @@ property to null. A successful `PATCH` request to the edit URL for a complex typed property updates that property. The request body MUST contain a single -valid representation for the target complex type or one of its derived types. +valid representation for the declared type of the complex property or one of its derived types. The service MUST directly modify only those properties of the complex type specified in the payload of the `PATCH` request. -A complex-typed property can be set to different type in a `PATCH` request -by specifying a different type in the update payload. -Properties shared through inheritance, as well as dynamic properties, +If a complex-typed property is set to a different type in a `PATCH` request, +properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.