[TriLUG] how to document an XML schema across versions

[William Sutton]

It sounds like you need to write an XSD for it.  That said, I wouldn't 
know where to begin.

If you just want tabular documentation, you could probably make a 
cross-reference database with
node table:
- node uid
- node or attribute xpath
- node type (char, varchar, int, float, boolean)
- node constraints (not null, must be between 0 and 10, etc.)
XML revision table
- rev uid
- rev #
- rev date
feature xref table:
- node uid
- rev uid

and then you can programatically cross-reference when a particular 
attribute became available, where to access it, what its attributes are, 
etc.  (add columns for things I didn't think of).

the benefit to doing it as a database is... you could provide a RESTful 
API to look up attributes from a web service, if you wanted to.

William Sutton

On Thu, 12 Feb 2015, Hrivnak, Michael wrote:

> I have a documentation project to tackle, and I think the key will be
> having the right tool. I'm hoping one of you can point me at something
> appropriate.
>
> Background:
> There is an XML schema that's been in wide use for a long time with little
> documentation. It has changed over the years as the tools that read and
> write it have changed, but nobody has taken the time to carefully document
> those changes. Those tools have been strongly versioned, so it's best to
> think of the XML schema as being versioned in-step with the tools. A wide
> range of these tools are in regular use today.
>
> Other third-part tools sometimes need to consume this XML, and the lack of
> docs makes integration painful. Periodically we discover yet another
> "gotcha", where some particular version had something unexpected; I want
> somewhere to document that.
>
> Goal:
> I want to document the schema, and especially how it has changed over time.
> I need it to be easy to see that an attribute didn't exist before version
> x.y.z, had a default value of empty string starting with some other
> version, then went to a default value of "0" in a later version.
>
> Human-readability is the most important goal. Being able to validate XML
> with the documented schema would be a bonus.
>
> Have a suggestion for how to represent this? I could produce something
> valuable with a word processor by using comments all over the place, but
> that seems like it would get out of hand and be cumbersome to use. It
> wouldn't show me "here's everything that changed from version x.y.0 to
> x.y+1.0.
>
> Thanks,
> Michael
> -- 
> This message was sent to: William <william at trilug.org>
> To unsubscribe, send a blank message to trilug-leave at trilug.org from that address.
> TriLUG mailing list : http://www.trilug.org/mailman/listinfo/trilug
> Unsubscribe or edit options on the web	: http://www.trilug.org/mailman/options/trilug/william%40trilug.org
> Welcome to TriLUG: http://trilug.org/welcome