OData TC meeting #151 Thursday Nov 03, 2016

Acting chair: Ralf

Chat transcript from room: odatatc
2016-11-03 0700-1030 PT

1. Roll call

1.1 Members present

        Gerald Krause (SAP SE)
        Hubert Heijkers (IBM)
        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)
        Susam Malaika (IBM)
        Ted Jones (Red Hat)

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

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

2. Approve agenda

Ralf: New Jira issue:
ODATA-993 - 14.2: Explicitly allow annotations on deleted entities

Agenda approved as published including the update

3. Approve minutes from previous meeting(s)

3.1 Minutes from October 27, 2016 TC meeting #150

https://www.oasis-open.org/committees/download.php/59261/odata-meeting-150_on-20161027-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"

Ralf: Shift until Mark Biamonte joins the call - skipped due to running out of time

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-993 - 14.2: Explicitly allow annotations on deleted entities

Ralf: The delta format identifies deleted entities via their entity id.

For legacy systems that don't store the entity id and only know the underlying key values it would be helpful if the sender would annotate the deleted entity JSON objects with the original key values, e.g.

    { 
      "@odata.context":"#Customers/$deletedEntity", 
      "id":"Customers('ANTON')", 
      "@Legacy.entityKey":{ 
        "ID":"ANTON" 
      }, 
      "reason":"deleted" 
    }

Mike: also allow for added links and deleted links.

Mike: can see scenarios where entity references might need annotations

Ralf: ODATA-993 is OPEN

Ralf: Current text:
Annotations can be applied to any name/value pair in a JSON payload that represents a value of any type from the entity data model (see [OData-CSDL]).

Ralf: New text:
Annotations can be applied to any name/value pair in a JSON payload.

Mike: Updated proposal:
Support annotations in the following:
-AddedLinks
-DeletedLinks
-Deleted Entries
-References

In JSON, clients should be prepared for annotations in any object and any name/value pair in a json payload. Clients should never error on an annotation.

Mike: I move we resolve ODATA-993 as proposed. Hubert seconds.

Ralf: ODATA-993 is RESOLVED with the modified proposal

5.1.2 ODATA-920 - Specify overflow for int data types (-INF, INF, NaN)

Mike: Proposal 1:

"numbers" : [ 
1, 
2, 
{"@odata.numericOverflow":"-INF"}, 
4 
]
"numbers" : [ 
     1, 
     2, 
     {
        "@mycomment":"MyFavoriteNumber",
        Value: 3
      }, 
     4 
]

Mike: concern that annotating something now changes the structure of the JSON document

Mike: also different from hand-crafted JSON

>Term Name="annotations" Type="Collection(Edm.Untyped)"/> 

{ 
"myArray":[1,2,null,4,5], 
"myArray@annotations":[null,null,{"@numericValueException":"NaN"},null,null} 
}

Ralf: JSON Pointer style

{ 
"myArray":[1,2,null,4,5], 
"myArray/2@numericValueException":"NaN" 
}
{ 
"myArray":[1,2,null,4,5], 
"myArray@annotations":{2:{"@numericValueException":"NaN"}} 
}

Ralf: JSON Schema:

"type":["number","null"]
"type":["number","string","null"]
"anyOf":[{"type":["number","null"]},{"type":"object"}]

Mike: 18.2:
When annotating a name/value pair for which the value is represented as a JSON array or primitive value, each annotation that applies to this name/value pair MUST be placed next to the annotated name/value pair and represented as a single name/value pair.

Mark: differentiate between streaming and non-streaming, use in-line objects for streaming, separate array/map for non-streaming

Mike: Annotating an array of arrays through expando-values:

"cells": [ 
[ 
{"foo":1,"bar":1}, 
{"foo":2,"bar":2} 
], 
{ 
"value": [ 
{"foo":3,"bar":3}, 
{"foo":4,"bar":4} 
], 
"@my.annotation":"myannotationvalue" 
} 
]

Ralf: Tentative consensus for placing annotations next to array values instead of injecting wrapper objects

Mike: separately decide whether to keep @numericValueException or move back to -INF, INF, and NaN string values

Ralf:
MyArray@odata.count: 3
MyArray/0@odata.count:2
MyArray/0/0@odata.count:42

Hubert:
MyArray@odata.count:2
MyArray/0@odata.count:42
MyArray/1@odata.count:13

Ralf:
MyArray[]@odata.count:[42,13]

Mike:
"number":[1,2,3,null],
"number@annotated":[1,2,{"@myfavoritenumber":3},{"@numericValueException":"INF"}]
"number@":[1,2,{"@comment":"myfavoritenumber","Value":3},{"@numericValueException":"INF"}]

Hubert: add odata preference for only serializing number@

Mike:
$select=number@
$select=*@

Ralf:
$select=number@Common.FieldControl

Mike:
preference="annotated-values"
"number@":{"@myannotation":"myfavoritevalue","Value":3}?
if preference="annotationobjects", then always and only return annotated primitive values as objects (without the trailing "@")
(and arrays)

Ralf: Current:
NavProp:[...]
NavProp@odata.count:41

Ralf: Current: Future:
NavProp:{@odata.count:41,value:[...]}

Hubert: "number@":{"odata.count":4, "Value":[1,2,{"@comment":"myfavoritenumber","Value":3},{"@numericValueException":"INF"}]}

Mike: Working idea:

{
    "number": 3
    "number@ns.comment":"myfavoritenumber",
    "numbers":[1,2,3,null],
    "numbers@":[1,2,{"@ns.comment":"myfavoritenumber","Value":3},{"@numericValueException":"INF"}]
}

With a new preference services could always and only return annotated primitive values as objects (without the trailing "@"):

{
    "number": {"@ns.comment":"myfavoritenumber","Value":3],
    "numbers":[1,2,{"@ns.comment":"myfavoritenumber","Value":3},{"@numericValueException":"INF"}]
}

5.1.3 ODATA-964 - Need to clarify nested delta representation

Mike: Partial Example:

{ 
"@odata.type":"#Northwind.Manager", 
"FirstName" : "Patricia", 
"DirectReports@odata.contextUrl" : "#Employees(1)/DirectReports/$delta", 
"DirectReports": [ 
{ 
"@odata.context":"#Employees/$deletedEntity", 
"id":"Employees(3)", 
"reason":"deleted" 
},

Mike: Would context for deleted entity be: "#Employees/$deletedEntity" or "#Employees(1)/DirectReports/$deletedEntity"

Mike: could shorten to "/$delta" and "/$deletedEntity"

Hubert: simplify context urls to "$delta", "$deleteEntity" for nested context

Mike: actually "#$delta" and "#$deletedEntity"

Mike: might want to qualify with the set in order to be common with deleted entities outside of the nesting.

Mike: Proposal:
Added/Deleted links only appear at the root.

Nested content with "#delta" is applied as a delta. Entities are upserted, deleted entities are removed from the collection. If reason:deleted is specified, client knows the related entity is deleted, otherwise (in a non-containment case) all the client knows is that the entity is no longer a member of that collection. The contextUrl for the nested deleted entity is the same as it would be in the flattened representation.

Ralf: ODATA-964 is OPEN

Mike: I move we resolve ODATA-964 as proposed. Matt seconds.

Ralf: ODATA-964 is RESOLVED as proposed

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

Mike: example:

{ 
"@odata.type":"myns.myComplexType, 
"@SchemaVersion":"1.0", 
"prop1":1 
}

Mike: to annotate a property:

{ 
"prop1@odata.type":"myns.myComplexType, 
"prop1@SchemaVersion":"1.0", 
"prop1":1 
}

Martin: schema version as a request header doesn't go well with caching

Ralf: Purpose 1: server tells client which schema version was used to generate response

Ralf: Best served by an annotation

Ralf: Purpose 2: client tells server which schema version it wants to get

Ralf: Maybe better served by a query option than a header

Mike: Revised proposal:

Proposal: for CSD01, clarify how the type is annotated, as below, leaving the rest of the semantics as in the current draft. Annotations are a nice way for the client to know what schema version was used without having to parse a URL and get the query option. For CSD02, consider replacing the SchemaVersion request header with a query option.

Martin: I move to resolve ODATA-980 as proposed. Hubert seconds.

Ralf: ODATA-980 is RESOLVED with the revised proposal

Ralf: New issue ODATA-994 - consider replacing SchemaVersion headerwith $SchemaVersion query option, or root URL versioning

5.1.5 ODATA-974 - Flesh out recommendations around OAuth support in OData

Nothing noted in this regard during meeting.

5.1.6 ODATA-965 - UpdateGeoJSON Reference to RFC7946

Stefan: It should be a breeze to replace the reference, as we took care to only flesh out the prose, clean up examples during the RFC process, etc. - but I will need to go over the data types we use to e.g. to be sure we do not have problems with inner rings and other specialties that were set straight during the community discussions - sorry for being late, but will update the issue accordingly before Monday - so we can put it on next Thursdays agenda.

6. Next meetings

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

Date and time of meeting agreed

7. AOB and wrap up

No other business.

Meeting adjourned by chair.