Subject:Enquiry about XSD documentation features Author:Naveen Malhotra Date:14 Jun 2011 01:00 AM
Greetings! We have a few queries with respect to the documentation features of your company’s product Stylus Studio. We have tried the evaluation version of Stylus Studio and we would consider using the licensed version of the software if it meets our expectations.
Here are our queries/expectations from the tool:
(1) We are trying to auto-generate documentation for our XML files using the corresponding XSD files (we are using the XSD files for the validation of our XML files). E.g. assume we have a “customer.xml” file and we have a schema file called “customer.xsd” file that is used for validation purpose of “customer.xml”. Now what we want is that we provide this “customer.xsd” file to the tool as the input, then the tool should be able to generate documentation about “customer.xml” file (and not about the .xsd file itself). Such documentation should include different fields (elements/attributes) in the xml, their data-types and restrictions in plain, simple English rather than technical XSD language (like maximum length limit, maximum precision for floating point, possible enumerated values etc) and, of course, the annotations (comments about the element).
In short, we want the generated documentation to be of XML style and we don’t want the XSD syntax look and feel in it (although we would provide XSD to the tool as the input). Our customers would want the documentation for the XML and the data-types for various fields in the XML & restrictions should be told to them in plain, simple English rather than technical XSD language (e.g. our customers don’t want to know what is a simple type or a complex type, or what is a facet or namespace, or if one XSD includes another XSD or inherits from another XSD etc). However, the problem we get with most of the documentation tools available online (apparently, including Stylus Studio) is that they generate a lot of XSD-style stuff which we don’t want to see. Is there a way to use or customize the tool to serve our purpose?
E.g. if we provide “customer.xsd” to the tool, then the generated document should only say that CUSTOMER has an element called NAME which is a string that can take upto 259 characters, plus annotations – that’s all we want! Instead, when I use most of the available tools (including Stylus Studio), they generate a document saying that the complex type “customer_type” has an element called “NAME” which is of simple type “fixed_length_260_string”, and further, “fixed_length_260_string” has a restriction base of “xs:string” and has a facet maxLength = 259 but we are not interested to read all of this as our goal is to document the corresponding XML file “customer.xml” in simple English easily understandable by the customer and not the XSD itself.
We have used annotations for all our types. E.g. the simple type “fixed_length_260_string” has an annotation “String (upto 259 characters)”, so in the documentation of the data-type of element NAME, if we can see this “String (upto 259 characters)” instead of “fixed_length_260_string”, that would also be good (probably a workaround) and should serve our purpose – though I am not sure if such a workaround could help in all cases.
(2) Another expectation from the tool is that if, in our new product release, we add/edit/delete a few elements in our “customer.xsd” file, then by providing the old & new “customer.xsd” files, we should be able to generate a document showing the differences in our XML file between the two releases (i.e. newly added fields, deleted fields and modified fields) – most likely in a tabular format and which can be saved (again, as explained above, in XML style, not XSD style syntax).
(3) We also want to generate sample XML files by providing the XSD file as an input. E.g. if we provide “customer.xsd” as input to the tool, it should be able to generate a few example files e.g. customer001.xml, customer002.xml, customer003.xml etc with the sample customer data contained in those files as per the syntax & restrictions defined in the XSD file provided to the tool.
I would appreciate your quick response. Thanks.