5 Syntax
5.1Well-formedness
A Schematron schema shall be a well-formed XML document, according to the version of XML used.
5.2Namespace
All elements shown in the grammar for Schematron are qualified with the namespace URI:
http://purl.oclc.org/dsdl/schematron
In subsequent clauses, the prefix sch is taken as bound to the Schematron namespace URI for exposition purposes. The prefix sch is not reserved or required by this part of ISO/IEC 19757.
Any element can also have foreign attributes in addition to the attributes shown in the grammar. A foreign attribute is an attribute with a name whose namespace URI is neither the empty string nor the Schematron namespace URI. Any non-empty element may have foreign child elements in addition to the child elements shown in the grammar. A foreign element is an element with a name whose namespace URI is not the Schematron namespace URI. There are no constraints on the relative position of foreign child elements with respect to other child elements.
5.3Whitespace
Any element can also have as children strings that consist entirely of whitespace characters, where a whitespace character is one of U+0020, U+009, U+00D or U+00A. There are no constraints on the relative position of whitespace string children with respect to child elements.
NOTE 1:  Leading and trailing whitespace should be stripped from attributes defined by this part. Whitespace should be collapsed in elements defined by this part that allow text. Whitespace may be stripped from elements defined by this part that do not allow text.
5.4Core Elements
The grammar for Schematron elements is given in Annex A.
5.4.1 
active element
The required pattern attribute is a reference to a pattern that is active in the current phase.
5.4.2 
assert element
An assertion made about the context nodes. The data content is a natural-language assertion. The required test attribute is an assertion test evaluated in the current context. If the test evaluates positive, the report succeeds. The optional diagnostics attribute is a reference to further diagnostic information.
The natural-language assertion shall be a positive statement of a constraint.
NOTE 2:  The natural-language assertion may contain information about actual values in addition to expected values and may contain diagnostic information. Users should note, however, that the
diagnostic element is provided for such information to encourage clear statement of the natural-language assertion.
The icon, see and fpi attributes allow rich interfaces and documentation. They are defined below.
The flag attribute allows more detailed outcomes. It is defined below.
The role and subject attributes allow explicit identification of some part of a pattern. They are defined below.
5.4.3 
extends element
Abstract rules are named lists of assertions without a context expression. The required rule attribute references an abstract rule. The current rule uses all the assertions from the abstract rule it extends.
5.4.4 
include element
The required href attribute references an external well-formed XML document whose document element is a Schematron element of a type which allowed by the grammar for Schematron at the current position in the schema. The external document is inserted in place of the include element.
5.4.5 
let element
A declaration of a named variable. If the let element is the child of a rule element, the variable is calculated and scoped to the current rule and context. Otherwise, the variable is calculated with the context of the instance document root.
The required name attribute is the name of the variable. The required value attribute is an expression evaluated in the current context.
It is an error to reference a variable that has not been defined in the current schema, phase, pattern, or rule, if the query language binding allows this to be determined reliably. It is an error for a variable to be multiply defined in the current schema, phase, pattern and rule.
The variable is substituted into assertion tests and other expressions in the same rule before the test or expression is evaluated. The query language binding specifies which lexical conventions are used to detect references to variables.
An implementation may provide a facility to override the values of top-level variables specified by let elements under the schema element. For example, an implementation may allow top-level variables to be supplied on the command line. The values provided are strings or data objects, not expressions.
5.4.6 
name element
Provides the names of nodes from the instance document to allow clearer assertions and diagnostics. The optional path attribute is an expression evaluated in the current context that returns a string that is the name of a node. In the latter case, the name of the node is used.
An implementation which does not report natural-language assertions is not required to make use of this element.
5.4.7 
ns element
Specification of a namespace prefix and URI. The required prefix attribute is an XML name with no colon character. The required uri attribute is a namespace URI.
NOTE 3:  Because the characters allowed as names may change in versions of XML subsequent to W3C XML 1.0, the RELAX NG Compact schema for Schematron does not constrain the prefix to particular characters.
In an ISO Schematron schema, namespace prefixes in context expressions, assertion tests and other query expressions should use the namespace bindings provided by this element. Namespace prefixes should not use the namespace bindings in scope for element and attribute names.
5.4.8 
param element
A name-value pair providing parameters for an abstract pattern. The required name attribute is an XML name with no colon. The required value attribute is a fragment of a query.
5.4.9 
pattern element
A structure, simple or complex. A set of rules giving constraints that are in some way related. The id attribute provides a unique name for the pattern and is required for abstract patterns.
The title and p elements allow rich documentation.
The icon, see and fpi attributes allow rich interfaces and documentation.
When a pattern element has the attribute abstract with a value true, then the pattern defines an abstract pattern. An abstract pattern shall not have a is-a attribute and shall have an id attribute.
Abstract patterns allow a common definition mechanism for structures which use different names and paths, but which are at heart the same. For example, there are different table markup languages, but they all can be in large part represented as an abstract pattern where a table contains rows and rows contain entries, as defined in the following example using the default query language binding:

    <sch:pattern abstract="true" id="table">
        <sch:rule context="$table">
            <sch:assert test="$row">
            The element <name/> is a table. Tables contain rows.
            </sch:assert>
        </sch:rule>
        
        <sch:rule context="$row">
            <sch:assert test="$entry">
            The element <name/> is a table row. Rows contain entries.
            </sch:assert>
        </sch:rule>
        
    </sch:pattern>
When a pattern element has the attribute is-a with a value specifying the name of an abstract pattern, then the pattern is an instance of an abstract pattern. Such a pattern shall not contain any rule elements, but shall have param elements for all parameters used in the abstract pattern.
The following example uses the abstract pattern for tables given above to create three patterns for tables with different names or structures.

    <sch:pattern is-a="table" id="HTML_Table">
        <sch:param name="table" value="table"/>
        <sch:param name="row"   value="tr"/>
        <sch:param name="entry" value="td|th"/>
    </sch:pattern>
    
    <sch:pattern is-a="table" id="CALS_Table">
        <sch:param name="table" value="table"/>
        <sch:param name="row"   value=".//row"/>
        <sch:param name="entry" value="cell"/>
    </sch:pattern>
    
    <sch:pattern is-a="table" id="calendar">
        <sch:param name="table" value="calendar/year"/>
        <sch:param name="row"   value="week"/>
        <sch:param name="entry" value="day"/>
    </sch:pattern>
When creating an instance of an abstract pattern, the parameter values supplied by the param element replace the parameter references used in the abstract patterns. The examples above use the default query language binding in which the character $ is used as the delimiter for parameter references.
Thus, given the abstract patterns defined earlier in this clause, the patterns defined above are equivalent to the following, with the id elements shown expanded:

    <sch:pattern id="HTML_table">
        <sch:rule context="table">
            <sch:assert test="tr">
            The element table is a table. Tables containing rows.
            </sch:assert>
        </sch:rule>
        
        <sch:rule context="tr">
            <sch:assert test="td|th">
            The element tr is a table row. Rows contain entries.
            </sch:assert>
        </sch:rule>
        
    </sch:pattern>
    
    <sch:pattern id="CALS_table">
        <sch:rule context="table">
            <sch:assert test=".//row">
            The element table is a table. Tables containing rows.
            </sch:assert>
        </sch:rule>
        
        <sch:rule context=".//row">
            <sch:assert test="cell">
            The element row is a table row. Rows contain entries.
            </sch:assert>
        </sch:rule>
        
    </sch:pattern>
    
    <sch:pattern id="calendar">
        <sch:rule context="calendar/year">
            <sch:assert test="week">
            The element year is a table. Tables containing rows.
            </sch:assert>
        </sch:rule>
        
        <sch:rule context="week">
            <sch:assert test="day">
            The element week is a table row. Rows contain entries.
            </sch:assert>
        </sch:rule>
        
    </sch:pattern>
5.4.10 
phase element
A grouping of patterns, to name and declare variations in schemas, for example, to support progressive validation. The required id attribute is the name of the phase. The implementation determines which phase to use for validating documents, for example by user command.
Two names, #ALL and #DEFAULT, have special meanings. The name #ALL is reserved and available for use by implementations to denote that all patterns are active. The name #DEFAULT is reserved and available for use by implementations to denote that the name given in in the defaultPhase attribute on the schema element should be used. If no defaultPhase is specified, then all patterns are active.
NOTE 4:  The names
#ALL and 
#DEFAULT shall not be used in a Schematron schema. They are for use when invoking or configuring schema validation, for example as a command-line parameter.
The icon, see and fpi attributes allow rich interfaces and documentation.
5.4.11 
report element
An assertion made about the context nodes. The data content is a natural-language assertion. The required test attribute is an assertion test evaluated in the current context. If the test evaluates positive, the report succeeds. The optional diagnostics attribute is a reference to further diagnostic information.
The natural-language assertion shall be a positive statement of a found pattern or a negative statement of a constraint.
NOTE 5:  The natural-language assertion may contain information about actual values in addition to expected values and may contain diagnostic information. Users should note, however, that the
diagnostic element is provided for such information to encourage clear statement of the natural-language assertion.
The icon, see and fpi attributes allow rich interfaces and documentation. They are defined below.
The flag attribute allows more detailed outcomes. It is defined below.
The role and subject attributes allow explicit identification of some part of a pattern. They are defined below.
5.4.12 
rule element
A list of assertions tested within the context specified by the required context attribute. The context attribute specifies the rule context expression.
NOTE 6:  It is not an error if a rule never fires in a document. In order to test that a document always has some context, a new pattern should be created from the context of the document, with an assertion requiring the element or attribute.
The icon, see and fpi attributes allow rich interfaces and documentation.
The flag attribute allows more detailed outcomes. It is defined below.
The role and subject attributes allow explicit identification of some part of a pattern as part of the validation outcome. They are defined below.
When the rule element has the attribute abstract with a value true, then the rule is an abstract rule. An abstract rule shall not have a context attribute. An abstract rule is a list of assertions that will be invoked by other rules belonging to the same pattern using the extends element. Abstract rules provide a mechanism for reducing schema size.
5.4.13 
schema element
The top-level element of a Schematron schema.
The optional schemaVersion attribute gives the version of the schema. Its allowed values are not defined by this part of ISO/IEC 19757 and its use is implementation-dependent.
The optional queryBinding attribute provides the short name of the query language binding in use. If this attribute is specified, it is an error if it has a value that the current implementation does not support.
The defaultPhase attribute may be used to indicate the phase to use in the absence of explicit user-supplied information.
The title and p elements allow rich documentation.
The icon, see and fpi attributes allow rich interfaces and documentation.
5.4.14 
value-of element
Finds or calculates values from the instance document to allow clearer assertions and diagnostics. The required select attribute is an expression evaluated in the current context that returns a string.
Variable references in the select attribute are resolved in the scope of the current schema, phase, pattern and rule.
An implementation which does not report natural-language assertions is not required to make use of this element.
5.5Ancillary Elements and Attributes
5.5.1 
diagnostic element
A natural-language message giving more specific details concerning a failed assertion, such as found versus expected values and repair hints.
NOTE 7:  in multiple languages may be supported by using a different
diagnostic element for each language, with the appropriate 
xml:lang language attribute, and referencing all the unique identifiers of the 
diagnostic elements in the 
diagnostics attribute of the assertion. Annex G gives a simple example of a multi-lingual schema.
An implementation is not required to make use of this element.
5.5.2 
diagnostics element
Section containing individual diagnostic elements.
An implementation is not required to make use of this element.
5.5.3 
dir element
A section of natural-language text with a direction specified by the value attribute. The value ltr indicates left-to-right text; the value rtl indicates right-to-left text.
An implementation is not required to make use of this element.
5.5.4 
emph element
A portion of text that should be rendered with some emphasis.
An implementation is not required to make use of this element.
5.5.5 
flag attribute
A boolean variable with initial value false. A flag is implicitly declared by an assertion or rule having a flag attribute with that name. The value of a flag becomes true when an assertion with that flag fails or a rule with that flag fires.
The purpose of flags is to convey state or severity information to a subsequent process.
An implementation is not required to make use of this attribute.
5.5.6 
fpi attribute
A formal public identifier for the schema, phase or other element.
An implementation is not required to make use of this attribute.
5.5.7 
icon attribute
The location of a graphics file containing some visible representation of the severity, significance or other grouping of the associated element.
An implementation is not required to make use of this attribute.
5.5.8 
p element
A paragraph of natural language text containing maintainer and user information about the parent element. The schema can nominate paragraphs that should be rendered in a distinct way, keyed with the class attribute.
An implementation is not required to make use of this element.
5.5.9 
role attribute
A name describing the function of the assertion or context node in the pattern. If the assertion has a subject attribute, then the role labels the arc between the context node and any nodes which match the path expression given by the subject attribute.
An implementation is not required to make use of this attribute.
5.5.10 
see attribute
The URI of external information of interest to maintainers and users of the schema.
An implementation is not required to make use of this attribute.
5.5.11 
span element
A portion of some paragraph that should be rendered in a distinct way, keyed with the class attribute.
An implementation is not required to make use of this element.
5.5.12 
subject attribute
A path allowing more precise specification of nodes. The path expression is evaluated in the context of the context node of the current rule. If no subject attribute is specified, the current subject node may be used.
NOTE 8:  The
subject attribute is required because the rule context may have been selected for reasons of convenience or performance, in association with the particular assertion tests. In such cases, the rule context may not be useful to identify users, and the nodes located by the 
subject attribute may be more useful. Similarly, it may not be possible to determine from an assertion test which nodes the assertion test has tested. In such a case, the nodes located by the 
subject attribute may be more useful.
An implementation is not required to make use of this element.
5.5.13 
title element
A summary of the purpose or role of the schema or pattern, for the purpose of documentation or a rich user interface.
An implementation is not required to make use of this element.