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

Clarify the use of ETags for Avoiding Update Conflicts

    Details

    • Proposal:
      Hide

      Make clear that EntityCollection/$ref and SingleEntity/$ref are intentionally allowed to return an ETag.

      EntityCollection/$ref (where EntityCollection is an entity set or collection-valued navigation path) may have an (own) ETag returned in the ETag header which changes if the list of references changes, i.e. a reference is added or removed.

      SingleNavigation/$ref (where SingleNavigation is a single-valued navigation path) may have an ETag which represents the identity of the related entity. If the relationship is changed to point to a different OData entity, the ETag MUST change.

      Note: the ETag for an entity reference (i.e. EntitySet(key)/$ref) can never change.

      In JSON, if an object contains an etag (or other control information other than type) then it is a representation of the object, not an entity reference.

      so:

      {"@id":"people(1)"}

      is an entity reference to the resource in the people entity set with the key value 1, where:

      {"@id":"people(1)","@etag":"xyz123"}

      is a minimal representation of the resource (not the reference), just as

      {"@id":"people(1)","name":"maggie"}

      is a minimal representation of the resource.
      So, if

      {"@id":"people(1)","@etag":"xyz123"}

      is returned, the etag refers to the person (and not the reference) and changes if any properties of the person changes.

      Show
      Make clear that EntityCollection/$ref and SingleEntity/$ref are intentionally allowed to return an ETag. EntityCollection/$ref (where EntityCollection is an entity set or collection-valued navigation path) may have an (own) ETag returned in the ETag header which changes if the list of references changes, i.e. a reference is added or removed. SingleNavigation/$ref (where SingleNavigation is a single-valued navigation path) may have an ETag which represents the identity of the related entity. If the relationship is changed to point to a different OData entity, the ETag MUST change. Note: the ETag for an entity reference (i.e. EntitySet(key)/$ref) can never change. In JSON, if an object contains an etag (or other control information other than type) then it is a representation of the object, not an entity reference. so: {"@id":"people(1)"} is an entity reference to the resource in the people entity set with the key value 1, where: {"@id":"people(1)","@etag":"xyz123"} is a minimal representation of the resource (not the reference), just as {"@id":"people(1)","name":"maggie"} is a minimal representation of the resource. So, if {"@id":"people(1)","@etag":"xyz123"} is returned, the etag refers to the person (and not the reference) and changes if any properties of the person changes.
    • Resolution:
      Show
      https://www.oasis-open.org/committees/download.php/64833/odata-json-format-v4.01-wd06-2019-03-08.docx https://www.oasis-open.org/committees/download.php/64834/odata-v4.01-wd06-part1-protocol-2019-03-08.docx

      Description

      http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part1-protocol/odata-v4.0-errata03-os-part1-protocol-complete.html#_Data_Modification states:

      11.4.1.1 Use of ETags for Avoiding Update Conflicts
      If an ETag value is specified in an If-Match or If-None-Match header of a Data Modification Request or Action Request, the operation MUST only be invoked if the if-match or if-none-match condition is satisfied.

      The ETag value specified in the if-match or if-none-match request header may be obtained from an ETag header of a response for an individual entity, or may be included for an individual entity in a format-specific manner.

      Issue requiring clarification: we carefully need to distinguish between OData’s meaning of “entity = an instance of an entity type" and HTTP’s meaning of “entity = the thing whose representation is transferred”. ETags (= entity tags) refer to the HTTP meaning, and thus links/references/relationships are “HTTP entities” that can have their own ETags.

      Also clarify:

      • Can a "HTTP entity" / "link entity" identified by xxx/$ref have an ETag?
      • Is the ETag of a "link entity" logically independent of the ETags of the linked OData entities at either end?
      • If xxx is a collection resource, can the references returned by GET xxx/$ref contain @odata.etag control information to carry the individual ETag of each "link entity"?
      • Are EntitySet/$ref and EntitySet(<key>)/$ref only accidentally allowed by the ABNF and the prose text in Protocol 11.2.8: Requesting Entity References or are these valid resource paths?

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              evan.ireland.2 Evan Ireland
            • Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: