Schematron Assertion Text


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?


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:

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


  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:

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:


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