OData TC meeting #150 Thursday Oct 27, 2016

Acting chair: Ralf

Chat transcript from room: odatatc
2016-10-27 0900-1200 PT

1. Roll call

1.1 Members present

        Gerald Krause (SAP SE)
        Hubert Heijkers (IBM)
        Ken Baclawski (Northeastern University)
        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)
        Stefan Hagen (Individual)

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

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

2. Approve agenda

Ralf: New Jira issue:
ODATA-992 - Prefer numeric representation of enumeration values

Agenda approved as published including the update

3. Approve minutes from previous meeting(s)

3.1 Minutes from October 20, 2016 TC meeting #149

https://www.oasis-open.org/committees/download.php/59196/odata-meeting-149_on-20161020-minutes.html

Minutes approved unchanged as published.

4. Review action items

4.1 Action items due July 31, 2016

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

Mark: finished document for header registration, working on document for preferences registration, will add it to TC document repository for review next week

Action #0036 remains open.

5. Issues for V4.01_WD01 in New or Open state

5.1 Issues ready for Resolution

5.1.1 ODATA-557 - Allow exponential notation for Edm.Decimal

Ralf: Allow exponential notation for Edm.Decimal literals.

Add new symbolic value Scale="floating" for DECFLOAT values. The Precision attribute will specify the number of digits in the mantissa.

Ralf: Just to confirm;

1) Services would only allow scale="Floating" for 4.01 and versions of metadata,
2) As per OData-771, services should only return values in exponential notation if the ExponentialDecimals format parameter is specified
3) Also, as per OData-771, clients should only supply values in exponential notation if SupportedFormats returns ExponentialDecimals

For 4.01, rather than burdening the media type with additional format parameters, should we just say that 4.01 clients and services have to be prepared to receive decimals in exponential format? Do we still need the ExponentialDecimals format parameter for 4.0 clients to say they will accept decimals in exponential format, or should we not apply OData-771?

Mike: 4.01 payloads by default may use exponential notation

Mike: no use for keeping this format parameter for disabling exponential notation

Ralf: Keep format parameter for V4, and state that it has no meaning for V4.01

Mike: Additions to proposal:
Services would only allow scale="Floating" for 4.01 and versions of metadata,

For 4.01 JSON payload, exponential decimals is always assumed and format parameter is not needed.

Mike: Fixed typos:
Services would only allow scale="Floating" for 4.01 and later versions of metadata,

For 4.01 JSON payloads, exponential decimals is always assumed and format parameter is not needed or used.

Hubert: I move to resolve ODATA-557 as per the amended proposal. Mark seconds.

Ralf: ODATA-557 is RESOLVED with the modified proposal

5.1.2 ODATA-959 - Allow path in an edm:key to also use a primitive property of a non null-able navigation property (recursively) of the entity type.

Hubert: goal is to simplify deep-insert, where the foreign-key properties would have to be redundantly specified with the nested/related key properties

Mike: would @odata.id be mandatory in this case, or would it be mandatory to sender-side expand the "foreign key" entities and include the key properties?

Ralf: including key fields would be beneficial for delta-tombstones. Check if tombstones allow annotations and open issue otherwise.

Hubert: deep-insert combined with server-generated keys for the principal entities is impossible if the dependent entities contains foreign-key properties.

Mike: "remote-key" property should be immutable

Hubert: no problem in targeted use cases

Mike: Additional Semantics:
In JSON payloads:
1)The id would always have to be written, even in minimal metadata, or
2)The nav properties were expanded to include at least the related ids (service *could* default expand to include the related id fields.)
You can only create the entity if:
a.You include a link to an existing related entity containing the key value, or
b.You do a deep insert that includes the related entity
You can't change the relationship to the related entity containing the key value (so it would have to be single, non-nullable, and immutable)
The referenced property(ies) on the related entity would have to be immutable (or, if changed, would delete the entity with the dependent key)
>>We could restrict this to say that the property of the related entity is a key of the related entity.
Deleting the related entity would delete the entity whose key referenced a property of that entity

Hubert: restrict this new features to key properties of the related entities

Mike: if we want to relax this in the future, we should explicitly point this out to clients

Ralf: ODATA-798 - Semantic Key or Alternate Key for entity types

Mike: revised proposal:
Allow the path expression to include references to primitive properties of non null-able navigation properties (recursively).

8.3.1 Attribute Name could be simply amended as in:
The edmropertyRef element MUST specify a value for the Name attribute which MUST be a path expression resolving to a primitive property of the entity type itself or to a primitive property of a complex or a single-valued, non-nullable navigation property (recursively) of the entity type. The names of the properties in the path are joined together by forward slashes.

Semantics:
In JSON payloads:
1)The id must be written, even in minimal metadata, or
2)The nav properties must be expanded to include at least the related ids (service *could* default expand to include the related id fields.)
You can only create the entity if:
a.You include a link to an existing related entity containing the key value, or
b.You do a deep insert that includes the related entity
You can't change the relationship to the related entity containing the key value (so it would have to be single, non-nullable, and immutable)
The referenced property(ies) on the related entity must be immutable and must be unique (i.e., are generally a key of the related entity)
Deleting the related entity deletes the entity whose key referenced a property of that entity

Martin: I move to resolve ODATA-959 as per the amended proposal

Mike: (clarified intro sentence: Allow the path expression to include references to unique, immutable, primitive (i.e., key) properties of non null-able, immutable navigation properties (recursively).

Martin: I move to resolve ODATA-959 as per the NEW amended proposal

Ralf: ODATA-959 is OPEN

Martin: I move to resolve ODATA-959 as per the most current amended proposal. Hubert seconds.

Ralf: ODATA-959 is RESOLVED as proposed

5.1.3 ODATA-969 - Chapter 15, Example 32: syntax of "target" URL

Ralf:

{
  "@odata.context": "http://host/service/$metadata#Employees/$entity",
  "#Model.RemainingVacation(Year)": {
  "title": "Remaining vacation from year...",
  "target": "Employees(2)/RemainingVacation(Year=@Year)"
  },
  ...
}

Ralf: "target": "Employees(2)/RemainingVacation(Year=@abc)"

Ralf: "target": "Employees(2)/RemainingVacation({Year})"

Ralf: "target": "Employees(2)/RemainingVacation"

Ralf: GET Employees(2)/RemainingVacation?@Year=2016

Ralf: GET Employees(2)/RemainingVacation(Year=@Year)?@Year=2016

Mike: Clarification: Clarify in text that functions are invoked by adding the named parameters as query options. The syntax of the url is up to the service.

Ralf: ODATA-969 is OPEN

Ralf: I move to resolve ODATA-969 with the modified proposal. Martin seconds.

Ralf: ODATA-969 is RESOLVED as proposed

5.1.4 ODATA-979 - Recursive containment navigation properties and Partner attribute

Ralf: Containment navigation properties MAY specify a Partner attribute. If the containment is recursive, the partner navigation property MUST be nullable and specify a single entity type. If the containment is not recursive, the partner navigation property MUST NOT be nullable.

An entity type hierarchy MUST NOT contain more than one navigation property with a Partner attribute referencing a containment relationship.

Ralf:
- EntityType Name=FileSystemEntry
- NavigationProperty Name=Parent Type=this.FileSystemEntry Nullable=true

- EntityType Name=Folder BaseType=this.FileSystemEntry
- NavigationProperty Name=Children Type=Collection(this.FileSystemEntry) Partner=Parent

- EntityType Name=File BaseType=this.FileSystemEntry
- NavigationProperty Name=Parent Type=this.Folder Nullable=false

Mike: Alternate example:
- EntityType Name=FileSystemEntry
- NavigationProperty Name=Parent Type=this.FileSystemContainer Nullable=true

- EntityType Name=File BaseType=this.FileSystemEntry
- NavigationProperty Name=Parent Type=this.Folder Nullable=false

- EntityType Name=FileSystemContainer BaseType=this.FileSystemEntry
- NavigationProperty Name=Children Type=Collection(this.Folder) Partner=Parent ContainsTarget=true

- EntityType Name=Folder BaseType=this.FileSystemContainer
- NavigationProperty Name=Parent Type=this.FileSystemContainer Nullable=false

- EntityType Name=Drive BaseType=this.FileSystemContainer

Ralf: When a containment navigation property navigates between entity types in the same inheritance hierarchy, the containment is called recursive.

Mike: Clarify prose text:
Containment navigation properties MAY specify a Partner attribute. If the containment is recursive, the relationship defines a tree; thus the navigation property on the type defined as the partner MUST specify a single entity type and MUST be nullable (for the root of the tree). If the containment is not recursive, the partner navigation property MUST NOT be nullable.

An entity type inheritance chain MUST NOT contain more than one navigation property with a Partner attribute referencing a containment relationship.

Ralf: If the containment is not recursive, the partner navigation property MUST NOT be nullable because it leads back to the containing entity.

Mike: Revised proposal:
Clarify prose text:

Containment navigation properties MAY specify a Partner attribute. If the containment is recursive, the relationship defines a tree; thus the navigation property on the type defined as the partner MUST specify a single entity type and MUST be nullable (for the root of the tree). If the containment is not recursive, the partner navigation property MUST NOT be nullable because it leads back to the containing entity.

An entity type inheritance chain MUST NOT contain more than one navigation property with a Partner attribute referencing a containment relationship.

Martin: I move to resolve ODATA-979 with the modified proposal

Ralf: ODATA-979 is OPEN

Martin: I move to resolve ODATA-979 with the modified proposal. Mike seconds.

Ralf: ODATA-979 is RESOLVED as proposed

5.1.5 ODATA-980 - SchemaVersion header, $SchemaVersion query option, or root URL versioning

Ralf: The SchemaVersion header and accompanying annotation are intended to allow breaking changes without having to change the service root URL.

How does this combine with type referencing in the @odata.type annotation?

We could annotate the @odata.type annotation with the @Core.SchemaVersion:

  "@odata.type":"https://some.whe.re/$metadata" 
  "@odata.type@Core.SchemaVersion":"2.0.1", 

Or we could add a system query option and make the schema version part of the URL:

  "@odata.type":"https://some.whe.re/$metadata?$SchemaVersion=2.0.1", 

Or we could reconsider this and fall back to root URL versioning:

  "@odata.type":"https://some.whe.re;v=2.0.1/$metadata",

Ralf: JSON Format:
Request payloads MAY include a context URL as a base URL for relative URLs in the request payload.
Example 4:

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  "@metadataEtag": "W/\"A1FF3E230954908F\"",
  "@Core.SchemaVersion": "2.0.1",
  ...
}

Ralf: Homework: reconsider schema version mechanism, e.g. based on query option instead of request header

Ralf: ODATA-980 is OPEN

Ralf: New proposal that reflects the homework: Add a $schemaversion system query option instead of a SchemaVersion header and use this in @odata,type URLs if the type needs refering to a specific schema version.

Ralf: Move issue into category "Needs refined proposal"

5.1.6 ODATA-983 - Chapter 15/16: advertise actions on collection-valued properties

Ralf: Prefix the advertisement with the primitive- or collection-valued property name and place it next to the navigation property, similar to annotations on navigation properties:

  "NavProp#Model.SomeAction": { 
  "title": "Do Something", 
  "target": "Managers(22)/Employees/DoSomething" 
  }, 
  "NavProp": [ ... ] 

Services must only returned this syntax in an OData 4.01 response.

Mike: question is when this annotation is returned

Ralf: Question from discussion in 2016-10-13 meeting: when does this appear?
1) Only when expanded?
2) Only when expanded and selected?
3) If I expand and select only action, do I have the object or just the action advertisement?

Ralf: $expand=NavProp($select=Model.SomeAction)

Ralf: would return just
NavProp#Model.SomeAction

Ralf: $expand=NavProp/$count

Ralf: NavProp@odata.count

Ralf: Question from discussion in 2016-10-13 meeting: when does this appear?
1) Only when expanded?
2) Only when expanded and selected?
3) If I expand and select only action, do I have the object or just the action advertisement?

Mike: proposed answers to questions from 2016-10-13:
Advertisement can appear any time.
If must appear if explicitly requested (i.e., through expand that explicitly selects the action/function).
If only the function/action is selected in the expand, then the nav property itself does not need to be included

Mike: Revised proposal:
Prefix the advertisement with the primitive- or collection-valued property name and place it next to the property, similar to annotations on navigation properties:

  "NavProp#Model.SomeAction": {
  "title": "Do Something",
  "target": "Managers(22)/Employees/DoSomething"
  },
  "NavProp": [ ... ]

Services must only returned this syntax in an OData 4.01 response.

These advertisement can appear any time.
They don't need to be included in an expand if not explicitly requested.
They must appear if explicitly requested (i.e., through expand that explicitly selects the action/function).
If only the function/action is selected in the expand, then the nav property itself does not need to be included

Mike: I move we resolve ODATA-983 as proposed. Martin seconds.

Ralf: ODATA-983 is RESOLVED as proposed

5.1.7 ODATA-985 - The HTTP Specification document referenced in the OData Protocol Spec has been obsoleted

Ralf: Proposal:
Substitute [RFC2617] by [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, September 2015. http://www.ietf.org/rfc/rfc7617.txt

Martin: But we still use the also obsolete RFC2617 (HTTP Authentication: Basic and Digest Access Authentication) in the protocol spec.
Documents updating RFC 2617 are
"Hypertext Transfer Protocol (HTTP/1.1): Authentication" ([RFC7235], defining the authentication framework),
"The 'Basic' HTTP Authentication Scheme" ([RFC7617] updating the definition of the "Basic" authentication scheme),
"HTTP Digest Access Authentication" ([RFC7616], updating the definition of the "Digest" authentication scheme), and
"HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields" ([RFC7615]).
Taken together, these four documents obsolete RFC2617.

We have 3 references to RFC2617 in the document; all 3 are pointing to the "basic authentication".
--> We should substitute RFC2617 by [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, September 2015. http://www.ietf.org/rfc/rfc7617.txt

There are no substantive changes from our perspective; the RFC7617 states:

"Changes from RFC 2617 

   The scheme definition has been rewritten to be consistent with newer 
   specifications such as [RFC7235]. 

   The new authentication parameter 'charset' has been added. It is 
   purely advisory, so existing implementations do not need to change, 
   unless they want to take advantage of the additional information that 
   previously wasn't available. 
" 

I updated the proposal accordingly.

Martin: Substitute [RFC2617] by [RFC7617] Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, September 2015. http://www.ietf.org/rfc/rfc7617.txt

Mark: I move that ODATA-985 be resolved as proposed. Mike seconds.

Ralf: ODATA-985 is RESOLVED as proposed

5.1.8 ODATA-992 - Prefer numeric representation of enumeration values

Ralf: Part 3: CSDL states that enumeration values are sorted and compared using their numeric value because it allows synonym symbolic names with the same numeric value.

Part 3: CSDL also only allows symbolic values in annotations.

JSON Format on the other hand states that the symbolic name, represented as a string, is preferred.

This makes life unnecessarily complicated for clients to evaluate conditional annotation expressions based on enums as they can't compare enum values in annotations and payloads without internally translating them into numeric values, which they can only know after reading vocabulary files.

Mike: leave enumeration types as they are. If no flags or synonyms/symbolic names are required/desired, use annotation Validation.AllowedValues instead.

Mike: My Proposal would be:
Keep enumerations as-is; maps to programming enumerations and there has been a strong desire in the past to optimize for the string representation (the only reason we have underlying numeric values is for flags).

Call out that services that want a discrete set of numeric should use AllowedValues.

Ralf: ODATA-992 is OPEN

Mike: I move we resolve ODATA-992 as proposed (leaving enums as they are and recommending allowedvalues for purely numeric representations). Martin seconds.

Ralf: ODATA-992 is RESOLVED as proposed

5.2 Issues waiting for refined proposal

Ralf: Vocabularies: move forward on placing them into a separate work product and get "latest-version" links for them.

5.2.1 ODATA-743 - Restructure Part 3: CSDL into CSDL Core, CSDL XML, and CSDL JSON

Mike: 16 changes from Part 1 & 2 to Part 3 that would have to be changed to CSDL XML Format

Ralf: Proposal: publish CSD01 without Part 3, reconsider this for CSD02

Mike: For CSD01:
Update [OData-CSDL] normative reference to be to CSDL-XML.

For CSD02:
Format-independent draft: https://www.oasis-open.org/committees/download.php/59121/odata-v4.01-wd01-part3-csdl-2016-10-12.docx

Pure format spec draft (chapters 1 to 11): https://www.oasis-open.org/committees/download.php/59177/odata-csdl-xml-v4.01-wd01-min.docx

Mike: I move we resolve ODATA-743 as proposed. Martin seconds.

Ralf: ODATA-743 is RESOLVED as proposed

5.2.2 ODATA-879 - Support Arrays of Arrays

Ralf: Related to 5.ODATA-920 Specify overflow for int data types (-INF, INF, NaN)

6. Next meetings

Mike: Review proposals for JSON CSDL on November 3

6.1 Meeting following Thursday November 3, 2016 during 07:00-10:30 am PT

Date and time of meeting agreed

7. AOB and wrap up

No other business.

Meeting adjourned by chair.