Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-666

Define Deep Update and Deep Upsert operations

    XMLWordPrintable

    Details

    • Proposal:
      Hide

      ODATA-613 defines semantics for PATCH to a collection of entities can take a delta payload (assumed delta format if an array).

      In addition:
      1) We deprecate @odata.bind in PATCH, PUT, POST
      a. Clients should instead use @odata.id for insert & link to existing elements
      i. i.e., instead of “property@odata.bind”:”...”, use “property”:

      {“@odata.id”:”url…”}

      ii. Allow entity references in deep insert to add/update reference to existing
      b. To be OData compliant, services need to support @odata.bind for OData-Version: 4.0
      i. OData-Version: 4.01 payloads must not use @odata.bind
      ii. NOTE: to be compliant with OData, you MUST support 4.0 clients

      2) In OData-Version 4.01 payloads, services that support conditional updates MUST pay attention to @odata.etag annotation within payloads ODATA-666
      a. If present, implicit match
      b. Returns 412 Precondition failed if no match (same as if-match header)
      i. Add to description in status codes?
      ii. Etag is ignored in 4.00 payloads
      c. An @odata.etag value of "*" means force update (same semantics as if-match)
      d. If present in the top level resource, it must match both the odata.etag value and any if-match header

      3) Contained items may have their own etags ODATA-666
      a. Changing a contained item MAY change the parent etag

      Show
      ODATA-613 defines semantics for PATCH to a collection of entities can take a delta payload (assumed delta format if an array). In addition: 1) We deprecate @odata.bind in PATCH, PUT, POST a. Clients should instead use @odata.id for insert & link to existing elements i. i.e., instead of “property@odata.bind”:”...”, use “property”: {“@odata.id”:”url…”} ii. Allow entity references in deep insert to add/update reference to existing b. To be OData compliant, services need to support @odata.bind for OData-Version: 4.0 i. OData-Version: 4.01 payloads must not use @odata.bind ii. NOTE: to be compliant with OData, you MUST support 4.0 clients 2) In OData-Version 4.01 payloads, services that support conditional updates MUST pay attention to @odata.etag annotation within payloads ODATA-666 a. If present, implicit match b. Returns 412 Precondition failed if no match (same as if-match header) i. Add to description in status codes? ii. Etag is ignored in 4.00 payloads c. An @odata.etag value of "*" means force update (same semantics as if-match) d. If present in the top level resource, it must match both the odata.etag value and any if-match header 3) Contained items may have their own etags ODATA-666 a. Changing a contained item MAY change the parent etag

      Description

      Similar to Deep Insert allow including nested entities that may already exist, in which case they are updated.
      Also allow nested "tombstones" to remove entities.
      Allow entity references to just create relations as an alternative to odata.bind (in the long run: retire odata.bind and use references everywhere).
      Use odata.etag annotation for conditional update of nested entities.

      Original Proposal for sanity check:
      Document changes
      part1-protocol

      11.4.3 Update an Entity
      Replace para #7 with:
      The entity MAY contain related entities or entity references as inline content. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this replaces the contents of the collection for the specified entites.
      may either add to the relationship (link to 11.4.3.1-see below) or update related entities (link to 11.4.3.2-see below). Combining these two variants for updating a single collection-valued navigation property results in a 400 Bad Request error.

      (new section providing a guideline for updating links) 11.4.3.1 Add Links to Related Entities When Updating an Entity
      To update an entity by adding further links to existing entities, the request includes bind operations on the corresponding navigation property. However, using such bind operations is deprecated. The preferred method is to update the related entities (link to 11.4.3.2).

      (new section) 11.4.3.2 Update Related Entities When Updating an Entity

      The request to update an entity MAY contain collection-valued navigation properties with updated representations of the set of entities related according to the relationship represented by the navigation property. This set MAY be a combination of entities as inline content in the request body, which is referred to as "deep update", entity references, deleted links and deleted entities.

      If the update operation is triggered by a PUT request, the value of a navigation property represents the full set of related entities. Any entity in the relation that is not included in the request, either as an entity or entity reference, is removed from the relation. Any entity that is included as an entity reference is retained without changes if it was already related or added as a member if it wasn't. Any entity represented inline is updated (link to 11.4.3) if it is already related and upserted otherwise (link to 11.4.4). A PUT request MUST NOT include deleted links and deleted entities.

      If the update operation is triggered by a PATCH request with the "delta format" for that nested entity collection, the value of a navigation property represents changes to the set of related entities. Any entity in the relation that is not included in the request is retained without changes. Any entity that is included as an entity reference is retained without changes if it was already related or added as a member if it wasn't. Any entity represented inline is updated (link to 11.4.3) if it is already related and upserted otherwise (link to 11.4.4). A deleted link is processed as removed reference for that navigation property (link to 11.4.6.2). A deleted entity is processed as deleted link and then deleted (link to 11.4.5). Comment: The collection may contain added links.
      If the update operation is triggered by a PATCH request without the "delta format" for that nested entity collection, we apply PUT semantics for the collection membership, and PATCH semantics for the rest.

      An entity being part of the deep update MUST include its entity-id or its full set of key values for identification. It is an error to specify an entity reference that does not identify an existing entity.

      The service MUST NOT treat an update request for related entities with an odata.etag annotation as an insert and must use the etag for conditional updates of existing members. Conflicts will be signaled via status code 412 (precondition failed).

      Upon failure of the operation, the service MUST NOT modify any of the entities in the request in order to prevent a partial update.

      (Guideline for linking entities) 11.4.2.1 Link to Related Entities When Creating an Entity

      • Replace sentence #2 with "The preferred method of providing such entity-ids is through entity references; the use of bind operations is deprecated".

      json-format

      In section 4.5.7 Annotation odata.id
      Add after para #2:
      The odata.id annotation MAY appear in deep update requests to identify entities to be updated.

      In section 8.4 Deep Inserts
      Remove sentence #2. ("Deep inserts are not allowed in update operations using PUT or PATCH requests.")

      Add section 8.5 Deep Update (shift all subsequent sections)
      When updating an entity with a PUT request, the request body MAY contain related entities specified using the same representation as for an expanded navigation property.
      When updating an entity with a PATCH request, the request body MAY contain changes to related entities specified using the representation as for an expanded navigation property that MAY also comprise deleted links and deleted entities.

      atom-format

      In section 8.4 Deep Inserts
      Remove sentence #2. ("Deep inserts are not allowed in update operations using PUT or PATCH requests.")

      Add section 8.5 Deep Update (shift all subsequent sections)
      When updating an entity with a PUT request, the request body MAY contain related entities specified using the same representation as for an expanded navigation property.
      When updating an entity with a PATCH request, the request body MAY contain changes to related entities specified using the representation as for an expanded navigation property that MAY also comprise deleted links and deleted entities.

        Attachments

          Activity

            People

            • Assignee:
              handl Ralf Handl
              Reporter:
              handl Ralf Handl
            • Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: