OData TC meeting #202 Thursday February 08, 2018

Acting chair: Ralf

Chat transcript from room: odatatc
2018-02-08 0800-1000 PST

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Kraue (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=46242).

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 February 01, 2018 TC meeting #201

https://www.oasis-open.org/committees/download.php/62433/odata-meeting-201_on-20180201-minutes.html

Minutes approved unchanged as published.

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

4.1 Action items due

None.

5. Issues

5.1 V4.01: NEW or OPEN

5.1.1 ODATA-1146 - Clarify that an enumeration type must have at least one member

Ralf: ODATA-1146 is OPEN

Mike: I move we resolve ODATA-1146 as proposed, clarifying the wording that enum types MUST contain one or more members, as intended and consistent with 4.0 and JSON. George seconds.

Ralf: ODATA-1146 is RESOLVED as proposed

5.1.2 ODATA-1144 - Allow percent-encoded colon in time values in URLs

Ralf: ODATA-1144 is OPEN

George: I move to approve ODATA-1144 as proposed. Mike seconds.

Ralf: ODATA-1144 is RESOLVED as proposed

5.2 Vocabularies: NEW or OPEN

5.2.1 ODATA-1145 - Align Authorization vocabulary with OpenAPI V3

Ralf: ODATA-1145 is OPEN

Mike: Current Authorizations vocabulary:

<Term Name="Authorizations" Type="Collection(Auth.Authorization)" AppliesTo="EntityContainer EntitySet Singleton NavigationProperty Action Function">
  <Annotation Term="Core.Description" String="Lists the methods available to authorize access to the annotated resource" />
</Term>
<ComplexType Name="Authorization" Abstract="true">
  <Annotation Term="Core.Description" String="Base type for all Authorization types" />
  <Property Name="Description" Type="Edm.String">
    <Annotation Term="Core.Description" String="Description of the authorization method" />
  </Property>
</ComplexType>
<ComplexType Name="OpenIDConnect" BaseType="Auth.Authorization">
  <Property Name="IssuerUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description"
      String="Issuer location for the OpenID Provider. Configuration information can be obtained by appending `/.well-known/openid-configuration` to this Url." />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="Http" BaseType="Auth.Authorization">
  <Property Name="Scheme" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="HTTP Authorization scheme to be used in the Authorization header, as per RFC7235" />
  </Property>
  <Property Name="BearerFormat" Type="Edm.String">
    <Annotation Term="Core.Description" String="Format of the bearer token" />
  </Property>
</ComplexType>
<ComplexType Name="OAuthAuthorization" BaseType="Auth.Authorization" Abstract="true">
  <Property Name="Scopes" Type="Collection(Auth.AuthorizationScope)">
    <Annotation Term="Core.Description" String="Available scopes" />
  </Property>
  <Property Name="RefreshUrl" Type="Edm.String">
    <Annotation Term="Core.Description" String="Refresh Url" />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="OAuth2ClientCredentials" BaseType="Auth.OAuthAuthorization">
  <Property Name="TokenUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Token Url" />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="OAuth2Implicit" BaseType="Auth.OAuthAuthorization">
  <Property Name="AuthorizationUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Authorization URL" />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="OAuth2Password" BaseType="Auth.OAuthAuthorization">
  <Property Name="TokenUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Token Url" />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="OAuth2AuthCode" BaseType="Auth.OAuthAuthorization">
  <Property Name="AuthorizationUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Authorization URL" />
    <Annotation Term="Core.IsURL" />
  </Property>
  <Property Name="TokenUrl" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Token Url" />
    <Annotation Term="Core.IsURL" />
  </Property>
</ComplexType>
<ComplexType Name="AuthorizationScope">
  <Property Name="Scope" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="Scope name" />
  </Property>
  <Property Name="Description" Type="Edm.String">
    <Annotation Term="Core.Description" String="Description of the scope" />
  </Property>
</ComplexType>
<ComplexType Name="ApiKey" BaseType="Auth.Authorization">
  <Property Name="KeyName" Type="Edm.String" Nullable="false">
    <Annotation Term="Core.Description" String="The name of the header or query parameter" />
  </Property>
  <Property Name="Location" Type="Auth.KeyLocation" Nullable="false">
    <Annotation Term="Core.Description" String="Whether the API Key is passed in the header or as a query option" />
  </Property>
</ComplexType>
<EnumType Name="KeyLocation">
  <Member Name="Header">
    <Annotation Term="Core.Description" String="API Key is passed in the header" />
  </Member>
  <Member Name="QueryOption">
    <Annotation Term="Core.Description" String="API Key is passed as a query option" />
  </Member>
  <Member Name="Cookie">
    <Annotation Term="Core.Description" String="API Key is passed as a cookie" />
  </Member>
</EnumType>

Mike: ODATA-1145 proposal:

1) Add the following property to the Auth.Authorization complex type:

<Property Name="Name" Type="Edm.String">
  <Annotation Term="Core.Description" String="Name that can be used to reference the authorization flow."/>
</Property>

2) Add the following new complex type to the Auth vocabulary:
<ComplexType Name="SecurityScheme">
  <Property Name="AuthorizationSchemeName" Type="Edm.String">
    <Annotation Term="Core.Description" String="The name of a required authorization scheme"/>
  </Property>
  <Property Name="RequiredScopes" Type="Collection(Edm.String">
    <Annotation Term="Core.Description" String="The names of scopes required from this authorization scheme."/>
  </Property>
<ComplexType>

3) Add the following property to the new HTTPRequest type proposed in ODATA-884:
<Property Name="SecuritySchemes" Type="Collection(Auth.SecurityScheme)">
  <Annotation Term="Core.Description" String="At least one of the specified security schemes are required to make the request."/>
</Property>

Mike: Add proposal:

4) Add the following term that can be applied to an EntityContainer.
<Term Name="SecuritySchemes" Type="Collection(Auth.SecurityScheme)" AppliesTo="EntityContainer">
  <Annotation Term="Core.Description" String="At least one of the specified security schemes are required to make a request against the service."/>
</Term>

Mike: Updated #3:

3) Add the following property to the new HTTPRequest type proposed in ODATA-884:
<Property Name="SecuritySchemes" Type="Collection(Auth.SecurityScheme)">
  <Annotation Term="Core.Description" 
    String="At least one of the specified security schemes are required to make the request. This overrides any SecuritySchemes specified on the EntityContainer."/>
</Property>

Mike: I move to resolve ODATA-1145 as proposed. George seconds.

Ralf: ODATA-1145 is RESOLVED as proposed

5.2.2 ODATA-1140 - Add details to HTTPResponseCode term

Mike: Note: this would be useful for documentation; not particularly useful for clients at runtime.

Services do tend to have service-specific error codes and descriptions, but there are typically a lot of them so documenting for each request may be verbose.

Ralf: ODATA-1140 is OPEN

Mike: It doesn't appear from a very quick read that OpenAPI has a similar concept in their Response object.

Mike: Renamed ODATA-884 to "Enable enumerating the valid requests and responses for a particular resource."

Mike: I move we move ODATA-1140 out of 4.01 CS02 to some undefined future. Ralf seconds.

Ralf: No objection, motion passes

5.2.3 ODATA-1132 - Propagation of NavigationRestrictions

Ralf: Clarify whether/how navigation restrictions "propagate".

Assume we have 
- Order entity related to single Customer entity 
- Customer entity related to multiple Address entities 
- a navigation restriction on Customers entity set which lists Addresses as filterable:false. 

Now a client knows that it cannot filter Customers by Addresses. 

Should a client assume that it also cannot filter Orders by Customer/Addresses? 

Or would the service have to explicitly declare navigation restrictions for all entity sets with navigation paths ending in Customer/Addresses?

Mike: propagation would require a navigation property binding to be able to identify another source for navigation restrictions

Mike: restrictions may depend on the path

Ralf: Question: is it easier for the server to produce more restrictions, or for the client to walk through all possible navigation paths

George: put burden on service

Mike: makes $metadata more verbose

Mike: In all but the most hypothetical situations, the client would be safe in assuming that restrictions on the entity set applied to restrictions on navigation properties referencing the entity set.

Mike: Proposal: State that clients can assume that restrictions specified on an entity set are valid whether the request is to the entity set or through a navigation property bound to that entity set.

Ralf: means restrictions propagate if there is a nav prop binding

Hubert: can we override a "propagated" restriction?

Mike: Service could specify a different set of restrictions specific to a path, in which case any specified restrictions take precedence.

Mike: Updated (working) proposal:

State that clients can assume that restrictions specified on an entity set are 
valid whether the request is to the entity set or through a navigation property 
bound to that entity set.  
Service could specify a different set of restrictions specific to a path, 
in which case any specified restrictions take precedence.

Ralf: I move to resolve ODATA-1132 as proposed. Hubert seconds.

Ralf: ODATA-1132 is RESOLVED as proposed

5.2.4 ODATA-1121 - Add FilterExpressionType values "MultiRange" and "MultiRangeOrSearchExpression"

Ralf:

Filter expression restrictions where introduced in ODATA-816 to express 
restricted filter capabilities on individual properties that can only be 
used in equality comparison or interval comparison. 

Similar to MultiValue being multiple SingleValues joined by OR, MultiRange 
is multiple SingleRanges joined by OR, with a slight generalization: in 
addition to closed intervals also half-open and open intervals are allowed, 
as well as degenerate intervals (closed intervals with identical lower 
and upper boundary can be expressed simply via EQ). 

This means that MultiRange subsumes SingleRange as well as MultiValue and SingleValue. 

For string-valued properties this can be extended to include multiple SearchExpressions: 
MultiRangeOrSearchExpression, allowing to OR zero or more startswith, endswith, 
or contains functions comparing the property to a string literal. 

These expressions are all fairly simple, including a property, a literal value, 
and at most one level of parentheses. They represent expressions that can be 
constructed by typical "extended search" forms that allow to pick the comparison 
operator and enter the comparison value (or two values for "between").

Ralf: Add new allowed values

<Record> 
  <PropertyValue Property="Value" String="MultiRange" /> 
  <Annotation Term="Core.Description" String="Property can be compared to a union of one or more closed, half-open, or open intervals" /> 
  <Annotation Term="Core.LongDescription" 
    String="The filter expression for this property consists of one or more interval expressions combined by OR. 
            A single interval expression is either a single comparison of the property and a literal value with eq, 
            le, lt, ge, or gt, or pair of boundaries combined by AND and enclosed in parentheses. 
            The lower boundary is either ge or gt, the upper boundary either le or lt." /> 
</Record> 
<Record> 
  <PropertyValue Property="Value" String="MultiRangeOrSearchExpression" /> 
  <Annotation Term="Core.Description" 
    String="Property can be compared to a union of zero or more closed, half-open, 
            or open intervals plus zero or more simple string patters" /> 
  <Annotation Term="Core.LongDescription" 
    String="The filter expression for this property consists of one or more interval expressions or string comparison functions combined by OR. 
            See MultiRange for a definition of an interval expression. See SearchExpression for the allowed string comparison functions." /> 
</Record>

Ralf:

a lt 5 or (a ge 9 and a le 11)
a lt 'Hugo' or startswith(a, 'Fred')

Ralf: ODATA-1121 is OPEN

5.2.5 ODATA-1099 - Add annotations to describe custom query options and custom headers

Skipped

5.2.6 ODATA-1067 - Consider ability to define computed default values

Skipped

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

Skipped

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

Skipped

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

Skipped

6. Next meetings

Ralf:

Thursday February 15, 2018 during 8-10 am PST (17:00-19:00 CET) (already confirmed)
Thursday February 22, 2018 during 8-10 am PST

7. AOB and wrap up

None

Meeting adjourned by chair.