Schematron Rules Reference

You define Schematron rules in an SCH file.

Tip: Schematron supports XSLT2 and use operators, functions, and syntax from the XPath language. For detailed information, see XPath.

Schematron Schema Example

The example includes both Basic Schematron Elements and Schematron QuickFix Elements (bold).

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://purl.oclc.org/dsdl/schematron"
    xmlns:sqf="http://www.schematron-quickfix.com/validator/process" queryBinding="xslt2">
    
    <!-- A Step or Substep element should not contain more than one Choices, Substeps, Step Example, or Info element. -->
    <pattern id="STRUCTURE_05">
        <rule context="step|substep">
            <assert test="count(info) &lt; 2">A Step or Substep element should not contain more than one Info
                element.</assert>
            <assert test="count(stepxmp) &lt; 2">A Step or Substep should not contain more than one Step
                Example element.</assert>
            <assert test="count(choices) &lt; 2">A Step or Substep should not contain more than one Choices
                element.</assert>
            <assert test="count(substeps) &lt; 2">A Step should not contain more than one Substeps
                element.</assert>
        </rule>
    </pattern>

    <!-- ... -->

    <!-- Unordered List and Ordered List elements should contain at least two List Item elements -->
    <pattern id="STRUCTURE_11">
        <rule context="ul|ol">
            <assert test="count(li) &gt; 1" sqf:fix="addListItem">Unordered List and Ordered List
                elements should contain at least two List Item elements.</assert>
            <sqf:fix id="addListItem">
                <sqf:description>
                    <sqf:title>Add a List Item element</sqf:title>
                    <sqf:p>To fix this issue, you can add another List Item element. If you cannot
                        come up with another List Item element, convert the list element to a Paragraph
                        element.</sqf:p>
                </sqf:description>
                <sqf:add node-type="element" target="li" position="last-child"/>
            </sqf:fix>
        </rule>
    </pattern>

</schema>

Schematron Schema Structure

The following structure includes both Basic Schematron Elements and Schematron QuickFix Elements (bold).

<schema> (single)

  • <pattern> (any number)
    • <rule> (any number)
      • <report> (any number)
      • <assert> (any number)
      • <sqf:fix> (optional, any number)
        • <sqf:add> (any number)
          • <sqf:description> (single)
            • <sqf:title> (single)
            • <sqf:p> (optional, single)
        • <sqf:replace> (any number)
          • <sqf:description> (single)
            • <sqf:title> (single)
            • <sqf:p> (optional, single)

Basic Schematron Elements

<schema>
The root element of a Schematron configuration file.

The <schema> element should include the following arguments:

<schema xmlns="http://purl.oclc.org/dsdl/schematron" xmlns:sqf="http://www.schematron-quickfix.com/validator/process" queryBinding="xslt2">

The namespaces are specific to Schematron 2.0.

<pattern id="yourLabelHere">
Groups related rules that are related in some way. For example, grammatical rules.

Requires an @id attribute assigned.

<pattern id="STRUCTURE_11">
The pattern @id attribute value is visible in the Schematron flag headers that appear in Heretto CCMS.
Grammar example
<rule>
Defines a context, by using XPath 2.0, (XPath) in which to apply the Schematron assert or report test on the content.

In this example, the Schematron rule would be applied to unordered and ordered list elements only.

<rule id="OrderedUnorderedLists" context="ul|ol">

In this example, the Schematron rule context detects whether a section element is the first section in a reference body element.

<rule id="RefbodySections" context="refbody/section[count(preceding-sibling::*) = 0]">
        
<assert>
Triggers a rule when the @test attribute value (XPath) evaluates to false.

In general, use an assert to evaluate whether something is missing in the content or the structure.

In the following example, a rule is triggered when a list contains only one list item.

<assert test="count(li) > 1">A list must have at least two list items.</assert>
<report>
Triggers a rule when the @test attribute value (XPath) evaluates to true.

In general, use a report to evaluate whether something is present in the content or the structure, and shouldn't be.

In the following example, a rule is triggered when you enter displays.

<report test="contains(., 'displays')">Use "shows" or "appears" instead.</report>

Schematron QuickFix Elements

Important: Currently, Heretto CCMS enables you to use the <sqf:add> and <sqf:replace> QuickFix actions.
<sqf:fix>
Contains either <sqf:add> or <sqf:replace> QuickFix actions.

Requires an @id attribute assigned.

<sqf:fix id="addListItem">

To link a QuickFix action, the @id attribute value must be referenced in the corresponding <report> or <assert> element.

<assert test="count(li) &gt; 1" sqf:fix="addListItem">A list must have at least two list items.</assert>

To apply a QuickFix action automatically, add the j:auto-apply-fix="true" to the corresponding <report> or <assert> element.

<assert test="count(li) &gt; 1" sqf:fix="addListItem" j:auto-apply-fix="true">A list must have at least two list items.</assert>
Warning: We recommend thoroughly testing a given rule before using the j:auto-apply-fix="true" attribute.
<sqf:description>
Can contain an <sqf:title> element and an <sqf:p> element.
<sqf:title>
The title of <sqf:fix> element. In Heretto CCMS, it is rendered as a QuickFix button.
QuickFix button example
<sqf:p>
An additional description of the QuickFix action. In Heretto CCMS, the description appears below the QuickFix button.
QuickFix with dsescription
<sqf:add>
A QuickFix action that adds an XML node, for example, an element or an attribute.
Should have the @node-type, @element, and @position attributes assigned.
<!-- Unordered List and Ordered List elements should contain at least two List Item elements -->
<pattern id="STRUCTURE_11">
    <rule context="ul|ol">
        <assert test="count(li) &gt; 1" sqf:fix="addListItem">Unordered List and Ordered List
            elements should contain at least two List Item elements.</assert>
        <sqf:fix id="addListItem">
            <sqf:description>
                <sqf:title>Add a List Item element</sqf:title>
                <sqf:p>To fix this issue, you can add another List Item element. If you cannot
                    come up with another List Item element, convert the list element to a Paragraph
                    element.</sqf:p>
            </sqf:description>
            <sqf:add node-type="element" target="li" position="last-child"/>
        </sqf:fix>
    </rule>
</pattern>
<sqf:replace>
A QuickFix action that replaces an XML node with another XML node.
<!-- Refer to the CCMS product by using the `varsProperNouns/productName` conkeyref -->
<pattern id="STYLE_30">
    <rule context="text()[matches(.,'[Hh][Ee][Rr][Ee] [Tt] [Oo]\W')]">
        <report test="." sqf:fix="productName">Refer to the CCMS product by using the `varsProperNouns/productName` conkeyref.        </report>
            <sqf:fix id="productName">
                <sqf:description>
                    <sqf:title>Insert Conkeyref</sqf:title>
                    </sqf:description>
            <sqf:replace match="productName">
                <ph xmlns="" conkeyref="varsProperNouns/companyName"/>
            </sqf:replace>
            </sqf:fix>
    </rule>
</pattern>

For more information about Schematron QuickFix elements and attributes, see the SQF User Guide.