OData TC meeting #222 Thursday July 26, 2018

Acting chair: Ralf

Chat transcript from room: odatatc
2018-07-26 0800-1000 PDT

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Krause (SAP SE)
    Hubert Heijkers (IBM)
    Mark Biamonte (Progress Software)
    Matthew Borges (SAP SE) a.k.a. Matt
    Michael Pizzo (Microsoft) a.k.a. Mike
    Ralf Handl (SAP SE)
    Stefan Hagen (Individual)
    Ted Jones (Red Hat)

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

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

2. Approve agenda

Agenda is approved unchanged as published

3. Approve minutes from previous meeting(s)

3.1 Minutes from July 19, 2018 TC meeting #219

URL = https://www.oasis-open.org/committees/download.php/63488/odata-meeting-221_on-20180719-minutes.html

Minutes approved unchanged as published

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

4.1 Action items due

4.1.1 #0036 Register the OData- headers and preferences with IANA Mark Biamonte 2017-11-30

1.IANA Header and Preference registration document questions
https://www.oasis-open.org/apps/org/workgroup/odata/email/archives/201807/msg00017.html

Ralf:

1) Gating items ahead of registration requests to the lists?  
I'm unsure whether there are any other gating items, but I see a lot of activity in the OData TC
- Part3  at CS level -- needed? 
Part 3 has been replaced by two documents in OData 4.01
OData Common Schema Definition Language (CSDL) XML Representation Version 4.0.1
OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01
Both of these documents are at CS01 
Note:  The Part1: Protocol document references OData Vocabularies Version 4.0 and that vocabularies 
document references OData Version 4.01. Part 3: Common Schema Definition Language (CSDL). 
Latest version: http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part3-csdl.html which is not valid for OData 4.01.  
I think this may be why Robin is asking about Part 3.

Ralf: Mark to open an issue to fix Vocabularies doc reference to non-existing OData V4.01 part 3

Ralf:

3) HTML section URLs: headlines in the new documents are links to the stable anchors, using the pattern #sec_...
4) Can we update the IANA registration later to point to the OASIS Specification once we've progressed it to OS? Mark to follow up
5) Only register the prefered variant of preferences without odata. prefix

Mark: prefers that

Mike: will go with that

Ralf: prefers that

Ralf: No objections, only register the non-prefixed variants

4.2 Action items upcoming

4.2.1 #0037 Concept for Google Protocol Buffers as a data format Hubert Heijkers 2018-07-26

Ralf: moved to end of September, candidate topic for F2F

4.3 Action items pending

4.3.1 #0038 Prepare proposal for REST Profile / OData Essentials Mike Pizzo 2018-05-03

Ralf: Moved to August 08, 2018

5. GitHub Pages sites for three of our GitHub repositories:

https://oasis-tcs.github.io/odata-json-schema/
https://oasis-tcs.github.io/odata-vocabularies/
https://oasis-tcs.github.io/odata-openapi/ 

Ralf: These Pages sites contain the same content as the GitHub repositories, just without the GitHub decoration. Currently one has to guess or know their URLs. We want to make them discoverable by linking to them from the repository start page, similar to:

https://github.com/oasis-open/csaf-documentation
https://oasis-open.github.io/csaf-documentation/

Ralf: I move to link from the Github repo start pages to the corresponding github.io Pages Sites. Mike seconds.

Ralf: Motion passes

Ralf: Volunteers for beautifying the Pages Sites, e.g. with an OData logo

Ralf: Ted Jones will have a go on it!

6. Issues

6.1 Data Aggregation: NEW or OPEN

6.1.1 ODATA-1201 - Improve the syntax of aggregation exceptions with "from"

Ralf:

https://github.com/oasis-tcs/odata-abnf/pull/1

Gerald: I move to resolve ODATA-1201 as proposed. Hubert seconds.

Ralf: ODATA-1201 is OPEN

Ralf: ODATA-1201 is RESOLVED as proposed

6.1.2 ODATA-947 - Transformation for computing ratios with aggregated values

Ralf: Hubert on 2018-06-21:

think about similar use cases
ratio() is very useful
combine this with hierarchies
revenue contribution of offices to countries to continents
ability to refer to the input set

Ralf:

GET ~/Sales?$apply=
groupby((Customer),aggregate(Amount with sum as CustomerAmount)) 
/ratio(CustomerAmount to CustomerAmount with sum as RevenueContribution)

GET ~/Sales?$apply=
groupby((Customer),aggregate(Amount with sum as CustomerAmount)) 
/compute(CustomerAmount div aggregate(CustomerAmount with sum) as RevenueContribution)

GET ~/Sales?$apply=
groupby((Customer),compute(Amount div aggregate(Amount with sum) as RevenueContribution))

Ralf: The last one won't work

Ralf:

GET ~/Sales?$apply=
groupby((Customer),aggregate(Amount with sum as CustomerAmount)) 
/compute(CustomerAmount div aggregate(CustomerAmount with sum) as RevenueContribution)

GET ~/Sales?$apply=
groupby((Customer),aggregate(Amount with sum as CustomerAmount)) 
/keep-in-mind(aggregate(CustomerAmount with sum as Divisor)/compute(CustomerAmount div Divisor as RevenueContribution)

George:

1) how does this relate to SQL?
2) how beneficial is this for clients?

Ralf: Second question (2): ratio is quite beneficial

Ralf: How would this translate into Common Table Expressions in SQL?

Gerald to provide SQL counterparts for evaluating these expressions

6.1.3 ODATA-945 - Correct examples 53 and 54

Ralf: Hubert: we have to explain more about the differences


Ralf:

Plain paths with / work like compute: pull arguments from related entities, place result "at the top"
Parentheses can be used to place the result within the related/nested structure
Ralf: Slight difference:

GET ~/Products?$apply=groupby((Name,Sales/Currency/Code),aggregate(Sales(Amount with sum as Total)))
GET ~/Products?$apply=groupby((Name,Sales/Currency/Code),aggregate(Sales/Amount with sum as Total))

Ralf: 3.1.1 Keyword as

Aggregate expressions can define an alias using the as keyword, followed by a SimpleIdentifier (see [OData-CSDL, section 17.2]).

The alias will introduce a dynamic property in the aggregated result set. The introduced dynamic property is added to the 
type containing the original expression or custom aggregate. 
The alias MUST NOT collide with names of declared properties, custom aggregates, or other aliases in that type.

Ralf:

Sales/Amount with sum as Total
Sales(Amount with sum as Total)

George: be more explicit in the definition and not define by example

Ralf:

First example: in top context we are interested in the Amount
Second example: we are interested in the Sales, and within the Sales in the Amount
Need to revise the specification text: section 3.1.1

Gerald to work on revised text for section 3.1.1

6.2 Vocabularies: Bug fixes

6.2.1 ODATA-1192 - Capabilities vocabulary: invalid DefaultValue for KeyAsSegmentSupported

Ralf: ODATA-1192 is OPEN

Ralf: Change default value from 'True' to 'true'.

Mike: I move to resolve ODATA-1192 as proposed. Hubert seconds.

Ralf: ODATA-1192 is RESOLVED as proposed

Ralf:

https://github.com/oasis-tcs/odata-vocabularies/pull/15

Diffs
-            "$DefaultValue": "True",
+            "$DefaultValue": true,

Next diff
-      <Term Name="KeyAsSegmentSupported" Type="Core.Tag" DefaultValue="True" AppliesTo="EntityContainer">
+      <Term Name="KeyAsSegmentSupported" Type="Core.Tag" DefaultValue="true" AppliesTo="EntityContainer">

Ralf: I move to merge this pull request. Hubert seconds.

Ralf: Motion passes

Ralf: I move to CLOSE ODATA-1192 as applied. Mike seconds.

Ralf: ODATA-1192 is CLOSED as applied

6.2.2 ODATA-1193 - Automated vocabulary checks indicate some potential issues

Ralf:

https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml:82 Property Warning: 
  Unspecified Nullable facet defaults to true for property 'Rollup'. 
    It is unusual for properties with default values to be nullable. 
      An explicit Nullable='true' facet is recommended when null property values should be permitted.

<Property Name="Rollup" DefaultValue="MultipleHierarchies" Type="Aggregation.RollupType">...

Ralf:

https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml:85 Property Warning: 
  Unspecified Nullable facet defaults to true for property 'PropertyRestrictions'. 
    It is unusual for boolean-typed properties to allow null values. 
      An explicit Nullable='true' facet is recommended when null property values should be permitted.

<Property Name="PropertyRestrictions" DefaultValue="false" Type="Edm.Boolean">...

Ralf:

https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Authorization.V1.xml:76 Property Warning: 
  Unspecified Nullable facet defaults to true for property 'RequiredScopes'. 
    It is unusual to for collection-typed properties to allow null items. 
      An explicit Nullable='true' facet is recommended when null property values should be permitted.

<Property Name="RequiredScopes" Type="Collection(Edm.String)">...

Ralf: ODATA-1193 is OPEN

Mike: these checks are great

Gerald: check Aggregation issues

Mike: check Authorization issues

Ralf: Capabilities:

collection of filter functions --> Nullable=false
maxlevels --> nullable=false

Ralf: Capabilities

6.3 Vocabularies: Annotation Examples and Example Values for types, parameters, request/response bodies

Ralf: ODATA-1194 and ODATA-1200

Ralf:

<Term Name="Example" Type="Core.ExampleType">
  <Annotation Term="Core.Description" String="A container for annotation examples" />
  <Annotation Term="Core.Example">
    <Record>
      <Annotation Term="Core.Description"
        String="Note that the value of Core.Example is a record/object containing the annotation examples" />
    </Record>
  </Annotation>
</Term>
<ComplexType Name="ExampleType">
  <Annotation Term="Core.Description" String="This type intentionally doesn't have properties, so it can only contain annotation examples" />
</ComplexType>

Ralf:

<Term Name="Example" Type="Core.ExampleValue" AppliesTo="EntityType ComplexType Parameter"/>
<ComplexType Name="ExampleValue" Abstract="true">
  <Property Name="Description" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Description of the example value" />
  </Property>
</ComplexType>
<ComplexType Name="InlineExampleValue" BaseType="ExampleValue">
  <Property Name="Value" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Example value for the custom parameter" />
  </Property>
</ComplexType>
<ComplexType Name="ExternalExampleValue" BaseType="ExampleValue">
  <Property Name="ExternalValue" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Url reference to the value in its literal format" />
  </Property>
</ComplexType>

6.3.1 ODATA-1194 - Add term Core.Example to allow including annotation examples in term definitions

Cf. section 6.3 for combined discussion

6.3.2 ODATA-1200 - ODATA-884 / Support sample values for types, parameters, request/response bodies

Cf. section 6.3 for combined discussion

7. Next meetings

Agreed next meetings:

Thursday August 02, 2018 during 8-10 am PDT (17:00-19:00 CEST)
Thursday August 09, 2018 during 8-10 am PDT (17:00-19:00 CEST)

Mike, Ramesh and Ted cannot attend next week

Ralf: Let's try it next week

8. AOB and wrap up

F2F in Redmond September 25-28

Meeting adjourned by chair.