OData TC meeting #159 Thursday Jan 26, 2017

Acting chair: Ralf

Chat transcript from room: odatatc
2017-01-26 0800-1000 PT

1. Roll call

1.1 Members present

        Gerald Krause (SAP SE)
        Hubert Heijkers (IBM)
        Mark Biamonte (Progress Software)
        Martin Zurmuehl (SAP SE)
        Matthew Borges (SAP SE) a.k.a. Matt
        Michael Pizzo (Microsoft) a.k.a. Mike
        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=43962).

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

2. Approve agenda

Stefan: Suggest to add a short presentation / discussion of the contribution after "approval of timeline" and before "issue processing".
New Contribution fromSAP SE (submitted by Ralf) with title: "Streamlined Metadata JSON" (https://www.oasis-open.org/committees/download.php/59875/Streamlined Metadata JSON.docx). Abstract: "This document describes a streamlined JSON format for OData V4 metadata intended to simplify client-side processing. It is different from the $metadata service's JSON format (see OData JSON Format Version 4.0) and the OData JSON Format for Common Schema Definition Language (CSDL) Version 4.0 (see corresponding specification)."

Ralf: New issues:
ODATA-1030 - Consider support of NavigationPropertyBindings to non-contained nav props; Discuss this right after ODATA-674 as 6.1.9; Move ODATA-674 to "ready for resolution" as new agenda item 6.1.8 (both skipped due to missing time)
ODATA-1031 - Define term for links to related information; Discuss this right before ODATA-674 as 6.1.7

Agenda is approved with above modifications.

3. Approve minutes from previous meeting(s)

3.1 Minutes from January 19, 2017 TC meeting #158


Minutes approved unchanged as published.

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

4.1 Action items due

4.1.1 AI#0036 - "Register the OData- headers and preferences with IANA"

Ralf: Documents for walk through: https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59874/latest/IANA_Preference_Registration.docx, and https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59873/latest/IANA_Header_Registration.docx.

Ralf: Mark will walk us through the documents

Ralf: Example 2: using a HTTP callback endpoint to receive notification

Prefer: callback; url="http://myserver/notfication/token/12345"

Ralf: Thanks to Mark!

Ralf: Documents will be submitted to IANA once V4.01 CS01 is published

5. TC Timeline - Topics for this year

Ralf: Timeline:
- URL = https://www.oasis-open.org/committees/download.php/59862/TC Timeline-2017-01-25.docx

5.1 CSDL JSON Representation V4.01

Mike: I move we accept the contribution "Streamlined Metadata in JSON" from SAP made by Ralf Handl. Mark seconds.

Ralf: No objections, motion passes.

Mike: push for earlier public review of CSDL JSON Representation?

Mike: take next week's meeting to walk through the document and see when we want to publish CSD01

6. V4.01

6.1 Issues for V4.01_CSD02 ready for resolution

6.1.1 ODATA-xxx - ttt

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


<Annotation Term="Core.ErrorCodes"> 
    <PropertyValue Property="HttpMethod" String="GET" /> 
    <PropertyValue Property="HttpStatusCode" String="400" /> 
    <PropertyValue Property="ODataErrorCode" String="QueryFilterFunctionNotSupported" /> 
    <PropertyValue Property="Description" 
    String="This error indicates that a request was made with a filter function that isnt supported on this entity set. Please refer to the Capabilities.FilterFunctions annotation on this entity set for a list of supported functions, and the exact error message for which function usage triggered this error." /> 

Ralf: Definition

<Term Name="ErrorCodes" Type="Collection(Core.ErrorCodeType)" AppliesTo="EntitySet Singleton ActionImport FunctionImport Action Function"> 
  <Annotation Term="Core.Description" String="Describes possible error codes in OData responses" /> 
  <Annotation Term="Core.LongDescription" String="The list need not be complete. It may be used to generate API documentation, so restricting it to the most common and most important errors may increase readability." />
<ComplexType Name="ErrorCodeType"> 
  <Property Name="HttpMethod" Type="Edm.String"> 
  <Annotation Term="Core.Description" String="Request verb of the HTTP request, e.g. GET, POST, PATCH, DELETE" /> 
  <Property Name="HttpStatusCode" Type="Edm.String"> 
  <Annotation Term="Core.Description" String="HTTP status code of the response, e.g. 400, 403, 501" /> 
  <Property Name="ODataErrorCode" Type="Edm.String"> 
  <Annotation Term="Core.Description" String="Language-independent, machine-readable OData error code" /> 
  <Property Name="Description" Type="Edm.String"> 
  <Annotation Term="Core.Description" String="Human-readable description of the error situation" /> 

Mike: would it make sense to pre-group the error codes by HTTP method and then HTTP status code

Ralf to prepare examples for XML and JSON showing more than one error code

6.1.2 ODATA-1013 - Selected nav props in a defining query should specify interest in added/deleted links

Ralf: Proposal:
Nav properties specified in the select list of a defining query are not used to define the scope or contents of the items being tracked. Clients can specify /$ref in $expand in order to specify interest in the set of related entities without interest in changes to the content of those related entities.

Delta responses contain AddedLinks and DeletedLinks entries (or, for nested collections, (at least) entity references representing the current membership) for navigation properties expanded with $ref in the defining request.

Mike: I move we approve ODATA-1013 as proposed to define semantics around /$ref in the expand of a defining query. Hubert seconds.

Ralf: ODATA-1013 is resolved as proposed

6.1.3 ODATA-1019 - Add term Core.DynamicDefaultValue

Ralf: Term definition

<Term Name="DynamicDefaultValue" Type="Core.Tag" DefaultValue="true" AppliesTo="Property"> 
  <Annotation Term="Core.Description" String="A value for this property is can be provided on insert and update. If no value is provided on insert, a non-static default value is generated" /> 

Mike: ComputedDefaultValue would be more in line with Core.Computed for read-only properties with computed values

Mike: Clarify how this combines with preference omit-defaults

Ralf: Computed default values cannot be omitted because the client can't know it

Mark: ComputedDefaultValue works

Hubert: +1

Matt: +1

Mike: -1

Ralf: ComputedDefaultValue is accepted

Ralf: ODATA-1019 is OPEN

Ralf: I move to resolve ODATA-1019 with the updated proposal. Matt seconds.

Ralf: ODATA-1019 is RESOLVED

6.1.4 ODATA-1027 - Support instance annotations in $orderby

Mike: I move we resolve ODATA-1027 as proposed. Ramesh seconds.

Ralf: ODATA-1027 is RESOLVED as proposed

6.1.5 ODATA-1028 - 4.3.4: clarify relative URLs when a type-cast segment is present

Ralf: Description:
4.3.4 Resolving an Entity-Id states that

The entity-id may be expressed as an absolute IRI or relative to the service root URL.

Example 23: request the entity representation for an entity-id

This was correct until we introduced type-cast segments after $entity with ODATA-528.

Now relative URLs should rather be relative to the request URL, as in all other places.

Ralf: Relative URLs passed with query option $id are relative to the request, as explicitly stated for other uses of $id.

Add example for a relative URL with and without type-cast segments, showing the need for ../ to dive down beyond the type-cast segment.

Mike: we also have $root as a symbolic segment

Ralf: So URLs relative to the service root can be expressed by prepending $root/

Ralf: According to JSON Format the entity id is relative to the context URL, which is (typically) the metadata URL, i.e. relative to the service root

Mike: $id should also be relative to the service root, so clients can just take the id provided in the JSON response

Ralf: GET $entity/self.Car?$id=People(42)

Ralf: Alternative proposal: stick to the current text: $id is always relative to service root, even if there's a type-cast segment appended to $entity

Ralf: ODATA-1028 is OPEN

Mike: I move we resolve ODATA-1028 as per the alternate proposal; that the $id is always relative to the service root. Martin seconds.

Ralf: ODATA-1028 is RESOLVED with the alternative proposal

6.1.6 ODATA-1029 - clarify that all() is always true if applied to an empty collection

Ralf: ODATA-1029 is OPEN

Mike: clarify that for all() and any()

Ralf: any(expr) is false on the empty set

Mike: Proposal: all() applied to an empty collection always returns true.
any() applied to an empty collection always returns false.

Hubert: I move to resolve ODATA-1029 as per the amended proposal. Stefan seconds.

Ralf: ODATA-1029 is RESOLVED with the extended proposal

6.1.7 ODATA-1031 - Define term for links to related information

Ralf: Define term for links to related information

Ralf: Example:

    <Annotation Term="Core.Link"> 
      <PropertyValue Property="rel" String="latest-version" /> 
      <PropertyValue Property="href" 
      String="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml" /> 

Ralf: Define new Core term:

    <Term Name="Link" Type="Core.LinkType"> 
    <Annotation Term="Core.Description" String="Link to related information" /> 
    <Annotation Term="Core.LongDescription" 
      String="The Link term is inspired by the 'atom:Link' element, see [RFC4287](https://tools.ietf.org/html/rfc4287#section-4.2.7) and the 'Link' HTTP header, see [RFC5988](https://tools.ietf.org/html/rfc5988)" /> 
    <ComplexType Name="LinkType"> 
    <Property Name="rel" Type="Edm.String" Nullable="false"> 
      <Annotation Term="Core.Description" 
      String="Link relation type, see [IANA Link Relations](http://www.iana.org/assignments/link-relations/link-relations.xhtml)" /> 
    <Property Name="href" Type="Edm.String" Nullable="false"> 
      <Annotation Term="Core.IsURL" /> 
      <Annotation Term="Core.Description" String="URL of related information" /> 

Mike: only for metadata annotations or also for instance annotations?

Mike: In the Atom format we could have used this out-of-the-box

Mike: Atom format used atom:link for @odata.editLink, @odata.id, ...

Mike: would need to define what happens if both the @odata link and the @Core.Link are present

Mike: would also need to consider this when reviving the Atom format

Mike: explicitly state that this annotation is (a) useful as an instance annotation (b) @odata annotations take precedence

Mike: make this a collection?

Mike: or use the qualifier for the rel and make it just a string?

Mike: want to have multiple links, dummy qualifiers seem awkward

Ralf: ODATA-1031 is OPEN

Stefan: I move to resolve ODATA-1031 as proposed making this a collection. Martin seconds.

Ralf: ODATA-1031 is RESOLVED with the amendment

7. Next meetings

7.1 Next Meeting Thursday February 02, 2017 during 08:00-10:00 am PST

Ralf: Topic next week: https://www.oasis-open.org/apps/org/workgroup/odata/download.php/59388/odata-csdl-json-v4.01-wd01-2016-11-16.docx

Mike and Stefan: All with spare cycles please take a look at that URL/document

No objections, we meet next week usual time

8. AOB and wrap up

Mark: example quotes for ISO publication?

Mike: Will put together sample quotes

Meeting adjourned by chair.