Revised rules for set operations:

[Michael Pizzo <mikep@microsoft.com>]

Below is a proposed set of rules for set operations that address a number of issues.  We will plan to review this as agenda item 8)b)i) in the previously sent proposed agenda.

 

Proposal:

1)      Introduce array collections

a.       Define new term, "Array", to advertise that a collection of primitive or complex types support indexing:
             < Term Name="Array" Type="Core.Tag" DefaultValue="true" AppliesTo="Property,ReturnType">
                 < Annotation Term="Core.Description" String="Collection members can be referenced by use of a zero-based ordinal index"/>
             < /Term>

                                                               i.      Term cannot be applied to collections of entities

b.       GET/PUT/PATCH/DELETE to the /{index} of an ordered collection of non-entities (Array) retrieves/replaces/modifies/deletes just that item

                                                               i.      /index cannot be appended to collections of entities or non-ordered collections

                                                             ii.      Index is zero-based ordinal and follows JSONPointer syntax: collection/index

c.     Update section 7.1.5 of the CSDL spec to note that it is possible to have an ordered collection (array) of complex types with navigation properties.

2)      POST of a single item to a collection of complex or primitive types adds that item to the collection (as it does today with entity types.)

a.       Define a new "PositionalInsert" term to advertise that a collection supports inserting at a given ordinal

              <Term Name="PositionalInsert" Type="Core.Tag" Default="true" AppliesTo="Property, NavigationProperty, EntitySet">

                      <Annotation Term="Core.Description" String="Items can be inserted at a given ordinal index."/>

              </Term>

b.       For collections of entity, complex, or primitive types annotated with PositionalInsert, client may specify new ?$index= query parameter in POST request to collection to specify where the item is inserted

3)      DELETE to any collection without a $filter clears the collection

4)      DELETE to any collection with a $filter clause removes any element matching that filter.

a.       $select, $orderby, $top, $skip are NOT expected to be supported

5)      PUT against a collection of primitive/complex types takes a collection in the payload and replaces the entire collection.

a.       PUT does not support $filter.

b.       This is the existing 4.0 behavior

6)     PUT is not supported against an entity collection

7)      PATCH to any collection with a payload containing a single value updates each element in the collection

a.       If $filter is present, applies patch to those items matching the $filter

8)     PATCH to a collection of primitive or complex types with a collection payload is not supported

9)     PATCH to a collection of entities can take a delta payload (assumed delta format if an array)

a.     MUST NOT have $filter, $select, $orderby, etc.

10)  A delta payload (in GET or PATCH) can have inline collections

a.     Default semantics of inline content is full replacement of the collection.

                                          i.    For consistency, should we add support for in-line single value nav prop?

b.     You can use contextUrl (ending in /$delta) to specify that the nested content is a delta content (partial update 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.

11)  You can GET deltas for/PATCH $all

a.     Delta response context URL is metadata-url#$delta

12)  We deprecate @odata.bind

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…”}

b.     Services still need to support @odata.bind

c.     Client can't mix (can't have property@odata.bind and property in same payload)

13)  Services should pay attention to @odata.etag annotation within payloads for conditional updates

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.    Change to current behavior which says it's ignored in request payloads)

14)  Contained items may have their own etags

a.     Changing a contained item MAY (SHOULD?) change the parent etag

 

Addresses:

1. ODATA-820   Allow indexing into collections
2. ODATA-616   Allow POST to collections of complex and primitive types, and DELETE with $filter
3. ODATA-615   Allow PATCH and DELETE with $filter on collections to modify or delete all (and only) the matching entities
4. ODATA-876 Allow services to return contained entities inline for delta responses
5. ODATA-666  Define Deep Update and Deep Upsert operations
6. ODATA-613  Allow POST to entity sets using the delta-response