More Schematron Features - Diagnostics
(Page 5 of 5 )
Since assertions in Schematron are made using plain language, if a document doesn't validate, it's often easy to figure out what's wrong and to fix it. However, sometimes, the assertion itself doesn't provide enough information. The user may need to know more information about the problem in order to fix it. This kind of information should not be placed in an assertion. Rather, it should be placed in a separate diagnostics section.
The diagnostics section contains diagnostic elements that give more information about a problem, such as what was expected and how to go about fixing the problem. Each diagnostic must be given a unique identifier using the id attribute. Assertions can then point to the relevant diagnostic element, and if there's a problem, then the contents of that diagnostic will be made available to the user.
Diagnostics are placed in a diagnostics element, which must be a child of the schema element:
<diagnostics>
...
</diagnostics>
As mentioned, a diagnostic element must have a unique identifier set using the id attribute. Within the element is the diagnostic message. Let's go back to our earlier scenario of checking the domain name of an e-mail address. We can create a diagnostic for the length assertion. Recall that a domain name can only be 253 characters long. We can convey this information in the diagnostic:
<diagnostic id="domain_length">
A full domain name can only be 253 characters long.
The supplied domain name exceeded this amount.
</diagnostic>
Next, the relevant report needs to point to the diagnostic using the diagnostics attribute:
<report test="string-length($domain)>253" diagnostics="domain_length">The domain is too long.</report>
Now, if the domain part of an e-mail address is too long, then the diagnostic information is available to help the user out, in addition to the report itself.
It's still possible to give even more information, though. In addition to telling the user what value was expected (a domain name of 253 characters or less), it's possible to tell the user what value was given. In this situation, we could tell the user the length of the supplied domain name. This is possible using the value-of element, which substitutes the result of an expression contained in its select attribute. Below, we modify the diagnostic to tell the user exactly how long the supplied domain is:
<diagnostic id="domain_length">
A full domain name can only be 253 characters long.
The supplied domain name was <value-of select="string-length($domain)"/> characters long.
</diagnostic>
This will provide the user with even more help in solving any problems, yet it didn't require much work on our part. This same observation—that a lot was done with a little bit of work—applies to all of the concepts covered in this article and to Schematron in general. Schematron offers a remarkable amount of power and flexibility without introducing complicated concepts or methods. Everything is rather straightforward and elegant, just as it should be.
| DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware. |
