Ralf Handl (SAP): Voting Members: 4 of 11 (36%) Ralf Handl (SAP): Voting Members: 5 of 11 (45%) Ralf Handl (SAP): Voting Members: 6 of 11 (54%) Ralf Handl (SAP): Achieved quorumyes Ralf Handl (SAP): 2.Approve agenda [6:05am PT] Ralf Handl (SAP): Add discussion on OpenAPI Ralf Handl (SAP): Discuss OpenAPI before going into V4.01 issues Ralf Handl (SAP): Adapted agenda is approved Ralf Handl (SAP): 3.Approve minutes from previous meeting(s) [6:10am PT] a.Minutes from July 14, 2016 TC meeting:
https://www.oasis-open.org/committees/download.php/58508/odata-meeting-137_on-20160714-minutes.html Ralf Handl (SAP): Minutes are approved Ralf Handl (SAP): 4.Review action items [Action item list:
https://www.oasis-open.org/apps/org/workgroup/odata/members/action_items.php ] [6:15am PT] a.Action items due i.None Ralf Handl (SAP): 5. Discuss way forward OpenAPI Ralf Handl (SAP): Recap: Ram asked about RAML and whether we should consider that Ralf Handl (SAP): Hubert: Current OpenAPI-based format doesn't feel like OData Ralf Handl (SAP): Different interests Ralf Handl (SAP): - OpenAPI representation, potentially lossy, x- stuff might distract or even impede Ralf Handl (SAP): - RAML representation, potentially lossy, extensions might distract or even impede Ralf Handl (SAP): - full-fidelity JSON format, no interest in OpenAPI, JSON Schema, RAML, ... - just lossless JSON $metadata Ralf Handl (SAP): Hubert: pure OpenAPI part of our current spec is lossy anyway Ralf Handl (SAP): Mark: considering to omit x- extensions and not risk to confuse OpenAPI tools that can't ignore x- extensions Ralf Handl (SAP): Susan: have an open discussion on which way to go Ralf Handl (SAP): Mike: write summary/intro to kickstart that discussion Ralf Handl (SAP): Decide in future meeting on how to set up this discussion Ralf Handl (SAP): 6.V4.01 [6:20am PT] a.Issues for V4.01_WD01 in New or Open state i.Ripe for resolution 1.ODATA-923 $expand for $metadata to include referenced schemas Ralf Handl (SAP): ODATA-923 is OPEN Mike Pizzo: Note: in generic client scenario, the client has the namespace-or-alias qualified type name, or entity set name from @odata.context. Mike Pizzo: Scenario-wise, what the client really wants is the ability to get the metadata necessary to understand a particular response. So, given a context, it wants to (minimally) get back the recursive set of types referenced by that context (and probably wouldn't really care about any additional types defined in the namespaces used by the referenced types). Mike Pizzo: also note, service can't just include referenced files; it has to make sure there are no conflicts in the defined aliases. Ralf Handl (SAP): Mike to get feedback from implementation team(s) and flesh out proposal Ralf Handl (SAP): ii.OData Protocol 1.ODATA-919 Specify the result type for each operation based on operator types Ralf Handl (SAP): Ralf to contact Evan whether he can round off the proposal Ralf Handl (SAP): 2.ODATA-942 How should headers applied to a batch affect statements within a batch Mike Pizzo: Michael Pizzo added a comment - a few seconds ago For each header, possibilities on a batch could be: 1) Not defined at the batch level 2) Defined and applies to the batch itself, not individual requests 3) Applies to each request within the batch (perhaps as a default, overridden (or combined?) if the statement contains the same header) Mike Pizzo: Michael Pizzo added a comment - a few seconds ago For each header, possibilities on a batch could be: 1) Not defined at the batch level 2) Defined and applies to the batch itself, not individual requests 3) Applies to each request within the batch (perhaps as a default, overridden (or combined?) if the statement contains the same header) Ralf Handl (SAP): Mark takes over this issue Ralf Handl (SAP): iii.Annotations 1.ODATA-571 Add annotation for properties that are (not) part of the default selection if no $select is specified Mike Pizzo: Mark will go through the existing headers defined in [Protocol] and propose which of these behaviors is most appropriate (and which require further discussion) Ralf Handl (SAP): I move to close ODATA-571 without action Hubert Heijkers: I second Ralf Handl (SAP): ODATA-571 is closed without action Ralf Handl (SAP): 2.ODATA-735 Enhance the CSDL for instance annotations Ralf Handl (SAP): ODATA-735 is OPEN Ralf Handl (SAP): Need more information on use cases Ralf Handl (SAP): And benefits for clients Ralf Handl (SAP): Inclination to close it without action Ralf Handl (SAP): Postponed Ralf Handl (SAP): 3.ODATA-811 Define propagation and (partial) overriding of annotations Ralf Handl (SAP): ODATA-811 is OPEN Ralf Handl (SAP): Mike: agree that annotations are propagated along usage (type definition to property, ...) Ralf Handl (SAP): Mike: agree that annotations are propagated along inheritance (base type to derived type) Mike Pizzo: -Annotations are applied wherever the type is used. -Annotations are propagated along inheritance -Annotations defined in a derived type take precedence over the same type defined in the base type. -For structured annotations, should we apply merge (PATCH) semantics or replace (PUT) semantics? Mike Pizzo: -For collection-values annotations, should it replace or append? Ralf Handl (SAP): Ralf to get concrete scenarios for PATCH semantics for structured terms Ralf Handl (SAP): Postponed Ralf Handl (SAP): 4.ODATA-859 Define term, semantics for inserting error information into a (mostly) successful response Ralf Handl (SAP): This instance annotation can appear everywhere in a response, even on a property Ralf Handl (SAP): Could be used for in-stream errors when streaming responses, see ODATA-868 Ralf Handl (SAP): ODATA-859 is OPEN Ralf Handl (SAP): Potential changes to the term definition Ralf Handl (SAP): - make term array-valued Ralf Handl (SAP): - just one complex type with details - recursively Hubert Heijkers: <Term Name="Notification" Type="Core.NotificationType"> <Annotation Term="Core.Description" String="Instance annotation for warning and info notifications" /> </Term> <ComplexType Name="NotificationType"> <Property Name="code" Type="Edm.String" Nullable="false" /> <Property Name="message" Type="Edm.String" Nullable="false"> <Annotation Term="Core.IsLanguageDependent" /> </Property> <Property Name="severity" Type="Core.NotificationSeverity" Nullable="false" /> <Property Name="target" Type="Edm.String" Nullable="true"> <Annotation Term="Core.Description" String="A path to the target of the notification detail, relative to the annotated instance" /> </Property> <Property Name="details" Type="Collection(Common.NotificationType)" Nullable="false" /> </ComplexType> <TypeDefinition Name="NotificationSeverity" UnderlyingType="Edm.String"> <Annotation Term="Validation.AllowedValues"> <Record> <PropertyValue Property="Values"> <Collection> <Record> <PropertyValue Property="Value" String="success" /> </Record> <Record> <PropertyValue Property="Value" String="info" /> </Record> <Record> <PropertyValue Property="Value" String="warning" /> </Record> <Record> <PropertyValue Property="Value" String="error" /> </Record> </Collection> </PropertyValue> </Record> </Annotation> </TypeDefinition> Hubert Heijkers: <Term Name="Notifications" Type="Collection(Core.NotificationType)"> <Annotation Term="Core.Description" String="Instance annotation for warning and info notifications" /> </Term> Ralf Handl (SAP): Mike and Ralf prefer "Messages" instead of "Notifications" Ralf Handl (SAP): DMTF has "ExtendedInformation" which is a collection of "Messages" Ralf Handl (SAP): Mark: "notification" more common in sense of push notifications Ralf Handl (SAP): ODATA-859 is OPEN Mike Pizzo: I second Hubert Heijkers: I move to resolve ODATA-859 as proposed. Mike Pizzo: I second again Ralf Handl (SAP): ODATA-859 is resolved as proposed Ralf Handl (SAP): 5.ODATA-883 Validation Vocabulary: add MultipleOf term Ralf Handl (SAP): ODATA-883 is OPEN Ralf Handl (SAP): Mike: doesn't add burden as it is a term, not a CSDL construct Mike Pizzo: I move we approve ODATA-883 as proposed Hubert Heijkers: I second Ralf Handl (SAP): ODATA-883 is resolved as proposed Ralf Handl (SAP): 6.ODATA-884 Add term ErrorCodes to describe possible codes in error messages (public comment c201510e00019) Ralf Handl (SAP): Align with term defined in ODATA-859, e.g. "code" instead of "ErrorCode" Ralf Handl (SAP): Could be applied to entity sets, singletons, action/function imports, actions/functions Ralf Handl (SAP): <Annotation Term=Core.ErrorCodes Qualifier=Update></Annotation> <Annotation Term=Core.ErrorCodes Qualifier=Delete></Annotation> <Annotation Term=Core.ErrorCodes Qualifier=Create></Annotation> Mike Pizzo: From discussion: Mike Pizzo: -Swagger returns HTTP status codes; should we align? Perhaps nest OData error codes under HTTP status codes? -Could be applied to entityset, singleton, function, or action. -Consider aligning with new inline messages defined in ODATA-859 -Clarify that this was non-limiting. Intended use is for generating API documentation -Can specify via qualifier what http methods each set of possible error codes apply to, i.e.: <Annotation Term="Core.ErrorCodes" Qualifier="Delete"></Annotation> <Annotation Term="Core.ErrorCodes" Qualifier="Create"></Annotation> Ralf Handl (SAP): 6.Next meeting [9:50am PT] a.Thursday July 28, 2016 during 8-10am PT? Ralf Handl (SAP): Meeting after next: Ralf Handl (SAP): August 11th for four hours Ralf Handl (SAP): Decide next week whether to meet on August 4th for two hours Ralf Handl (SAP): August 18th two hours Ralf Handl (SAP): September 8th two hours Ralf Handl (SAP): 7.AOB and wrap up [9:55am PT] Ralf Handl (SAP): Meeting is adjourned anonymous1111 asked for a victim, I choose... anonymous111 anonymous211 asked for a victim, I choose... anonymous1 Room information was updated by: anonymous11111 <place room="room" info="info" call-in="call-in" here="here"></place> anonymous1111111 asks: null Magic 8-Ball says: Better not tell you now Room information was updated by: anonymous2111 <place room="room" info="info" call-in="call-in" here="here"></place> anonymous211111 asks: null Magic 8-Ball says: Outlook good anonymous3111 asked for a victim, I choose... anonymous3111 anonymous3111111 asks: null Magic 8-Ball says: My sources say no Ralf Handl (SAP): Voting Members: 7 of 11 (63%) (used for quorum calculation) Ralf Handl (SAP): Achieved quorumyes Ralf Handl (SAP): 2.Approve agenda [8:05am PT] Matt Borges (SAP): I'm having a hard time getting into the conference call. Is anyone else having the same problem? Ralf Handl (SAP): Hubert: General questions, e.g. wrt HTTP/2 Ralf Handl (SAP): New agenda item 4 1/2 Ralf Handl (SAP): 3.Approve minutes from previous meeting(s) [8:10am PT] a.Minutes from July 21, 2016 TC meeting:
https://www.oasis-open.org/apps/org/workgroup/odata/download.php/58581/odata-meeting-138_on-20160721-minutes.html Ralf Handl (SAP): 6.1.7: Remark on DMTF came from Mike, not Ralf anonymous2 morphed into Matt Borges (SAP) Ralf Handl (SAP): Mike: add agenda item for kickoff OpenAPI discussion Ralf Handl (SAP): New agenada item 4 1/4 Ralf Handl (SAP): Minutes approved with the above correction Ralf Handl (SAP): 4.Review action items [Action item list:
https://www.oasis-open.org/apps/org/workgroup/odata/members/action_items.php ] [8:15am PT] a.Action items due i.None Ralf Handl (SAP): 4 1/4. Mike reports on kickoff OpenAPI discussion Mike Pizzo: Background for discussion on a JSON representation of CSDL: Mike Pizzo: JSON Schema is a popular format for validating JSON payloads. Swagger/OpenAPI leverages and extends a compatible subset of JSON Schema to describe and document the paths exposed by a service. Neither fully describes a model-oriented hypermedia-driven REST service. OData defines such a model-oriented service description using a "Common Schema Definition Language (CSDL)". Currently this definition language is in XML, and the OData TC is investigating a JSON version of this model description language. We have been looking at several different approaches for this JSON representation of a model description language. 1)Base the representation on JSON Schema 2)Base the representation on Swagger/OpenAPI 3)Base the representation on some other format 4)Define a custom JSON representation Each of these have a set of pros and cons. 1)Base the representation on JSON Schema. Since JSON Schema was defined as a validation language, it lacks many of the modeling concepts such as inheritance fundamental to a modeling language. Swagger/OpenAPI faces many of these same restrictions. Additionally, describing an entity model in JSON Schema is much more verbose and less intuitive, from a modeling perspective, than a more direct mapping of the existing XML format to JSON. In addition, the extensions necessary to represent modeling concepts make the validation schema more verbose. 2)Swagger/OpenAPI goes beyond JSON Schema in describing the paths supported by a service, but it imposes even more restrictions (all extensions must start with x-). Also, Swagger/OpenAPI is prescriptive in the supported paths and doesn't (currently) have a good way of describing patterns/conventions. OData clients understand the operations they can perform against a service by understanding the model and a set of conventions for traversing the model; spelling these out in Swagger/OpenAPI is difficult (although work is going on to try and add support for this to OpenAPI). Because of the popularity of Swagger, we have done the work to define what an OData entity model would look like in Swagger/OpenAPI, and again the use of JSON Schema and the restrictions of Swagger/OpenAPI makes it more verbose and less intuitive than a custom JSON representation, and at the same time the additional extensions required to represent an OData model make the Swagger definition more verbose and less intuitive. 3)We are not aware of any existing formats that don't have the same types of issues as JSON Schema and Swagger/OpenAPI. 4)Several efforts have demonstrated that a direct representation of an OData model in JSON can be both concise and intuitive. Existing JSON client would still be able to parse a custom format, but existing tooling written around validation and API documentation wouldn't know what to do with this new format. After doing some research into each option, we are considering defining a custom JSON format for OData models with tools/transforms that can generate a Swagger/OpenAPI representation (and perhaps other representations, such as RAML) anonymous morphed into Martin Zurmuehl (SAP) Susan Malaika2: it would be great if u include the links to the proposal docs along with the text Susan Malaika2: it will also be great if you summarize the improvements since our last review Susan Malaika2: it will also be great if you summarize the improvements since our last review Susan Malaika2: will you have a call with Open API before we have the internal call in IBM? Susan Malaika2: will you have a call with Open API before we have the internal call in IBM? Ralf Handl (SAP): 4 1/2. Hubert's questions Ralf Handl (SAP): Interesting discussion around HTTP/2, GRPC, protoBuf, CBOR, ... Ralf Handl (SAP): 5.V4.01 [8:20am PT] a.Issues for V4.01_WD01 in New or Open state i.Ripe for resolution 1.ODATA-923 $expand (or $include) for $metadata to include referenced schemas Ralf Handl (SAP): Validate proposal with implementation teams, e.g. Olingo team Ralf Handl (SAP): ii.OData Protocol 1.ODATA-873 Define a default order for deep inserted entities in responses Ralf Handl (SAP): Mike: use annotation in request that is echoed in the response, similar to Content-ID header in $batch requests Ralf Handl (SAP): Instance annotation that is not (necessarily) persisted Ralf Handl (SAP): Only needed for server-generated keys Ralf Handl (SAP): ODATA-873 is OPEN Ralf Handl (SAP): @odata.contentID Matt Borges (SAP): Updated proposal: The client can specify an instance annotation on the nested entities that the server MUST return as instance annotation in the corresponding entity in the response. Matt Borges (SAP): Updated proposal2: The client can specify @odata.contentID the instance annotation on the nested entities that the server MUST return the @odata.contentID instance annotation in the corresponding entity in the response. Matt Borges (SAP): The client can specify @odata.contentID instance annotation in the nested entities in the request and the server MUST return the @odata.contentID instance annotation in the corresponding entity in the response. Ralf Handl (SAP): Hubert: make this a conformance clause? Ralf Handl (SAP): Mike: is a Protocol issue that then has representations in JSON and Atom formats Ralf Handl (SAP): Mike: should have a capability for deep-insert Ralf Handl (SAP): Mike: make contentId support part of this capability term Ralf Handl (SAP): Matt to answer these questions in an updated proposal Ralf Handl (SAP): 2.ODATA-942 How should headers applied to a batch affect statements within a batch Ralf Handl (SAP): Mark will provide proposal for next week Ralf Handl (SAP): 3.ODATA-949 Clarify the affect Accept-Language header has on a delta response Ralf Handl (SAP): ODATA-949 is OPEN Matt Borges (SAP): Revised Proposal: Clients should use the same Accept-Language header when using a delta link as was used with the defining query. Servers MAY reject a delta link used with a different Accept-Language header as Not-Acceptable. Mike Pizzo: Clarify: Clients SHOULD specify the same Accept-Language header when querying the delta link as was specified in the defining query. Services MAY return Not Acceptable if a different Accept-Language is specified. If a service does support an Accept-Language header it MAY return changes only visible in that language, or MAY return records that have changes not visible in the requested language. Matt Borges (SAP): I move we resolve ODATA-949 with the revised proposal. Matt Borges (SAP): I move we resolve ODATA-949 with the revised proposal. Mike Pizzo: I second Ralf Handl (SAP): ODATA-949 is resolved with the adapted proposal Ralf Handl (SAP): 6.Next meetings [9:50am PT] a.Thursday August 04, 2016 during 8-10am PT Ralf Handl (SAP): 7.AOB and wrap up