OData TC meeting #232 Thursday October 04, 2018

Acting chair: Ralf

Chat transcript from room: odatatc
2018-10-04 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)
    Ramesh Reddy (Red Hat)
    Stefan Hagen (Individual)
    Ted Jones (Red Hat)

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

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 September 27/28, 2018 Face-to-Face Meeting #231

URL = https://www.oasis-open.org/committees/download.php/64003/odata-meeting-231_on-20180927-and-20180928-minutes-f2f.html

Minutes are approved unchanged as published.

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

Nothing noted

5. Issues

5.1 GitHub Pull Requests

5.1.1 ODATA-xxx - ttt

i.ODATA-1212: Validation.AllowedTerms - https://github.com/oasis-tcs/odata-vocabularies/pull/18

Ralf: Application of https://issues.oasis-open.org/browse/ODATA-1212

<Annotations Target="C_PURCHASEORDER_FS_SRV.C_PurchaseOrderFsType">
  <Annotation Term="UI.Facets">
    <Collection>
      <Record Type="UI.CollectionFacet">
        <PropertyValue Property="Label" String="General Information"/>
        <PropertyValue Property="ID" String="GeneralInfo"/>
        <PropertyValue Property="Facets">
          <Collection>
            <Record Type="UI.ReferenceFacet">
              <Annotation Term="UI.IsSummary"/>
              <Annotation Term="UI.PartOfPreview"/>
              <PropertyValue Property="Label" String="Basic Data"/>
              <PropertyValue Property="ID" String="BasicData"/>
              <PropertyValue AnnotationPath="@UI.Identification" Property="Target"/>
            </Record>
            <Record Type="UI.ReferenceFacet">
              <PropertyValue Property="Label" String="Delivery and Payment"/>
              <PropertyValue Property="ID" String="DelivAndPayment"/>
              <PropertyValue AnnotationPath="@UI.FieldGroup#DelivAndPayment" Property="Target"/>
            </Record>
            <Record Type="UI.ReferenceFacet">
              <PropertyValue Property="Label" String="Recipient"/>
              <PropertyValue Property="ID" String="Recipient"/>
              <PropertyValue AnnotationPath="@UI.FieldGroup#Recipient" Property="Target"/>
            </Record>
          </Collection>
        </PropertyValue>
      </Record>
      <Record Type="UI.ReferenceFacet">
        <PropertyValue Property="Label" String="Items"/>
        <PropertyValue Property="ID" String="Items"/>
        <PropertyValue AnnotationPath="to_PurchaseOrderItem/@UI.LineItem" Property="Target"/>
      </Record>
      <Record Type="UI.ReferenceFacet">
        <PropertyValue Property="Label" String="Purchase Requisition Items"/>
        <PropertyValue Property="ID" String="PurchReqItm"/>
        <PropertyValue AnnotationPath="to_PurReqItemByPurOrder/@UI.LineItem#PurchReqItemByPurOrder" Property="Target"/>
      </Record>
    </Collection>
  </Annotation>

Ralf: Current definition:

<ComplexType Name="ReferenceFacet" BaseType="UI.Facet">
  <Annotation Term="Core.Description" String="Facet that refers to a thing perspective, e.g. LineItem" />
  <Property Name="Target" Type="Edm.AnnotationPath" Nullable="false">
    <Annotation Term="Core.Description"
      String="Referenced information: Communication.Contact, Communication.Address, or a term that is tagged with UI.ThingPerspective, e.g. UI.StatusInfo, UI.LineItem, UI.Identification, UI.FieldGroup, UI.Badge" />
  </Property>
</ComplexType>

Ralf: Would become:

<ComplexType Name="ReferenceFacet" BaseType="UI.Facet">
  <Annotation Term="Core.Description" String="Facet that refers to a thing perspective, e.g. LineItem" />
  <Property Name="Target" Type="Edm.AnnotationPath" Nullable="false">
    <Annotation Term="Core.Description"
      String="Referenced information: Communication.Contact, Communication.Address, or a term that is tagged with UI.ThingPerspective, e.g. UI.StatusInfo, UI.LineItem, UI.Identification, UI.FieldGroup, UI.Badge" />
  </Property>
</ComplexType>

<ComplexType Name="ReferenceFacet" BaseType="UI.Facet">
  <Annotation Term="Core.Description" String="Facet that refers to a thing perspective, e.g. LineItem" />
  <Property Name="Target" Type="Edm.AnnotationPath" Nullable="false">
    <Annotation Term="Core.Description">
      <Collection>
        <String>Communication.Contact</String>
        ...
      </Collection>
    </Annotation>
    <Annotation Term="Core.Description"
      String="Referenced information: Communication.Contact, Communication.Address, or a term that is tagged with UI.ThingPerspective, e.g. UI.StatusInfo, UI.LineItem, UI.Identification, UI.FieldGroup, UI.Badge" />
  </Property>
</ComplexType>

<ComplexType Name="ReferenceFacet" BaseType="UI.Facet">
  <Annotation Term="Core.Description" String="Facet that refers to a thing perspective, e.g. LineItem" />
  <Property Name="Target" Type="Edm.AnnotationPath" Nullable="false">
    <Annotation Term="Validation.AllowedTerms">
      <Collection>
        <String>Communication.Contact</String>
        ...
      </Collection>
    </Annotation>
    <Annotation Term="Core.Description"
      String="Referenced information: Communication.Contact, Communication.Address, or a term that is tagged with UI.ThingPerspective, e.g. UI.StatusInfo, UI.LineItem, UI.Identification, UI.FieldGroup, UI.Badge" />
  </Property>
</ComplexType>

Mike: Annotate a property or term of type AnnotationPath to restrict the terms that can be targeted by the path.

Ralf: Ralf to update the pull request

5.1.2 Request TC GitHub Repository for ANTLR grammar for URL Conventions

GitHub repository name: odata-antlr
Maintainers
  Hubert Heijkers, hubert-heijkers, hubert@heijkers.com
  Stefan Hagen, sdrees, stefan@hagen.link
  Mike Pizzo, mikepizzo, mikep@microsoft.com
  Ralf Handl, ralfhandl, ralf.handl@sap.com
Description: Supporting an ANTLR grammar for OData URLs
Purpose statement: This repository contains an ANTLR-based grammar for OData Uniform Resource Identifiers. 
Notes:

Hubert: I move to have the chair request the creation of the odata-antlr git repository with the above mentioned description. George

.

Ralf: Motion passes, Ralf to request Github repo

5.2 NEW or OPEN

5.2.1 ODATA-1236 - What should be returned for inserted non-entity value?

Ralf: JSON PATCH format: https://tools.ietf.org/html/rfc6902

Ralf: Example

   PATCH /my/data HTTP/1.1
   Host: example.org
   Content-Length: 326
   Content-Type: application/json-patch+json
   If-Match: "abc123"
   [
     { "op": "test", "path": "/a/b/c", "value": "foo" },
     { "op": "remove", "path": "/a/b/c" },
     { "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] },
     { "op": "replace", "path": "/a/b/c", "value": 42 },
     { "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
     { "op": "copy", "from": "/a/b/d", "path": "/a/b/e" }
   ]
[17:43] Ralf Handl (SAP SE): A.2.  Adding an Array Element
   An example target JSON document:

   { "foo": [ "bar", "baz" ] }

   A JSON Patch document:

   [
     { "op": "add", "path": "/foo/1", "value": "qux" }
   ]

   The resulting JSON document:

   { "foo": [ "bar", "qux", "baz" ] }
 

Ralf: would expect, if a response was returned, it would be the collection.

Hubert: would expect, if a response was returned, it would be the added item.

George: what if you do an POST to collection/$index?

Mike: (mea culpa) $index is a query option: orderedCollection?$index=10

Mike: consensus: we are (still) okay returning the updated collection.

Mike: Updated proposal:

1) We shouldn't have different behavior for ordered versus non-ordered collections.
2) Inserting into a non-entity collection (in general) isn't creating a resource, 
   so 201 is not appropriate, which resolves the issue of the location and entity-id headers.
3) By default, we should return 204, no content (and no body)
4) If we support the return=representation header, we should return the updated collection.

Ralf: ODATA-1236 is OPEN

Hubert: I move to resolve ODATA-1236 as per the amended proposal. Mike seconds.

Ralf: ODATA-1236 is RESOLVED as proposed

5.2.2 ODATA-1237 - How to specify static result entity set for bound actions/functions?

Ralf: Description

Bound actions/functions that return a single entity or a collection of entities can specify the 
entity set of the returned entities relative to the binding parameter via the EntitySetPath attribute.

How to specify that the returned entities always belong to a statically known entity set that 
cannot be reached via navigation from the binding parameter type?

Mike:

we intentionally constructed bound functions/actions this way to make the function/action definition 
independent from the schema that defines the binding target
also we nowhere have references from Schema children to an Entity Container
extended path syntax for EntitySetPath would be restricted to V4.01 schemas to not break existing clients
softer solution would be an annotation. It could also be used in V4 schemas because it can be ignored.
My other concern would be that, if we allow an absolute path to an entityset for the entitysetpath, 
that people will default to always specifying that entityset path even if the relative path exists.

Ralf: Example:

EntityType Name=Customer
- NavigationProperty Name=to_Orders

Function Name=OutstandingOrders
- Binding Parameter Name=__in Type=s.Customer
- EntitySetPath=__in/to_Orders

Mike: That works as long as to_Orders is contained or has a navigationpropertybinding.

Ralf: ODATA-1237 is OPEN

Ralf: Proposal

No action.

We intentionally constructed bound functions/actions this way to make the function/action definition 
independent from the schema that defines the binding target.

Also we intentionally don't have references from Schema children to an Entity Container.

Model designers are encourage to add navigation paths that allow them specifying an EntitySetPath.

Ralf: Corrected:

No action.

We intentionally constructed bound functions/actions this way to make the function/action definition 
independent of the schema that defines the binding target.

Also we intentionally don't have references from Schema children to an Entity Container.

Model designers are encouraged to add navigation paths that allow them specifying an EntitySetPath.

Mike: I move we resolve ODATA-1237 with no action. Hubert seconds.

Ralf: ODATA-1237 is CLOSED without action

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

Ralf: George and Mike to prepare examples and walk us through the proposal

Mike: Discussion:

Control information and annotations are different metamodel concepts that happen to have 
the same representation in the json payload.
Protocol operations that target control information should be specific to control information, 
and protocol operations that target annotations should be specific to things within the annotation metamodel concept.

6. Next meetings

Agreed next meetings:

Thursday October 11, 2018 during 8-10 am PDT (17:00-19:00 CEST)
Thursday October 18, 2018 during 8-10 am PDT (17:00-19:00 CEST)

7. AOB and wrap up

Meeting adjourned by chair.