p:validate-with-nvdl (3.1)

Validate a document using NVDL.

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-nvdl">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <input port="nvdl" primary="false" content-types="xml" sequence="false"/>
  <input port="schemas" primary="false" content-types="text xml" sequence="true">
    <p:empty/>
  <input/>
  <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="report-format" as="xs:string" required="false" select="'xvrl'"/>
</p:declare-step>

The p:validate-with-nvdl step validates the document appearing on the source port using NVDL (Namespace-based Validation Dispatching Language) validation. The NVDL schema is supplied through the nvdl 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.
`nvdl`	`input`	`false`	`xml`	`false`	The NVDL schema to validate against.
`schemas`	`input`	`false`	`text xml`	`true`	Optional schemas, referenced from the NVDL schema by URI. See the description below for more information.
`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 `XC0053` 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 `XC0053` 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.
`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.

Name

Type

Req?

Default

Description

assert-valid

xs:boolean

false

true

Determines what happens if the document is invalid:

If true, error XC0053 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.

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-nvdl step applies NVDL (Namespace-based Validation Dispatching Language) validation to the document appearing on the source port. The NVDL schema is supplied using the nvdl port. The outcome of the step, what appears on the result port, is a verbatim copy of the source document.

An NVDL schema usually refers to other schemas by URI. To find such a schema, the step first looks at the schemas provided on the schema port (if any). If a schema with the same base URI as mentioned in the NVDL schema is present on the schemas port, this is used. If not, the XProc processor will attempt to load it by its URI, usually from disk.

Validation parameters

The p:validate-with-nvdl 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 xmlns:thingies="https://www.xprocref.org/ns/thingies">
  <thingies:thing id="A">A thing...</thingies:thing>
  <thingies:thing id="B">Another thing...</thingies:thing>
</things>

Since this document mixes namespaces, we want to validate it using NVDL. An NVDL schema for this, called example.nvdl, is as follows:

<rules xmlns="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0">
  <namespace ns="https://www.xprocref.org/ns/thingies">
    <validate schema="thingies.xsd"/>
  </namespace>
  <anyNamespace>
    <allow/>
  </anyNamespace>
</rules>

The <thing> elements in the https://www.xprocref.org/ns/thingies namespace are validated using the following simple XML schema called thingies.xsd. It says that the only thing allowed is a <thing> element with a required id attribute:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" targetNamespace="https://www.xprocref.org/ns/thingies"
  xmlns="https://www.xprocref.org/ns/thingies">
  <xs:element name="thing">
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base="xs:string">
          <xs:attribute name="id" type="xs:NCName" use="required"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>
</xs:schema>

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

</p:declare-step>

Result document:

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

Basic usage (invalid source document)

Using the same NVDL 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-nvdl 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-nvdl name="validate" assert-valid="false">
    <p:with-input port="nvdl" href="example.nvdl"/>
  </p:validate-with-nvdl>

</p:declare-step>

Result document:

<report xmlns="http://www.xproc.org/ns/xvrl">
   <metadata>
      <timestamp>2025-02-06T10:45:03.59+01:00</timestamp>
      <document href="file:/…/…/input-invalid.xml"/>
      <schema href="file:/…/…/example.nvdl"
              schematypens="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0"/>
      <validator name="jing"/>
   </metadata>
   <detection severity="error">
      <location line="2" column="51"/>
      <message>cvc-complex-type.3.2.2: Attribute 'invalid-attribute' is not allowed to appear in element 'thingies:thing'.</message>
   </detection>
   <digest/>
</report>

Additional details

p:validate-with-nvdl 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
`XC0053`	It is a dynamic error if the `assert-valid` option on `<p:validate-with-nvdl>` is `true` and the input document is not valid.
`XC0117`	It is a dynamic error if a report-format option was specified that the processor does not support.
`XC0154`	It is a dynamic error if the document supplied on `nvdl` port is not a valid NVDL document.

Reference information

This description of the p:validate-with-nvdl 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-nvdl step can be found here.

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

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