OData TC meeting #206 Thursday March 08, 2018

Acting chair: Ralf

Chat transcript from room: odatatc
2018-03-08 0800-1000 PST

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Kraue (SAP SE)
    Mark Biamonte (Progress Software)
    Martin Zurmuehl (SAP SE)
    Matthew Borges (SAP SE) a.k.a. Matt
    Ralf Handl (SAP SE)
    Ramesh Reddy (Red Hat)
    Stefan Hagen (Individual)
    Ted Jones (Red Hat)

Quorum achieved. Details cf. normative attendance sheet for this meeting (event_id=46246).

Notes taken by all and subsequently edited for readability by Stefan.

2. Approve agenda

Ralf: Agenda approved unchanged as published

3. Approve minutes from previous meeting(s)

3.1 Minutes from March 01, 2018 TC meeting #205

https://www.oasis-open.org/committees/download.php/62633/odata-meeting-205_on-20180301-minutes.html

Minutes approved unchanged as published.

4. Review action items [Link to Action item list]

4.1 Action items due

None.

5. Infos from TC Admin (Chet Ensign)

5.1 Vocabularies and V4.0 Errata 04

  1. We can change the vocabulary references in the specification documents to the GitHub vocabularies
  2. We should in addition pack the most recent copy of the GitHub vocabularies into the Errata zip, so they are published at the usual location
  3. This is not a problem because the GitHub vocabularies contain latest-version links that point to GitHub

George: let's go with GitHub as the vocabulary source and NOT publish Errata 04

Ralf: Change log of vocabulary files is GitHub: https://github.com/oasis-tcs/odata-vocabularies

Ralf: Commits link back to TC Jira

Ralf: Same procedure in the time before GitHub: SVN as source control, commit comment links to TC Jira

Ralf:

<Annotation Term="Core.Links">
  <Collection>
    <Record>
      <PropertyValue Property="rel" String="latest-version" />
      <PropertyValue Property="href" String="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml" />
    </Record>
    <Record>
      <PropertyValue Property="rel" String="alternate" />
      <PropertyValue Property="href" String="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json" />
    </Record>
    <Record>
      <PropertyValue Property="rel" String="describedby" />
      <PropertyValue Property="href"
        String="https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md" />
    </Record>
  </Collection>
</Annotation>

5.2 Jira Issue Notifications

  1. Currently the TC Jira sends notifications to the TC mailing list for every change of an issue:
    1.Created, Updated, Resolved, Closed, Commented, Comment Edited, Comment Deleted, Reopened, Deleted
  2. Now a terse notification scheme is available, reduced to:
    1.Created, Resolved
  3. Do we want to switch to terse? Watchers of an issue will still receive notifications of any change to the watched issue

Gerald: terse

Ralf: terse

Mark: no preference

Ramesh: keep verbose (but fine with switching to terse)

Stefan: also in favour of terse

Ralf to contact TC Admin to switch to "terse" notifications

6. Timeline

6.1 Updated timeline

URL = https://www.oasis-open.org/committees/download.php/62637/TC Timeline-2018-03-02.docx

Ralf: I move to approve the new timeline. Martin seconds.

Ralf: No objections, motion passes

7. Issues

7.1 APPLIED

7.1.1 ODATA-1155 - ABNF: allow omitting default namespaces everywhere in the URL

Ralf: Relax ABNF to allow omitting namespaces for

- functions 
- actions 
- type-cast 
in 
- path 
- query options 

But NOT in the context URL.

Ralf: https://tools.oasis-open.org/version-control/browse/wsvn/odata/?op=comp&compare%5B%5D=%2Ftrunk%2F4.01+spec%2FABNF@1129&compare%5B%5D=%2Ftrunk%2F4.01+spec%2FABNF@1142&manualorder=1

Ralf: I move to CLOSE ODATA-1155 as applied. Mark seconds.

Ralf: ODATA-1155 is CLOSED as applied

7.2 Vocabularies: NEW or OPEN with concrete proposal

7.2.1 ODATA-1072 - Annotation to describe supported aggregation methods

Gerald: I move to resolve ODATA-1072 as proposed. Martn seconds.

Ralf: ODATA-1072 is RESOLVED as proposed

7.2.2 ODATA-1064 - Add ability to annotate collections to return only count and NextLink

Ralf: Skipped

7.3 Vocabularies: NEW or OPEN that need more discussion triage

7.3.1 ODATA-1099 - Add annotations to describe custom query options and custom headers

Ralf: would like to have it for odata-to-openapi mapping

7.3.2 ODATA-1067 - Consider ability to define computed default values

Ralf: No one voting for doing it now, deferred

7.3.3 ODATA-1005 - Make sure we have capabilities for all new 4.01 functionality

Ralf: need this for generic clients

Mark: agreed, need to do it

Ralf: split it up into "topic groups" to see some progress

7.3.4 ODATA-884 - Add term ErrorCodes to describe possible codes in error messages (public comment c201510e00019)

Ralf: probably have to do this together with ODATA-1099 - Add annotations to describe custom query options and custom headers

7.4 V4.01: NEW or OPEN

7.4.1 ODATA-1156 - Context URL: allow empty parentheses after navigation property

Ralf: ABNF issue, ABNF is more restrictive than prose specification

Ralf: ODATA-1156 is OPEN

Ralf: https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/4.01%20spec/ABNF/odata-abnf-construction-rules.txt?op=diff&rev=1137
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/4.01%20spec/ABNF/odata-abnf-testcases.xml?op=diff&rev=1137

Ralf: Change:

old: selectList         = OPEN selectListItem *( COMMA selectListItem ) CLOSE
new: selectList         = OPEN [ selectListItem *( COMMA selectListItem ) ] CLOSE

Ralf: I move to resolve ODATA-1156 as proposed. George seconds.

Ralf: I move to close ODATA-1156 as applied. George seconds.

Ralf: ODATA-1156 is CLOSED as applied

7.4.2 ODATA-1154 - Clarify which OData-Version a service should return

Ralf: Skipped

7.4.3 ODATA-1151 - Edm.Stream and Nullable

Ralf:

1) Expanded returns null 
2) Link is always valid, returns 204 if the value is null

Ralf: Remark

1) is consistent with the representation of structural properties of other primitive type and with expanded single-valued navigation properties 
2) is consistent with directly accessing a property that has the null value, directly accessing the raw value of a property that has the null value, 
   and directly accessing a single-valued navigation property that has no entity related 
- http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_RequestingIndividualProperties 
- http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_RequestingaPropertysRawValueusingval 
- http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_RequestingRelatedEntities

Ralf: I move to resolve ODATA-1151 as proposed. George seconds.

Ralf: ODATA-2251 is RESOVLED as proposed

7.4.4 ODATA-1149 - Support Delta responses for Singletons

Ralf: Today we are a bit unclear about whether or not deltas are supported for singletons.

In 11.3 Requesting Changes of the Protocol document, we say: 
"Any GET request to retrieve one or more entities MAY allow change-tracking." 

However, in 15.1 Delta Response of the JSON document we say: 
"Responses from a delta request are returned as a JSON object. The JSON object MUST contain an array-valued property named value containing all added, 
changed, or deleted entities, as well as added links or deleted links between entities, and MAY contain additional, unchanged entities." 

The wording from the JSON spec makes sense for 4.0, since changes to related entities and links were represented in a flattened result, 
but with the ability to represent nested related content, it is useful to support a delta payload (GET or PATCH) for requests anchored on a single node.

George: why not

George: no array, just one "delta object"

Ralf: need new context URL pattern to distinguish this from "full object"

Ralf: ODATA-1149 is OPEN

Ralf: Need a more concrete proposal

7.4.5 ODATA-1148 - PATCH with nested nav props should not remove omitted resources

Ralf:

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.

George: consider PATCH on collection

Ralf:

11.4.12 Update a Collection of Entities
Collections of entities can be updated by submitting a PATCH request to the resource path of the collection. 
The body of the request MUST be a delta payload, and the resource path of the collection MUST NOT contain type cast or filter segments.

Added/changed entities are applied as upserts, and deleted entities as deletions. 
The top-level collection may include added and deleted links, and related entities represented inline are updated 
according to the rules for treating related entities when updating an entity.

The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes.

On failure, the service MUST NOT apply any of the changes specified in the delta request payload.

Ralf:

Current PATCH behavior for single entity with related collection:
{
  "Items": [...] 
}
means replace

Ralf:

For "delta patch" use
 {
  "Items@odata.delta": [...] 
}

Ralf: ODATA-1148 is OPEN

7.4.6 ODATA-1141 - Upsert: clarify upsert along nullable single-valued navigation path

Ralf: Description:

Section 11.4.4 Upsert an Entity allows upsert request to any URL that identifies a single entity. 
It then references section 11.4.2 Create an Entity, which only talks about creating entities in a collection 

Clarify that upsert is also valid along a nullable single-valued navigation property, at least as long the key property values are client-defined. 
May also work with server-defined keys by responding with 201 and a location header with the canonical URL of the newly created entity.

George: for server-generated keys: if key is provided, relate and update target, otherwise create and relate new target entity

Ralf: ODATA-1141 is OPEN

8. Next meetings

Ralf:

Thursday March 15, 2018 during 8-10 am PDT (16:00-18:00 CET) – Daylight Saving Time in North America
Thursday March 22, 2018 during 8-10 am PDT (16:00-18:00 CET) – Daylight Saving Time in North America
Thursday March 29, 2018 during 8-10 am PDT (17:00-19:00 CEST) – back to normal time difference, Easter is coming

9. AOB and wrap up

Ralf: Switch back to Adobe Connect for telco

* Dial-in not possible from Linux with Skype for Business
* Screen sharing problematic

Meeting adjourned by chair.