OData TC meeting #169 Thursday Apr 06, 2017

Acting chair: Ralf

Chat transcript from room: odatatc
2017-04-06 0800-1000 PDT

1. Roll call

1.1 Members present

    George Ericson (Dell)
    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=43972).

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

2. Approve agenda

Agenda approved unchanged as published.

3. Approve minutes from previous meeting(s)

3.1 Minutes from March 30, 2017 TC meeting #168

https://www.oasis-open.org/committees/download.php/60407/odata-meeting-168_on-20170330-minutes.html

Minutes approved unchanged as published.

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

4.1 Action items due

None

5. V4.01

5.1 Issues for V4.01_CSD02 ready for resolution

5.1.1 ODATA-1063 - Allow $format and custom query options for all requests

Ralf: ODATA-1063 is OPEN

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

Ralf: ODATA-1063 is RESOLVED as proposed

5.1.2 ODATA-1061 - Allow key expressions in Path constructs within annotations

Ralf: ODATA-1061 is OPEN

Ralf:

<Annotation Term="Display.visible" Path="/this.container/Settings/FeatureXxxIsAvailable" />
<Annotation Term="Display.visible" Path="/this.container/SettingsCollection('FeatureXxx')/IsAvailable" />
<Annotation Term="Display.title" Path="/this.container/Products(ID=ProductID)Name" />
<Annotation Term="Display.title" Path="/this.container/Products(ID=ProductID)/Name" />
<Annotation Term="Display.title" Path="/this.container/Products(IProductID)Name" />
<Annotation Term="Display.title" Path="/this.container/Products(ProductID)Name" />
<Annotation Term="Display.title" Path="/this.container/Products(ProductID)/Name" />
<Annotation Term="Display.title" Path="/this.container/OrderItems(OrderID=42,ItemID=2)/Price" />
<Annotation Term="Display.title" Path="/this.container/Products(Product/ID)/Name" /> -- path for fetching key value

Ralf: Only literals and paths allowed as "key values", no arithmetic expressions or functions

Hubert: I move to resolve ODATA-1061 as per the amended proposal. Mark seconds.

Ralf: ODATA-1061 is RESOLVED

5.1.3 ODATA-1057 - Add path segment /$each

[17:32] anonymous morphed into George Ericson (Dell)

Mike: I move we resolve ODATA-1057 as proposed. Hubert seconds.

Ralf: ODATA-1057 is RESOLVED

5.1.4 ODATA-1058 - Add ability to annotate revisions with information on all elements

Ralf: The proposal is to create a 'Revision' term in the Core vocabulary that may be applied to any element. Elements defined in a schema may then evolve over time and with their complete revision history intact. The proposal is as follows:

<Term Name="Revision" Type="CsdlMetamodel.RevisionType"> 
  <Annotation Term="OData.Description" String="Defines an annotation to mark a revision." /> 
</Term>

Mike:

<EnumType Name="RevisionKind"> 
  <Member Name="Add"/> 
  <Member Name="Insert"/> 
  <Member Name="Change"/> 
  <Member Name="Delete"/> 
  <Member Name="Deprecate"/> 
</EnumType>

Mike:

<ComplexType Name="RevisionType"> 
  <Property Name="Version" Type="Edm.String"> 
    <Annotation Term="OData.Description" String="An 'm.n.e' string value composed of three decimal values separated by '.'. 
    These values express major, minor, and errata version numbers for this revision where 'm' is an integer representing 
    a major version. Major versions are expected to provide similar but extended functionality, but may be incompatible in 
    any way. The minor version 'n' may include additional features and may not remove any features from previous minor 
    versions of the same major version. The set of allowable values must include all allowable values of previous minor versions 
    of the same major version. The errata version 'e' is used to mark a change that fixes something that was broken in the 
    including minor version. By its nature, an errata version may include incompatible changes to fix a prior version."/> 
  </Property> 
  <Property Name="Type" Type="CsdlMetamodel.RevisionKind"> 
    <Annotation Term="Core.Description" String="An enumerated value expressing the type of revision." /> 
  </Property> 
  <Property Name="Description" Type="String"> 
    <Annotation Term="Core.Description" String="Text description of the reason for the revision." /> 
  </Property> 
</ComplexType>

Ralf: Expection: revisions cumulate over time, so revision needs to state which version it was introduced

<Property Name="NewProp" ...>
  <Annotation Term="Core.Revision" Qualifier="first">
    <Record>
      <PropertyValue Property="Version" String="10.4.1" />
      <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Insert" />
    </Record>
  </Annotation>
</Property>

Ralf: In JSON:

"@Core.Revision#first":{"Version":"10.4.1","Type":"Insert"}

Ralf: Multiple revisions of the same model element:

<Property Name="NewProp" ...>
  <Annotation Term="Core.Revision" Qualifier="first">
    <Record>
      <PropertyValue Property="Version" String="10.4.1" />
      <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Insert" />
    </Record>
  </Annotation>
  <Annotation Term="Core.Revision" Qualifier="second">
    <Record>
      <PropertyValue Property="Version" String="10.4.2" />
      <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Deprecate" />
    </Record>
  </Annotation>
</Property>

Mike:

<Annotation Term="Core.Revision" Qualifier="v10_4_1">
  <Record>
    <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Insert" />
  </Record>
</Annotation>

Ralf: Alternative: collection-valued annotation:

<Property Name="NewProp" ...>
  <Annotation Term="Core.Revision">
    <Collection>
      <Record>
        <PropertyValue Property="Version" String="10.4.1" />
        <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Insert" />
      </Record>
      <Record>
        <PropertyValue Property="Version" String="10.4.2" />
        <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Deprecate" />
      </Record>
    </Collection>
  </Annotation>
</Property>

Mike: Updated term definition:

<Term Name="Revision"  Type="Collection(CsdlMetamodel.RevisionType)">
  <Annotation Term="OData.Description" String="Defines an annotation to mark a revision." />
</Term>

Ralf: George, Martin, Mark, and Mike like the collection-valued notation

Ralf: It also allows ordering of revisions by version/time

Ralf: Example for description via annotation:

<Record>
  <PropertyValue Property="Version" String="10.4.2" />
  <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Deprecate" />
  <Annotation Term="Core.Description" String="Cool new property requested by BigCustomer" />
</Record>

Ralf: Example for description via property:

<Record>
  <PropertyValue Property="Version" String="10.4.2" />
  <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Deprecate" />
  <PropertyValue Property="Description" String="Cool new property requested by BigCustomer" />
</Record>

Ralf: Example for description via annotation:

"@Core.Revision":[{
  "Version":"10.4.2",
  "Type":"Add" />
  "@Core.Description":"Cool new property requested by BigCustomer"
}]

Ralf: Example for description via annotation:

"@Core.Revision":[{
  "Version":"10.4.2",
  "Type":"Add",
  "Description":"Cool new property requested by BigCustomer"
}]

Mike: Has slight preference for second variant with explicit Description property

Ralf: Is more explicit in the term definition

<EnumType Name="RevisionKind"> 
  <Member Name="Add"/> 
  <Member Name="Insert"/> 
  <Member Name="Change"/> 
  <Member Name="Delete"/> 
  <Member Name="Deprecate"/> 
</EnumType>

Ralf: Ralfs preference: New, Changed, Deprecated

Mike: Added, Changed, Deprecated

George: Add, Change, Deprecate

Mike: keep "Deleted" and add an optional property "ChildElement"

Mike: If RevisionKind is changed, you could add a structured property that was membername and revisionkind ... (including deleted)

Ralf: Example for Deleted:

<EntityType Name="...
  <Annotation Term="Core.Revision">
    <Collection>
      <Record>
        <PropertyValue Property="Version" String="10.4.2" />
        <PropertyValue Property="Type" EnumMember="Core.RevisionKind/Deleted" />
        <PropertyValue Property="Description" String="Unused property removed" />
        <PropertyValue Property="ChildElement" String="SomeRandomProperty" />
      </Record>
    </Collection>
  </Annotation>
</EntityType>

George: Deletion should only happen when moving to the next major version, so Deleted annotation is not really necessary

Ralf: So no ChildElement, and directly annotate the added/changed/deprecated model element

George: Points out annotating the structured object would require multiple records with the same version ...

Mike: use "Kind" for property name and enumtype name suffix instead of "Type"

Martin: use "Kind"

George: XML uses "Kind" for enumerations

Ralf: Enumeration member names: Added, Modified, Deprecated

Mike: The proposal is to create a 'Revision' term in the Core vocabulary that may be applied to any element. Elements defined in a schema may then evolve over time and with their complete revision history intact. The proposal is as follows:

<Term Name="Revision"  Type="Collection(CsdlMetamodel.RevisionType)">
  <Annotation Term="OData.Description" String="Defines an annotation to mark a revision." />
</Term>

The members of the collection are sequential.

<ComplexType Name="RevisionType">
  <Property Name="Version" Type="Edm.String">
    <Annotation Term="OData.Description" String="An 'm.n.e' string value composed of three decimal values separated by '.'.  
    These values express major, minor, and errata version numbers for this revision where 'm' is an integer representing 
    a major version.  Major versions are expected to provide similar but extended functionality, but may be incompatible in 
    any way. The minor version 'n' may include additional features and may not remove any features from previous minor 
    versions of the same major version.  The set of allowable values must include all allowable values of previous minor versions 
    of the same major version. The errata version 'e' is used to mark a change that fixes something that was broken in the 
    including minor version.  By its nature, an errata version may include incompatible changes to fix a prior version."/>
  </Property>
  <Property Name="Kind" Type="CsdlMetamodel.RevisionKind">
    <Annotation Term="Core.Description" String="An enumerated value expressing the type of revision." />
  </Property>
  <Property Name="Description" Type="String">
    <Annotation Term="Core.Description" String="Text description of the reason for the revision." />
  </Property>
</ComplexType>

<EnumType Name="RevisionKind">
  <Member Name="Added"/>
  <Member Name="Modified"/>
  <Member Name="Deprecated"/>
</EnumType>

Ralf: ODATA-1058 is OPEN

Martin: I move we resolve ODATA-1058 as proposed (revised proposal see chat). Mike seconds.

Ralf: ODATA-1058 is RESOLVED

Martin: proposal is updated in jira

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

Skipped

5.2 Document walkthrough

5.2.1 Part 1: Protocol

URL = https://www.oasis-open.org/committees/download.php/60437/odata-v4.01-wd02-part1-protocol-2017-04-05.docx

All walk through the document, discuss and perform online changes during the meeting.

5.2.2 Part 2: URL Conventions

URL = https://www.oasis-open.org/committees/download.php/60438/odata-v4.01-wd02-part2-url-conventions-2017-04-05.docx

Skipped

5.2.3 JSON Format

URL = https://www.oasis-open.org/committees/download.php/60365/odata-json-format-v4.01-wd02-2017-03-24.docx

Skipped

5.2.4 CSDL JSON Representation

URL = https://www.oasis-open.org/committees/download.php/60363/odata-csdl-json-v4.01-wd01-2017-03-24.docx

Skipped

5.2.5 CSDL XML Representation

URL = https://www.oasis-open.org/committees/download.php/60364/odata-csdl-xml-v4.01-wd02-2017-03-24.docx

Skipped

5.2.6 New in OData 4.01

URL = https://www.oasis-open.org/committees/download.php/60439/new-in-odata-v4.01-wd01-2017-04-05.docx

Skipped

6. Next meetings

6.2 Meeting on April 13, 2017, during 08:00-10:00 am PDT

Ralf: (17:00-19:00 CEST) already confirmed

6.2 Meeting after that on April 20, 2017, during 08:00-10:00 am PDT

Mark: Can't attend week after next

7. AOB and wrap up

None

Meeting adjourned by chair.