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

Allow services to return contained entities inline for delta responses

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_ERRATA02
    • Fix Version/s: V4.01_WD01
    • Component/s: JSON Format
    • Labels:
    • Environment:

      [Proposed]

    • Proposal:
      Hide

      Services MAY return related entities inline in a delta response for expanded navigation properties to collections whose members are not otherwise referenced in the defining query. If a navigation property is present in the response then its value represents the current values for the full set of entities related according to that relationship and satisfying any specified expand options. Any entities not included are no longer members of that collection, either because the related entity has been removed from the collection, deleted, or changed such that it no longer satisfies the expand options in the defining query. In any case, the client SHOULD NOT receive additional notifications for those entities.

      1) A delta payload (in GET or PATCH) can have inline navigation values (collection or single, entity or ref) ODATA-876
      a. Default semantics of inline collection of entities is replace membership and PATCH (upsert) individual members (existing members must include entity keys or @odata.id update (PATCH semantics), otherwise insert.)
      b. For single-valued nav prop, update reference & PATCH semantics.
      c. You can use contextUrl (ending in /$delta) on the navigation property to specify that the nested content is a delta content (partial update with patch semantics that can contain added/deleted links and tombstones).
      i. Open issue: any restrictions on the added/deleted links?
      ii. As a shortcut for nested content in delta format you can specify #$delta as the context (gets context from parent).

      2) You can GET deltas for/PATCH $all ODATA-876
      a. Delta response context URL is metadata-url#$delta

      Show
      Services MAY return related entities inline in a delta response for expanded navigation properties to collections whose members are not otherwise referenced in the defining query. If a navigation property is present in the response then its value represents the current values for the full set of entities related according to that relationship and satisfying any specified expand options. Any entities not included are no longer members of that collection, either because the related entity has been removed from the collection, deleted, or changed such that it no longer satisfies the expand options in the defining query. In any case, the client SHOULD NOT receive additional notifications for those entities. 1) A delta payload (in GET or PATCH) can have inline navigation values (collection or single, entity or ref) ODATA-876 a. Default semantics of inline collection of entities is replace membership and PATCH (upsert) individual members (existing members must include entity keys or @odata.id update (PATCH semantics), otherwise insert.) b. For single-valued nav prop, update reference & PATCH semantics. c. You can use contextUrl (ending in /$delta) on the navigation property to specify that the nested content is a delta content (partial update with patch semantics that can contain added/deleted links and tombstones). i. Open issue: any restrictions on the added/deleted links? ii. As a shortcut for nested content in delta format you can specify #$delta as the context (gets context from parent). 2) You can GET deltas for/PATCH $all ODATA-876 a. Delta response context URL is metadata-url#$delta

      Description

      In a delta response for an expanded query we return a flattened result that includes any nested entities that have been added/changed/deleted, along with added/deleted links as appropriate.

      We did this rather than returning expanded content in-line because the semantics of including them inline are unclear; does it mean that only the included inline elements changed, or is it a replacement for the entire set? How do you represent a deletion of a related entity versus simply removing the relationship to that entity – do you have to have a deleted entry in the current collection for deletions? And what if that deleted entity had related entities, some of which were also changed/deleted; how do you return those in a nested result?

      We generally allow the service to track only that a change has occurred to a given item, not what changed within that item. However, a store may well track contained items along with the entity and not be able to tell whether the set of contained items changed, only that a change occurred somewhere in the containment hierarchy.

      For collections of non-entity types we say that the collection is treated as an atomic value – that, if present, the members represent the full membership of the collection. Services don't have to track individual changes to the collection, they just have to know that something changed and they can give the current membership of the collection.

      We could say the same thing for containment navigation properties – that expanding them in-line means that the set of returned entities represents the full set of contained entities, and any previous entities not listed (and all relationships) are implicitly deleted. The client already has to delete contained entities when the parent is deleted so this shouldn't be too onerous.

      We could consider allowing this for non-containment navigation properties, with the semantic that entities omitted from the collection were no longer related (but not deleted), but any related entities that were deleted would have to also be returned as (non-nested) deleted entities, and any changed entities/relationships nested below that deleted entity would have to be separately represented in the payload.

        Attachments

          Activity

            People

            • Assignee:
              mikep Michael Pizzo (Inactive)
              Reporter:
              mikep Michael Pizzo (Inactive)
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: