Acting chair: Ralf
Chat transcript from room: odatatc 2017-10-26 0900-1100 PT
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.
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 11.5.4.1 Invoking an Action
Agenda approved as published with the above additions
https://www.oasis-open.org/committees/download.php/61866/odata-meeting-192_on-20171019-minutes.html
Minutes approved unchanged as published.
https://www.oasis-open.org/committees/download.php/61752/IANA_Header_Registration.docx
https://www.oasis-open.org/committees/download.php/61751/IANA_Preference_Registration.docx
Ralf: Documents look fine, Mark to follow up with Robin Cover on triggering the IANA registration
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.
Ralf:
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
{
"@context":"http://host/service/$metadata#Collection(Model.Address)",
"value": []
}
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);
Ralf:
{ 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
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
"11.4.6.2 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.
Example:
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).
Ralf:
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.
Ralf:
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.
Ralf:
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
Mike: likes it
Ralf:
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
None
Meeting adjourned by chair.