OData TC meeting #190 Thursday October 05, 2017

Acting chair: Ralf

Chat transcript from room: odatatc
2017-10-05 0800-1000 PDT

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Krause (SAP SE)
    Hubert Heijkers (IBM)
    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=43998).

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

2. Approve agenda

Hubert: discuss timeline first

Agenda approved as published with the above change

3. Approve minutes from previous meeting(s)

3.1 Minutes from September 28, 2017 TC meeting #189

https://www.oasis-open.org/committees/download.php/61673/odata-meeting-189_on-20170928-minutes.html

Minutes approved unchanged as published.

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

4.1 Action items due

None

5. Timeline and next steps

5.1 Timeline Proposal

URL: https://www.oasis-open.org/committees/download.php/61677/TC Timeline-2017-09-29.docx

Ralf: Publishing of new Vocabulary revisions: consider publishing Errata04, cross-check if adding terms is problematic, and whether we did that in the past

6. Issues

6.1 Vocabularies: APPLIED

6.1.1 ODATA-958 - Capabilities: FilterRestrictions and SortRestrictions for navigation properties

Need guidance on how to use: URL = https://issues.oasis-open.org/browse/ODATA-958?focusedCommentId=67703&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-67703

Ralf: Add three new properties, FilterFunctions, FilterRestrictions, and SortRestrictions, to Capabilities.NavigationPropertyRestriction

Ralf: After this addition I wonder where I should annotate filter and sort restrictions for contained entities:

* FilterRestrictions and SortRestrictions on the containment navigation property (only way before applying this issue), or 
* NavigationRestrictions on the "parent" entity set with the "container" entities 

Which restrictions would apply to direct access to the contained set: 
* GET Whole(42)/Parts?$filter=...&$orderby=... 

Which restrictions would apply to nested query options within expand: 
* GET Whole?$expand=Parts($filter=...;$orderby=...)
<Annotations Target="schema.container/Whole/Parts">
<Annotation Term="FilterRestrictions" ..

OR

<Annotations Target="schema.container/Whole">
  <Annotation Term="NavigationRestrictions">
    ...
     <FilterRestrictions...

Mike: I want to discourage

<NavigationProperty Name="Parts"><Annotation Term="FilterRestrictions">...</></>

Mike: One option would be to roll-back ODATA-958, allow FilterRestrictions, OrderRestrictions, and FilterFunctions to be applied to any collection, and encourage the best practice of applying these annotations through external targeting for reusability of types (that is, applied to any collection-valued property as well as entity set).

Ralf: Another nit:
FilterRestrictions and SortRestrictions apply to EntitySet Collection
ExpandRestrictions and NavigationRestrictions apply to EntitySet Collection EntityType

Mike: I think it was a mistake to say that the last two could be applied to an entity type. This seems an anti-pattern that has no additional benefit.

Mike: I can see reasons to annotate on either the EntitySet, or a collection-valued (navigation) property, but not at the EntityType level.

Ralf:

<Term Name="ExpandRestrictions" Type="Capabilities.ExpandRestrictionsType" AppliesTo="EntitySet Collection EntityType">
  <Annotation Term="Core.Description" String="Restrictions on $expand expressions" />
</Term>
<ComplexType Name="ExpandRestrictionsType">
  <Property Name="Expandable" Type="Edm.Boolean" DefaultValue="true">
    <Annotation Term="Core.Description" String="$expand is supported" />
  </Property>
  <Property Name="NonExpandableProperties" Type="Collection(Edm.NavigationPropertyPath)" Nullable="false">
    <Annotation Term="Core.Description" String="These properties cannot be used in $expand expressions" />
  </Property>
  <Property Name="MaxLevels" Type="Edm.Int32" DefaultValue="-1">
    <Annotation Term="Core.Description"
      String="The maximum number of levels that can be expanded in a $expand expression. A value of -1 indicates there is no restriction." />
  </Property>
</ComplexType>

Ralf: Postpone to next meeting

Ralf to craft examples showing both alternatives

Ralf: Note: ExpandRestrictions not yet sub-structure of NavigationRestrictions, so either include all xxxRestrictions in NavigationRestrictions moving forward, or back out ODATA-958

6.1.2 ODATA-1055 - DeepInsertSupport: allow applying to entity sets and collection-valued navigation properties

Ralf: Adding EntitySet is fine, adding Collection has to be reconsidered along with ODATA-958

Ralf: Postponed after closing ODATA-958

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

Ralf: Needs more discussion, to be prepared offline

6.1.4 ODATA-1069 - New term Core.OperationAvailable

Ralf: Add to the Core vocabulary:

<Term Name="OperationAvailable" Type="Edm.Boolean" DefaultValue="true" AppliesTo="Action Function"> 
  <Annotation Term="Core.Description" String="Action or function is available" /> 
</Term>

Ralf: Applied as:

<Term Name="OperationAvailable" Type="Edm.Boolean" DefaultValue="true" AppliesTo="Action Function">
  <Annotation Term="Core.Description" String="Action or function is available" />
  <Annotation Term="Core.LongDescription"
    String="The annotation value will usually be an expression, e.g. using properties of the binding parameter type for instance-dependent availability, or using properties of a singleton for global availability." />
</Term>

Mike: Example usage:

<Annotation Term="Capabilties.OperationAvailable"> 
  <Ne> 
    <Path>bindingParam/OrderStatus</Path> 
    <String>SHIPPED</String> 
  </Ne> 
</Annotation>

Mike: I move we approve the application of OData-1069. Stefan seconds.

Ralf: ODATA-1069 is CLOSED as applied

6.1.5 ODATA-1079 - Several issues with latest standard vocabularies

Ralf: Org.OData.Core.V1.xml

<ComplexType Name="AlternateKey"> 
  <Property Type="Collection(Core.PropertyRef)" Name="Key"> 
    <Annotation Term="Core.Description" String="The set of properties that make up this key" /> 
  </Property> 
</ComplexType> 

Ralf: should have Nullable="false" in the Property

Ralf: Org.OData.Temporal.V1.xml

  <Term Name="TemporalSupported" Type="Aggregation.TemporalSupportedType" AppliesTo="EntityContainer EntitySet NavigationProperty"> --> 

Ralf: should be:

   
  <Term Name="TemporalSupported" Type="Temporal.TemporalSupportedType" AppliesTo="EntityContainer EntitySet NavigationProperty"> 

Ralf: 8 references to Term="Core.Documentation" should be to Term="Core.Description"

Mike: I move we approve the application of ODATA_1079. Stefan seconds.

Ralf: ODATA-1079 is CLOSED as applied

6.1.6 ODATA-1082 - Add term Constraint to Validation vocabulary

Ralf: Add new term

<Term Name="Constraint" 
           Type="Validation.ConstraintType" 
           AppliesTo="Property EntityType ComplexType"> 
    <Annotation Term="Core.Description" String="Condition that the annotation target has to fulfill" /> 
</Term> 
<ComplexType Name="ConstraintType"> 
    <Property Name="FailureMessage" Type="Edm.String" Nullable="true"> 
        <Annotation Term="Core.IsLanguageDependent" /> 
    </Property> 
    <Property Name="Condition" Type="Edm.Boolean" Nullable="false"> 
        <Annotation Term="Core.Description" 
              String="Value MUST be a dynamic expression that evaluates to true if and only if the constraint is fulfilled" /> 
    </Property> 
</ComplexType> 

Ralf: Example:

<Annotation Term="Validation.Constraint" Qualifier="Comparison"> 
  <Record> 
    <PropertyValue Property="FailureMessage" String="Start date cannot be after end date" /> 
    <PropertyValue Property="Condition"> 
      <Le> 
        <Path>StartDate</Path> 
        <Path>EndDate</Path> 
      </Le> 
    </PropertyValue> 
  </Record> 
</Annotation>

Stefan: I move we resolve ODATA-1082 as applied. Martin seconds.

Ralf: ODATA-1082 is CLOSED as applied

6.1.7 ODATA-1089 - Org.OData.Aggregation.V1 missing Nullable="false" for Function ReturnType

Stefan: I move we resolve ODATA-1089 as applied. Martin seconds.

Ralf: ODATA-1089 is CLOSED as applied

6.1.8 ODATA-1098 - xxxRestrictions can be applied more broadly

Ralf: Postpone until closing ODATA-958

6.2 Vocabularies: NEW or OPEN

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

META 1: use issue-specific branches for new terms, types, properties, or add them to master branch and mark them as experimental?
META 2: add examples to term definitions as shown here via annotation Core.Example?

Mike: likes to put new terms into separate branches, drawback is reviewing combinations of new terms

Ralf:

<Term Name="CustomHeaders" Type="Collection(Capabilities.CustomParmater)" AppliesTo="EntitySet Singleton Action ActionImport Function FunctionImport"> 
  <Annotation Term="Core.Description" String="Custom headers that are supported/required for the annotated resource" /> 
  <Annotation Term="Core.Example"> 
    <Annotation Term="Capabilities.CustomHeaders"> 
      <Collection> 
        <Record> 
          <PropertyValue Property="Name" String="X-CSRF-Token" /> 
          <PropertyValue Property="Description" String="Token to protect against Cross-Site Request Forgery attacks" /> 
          <PropertyValue Property="DocumentationURL" 
            String="https://help.sap.com/viewer/68bf513362174d54b58cddec28794093/7.51.1/en-US/b35c22518bc72214e10000000a44176d.html" /> 
          <PropertyValue Property="Required" Bool="true" /> 
          <PropertyValue Property="ExampleValues"> 
            <Collection> 
              <Record> 
                <PropertyValue Property="Value" String="Fetch" /> 
                <PropertyValue Property="Description" 
                  String="Can be used on HEAD request to the service document for obtaining a new CSRF token. This token must then be sent in subsequent requests to resources of the service." /> 
              </Record> 
            </Collection> 
          </PropertyValue> 
        </Record> 
      </Collection> 
    </Annotation> 
  </Annotation> 
</Term>

Ralf: https://github.com/oasis-tcs/odata-vocabularies/blob/ODATA-1099/vocabularies/Org.OData.Capabilities.V1.md#CustomHeaders

Stefan: likes it

Mike: sees the vocabulary files grow in size though, but we do not have to put examples everywhere, we can select.

Martin: suggests to split up pure vocabulary files with sibling versions (maybe with a specific extension adding the examples in) as one option

7. Next meetings

Thursday October 12, 2017 during 8-10 am PDT

8. AOB and wrap up

None

Meeting adjourned by chair.