How to document the structure of XML files

When it comes to documenting the structure of XML files. One of my co-workers does it in a Word table. Another pastes the elements into a Word document with comments like this:

Which one of these methods is preferred? Is there a better way? Are there other options that do not require third party Schema Documenter tools to update?

2,125 2 2 gold badges 26 26 silver badges 35 35 bronze badges asked Nov 17, 2009 at 23:23 17.4k 36 36 gold badges 97 97 silver badges 133 133 bronze badges

6 Answers 6

I'd write an XML Schema (XSD) file to define the structure of the XML document. xs:annotation and xs:documentation tags can be included to describe the elements. The XSD file can be transformed into documentation using XSLT stylesheets such as xs3p or tools such as XML Schema Documenter.

For an introduction to XML Schema see the XML Schools tutorial.

Here is your example, expressed as XML Schema with xs:annotation tags:

      Current version of the object from the repository.    Name of the object from the repository.

557 5 5 silver badges 23 23 bronze badges answered Nov 17, 2009 at 23:34 26k 9 9 gold badges 69 69 silver badges 78 78 bronze badges Well played Phil, well played ;) Commented Nov 18, 2009 at 3:47

Good idea. Although I am a little worried that my documentation will never get updated because someone now needs another tool to update it.

Commented Nov 18, 2009 at 4:56

@joe: an option is to use that file directly as the documentation - with the bonus that you can use standard tools to produce further documentation; and also use the XSD to to check (validate) the XML; and to exchange with other parties who might need to understand your format. Because it's a standard, learning to use it becomes a valuable skill for you in other tasks/employers - and similarly, it's a common skill in the employment pool, so replacements can be found. Unfortunately, it's an awful standard in that it's harder to read and write than either of your examples.

Commented Nov 18, 2009 at 5:59

@13ren: Yes, it is unfortunate that the structure of an XSD file is so hard to read. I would not feel comfortable passing it off as "documentation". It would be nice if there was a tool that could open an XSD file in a user friendly view. (As apposed to a tool that generates a readonly file for viewing). Or even a tool that generates a Word document version of the documentation would be nice.

Commented Nov 18, 2009 at 22:21

@joe: It may or may not fit your notion of user friendliness, but one tool that allows an XSD schema document to display in a Web browser is the xsd.xsl stylesheet on the W3C web site. It does not hide the XSD syntax or translate it into more legible forms, but it does display XHTML-encoded documentation elements nicely and it turns references to other components defined in the same schema document into hyperlinks (in any non-Mozilla browser).