Google Groups

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

Neil Brown Apr 4, 2012 3:04 PM
Posted in group: API Craft

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.



On Monday, 19 March 2012 12:32:08 UTC, Tino wrote:

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.


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:

There is an IETF draft do define a JSON schema - no idea how much resonance this has: