User-Friendly Diagnostics

Click arrow key () to navigate to next page

Error Messages for Non-Experts

The <diagnostic> element enables the schema designer to compose error messages that are user-friendly.
Oftentimes the results of a validation are delivered to users who are not XML experts, or technology whizzes. Rather, they are domain experts. Thus, the <diagnostic> element allows you to give users error messages expressed in their own lingo, i.e., domain-specific diagnostics.
This is a very important and unique feature of Schematron.

A Schematron schema is comprised of one or more <pattern> elements followed by an optional <diagnostics> element.
The <diagnostics> element is comprised of one or more <diagnostic> elements.

A <sch:diagnostic> element is comprised of mixed content: text and <sch:value-of> elements. Here's an example:

<sch:diagnostic id="invalid-security-label">
Your document does not meet the Security Classification Policy. Your Para has a security
label of <sch:value-of select="./@classification"/>, which has a higher sensitivity than the document's
sensitivity: <sch:value-of select="/Document/@classification"/>
</sch:diagnostic>

Read as: this diagnostic has an identifier (invalid-security-label). When invoked, this diagnostic is to output some text along with the value of the classification attribute of the current - context - node (Para), and the value of the classification attribute of the <Document> element.

A <sch:value-of> element has the same functionality as the XSLT <xsl:value-of> element. It has a select attribute that you use to identify a node in the document. The Schematron tool will output the value of the node that is identified.
For example, the below <sch:value-of> element says to output the value of the classification attribute on the current node:

You connect an assertion to a diagnostic.
The <assert> element has an optional diagnostics attribute. The value of the diagnostics attribute is the value of a <diagnostic> element's id attribute.
Example: this assertion is connected to the diagnostic (shown two slides back):

<sch:assert test="/Document/@classification='top-secret'" diagnostics="invalid-security-label">
If there is a Para labeled "top-secret" then the Document
should be labeled top-secret
</sch:assert>

During validation, if the assertion fails, then the diagnostic identified as "invalid-security-label" will be executed.

To enable Oxygen XML to generate diagnostic messages you need to download this file: http://www.oxygenxml.com/update/schPatchDiagnostics.jar
Then, place the jar file into this folder: [oxygen]/lib/endorsed, where [oxygen] is the folder that where you installed Oxygen. Note that the endorsed folder does not exist by default so you need to create it first.
The diagnostic message will appear when you hover your mouse over the message at the bottom of the Oxygen screen.

View check-classifications.sch (example04 folder).
Use Oxygen XML and Topologi to validate valid-document.xml and invalid-document.xml (both in the example04 folder).

Currently Flight.sch (lab04 folder) does not have any diagnostics.
Revise it so that there is a nice user-friendly diagnostic connected with each assertion (create two <diagnostic> elements, one for each assertion).
Validate valid-document.xml (lab04 folder) against your Schematron schema.
Validate invalid-document.xml (lab04 folder) against your Schematron schema.
Use both Oxygen XML and Topologi to do the validation.