ODATA-1472 (#141)

docs/odata-protocol/odata-protocol.html

@@ -1794,7 +1794,7 @@ <h4 id="11422-create-related-entities-when-creating-an-entity"><a name="CreateRe
 <h3 id="1143-update-an-entity"><a name="UpdateanEntity" href="#UpdateanEntity">11.4.3 Update an Entity</a></h3>
 <p>To update an individual entity, the client makes a <code>PATCH</code> or <code>PUT</code> request to a URL that identifies the entity. Services MAY restrict updates only to requests addressing the <a href="#ReadURLsandEditURLs">edit URL</a> of the entity.</p>
 <p>Services SHOULD support <code>PATCH</code> as the preferred means of updating an entity. <code>PATCH</code> provides more resiliency between clients and services by directly modifying only those values specified by the client.</p>
-<p>The semantics of <code>PATCH</code>, as defined in <a href="#rfc5789">RFC5789</a>, 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.</p>
+<p>The semantics of <code>PATCH</code>, as defined in <a href="#rfc5789">RFC5789</a>, 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 <code>PATCH</code> semantics recursively, see also <a href="#UpdateaComplexProperty">section 11.4.9.3</a>. 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.</p>
 <p>Services MAY additionally support <code>PUT</code> 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 <code>PUT</code> 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 <code>PUT</code> request results in a <code>400 Bad Request</code> error. Missing dynamic structural properties MUST be removed or set to <code>null</code>.</p>
 <p>For requests with an <code>OData-Version</code> header with a value of <code>4.01</code> 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 <code>$value</code>.</p>
 <p>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.</p>
@@ -1976,8 +1976,9 @@ <h4 id="11492-set-a-value-to-null"><a name="SetaValuetoNull" href="#SetaValuetoN
 <p>Services MUST return an error if the property is not updatable.</p>
 <p><a href="#UpdateaPrimitiveProperty">Updating a primitive property</a> or a <a href="#UpdateaComplexProperty">complex property</a> with a null value also sets the property to null.</p>
 <h4 id="11493-update-a-complex-property"><a name="UpdateaComplexProperty" href="#UpdateaComplexProperty">11.4.9.3 Update a Complex Property</a></h4>
-<p>A successful <code>PATCH</code> 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.</p>
+<p>A successful <code>PATCH</code> 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.</p>
 <p>The service MUST directly modify only those properties of the complex type specified in the payload of the <code>PATCH</code> request.</p>
+<p>If a complex-typed property is set to a different type in a <code>PATCH</code> 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.</p>
 <p>The service MAY additionally support clients sending a <code>PUT</code> 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.</p>
 <p>Upon successful completion the service responds with either <a href="#ResponseCode200OK"><code>200 OK</code></a> or <a href="#ResponseCode204NoContent"><code>204 No Content</code></a>. The client may request that the response SHOULD include a body by specifying a <a href="#Preferencereturnrepresentationandreturnminimal">Prefer header</a> with a value of <a href="#Preferencereturnrepresentationandreturnminimal"><code>return=representation</code></a>.</p>
 <p>Services MUST return an error if the property is not updatable.</p>

docs/odata-protocol/odata-protocol.md

@@ -4262,8 +4262,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.
 
@@ -4824,11 +4826,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 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.
 
+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

odata-protocol/11.4 Data Modification.md

@@ -315,8 +315,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.
 
@@ -877,11 +879,16 @@ 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 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.
 
+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