Good Web service design starts with a schema. Binding, port type and all these other parameters of a WSDL file usually are not interesting at all – 99.9% of all services have trivial SOAP bindings, no headers and no declared faults. Also, majority of Web services today are document-style with one “part” per message. So schemas of input and output messages are really the key to understanding what service is about. In other words, schema truly defines the contract of a service.
There is no substitution for the schema – you can’t generate a good schema from a source code or a UML class diagram since they do not convey optionality, restrictions, patterns, element model (sequence or choice) and other aspect. XML Schema is verbose and complex (and that’s a topic for another post), but it is pretty expressive as far the data typing goes.
So I usually start a service design with a well-documented schema. The question is, however, how to then publish it so other people can review it (you know, people who represent service consuming applications – these folks are kind of important). Reviewing a schema in a “raw” format is out of question, especially if business people are involved. So a nicely formatted HTML documentation which could present the schema in a readable format (ideally, translating schema lingo into plain English, such as “minOccur=0 ” could translate into “optional”) is the way to go.
I suspect that SOA registries, such as Infravio, can take care of this problem. But oftentimes there is a need to prototype a solution quickly before SOA infrastructure is put into place. Also, at this day and age, open source/free/inexpensive tools might be a requirement for many projects.
The best known Schema documentation generator is xnsdoc. It is not free, but 49 EUR seems like a reasonable price. xnsdoc has an open source XSLT-based counterpart with fewer capabilities. xnsdoc does produce nice documentation along the lines of JavaDoc format (although I’m not convinced that this is the best choice – remember, the documentation has to be suitable for non-developers), however, in my view it does not do much in terms of explaining the schema in plain English. In other words, the assumption is that users are familiar with Schema concepts. I also found that the support for groups and multi-files schemas had some problems (but keep in mind that I’d done my testing almost a year back, so please check the latest version)
A better tool that I found is Bluetetra XSDDoc (99 USD). In my view, it provides more user-friendly schema documentations. You can see some examples here. Unfortunately, it is not clear if XSDDoc is still actively supported – its website provides only minimal information and the product has not been updated in a while.
I still think that there is a need for more interactive Wiki-style schema publishing tool that would allow users reviews schemas expressed in layman terms and comment on elements and types.
