Generate XML Schema documentation the easy way with XS3P

I have to work with the CDA XML schema on a regular basis and sometimes it is easier to check things either via a tool that can visualise the schema or through hyperlinked documentation that describes the schema in a concise way. Unfortunately, as I found out, most tools can't handle a complex schema that has multiple cyclic references within it. So what's the solution? Use a tool that doesn't analyse the XSD! This is where xs3p comes in.

Quoting from the xs3p web site...

xs3p is a schema documentation generator. Basically, it is an XSLT stylesheet that will generate an XHTML document from an XSD schema. Some of its cool features are:
* It provides links that allow the user to jump to the documentation of schema components that are referenced.
* It provides a view of schema components' constraints as a sample XML instance.
* For global type definitions, it shows the super- and sub- types of the type definition.
* For global element declarations, it shows the substitution groups that the element declaration heads or belongs to.
* It can sort schema components by type and name.
* It has a glossary section which explains some XML Schema terminology.

Their wiki is also quite useful though I could not get the link generator XSLT to work.

The output looks quite nice too...

The generated documentation is fully hyperlinked and easy to navigate. This definitely makes a XSD much easier to comprehend.

So to do this, I had to generate a links.xml file that described which XSDs map to which HTML output files. This is really straight forward, just put in the XSD file name along with its HTML file which you generate later. For example...

links.xml

<?xml version="1.0"?>

...

</links>

I had an entry for every XSD file in my whole schema.

Now all I had to do was to run xsltproc to generate my output. This is done for every XSD file and looks something like this (though I created a shell script to do it for me)...

xsltproc command

xsltproc --stringparam title "My Schema Name" \

--stringparam searchIncludedSchemas true \

--stringparam searchImportedSchemas true \

--stringparam linksFile links.xml \

xs3p.xsl CDA-AU-V1_0.xsd > CDA-AU-V1_0.xsd.html

Note the naming of the output file, it's simply the XSD file name with .html at the end of it and that's exactly what the links.xml file contains as well.

Do this for all the XSD files in your schema and your documentation will be complete.

-i