JSON vs XML/XSD (was: sending search criteria in request body?)

[Martin Kügler]

I used to think the idea of XSD and equivalent were important, but I've since become disenchanted.  I'd be interested to know the specific things you see them enabling and/or preventing?  Thanks in advance.

-Mike

Hi Mike and everyone,

(since the topic shifted away from the original question, I changed the subject.)

Funny you mention this, I am currently experiencing the same - I used to very much like XSD as interface contracts, but for my current project I am very tempted to expose mainly or even only JSON.

On the prod-side of things I see nothing apart from the obvious, like

* a fine grained definition of structure and and allowed ranges for values xs:dateTime, xs:int, xs:id amke it very clear what you expect.

* tools for frameworks like Java and .NET (any others?) that allow to generate classes from the xsd's to allow developers a pretty quick access to the data.

* maybe re-use of common types in several contracs, although more often than not that intrduces more headache than it solves.

On the down side, it is 

* very time consuming to define XSD's

* not so straight forward to use the generated classes (should you always build them from XSD's in zyou CI build or provide them as dependency to you project etc)

* normally there are some subtle problems in how the respective frameworks generate their classes, since XSD is not 1:1 translatable to an object model (e.g.: optional parameters used to generate boolean "switch"-fields in .NET. Not sure if this is still the case.)

* most of the time you still need examples to get developers going with your API.

On the other hand, JSON is so easily written in any old text editor to create examples and really, it has been a long time since I have seen a public service publishing XSD's, it seems everyone explains their API by examples and using JSON.

Doing some polyglot programming e.g. in Java using Groovy to read JSON, you maybe don't feel a need for generated classes any more, anyway (how cool is that: http://groovy.codehaus.org/gapi/groovy/json/JsonSlurper.html)

There is an IETF draft do define a JSON schema - no idea how much resonance this has: http://tools.ietf.org/html/draft-zyp-json-schema-03

cheers,

Martin

[Neil Brown]

Hi, 

Interesting topic. We're in the process of designing some new REST APIs, which support XML representations, and I'm proposing we produce XSD, primarily as part of documenting the APIs. The pros as I see them are similar to the ones already mentioned below, with some additions - 

1) Precisely defines the types (resources) and cardinality of elements for API clients, removing ambiguities that occur if you rely on specification through (repeated) examples. This will also serve to remove ambiguity in other (e.g. JSON) representations if we support them in the future.

2) Useful to support validation of generated XML representations (output) on both the client and the server side, by their respective test suites. 

3) May help to automate the building of API clients, e.g. generating DTOs.  

4) On the server-side, the use of schema also supports validation of client requests although this should be kept purposely loose, so as to be as forgiving as possible.

However, I'm aware that in practice it may not all be as great as the above seems. Possible issues I foresee:

1) The schemas are going to need to be specified on a per API, rather than per resource basis, because the representation (extent of fields) may vary across APIs. That means a greater number of schemas.

2) The schemas are going to need to be versioned inline with the API. More stuff to maintain.

Interesting in hearing from other people's views in light of experience.

Thanks, 

Neil.

[Arlo Belshee]

With OData, we set out to solve a similar problem. We wanted to support a strong tooling experience and generic clients on top of any data service. That meant that we needed to provide a standard mechanism for a service to describe its data model.

 

Our solution was /$metadata. This worked reasonably well.

 

We defined a modeling mini-language, and a representation of that in XML. We could have gotten part of the value with just XSDs, but we wanted more generic clients. In particular, we wanted a client to not only know that there could be a “Manager” element inside of an “Employee” element, but to also know that “Manager” represented a relation to another PersonType entity.

 

A few years down the line, we’re seeing a number of advantages that came from making each service self-describing:

 

·         Generic tools are able to ask a service what it supports and learn about what queries it’ll probably handle (this could be made better, and probably will in future releases, but it is being used successfully today).

·         Clients can tell a little more about the meaning of the things it sees in resources, which allows generic clients to display things to users in a useful manner (e.g., if an element represents a navigation property, then show it as a link. But if it’s a regular property, just show it as text).

·         This will allow us to dramatically reduce the amount of control information in each resource, yet still maintain zero service-specific machine understanding of services.

·         This makes it easy to do client-side code generation (in statically-typed languages) for a particular service – the machine can understand the service.

·         There is a service-central place to put information of relevance to clients (e.g., model version).

 

There are also several disadvantages:

 

·         DTDs already have parsers in every language. If you define your own metadata format, then you need to either write all those parsers or be important enough that open source projects will appear and write them for you. We still have problems with this, and we’re a lot bigger than just one service.

·         If you support client-side code generation in static languages, then people will use it. And those people tend to expect more backwards-compatibility support (while understanding their own code less – especially the generated code parts). So you might need to be more deliberate in your model changes. In other words, this can help open up a new market, but serving that market has costs.

·         We really should have made a JSON representation for /$metadata too. Perhaps we will someday (I’ve seen individual efforts in this direction, but no one has yet tried to promote one to the protocol spec level).

 

There’s probably more learning available, but this is what I’ve got on top of mind.

 

Arlo