Igor Kromin |   Consultant. Coder. Blogger. Tinkerer. Gamer.

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...
<?xml version="1.0"?>
<links xmlns="http://titanium.dstc.edu.au/xml/xs3p">
<schema file-location="CDA-AU-V1_0.xsd" docfile-location="CDA-AU-V1_0.xsd.html"/>

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.


Hope you found this post useful...

...so please read on! I love writing articles that provide beneficial information, tips and examples to my readers. All information on my blog is provided free of charge and I encourage you to share it as you wish. There is a small favour I ask in return however - engage in comments below, provide feedback, and if you see mistakes let me know.

If you want to show additional support and help me pay for web hosting and domain name registration, donations, no matter how small, are always welcome!

Use of any information contained in this blog post/article is subject to this disclaimer.
comments powered by Disqus
Other posts you may like...