This is an archived snapshot of W3C's public bugzilla bug tracker, decommissioned in April 2019. Please see the home page for more details.
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.
I've got slightly mixed feelings about this. This might encourage an expectation that the content of the documentation is suitable text for use in an error message. If everyone shares that expectation, that's probably good. But some people might not share the expectation, and write <xs:documentation> TODO: This catches some illegal inputs, but leaves a security hole if the user specifies "-17". </xs:documentation> It might be better also to add a Note: "Schema authors are encouraged to write the content of the documentation element within an assertion in a form suitable for use in an error message directed at authors of instance documents that fail to satisfy the assertion." But then we beg questions about localisation. On balance, yes, let's do it. If we just put it in an example with no recommendations, we can leave the community to develop conventions.
Can't we just think of adding an xs:message child to xs:annotation that could be used for such purpose (this goes without saying that we should document the maximum the schema)
I agree there are a number of potential audiences for such documentation, and it's hard to decide which audience should have priority. Like Innovimax I think the ideal case would be to have something like an xs:errorMessage element, e.g.: <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:errorMessage> The value of the min attribute must be less than or equal to that of the max attribute. </xs:errorMessage> </xs:assert> </xs:complexType> As you can see I'm not sure whether this should be a child of xs:annotation or just xs:assert, because I'm not sure it makes sense in all cases where xs:annotation is used (haven't checked). I imagine this sort of thing would have been easy to add 6 months ago, but maybe we're past that point. So Michael's suggestion not to include any particular recommendations with regard to this and leave the community to develop conventions would seem to be the best we can do at this stage.
Based on WG discussion and on Pete Cordell's comment, the WG believes that it's best to encourage community development, and that the WG might want to create a note to cover this issue if it still seems relevant in the future. So the WG is closing this bug.
The WG reported this bug as WONTFIX on 2009-07-17. We are closing this bug as requiring no futher work. If there are issues remaining, you can reopen this bug and enter a comment to indicate the problem. Thanks very much for the feedback.