Include xs:documentation in xs:assert examples

2 things...

1. I'm not sure if this has been proposed before (maybe by Rick 
[http://lists.xml.org/archives/xml-dev/200812/msg00146.html], but I couldn't 
find it in the bug database), but could we include xs:annotation elements in 
the xs:assert examples, e.g. do:

<xs:complexType name="intRange">
 <xs:attribute name="min" type="xs:int"/>
 <xs:attribute name="max" type="xs:int"/>
 <xs:assert test="@min le @max">
  <xs:annotation><xs:documentation>
   The value of the min attribute must be less
   than or equal to that of the max attribute.
  </xs:documentation></xs:annotation>
 </xs:assert>
</xs:complexType>

and:

<xs:complexType name="arrayType">
 <xs:sequence>
  <xs:element name="entry" minOccurs="0" maxOccurs="unbounded"/>
 </xs:sequence>
 <xs:attribute name="length" type="xs:int"/>
 <xs:assert test="@length eq fn:count(./entry)">
  <xs:annotation><xs:documentation>
   The value of the length attribute must be the same as the number
   of occurrences of entry sub-elements.
  </xs:documentation></xs:annotation>
 </xs:assert>
</xs:complexType>

I think this would be a good opportunity to show what looks like a good best 
practice for defining xs:asserts.

2. What's the prospect of having an <xs:doc> element defined which is a 
short from of <xs:annotation><xs:documentation>?!  Documentation tends to 
get short changed at the best of times, but when there's so much typing to 
even start a comment it's going to be pushed out even further.  I know tools 
help with this, but even then I find you end up worrying more about how to 
format the <xs:annotation><xs:documentation> part rather than the comment 
itself!  This would allow you to do:

<xs:complexType name="intRange">
 <xs:attribute name="min" type="xs:int"/>
 <xs:attribute name="max" type="xs:int"/>
 <xs:assert test="@min le @max">
  <xs:doc>
   The value of the min attribute must be less
   than or equal to that of the max attribute.
  </xs:doc>
 </xs:assert>
</xs:complexType>

(Although, based on the above e-mail, Rick would probably prefer something 
like:

<xs:complexType name="intRange">
 <xs:attribute name="min" type="xs:int"/>
 <xs:attribute name="max" type="xs:int"/>
 <xs:assert test="@min le @max">
  <xs:doc>
   Check the min and max attributes are appropriate.
  </xs:doc>
  <xs:error>
   The value of the min attribute must be less
   than or equal to that of the max attribute.
  </xs:error>
 </xs:assert>
</xs:complexType>
)

I haven't submitted this formally as I'm under the impression that XSD 1.1 
is now closed for input.

Thanks,

Pete Cordell
Codalogic Ltd
Interface XML to C++ the easy way using XML C++
data binding to convert XSD schemas to C++ classes.
Visit http://codalogic.com/lmx/ for more info

Received on Thursday, 14 May 2009 10:55:35 UTC