[TriLUG] how to document an XML schema across versions

[Steve Burnett via TriLUG]

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

Some links that might help at least partially:
http://www.freeformatter.com/xsd-generator.html
http://www.freeformatter.com/xml-validator-xsd.html

best practices for documenting XML schemas advice
http://www.adivo.com/best-practices-guide/documenting-xml-schemas.aspx
http://www.adivo.com/resource-center/xml-schema-resources.aspx

a not-free and Windows-only doc generator for XML schemas
http://www.adivo.com/techwriter-for-xml-schemas.aspx

hope this helps,
Steve