[SOLVED] What is the best format for documenting XML?

What is the best format for documenting XML?

I am currently writing the specification for an API that works as follows:

Client makes a HTTPS post to a particular URL with zero or more HTTP parameters
Server responds with a short XML document

The data being transferred is very light. Most of the responses will be smaller than 1k, and the largest would be only 10k.

Backwards compatability is important. I would like old clients to continue to work correctly against a upgraded version of the server.

This is what I want to tell the clients:-

I expect the client to read the XML, but only access those elements which it needs for processing.
Additional elements or attributes may be added into the XML document at any time when the server is upgraded. The clients should skip anything they did not know about.

This is so that old clients will continue to work even though additional information is now returned in a response. (Removing elements from the XML is obviously more difficult and some process for deprecation would be needed).

What is the best format for documenting the XML that is returned?

I have concerns about using a formal language for this documentation (e.g. XSD):

addition of extra attributes or elements would mean the XML was not meeting a previously published specification
this would tempt people writing clients to parse everything in the XML (even if they do not use it) making it harder to remove elements should that become necessary

Alternatively, am I going about the backwards-compatability wrong? Is this a well-solved problem already? Should the client be asking for a particular version of the response XML?

Solution

IMO, you should send your client's desired version along with the request and return that format. as you'll need to compute the info of previous versions anyway, there's no need to bloat up the answer when you know the client won't use it. if you have an xml independent data structure backing your response code, you can probably even reuse your xml creator for old-style responses.

Of course, this assumes that the response document is dynamically created. Otherwise, won't an XQuery or something similar do exactly what you want: filtering the document for only known elements/values?