[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Chat Trace (Kudos to Susan)
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]