Reputation: 5814

Less Cumbersome Way To Document XSDs?

We recently started providing a data extract to clients via an XML. We have a schema (XSD) that defines the structure of this XML. I would like to include the documentation of the elements and attributes in the schema itself. The only thing I am finding is the very cumbersome "annotation" and "documentation" tags.

So you take something as simple and easy to read as this:

<xs:element name="TransactionType" type="xs:string"  />

And end up with this ugly mess:

<xs:element name="TransactionType" type="xs:string">
    <xs:annotation>
        <xs:documentation>
            Type of transaction
        </xs:documentation>
    </xs:annotation>
</xs:element>

Is there anything better? Say something like this:

<xs:element name="TransactionType" type="xs:string" description="Type of transaction"  />

PS: We already provided this extract as a simple fixed length file and as a CSV. One client requested an XML and we now have a second client wanting to use the XML. I got asked for documentation. The first client for whom we originally developed the XML version just wanted an XSD. Hence my hope to just send the second client one document -- the XSD with simple annotations describing the elements.

Upvotes: 1

Answers (5)

Eddie

Reputation: 54421

Yes, this is cumbersome, but unfortunately it is the only mechanism for documentation. However, the annotation tag is provided to meet many needs. You can put computer processing instructions in there, you can put human-readable documentation in there.

XSD is designed more, I think, to convey information effectively to a computer program. For example, if you are running a code generator from a schema, the code generator can include the annotation element information in code self-documentation, such as JavaDoc or equivalents for other languages.

Also, the annotation documentation tag can include text of an arbitrary length. It can include HTML tags and in fact arbitrary XML. This is why it is not an attribute, but an element.

Upvotes: 0

JonoW

Reputation: 14229

I have a suggestion - why don't you write the schemas in the way you propose, i.e.

<xs:element name="TransactionType" type="xs:string" description="Type of transaction" />

and pass it through an XSLT to transform that into the full format of

<xs:element name="TransactionType" type="xs:string"> 
 <xs:annotation> 
  <xs:documentation> Type of transaction </xs:documentation> 
 </xs:annotation> 
</xs:element>

You give out the transformed XSD to customers, internally you use the compact version.

Upvotes: 0

marc_s

Reputation: 754200

Are you aware that you can easily transform your XSD - even with the cumbersome annotation and documentation tags - into a fairly nicely readable HTML documentation file?

The magic is called xs3p and it's a fairly substantial XSLT file to convert your XSD (which is just another XML after all) into nicely structured, very useful documentation HTML.

It's free, it works - just great! :-)

Of course - you still have to add the annotation/documentation to your XSD, but it might be a better solution than having a XSD and a separate documentation file (which most likely will be out of sync sooner or later......)

Marc

Upvotes: 3