p:validate-with-relax-ng (3.0)

Validate a document using RELAX NG.

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-relax-ng">
  <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="text 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="dtd-attribute-values" as="xs:boolean" required="false" select="false()"/>
  <option name="dtd-id-idref-warnings" as="xs:boolean" required="false" select="false()"/>
  <option name="parameters" as="map(xs:QName,item()*)?" required="false" select="()"/>
  <option name="report-format" as="xs:string" required="false" select="'xvrl'"/>
</p:declare-step>

The p:validate-with-relax-ng step validates the document appearing on the source port using RELAX NG (REgular LAnguage for XML Next Generation) validation. The RELAX NG 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`	`text xml`	`false`	The RELAX NG schema to validate against: If the document appearing on this port is XML (has an XML media type), it must be a valid RELAX NG XML Syntax schema. If the document appearing on this port is text (has a text media type), it must be a valid RELAX NG Compact Syntax schema.
`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 `XC0155` 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 `XC0155` 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.
`dtd-attribute-values`	`xs:boolean`	`false`	`false`	If `true`, the attribute value defaulting conventions of RELAX NG are applied. See the RELAX NG DTD Compatibility specification for more information.
`dtd-id-idref-warnings`	`xs:boolean`	`false`	`false`	If `true`, a schema that is incompatible with the ID/IDREF/IDREFs feature of RELAX’NG DTD Compatibility as invalid. See the RELAX NG DTD Compatibility specification for more information.
`parameters`	`map(xs:QName,item()*)?`	`false`	`()`	Parameters controlling the validation. See Validation parameters for more information.
`report-format`	`xs:string`	`false`	`xvrl`	The format for the document on the `report` port. The value `xvrl` (default) will always work: the report will be 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-relax-ng step applies RELAX NG (REgular LAnguage for XML Next Generation) validation to the document appearing on the source port. The RELAX NG schema is supplied using the schema port. The outcome of the step, what appears on the result port, is a verbatim copy of the source document.

RELAX NG has two syntaxes: An XML based syntax and a text based syntax. Both can be used.

Validation parameters

The p:validate-with-relax-ng step has a parameters port of datatype map(xs:QName, item()*)?. This (optional) map passes additional parameters for the validation process to the step:

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: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.
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>A thing...</thing>
  <thing>Another thing...</thing>
</things>

A RELAX NG schema to validate this is as follows:

<grammar ns="" xmlns="http://relaxng.org/ns/structure/1.0">
  <start>
    <element name="things">
      <oneOrMore>
        <element name="thing">
          <text/>
        </element>
      </oneOrMore>
    </element>
  </start>
</grammar>

Performing this validation using the p:validate-with-relax-ng step 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-relax-ng name="validate">
    <p:with-input port="schema" href="example.rng"/>
  </p:validate-with-relax-ng>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:09.29+01:00</timestamp>
      <document href="file:/…/…/input-valid.xml"/>
      <schema href="file:/…/…/example.rng"
              schematypens="http://relaxng.org/ns/structure/1.0"/>
      <validator name="jing"/>
   </metadata>
   <digest/>
</report>

Basic usage (invalid source document)

Using the same RELAX NG 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 xmlns:thingies="https://www.xprocref.org/ns/thingies">
  <thingies:thing id="A" invalid-attribute="true">A thing...</thingies:thing>
  <thingies:thing id="B">Another thing...</thingies:thing>
</things>

Performing this validation using the p:validate-with-relax-ng step 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-relax-ng assert-valid="false" name="validate">
    <p:with-input port="schema" href="example.rng"/>
  </p:validate-with-relax-ng>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:09.6+01:00</timestamp>
      <document href="file:/…/…/input-invalid.xml"/>
      <schema href="file:/…/…/example.rng"
              schematypens="http://relaxng.org/ns/structure/1.0"/>
      <validator name="jing"/>
   </metadata>
   <detection severity="error">
      <location line="3" column="16"/>
      <message>element "thing-error" not allowed anywhere; expected the element end-tag or element "thing"</message>
   </detection>
   <digest/>
</report>

Additional details

p:validate-with-relax-ng 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
`XC0117`	It is a dynamic error if a report-format option was specified that the processor does not support.
`XC0153`	It is a dynamic error if the document supplied on `schema` port cannot be interpreted as an RELAX NG Grammar.
`XC0155`	It is a dynamic error if the `assert-valid` option on `<p:validate-with-relax-ng>` is `true` and the input document is not valid.

Reference information

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

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

The p:validate-with-relax-ng step is part of categories:

The p:validate-with-relax-ng step is also present in version: 3.1.