OData TC meeting #211 Thursday April 19, 2018

Acting chair: Ralf

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

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

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

2. Approve agenda

Ralf: New V4.01 issue: ODATA-1172 - 4.5.3: use $schemaversion query option instead of SchemaVersion header

Agenda is approved

3. Approve minutes from previous meeting(s)

3.1 Minutes from April 05, 2018 TC meeting #209

https://www.oasis-open.org/committees/download.php/62839/odata-meeting-209_on-20180405-minutes.html

Minutes approved unchanged as published.

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

4.1 Action items due

None

5. Timeline

5.1 Vocabularies

  1. Publish CSD02 soon, or rather continue with issue processing and publishing on GitHub?

5.2 OData to OpenAPI Mapping

  1. Publish CND02 soon, or rather postpone it after REST Profile and/or Compact JSON?

Mike: review latest changes next

Ralf: Open issues affecting OpenAPI Mapping:

i.ODATA-1099 Add annotations to describe custom query options and custom headers
iii.ODATA-884 Add term ErrorCodes to describe possible codes in error messages (public comment c201510e00019)

Mike to follow up on ODATA-884

Ralf to amend ODATA-1099 with schema/examples for custom header/option values

Ralf: Example values in primitive property definitions in OpenAPI are used by Swagger UI for drawing example payloads

Ralf: See http://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/master/examples/TripPin.openapi3.json#/People/get_People

Ralf: Example Value:

{
  "value": [
    {
      "UserName": "string",
      "FirstName": "string",
      "LastName": "string",
      "Emails": [
        "string"
      ],
      "AddressInfo": [
        {
          "Address": "string",
          "City": {
            "CountryRegion": "string",
            "Name": "string",
            "Region": "string"
          }
        }
      ],
      "Concurrency": "42",
      "Friends": [
        null
      ],
      "Trips": [
        {
          "TripId": 0,
          "ShareId": "01234567-89ab-cdef-0123-456789abcdef",
          "Description": "string",
          "Name": "string",
          "Budget": 3.14,
          "StartsAt": "2017-04-13T15:51:04Z",
          "EndsAt": "2017-04-13T15:51:04Z",
          "Tags": [
            "string"
          ],
          "Photos": [
            {
              "Id": "42",
              "Name": "string"
            }
          ],
          "PlanItems": [
            {
              "PlanItemId": 0,
              "ConfirmationCode": "string",
              "StartsAt": "2017-04-13T15:51:04Z",
              "EndsAt": "2017-04-13T15:51:04Z",
              "Duration": "P4DT15H51M04.217S"
            }
          ]
        }
      ]
    }
  ]
}

Ralf: After resolving these two issues update document and walk through again

5.3 REST Profile / Essential OData

  1. Before or after Compact JSON?

Ralf: Next: REST Profile or Compact JSON

Ralf: "REST Profile" or "OData Light" or "Essential OData": Overview/cookbook for adopting OData step by step

Ralf: Option: don't use "OData" to avoid confusion around data-centric/non-data-centric APIs

Ralf: Idea: OpenAPI instead of CSDL as metadata/service description

George: RestLite doesn't have any hits

Ralf: Unfortunately it does:

- GitHub - theintencity/restlite: Light-weight RESTful server tools in Python
- GitHub - ncribt/restlite: A JavaScript Microframework to make Single ...

Ralf: and more

Ralf: Compact JSON: walk-through next week

5.4 Compact JSON

  1. Before or after REST Profile?
  2. Hubert has contributed a proposal: 1.https://www.oasis-open.org/committees/document.php?document_id=62898&wg_abbrev=odata

George: no pushback from Redfish on Github as publishing point for vocabularies

Mike: no reason to publish legacy documents

Mike: I move that we continue processing Vocabulary issues through GitHub and do not plan to publish a legacy CSD02 document for the accumulated changes. Hubert seconds.

Ralf: No objection, motion passes

6. Issues

6.1 V4.01: NEW or OPEN

6.1.1 ODATA-1172 - 4.5.3: use $schemaversion query option instead of SchemaVersion header

Ralf: Proposal:

Current text: 
---- 
If the URI references a metadata document (that is, its not just a fragment), and refers to a specific version of that metadata, then the object or name/value pair MUST also be annotated with the Core.SchemaVersion annotation, defined in [OData-VocCore], to indicate the version of the metadata document containing the corresponding version of the type. For streamed JSON responses, this annotation MUST immediately follow the type annotation. If the Core.SchemaVersion annotation is present, the Core.SchemaVersion header, defined in [OData-Protocol], SHOULD be used when retrieving the referenced metadata document. 
---- 

Change to 
---- 
If the URI references a metadata document (that is, its not just a fragment), it MAY refer to a specific version of that metadata document using the $schemaversion system query option defined in [OData-Protocol]. 
---- 

That is: no need for an additional annotation with Core.SchemaVersion, just follow the @odata.type URL.

Ralf: ODATA-1172 is OPEN

Mike: I move we resolve ODATA-1172 as proposed. Mark seconds.

Ralf: ODATA-1172 is RESOLVED as proposed

6.1.2 ODATA-1171 - Consider using matrix parameters for filter segments

Mike: Current filter segment syntax:

Customers/$filter=@q/myns.action?$@q=Age gt 18
Syntax using Matrix Parameters: Customers;$filter=@q?$@q=name eq 'Smith'
Customers;$filter=@q/myns.action?$@q=name eq 'Smith'

Ralf: According to "Restful Java with JAX-RS 2.0", a request like "GET /mercedes/e55;color=black/2006/interior;color=tan" would have an ambiguous definition of the color matrix param.

Ralf: ODATA-1171 is OPEN

Mike to get feedback from implementation team regarding concerns of IETF specifications and HTTP-related tools being unable to cope with semicolons in URL paths

Mike: don't have both syntax variants, decide for exactly one soon

6.1.3 ODATA-1163 - A Case for Common Expressions

Ralf: Proposal:

The case function has the following signatures: 

expression case(Edm.Boolean:expression, ..., Edm.Boolean:expression) 
expression case(Edm.Boolean:expression, ..., Edm.Boolean:expression,expression) 

Each Edm.Boolean:expression parameter is a tuple separated by a colon, 
where the first component evaluates to a Boolean value, 
and the second component may be an expression of any type. 

The case function returns the expression value of the leftmost parameter, whose first component evaluates to true. 
If none of the parameters match, case returns null, unless the last parameter is an expression, 
whose value is returned otherwise. 

If all parameters are of the same type, the type of the expression is of that type. 
If all parameter expressions are of numeric type, the return value has a numeric type capable 
of representing any of these expressions. 
Otherwise, the return value is the result of casting the expression of the matching parameter to Edm.String.

Mike: (From ODATA-1171: George: Note that putting a filter in the Path is problematic for some implementations that serve hard-coded paths or do routing based on fixed path templates. Also, it breaks the hypermedia-driven model of services providing URLs and the client only affecting query string parameters.)

Mike: agree that type-compatible result expressions lead to that type using existing OData rules

Mike: From 2018-4-5: All parameter expressions must be compatible. If all parameters are of the same type, the type of the case expression is of that type. If all parameter expressions are of numeric type, then the type of the case expression is a numeric type capable of representing any of these expressions according to standard type promotion rules. If types of parameter expressions are not compatible, then they must be cast to compatible types.

Mike: could use Edm.Untyped instead of forcing cast in case the parameter expressions aren't compatible

Mike: can start with the stricter rule and relax it later to resulting in Edm.Untyped.

George: be strict and make client responsible for formulating consistent requests

Ralf: Side-discussion on wording in CSDL "14.4.11 Null", George to open separate issue with proposal for improved wording

Mike: One option: Clients SHOULD ensure that the type of the expression is well defined. Services MAY support case expressions containing parameters of different types, in which case the type of the expression is UnTyped.

George: OData-1173 addresses 14.4.11

Mike: Revised proposal:

The client SHOULD ensure that all expressions are compatible. 
If all parameters are of the same type, the type of the case expression is of that type. 
If all parameter expressions are of numeric type, then the type of the case expression 
is a numeric type capable of representing any of these expressions according to standard type promotion rules.

Services MAY support case expressions containing parameters of incompatible types, 
in which case the expression is treated as Edm.Untyped.

Ralf: Perfect

Mike: Revised last statement: Services MAY support case expressions containing parameters of incompatible types, in which case the expression is treated as Edm.Untyped and its value is the type of the parameter expression taken selected by the case statement..

Mike: Reworded:

The client SHOULD ensure that all parameter expressions are compatible. 
If all parameter expressions are of the same type, the type of the case expression is of that type. 
If all parameter expressions are of numeric type, then the type of the case expression is a 
numeric type capable of representing any of these expressions according to standard type promotion rules.

Services MAY support case expressions containing parameters of incompatible types, in which case the expression 
is treated as Edm.Untyped and its value is the type of the parameter expression selected by the case statement.

Mark: I like this latest proposal

Ralf: Me too

Mark: I move that OData-1163 be resolved as proposed. Mike seconds.

Ralf: ODATA-1163 is RESOLVED with the amended proposal

7. Next meetings

Thursday April 19, 2018 during 8-10 am PDT (17:00-19:00 CEST)
Thursday May 03, 2018 during 8-10 am PDT (17:00-19:00 CEST)

8. AOB and wrap up

None.

Meeting adjourned by chair.