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

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 2

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 3

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.