Schematron Assertion Text

Issue

A Schematron assertion contains an XPath expression and a natural language statement of the assertion:

1. <sch:assert text="XPath">
2. Assertion Text
3. </sch:assert>

What is best practice for phrasing Assertion Text?

Example

Consider this XML document:

1. <?xml version="1.0"?>
2. <meeting>
3. <startTime>0900</startTime>
4. <endTime>1000</endTime>
5. </meeting>

To keep the example simple we will assume:

• the meeting does not span multiple days
• the times are specified as an integer (0000 - 2359)

With Schematron the co-constraint between the two time values can be expressed:

1. The meeting's startTime must be before its endTime

This is expressed using a Schematron rule:

1. <sch:rule context="meeting">
3. <sch:assert test="startTime &lt; endTime">
4. Assertion Text
5. </sch:assert>
7. </sch: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?

Use Domain Terminology

Specify the Assertion Text using terminology of the problem domain, rather than markup (XML, XPath) terminology.

Advantages:

1. The Assertion Text can be written and maintained by domain experts, who don't know XML or XPath.
2. The Assertion Text may be displayed in a GUI. The Assertion Text can be understood by users (who cannot see the element names).
3. It enables maximum repurposing.

"Should" or "Must" or "Is" or "Shall"

Here are some alternative ways of phrasing the Assertion Text:

• The meeting's start time is before its end time.
• The meeting's start time should be before its end time.
• The meeting's start time shall be before its end time.
• The meeting's start time must be before its end time.

Which alternative should be used? The answer varies, depending on your users and the purpose of the assertion. Below are some considerations.

Contractual Assertions

When assertions are used contractually, then precision and definiteness are the overriding consideration. One of these may be best suited:

1. The meeting's start time shall be before its end time.
2. The meeting's start time must be before its end time.

User-Friendly Assertions

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:

1. The meeting's start time should be before its end time.

An important consideration in phrasing Assertion Text is to decide whether:

• you are addressing people who know what the rules are, and just needed to be told they've slipped up, or
• you are addressing people who don't know the rules and need to be told what they are

Summary

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 assertion is intended to be used as a statement of a contractual obligation, or
• the assertion is intended to be used as a friendly message to guide users, or

Acknowledgements

The following people contributed to the creation of this document:

• Roger Costello
• Peter Hunsberger
• Lars Huttar
• Rick Jelliffe
• Michael Kay
• Frank Manola
• Dave Pawson
• Bryan Rasmussen

Last Updated: June 27, 2007