[Summary] Schematron Question: proper way to express the text version of

["Costello, Roger L." <costello@mitre.org>]

Hi Folks,

Many thanks for your excellent comments!  Below I have summarized the
discussions.  Please let me know if I missed anything.  /Roger

ISSUE

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

<sch:assertion text="XPath">
      Assertion Text
</sch:assertion>

What is best practice for phrasing Assertion Text?

EXAMPLE

Consider this simple XML document:

<meeting>
      <startTime>0900</startTime>
      <endTime>1000</endTime>
</meeting>

To keep the example simple I will assume: 
    - the meeting does not span multiple days
    - the times are specified as an integer (0000 - 2359)

With Schematron I can express this (co-)constraint between the two time
values: 

       "The meeting's startTime must be before its endTime"

This is expressed using a Schematron rule:

<sch:rule context="meeting">

     <sch:assert test="startTime &lt; endTime">
             Assertion Text
     </sch:assert>

</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 I can provide a textual description of
the assertion (which I indicate above as " Assertion Text ").  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 in the
above example:

(a) The meeting's start time is before its end time.

(b) The meeting's start time should be before its end time.

(c) The meeting's start time shall be before its end time.

(d) 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.  Alternatives (c) or (d) may be
appropriate:

(c) The meeting's start time shall be before its end time.

(d) The meeting's start time must be before its end time.

USER-FRIENDLY ASSERTIONS

Users react strongly to message that they think are strident and which
seem to blame the user.  So, shifting "must" or "shall" to "should" may
be appropriate:

(b) 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

DEVELOPER ASSERTIONS

In the case where the Assertion Text is to be seen and used only by
developers, alternative (a) may be appropriate:

(a) The meeting's start time is before its end time.

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

- the assertion is intended to be used as information for developers.

ACKNOWLEDGEMENTS

Many thanks to the following people for their excellent contributions
to this document:

- Peter Hunsberger
- Rick Jelliffe
- Michael Kay
- Pete Kirkham
- Frank Manola
- Dave Pawson
- Bryan Rasmussen