[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] [Summary] Schematron Question: proper way to express the text version of
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 < 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] |
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|