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.
- Make JSON CSDL as consistent as possible with existing OData concepts
- Make JSON CSDL appeal to _javascript_ programmers as our main target audience for OData consumption
- 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
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
(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)
Date: 11/28/2014 11:29 AM
Subject: [odata] JSON CSDL: Representing property facets
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