A Schematron assertion contains an XPath expression and a natural language statement of the assertion:
What is best practice for phrasing Assertion Text?
Consider this XML document:
To keep the example simple we will assume:
With Schematron the co-constraint between the two time values can be expressed:
This is expressed using a Schematron rule:
Read as: "In the context of the meeting element, I assert that the value of startTime must be less than the value of endTime"
Within the <sch:assert> element a textual description of the assertion (which is indicated above as "Assertion Text") can be provided. What is the best way of phrasing the text version of an assertion?
Specify the Assertion Text using terminology of the problem domain, rather than markup (XML, XPath) terminology.
Here are some alternative ways of phrasing the Assertion Text:
Which alternative should be used? The answer varies, depending on your users and the purpose of the assertion. Below are some considerations.
When assertions are used contractually, then precision and definiteness are the overriding consideration. One of these may be best suited:
Users react strongly to message they think are strident and which seem to blame the user. So, shifting "must" or "shall" to "should" may be appropriate:
An important consideration in phrasing Assertion Text is to decide whether:
Schematron is an assertion-based schema language. Assertions are expressed using XPath and natural language (i.e., the "Assertion Text"). How the Assertion Text is phrased is an important consideration. In general, it should be phrased using terminology appropriate to the domain. Beyond that, how it is phrased depends on whether:
The following people contributed to the creation of this document:
Last Updated: June 27, 2007