Getting Started with XSpec and Schematron - xspec/xspec GitHub Wiki

This page demonstrates how to get started with XSpec and Schematron. It runs through a tutorial that tests Schematron rules with XSpec. The examples are in the tutorial directory.

Make sure that XSpec is installed correctly by running the help message at the end of the installation process:

• Installation on Mac/Linux
• Installation on Windows

The tutorial directory contains these files:

• demo-01.sch
  A sample Schematron schema.
• demo-01.xml
  An XML file to apply the Schematron to.
• demo-01.xspec
  An XSpec test to test the Schematron.

Navigate to your XSpec directory (e.g. ~/xspec/for Mac/Linux or C:\xspec\ for Windows) and run the XSpec test suite with this command:

For Mac/Linux:

bin/xspec.sh -s tutorial/schematron/demo-01.xspec

For Windows:

bin\xspec.bat -s tutorial\schematron\demo-01.xspec

The output in the command line should be similar to this:

Creating XSpec Directory at tutorial/schematron/xspec...


Converting Schematron into XSLT...

Converting Schematron XSpec into XSLT XSpec...

Creating Test Stylesheet...


Running Tests...
Testing with SAXON HE 12.4
demo-01
..article should have a title
not assert a001
..section should have a title
not assert a002 /article[1]/section[1]
assert a002 /article[1]/section[2]

Formatting Report...
passed: 3 / pending: 0 / failed: 0 / total: 3
Report available at tutorial/schematron/xspec/demo-01-result.html
Done.

Open the HTML report at tutorial/schematron/xspec/demo-01-result.html with your favourite web browser to see the test results. The HTML report should look like this:

Note that you invoke the XSpec script against the test (*.xspec file), not the Schematron rule (*.sch file). The Schematron filename to test is specified at the beginning of the XSpec test on the @schematron attribute:

<x:description xmlns:x="http://www.jenitennison.com/xslt/xspec" schematron="demo-01.sch">

If everything worked, there should be a new xspec subdirectory in ~/xspec/tutorial/schematron (or C:\xspec\tutorial\schematron). It contains several files generated by XSpec:

• demo-01-compiled.xsl
  The test runner compiled from demo-01-sch-preprocessed.xspec by the XSpec implementation.
• demo-01-result.xml
  The test results in XML format generated by demo-01-compiled.xsl.
• demo-01-result.html
  The human-readable HTML test report generated from demo-01-result.xml.
  Most of the time, this is the only file that you'll care about.
• demo-01-sch-preprocessed.xsl
  XSLT generated from demo-01.sch by the Schematron implementation (by default, the skeleton implementation through XSpec v2.3.2 and the SchXslt implementation starting in XSpec v3.0).
• demo-01-sch-preprocessed.xspec
  The XSpec test converted from demo-01.xspec.

Open the source files in your favourite XML editor to understand how to write an XSpec test for Schematron rules.

• demo-01.xml
• demo-01.sch
• demo-01.xspec

This XML file contains the following:

<?xml version="1.0" encoding="UTF-8"?>
<article>
  <title>Example</title>
  <section>
    <title>Introduction</title>
    <p>This is an example.</p>
  </section>
  <section>
    <p>This is an example.</p>
  </section>
</article>

This Schematron rule file checks two things:

• The article element has a nested title element.
• The section element has a nested title element.

Each rule is identified with an @id attribute.

<?xml version="1.0" encoding="UTF-8"?>
<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2">

    <sch:pattern>
        <sch:rule context="article">
            <sch:assert test="title" id="a001">
                article should have a title
            </sch:assert>
        </sch:rule>
        <sch:rule context="section">
            <sch:assert test="title" id="a002">
                section should have a title
            </sch:assert>
        </sch:rule>
    </sch:pattern>

</sch:schema>

This XSpec test file is associated with the Schematron file using the @schematron attribute of x:description.

The context of the XSpec test is associated with the XML file using the @href attribute of x:context.

<?xml version="1.0" encoding="UTF-8"?>
<x:description xmlns:x="http://www.jenitennison.com/xslt/xspec" schematron="demo-01.sch">
    <x:scenario label="demo-01">
        <x:context href="demo-01.xml"/>
        <x:scenario label="article should have a title">
            <x:expect-not-assert id="a001"/>
        </x:scenario>
        <x:scenario label="section should have a title">
            <x:expect-not-assert id="a002" location="/article[1]/section[1]"/>
            <x:expect-assert id="a002" location="/article[1]/section[2]"/>
        </x:scenario>
    </x:scenario>
</x:description>

This XSpec file contains one top-level scenario with two nested scenarios testing the two Schematron rules. Each scenario contains one or more expectations which specify the expected results when the context XML is validated by the Schematron rule. Note that:

• x:expect-assert verifies that an assert is thrown. (sch:assert is evaluated as failure.)
• x:expect-not-assert verifies that an assert is not thrown. (sch:assert is not evaluated as failure.)

The scenario labelled as article should have a title contains an x:expect-not-assert.

The x:expect-not-assert in this scenario makes sure that an assert with @id="a001" is not thrown (sch:assert[@id="a001"] is not evaluated as failure) when the Schematron rule is applied to demo-01.xml.

The scenario labelled as section should have a title contains one x:expect-not-assert and one x:expect-assert.

The x:expect-not-assert in this scenario makes sure that an assert with @id="a002" is not thrown (sch:assert[@id="a002"] is not evaluated as failure) at the node located with the XPath expression /article[1]/section[1] in demo-01.xml.

The x:expect-assert in this scenario works in the opposite way and makes sure that an assert with @id="a002" is thrown (sch:assert[@id="a002"] is evaluated as failure) at the node located with the XPath expression /article[1]/section[2] in demo-01.xml.

The tutorial directory contains more examples. They can be run in the same way as demo-01.xspec.

For Mac/Linux:

bin/xspec.bat -s tutorial/schematron/demo-02-PhaseA.xspec
bin/xspec.bat -s tutorial/schematron/demo-02-PhaseB.xspec
bin/xspec.bat -s tutorial/schematron/demo-03.xspec
bin/xspec.bat -s tutorial/schematron/demo-04.xspec

For Windows:

bin\xspec.bat -s tutorial\schematron\demo-02-PhaseA.xspec
bin\xspec.bat -s tutorial\schematron\demo-02-PhaseB.xspec
bin\xspec.bat -s tutorial\schematron\demo-03.xspec
bin\xspec.bat -s tutorial\schematron\demo-04.xspec

Test results will be written to tutorial/schematron/xspec/ (or tutorial\schematron\xspec\ for Windows) as these files:

• demo-02-PhaseA-result.html
• demo-02-PhaseB-result.html
• demo-03-result.html
• demo-04-result.html

Check out Writing Scenarios for Schematron for more details about Schematron support in XSpec.

XSpec for Schematron was first implemented by Vincent Lizzi.

He gave a presentation on Schematron support in XSpec in an open session at JATS-Con 2017. Watch his presentation.