-
Type:
Bug
-
Status: Closed
-
Priority:
Major
-
Resolution: No Action
-
Affects Version/s: V4.01_CS01
-
Fix Version/s: V4.01_CS02
-
Component/s: JSON Format, Protocol
-
Labels:None
-
Environment:
Proposed
-
Proposal:
-
Resolution:
In OData 4.0 we explicitly disallowed deep updates (i.e., including related entities in a PUT or PATCH request). We did allow binding (through the @bind annotation).
In OData 4.01 we added the ability to do deep updates, but we are inconsistent with how we describe the behavior.
In the Protocol document we say that the nested content replaces the existing content, removing any related resources not specified in the payload:
11.4.3.1 Update Related Entities When Updating an Entity (Protocol)
…
Payloads with an OData-Version header with a value of 4.01 or greater MAY include nested entities and entity references that specify the full set of currently related entities, or a nested delta payload representing the related entities that have been added, removed, or changed.
If the nested collection is represented identical to an expanded navigation property, then the set of nested entities and entity references specified in a successful update request represents the full set of entities to be related according to that relationship and MUST NOT include added links, deleted links, or deleted entities.
However, this is different than the semantics we describe in section 8.5 of the JSON document (taken from 4.0), which says that the bound items are added, and don't affect the existing relationships:
8.5 Bind Operation (JSON)
…
For update operations a bind operation on a collection navigation property adds additional relationships, it does not replace existing relationships, while bind operations on an entity navigation property update the relationship.
In fact, for a PATCH operation, most people expect that the membership of the collection-valued nav prop is not replaced, but that specified resources are added or updated.
It would probably be more intuitive to say that PATCH updates the service with the references in the payload, and that PUT must be used in order to do the replace semantics, or @delta can be used to remove (or upsert) individual entries.