Yes, I think it would be good if we mentioned each term in one of the standard vocabularies at least once in the prose specifciations. Maybe we should add a chapter in Part 1: Protocol that at least lists all of the terms. Sort of extract of the XML files, just term names and term description. What do you think? From: Mark Biamonte [mailto:
Mark.Biamonte@progress.com] Sent: Donnerstag, 1. Oktober 2015 15:31 To: Handl, Ralf <
ralf.handl@sap.com>; Mark Stafford <
mastaffo@microsoft.com> Cc:
odata@lists.oasis-open.org; Garimella, Anila Kumar <
AnilaKumar.GVN@ca.com> Subject: RE: [odata] RE: JSON as default format What would have helped me in this particular case was if the description for the Accept header and the $format query parameter had some text that said that if neither is specified the returned format is service dependent. A client can determine the list of supported formats by examining the SupportedFormats capability. I know that doesn’t address the your general question though. Mark B From: Handl, Ralf [ mailto:
ralf.handl@sap.com ] Sent: Thursday, October 01, 2015 4:21 AM To: Mark Stafford Cc: Mark Biamonte;
odata@lists.oasis-open.org ; Garimella, Anila Kumar Subject: RE: [odata] RE: JSON as default format Hi Mark, This kind of problem is showing up with increasing frequency: · You know it’s somewhere but you can’t find it, or even worse · You don’t know whether it is somewhere and don’t know where to start looking for it This is worst for the vocabularies because we only mention a subset of the terms in the prose specifications, but it’s not much better for the prose specs: should you look in Part 1, 2, 3, or the JSON Format spec first? Or was it in Data Aggregation, or JSON CSDL, or Temporal? Bundling all of the specs into one large document probably also won’t help. Should we extend the “ What’s New ” document to mention all “key” words and include links to the relevant documents and sections? Or should we start an FAQ, Index, and Glossary on odata.org? Thoughts? Thanks in advance! --Ralf From: Mark Stafford [ mailto:
mastaffo@microsoft.com ] Sent: Donnerstag, 1. Oktober 2015 05:23 To: Handl, Ralf <
ralf.handl@sap.com > Cc: Mark Biamonte <
Mark.Biamonte@progress.com >;
odata@lists.oasis-open.org ; Garimella, Anila Kumar <
AnilaKumar.GVN@ca.com > Subject: RE: [odata] RE: JSON as default format I knew that was out there somewhere. I was looking in the core vocabulary but I guess capabilities makes sense. Thanks for reminding me. Sent from Outlook Mail for Windows 10 phone From: Handl, Ralf Sent: Wednesday, September 30, 2015 6:26 PM To: Mark Stafford Cc: Mark Biamonte;
odata@lists.oasis-open.org;Garimella, Anila Kumar Subject: RE: [odata] RE: JSON as default format For this we already have a term in the Capabilities vocabulary
http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/vocabularies/Org.OData.Capabilities.V1.xml : <Term Name="SupportedFormats" Type="Collection(Edm.String)"> <Annotation Term="Core.Description" String="Media types of supported formats, including format parameters"/> <Annotation Term="Core.IsMediaType"/> </Term> I haven’t gotten around to leverage that term in my experimental CSDL-to-Swagger XSL transformation , but it’s on my TODO list J From: Mark Stafford [ mailto:
mastaffo@microsoft.com ] Sent: Mittwoch, 30. September 2015 10:10 To: Handl, Ralf <
ralf.handl@sap.com >; Garimella, Anila Kumar <
AnilaKumar.GVN@ca.com > Cc: Mark Biamonte <
Mark.Biamonte@progress.com >;
odata@lists.oasis-open.org Subject: RE: [odata] RE: JSON as default format Swagger prescribes “produces” and “consumes” static fields that help consumers to know what mime types are supported. With this information also in $metadata we can more accurately generate Swagger docs rather than guessing at whether the server consumes/produces specific formats. (This isn’t too much of an issue right now since we kind of expect OData servers to support the JSON format, but obviously it doesn’t have to be that way.) From: Handl, Ralf [ mailto:
ralf.handl@sap.com ] Sent: Wednesday, September 30, 2015 4:04 PM To: Mark Stafford <
mastaffo@microsoft.com >; Garimella, Anila Kumar <
AnilaKumar.GVN@ca.com > Cc: Mark Biamonte <
Mark.Biamonte@progress.com >;
odata@lists.oasis-open.org Subject: RE: [odata] RE: JSON as default format Hi Anil and Mark S,
https://issues.oasis-open.org/browse/ODATA-805 suggests to add a term to the Capabilities vocabulary that describes the supported $metadata formats. We probably should extend this term to also name the default format: feel free to comment on the Jira issue or directly edit the proposal. @Mark S: how would that help with producing Swagger documents from OData services? Thanks in advance! --Ralf From:
odata@lists.oasis-open.org [ mailto:
odata@lists.oasis-open.org ] On Behalf Of Mark Stafford Sent: Mittwoch, 30. September 2015 05:00 To: Garimella, Anila Kumar <
AnilaKumar.GVN@ca.com >; Mark Biamonte <
Mark.Biamonte@progress.com >;
odata@lists.oasis-open.org Subject: RE: [odata] RE: JSON as default format Anil, I think that’s a great suggestion for a possible vocabulary. It would also smooth some of the gaps in projecting Swagger documents from OData services. I’d welcome a proposal at the GitHub repo for vocabularies:
http://www.github.com/odata/vocabularies . From:
odata@lists.oasis-open.org [ mailto:
odata@lists.oasis-open.org ] On Behalf Of Garimella, Anila Kumar Sent: Wednesday, September 30, 2015 2:13 AM To: Mark Stafford <
mastaffo@microsoft.com >; Mark Biamonte <
Mark.Biamonte@progress.com >;
odata@lists.oasis-open.org Subject: Re: [odata] RE: JSON as default format That might mean a generic client wouldn't known before hand what to expect for 2 different services unless it can see response headers, unless it states by its headers what format it wants to see? Can there be a flag in $metadata stating the default format the service chose? On the same lines, the default odata.metadata level is minimal. Is there a way, a service can decide to override this and say in it's $metadata that by default "odata.metadata=none" in its responses? -- Anil / Platform@CA From: "
odata@lists.oasis-open.org " on behalf of Mark Stafford Date: Monday, September 28, 2015 at 7:26 PM To: Mark Biamonte, "
odata@lists.oasis-open.org " Subject: [odata] RE: JSON as default format Typically we say that the default is up to the server. The server only needs to support one of the standardized serialization formats – but since JSON is the only format that is fully standardized at this point, we typically expect JSON to be the default response. I can also say that I * hope * it’s not put down somewhere in the standard as the default. I personally believe we’re at the height of the maturity curve for JSON, and I think as HTTP debugging tools continue to rapidly improve, that we will see a shift in the default serialization format from JSON to a binary format, similar to what we’re seeing happen with HTTP2. So in my personal ideal future state, we would see something like Avro take over as the default serialization format for OData payloads – but of course that depends upon the ability of the server to choose the right default for the API. Thoughts? Pushback? From:
odata@lists.oasis-open.org [ mailto:
odata@lists.oasis-open.org ] On Behalf Of Mark Biamonte Sent: Tuesday, September 29, 2015 4:06 AM To:
odata@lists.oasis-open.org Subject: [odata] JSON as default format I know that the default format for services in OData v4 changed to be JSON, but I am having difficulty in the spec finding where it explicitly states that. I would have expected to find something in the definition of the accept header and the $format query parameter. Something along the lines of if the accept header and $format query parameter are not present then the JSON format is used. Mark