OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

odata message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [odata] JSON CSDL: Representing property facets





A primary OData-specific format that is returned when requesting application/json”


I would agree (if we are going to have JSON-based CSDL at all), that this is preferable (and primary).


The client may already be using a library that does validation according to the CSDL constraints. A JSON Schema isn’t needed for that, just clear and concise CSDL _expression_ in some agreeable JSON format.


From: Handl, Ralf [mailto:ralf.handl@sap.com]
Sent: Tuesday, 16 December 2014 10:19 p.m.
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 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.




-----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



Any thoughts anybody? Tell me if you think I'm nuts too, wouldn't be the

first time, I can take it;-).


Happy holidays,







                     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: 











                     (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>

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!



        In preparing for battle

        I have always found that plans are useless,

        but planning is indispensable.

        - Dwight D. Eisenhower




[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]