Formatting XSD scheme for peer review

Question

I designed a data model which is represented by an XSD scheme. The data model also provides the types that are being used as web service parameters in a WSDL descriptor.

Answer 1

I know the following tools that generate documentation from XML Schema files (XSD):

• xs3p
  • XSLT stylesheet that generates single XHTML from XSD
• xsddoc
  • free / LGPL
  • mainly XSLT based
  • JavaDoc like output
  • see xsddoc examples
• xnsdoc
  • improved commercial version of xsddoc
  • free for personal/educational use
  • JavaDoc like output
• XSDdoc 2.0
  • commercial
  • JavaDoc like output

For small a XML schema, I would probably suggest using the xs3p XSLT stylesheet. For more a complex schema, I suggest using xsddoc.

Answer 2

The very useful Oxygen XML developer also supports generating documentation, see http://www.oxygenxml.com/xml_schema_documentation.html (commercial, but there's a fully functional 30 day trial available)

I'll try it out now, need a simple way to generate a document with all types and available xsd:documentation description as a simple interface description...

Answer 3

I recommend using the XSD for something. Specifically, show some actual applications, with examples as real code.

Actual applications are what make a schema interesting. The examples don't have to be big, sophisticated or completely realistic. They just have to compile. Other people will want to copy and paste the code samples.

These examples are the "hello world" of the schema. And they act as a kind of unit test for the schema.

Answer 4

** Disclosure : I work for Innovasys, the producer of the documentation tool mentioned below *

You could take a look at Innovasys Document! X. As well as automatically generating a structured and linked page for every element, simple type, complex type, group and attribute group it will also generate linked XSD diagrams (including sequences/choice etc.) and structure tables that include the annotations from your XSDs and make sense of the relationships between the elements in your schemas. The output is template based so you can adapt it to your preferred style and structure. It will build output to web ready html or compiled help files.

Uniquely it also includes a WYSIWYG editor that allows you author additional content to supplement the stuff that's automatically generated and the annotations from the XSD source - so you can provide additional contextual information for your peer review. There is also a Community Extensions feature that allows people viewing the generated output to record comments and feedback and that can be viewed and actioned directly from within Document! X.

Answer 5

The closest thing to Javadoc for an XML schema that I've seen is running the Javadoc tool on source generated from the schema. This requires two things: 1) That your schema has internal annotation elements documenting it, and that 2) your source generator uses those annotations as Javadoc elements.