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.

I would like to send the XSD scheme around and ask the people involved to peer review the data model.

What tool or presentation method would you suggest to be used as a basis for peer reviews? The data model should be readable for non-skilled people, at least when it comes to the semantic meanings of the parameters

Edit:

To be more specific: Of course, syntactically, the scheme validates. Actually I'm already working on code which is based on JAXB generated classes. My goal is

1. to freeze the data model and thus the input parameters
2. to make sure nothing got lost or forgotten from a semantic (in the meaning of business-relevant) point of view.

Edit 2

I've been thinking about how it probably would be best to spread a datamodel around. I'm thinking of something like a JavaDoc for XSD schemas. Anyone knows if something like that exists? Basically it would be done with a set of XSLTs, right?

Answer 1

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.

Answer 2

** 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 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

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 5

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.