Have Geek Brain

Less cumbersome way to document XSD?

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

So, you take something simple and easy to read:

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

And in the end 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 have already provided this snippet as a simple fixed length file and as a CSV. One client requested XML and we now have a second client wanting to use XML. I was asked to provide documentation. The first client we originally developed an XML version for just wanted an XSD. So I'm hoping to just send a second client to one document - an XSD with simple annotations describing the elements.

+1


a source to share


5 answers


No no. <xs:annotation><xs:documentation>

is all there is.



+1


a source


Did you know that you can easily convert your XSD - even with cumbersome annotations and documentation tags - into a fairly readable HTML documentation file?

The magic is called xs3p and it's a pretty essential XSLT file for transforming your XSD (which is just another XML) into well-structured, very useful HTML documentation.

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



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

Mark

+3


a source


XSD provides the tags that you specify for documentation. I agree with you, they are cumbersome and make your files even bigger.

Fortunately, this is what we have.

0


a source


Yes, this is cumbersome, but unfortunately this is the only mechanism for documentation. However, an annotation tag is provided to suit many needs. Here you can place instructions for processing the computer, there you can place readable documentation.

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

In addition, the annotation doc tag can contain arbitrary length text. It can include HTML tags and virtually arbitrary XML. This is why it is not an attribute but an element.

0


a source


I have a suggestion - why don't you write the circuits the way you suggest, i.e.

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

and pass it through XSLT to convert it to full format

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

You are passing the transformed XSD to the clients, inside which you are using the compact version.

0


a source






More articles:


All Articles