XML Spy, Schema Documentation, and Java

I've mentioned in the past that my preferred XML editor/IDE is oXygen (although I currently use XXE to write these blog posts in XHTML; it's also good for editing DocBook). However, my clients almost always use XML Spy (which I also have, for that reason). In particular, a lot of people prefer the Schema diagrams that XML Spy produces to those produced by other tools (although Liquid XML also produces attractive Schema diagrams).

Now, one thing I've done for a number of clients is to implement a Schema quality control framework for them. This is a batch-mode tool that does for XML what a build system (like 'make', 'Ant', 'NAnt', etc.) does for Java/C#/etc. You don't compile Schemas, but you can regression test them against examples, you can test that they conform with your design rules (e.g. to have a consistent style, which makes maintenance easier), you can produce dependency documentation, and generally provide reports that help both developers and managers understand what is happening within a large set of Schemas, and help them catch unintended consequences of changes in a new version of the Schemas, so their own clients don't end up impacted by those consequences.

One thing that you do within such a framework is generate Schema documentation. Since so many people like XML Spy documentation, that is what they ask for. The problem is that it hasn't always been easy to get the result you want with XML Spy. In particular, previous versions produced either one Word file or one HTML file for all of the Schemas connected to your main Schema (assuming you want the documentation fully hyperlinked). That one HTML file could easily have thousands of diagrams in it, and it wasn't uncommon to find that you had produced an HTML file that none of your client's PCs could load without the browser crashing. I'm very happy to find that XML Spy 2008 now allows you to generate separate HTML files with the appropriate hyperlinks between the files, which is an enormous improvement.

In terms of running it from the command line, XML Spy has for a long time had a COM interface for running XML Spy from an external program. I noticed that XML Spy 2008 now has a Java wrapper for that API, which seemed like a good way to integrate it with Apache Ant, so I gave that a try. The bad news is that while some of the functions work, it crashed with a memory violation error when I tried to create the dialog object needed to control the settings for Schema generation. Instead, I wrote a short command-line program in C# to call the COM API more directly, and then I used Ant's 'exec' task to run the .NET executable.

The result is that I had to add an extra technology into the mix (always something to avoid if you can), but it works, and I am now generating the documentation that my client wants from an Apache Ant build process. Who knows, if Altova gives that Java API wrapper some more testing, it might turn out to be usable in XML Spy 2009 or XML Spy 2010.