----- Original Message -----
From: "David Lutterkort" <lutter(a)redhat.com>
To: "Martyn Taylor" <mtaylor(a)redhat.com>
Sent: Wednesday, 8 June, 2011 1:09:11 PM
Subject: Re: CLI - Formal XML Definition
On Tue, 2011-06-07 at 06:45 -0400, Martyn Taylor wrote:
Providing a formal deffinition of the XML for an API, makes using
API, in particular creating and maintaining client applications that
utilise the API much simpler, and far clearer for a developer.
I completely agree that we need better docs for (at least) the
Deltacloud API. I am highly doubtful though that a grammar for the XML
is the right answer here - for the nitty-gritty of what's in the XML,
going to deltacloudd's HTML interface does the job for the most part.
I find XSD plain unreadable, and even a RelaxNG grammar doesn't quite
pay back the effort you need to put into it for this sort of API.
The issue with proving documentation although human readable, is that it is almost always
not fully comprehensive, and sometimes out of sync with the codebase. Which I suppose
could be said about a formal definition should it not be updated. Another problem is that
it is not machine readable.
There are an array of tools that provide class generation, and
automatic marshalling and unmarshalling of objects,
'Class generation' is really an artifact of certain features of some
languages; in languages like Ruby or Python there isn't really a need
for ahead-of-time class generation. The Deltacloud Ruby client, for
example, 'unmarshals' XML into Ruby objects dynamically, for the most
part following simle rules about how XML constructs are turned into Ruby
Ruby and Python might not need ahead of time class generation, I'm sure others
languages too, but there are languages that would benefit from this. The main benefit of
marshalling objects to XML is to make it language independent. Even with this in mind, a
quick look at the code base for both these clients, and they have specific information in
there about the API. e.g. hwp_properties.rb (I'm not really familiar with this code
base, maybe there is some other reason for this).
I personally don't see a particularly large overhead in creating a formal definition,
I wrote one a while back for DC which probably took me a day, and the main timesync there
was figuring out what the XML actually looked like since the doc was so out of date
generated straight from a formally defined XML Document, for ruby,
this project looks to offer these functions:
As far as I can tell, this is simply a SOAP (blech) library. And much
less popular than Savon.
Great, some better tools :)
In my experience writing Java and Android clients, I have found that
the time spent creating an XSD or other formal XML definition, repays
10 fold in development time, and also makes keeping clients up to date
How exactly has having XSD helped you there (not trolling, I am really
Firstly, XSDs are machine readable and there are tools that let you do things like class
generation or what ever else, which is a massive time saver in a language like Java.
I'm sure there are many other tools in many other languages that offer this + more
functionality, when providing a machine readable definition.
Secondly, and probably more importantly for me, is that they offers a clear, concise,
comprehensive and standard descriptions of the data model. Which from a developing
perspective is really what I want.
I'm not at all trying to advocate XSD, RelayNG, but since a data model in Aeolus uses
XML that would be a potential way to describe the model in a formal way.
If there are alternative solutions that offer the best of both worlds then awesome.
Offering a formal definition along side documentation would probably give us the best of