Schematron

Schematron provides XML content authors with a convenient way to check the quality of their XML data, to ensure that in addition to being syntactically correct, the file meets guidelines for use established in a project. It is often used in conjunction with DTD/Schema validation.

Schematron contains 6 basic elements:

contains optional <title>
zero or more <ns prefix="[]" uri="[]" /> declaring the namespaces and prefixes used for the XPaths
One or more <pattern> elements, which contain logical groupings of associated rules
One or more <rule> elements in which the context attribute identifies via an XPath expression, the node within a tree to apply tests.
One or more <assert> elements in which the test attribute is an XPath expression, and which contains rich text expressing the statement being asserted in plain language
One or more <report> elements in which the test attribute is an XPath expression, and which contains rich text expressing the fact to be reported in plain language.

The Schematron Workflow

Getting Started: Install the Schematron plugin
The plugin requires Oxygen version 7.1 or higher (NOTE: There are reports of this plugin not working on some platforms running Oxygen 8.1). Oxygen can be downloaded from: http://www.oxygenxml.com.

Close Oxygen
Download the file: Validator-jdk14.zip
Unzip the file. This will create a folder called Validator somewhere on your computer. Copy the entire folder into the plugins directory of your Oxygen Installation.

Using the Schematron plugin to validate your document
If you are creating a new Schematron validator, you will need to make sure a repository has been created on Algernon, and follow the steps below to create a validator file before you can use the plugin.

Open an instance of the document to be validated (e.g. an issue of the Indiana Magazine of History).
Right click (or ctrl-click) anywhere within the main window and select 'Plugins' and 'XTF Validator'.
In the 'Choose Repository' window, select the appropriate option and hit 'OK'.
Save the resulting report as an .html file and open it to see any errors in the source document.
Make any changes to the source document, save and repeat.

Creating a new validator

Encode markup usage guidelines in a Schematron file (.sch). This file should contain a combination of patterns, rules assertions and reports that examine and validate the use of tags in instance files. (Note: We have had some problems with reports, so use assertions whenever possible.)

For example, to test that all abbr tags in a TEI file include an expan attribute, a Schematron file might include the following:

<sch:pattern  id="editorial">
<sch:title>Transcription Checks</sch:title>
  <sch:rule context="/TEI.2/text/body//abbr">
     <sch:assert icon="#dLevel-Warning" test="@expan">Abbr elements should have an @expan attribute.</sch:assert>
  </sch:rule>
</sch:pattern>

See the Schematron web site for more instructions on creating Schematron documents. Also see the sample documents attached, including IMH_issue_schematron.sch and INAuthorsEncyclopediaSchematron.sch.

Configure Transformation Scenario
Before you use your first validator, you will need to download schematron-report-xml.xsl and configure a transformation scenario. Once this is done, you can use the same scenario for all of your Schematron instances.

From the Document menu, choose 'Transformation', and 'Configure Transformation Scenario'.
In the window that appears, click the 'New' button.
In the 'Edit Scenario' window, give the scenario a name that you will remember (e.g. Create Schematron XSLT) and use the folder icon next to the XSL URL field to locate the schematron-report-xml.xsl file on your computer. Make sure the 'Transformer' setting is Saxon 8B.
Select 'Output' on the top menu and make sure that 'Save As' is selected.
Use the folder icon next to the 'Save As' field to instruct the processor to save the resulting XSLT in your working folder as "schematron.xsl". (Each time you repeat the transformation, you will overwrite the previous schematron.xsl.)
Hit 'OK' in both windows to exit Configure Transformation Scenario.
Download skeleton1-5.xsl and save it to the same directory as schematron-report-xml.xsl.

Transform your Schematron document into an XSLT validator
You will need to do this each time you make changes to your Schematron file.

Open your Schematron document
From the Document menu, choose 'Transformation', and 'Configure Transformation Scenario'. Make sure the appropriate scenario is selected and hit 'OK'.
Again from the Document menu, choose 'Transformation' and 'Apply Transformation Scenario'. If you are repeating this step, Oxygen will ask you if you want to overwrite the existing schematron.xsl file. You do.
Connect to algernon.dlib.indiana.edu and navigate to /opt/xubmit/repositories and then to the appropriate repository and the schematron file within it.
Upload the validator.xsl file
Once this is done, you are ready to use the Schematron plugin (see above) to validate your document or test your Schematron assertions. (Hint: Test your assertions one at a time by 'breaking' something in the source file that the assertion should catch and using the plugin to validate.)

Schematron Hints

You can only match an element once in a pattern. For example, if I write one rule where context="div" and one where context="div(@type='filingLetter'), they need to go in separate patterns or the second one will be ignored.
If you are telling it to look for an attribute and it doesn't notice when that attribute isn't present, check the DTD to make sure there isn't a default value for the attribute.

Schematron and the DLP

The DLP is using Schematron in a number of ways, but primarily through Xubmit, our XML documents ingest, validation and versioning tool.

Projects using Schematron include:

EAD Working Group (see documentation)
Chymistry of Isaac Newton (see documentation)
Aquifer Project (see documentation)
Indiana Magazine of History (see documentation)
Indiana Authors (see documentation)

CVS

Schematron is associated with more than one CVS project on urania. The main CVS directory housing schematron files:

/cvsdata/schematron
             /iso
             /prototype

The prototype directory contains files associated with early schematron development and the first rollout of Xubmit; the iso directory contains an altered version of the 1.5 reference implementation that conforms both to XSLT 2.0 and should handle schematron files written to the ISO spec.

The XML to HTML report (schematron-xml2html-report.xsl) is also located with the src directory of the Xubmit CVS tree:

/cvsdata/xubmit

To aid future developers, the Newton project currently uses the ISO version file and the XSLT 2.0 transformations which are housed in /newton/tools/xubmit/schematron