[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [odata] JSON CSDL: Representing property facets
Needless to say I like were this is going;-), thanks Ralf!
Just to be sure we are totally on the same page wrt JSON Schema, I
envisioned a situation were we the JSON Schema we'd return would be a
document that could be used to validate input and responses of an OData
service based on a certain CSDL, not representing everything that is
described by the CSDL necessarily. Is that what you see too?
If we make that clean abstraction I can see us specify a fixed JSON Schema
file for the JSON CSDL itself as well, just for completeness perhaps but
anyway. The thing I don't know yet is if we could then use the information
for our odata.context to know what part of the JSON Scheme to use to
validate the response by such request as well. I'd imagine one could given
that type and everything is clear from that context.
Happy holidays and all the best wishes for 2015!
Cheers,
-H
Hubert Heijkers
STSM, Chief Architect TM1 Server
Business Analytics
Phone: +31-20-513-9456
Mobile: +31-621-394123
E-mail: hubert.heijkers@nl.ibm.com
(Embedded image
moved to file:
pic17957.gif)
(Embedded image moved to file: pic26497.gif)Facebook Button
(Embedded image moved to file: pic47998.gif)LinkedIn Button
OData Button
OASIS Button
(Embedded image moved to file: pic08346.jpg)
(Embedded image moved to
file: pic18892.jpg)
From: "Handl, Ralf" <ralf.handl@sap.com>
To: "Borges, Matt" <matt.borges@sap.com>, Hubert
Heijkers/Netherlands/IBM@IBMNL, "Ireland, Evan"
<evan.ireland@sap.com>
Cc: "odata@lists.oasis-open.org" <odata@lists.oasis-open.org>
Date: 12/18/2014 02:31 PM
Subject: RE: [odata] JSON CSDL: Representing property facets
Sent by: <odata@lists.oasis-open.org>
To base the future discussion on concrete examples I went back two months
in SVN and forked off the last pre-JSON-Schema transformation, reapplying
all changes to the non-JSON-Schema part. The results can be found in SVN:
New Revision: 650 (metadata and annotation examples)
Web View:
https://tools.oasis-open.org/version-control/browse/wsvn/odata/?rev=650&sc=1
New Revision: 651 (vocabularies Core, Measures, Capabilities)
Web View:
https://tools.oasis-open.org/version-control/browse/wsvn/odata/?rev=651&sc=1
You can get a side-by-side view by comparing each file with its previous
version and choosing “Show entire file” just above the file content area,
e.g.
https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/examples/csdl-16.1.json?op=diff&rev=650&sc=1&all=1
You’ll notice that the new JSON CSDL format is more compact, and maybe it
is closer to the “nice clean JSON CSDL” that Hubert wants to have.
Feedback is highly welcome!
--Ralf
_____________________________________________
From: Borges, Matt
Sent: Tuesday, 16. December 2014 19:50
To: Handl, Ralf; Hubert Heijkers
Cc: odata@lists.oasis-open.org
Subject: RE: [odata] JSON CSDL: Representing property facets
Thanks for explaining the evolution of the JSON CSDL. I know originally
the proposal for a JSON CSDL format mentioned we could start with the JSON
payloads returned from the Metadata Service, but I didn’t know the reason
(s) why we moved away from that until your email below.
I like the two document approach; it allows for the OData-specific document
to be as consistent as possible with the rest of the spec (deviating where
necessary for the reasons Ralf pointed out) but allows for the additional
document to satisfy additional goals.
Matt
_____________________________________________
From: Handl, Ralf
Sent: Tuesday, December 16, 2014 4:19 AM
To: Borges, Matt; Hubert Heijkers
Cc: odata@lists.oasis-open.org
Subject: RE: [odata] JSON CSDL: Representing property facets
I share your concerns, and I think it is time to restate the goals we want
to achieve, retrace how we arrived at the current unsatisfying point, and
consider where we could go instead.
The primary goal (at least for SAP) is:
JSON CSDL contains the same information as the XML format for CSDL defined
in [OData?CSDL]
This has a practical reason: our main consumers for OData services are
JavaScript-based, and we just want to use JSON.parse() to interpret
$metadata.
As this primary goal gives a lot of leeway for defining the actual payload
format, we can choose which secondary goal or goals we want to achieve, and
this is where we seem to have several choices.
A. Make JSON CSDL as consistent as possible with existing OData concepts
B. Make JSON CSDL appeal to JavaScript programmers as our main target
audience for OData consumption
C. Make JSON CSDL appeal to JSON Schema fans, including other standards
bodies
The initial stab at JSON CSDL followed the secondary goal A and produced a
static JSON format that very much looked like expanded responses from the
Metadata Service, but had two drawbacks:
Annotations looked quite different from instance annotations in the JSON
Format
The JSON.parse’d JavaScript object graph wasn’t very friendly to use for
JavaScript programmers
So with a lot of feedback from our OpenUI5 developers we reformulated the
secondary goal B to
JSON.parse() of JSON CSDL creates a JavaScript object graph that
Appeals to JavaScript programmers by following common naming conventions
Satisfies basic access patterns
Can easily be augmented with client-side post-processing to satisfy more
sophisticated access patterns
This lead to four simple transformation rules:
Element and attribute names in UpperCamelCase are converted to
lowerCamelCase, and uppercase attribute names are converted to lowercase
Attributes and elements that can occur at most once within a parent become
name/value pairs
Elements that can occur more than once within a parent and can be uniquely
identified within their parent (schemas, key properties, entity sets, …)
became a name/value pair with pluralized name and a "dictionary" object as
value containing one name/value pair per element with the identifier as
name
Elements that can occur more than once within a parent and cannot be
uniquely identified within their parent (action overloads, function
overloads, …) become a name/value pair with pluralized name and an array as
value containing one item per child element
The result satisfied the primary goal and the reformulated secondary goal
B, and partially reached the secondary goal A: little similarity with
responses from the Metadata service, but at least an annotation format that
closely resembles that of instance annotations.
The result also had some similarity with JSON Schema, which is where the
secondary goal C entered the picture. We are now in a stage where we
achieve secondary goal C, but have compromised secondary goal B and
unfortunately also the primary goal: some information is still “contained”,
but in a way that is really hard to recognize. Most notable are Edm
primitive types and their facets as well as inheritance.
This makes Hubert’s proposal very attractive: instead of striving for “one
size that fits no-one” we could have
A primary OData-specific format that is returned when requesting
application/json
A secondary JSON Schema format that is returned when requesting
application/schema+json
What do you think?
_____________________________________________
From: Borges, Matt
Sent: Friday, 12. December 2014 18:52
To: Hubert Heijkers; Handl, Ralf
Cc: odata@lists.oasis-open.org
Subject: RE: [odata] JSON CSDL: Representing property facets
I agree with Hubert. My impression is that instead of making an equivalent
JSON representation of the CSDL, we are making something more complicated
and harder to read so that we adhere to another spec. And in some cases, I
think we are losing some of the OData information. For example, in section
4.1.2.4 in the JSON CSDL document, there is an example of an Edm.Decimal
property, Price. Nowhere in the example JSON does it actually say that the
OData type of the property is Edm.Decimal. Yet if you were to access that
property directly (i.e. ~/Entity(key)/Price), the context URL in the
payload would contain Edm.Decimal.
Another thing to consider is that in the current CSDL document we have the
section about Metadata Service Schema. The JSON payloads that are returned
when accessing this service is quite different than the proposed JSON CSDL
format based on JSON schema, yet it is intended to represent the same
information. That seems like a huge inconsistency in our spec.
I think our highest priority has to be clearly and concisely describing the
OData metadata of a service in a JSON document that is consistent with the
rest of the OData spec. As Hubert mentions, JSON schema does not appear to
be a natural fit.
Matt
-----Original Message-----
From: odata@lists.oasis-open.org [mailto:odata@lists.oasis-open.org] On
Behalf Of Hubert Heijkers
Sent: Friday, December 12, 2014 6:00 AM
To: Handl, Ralf
Cc: odata@lists.oasis-open.org
Subject: Re: [odata] JSON CSDL: Representing property facets
Hi Ralf, et.al.,
It's been bothering me for a bit, and I don't think I can express very well
what exactly it is, but I more and more am getting the feeling, especially
when I see things like you are proposing, that we are creating something
pretty ugly just because we are trying to adhere to something that is not
likely the best natural fit for what we are trying to convey, which, after
all, is the schema of our service.
Now don't get me wrong, I do see value in having a JSON schema, but for
those cases were we'd want to validate our payloads, for which we need less
then what we are trying to put in currently. As you say, there are clients
that are not interested in validating payloads, and I wonder, aren't we
making it to hard on them because we are trying to make the JSON CSDL a
JSON Schema too?
So here is a crazy idea, why wouldn't we have a nice clean JSON CSDL and,
separately, allow services to provide a JSON Schema as well put purely for
validation, meaning that it wouldn't have to convey any of the OData
specifics?
Any thoughts anybody? Tell me if you think I'm nuts too, wouldn't be the
first time, I can take it;-).
Happy holidays,
-H
Hubert Heijkers
STSM, Chief Architect TM1 Server
Business Analytics
Phone: +31-20-513-9456
Mobile: +31-621-394123
E-mail: hubert.heijkers@nl.ibm.com
(Embedded image
moved to file:
pic10387.gif)
(Embedded image moved to file: pic53554.gif)Facebook
Button
(Embedded image moved to file:
pic10481.gif)LinkedIn Button
OData Button
OASIS Button
(Embedded image moved to file: pic46286.jpg)
(Embedded
image moved to
file:
pic56306.jpg)
From: "Handl, Ralf" <ralf.handl@sap.com>
To: "odata@lists.oasis-open.org" <odata@lists.oasis-open.org>
Date: 11/28/2014 11:29 AM
Subject: [odata] JSON CSDL: Representing property facets
Sent by: <odata@lists.oasis-open.org>
I’ve received feedback that the current translation of primitive type
facets into JSON Schema makes the JSON CSDL hard to understand for clients
that are not interested in validating payloads but just want to get the
OData metadata.
For example a simple
<Property Type="Edm.Decimal" Name="Price" Precision="15" Scale="3" />
Becomes (as Nullable="true" is the default):
"anyOf":[{"type":"number", "multipleOf":0.001, "minimum":-999999999999.999,
"maximum":999999999999.999}, {"type":"null"}]
One way to make this more digestible would be to redundantly add the OData
facets to the JSON Schema representation:
"anyOf":[{"type":"number", "multipleOf":0.001, "minimum":-999999999999.999,
"maximum":999999999999.999}, {"type":"null"}], "precision":15, "scale":3
And redundantly add "nullable":false so clients don’t have to check for the
anyOf" or "type":["number","null"] constructs.
What do you think?
Thanks in advance!
--Ralf
In preparing for battle
I have always found that plans are useless,
but planning is indispensable.
- Dwight D. Eisenhower
Attachment:
pic17957.gif
Description: GIF image
Attachment:
pic26497.gif
Description: GIF image
Attachment:
pic47998.gif
Description: GIF image
Attachment:
pic08346.jpg
Description: JPEG image
Attachment:
pic18892.jpg
Description: JPEG image
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
