OData TC meeting #193 Thursday October 26, 2017

Acting chair: Ralf

Chat transcript from room: odatatc
2017-10-26 0900-1100 PT

1. Roll call

1.1 Members present

    George Ericson (Dell)
    Gerald Krause (SAP SE)
    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=44001).

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

2. Approve agenda

Ralf: New agenda items:

  5.a. V4.01 Public Review
  iii. ODATA-1126 Remove a Reference to an Entity (public review comment c201710e00005)
  iv.  ODATA-1127 clarify support for navigation properties on deleted entries
  v.   Function Imports in $filter and $orderby - possible with $root/FuncImpName --> remove contradicting MUST NOT text in part 1 and 2
  vi.  Action Invocation: editorial change to first paragraph of section Invoking an Action

Agenda approved as published with the above additions

3. Approve minutes from previous meeting(s)

3.1 Minutes from October 19, 2017 TC meeting #192


Minutes approved unchanged as published.

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

4.1 Action items due

4.1.1 #0036 Register the OData- headers and preferences with IANA


Ralf: Documents look fine, Mark to follow up with Robin Cover on triggering the IANA registration

5. Issues

5.1 V4.01 Public Review

5.1.1 ODATA-1125 - Define by-value/reference expectations for action/function payloads.

Ralf: Description
Descriptions of parameters and return types do not explain expectations for references to Entities.
The metamodel + vocabulary for CSDL allows three types of encodings:
By-reference, represented as a string containing a URL that references the resource.
By-reference, represented as an object containing a partial copy of the resource that includes just the @odata.id meta property with a value that is a string containing a URL that references the resource.
By-value, represented as an object containing a copy of the resource.

For parameters and return-types, the question is which of these are expected in a payload.


1) Describe the encoding options in the CSDL documents. 
2) In the protocol, describe the expectations for different uses when type is an entitytype. 
3) cover these in the JSON format document.

Ralf: ODATA-1125 is OPEN

Ralf: Expectations:

- binding parameter by reference via URL preceding action/function
- non-binding primitive and complex by value in action request body
- non-binding (collection-valued) parameters of entity type:
- by reference using { "@id": ... }
 - by value using object notation with literal property values

Mike: Consider adding a vocabulary term to annotate an entity-valued parameter as byref/byvalue?

Ralf: Expected default: by reference (George, Ralf)

Mike: So term would be a "tag" representing "ByValue" with a default Boolean value (if applied) of true.

Mike: or "PassByValue"?

Mike: Absence of the term would mean by reference

Mike: Pass by reference would be {"@id":...}

Mike: When passed by value, its dependent upon the semantics of the action how many (if any) properties need to be included...

Ralf: Mixed list of value entities and entity references:

  "Name": "UpdatedCategory",
  "Products": [
      "@id": "Products(42)"
      "@id": "Products(57)",
      "Name": "Widgets"
      "Name": "Wedges"

Ralf: ByValue means: all of the above allowed

Ralf: ByReference means: only first form is allowed

Ralf: Example taken from http://docs.oasis-open.org/odata/odata-json-format/v4.01/csprd03/odata-json-format-v4.01-csprd03.html#sec_BindOperation

Ralf: Agreement: expectations to be spelled out in Part 1: Protocol, with forward-reference to JSON Format for "bind syntax" / "entity references"

Ralf: To be detailed by authors, to be reviewed in document walk-through

George: I move to accept the agreement on documenting the by-value/by-reference expectations in Part 1: Protocol, with forward-reference to JSON Format for "bind syntax" / "entity references". Mark seconds.

Ralf: ODATA-1125 is RESOLVED as proposed

Ralf: Example 22: primitive value

  "@context": "http://host/service/$metadata#Edm.String",
  "value": "Pilar Ackerman"

Ralf: Example 25: complex value

  "@context": "http://host/service/$metadata#Model.Address",
  "Street": "12345 Grant Street",
  "City": "Taft",
  "Region": "Ohio",
  "PostalCode": "OH 98052",
  "Country@navigationLink": "Countries('US')"

Ralf: Example 26: empty collection of complex values

  "value": []

5.1.2 ODATA-1123 - Allow 24:00:00 for Edm.TimeOfDay

Ralf: Description
Public review comment https://lists.oasis-open.org/archives/odata-comment/201710/msg00003.html

CSDL 4.01 permits Edm.TimeOfDay values to range from 00:00:00 to 23:59:59.999*.

However existing systems (e.g. SAP backends) frequently utilize 24:00:00 to indicate end-of-day. Requiring these values to be transmitted (e.g. to clients) as 23:59:59.999* could result in round-trip data loss.

In fact such SAP systems (for V2/V4) already will return PT24H or normalization-equivalent (for the V2 format of Edm.Time using XSD duration) or 24:00:00 (for the V4 format of Edm.TimeOfDay using XSD time), which is non-compliant with OData V2-V4 specifications.

To improve interoperability, it would be preferable to standardize this behaviour.

Note that the lexical format for XSD time permits 24:00:00, as it is the left-truncation of dateTime lexical representation, and dateTime lexical representation (see https://www.w3.org/TR/xmlschema-2/#dateTime) states:

- hh is a two-digit numeral that represents the hour; '24' is permitted if the minutes and seconds represented are zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime object in the value space cannot have a value greater than 23);


{ date: 2017-10-26, time: 24:00:00 } is end of that day
{ date: 2017-10-26, time: 00:00:00 } is begin of that day
Would mean 00:00:00 lt 24:00:00
Could allow it in DateTimeOffset
2017-10-26T24:00:00 eq 2017-10-27T00:00:00

Mike: two concerns

- backward compatibility with V4 / V3 / V2 clients
--> would need some kind of content negotiation
--> would cause round-tripping problems for clients not able to represent 24:00:00

Ralf: ISO 8601 allowed 24:00 but seems to disallow it in the future: https://www.loc.gov/standards/datetime/ISO_DIS 8601-1.pdf

Mike: Description of PHP understanding 24:00 but saving as 00:00: https://stackoverflow.com/questions/13060467/difference-between-2400-and-0000

Ralf: NOTE 2 The expression 00:00:00 denotes beginning of day; for Information Technology Interchange there is no representation of end of day. Thus even though it is recognized that the expression 24:00:00 is used as a natural language expression to denote end of a day, this expression is not used for Information Technology Interchange.

Ralf: ODATA-1123 is OPEN

George: I move to close OData-1123 with no action. Mark seconds.

Ralf: ODATA-1123 is CLOSED without action

5.1.3 ODATA-1126 - Remove a Reference to an Entity (public review comment c201710e00005)

Ralf: Description

Public review comment https://lists.oasis-open.org/archives/odata-comment/201710/msg00005.html

The document "OData Version 4.0, Part1: Protocol" specifies in section
" Remove a Reference to an Entity":

     For collection-valued navigation properties, the entity reference of 
     the entity to be removed MUST be specified using the $id query 
     string option. 

It would be nice if instead of or at least additional to using the $id query 
option it would be allowed to use the key after the navigation property 
to specify which entity is referenced. 

    DELETE http://host/service/Customers(1)/Orders/$ref?$id=../../Orders(4711) 
could be expressed as 
    DELETE http://host/service/Customers(1)/Orders(4711)/$ref 

This avoids a mandatory query option, handling of nested URLs, and parsing of relative or absolute URLs including verification that the URL is fitting; last but not least it is shorter and easier to understand. 

Kind Regards, 
Oliver Heinrich

George: likes it

Ralf: Part 2, section 4.9: http://docs.oasis-open.org/odata/odata/v4.01/csprd03/part2-url-conventions/odata-v4.01-csprd03-part2-url-conventions.html#sec_AddressingaMemberwithinanEntityColle

Ralf: Added recently, lists cases where an entity can be identified by key within a collection

Mike: I believe we discussed this when defining how to delete references in OData 4.0. The concern was the URL http://host/service/Customers(1)/Orders(4711) represents the entity, so /$ref would be order 4711's reference, not the reference from the customer...

Ralf: ODATA-1126 is OPEN

Mike: i.e., if you do a GET on http://host/service/Customers(1)/Orders(4711)/$ref would return Orders(4711)

Mike: if you did a delete on that returned value, you would be deleting Orders(4711), not the reference from Customers(1) to Orders(4711).


GET http://host/service/Customers(1)/Orders(4711)/$ref --> { @id: Orders(4711) }
GET http://host/service/Customers(1)/Orders$ref --> [ { @id: Orders(4711) }, ... ]
a) DELETE http://host/service/Customers(1)/Orders(4711)/$ref
a) DELETE http://host/service/Customers(1)/Orders/$ref(4711)

Mike: However, we do cheat a bit on the single-valued nav prop by allowing host://service/Customers(1)/BestFriend/$ref...

Ralf: Example 29: two ways of unrelating Categories(1) and Products(0)

DELETE http://host/service/Categories(1)/Products/$ref?$id=../../Products(0)
DELETE http://host/service/Products(0)/Category/$ref

Ralf: Resolve relative URL in first notation:

DELETE http://host/service/Categories(1)/Products/$ref?$id=/service/Products(0)

Mike: The associationLink annotation in a response contains an association URL that can be used to retrieve a reference to an entity or a collection of references to entities related to the current entity via a navigation property. The default computed value of an association URL is the value of the navigation URL appended with /$ref. (from JSON format doc)

Mike: However, when we do a GET to nav property appended with $ref you get back the id of the related entity, not relative to the nav prop.


GET http://host/service/Customers(1)/Orders(4711)/$ref --> { @id: Orders(4711) }

Mike: Matches 11.2.8 Requesting Entity References
To request entity references in place of the actual entities, the client issues a GET request with /$ref appended to the resource path.


GET http://host/service/Customers(1)/Orders/$ref --> [ { @id: Orders(4711) }, ... ]
DELETE http://host/service/Customers(1)/Orders(4711)/$ref
GET http://host/service/Customers(1)/Orders/$ref --> [ ... ]

George: for containment navigation properties DELETE Parent(key1)/CNProp(key2) and DELETE Parent(key1)/CNProp(key2)/$ref have the same result: child is gone

Ralf: Single-valued case - already allowed

GET http://host/service/Products(0)/Category/$ref --> { Categories(1) }
DELETE http://host/service/Products(0)/Category/$ref
GET http://host/service/Products(0)/Category/$ref --> 204 No Content
GET http://host/service/Products(0)/Category --> 204 No Content

Mike: from a pure REST perspective, the action (DELETE) is not being carried out on what would be returned by a GET on the same URL (the id of the order, not it's reference from customer), but (again) we already violate that for the single nav prop case...

Ralf: Postpone to next meeting, sleep over it for some nights...

Ralf: Tentative proposal:
- servers to accept both forms
- clients to prefer new form

Mike: For compatibility, 4.01 service would have to support both; would prefer 4.01 clients to use the new format.

Mike: not tie new URL syntax to OData-Version header, allow it also with OData-Version:4.0

5.2 Vocabularies: Schema Versioning

5.2.1 Proposal: annotate vocabulary schemas with Core.SchemaVersion to make different revisions distinguishable

  1. Major version is 1 will only be changed if we switch to Xxx.V2
  2. Minor version is incremented whenever we add a term, property, or AppliesTo target
  3. Patch version is incremented whenever we fix something typos, descriptions,

Mike: likes it

6. Next meetings


Thursday November 02, 2017 during 8-10 am PDT - 16:00 CEST in Europe, one hour earlier
Thursday November 09, 2017 during 8-10 am PDT

7. AOB and wrap up


Meeting adjourned by chair.