p:validate-with-schematron (3.1)

Validates a document using Schematron.

Summary
Description
- Validation parameters
Examples
- Basic usage (valid source document)
- Basic usage (invalid source document)
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:validate-with-schematron">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <input port="schema" primary="false" content-types="xml" sequence="false"/>
  <output port="report" primary="false" content-types="xml json" sequence="true"/>
  <option name="assert-valid" as="xs:boolean" required="false" select="true()"/>
  <option name="parameters" as="map(xs:QName,item()*)?" required="false" select="()"/>
  <option name="phase" as="xs:string" required="false" select="'#DEFAULT'"/>
  <option name="report-format" as="xs:string" required="false" select="'svrl'"/>
</p:declare-step>

The p:validate-with-schematron step validates the document appearing on the source port using Schematron validation. The Schematron schema is supplied through the schema port. The result port emits a copy of the source document.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`source`	`input`	`true`	`xml html`	`false`	The document to validate.
`result`	`output`	`true`	`xml html`	`false`	A verbatim copy of the document that appeared on the `source` port.
`schema`	`input`	`false`	`xml`	`false`	The Schematron schema to validate against.
`report`	`output`	`false`	`xml json`	`true`	A report that describes the validation results, both for valid and invalid source documents. The format for this report is determined by the `report-format` option. When the `assert-valid` option is `true` and the document is invalid, nothing will appear on this port because error `XC0054` is raised.

Options:

Name	Type	Req?	Default	Description
`assert-valid`	`xs:boolean`	`false`	`true`	Determines what happens if the document is invalid: If `true`, error `XC0054` is raised. If `false`, the step always succeeds. The validity of the document must be determined by inspecting the document that appears on the `report` port.
`parameters`	`map(xs:QName,item()*)?`	`false`	`()`	Parameters controlling the validation. See Validation parameters for more information.
`phase`	`xs:string`	`false`	`#DEFAULT`	The Schematron schema phase to select.
`report-format`	`xs:string`	`false`	`svrl`	The format for the document on the `report` port: The value `svrl` (default) produces a report in SVRL (Schematron Validation Report Language). The value `xvrl` (default) produces a report in XVRL (Extensible Validation Report Language). Whether any other formats are supported is implementation-defined and therefore dependent on the XProc processor used.

Description

The p:validate-with-schematron step applies Schematron validation to the document appearing on the source port. The Schematron schema must be supplied using the schema port. The outcome of the step, what appears on the result port, is a verbatim copy of the source document.

Validation parameters

The p:validate-with-schematron step has a parameters port of datatype map(xs:QName, item()*)?. This (optional) map passes additional parameters for the validation process to the step, which correspond to Schematron external variables, to parameters that influence code generation, or to parameters that influence SVRL to XVRL conversion.

The parameters in this map, their values and semantics are implementation-defined and therefore dependent on the XProc processor used.
A special entry with key c:implementation (the c namespace prefix is bound to the standard XProc namespace http://www.w3.org/ns/xproc-step) is reserved to select a Schematron implementation the XProc processor supports.The list of supported Schematron implementations and their associated values is implementation-defined and therefore dependent on the XProc processor used.
A special entry with key c:compile (the c namespace prefix is bound to the standard XProc namespace http://www.w3.org/ns/xproc-step) is reserved for parameters for the schema compilation (if applicable). The value of this key must be a map itself.
For instance, if a code-generating implementation such as SchXslt is used, the entries of the c:compile map are passed to the code generator.
If the report-format option is set to xvrl (default): Any entries with keys in the xvrl namespace (http://www.xproc.org/ns/xvrl) are passed as parameters to the process that generates the XVRL report appearing on the report port. All standard XVRL generation parameters are supported.

Examples

Basic usage (valid source document)

Assume we have an input document, called input-valid.xml, that looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<things>
  <thing id="A">A thing...</thing>
  <thing id="B">Another thing... referencing <thingref idref="A"/>!</thing>
</things>

Any <thingref> elements must reference existing <thing> elements by identifier. Here is a simple Schematron schema that validates this:

<schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2">

  <pattern>
    <rule context="thingref/@idref">
      <let name="id" value="string(.)"/>
      <assert test="exists(//thing[@id eq $id])">Reference to non-existent id: "<value-of select="$id"/>"</assert>
    </rule>
  </pattern>

</schema>

Performing this validation using the p:validate-with-schematron step (which, for this example, uses the SchXslt Schematron processor) returns the following on the report port:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-schematron name="validate">
    <p:with-input port="schema" href="example.sch"/>
  </p:validate-with-schematron>

</p:declare-step>

Result document:

<svrl:schematron-output xmlns:svrl="http://purl.oclc.org/dsdl/svrl">
   <svrl:metadata>
      <dct:creator xmlns:dct="http://purl.org/dc/terms/">
         <dct:Agent>
            <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SAXON/HE 12.4</skos:prefLabel>
         </dct:Agent>
      </dct:creator>
      <dct:created xmlns:dct="http://purl.org/dc/terms/">2025-02-06T10:45:03.3638698+01:00</dct:created>
      <dct:source xmlns:dct="http://purl.org/dc/terms/">
         <rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
            <dct:creator>
               <dct:Agent>
                  <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SchXslt/1.10.1 SAXON/HE 12.4</skos:prefLabel>
                  <schxslt.compile.typed-variables xmlns="https://doi.org/10.5281/zenodo.1495494#">true</schxslt.compile.typed-variables>
               </dct:Agent>
            </dct:creator>
            <dct:created>2025-02-06T10:45:03.3578884+01:00</dct:created>
         </rdf:Description>
      </dct:source>
   </svrl:metadata>
   <svrl:active-pattern documents="file:/…/…/input-valid.xml"/>
   <svrl:fired-rule context="thingref/@idref"/>
</svrl:schematron-output>

The same example, but now producing a XVRL format report, is as follows:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-schematron name="validate" report-format="xvrl">
    <p:with-input port="schema" href="example.sch"/>
  </p:validate-with-schematron>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:03.01+01:00</timestamp>
      <document href="file:/…/…/input-valid.xml"/>
      <schema href="file:/…/…/example.sch"
              schematypens="http://purl.oclc.org/dsdl/schematron"/>
      <validator name="SchXslt"/>
   </metadata>
   <digest/>
</report>

The exact format of the reports might differ across implementations. Please experiment before using it.

Basic usage (invalid source document)

Using the same Schematron schema as in Basic usage (valid source document), we’re now going to validate an invalid document (called input-invalid.xml). Since we want to have a look at what comes out of the report port, we have to set the assert-valid option to false.

<?xml version="1.0" encoding="UTF-8"?>
<things>
  <thing id="A">A thing...</thing>
  <thing id="B">Another thing... referencing <thingref idref="C"/>!</thing>
</things>

Performing this validation using the p:validate-with-schematron step (which, for this example, uses the SchXslt Schematron processor) returns the following on the report port:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-schematron assert-valid="false" name="validate">
    <p:with-input port="schema" href="example.sch"/>
  </p:validate-with-schematron>

</p:declare-step>

Result document:

<svrl:schematron-output xmlns:svrl="http://purl.oclc.org/dsdl/svrl">
   <svrl:metadata>
      <dct:creator xmlns:dct="http://purl.org/dc/terms/">
         <dct:Agent>
            <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SAXON/HE 12.4</skos:prefLabel>
         </dct:Agent>
      </dct:creator>
      <dct:created xmlns:dct="http://purl.org/dc/terms/">2025-02-06T10:45:03.4366224+01:00</dct:created>
      <dct:source xmlns:dct="http://purl.org/dc/terms/">
         <rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
            <dct:creator>
               <dct:Agent>
                  <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SchXslt/1.10.1 SAXON/HE 12.4</skos:prefLabel>
                  <schxslt.compile.typed-variables xmlns="https://doi.org/10.5281/zenodo.1495494#">true</schxslt.compile.typed-variables>
               </dct:Agent>
            </dct:creator>
            <dct:created>2025-02-06T10:45:03.4296458+01:00</dct:created>
         </rdf:Description>
      </dct:source>
   </svrl:metadata>
   <svrl:active-pattern documents="file:/…/…/input-invalid.xml"/>
   <svrl:fired-rule context="thingref/@idref"/>
   <svrl:failed-assert location="/Q{}things[1]/Q{}thing[2]/Q{}thingref[1]/@Q{}idref"
                       test="exists(//thing[@id eq $id])">
      <svrl:text>Reference to non-existent id: "C"</svrl:text>
   </svrl:failed-assert>
</svrl:schematron-output>

The same example, but now producing a XVRL format report, is as follows:

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result" pipe="report@validate"/>

  <p:validate-with-schematron name="validate" assert-valid="false" report-format="xvrl">
    <p:with-input port="schema" href="example.sch"/>
  </p:validate-with-schematron>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:03.68+01:00</timestamp>
      <document href="file:/…/…/input-invalid.xml"/>
      <schema href="file:/…/…/example.sch"
              schematypens="http://purl.oclc.org/dsdl/schematron"/>
      <validator name="SchXslt"/>
   </metadata>
   <detection severity="error">
      <location xpath="/Q{}things[1]/Q{}thing[2]/Q{}thingref[1]/@Q{}idref"/>
      <message>Reference to non-existent id: "C"</message>
   </detection>
   <digest/>
</report>

Again, the exact format of the reports might differ across implementations. Please experiment before using it.

Another way of handling validation errors is to have p:validate-with-schematron raise its error XC0054 (by setting the assert-valid option to true) and catch this in a <p:try>/<p:catch> construction. The following pipeline shows you the <c:errors> result, that is available inside the <p:catch>:

<p:declare-step xmlns:err="http://www.w3.org/ns/xproc-error" xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:try>
    <p:validate-with-schematron assert-valid="true">
      <p:with-input port="schema" href="example.sch"/>
    </p:validate-with-schematron>
    <p:catch code="err:XC0054">
      <p:identity/>
    </p:catch>
  </p:try>
  
</p:declare-step>

Result document:

<c:errors xmlns:c="http://www.w3.org/ns/xproc-step">
   <c:error xmlns:err="http://www.w3.org/ns/xproc-error"
            code="err:XC0054"
            name="!1.1.1.1"
            type="p:validate-with-schematron"
            href="file:/…/…/…"
            line="7"
            column="53">
      <svrl:schematron-output xmlns:svrl="http://purl.oclc.org/dsdl/svrl">
         <svrl:metadata>
            <dct:creator xmlns:dct="http://purl.org/dc/terms/">
               <dct:Agent>
                  <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SAXON/HE 12.4</skos:prefLabel>
               </dct:Agent>
            </dct:creator>
            <dct:created xmlns:dct="http://purl.org/dc/terms/">2025-02-06T10:45:03.501597+01:00</dct:created>
            <dct:source xmlns:dct="http://purl.org/dc/terms/">
               <rdf:Description xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
                  <dct:creator>
                     <dct:Agent>
                        <skos:prefLabel xmlns:skos="http://www.w3.org/2004/02/skos/core#">SchXslt/1.10.1 SAXON/HE 12.4</skos:prefLabel>
                        <schxslt.compile.typed-variables xmlns="https://doi.org/10.5281/zenodo.1495494#">true</schxslt.compile.typed-variables>
                     </dct:Agent>
                  </dct:creator>
                  <dct:created>2025-02-06T10:45:03.4976139+01:00</dct:created>
               </rdf:Description>
            </dct:source>
         </svrl:metadata>
         <svrl:active-pattern documents="file:/…/…/input-invalid.xml"/>
         <svrl:fired-rule context="thingref/@idref"/>
         <svrl:failed-assert location="/Q{}things[1]/Q{}thing[2]/Q{}thingref[1]/@Q{}idref"
                             test="exists(//thing[@id eq $id])">
            <svrl:text>Reference to non-existent id: "C"</svrl:text>
         </svrl:failed-assert>
      </svrl:schematron-output>
   </c:error>
</c:errors>

The exact contents of the <c:errors> element might differ across implementations. Please experiment before using it.

Additional details

p:validate-with-schematron preserves all document-properties of the document appearing on its source port for the document on its result port.
The document appearing on the report port only has a content-type property. It has no other document-properties (also no base-uri).
The document appearing on the result port may have been enriched with PSVI (Post-Schema-Validation-Infoset) annotations (see the XML Schema recommendation).

Errors raised

Error code	Description
`XC0054`	It is a dynamic error if the `assert-valid` option is `true` and any Schematron assertions fail.
`XC0117`	It is a dynamic error if a report-format option was specified that the processor does not support.
`XC0151`	It is a dynamic error if the document supplied on `schema` port is not a valid Schematron document.

Reference information

This description of the p:validate-with-schematron step is for XProc version: 3.1. This is a non-required step (an XProc 3.1 processor does not have to support this).

The formal specification for the p:validate-with-schematron step can be found here.

The p:validate-with-schematron step is part of categories:

The p:validate-with-schematron step is also present in version: 3.0.