OData TC meeting #226 Thursday August 23, 2018

Acting chair: Ralf

Chat transcript from room: odatatc
2018-08-23 0800-1000 PDT

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Krause (SAP SE)
    Mark Biamonte (Progress Software)
    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=46270).

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

2. Approve agenda

New issue:

https://issues.oasis-open.org/browse/ODATA-1216 - vocabulary-related

Ralf: No further changes, agenda is approved

3. Approve minutes from previous meeting(s)

3.1 Minutes from August 09, 2018 TC meeting #224

URL = https://www.oasis-open.org/committees/download.php/63732/odata-meeting-225_on-20180816-minutes.html

Minutes approved unchanged as published

Ralf: Reminder: volunteer for minutes-keeper needed!

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

4.1 Action items due

None.

4.2 Action items upcoming

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

Nothing noted

4.3 Action items pending

4.3.1 #0036 Register the OData- headers and preferences with IANA Mark Biamonte 2018-07-26

Ralf: Mark provided new versions of the registration documents without redlining and handed them over to Chet Ensign

5. Issues

5.1 Data Aggregation: NEW or OPEN

5.1.1 ODATA-1215 - Clarify datatype of virtual property $count

Ralf: ODATA-1215 is OPEN

Gerald:

GET ~/Sales?$apply=aggregate($count as SalesCount)
{ 
  "@odata.context": "$metadata#Sales(SalesCount)",
  "value": [
    { "@odata.id": null, "SalesCount": 8 }
  ]
}

Gerald: I move to resolve ODATA-1215 as proposed. Mark seconds.

Ralf: ODATA-1215 is RESOLVED as proposed

5.1.2 ODATA-1207 - Clarify need for @odata.id in nested response structures

Ralf: Defer this to next time Mike can join us

5.1.3 ODATA-1216 - Terms for POST/PATCH/PUT with system query options to shape response

Ralf: Add new terms

<Term Name="InsertSupport" Type="Core.InsertSupportType">
  <Annotation Term="Core.Description" String="Advanced insert capabilities" />
</Term>
<ComplexType Name="InsertSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with insert requests" />
  </Property>
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with insert requests" />
  </Property>
</ComplexType>
 
<Term Name="UpdateSupport" Type="Core.UpdateSupportType">
  <Annotation Term="Core.Description" String="Advanced update capabilities" />
</Term>
<ComplexType Name="UpdateSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with update requests" />
  </Property>
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with update requests" />
  </Property>
</ComplexType>
 
<Term Name="ActionSupport" Type="Core.ActionSupportType">
  <Annotation Term="Core.Description" String="Advanced Action capabilities" />
</Term>
<ComplexType Name="ActionSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with action invocation requests" />
  </Property>
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with action invocation requests" />
  </Property>
</ComplexType>

Description

PATCH Orders(42)?$expand=Items($top=10)&$select=ID,Currency,TotalAmount,...

George: why not needed for Delete?

Ralf: DELETE always returns 204 No Content

George: where would these be applied?

Ralf: on Entity Container if all resources support it, otherwise on entity sets, singletons, actions

Ralf: ODATA-1216 is OPEN

Ralf: Updated proposal:

<Term Name="InsertSupport" Type="Core.InsertSupportType" AppliesTo="EntityContainer EntitySet Singleton Action">
  <Annotation Term="Core.Description" String="Advanced insert capabilities" />
</Term>
<ComplexType Name="InsertSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with insert requests" />
  </Property>
  <Property Name="SelectSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with insert requests" />
  </Property>
</ComplexType>
 
<Term Name="UpdateSupport" Type="Core.UpdateSupportType" AppliesTo="EntityContainer EntitySet Singleton Action">
  <Annotation Term="Core.Description" String="Advanced update capabilities" />
</Term>
<ComplexType Name="UpdateSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with update requests" />
  </Property>
  <Property Name="SelectSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with update requests" />
  </Property>
</ComplexType>
 
<Term Name="ActionSupport" Type="Core.ActionSupportType" AppliesTo="EntityContainer EntitySet Singleton Action">
  <Annotation Term="Core.Description" String="Advanced Action capabilities" />
</Term>
<ComplexType Name="ActionSupportType">
  <Property Name="ExpandSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $expand with action invocation requests" />
  </Property>
  <Property Name="SelectSupported" Type="Edm.Boolean" Nullable="false">
    <Annotation Term="Core.Description" String="Service supports $select with action invocation requests" />
  </Property>
</ComplexType>

Ralf:

Default behavior: expect only new services to advertise the capability
So would expect that absence of the annotation means not supported

Ralf: All agree that not specifying a default value for the "Supported" properties is the right choice

Ralf: It's also in line with the existing term BatchSupport

Mark: I move that ODATA-1216 be resolved as proposed. George seconds.

Ralf: ODATA-1216 is RESOLVED as proposed

5.2 Vocabularies: NEW or OPEN with concrete proposal

5.2.1 ODATA-1209 - Term for original OData version of (auto-)converted $metadata

Ralf: We have several cases of generic clients that can interact with V2 and V4 services and internally only use V4 syntax and semantics. One aspect of this is that the client converts the V2 $metadata into V4 $metadata and needs to "remember" whether the original protocol version - and the one to use for URL generation and payload serialization is something else than V4.

Mark: seems to be an implementation detail

George: not run into that problem

Ralf: Will close this without action

5.2.2 ODATA-1204 - Vocabularies Document references OData Version 4.01. Part 3: Common Schema Definition Language (CSDL)

Ralf: Part 3 doesn't exist any more

Ralf: Proposal:

In the Related Work section of the OData Vocabularies document remove the sub-bullet that references 
 
 OData Version 4.01. Part 3: Common Schema Definition Language (CSDL)
 
and replace with references to
 
OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01
OData Common Schema Definition Language (CSDL) XML Representation Version 4.01

Ralf: ODATA-1204 is OPEN

George: I move to approve ODATA-1204 as proposed. Mark seconds.

Ralf: ODATA-1204 is RESOLVED as proposed

5.2.3 ODATA-1176 - Capabilities: add new term SelectRestrictions

Ralf: Similar to other xxxRestrictions add a SelectRestrictions structured term with (for now) a single property Selectable of type Boolean:

Example:
 
<Annotation Term="Capabilities.SelectRestrictions">
  <Record>
    <PropertyValue Property="Selectable" Bool="false" />
  </Record>
 </Annotation>

Ralf: Proposal

<Term Name="SelectRestrictions" Type="Capabilities.SelectRestrictionsType" AppliesTo="EntitySet Singleton">
  <Annotation Term="Core.Description" String="Restrictions on selecting properties" />
</Term>
<ComplexType Name="SelectRestrictionsType">
  <Property Name="Selectable" Type="Edm.Boolean" DefaultValue="true">
    <Annotation Term="Core.Description" String="$select is supported" />
  </Property>
</ComplexType>

Ralf: Alternative term would be "SelectSupported" similar to existing TopSupported:

<Term Name="TopSupported" Type="Core.Tag" DefaultValue="true" AppliesTo="EntitySet">
  <Annotation Term="Core.Description" String="Supports $top" />
</Term>

Ralf: New proposal:

<Term Name="SelectSupported" Type="Core.Tag" Nullable="true" DefaultValue="true" AppliesTo="EntitySet">
  <Annotation Term="Core.Description" String="Supports $select" />
</Term>

: Newer proposal:

<Term Name="SelectSupported" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="EntitySet">
  <Annotation Term="Core.Description" String="Supports $select" />
</Term>

Ralf: Even newer proposal:

<Term Name="SelectSupported" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="EntitySet Singleton">
  <Annotation Term="Core.Description" String="Supports $select" />
</Term>

George: I move to approve ODATA-1176 as modified. Mark seconds.

Ralf: ODATA-1176 is RESOLVED as proposed

5.2.4 ODATA-1167 - Add way to specify which batch formats (if any) are supported by a service

Ralf: Add a SupportedFormats property to the BatchSupportType:

<Property Name="SupportedFormats" Type="Collection(Edm.String)" Nullable="false">
  <Annotation Term="Core.Description" String="Media types of supported formats for $batch" />
  <Annotation Term="Core.IsMediaType" />
  <Annotation Term="Validation.AllowedValues">
    <Collection>
      <Record>
        <PropertyValue Property="Value" String="multipart/mixed" />
        <Annotation Term="Core.Description"
          String="Multipart Batch Format, see http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_MultipartBatchFormat" />
      </Record>
      <Record>
        <PropertyValue Property="Value" String="application/json" />
        <Annotation Term="Core.Description"
          String="JSON Batch Format, see http://docs.oasis-open.org/odata/odata-json-format/v4.01/cs01/odata-json-format-v4.01-cs01.html#sec_BatchRequestsandResponses" />
      </Record>
    </Collection>
  </Annotation>
</Property>

Ralf: Short form:

Add a SupportedFormats property to the BatchSupportType:
 
<Property Name="SupportedFormats" Type="Collection(Edm.String)" Nullable="false">
  <Annotation Term="Core.Description" String="Media types of supported formats for $batch" />
  <Annotation Term="Core.IsMediaType" />
</Property>

plus restriction on allowed values:
 
<Annotation Term="Validation.AllowedValues">
  <Collection>
    <Record>
      <PropertyValue Property="Value" String="multipart/mixed" />
      <Annotation Term="Core.Description"
        String="Multipart Batch Format, see http://docs.oasis-open.org/odata/odata/v4.01/cs01/part1-protocol/odata-v4.01-cs01-part1-protocol.html#sec_MultipartBatchFormat" />
    </Record>
    <Record>
      <PropertyValue Property="Value" String="application/json" />
      <Annotation Term="Core.Description"
        String="JSON Batch Format, see http://docs.oasis-open.org/odata/odata-json-format/v4.01/cs01/odata-json-format-v4.01-cs01.html#sec_BatchRequestsandResponses" />
    </Record>
  </Collection>
</Annotation>

Ralf: Annotation example:

@Capabilities.BatchSupport:{
  SupportedFormats: ["application/json", "multipart/mixed" ]
}

Ralf: ODATA-1167 is OPEN

Mark: I move that ODATA-1167 be resolved as proposed. Ramesh seconds.

Ralf: ODATA-1167 is RESOLVED as proposed

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

George: agreement with Mike reached, wait for Mike to recap the proposal

5.3 V4.01: NEW or OPEN

5.3.1 ODATA-1210 - CSDL ReturnType element needs to specify rules for Nullable and Collection with entity types

Ralf: Description

It is reasonable to assume:
 
A collection of entities never contains null because the null entity has no meaning.
A function returning a single entity would have to return 204 No Content to signal no entity returned, 
similar to following a single-valued navigation property with nothing associated at that point in time.
Therefore:
 
A function returning entities behaves like a navigation property.
A function returning structured or primitive instances behaves like a structural property.
In regard to CSDL XML/JSON 4.01, we should specify:
 
Nullable should never be specified for a Collection(SomeEntityType), and it must always be considered 
to be false by default. This would bring consistency with navigation properties.
 
Going one step further, we should probably apply this reasoning to Parameter elements, i.e. a parameter 
of type Collection(SomeEntityType) should also never have an explicit Nullable facet.

Ralf: ODATA-1210 is OPEN

Mark: I move ODATA-1210 be resolved as proposed. Ramesh seconds.

Ralf: ODATA-1210 is RESOLVED as proposed

5.3.2 ODATA-1203 - Allow numeric indexes in Path constructs within annotations

Ralf: Description

With ODATA-1061 we allowed key segments in parenthesis syntax after path segments that identify a collection of entities.
 
A logical extension is allowing numeric indexes to reference entities or complex type instances within a collection:
 
<Annotation Term="Some.Term" Path="ComplexCollection/0/SomeProperty" />
This would address the first item in the collection. If the item is structured, additional path segments can follow after the index segment.

Ralf: Proposal

Path expressions allow index segments after path segments that identify a collection. 
The index is zero-based and MUST be an integer literal. Negative integers count from the end of the collection, 
with -1 representing the last item in the collection.
 
This key syntax can only be used in Path expressions as only these refer to instance values.
 
It cannot be used in expressions for model references, i.e. PropertyPath, NavigationPropertyPath, AnnotationPath, 
and their abstract supertypes AnyPropertyPath and AnyPath.
 
Optional extension: this could be generalized to allow path expressions as indexes if we make path expressions 
to be used as an index distinguishable from path expressions that navigate into structured collection items. 
The natural choice would be the # symbol:
 
<Annotation Term="Some.Term" Path="ComplexCollection/#(ComplexPropertyNextToComplexCollection/IntegerProperty)/SomePropertyofComplexItem" />
The # symbol so far is only used to separate a term from a qualifier, so the sequence /#( cannot appear so far. 
Using parentheses around the path to the index is necessary to mark the end of the index path.
 
An even more powerful alternative would be to add a templating-style syntax using e.g. curly braces
 
<Annotation Term="Some.Term" Path="ComplexCollection/{path/to/something/that/results/in/a/valid/path/segment}/SomePropertyofComplexItem" />
Here the result of evaluating the path _expression_ within the curly braces is then used as a path segment 
for the "outer" path - of course with nesting. If the result is a number, it is treated as an index for the collection, 
if it is a string, it is treated as a path.

Ralf: ODATA-1203 is OPEN

7. Next meetings

Agreed next meetings:

Thursday August 30, 2018 during 8-10 am PDT (17:00-19:00 CEST)
Thursday September 06, 2018 during 8-10 am PDT (17:00-19:00 CEST)

George: may not be able to attend on September 06

8. AOB and wrap up

Hotels for F2F

Name of hotel: Element Seattle Redmond
Street: 15220 NE SHEN ST SUITE 100
Postal code/City: 98052 Redmond (United States)

Ralf: That's where Gerald and I will stay

Meeting adjourned by chair.