The presentation of this document has been augmented to identify changes from a previous version. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.


W3C

XProc: An XML Pipeline Language

W3C Editor's Draft (with revision marks) 29 August 2007

This Version:
http://www.w3.org/TR/2007/ED-xproc-20070829/
Latest Version:
http://www.w3.org/TR/xproc/
Previous versions:
http://www.w3.org/TR/2007/WD-xproc-20070405/ http://www.w3.org/TR/2006/WD-xproc-20061117/ http://www.w3.org/TR/2006/WD-xproc-20060928/
Editors:
Norman Walsh, Sun Microsystems, Inc.
Alex Milowski, Invited expert

This document is also available in these non-normative formats: XML, Revision markup


Abstract

This specification describes the syntax and semantics of XProc: An XML Pipeline Language, a language for describing operations to be performed on XML documents.

An XML Pipeline specifies a sequence of operations to be performed on one or more XML documents. Pipelines generally accept one or more XML documents as input and produce one or more XML documents as output. Pipelines are made up of simple steps which perform atomic operations on XML documents and constructs similar to conditionals, loops and exception handlers which control which steps are executed.

Status of this Document

This document is an editor's draft that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was produced by the XML Processing Model Working Group which is part of the XML Activity. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This is a public Working Draft. This draft addresses many, but not all, of the design questions that were incomplete in previous drafts. The library of standard steps, both required and optional, is still being reviewed and considered. The Working Group continues to encourage feedback from potential users. A revision marks draft, with respect to the 5 April 2007 specification, has been provided, though it is not obviously of great value due to editorial reorganization of the material.

The most significant changes in this draft are: a new mechanism for dealing with parameters, new defaulting rules for primary input and output ports, and revisions to the standard step library.

Please send comments about this document to public-xml-processing-model-comments@w3.org (public archives are available).

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.


Table of Contents

Introduction
Pipeline Concepts
2.1 Steps
2.1.1 Step names
2.2 Inputs and Outputs
2.2.1 External Documents
2.3 Primary Inputs and Outputs
2.4 Options
2.5 Parameters
2.6 Connections
2.7 Environment
2.8 XPath Context
2.8.1 Processor XPath Context
2.8.2 Step XPath Context
2.8.3 XProc Extension Functions
Syntax Overview
3.1 XProc Namespaces
3.2 Scoping of Names
3.3 Global Attributes
3.4 Associating Documents with Ports
3.5 Documentation
3.6 Ignored namespaces
3.7 Extension attributes
3.8 Extension elements
3.9 Syntax Summaries
Steps
4.1 p:pipeline
4.2 p:for-each
4.2.1 XPath Context
4.3 p:viewport
4.3.1 XPath Context
4.4 p:choose
4.4.1 p:xpath-context
4.4.2 p:when
4.4.3 p:otherwise
4.5 p:group
4.6 p:try/p:catch
4.6.1 The Error Vocabulary
4.7 Other Steps
4.7.1 Syntactic Shortcut for Option Values
Other pipeline elements
5.1 p:input Element
5.1.1 Document Inputs
5.1.2 Parameter Inputs
5.2 p:iteration-source Element
5.3 p:viewport-source Element
5.4 p:output Element
5.5 p:log Element
5.6 p:serialization Element
5.7 Options and Parameters
5.7.1 p:option Element
5.7.2 p:parameter Element
5.7.3 Option and Parameter Namespaces
5.8 p:declare-step Element
5.9 p:pipeline-library Element
5.10 p:import Element
5.11 p:pipe Element
5.12 p:inline Element
5.13 p:document Element
5.14 p:empty Element
5.15 p:documentation Element
Errors
6.1 Static Errors
6.2 Dynamic Errors
6.3 Step Errors
Standard Step Library
7.1 Required Steps
7.1.1 Add Attribute
7.1.2 Add xml:base
7.1.3 Count
7.1.4 Delete
7.1.5 Directory List
7.1.6 Equal
7.1.7 Error
7.1.8 Escape Markup
7.1.9 HTTP Request
7.1.10 Identity
7.1.11 Insert
7.1.12 Label Elements
7.1.13 Load
7.1.14 Make Absolute URIs
7.1.15 Namespace Rename
7.1.16 Parameters
7.1.17 Rename
7.1.18 Replace
7.1.19 Set Attributes
7.1.20 Sink
7.1.21 Split Sequence
7.1.22 String Replace
7.1.23 Store
7.1.24 Unescape Markup
7.1.25 Unwrap
7.1.26 Wrap
7.1.27 Wrap Sequence
7.1.28 XInclude
7.1.29 XSLT
7.2 Optional Steps
7.2.1 Relax NG Validate
7.2.2 Schematron Validate
7.2.3 XML Schema Validate
7.2.4 XSLT 2.0
7.2.5 XSL Formatter
7.2.6 XQuery 1.0
7.3 Serialization Options

Appendices

Conformance
A.1 Implementation-defined features
A.2 Implementation-dependent features
References
The XProc Media Type
C.1 Registration of MIME media type application/xproc+xml
C.2 Fragment Identifiers
Glossary
Pipeline Language Summary

1 Introduction

An XML Pipeline specifies a sequence of operations to be performed on a collection of XML input documents. Pipelines take zero or more XML documents as their input and produce zero or more XML documents as their output.

A pipeline consists of steps. Like pipelines, steps take zero or more XML documents as their inputs and produce zero or more XML documents as their outputs. The inputs to a step come from the web, from the pipeline document, from the inputs to the pipeline itself, or from the outputs of other steps in the pipeline. The outputs from a step are consumed by other steps, are outputs of the pipeline as a whole, or are discarded.

There are two kinds of steps: atomic steps and compound steps. Atomic steps carry out single operations and have no substructure as far as the pipeline is concerned, whereas compound steps control the execution of other steps, which they include in the form of one or more subpipelines.

This specification defines a standard library, Section 7, “Standard Step Library”, of steps. Pipeline implementations may support additional types of steps as well.

Figure 1, “A simple, linear XInclude/Validate pipeline” is a graphical representation of a simple pipeline that performs XInclude processing and validation on a document.

A simple, linear XInclude/Validate pipeline
Figure 1. A simple, linear XInclude/Validate pipeline

This is a pipeline that consists of two atomic steps, XInclude and Validate. The pipeline itself has two inputs, “source” (a source document) and “schemas” (a list of W3C XML Schemas). How inputs are connected to XML documents outside the pipeline is implementation-defined. The XInclude step reads the pipeline input “source” and produces a result document. The Validate step reads the pipeline input “schemas” and the output from the XInclude step and produces a result document. The result of the validation, “result”, is the result of the pipeline. How pipeline outputs are connected to XML documents outside the pipeline is implementation-defined.

The pipeline document for this pipeline is shown in Example 1, “A simple, linear XInclude/Validate pipeline”.

Example 1. A simple, linear XInclude/Validate pipeline
<p:pipeline name="pipeline" xmlns:p="http://www.w3.org/2007/03/xproc">
  <p:input port="source" primary="true"/>
  <p:input port="schemas" sequence="true"/>
  <p:output port="result">
    <p:pipe step="validated" port="result"/>
  </p:output>

  <p:xinclude name="included">
    <p:input port="source">
      <p:pipe step="pipeline" port="source"/>
    </p:input>
  </p:xinclude>

  <p:validate-xml-schema name="validated">
    <p:input port="source">
      <p:pipe step="included" port="result"/>
    </p:input>
    <p:input port="schema">
      <p:pipe step="pipeline" port="schemas"/>
    </p:input>
  </p:validate-xml-schema>
</p:pipeline>

The example in Example 1, “A simple, linear XInclude/Validate pipeline” is very verbose. It makes all of the connections seen in the figure explicit. In practice, pipelines do not have to be this verbose. XProc supports defaults for many common cases. The same pipeline, using XProc defaults, is shown in Example 2, “A simple, linear XInclude/Validate pipeline (simplified)”.

Example 2. A simple, linear XInclude/Validate pipeline (simplified)
<p:pipeline name="pipeline" xmlns:p="http://www.w3.org/2007/03/xproc">
  <p:input port="source" primary="true"/>
  <p:input port="schemas" sequence="true"/>

  <p:xinclude/>

  <p:validate-xml-schema>
    <p:input port="schema">
      <p:pipe step="pipeline" port="schemas"/>
    </p:input>
  </p:validate-xml-schema>
</p:pipeline>

Figure 2, “A validate and transform pipeline” is a more complex example: it performs schema validation with an appropriate schema and then styles the validated document.

A validate and transform pipeline
Figure 2. A validate and transform pipeline

The heart of this example is the conditional. The “choose” step evaluates an XPath expression over a test document. Based on the result of that expression, one or another branch is run. In this example, each branch consists of a single validate step.

Example 3. A validate and transform pipeline
<p:pipeline xmlns:p="http://www.w3.org/2007/03/xproc">
  <p:input port="source"/>

  <p:choose>
    <p:when test="/*[@version &lt; 2.0]">
      <p:validate-xml-schema name="val1">
        <p:input port="schema">
          <p:document href="v1schema.xsd"/>
        </p:input>
      </p:validate-xml-schema>
    </p:when>

    <p:otherwise>
      <p:validate-xml-schema name="val2">
        <p:input port="schema">
          <p:document href="v2schema.xsd"/>
        </p:input>
      </p:validate-xml-schema>
    </p:otherwise>
  </p:choose>

  <p:xslt name="xform">
    <p:input port="stylesheet">
      <p:document href="stylesheet.xsl"/>
    </p:input>
  </p:xslt>
</p:pipeline>

This example, like the preceding, relies on XProc defaults for simplicity. It is always valid to write the fully explicit form if you prefer.

2 Pipeline Concepts

[Definition: A pipeline is a set of connected steps, outputs flowing into inputs, without any loops (no step can read its own output, directly or indirectly).] A pipeline is itself a step and must satisfy the constraints on steps.

The result of evaluating a pipeline is the result of evaluating the steps that it contains, in the order determined by the connections between them. A pipeline must behave as if it evaluated each step each time it occurs. Unless otherwise indicated, implementations must not assume that steps are functional (that is, that their outputs depend only on their explicit inputs, options, and parameters) or side-effect free.

2.1 Steps

[Definition: A step is the basic computational unit of a pipeline.] All steps have a name; if the pipeline author does not provide a name for a step, a default name is manufactured automatically.

Steps are either atomic or compound. [Definition: An atomic step is a step that performs a unit of XML processing, such as XInclude or transformation, and has no internal subpipeline.] Atomic steps carry out fundamental XML operations and can perform arbitrary amounts of computation, but they are indivisible. An XSLT step, for example, performs XSLT processing; an XML Schema Validation step validates one input with respect to some set of XML Schemas, etc.

There are many types of atomic steps. The standard library of atomic steps is described in Section 7, “Standard Step Library”, but implementations may provide others as well. What additional step types, if any, are provided is implementation defined. Each use, or instance, of an atomic step invokes the processing defined by that type of step. A pipeline may contain instances of many types of steps and many instances of the same type of step.

Compound steps, on the other hand, control and organize the flow of documents through a pipeline, reconstructing familiar programming language functionality such as conditionals, iterators and exception handling. They contain other steps, whose evaluation they control.

[Definition: A compound step is a step that contains one or more subpipelines. That is, a compound step differs from an atomic step in that its semantics are at least partially determined by the steps that it contains.] Every compound step contains one or more subpipelines. [Definition: The steps that occur directly inside a compound step are called contained steps.] [Definition: A compound step which immediately contains another step is called its container.]

This simple distinction between atomic and compound steps is occasionally stretched. The immediate children of some compound steps, e.g. p:choose and p:try, are special. In the case of p:choose, the p:when and p:otherwise elements serve as wrappers around different pipelines at most one of which will be processed. In the case of p:try, the p:catch element is a wrapper around a subpipeline that will only be processed if the initial p:group fails. Acknowledging this slight irregularity, we nevertheless treat all compound steps as if they directly contained one or more subpipelines.

[Definition: The steps (and the connections between them) within a compound step form a subpipeline.] [Definition: The last step in a subpipeline is the last step in document order within its container. ]

subpipeline = (p:for-each|p:viewport|p:choose|p:group|p:try|pfx:other-step|p:documentation|ipfx:ignored)*

A compound step can contain one or more subpipelines and it determines how and which of its subpipelines are evaluated.

Note

A p:pipeline, because it defines a subpipeline that can be called from other pipelines, has a somewhat dual nature with respect to the atomic vs. compound distinction. A p:pipeline is a compound step. When it is invoked by name from some other pipeline, its invocation is an atomic step. The “type” of the atomic step is determined by the p:pipeline that defines it.

Steps have “ports” into which inputs and outputs are connected or “bound”. Each step has a number of input ports and a number of output ports; a step can have zero input ports and/or zero output ports. (All steps have an implicit output port for reporting errors that must not be declared.) The names of all ports on each step must be unique on that step (you can't have two input ports named “source”, nor can you have an input port named “schema” and an output port named “schema”).

Steps have any number of options, all with unique names. A step can have zero options.

Steps have parameter input ports, on which parameters can be passed. The parameters passed on a particular parameter input port must be uniquely named. If multiple parameters with the same name are used, only one of the values will actually be available to the step. A step can have zero parameter input ports, and each parameter port can have zero parameters passed on it.

2.1.1 Step names

The name attribute on any step can be used to give it a name. The name must be unique within its scope, see Section 3.2, “Scoping of Names”.

If the pipeline author does not provide an explicit name, the processor manufactures a default name. All default names are of the form “!n” where “n” is the ordinal number of the step, considering all steps in document order. For example, consider the pipeline in Example 3, “A validate and transform pipeline”. The p:pipeline step has no name, so it gets the default name “!1”; the p:choose gets the name “!2”; the first p:when gets the name “!3”, etc. If the p:choose had had a name, it would not have received a default name, but it would still have been counted and its first p:when would still have been “!3”.

Providing every step in the pipeline with an interoperable name has several benefits:

  1. It provides a simple mechanism for identifying all steps from outside the pipeline, see Appendix C, The XProc Media Type.

  2. It allows implementors to refer to all steps in an interoperable fashion, for example, in error messages.

  3. Pragmatically, we say that readable ports are identified by a step name/port name pair. By manufacturing names for otherwise anonymous steps, we include implicit bindings without changing our model.

In a valid pipeline that runs successfully to completion, the manufactured names aren't visible (except perhaps in debugging or logging output).

Note

The format for defaulted names does not conform to the requirements of an NCName. This is an explicit design decision; it prevents pipelines from using the defaulted names on p:pipe elements. If an explicit connection is required, the pipeline author must provide an explicit name for the step.

2.2 Inputs and Outputs

Although some steps can read and write non-XML resources, what flows between steps through input ports and output ports are exclusively XML documents or sequences of XML documents. Each XML document (or document in a sequence) must conceptually be an [Infoset] with a Document Information Item at its root. The inputs and outputs can be implemented as sequences of characters, events, or object models, or any other representation the implementation chooses.

It is a dynamic error (err:XD0001) if a non-XML resource is produced on a step output or arrives on a step input.

An implementation may make it possible for a step to produce non-XML output (through channels other than a named output port)—for example, writing a PDF document to a URI—but that output cannot flow through the pipeline. Similarly, one can imagine a step that takes no pipeline inputs, reads a non-XML file from a URI, and produces an XML output. But the non-XML file cannot arrive on an input port to a step.

The common case is that each step has one or more inputs and one or more outputs. Figure 3, “An atomic step” illustrates symbolically an atomic step with two inputs and one output.

An atomic step with two inputs and one output
Figure 3. An atomic step

All atomic steps are defined by a p:declare-step. The declaration of an atomic step defines the input ports, output ports, and options of all steps of that type. For example, every p:xslt step has two inputs, named “source” and “stylesheet”, and one output named “result” and the same set of options.

The situation is slightly more complicated for compound steps because they don't have separate declarations; each instance of a compound step serves as its own declaration. Compound steps don't have declared inputs, but they do have declared outputs, and unlike atomic steps, on compound steps, the number and names of the outputs can be different on each instance of the step.

Figure 4, “A compound step” illustrates symbolically a compound step with one output. As you can see from the diagram, the output from the compound step comes from one of the outputs of the subpipeline within the step.

A compound step with two inputs and one output
Figure 4. A compound step

[Definition: The input ports declared on a step are its declared inputs.] [Definition: The output ports declared on a step are its declared outputs.] When a step is used in a pipeline, it is connected to other steps through its inputs and outputs.

When a step is used, all of the declared inputs of the step must be connected. Each input can be connected to:

  • The output port of some other step.

  • A fixed, inline document or sequence of documents.

  • A document read from a URI.

  • One of the inputs declared on one of its ancestors.

  • A special port provided by an ancestor compound step, for example, “current” in a p:for-each or p:viewport.

When an input accepts a sequence of documents, the documents can come from any combination of these locations.

The declared outputs of a step may be connected to:

  • The input port of some other step.

  • One of the outputs declared on its container.

The primary output port of a step must be connected, but other outputs can remain unconnected. Any documents produced on an unconnected output port are discarded.

Output ports on compound steps have a dual nature: from the perspective of the compound step's siblings, its outputs are just ordinary outputs and must be connected as described above. From the perspective of the compound step itself, they are inputs into which something must be connected.

Within a compound step, the declared outputs of the step can be connected to:

  • The output port of some contained step.

  • A fixed, inline document or sequence of documents.

  • A document read from a URI.

Each input and output is declared to accept or produce either a single document or a sequence of documents. It is not an error to connect a port that is declared to produce a sequence of documents to a port that is declared to accept only a single document. It is, however, an error if the former step actually produces more than one document at run time.

[Definition: The signature of a step is the set of inputs, outputs, and options that it is declared to accept.] Each atomic step (e.g. XSLT or XInclude) has a fixed signature, declared globally or built-in, which all its instances share, whereas each compound step has its own implicit signature.

[Definition: A step matches its signature if and only if it specifies an input for each declared input, it specifies no inputs that are not declared, it specifies an option for each option that is declared to be required, and it specifies no options that are not declared.] In other words, every input and required option must be specified and only inputs and options that are declared may be specified. Options that aren't required do not have to be specified.

Steps may also produce error, warning, and informative messages. These messages appear on a special “error output” port. The error output port is only bound to an input in the catch clause of a try/catch. Outside of a try/catch, the disposition of error messages is implementation-dependent.

2.2.1 External Documents

It's common for some of the documents used in processing a pipeline to be read from URIs. Sometimes this occurs directly, for example with a p:document element. Sometimes it occurs indirectly, for example if an implementation allows the URI of a pipeline input to be specified on the command line or if an p:xslt step encounters an xsl:import in the stylesheet that it is processing. It's also common for some of the documents produced in processing a pipeline to be written to locations which have, or at least could have, a URI.

The process of dereferencing a URI to retrieve a document is often more interesting than it seems at first. On the web, it may involve caches, proxies, and various forms of indirection. Resolving a URI locally may involve resolvers of various sorts and possibly appeal to implementation dependent mechanisms such as catalog files.

In XProc, the situation is made even more interesting by the fact that many intermediate results produced by steps in the pipeline have base URIs.Whether or not (and when and how) the intermediate results that pass between steps are ever written to a filesystem is implementation dependent.

In Version 1.0 of XProc, how (or if) implementers provide local resolution mechanisms and how (or if) they provide access to intermediate results by URI is implementation-defined.

Note

On the one hand, this is a somewhat unsatisfying state of affairs because it leaves room for interoperability problems. On the other, it is not expected to cause such problems very often in practice.

If these problems arise in practice, implementers are encouraged to use the existing extension mechanisms to give users the control needed to circumvent them. Should such mechanisms become widespread, a standard mechanism could be added in some future version of the language.

2.3 Primary Inputs and Outputs

As a convenience for pipeline authors, each step may have one input port designated as the primary input port and one output port designated as the primary output port.

[Definition: If a step has a document input port which is explicitly marked “primary='true'”, or if it has exactly one document input port and that port is not explicitly marked “primary='false'”, then that input port is the primary input port of the step.] If a step has a single input port and that port is explicitly marked “primary='false'”, or if a step has more than one input port and none is explicitly marked as the primary, then the primary input port of that step is undefined.

[Definition: If a step has a document output port which is explicitly marked “primary='true'”, or if it has exactly one document output port and that port is not explicitly marked “primary='false'”, then that output port is the primary output port of the step.] If a step has a single output port and that port is explicitly marked “primary='false'”, or if a step has more than one output port and none is explicitly marked as the primary, then the primary output port of that step is undefined.

The special significance of primary input and output ports is that they are connected automatically by the processor if no explicit binding is given. Generally speaking, if two steps appear sequentially in a subpipeline, then the primary output of the first step will automatically be connected to the primary input of the second.

Additionally, if a p:pipeline has no declared inputs and the first step in its subpipeline has an unbound primary input, then an implicit primary input port (named “source”) will be added to the p:pipeline (and consequently bound to the first step's primary input port). If a compound step has no declared outputs and the last step in its subpipeline has an unbound primary output, then an implicit primary output port (named “result”) will be added to the compound step (and consequently the last step's primary output will be bound to it).

The practical consequence of these rules is that straightforward, linear pipelines are much simpler to read, write, and understand. The following pipeline has a single input which is transformed by the XSLT step; the result of that XSLT step is the result of the pipeline:

<p:pipeline xmlns:p="http://www.w3.org/2007/03/xproc">
<p:xslt>
  <p:input port="stylesheet">
    <p:document href="docbook.xsl"/>
  </p:input>
</p:xslt>
</p:pipeline>

It is semantically equivalent to this pipeline:

<p:pipeline name="main" xmlns:p="http://www.w3.org/2007/03/xproc">
<p:input port="source"/>
<p:input port="parameters" kind="parameter"/>
<p:output port="result">
  <p:pipe step="transform" port="result"/>
</p:output>

<p:xslt name="transform">
  <p:input port="source">
    <p:pipe step="main" port="source"/>
  </p:input>
  <p:input port="stylesheet">
    <p:document href="docbook.xsl"/>
  </p:input>
  <p:input port="parameters">
    <p:pipe step="main" port="parameters"/>
  </p:input>
</p:xslt>

</p:pipeline>

(Parameter input ports are a special case discussed in Section 2.5, “Parameters”.)

2.4 Options

Some steps accept options. Options are name/value pairs.

[Definition: An option is a name/value pair where the name is an expanded name and the value must be a string.] If a document, node, or other value is given, its [XPath 1.0] string value is computed and that string is used.

[Definition: The options declared on a step are its declared options.] All of the options specified on an atomic step must have been declared. Option names are always expressed as literal values, pipelines cannot construct option names dynamically.

[Definition: The options on a step which have specified values, either because a p:option element specifies a value or because the declaration included a default value, are its specified options.]

2.5 Parameters

Some steps accept parameters. Parameters are name/value pairs.

[Definition: A parameter is a name/value pair where the name is an expanded name and the value must be a string.] If a document, node, or other value is given, its [XPath 1.0] string value is computed and that string is used.

Unlike options, which have names known in advance to the pipeline, parameters are not declared and their names may be unknown to the pipeline author. Pipelines can dynamically construct sets of parameters. Steps can read dynamically constructed sets on parameter input ports.

[Definition: A parameter input port is a distinguished kind of input port which accepts (only) dynamically constructed parameter name/value pairs.] See Section 5.1.2, “Parameter Inputs”.

Analogous to primary input ports, steps that have parameter inputs may designate at most one parameter input port as a primary parameter input port.

[Definition: If a step has a parameter input port which is explicitly marked “primary='true'”, or if it has exactly one parameter input port and that port is not explicitly marked “primary='false'”, then that parameter input port is the primary parameter input port of the step.] If a step has a single parameter input port and that port is explicitly marked “primary='false'”, or if a step has more than one parameter input port and none is explicitly marked as the primary, then the primary parameter input port of that step is undefined.

Additionally, if a p:pipeline does not declare any parameter input ports, but contains a step which has a primary parameter input port, then an implicit primary parameter input port (named “parameters”) will be added to the pipeline. (If the pipeline declares an ordinary input named “parameters”, the implicit primary parameter input port will be named “parameters1”. If that's not available, then “parameters2”, etc. until an available name is found.)

How an implementation maps parameters specified to the application, or through some API, to parameters accepted by the p:pipeline is implementation-defined.

2.6 Connections

Steps are connected together by their input ports and output ports. It is a static error (err:XS0001) if there are any loops in the connections between steps: no step can be connected to itself nor can there be any sequence of connections through other steps that leads back to itself.

2.7 Environment

[Definition: The environment of a step is the static information available to each instance of a step in a pipeline.]

The environment consists of:

  1. A set of readable ports. [Definition: The readable ports are the step name/output port name pairs that are visible to the step.] Inputs and outputs can only be connected to readable ports.

  2. A set of in-scope options. [Definition: The in-scope options are the set of options that are visible to a step.] All of the in-scope options are available to the processor for computing option and parameter values. The actual options passed to a step are those that are declared for a step of its type and that have values either provided explicitly with p:option elements on the step or as defaults in the declaration of the step type.

  3. A default readable port. [Definition: The default readable port, which may be undefined, is a specific step name/port name pair from the set of readable ports.]

[Definition: The empty environment contains no readable ports, no in-scope options, and an undefined default readable port. ]

Unless otherwise specified, the environment of a contained step is its inherited environment. [Definition: The inherited environment of a contained step is an environment that is the same as the environment of its container with the standard modifications. ]

The standard modifications made to an inherited environment are:

  • All of the specified options of the container are added to the in-scope options. The value of any option in the environment with the same name as one of the options specified on the container is shadowed by the new value.

    In other words, steps can access the most recently specified value of all of the options specified on any ancestor step.

  • The declared inputs of the container are added to the readable ports.

    In other words, contained steps can see the inputs to their container.

  • The union of all the declared outputs of all of the step's contained steps are added to the readable ports.

    In other words, sibling steps can see each other's outputs in addition to the outputs visible to their container.

  • If there is a preceding sibling step element:

  • If there is not a preceding sibling step element, the default readable port is the primary input port of the container, if it has one, otherwise the default readable port is unchanged.

A step with no parent inherits the empty environment.

2.8 XPath Context

XProc uses [XPath 1.0] as an expression language. XPath expressions can occur in several places: on compound steps, in the expressions used to compute option and parameter values, and in values passed to atomic steps.

Broadly, these can be divided into two classes: expressions evaluated by the XProc processor and expressions evaluated by the implementations of individual steps.

This distinction can be seen in the following example:

<p:option name="home" value="http://example.com/docs"/>

<p:load name="read-from-home">
  <p:option name="href" select="concat($home,'/document.xml')"/>
</p:load>

<p:split-sequence name="select-chapters">
  <p:input port="source" select="//section"/>
  <p:option name="test" value="@role='chapter'"/>
</p:split-sequence>

The href option of the p:load step step is evaluated by the XProc processor. The actual href option received by the step is simply the string literal “http://example.com/docs/document.xml”. (The selection on the source input of the select-chapters step is also evaluated by the XProc processor.)

Conversely, the XPath expression “@role='chapter'” is passed literally to the test option on the p:split-sequence step. That's because the nature of the p:split-sequence is that it evaluates the expression. Only some options on some steps expect XPath expressions.

The XProc processor evaluates all of the XPath expressions in select attributes on steps, options, parameters, and inputs and in test attributes on p:when steps. (XPath expressions in value attributes are passed literally to the step for evaluation.)

2.8.1 Processor XPath Context

When the XProc processor evaluates an XPath expression, unless otherwise indicated by a particular step, it does so with the following context:

context node

The document node of a document. The document is either specified with a binding or is taken from the default readable port. It is a dynamic error (err:XD0008) if a document sequence appears where a document to be used as the context node is expected.

If there is no binding and there is no default readable port then the context node is an empty document node.

context position and context size

The context position and context size are both “1”.

variable bindings

The in-scope options are available as variables.

function library

The [XPath 1.0] core function library and the XProc extension functions.

in-scope namespaces

The namespace bindings in-scope on the element where the expression occurred.

2.8.2 Step XPath Context

When a step evaluates an XPath expression, it does so with the following context:

context node

The document node that appears on the primary input port of the step, unless otherwise specified by the step.

context position and context size

The position and size are both “1”, unless otherwise specified by the step.

variable bindings

None, unless otherwise specified by the step.

function library

The [XPath 1.0] core function library, unless otherwise specified by the step.

in-scope namespaces

The set of namespace bindings provided by the XProc processor. The processor computes this set of bindings by taking a union of the bindings on the step element itself as well as the bindings on any of the options and parameters used in computing values for the step (see Section 5.7.3, “Option and Parameter Namespaces”).

The results of computing the union of namespaces in the presence of conflicting declarations for a particular prefix are implementation-dependent.

2.8.3 XProc Extension Functions

The XProc processor must support a few additional functions in XPath expressions evaluated by the processor.

2.8.3.1 System Properties

XPath expressions within a pipeline document can interrogate the processor for information about the current state of the pipeline. Various aspects of the processor are exposed through the p:system-property function in the pipeline namespace:

Function: String p:system-property(String property)

The property string must have the form of a QName; the QName is expanded into a name using the namespace declarations in scope for the expression. The p:system-property function returns the string representing the value of the system property identified by the QName. If there is no such property, the empty string must be returned.

Implementations must provide the following system properties, which are all in the XProc namespace:

p:episode

Returns a string which should be unique for each invocation of the pipeline processor.

The unique identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name.

p:product-name

Returns a string containing the name of the implementation, as defined by the implementer. This should normally remain constant >From one release of the product to the next. It should also be constant across platforms in cases where the same source code is used to produce compatible products for multiple execution platforms.

p:product-version

Returns a string identifying the version of the implementation, as defined by the implementer. This should normally vary from one release of the product to the next, and at the discretion of the implementer it may also vary across different execution platforms.

p:vendor

Returns a string which identifies the vendor of the processor.

p:vendor-uri

Returns a URI which identifies the vendor of the processor. Often, this is the URI of the vendor's web site.

p:version

Returns the version of XProc implemented by the processor; for processors implementing the version of XProc specified by this document, the value is “1.0”. The value of the version attribute is a token (i.e., an xs:token per [W3C XML Schema: Part 2]).

2.8.3.2 Step Available

The p:step-available function reports whether or not a particular type of step is understood by the processor.

Function: Boolean p:step-available(String step-type)

The step-type string must have the form of a QName; the QName is expanded into a name using the namespace declarations in scope for the expression. The p:step-available function returns true if and only if the processor knows how to evaluate steps of the specified type.

2.8.3.3 Iteration Position

In the context of a p:for-each or a p:viewport, the p:iteration-position function reports the position of the document being processed in the sequence of documents that will be processed. In the context of other standard XProc compound steps, it returns 1.

Function: Integer p:iteration-position()

In the context of an extension compound step, the value returned by p:iteration-position is implementation-defined.

2.8.3.4 Iteration Size

In the context of a p:for-each or a p:viewport, the p:iteration-size function reports the number of documents in the sequence of documents that will be processed. In the context of other standard XProc compound steps, it returns 1.

Function: Integer p:iteration-size()

In the context of an extension compound step, the value returned by p:iteration-size is implementation-defined.

3 Syntax Overview

This section describes the normative XML syntax of XProc. This syntax is sufficient to represent all the aspects of a pipeline, as set out in the preceding sections. [Definition: XProc is intended to work equally well with [XML 1.0] and [XML 1.1]. Unless otherwise noted, the term “XML” refers equally to both versions.] [Definition: Unless otherwise noted, the term Namespaces in XML refers equally to [Namespaces 1.0] and [Namespaces 1.1].] Support for pipeline documents written in XML 1.1 and pipeline inputs and outputs that use XML 1.1 is implementation defined.

Elements in a pipeline document represent the pipeline, the steps it contains, the connections between those steps, the steps and connections contained within them, and so on. Each step is represented by an element; a combination of elements and attributes specify how the inputs and outputs of each step are connected and how options and parameters are passed.

Conceptually, we can speak of steps as objects that have inputs and outputs, that are connected together and which may contain additional steps. Syntactically, we need a mechanism for specifying these relationships.

Containment is represented naturally using nesting of XML elements. If a particular element identifies a compound step then the step elements that are its immediate children form its subpipeline.

The connections between steps are expressed using names and references to those names.

Six kinds of things are named in XProc:

  1. Step types,
  2. Steps,
  3. Input ports,
  4. Output ports,
  5. Options, and
  6. Parameters

3.1 XProc Namespaces

The XML syntax for XProc uses three namespaces:

http://www.w3.org/ns/xproc

The namespace of the XProc XML vocabulary described by this specification; by convention, the namespace prefix “p:” is used for this namespace.

http://www.w3.org/ns/xproc-step

The namespace used for documents that are inputs to and outputs >From several standard and optional steps described in this specification. Some steps, such as p:http-request and p:store, have defined input or output vocabularies. We use this namespace for all of those documents. The conventional prefix “c:” is used for this namespace.

http://www.w3.org/ns/xproc-error

The namespace used for errors. The conventional prefix “err:” is used for this namespace.

Note

The namespace URIs have been changed to their final location for this and future drafts, however, the Working Group, reserves the right to make changes at will until such time as this document reaches Recommendation status.

3.2 Scoping of Names

The scope of the names of the step types is the union of all the pipelines and pipeline libraries available directly or via p:import.

Step types are:

All the step types in a pipeline must have unique names: it is a static error (err:XS0036) if any step type name is built-in and/or declared or defined more than once in the same scope.

The scope of the names of the steps themselves is determined by the environment of each step. In general, the name of a step, the names of its sibling steps, the names of any steps that it contains directly, the names of its ancestors, and the names of its ancestor's siblings are all in the same scope. All the named steps in the same scope must have unique names: it is a static error (err:XS0002) if two steps with the same name appear in the same scope.

The scope of an input or output port name is the step on which it is defined. The names of all the ports on any step must be unique.

Taken together, these uniqueness constraints guarantee that the combination of a step name and a port name uniquely identifies exactly one port on exactly one in-scope step.

The scope of option names is the step on which they occur and the descendants of that step. The names of all of the options specified on a step must be unique. If a step specifies a value for an option with the same name as some option specified on one of its ancestors, the new value shadows the previous value on the current step and its descendants.

Parameter names are not scoped; they are distinct on each step.

3.3 Global Attributes

The following attributes may appear on any element in a pipeline:

  • The attribute xml:id with the semantics outlined in [xml:id].

  • The attribute xml:base with the semantics outlined in [XML Base].

3.4 Associating Documents with Ports

[Definition: A binding associates an input or output port with some data source.] A document or a sequence of documents can be bound to a port in four ways: by source, by URI, by providing an inline document, or by making it explicitly empty. Each of these mechanisms is allowed on the p:input, p:output, p:xpath-context, p:iteration-source, and p:viewport-source elements.

Specified by URI

[Definition: A document is specified by URI if it is referenced with a URI.] The href attribute on the p:document element is used to refer to documents by URI.

In this example, the input to the p:identity step named “otherstep” comes from “http://example.com/input.xml”.

<p:identity name="otherstep">
  <p:input port="source">
    <p:document href="http://example.com/input.xml"/>
  </p:input>
</p:identity>

It is a dynamic error (err:XD0002) if the processor attempts to retrieve the URI specified on a p:document and fails. (For example, if the resource does not exist or is not accessible with the user's authentication credentials.)

Specified by source

[Definition: A document is specified by source if it references a specific port on another step.] The step and port attributes on the p:pipe element are used for this purpose.

In this example, the “document” input to the p:xinclude step named “expand” comes from the “result” port of the step named “otherstep”.

<p:xinclude name="expand">
  <p:input port="source">
    <p:pipe step="otherstep" port="result"/>
  </p:input>
</p:xinclude>

When a p:pipe is used, the specified port must be in the readable ports of the current environment. It is a static error (err:XS0003) if the port specified by a p:pipe is not in the readable ports of the environment.

Specified inline

[Definition: An inline document is specified directly in the body of the element that binds it.] The content of the p:inline element is used for this purpose.

In this example, the “stylesheet” input to the XSLT step named “xform” comes from the content of the p:input element itself.

<p:xslt name="xform">
  <p:input port="stylesheet">
    <p:inline>
      <xsl:stylesheet version="1.0">
        ...
      </xsl:stylesheet>
    </p:inline>
  </p:input>
</p:xslt>

Inline documents are considered “quoted”. The pipeline processor passes them literally to the port, even if they contain elements >From the XProc namespace or ignored namespaces that would have other semantics outside of the p:inline.

Specified explicitly empty

[Definition: An empty sequence of documents is specified with the p:empty element.]

In this example, the “source” input to the XSLT 2.0 step named “generate” is explicitly empty:

<p:xslt2 name="generate">
  <p:input port="source">
    <p:empty/>
  </p:input>
  <p:input port="stylesheet">
    <p:inline>
      <xsl:stylesheet version="2.0">
        ...
      </xsl:stylesheet>
    </p:inline>
  </p:input>
  <p:option name="template-name" value="someName"/>
</p:xslt2>

If you omit the binding on a primary input port, a binding to the default readable port will be assumed. Making the binding explicitly empty guarantees that the binding will be to an empty sequence of documents.

It is inconsistent with the [XPath 1.0] specification to specify an empty binding as the context for evaluating an XPath expression. When an empty binding is specified for an XPath expression, an empty document node must be used instead as the context node.

Note that a p:input or p:output element may contain more than one p:pipe, p:document, or p:inline element. If more than one binding is provided, then the specified sequence of documents is made available on that port in the same order as the bindings.

3.5 Documentation

Pipeline authors may add documentation to their pipeline documents with the p:documentation element. Except when it appears as a descendant of p:inline, the p:documentation element is completely ignored by pipeline processors, it exists simply for documentation purposes. (If a p:documentation is provided as a descendant of p:inline, it has no special semantics, it is treated literally as part of the document to be provided on that port.)

Pipeline processors that inspect the contents of p:documentation elements and behave differently on the basis of what they find are not conformant. Processor extensions must be specified with extension elements.

3.6 Ignored namespaces

In order to facilitate extension elements, the processor can be instructed to ignore elements from selected namespaces. [Definition: Any element in an ignored namespace is an ignorable element.]

If a processor encounters an ignorable element as the child of a p:pipeline or p:pipeline-library then it behaves in an implementation-defined manner if it recognizes the element, otherwise it must behave as if the element (and its content) had not been present.

Syntactically, a pipeline author can specify the set of ignored namespaces with the ignore-prefixes attribute. This attribute can appear on the p:pipeline and p:pipeline-library elements.

The value of the ignore-prefixes attribute is a sequence of tokens, each of which must be the prefix of an in-scope namespace. It is a static error (err:XS0005) if any token specified in the prefix list is not the prefix of an in-scope namespace.

Ignored namespaces specified on a p:pipeline-library are inherited by pipelines that occur within that library.

It is a static error (err:XS0015) to specify as an ignored namespace the XProc namespace, the namespace of any imported p:pipeline, or any namespace in which an atomic step is declared.

3.7 Extension attributes

[Definition: An element from the XProc namespace may have any attribute not from the XProc namespace, provided that the expanded-QName of the attribute has a non-null namespace URI. Such an attribute is called an extension attribute.] Extension attributes are always allowed and do not have to be declared with ignored namespaces.

The presence of an extension attribute must not cause the connections between steps to differ from the connections that any other conformant XProc processor would produce. They must not cause the processor to fail to signal an error that a conformant processor is required to signal. This means that an extension attribute must not change the effect of any XProc element except to the extent that the effect is implementation-defined or implementation-dependent.

A processor which encounters an extension attribute that it does not recognize must behave as if the attribute was not present.

3.8 Extension elements

[Definition: An extension element is any element that is not in the XProc namespace and is not a step.] The presence of an extension element must not cause the connections between steps to differ from the connections that any other conformant XProc processor would produce. They must not cause the processor to fail to signal an error that a conformant processor is required to signal. This means that an extension element must not change the effect of any XProc element except to the extent that the effect is implementation-defined or implementation-dependent.

An element is only an extension element if it is an ignorable element that occurs as a direct child of a p:pipeline or p:pipeline-library.

In other words, elements in a subpipeline are interpreted as follows:

  1. In XProc namespace?
    1. Names a built-in compound step? Check against grammar, interpret per spec.
    2. Names a built-in atomic step? Check against grammar and built-in declaration, intepret per spec.
    3. Otherwise, error.
  2. Names a declared step type? Check against grammer and supplied step declaration, interpret per spec.
  3. Names a defined pipeline? Check against pipeline definition, interpret per spec.
  4. Is in ignorable namespace?
    1. Is a known extension? Process as appropriate.
    2. Otherwise, ignore.
  5. Otherwise, error.

3.9 Syntax Summaries

The description of each element in the pipeline namespace is accompanied by a syntactic summary that provides a quick overview of the element's syntax:

<p:some-element
  some-attribute? = some-type>
    (some |
     elements |
     allowed)*,
    other-elements?
</p:some-element>

For clarity of exposition, some attributes and elements are elided from the summaries:

[Definition: In the context of XProc, a QName is almost always a QName in the Namespaces in XML sense. Note, however, that p:option and p:parameter values can get their namespace declarations in a non-standard way (with p:namespaces) and QNames that have no prefix are always in no-namespace, irrespective of the default namespace.]

A number of errors apply generally:

If an XProc processor can determine statically that a dynamic error will always occur, it may report that error statically.

4 Steps

This section describes the core steps of XProc.

Every compound step in a pipeline has several parts: a set of inputs, a set of outputs, a set of options, a set of contained steps, and an environment.

Editorial Note

In previous drafts, inputs, outputs, and options occurred in a fixed order. In this draft, they may appear in any order (but before the contained steps). Is that problematic?

Except where otherwise noted, a compound step can have an arbitrary number of outputs, options, and contained steps.

It is a static error (err:XS0027) if a compound step has no contained steps.

4.1 p:pipeline

A pipeline is specified by the p:pipeline element. It encapsulates the behavior of a subpipeline. Its children declare the inputs, outputs, and options that the pipeline exposes and identify the steps in its subpipeline.

A pipeline can declare additional steps (e.g., ones that are provided by a particular implementation or in some implementation-defined way) and import other pipelines. If a pipeline has been imported, it may be invoked as a step within the pipeline that imported it.

<p:pipeline
  name? = NCName
  type? = QName
  ignore-prefixes? = prefix list>
    (p:input |
     p:output |
     p:option |
     p:import |
     p:declare-step |
     p:log |
     p:serialization)*,
    subpipeline
</p:pipeline>

Viewed from the outside, a p:pipeline is a black box which performs some calculation on its inputs and produces its outputs. From the pipeline author's perspective, the computation performed by the pipeline is described in terms of contained steps which read the pipeline's inputs and produce the pipeline's outputs.

The environment inherited by the contained steps of a p:pipeline is the empty environment with these modifications:

If the p:pipeline has a primary output port and that port has no binding, then it is bound to the primary output port of the last step in the subpipeline. It is a static error (err:XS0006) if the primary output port has no binding and the last step in the subpipeline does not have a primary output port.

There are two additional constraints on pipelines:

If the pipeline initially invoked by the processor has inputs or outputs, those ports are bound to documents outside of the pipeline in an implementation-defined manner.

If a pipeline has a type then that type may be used as the name of a step to invoke the pipeline. This most often occurs when the it has been imported into another pipeline, but pipelines may also invoke themselves recursively. If it does not have a type, then its name is used to invoke it as a step.

For pipelines that are part of a p:pipeline-library, see Section 5.9, “p:pipeline-library Element” for more details on how p:pipeline names are used to compute step names.

4.1.1 Example

A pipeline might accept a document and a stylesheet as input; perform XInclude, validation, and transformation; and produce the formatted document as its output.

Example 4. A Sample Pipeline Document
<p:pipeline name="pipeline" xmlns:p="http://www.w3.org/2007/03/xproc">
<p:input port="document" primary="true"/>
<p:input port="stylesheet"/>
<p:output port="result" primary="true"/>

<p:xinclude/>

<p:validate-xml-schema>
  <p:input port="schema">
    <p:document href="http://example.com/path/to/schema.xsd"/>
  </p:input>
</p:validate-xml-schema>

<p:xslt>
  <p:input port="stylesheet">
    <p:pipe step="pipeline" port="stylesheet"/>
  </p:input>
</p:xslt>

</p:pipeline>

4.2 p:for-each

A for-each is specified by the p:for-each element. It processes a sequence of documents, applying its subpipeline to each document in turn.

<p:for-each
  name? = NCName>
    (p:iteration-source?,
     (p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:for-each>

When a pipeline needs to process a sequence of documents using a subpipeline that only processes a single document, the p:for-each construct can be used as a wrapper around that subpipeline. The p:for-each will apply that subpipeline to each document in the sequence in turn.

The result of the p:for-each is a sequence of documents produced by processing each individual document in the input sequence. If the p:for-each has one or more output ports, what appears on each of those ports is the sequence of documents that is the concatenation of the sequence produced by each iteration of the loop on the port to which it is connected.

The p:iteration-source is an anonymous input: its binding provides a sequence of documents to the p:for-each step. If no iteration sequence is explicitly provided, then the iteration source is read from the default readable port.

A portion of each input document can be selected using the select attribute. If no selection is specified, the document node of each document is selected.

Each subtree selected by the p:for-each from each of the inputs that appear on the iteration source is wrapped in a document node and provided to the subpipeline.

The processor provides each document, one at a time, to the subpipeline represented by the children of the p:for-each on a port named current.

For each declared output, the processor collects all the documents that are produced for that output from all the iterations, in order, into a sequence. The result of the p:for-each on that output is that sequence of documents.

The environment inherited by the contained steps of a p:for-each is the inherited environment with these modifications:

If the p:for-each has a primary output port and that port has no binding, then it is bound to the primary output port of the last step in the subpipeline. It is a static error (err:XS0006) if the primary output port has no binding and the last step in the subpipeline does not have a primary output port.

4.2.1 XPath Context

Within a p:for-each, the p:iteration-position and p:iteration-size are taken from the sequence of documents that will be processed by the p:for-each. The total number of documents is the size; the ordinal value of the current document (the document appearing on the current port) is the position.

Note to implementers: in the case where no XPath expression that must be evaluated by the processor makes any reference to p:iteration-size, its value does not actually have to be calculated (and the entire input sequence does not, therefore, need to be buffered so that its size can be calculated before processing begins).

4.2.2 Example

A p:for-each might accept a sequence of chapters as its input, process each chapter in turn with XSLT, a step that accepts only a single input document, and produce a sequence of formatted chapters as its output.

Example 5. A Sample For-Each
<p:for-each name="chapters">
  <p:iteration-source select="//chapter"/>
  <p:output port="html-results">
    <p:pipe step="make-html" port="result"/>
  </p:output>
  <p:output port="fo-results">
    <p:pipe step="make-fo" port="result"/>
  </p:output>

  <p:xslt name="make-html">
    <p:input port="stylesheet">
      <p:document href="http://example.com/xsl/html.xsl"/>
    </p:input>
  </p:xslt>

  <p:xslt name="make-fo">
    <p:input port="source">
      <p:pipe step="chapters" port="current"/>
    </p:input>
    <p:input port="stylesheet">
      <p:document href="http://example.com/xsl/fo.xsl"/>
    </p:input>
  </p:xslt>
</p:for-each>

The //chapter elements of the document are selected. Each chapter is transformed into HTML and XSL Formatting Objects using an XSLT step. The resulting HTML and FO documents are aggregated together and appear on the html-results and fo-results ports, respectively, of the chapters step itself.

4.3 p:viewport

A viewport is specified by the p:viewport element. It processes a single document, applying its subpipeline to one or more subsections of the document.

<p:viewport
  name? = NCName
  match = XSLT Match pattern>
    ((p:viewport-source?,
      p:output?,
      p:log?,
      p:option*),
     subpipeline)
</p:viewport>

The result of the p:viewport is a copy of the original document with the selected subsections replaced by the results of applying the subpipeline to them.

The p:viewport-source is an anonymous input: its binding provides a single document to the p:viewport step. If no document is explicitly provided, then the viewport source is read from the default readable port.

The match attribute specifies an [XPath 1.0] expression that is a Pattern in [XSLT 1.0]. Each matching node in the source document is wrapped in a document node and provided to the viewport's subpipeline.

The processor provides each document, one at a time, to the subpipeline represented by the children of the p:viewport on a port named current.

What appears on the output from the p:viewport will be a copy of the input document where each matching node is replaced by the result of applying the subpipeline to the subtree rooted at that node.

It is a dynamic error (err:XD0003) if the viewport source does not provide exactly one document.

The environment inherited by the contained steps of a p:viewport is the inherited environment with these modifications:

If the p:viewport has a primary output port and that port has no binding, then it is bound to the primary output port of the last step in the subpipeline. It is a static error (err:XS0006) if the primary output port has no binding and the last step in the subpipeline does not have a primary output port.

4.3.1 XPath Context

Within a p:viewport, the p:iteration-position and p:iteration-size are taken from the sequence of documents that will be processed by the p:viewport. The total number of documents is the size; the ordinal value of the current document (the document appearing on the current port) is the position.

Note to implementers: in the case where no XPath expression that must be evaluated by the processor makes any reference to p:iteration-size, its value does not actually have to be calculated (and the entire input sequence does not, therefore, need to be buffered so that its size can be calculated before processing begins).

4.3.2 Example

A p:viewport might accept an XHTML document as its input, add an hr element at the beginning of all div elements that have the class value “chapter”, and return an XHTML document that is the same as the original except for that change.

Example 6. A Sample Viewport
<p:viewport match="h:div[@class='chapter']"
            xmlns:h="http://www.w3.org/1999/xhtml">
  <p:insert at-start="true">
    <p:input port="insertion">
      <p:inline>
        <hr xmlns="http://www.w3.org/1999/xhtml"/>
      </p:inline>
    </p:input>
  </p:insert>
</p:viewport>

</p:pipeline>

The nodes which match h:div[@class='chapter'] (according to the rules of [XSLT 1.0]) in the input document are selected. An hr is inserted as the first child of each h:div and the resulting version replaces the original h:div. The result of the whole step is a copy of the input document with a horizontal rule as the first child of each selected h:div.

4.4 p:choose

A choose is specified by the p:choose element. It selects exactly one of a list of alternative subpipelines based on the evaluation of [XPath 1.0] expressions.

<p:choose
  name? = NCName>
    (p:xpath-context?,
     p:when*,
     p:otherwise?)
</p:choose>

A p:choose has no inputs. It contains an arbitrary number of alternative subpipelines, exactly one of which will be evaluated.

The list of alternative subpipelines consists of zero or more subpipelines guarded by an XPath expression, followed optionally by a single default subpipeline.

The p:choose considers each subpipeline in turn and selects the first (and only the first) subpipeline for which the guard expression evaluates to true in its context. If there are no subpipelines for which the expression evaluates to true, the default subpipeline, if it was specified, is selected.

After a subpipeline is selected, it is evaluated as if only it had been present.

The result of the p:choose is the result of the selected subpipeline.

In order to ensure that the result of the p:choose is consistent irrespective of the subpipeline chosen, each subpipeline must declare the same number of outputs with the same names. If any of the subpipelines specifies a primary output port, each subpipeline must specify exactly the same output as primary. It is a static error (err:XS0007) if two subpipelines in a p:choose declare different outputs.

It is a dynamic error (err:XD0004) if no subpipeline is selected by the p:choose and no default is provided.

The p:choose can specify the context node against which the [XPath 1.0] expressions that occur on each branch are evaluated. The context node is specified as a binding for the p:xpath-context. If no binding is provided, the default p:xpath-context is the document on the default readable port.

Each conditional subpipeline is represented by a p:when element. The default branch is represented by a p:otherwise element.

4.4.1 p:xpath-context

An XPath context specifies the context against which an [XPath 1.0] expression will be evaluated for a p:when.

<p:xpath-context>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?
</p:xpath-context>

Only one binding is allowed and it works the same way that bindings work on a p:input. No select expression is allowed. It is a dynamic error (err:XD0005) if the xpath-context is bound to a sequence of documents.

If the context node is bound to p:empty, or is unbound and the default readable port is undefined, an empty document node is used instead as the context.

4.4.2 p:when

A when specifies one subpipeline guarded by a test expression.

<p:when
  name? = NCName
  test = XPath expression>
    (p:xpath-context?,
     (p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:when>

Each p:when branch of the p:choose has a test attribute which must contain an [XPath 1.0] expression. That XPath expression's effective boolean value is the guard expression for the subpipeline contained within that p:when.

It is a dynamic error (err:XD0020) if the value of the test attribute is not a valid XPath expression.

The p:when can specify a context node against which its test expression is to be evaluated. That context node is specified as a binding for the p:xpath-context. If no context is specified on the p:when, the context of the p:choose is used.

4.4.3 p:otherwise

An otherwise specifies the default branch; the subpipeline selected if no test expression on any preceding p:when evaluates to true.

<p:otherwise
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:otherwise>

4.4.4 Example

A p:choose might test the version attribute of the document element and validate with an appropriate schema.

Example 7. A Sample Choose
<p:choose name="version">
  <p:when test="/*[@version = 2]">
    <p:validate-xml-schema>
      <p:input port="schema">
        <p:document href="v2schema.xsd"/>
      </p:input>
    </p:validate-xml-schema>
  </p:when>

  <p:when test="/*[@version = 1]">
    <p:validate-xml-schema>
      <p:input port="schema">
        <p:document href="v1schema.xsd"/>
      </p:input>
    </p:validate-xml-schema>
  </p:when>

  <p:when test="/*[@version]">
    <p:identity/>
  </p:when>

  <p:otherwise>
    <p:output port="result">
      <!-- this output is necessary so that all the branches have
           the same outputs; it'll never really matter because
           we're just about to raise an error. -->
      <p:inline>
        <nop/>
      </p:inline>
    </p:output>
    <p:error code="NOVERSION"
             description="Required version attribute missing."/>
  </p:otherwise>
</p:choose>

4.5 p:group

A group is specified by the p:group element. It encapsulates the behavior of its subpipeline.

<p:group
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:group>

A p:group is a convenience wrapper for a collection of steps. The result of a p:group is the result of its subpipeline.

4.5.1 Example
Example 8. An Example Group
<p:group>
  <p:option name="db-key" value="some-long-string-of-nearly-random-characters"/>

  <p:choose>
    <p:when test="/config/output = 'fo'">
      <p:xslt>
        <p:parameter name="key" select="$db-key"/>
        <p:input port="stylesheet">
          <p:document href="fo.xsl"/>
        </p:input>
      </p:xslt>
    </p:when>
    <p:when test="/config/output = 'svg'">
      <p:xslt>
        <p:parameter name="key" select="$db-key"/>
        <p:input port="stylesheet">
          <p:document href="svg.xsl"/>
        </p:input>
      </p:xslt>
    </p:when>
    <p:otherwise>
      <p:xslt>
        <p:parameter name="key" select="$db-key"/>
        <p:input port="stylesheet">
          <p:document href="html.xsl"/>
        </p:input>
      </p:xslt>
    </p:otherwise>
  </p:choose>
</p:group>

4.6 p:try/p:catch

A try/catch is specified by the p:try element. It isolates a subpipeline, preventing any dynamic errors that arise within it from being exposed to the rest of the pipeline.

<p:try
  name? = NCName>
    (p:group,
     p:catch)
</p:try>

The p:group represents the initial subpipeline and the recovery (or “catch”) pipeline is identified with a p:catch element.

The p:try step evaluates the initial subpipeline and, if no errors occur, the results of that pipeline are the results of the step. However, if any errors occur, it abandons the first subpipeline, discarding any output that it might have generated, and evaluates the recovery subpipeline.

If the recovery subpipeline is evaluated, the results of the recovery subpipeline are the results of the p:try step. If the recovery subpipeline is evaluated and a step within that subpipeline fails, the p:try fails.

A pipeline author can cause an error to occur with the p:error step.

In order to ensure that the result of the p:try is consistent irrespective of whether the initial subpipeline provides its output or the recovery subpipeline does, both subpipelines must declare the same number of outputs with the same names. If either of the subpipelines specifies a primary output port, both subpipelines must specify exactly the same output as primary. It is a static error (err:XS0009) if the p:group and p:catch subpipelines declare different outputs.

The recovery subpipeline of a p:try is identified with a p:catch:

<p:catch
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:catch>

The environment inherited by the contained steps of the p:catch is the inherited environment with this modification:

What appears on the error port is an error document. The error document may contain messages generated by steps that were part of the initial subpipeline. Not all messages that appear are indicative of errors; for example, it is common for all xsl:message output from the XSLT component to appear on the error port. It is possible that the component which fails may not produce any messages at all. It is also possible that the failure of one component may cause others to fail so that there may be multiple failure messages in the document.

4.6.1 The Error Vocabulary

In general, it is very difficult to predict error behavior. Step failure may be catastrophic (programmer error), or it may be be the result of user error, resource failures, etc. Steps may detect more than one error, and the failure of one step may cause other steps to fail as well.

The p:try/p:catch mechanism gives pipeline authors the opportunity to process the errors that caused the p:try to fail. In order to facilitate some modicum of interoperability among processors, errors that are reported on the error port of a p:catch should conform to the format described here.

4.6.1.1 c:errors

The error vocabulary consists of a root element, c:errors which contains zero or more c:error elements.

<c:errors>
    c:error*
</c:errors>

4.6.1.2 c:error

Each specific error is represented by an c:error element:

<c:error
  name? = NCName
  type? = QName
  code? = QName
  href? = anyURI
  line? = integer
  column? = integer
  offset? = integer>
    (string |
     anyElement)*
</c:error>

The name and type attributes identify the name and type, respectively, of the step which failed.

The code is a QName which identifies the error. For steps which have defined error codes, this is an opportunity for the step to identify the error in a machine-processable fashion. Many steps omit this because they do not include the concept of errors identified by QNames.

If the error was caused by a specific document, or by the location of some erroneous construction in a specific document, the href, line, column, and offset attributes identify this location. Generally, the error location is identified either with line and column numbers or with an offset from the beginning of the document, but not usually both.

The content of the c:error element is any well-formed XML. Specific steps, or specific implementations, may provide more detail about the format of the content of an error message.

4.6.1.3 Error Example

Consider the following XSLT stylesheet:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="1.0">

<xsl:template match="/">
  <xsl:message terminate="yes">
    <xsl:text>This stylesheet is </xsl:text>
    <emph>pointless</emph>
    <xsl:text>.</xsl:text>
  </xsl:message>
</xsl:template>

</xsl:stylesheet>

If it was used in a step named “xform” in a p:try, the following error document might be produced:

<c:errors xmlns:c="http://www.w3.org/2007/03/xproc-step">
  <c:error name="xform" type="p:xslt"
             href="style.xsl" line="6">This stylesheet is <emph>pointless</emph>.</c:error>
</c:errors>

It is not an error for steps to generate non-standard error output as long as it is well-formed.

4.6.2 Example

A pipeline might attempt to process a document by dispatching it to some web service. If the web service succeeds, then those results are passed to the rest of the pipeline. However, if the web service cannot be contacted or reports an error, the p:catch step can provide some sort of default for the rest of the pipeline.

Example 9. An Example Try/Catch
<p:try>
  <p:group>
    <p:http-request>
      <p:input port="source">
        <p:inline>
          <c:http-request method="post" href="http://example.com/form-action">
            <c:entity-body content-type="application/x-www-form-urlencoded">
              <c:body>name=W3C&amp;spec=XProc</c:body>
            </c:entity-body>
          </c:http-request>
        </p:inline>
      </p:input>
    </p:http-request>
  </p:group>
  <p:catch>
    <p:identity>
      <p:input port="source">
        <p:inline>
          <c:error>HTTP Request Failed</c:error>
        </p:inline>
      </p:input>
    </p:identity>
  </p:catch>
</p:try>

4.7 Other Steps

Other steps are specified by elements that occur as contained steps and are not in any of the the ignored namespaces. For example, other atomic steps:

<pfx:other-atomic-step
  name? = NCName>
    (p:input |
     p:option |
     p:parameter |
     p:log)*
</pfx:other-atomic-step>

Each atomic step must be the name of a p:pipeline type or must have been declared with a p:declare-step that appears in the pipeline, or an imported library, before it is used. Pipelines can refer to themselves (recursion is allowed), to pipelines defined in imported libraries, and to other pipelines in the same library if they are in a library.

If the step element name is the same as the type of a step declared with p:declare-step, then that step invokes the declared step.

If the step element name is the same as the type or name of a p:pipeline, then that step runs the pipeline identified by that type or name.

The presence of other compound steps is implementation defined; XProc provides no standard mechanism for defining them or describing what they can contain.

It is a static error (err:XS0010) if a pipeline contains a step whose specified inputs, outputs, and options do not match the signature for steps of that type.

It is a dynamic error (err:XD0017) if the running pipeline attempts to invoke a step which the processor does not know how to perform.

Editorial Note

A pipeline author can make the set of parameters passed to a step explicit with a parameter input. If the step does not make an explicit binding for a parameter input, the default could be either to pass no parameters to the step or to behave as if the parameter input was bound to the pipeline parameters.

The working group is divided on this issue and this draft does not provide an answer to that question. Reader feedback is encouraged.

4.7.1 Syntactic Shortcut for Option Values

Namespace qualified attributes on a step are extension attributes. Attributes, other than name, that are not namespace qualified are treated as a syntactic shortcut for specifying the value of an option. In other words, the following two steps are equivalent:

The first step uses the standard p:option syntax:

<ex:stepType>
  <p:option name="option-name" value="5"/>
</ex:stepType>

The second step uses the syntactic shortcut:

<ex:stepType option-name="5"/>

Note that there are significant limitations to this shortcut syntax:

  1. It only applies to option names that are not in a namespace.

  2. It only applies to option names that are not otherwise used on the step, such as “name”.

  3. It can only be used to specify a constant value. Options that are computed with a select expression must be written using the longer form.

It is a static error (err:XS0027) if an option is specified with both the shortcut form and the long form. It is a static error (err:XS0031) to use an option on an atomic step that is not declared on steps of that type.

5 Other pipeline elements

5.1 p:input Element

A p:input identifies an input port for a step. In some contexts, p:input declares that a port with the specified name exists and identifies the properties of that port. In other contexts, it provides a binding for a port with a specified name (in which case it must have been declared elsewhere). In some contexts, it does both. The semantics of p:input are complicated further by the fact that there are two kinds of inputs, ordinary “document” inputs and “parameter” inputs.

On a p:declare-step, the p:input element is only a declaration. On a p:pipeline, it is both a declaration and a binding. In other contexts, it is only a binding.

5.1.1 Document Inputs

The declaration of a document input identifies the name of the port, whether or not the port accepts a sequence, and whether or not the port is a primary input port.

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind? = "document" />

The port attribute defines the name of the port. It is a static error (err:XS0011) to identify two ports with the same name on the same step.

The sequence attribute determines whether or not a sequence of documents is allowed on the port. If sequence is not specified, or has the value “false”, then it is a dynamic error (err:XD0006) unless exactly one document appears on the declared port.

The primary attribute is used to identify the primary input port. An input port is a primary input port if primary is specified with the value “true” or if the step has only a single input port and primary is not specified. It is a static error (err:XS0030) to specify that more than one input port is the primary.

The kind attribute distinguishes between the two kinds of inputs: document inputs and parameter inputs. An input port is a document input port if kind is specified with the value “document” or if kind is not specified.

On p:declare-step, the p:input simply declares the input port. It is a static error (err:XS0042) if the declaration of a document input port inside a p:declare-step. Document input port declarations must be empty unless they are declaring and binding an input port for a p:pipeline.

On an atomic step, it specifies a binding for the input:

<p:input
  port = NCName
  select? = XPath expression>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:input>

If no binding is provided, the input will be bound to the default readable port. It is a static error (err:XS0032) if no binding is provided and the default readable port is undefined. A select expression may also be provided with a binding. The select expression, if specified, applies the specified [XPath 1.0] select expression to the document(s) that are read. Each node selected is wrapped in a document and provided to the input port. In other words,

<p:input port="source">
  <p:document href="http://example.org/input.html"/>
</p:input>

provides a single document, but

<p:input port="source" select="//html:div">
  <p:document href="http://example.org/input.html"/>
</p:input>

provides a sequence of zero or more documents, one for each html:div in http://example.org/input.html. (Note that in the case of nested html:div elements, this may result in the same content being returned in several documents.)

A select expression can equally be applied to input read from another step. This input:

<p:input port="source" select="//html:div">
  <p:pipe step="origin" port="result"/>
</p:input>

provides a sequence of zero or more documents, one for each html:div in the document (or each of the documents) that is read from the result port of the step named origin.

It is a dynamic error (err:XD0016) if the select expression on a p:input returns anything other than a possibly empty set of nodes.

When a p:input is used in any context where it provides only a binding (e.g., on an atomic step), it is a static error (err:XS0012) if the port given does not match the name of an input port specified in the step's declaration.

5.1.2 Parameter Inputs

The declaration of a parameter input identifies the name of the port and that the port is a parameter input.

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind = "parameter" />

The port attribute defines the name of the port. It is a static error (err:XS0011) to identify two ports with the same name on the same step.

The sequence attribute determines whether or not a sequence of documents is allowed on the port. A sequence of documents is always allowed on a parameter input port. It is a static error (err:XS0040) to specify any value other than “true”.

The primary attribute is used to identify the primary parameter input port. An input port is a primary parameter input port if it is a parameter input port and primary is specified with the value “true” or if the step has only a single parameter input port and primary is not specified. It is a static error (err:XS0030) to specify that more than one parameter input port is the primary.

The kind attribute distinguishes between the two kinds of inputs: document inputs and parameter inputs. An input port is a parameter input port only if the kind attribute is specified with the value “parameter”. It is a static error (err:XS0033) to specify any kind of input other than “document” or “parameter”.

A parameter input port is a distinguished kind of input port. It exists only to receive computed parameters; if a step does not have a parameter input port then it cannot receive parameters. A parameter input port must satisfy all the constraints of a normal, document input port.

It is a static error (err:XS0035) if the declaration of a parameter input port contains a binding; parameter input port declarations must be empty.

When used on a step, parameter input ports always accept a sequence of documents. If no binding is provided for a primary parameter input port, then the port will be bound to the primary parameter input port of the p:pipeline which contains the step. If no binding is provided for a parameter input port other than the primary parameter input port, then the port will be bound to an empty sequence of documents. It is a static error (err:XS0035) if a primary parameter input port has no binding and the pipeline that contains the step has no primary parameter input port.

If a binding is manufactured for a primary parameter input port, that binding occurs logically last among the other parameters, options, and bindings passed to the step. In other words, the parameter values that appear on that port will be used even if other values were specified with p:parameter elements. Users can change this priority by making the binding explicit and placing any p:parameter elements that they wish to function as overrides after the binding.

All of the documents that appear on a parameter input must either be c:parameter documents or c:parameter-set documents.

A step which accepts a parameter input reads all of the documents presented on that port, using each c:parameter (either at the root or inside the c:parameter-set) to establish the value of the named parameter. If the same name appears more than once, the last value specified is used. If the step also has literal p:parameter elements, they are are also considered in document order. In other words, p:parameter elements that appear before the parameter input may be overridden by the computed parameters; p:parameter elements that appear after may override the computed values.

Consider the example in Example 10, “A Parameter Example”.

Example 10. A Parameter Example
<p:pipeline name="main"
            xmlns:p="http://www.w3.org/2007/03/xproc"
            xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<p:input port="source"/>
<p:input port="parameters" kind="parameter"/>
<p:output port="result"/>

<p:xslt>
  <p:input port="source">
    <p:pipe step="main" port="source"/>
  </p:input>
  <p:input port="stylesheet">
    <p:document href="http://example.com/stylesheets/doc.xsl"/>
  </p:input>
  <p:parameter name="output-type" value="html"/>
  <p:input port="parameters">
    <p:pipe step="main" port="parameters"/>
  </p:input>
</p:xslt>

</p:pipeline>

This p:pipeline declares that it accepts parameters. Suppose that (through some implementation-defined mechanism) I have passed the parameters “output-type=fo” and “profile=unclassified” to the pipeline. These parameters are available on the parameters input port.

When the XSLT step runs, it will read those parameters and combine them with any parameters specified literally on the step. Because the parameter input comes after the literal declaration for output-type on the step, the XSLT stylesheet will see both values that I passed in (“output-type=fo” and “profile=unclassified”).

If the parameter input came before the literal declaration, then the XSLT stylesheet would see “output-type=html” and “profile=unclassified”.

Most stylesheets don't bother to declare parameter inputs, or provide explicit bindings for them, and “the right thing” usually happens.

5.1.2.1 The c:parameter element

A c:parameter represents a parameter on a parameter input.

<c:parameter
  name = QName
  namespace? = anyURI
  value = string />

The name attribute of the c:parameter must have the lexical form of a QName.

If the namespace attribute is specified, then the expanded name of the parameter is constructed >From the specified namespace and the local-name part of the name value (in other words, the prefix, if any, is ignored).

If the namespace attribute is not specified, and the name contains a colon, then the expanded name of the parameter is constructed using the name value and the namespace declarations in-scope on the c:parameter element.

If the namespace attribute is not specified, and the name does not contain a colon, then the expanded name of the parameter is in no namespace.

Any namespace-qualified attribute names that appear on the c:parameter element are ignored. It is a dynamic error (err:XD0014) for any unqualified attribute names other than “name”, “namespace”, or “value” to appear on a c:parameter element.

5.1.2.2 The c:parameter-set element

A c:parameter-set represents a set of parameters on a parameter input.

<c:parameter-set>
    c:parameter*
</c:parameter-set>

The c:parameter-set contains zero or more c:parameter elements. It is a dynamic error (err:XD0018) if the parameter list contains any elements other than c:parameter.

Any namespace-qualified attribute names that appear on the c:parameter-set element are ignored. It is a dynamic error (err:XD0014) for any unqualified attribute names to appear on a c:parameter element.

5.2 p:iteration-source Element

A p:iteration-source identifies input to a p:for-each.

<p:iteration-source
  select? = XPath expression>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:iteration-source>

The select attribute and binding of a p:iteration-source work the same way that they do in a p:input.

5.3 p:viewport-source Element

A p:viewport-source identifies input to a p:viewport.

<p:viewport-source>
    (p:pipe |
     p:document |
     p:inline)?
</p:viewport-source>

Only one binding is allowed and it works the same way that bindings work on a p:input. It is a dynamic error (err:XD0006) unless exactly one document appears on the p:viewport-source. No select expression is allowed.

5.4 p:output Element

A p:output identifies an output port, optionally declaring it, if necessary.

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean />

The port attribute defines the name of the port. It is a static error (err:XS0011) to identify two ports with the same name on the same step. It is a static error (err:XS0013) if the port given does not match the name of an output port specified in the step's declaration.

An output declaration can indicate if a sequence of documents is allowed to appear on the declared port. If sequence is specified with the value “true”, then a sequence is allowed. If sequence is not specified on p:output, or has the value “false”, then it is a dynamic error (err:XD0007) if the step does not produce exactly one document on the declared port.

The primary attribute is used to identify the primary output port. An output port is a primary output port if primary is specified with the value “true” or if the step has only a single output port and primary is not specified. It is a static error (err:XS0014) to identify more than one output port as primary.

On compound steps, the declaration may be accompanied by a binding for the output.

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:output>

It is a static error (err:XS0029) to specify a binding for a p:output inside a p:declare-step.

If a binding is provided for a p:output, documents are read from that binding and those documents form the output that is written to the output port. In other words, placing a p:document inside a p:output causes the processor to read that document and provide it on the output port. It does not cause the processor to write the output to that document.

5.5 p:log Element

A p:log element is a debugging aid. It associates a URI with a specific output port on a step:

<p:log
  port = NCName
  href? = anyURI />

The semantics of p:log are that it writes to the specified URI whatever document or documents appear on the specified port. How a sequence of documents is represented in a p:log implementation-defined.

It is a static error (err:XS0026) if the port specified on the p:log is not the name of an output port on the step in which it appears or if more than one p:log element is applied to the same port.

Implementations may, at user option, ignore all p:log elements.

Note

This element represents a potential security risk: running unexamined 3rd-party pipelines could result in vital system resources being overwritten.

5.6 p:serialization Element

The p:serialization element allows the user to request serialization properties on a p:pipeline output.

<p:serialization
  port = NCName
  byte-order-mark? = boolean
  cdata-section-elements? = NMTOKENS
  doctype-public? = string
  doctype-system? = string
  encoding? = string
  escape-uri-attributes? = boolean
  include-content-type? = boolean
  indent? = boolean
  media-type? = string
  method? = QName
  normalization-form? = NFC|NFD|NFKC|NFKD|fully-normalized|none
  omit-xml-declaration? = boolean
  standalone? = true|false|omit
  undeclare-prefixes? = boolean
  version? = string />

If the pipeline processor serializes the output on the specified port, it must use the serialization options specified. If the processor is not serializing (if, for example, the pipeline has been called from another pipeline), then the p:serialization must be ignored. The processor may reject statically a pipeline that requests serialization options that it cannot provide.

The default value of any unspecified serialization option is implementation defined.

The semantics of the attributes on a p:serialization are described in Section 7.3, “Serialization Options”.

It is a static error (err:XS0039) if the port specified on the p:serialization is not the name of an output port on the pipeline in which it appears or if more than one p:serialization element is applied to the same port.

5.7 Options and Parameters

Options and parameters are both name/value pairs. What distinguishes them is whether or not the pipeline author is expected to know their names in advance. Option names are always known and specified by name. Parameter names may be known, in which case they can be specified by name just like options, or they may be computed dynamically by the pipeline.

5.7.1 p:option Element

The p:option element is used both to declare options and to establish values for them. It can occur in three contexts:

  1. On p:declare-step, it declares that the step accepts the named option. It may also provide a default value for the option.

  2. On a compound step, it provides a value for the option, simultaneously declaring it.

  3. On an atomic step, it provides a value for one of the declared options, overriding any default specified in the declaration.

It is a static error (err:XS0004) to specify two or more options or parameters on the same step with the same name.

5.7.1.1 Declaring Options

Options are declared for atomic steps by putting p:option elements in the p:declare-step that declares the atomic step type.

<p:option
  name = QName
  required? = boolean />

The name of the option must be a QName. If it does not contain a prefix then it is in no namespace. It is a static error (err:XS0028) to declare an option in the XProc namespace.

An option may be declared as required or it may be given a default value.

If an option is required, it is a static error (err:XS0018) to invoke the step without specifying a value for that option. It is a static error (err:XS0017) to specify that an option is both required and has a default value.

5.7.1.2 Using Options

Values are assigned to options on a particular step with p:option. The name of the option must be a QName. If it does not contain a prefix then it is in no namespace.

The option must be given a value when it is used. It is a static error (err:XS0031) to use an undeclared option on an atomic step.

5.7.1.3 Assigning Values to Options

When an option is declared, it may be given a default value. When it is used, it must be given a value.

The value can be specified in two ways: with a select or value attribute.

If a select expression is given, it is evaluated as an [XPath 1.0] expression using the context defined in Section 2.8.1, “Processor XPath Context”. The [XPath 1.0] string value of the expression becomes the value of the option. Since all in-scope options are present in the Processor XPath Context as variable bindings, select expressions may refer to the value of in-scope options by variable reference. It is a static error (err:XS0019) if the variable reference uses a QName that is not the name of an in-scope option. It is a dynamic error (err:XD0008) if a document sequence is specified in the binding for a p:option.

<p:option
  name = QName
  select = XPath expression
  required? = boolean>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?,
    p:namespaces*
</p:option>

If a select expression is used but no binding is provided, the implicit binding is to the default readable port. It is a static error (err:XS0032) if no binding is provided and the default readable port is undefined. If the context node is bound to p:empty, an empty document node is used instead as the context.

If a value attribute is specified, its content becomes the value of the option.

<p:option
  name = QName
  value = string
  required? = boolean>
    p:namespaces*
</p:option>

The p:namespaces element can be used to specify the namespace bindings associated with the option, see Section 5.7.3, “Option and Parameter Namespaces”.

If the value of an option is a constant, and no namespace bindings other than those in-scope on the step are necessary, its value may also be specified on the parent step as specified in Section 4.7.1, “Syntactic Shortcut for Option Values”.

It is a static error (err:XS0016) if the value is not specified with either select or value, or if both are specified, or if value is specified with a binding.

5.7.2 p:parameter Element

The p:parameter element is used to establish the value of a parameter. The parameter must be given a value when it is used. (Parameter names aren't known in advance; there's no provision for declaring them.)

The value can be specified in two ways: with a select or value attribute.

<p:parameter
  name = QName
  select = XPath expression
  port? = NCName>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?,
    p:namespaces*
</p:parameter>

If a select expression is given, it is evaluated as an [XPath 1.0] expression using the context defined in Section 2.8.1, “Processor XPath Context”. The [XPath 1.0] string value of the expression becomes the value of the parameter. Since all in-scope options are present in the Processor XPath Context as variable bindings, select expressions may refer to the value of in-scope options by variable reference. It is a static error (err:XS0019) if the variable reference uses a QName that is not the name of an in-scope option. It is a dynamic error (err:XD0008) if a document sequence is specified in the binding for a p:parameter.

If a select expression is used but no binding is provided, the implicit binding is to the default readable port. It is a static error (err:XS0032) if no binding is provided and the default readable port is undefined. If the context node is bound to p:empty, an empty document node is used instead as the context.

If a value attribute is specified, its content becomes the value of the parameter.

<p:parameter
  name = QName
  value = string
  port? = NCName>
    p:namespaces*
</p:parameter>

It is a static error (err:XS0016) if the value is not specified with either select or value, or if both are specified.

If the optional port attribute is specified, then the parameter appears on the named port, otherwise the parameter appears on the step's primary parameter input port. It is a static error (err:XS0034) if the specified port is not a parameter input port or if no port is specified and the step does not have a primary parameter input port.

5.7.3 Option and Parameter Namespaces

Option and parameter values carry with them not only their literal or computed string value but also a set of namespaces. To see why this is necessary, consider the following step:

<p:delete>
  <p:option name="match" value="html:div"
            xmlns:html="http://www.w3.org/1999/xhtml"/>
</p:delete>

The p:delete step will delete elements that match the expression “html:div”, but that expression can only be correctly interpreted if there's a namespace binding for the prefix “html” so that binding has to travel with the option.

The default namespace bindings associated with an option or parameter value are computed as follows:

  1. If the select attribute was used to specify the value and it contained a single VariableReference (per [XPath 1.0]), then the namespace bindings from the referenced option are used.

  2. If the select attribute was used to specify the value and it evaluated to a node-set, then the in-scope namespaces from the first node in the selected node-set (or, if it's not an element, its parent) are used.

    The expression is evaluated in the appropriate context, See Section 2.8, “XPath Context”.

  3. Otherwise, the in-scope namespaces from the p:option or p:parameter itself are used.

The default namespace is never included in the namespace bindings for an p:option or p:parameter. Unqualified names are always in no-namespace.

Unfortunately, in more complex situations, there may be no single option or parameter that can reliably be expected to have the correct set of namespace bindings. Consider this pipeline:

<p:pipeline type="ex:delete-in-div"
            xmlns:p="http://www.w3.org/2007/03/xproc"
            xmlns:ex="http://example.org/ns/ex"
            xmlns:h="http://www.w3.org/1999/xhtml">
<p:option name="divchild" required="true"/>

<p:delete>
  <p:option name="match" select="concat('h:div/',$divchild)"/>
</p:delete>

</p:pipeline>

It defines an atomic step (“ex:delete-in-div”) that deletes elements that occur inside of XHTML div elements. It might be used as follows:

<ex:delete-in-div>
  <p:option name="divchild" select="html:p[@class='delete']"
            xmlns:html="http://www.w3.org/1999/xhtml"/>
</ex:delete-in-div>

In this case, the match option passed to the p:delete step needs both the namespace binding of “h” specified in the ex:delete-in-div pipeline definition and the namespace binding of “html” specified in the divchild option on the call of that pipeline. It's not sufficient to provide just one of the sets of bindings.

The p:namespaces element can be used as a child of p:option or p:parameter to provide explicit bindings.

<p:namespaces
  option? = QName
  element? = XPath expression
  except-prefixes? = prefix list />

The namespace bindings specified by a p:namespaces element are determined as follows:

  1. If the option attribute is specified, it must contain the name of a single in-scope option. The namespace bindings associated with that option are used;

  2. If the element attribute is specified, it must contain an XPath expression which identifies a single element node (the input binding for this expression is the same as the binding for the p:option or p:parameter which contains it). The in-scope namespaces of that node are used;

    The expression is evaluated in the appropriate context, See Section 2.8, “XPath Context”.

  3. If neither option nor element is specified, the in-scope namespaces on the p:namespaces element itself are used.

Irrespective of how the set of namespaces are determined, the except-prefixes attribute can be used to exclude one or more namespaces. The value of the except-prefixes attribute must be a sequence of tokens, each of which must be bound to a namespace in the in-scope namespaces of the p:namespaces element. All bindings of prefixes to each of the namespaces thus identified are excluded.

It is a static error (err:XS0041) to specify both option and element on the same p:namespaces element. It is a static error (err:XS0005) if any token specified in the prefix list is not the prefix of an in-scope namespace.

If a p:option or p:parameter includes one or more p:namespaces elements, then the union of all the namespaces specified on those elements are used as the bindings for the option or parameter value. In this case, the in-scope namespaces on the p:option or p:parameter are ignored. It is a dynamic error (err:XD0013) if the specified namespace bindings are inconsistent; that is, if the same prefix is bound to two different namespace names.

For example, this would allow the preceding example to work:

<p:pipeline type="ex:delete-in-div"
            xmlns:p="http://www.w3.org/2007/03/xproc"
            xmlns:ex="http://example.org/ns/ex"
            xmlns:h="http://www.w3.org/1999/xhtml">
<p:option name="divchild" required="true"/>

<p:delete>
  <p:option name="match" select="concat('h:div/',$divchild)">
    <p:namespaces xmlns:h="http://www.w3.org/1999/xhtml"
                  xmlns:html="http://www.w3.org/1999/xhtml"/>
  </p:option>
</p:delete>

</p:pipeline>

The p:namespaces element provides namespace bindings for both of the prefixes necessary to correctly interpret the expression ultimately passed to the p:delete step.

This solution has the weakness that it depends on knowing the bindings that will be used by the caller. A more flexible solution would use the option attribute to copy the bindings from the caller's option value.

<p:pipeline type="ex:delete-in-div"
            name="main"
            xmlns:p="http://www.w3.org/2007/03/xproc"
            xmlns:ex="http://example.org/ns/ex"
            xmlns:h="http://www.w3.org/1999/xhtml">
<p:option name="divchild" required="true"/>

<p:delete>
  <p:option name="match" select="concat('h:div/',$divchild)">
    <p:namespaces option="divchild"/>
    <p:namespaces xmlns:h="http://www.w3.org/1999/xhtml"/>
  </p:option>
</p:delete>

</p:pipeline>

This example will succeed as long as the caller-specified option does not bind the “h” prefix to something other than the XHTML namespace.

5.8 p:declare-step Element

A p:declare-step provides the type and signature of an atomic step. It declares the inputs, outputs, and options for all steps of that type.

<p:declare-step
  name? = NCName
  type = QName>
    (p:input |
     p:output |
     p:option)*
</p:declare-step>

Implementations may use extension attributes to provide implementation-dependent information about a declared step. For example, such an attribute might identify the code which implements steps of this type.

The value of the type can be from any namespace provided that the expanded-QName of the value has a non-null namespace URI. It is a static error (err:XS0025) if the expanded-QName value of the type attribute is in no namespace. If the namespace URI of the type is the XProc namespace, then the declaration must be exactly as defined in this specification. Neither users nor implementers may define additional steps in the XProc namespace.

5.9 p:pipeline-library Element

A p:pipeline-library is a collection of step declarations and/or pipeline definitions.

<p:pipeline-library
  namespace? = anyURI
  name? = NCName
  ignore-prefixes? = prefix list>
    (p:import |
     p:declare-step |
     p:pipeline)*
</p:pipeline-library>

Libraries can import pipelines and/or other libraries. It is a static error (err:XS0021) if the import references in a pipeline or pipeline library are circular.

If the p:pipeline-library specifies a namespace with the namespace attribute, then all of the untyped pipelines that occur in the library are in that namespace.

For example, given the following pipeline library:

<p:pipeline-library xmlns:p="http://www.w3.org/2007/03/xproc"
                    namespace="http://example.com/ns/pipelines">

<p:import href="ancillary-library.xml"/>
<p:import href="other-pipeline.xml"/>

<p:pipeline name="validate">
  <!-- definition of validate pipeline -->
</p:pipeline>

<p:pipeline name="format" type="my:format"
            xmlns:my="http://example.com/vanity/mine">
  <!-- definition of format pipeline -->
</p:pipeline>

</p:pipeline-library>

The pipeline named “validate” is in the namespace http://example.com/ns/pipelines. That means that it must be invoked from the importing pipeline with a qualified name of the form:

<ex:validate>
  …
</ex:validate>

(Assuming that the “ex” prefix is bound to http://example.com/ns/pipelines.)

The pipeline named “format” has an explicit type so it must be invoked with a qualified name of the form:

<my:format>
  …
</my:format>

(Assuming that the “my” prefix is bound to http://example.com/vanity/mine.)

The pipeline library namespace applies only to pipelines that are defined directly in the library; it does not apply to pipeline libraries that are imported or pipelines that are directly imported.

[Definition: The expanded pipeline name of a pipeline is the expanded name denoted by its type, if it has one, otherwise the expanded name specified by the namespace of its containing pipeline-library and its name.]

5.10 p:import Element

An p:import loads a pipeline or pipeline library, making it available in the pipeline or library which contains the p:import.

<p:import
  href = anyURI />

An import statement loads the specified URI and makes any pipelines declared within it available to the current pipeline. An imported pipeline has an implicit signature that consists of the inputs, outputs, and options declared on it.

It is a dynamic error (err:XD0009) if the URI of a p:import cannot be retrieved or if, once retrieved, it does not point to a p:pipeline-library or p:pipeline. It is a dynamic error (err:XD0010) to import a single pipeline if that pipeline does not have a name or a type. It is a dynamic error (err:XD0012) to import more than one pipeline with the same expanded pipeline name (either directly or within a library).

5.11 p:pipe Element

A p:pipe connects an input to a port on another step.

<p:pipe
  step = NCName
  port = NCName />

The p:pipe element connects to a readable port of another step. It identifies the readable port to which it connects with the name of the step in the step attribute and the name of the port on that step in the port attribute.

In all cases except the p:output of a compound step, it is a static error (err:XS0022) if the port identified by a p:pipe is not in the readable ports of the step that contains the p:pipe.

A p:pipe that is a binding for an p:output of a compound step may connect to one of the readable ports of the compound step or to an output port on one of the compound step's contained steps. In other words, the output of a compound step can simply be a copy of one of the available inputs or it can be the output of one of its children.

5.12 p:inline Element

A p:inline provides a document inline.

<p:inline>
    anyElement
</p:inline>

The content of the p:inline element is wrapped in a document node and passed as input. The base URI of the document is the base URI of the p:inline element.

Note

The nodes inside a p:inline element naturally inherit the namespaces that are in-scope at the point where they occur in the pipeline document. Implementations must assure that those namespaces remain in-scope in the resulting document.

It is a static error (err:XS0024) if the content of the p:inline element does not consist of exactly one element, optionally preceded and/or followed by any number of processing instructions, comments or whitespace characters.

5.13 p:document Element

A p:document reads an XML document >From a URI.

<p:document
  href = anyURI />

The document identified by the URI in the href attribute is loaded and returned.

It is a dynamic error (err:XD0011) if the document referenced by a p:document element does not exist, cannot be accessed, or is not a well-formed XML document.

The parser which the p:document element employs must be conformant to Namespaces in XML. It must not perform validation. It must not perform any other processing, such as expanding XIncludes.

Use the p:load step if you need to perform DTD-based validation or wish to perform other processing on the document before it is used by a step.

5.14 p:empty Element

A p:empty binds to an empty sequence of documents.

<p:empty />

5.15 p:documentation Element

A p:documentation contains human-readable documentation.

<p:documentation>
    any-well-formed-content*
</p:documentation>

There are no constraints on the content of the p:documentation element. Documentation is ignored by pipeline processors.

6 Errors

Errors in a pipeline can be divided into two classes: static errors and dynamic errors.

6.1 Static Errors

[Definition: A static error is one which can be detected before pipeline evaluation is even attempted.] Examples of static errors include cycles, incorrect specification of inputs and outputs, and reference to unknown steps.

Static errors are fatal and must be detected before any steps are evaluated.

Static Errors
err:XS0001

It is a static error if there are any loops in the connections between steps: no step can be connected to itself nor can there be any sequence of connections through other steps that leads back to itself.

See: Connections

err:XS0002

All the named steps in the same scope must have unique names: it is a static error if two steps with the same name appear in the same scope.

See: Scoping of Names

err:XS0003

It is a static error if the port specified by a p:pipe is not in the readable ports of the environment.

See: Associating Documents with Ports

err:XS0004

It is a static error to specify two or more options or parameters on the same step with the same name.

See: p:option Element

err:XS0005

It is a static error if any token specified in the prefix list is not the prefix of an in-scope namespace.

See: Ignored namespaces, Option and Parameter Namespaces

err:XS0006

It is a static error if the primary output port has no binding and the last step in the subpipeline does not have a primary output port.

See: p:pipeline, p:for-each, p:viewport

err:XS0007

It is a static error if two subpipelines in a p:choose declare different outputs.

See: p:choose

err:XS0008

It is a static error if any element in the XProc namespace has attributes not defined by this specification unless they are extension attributes.

See: Syntax Summaries

err:XS0009

It is a static error if the p:group and p:catch subpipelines declare different outputs.

See: p:try/p:catch

err:XS0010

It is a static error if a pipeline contains a step whose specified inputs, outputs, and options do not match the signature for steps of that type.

See: Other Steps

err:XS0011

It is a static error to identify two ports with the same name on the same step.

See: Document Inputs, Parameter Inputs, p:output Element

err:XS0012

it is a static error if the port given does not match the name of an input port specified in the step's declaration.

See: Document Inputs

err:XS0013

It is a static error if the port given does not match the name of an output port specified in the step's declaration.

See: p:output Element

err:XS0014

It is a static error to identify more than one output port as primary.

See: p:output Element

err:XS0015

It is a static error to specify as an ignored namespace the XProc namespace, the namespace of any imported p:pipeline, or any namespace in which an atomic step is declared.

See: Ignored namespaces

err:XS0016

It is a static error if the value is not specified with either select or value, or if both are specified, or if value is specified with a binding.

See: Assigning Values to Options, p:parameter Element

err:XS0017

It is a static error to specify that an option is both required and has a default value.

See: Declaring Options

err:XS0018

If an option is required, it is a static error to invoke the step without specifying a value for that option.

See: Declaring Options

err:XS0019

It is a static error if the variable reference uses a QName that is not the name of an in-scope option.

See: Assigning Values to Options, p:parameter Element

err:XS0021

It is a static error if the import references in a pipeline or pipeline library are circular.

See: p:pipeline-library Element

err:XS0022

In all cases except the p:output of a compound step, it is a static error if the port identified by a p:pipe is not in the readable ports of the step that contains the p:pipe.

See: p:pipe Element

err:XS0024

It is a static error if the content of the p:inline element does not consist of exactly one element, optionally preceded and/or followed by any number of processing instructions, comments or whitespace characters.

See: p:inline Element

err:XS0025

It is a static error if the expanded-QName value of the type attribute is in no namespace.

See: p:declare-step Element

err:XS0026

It is a static error if the port specified on the p:log is not the name of an output port on the step in which it appears or if more than one p:log element is applied to the same port.

See: p:log Element

err:XS0027

It is a static error if a compound step has no contained steps.

See: Steps, Syntactic Shortcut for Option Values

err:XS0028

It is a static error to declare an option in the XProc namespace.

See: Declaring Options

err:XS0029

It is a static error to specify a binding for a p:output inside a p:declare-step.

See: p:output Element

err:XS0030

It is a static error to specify that more than one input port is the primary.

See: Document Inputs, Parameter Inputs

err:XS0031

It is a static error to use an option on an atomic step that is not declared on steps of that type.

See: Syntactic Shortcut for Option Values, Using Options

err:XS0032

It is a static error if no binding is provided and the default readable port is undefined.

See: Document Inputs, Assigning Values to Options, p:parameter Element

err:XS0033

It is a static error to specify any kind of input other than “document” or “parameter”.

See: Parameter Inputs

err:XS0034

It is a static error if the specified port is not a parameter input port or if no port is specified and the step does not have a primary parameter input port.

See: p:parameter Element

err:XS0035

It is a static error if the declaration of a parameter input port contains a binding; parameter input port declarations must be empty.

See: Parameter Inputs, Parameter Inputs

err:XS0036

All the step types in a pipeline must have unique names: it is a static error if any step type name is built-in and/or declared or defined more than once in the same scope.

See: Scoping of Names

err:XS0037

It is a static error if any step contains text nodes that do not consist entirely of whitespace.

See: Syntax Summaries

err:XS0038

It is a static error if any required attribute is not provided.

See: Syntax Summaries

err:XS0039

It is a static error if the port specified on the p:serialization is not the name of an output port on the pipeline in which it appears or if more than one p:serialization element is applied to the same port.

See: p:serialization Element

err:XS0040

It is a static error to specify any value other than “true”.

See: Parameter Inputs

err:XS0041

It is a static error to specify both option and element on the same p:namespaces element.

See: Option and Parameter Namespaces

err:XS0042

It is a static error if the declaration of a document input port inside a p:declare-step.

See: Document Inputs

err:XS0043

It is a static error if any attribute value does not satisfy the type required for that attribute.

See: Syntax Summaries

err:XS0044

It is a static error if any element in the XProc namespace or any step has element children other than those specified for it by this specification.

See: Syntax Summaries

err:XS0045

It is a static error if any string that must be interpreted as a QName uses a prefix for which there is not a namespace binding.

See: Syntax Summaries

6.2 Dynamic Errors

A [Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space).

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

Dynamic Errors
err:XD0001

It is a dynamic error if a non-XML resource is produced on a step output or arrives on a step input.

See: Inputs and Outputs

err:XD0002

It is a dynamic error if the processor attempts to retrieve the URI specified on a p:document and fails.

See: Associating Documents with Ports

err:XD0003

It is a dynamic error if the viewport source does not provide exactly one document.

See: p:viewport

err:XD0004

It is a dynamic error if no subpipeline is selected by the p:choose and no default is provided.

See: p:choose

err:XD0005

It is a dynamic error if the xpath-context is bound to a sequence of documents.

See: p:xpath-context

err:XD0006

If sequence is not specified, or has the value “false”, then it is a dynamic error unless exactly one document appears on the declared port.

See: Document Inputs, p:viewport-source Element

err:XD0007

If sequence is not specified on p:output, or has the value “false”, then it is a dynamic error if the step does not produce exactly one document on the declared port.

See: p:output Element

err:XD0008

It is a dynamic error if a document sequence appears where a document to be used as the context node is expected.

See: Processor XPath Context, Assigning Values to Options, p:parameter Element

err:XD0009

It is a dynamic error if the URI of a p:import cannot be retrieved or if, once retrieved, it does not point to a p:pipeline-library or p:pipeline.

See: p:import Element

err:XD0010

It is a dynamic error to import a single pipeline if that pipeline does not have a name or a type.

See: p:import Element

err:XD0011

It is a dynamic error if the document referenced by a p:document element does not exist, cannot be accessed, or is not a well-formed XML document.

See: p:document Element

err:XD0012

It is a dynamic error to import more than one pipeline with the same expanded pipeline name (either directly or within a library).

See: p:import Element

err:XD0013

It is a dynamic error if the specified namespace bindings are inconsistent; that is, if the same prefix is bound to two different namespace names.

See: Option and Parameter Namespaces

err:XD0014

It is a dynamic error for any unqualified attribute names other than “name”, “namespace”, or “value” to appear on a c:parameter element.

See: The c:parameter element, The c:parameter-set element

err:XD0016

It is a dynamic error if the select expression on a p:input returns anything other than a possibly empty set of nodes.

See: Document Inputs

err:XD0017

It is a dynamic error if the running pipeline attempts to invoke a step which the processor does not know how to perform.

See: Other Steps

err:XD0018

It is a dynamic error if the parameter list contains any elements other than c:parameter.

See: The c:parameter-set element

err:XD0019

It is a dynamic error if any option value does not satisfy the type required for that option.

See: Syntax Summaries

err:XD0020

It is a dynamic error if the value of the test attribute is not a valid XPath expression.

See: p:when

6.3 Step Errors

Several of the steps in the standard and option step library can generate dynamic errors.

Step Errors
err:XC0001

It is a dynamic error if the requested method is not supported.

See: Serialization Options

err:XC0003

It is a dynamic error if the requested auth-method isn't supported or the authentication challenge contains an authentication method that isn't supported.

See: HTTP Request

err:XC0004

It is a dynamic error if the status-only attribute has a value of “true” and the detailed attribute does not value of “true”.

See: HTTP Request

err:XC0005

It is a dynamic error if the request contains a c:body or c:multipart but the method does not allow an entity body being sent with the request.

See: c:http-request

err:XC0006

It is a dynamic error if an existing xml:id value conflicts with a previously generated value.

See: Label Elements

err:XC0007

It is a dynamic error if the scheme of the URI is not supported.

See: Load

err:XC0008

It is a dynamic error if the pattern does not match an element or attribute.

See: Make Absolute URIs

err:XC0009

It is a dynamic error if the specified new-name is not a valid QName.

See: Rename

err:XC0010

it is a dynamic error if the encoding is not supported by the implementation.

See: Unescape Markup

err:XC0011

It is a dynamic error dynamic error if the step is not allowed to load document from the location.

See: Load, XInclude

err:XC0012

It is a dynamic error if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.

See: Directory List

err:XC0013

It is a dynamic error if the match pattern does not match an element.

See: Add Attribute

err:XC0014

It is a dynamic error if the XML namespace (http://www.w3.org/XML/1998/namespace) or the XMLNS namespace (http://www.w3.org/2000/xmlns/) is used in either the from or to options.

See: Namespace Rename

err:XC0015

It is a dynamic error if the renaming would introduce a syntactic error into the document (i.e., if it would create two attributes with the same name on the same element).

See: Rename

err:XC0016

It is a dynamic error if the value supplied for any option specified for any step in this section is not of the type mandated in the step description, with phrases such as "The value of the xxx-name option must be a QName" or "the value of the yyy-flag option must be a boolean".

See: Standard Step Library

err:XC0017

It is a dynamic error if the absolute path does not identify a directory.

See: Directory List

err:XC0018

It is a dynamic error if the directory path's scheme is not supported.

See: Directory List

err:XC0019

It is a dynamic error if the documents are not equal, and the value of the fail-if-not-equal option is “true”.

See: Equal

7 Standard Step Library

This appendix describes the standard XProc steps. A machine-readable description of these steps may be found in pipeline-library.xml.

Some steps in this appendix consume or produce an XML vocabulary defined in this section. In all cases, the namespace for that vocabulary is http://www.w3.org/2007/03/xproc-step and is represented by the prefix 'c:' in this appendix.

When a step in this library produces an output document, the base URI of the output is the base URI of the step's primary input document unless the step's process explicitly sets an xml:base attribute or the step's description explicitly states how the base URI is constructed.

Also, in this section, several steps use this element for result information:

<c:result>
    string
</c:result>

When a step uses an XPath from an option value, the XPath context is as defined in Section 2.8.2, “Step XPath Context”.

It is a dynamic error (err:XC0016) if the value supplied for any option specified for any step in this section is not of the type mandated in the step description, with phrases such as "The value of the xxx-name option must be a QName" or "the value of the yyy-flag option must be a boolean".

7.1 Required Steps

This section describes standard steps that must be supported by any conforming processor.

7.1.1 Add Attribute

The p:add-attribute step adds a single attribute to a set of matching elements. The input document specified on the source is processed for matches specified by the match pattern in the match option. For each of these matches, the attribute whose name is specified by the attribute-name option is set to the attribute value specified by the attribute-value option.

The resulting document is produced on the result output port and consists of a exact copy of the input with the exception of the matched elements. Each of the match elements is copied to the output with the addition or change of the specified attribute name.

<p:declare-step type="p:add-attribute">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="attribute-name" required="true"/>
     <p:option name="attribute-value" required="true"/>
</p:declare-step>

The value of the match option must be an XSLT match pattern. It is a dynamic error (err:XC0013) if the match pattern does not match an element.

The value of the attribute-name option must be a QName. The corresponding expanded name is used to construct the added attribute. A namespace binding is added if necessary, using the prefix from the QName if possible, otherwise the prefix is implementation-determined.

The value of the attribute-value option must be a legal attribute value according to XML.

Note

If multiple attributes need to be set, the p:set-attributes step should be used.

7.1.2 Add xml:base

The p:add-xml-base step exposes the base URI via explicit xml:base attributes. The input document from the source port is replicated to the result port with xml:base attributes added to each element according to these rules:

<p:declare-step type="p:add-xml-base">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="all" value="false"/>
     <p:option name="relative" value="true"/>
</p:declare-step>

The value of the all option must be a boolean.

The value of the relative option must be a boolean.

  • If the all option has the value “true”, an xml:base attribute is added with the value set to the element's base URI.

  • If the element is the document element and there is no xml:base attribute specified, an xml:base attribute is added with the value set to the element's base URI.

  • If the element's base URI is different from its parent, an xml:base attribute is added with the value set to the element's base URI.

If the value of the relative option is “true”, any xml:base attribute value should be expressed relative to the current base URI. Otherwise, the value of the xml:base attribute should be an absolute URI.

7.1.3 Count

The p:count step counts the number of documents in the source input sequence and returns a single document on result containing that number. The generated document contains a single c:result element whose contents is the string representation of the number of documents in the sequence.

<p:declare-step type="p:count">
     <p:input port="source" sequence="true"/>
     <p:output port="result"/>
</p:declare-step>

7.1.4 Delete

The p:delete step deletes items specified by a match pattern from the source input document and produces the resulting document with the deletions on the result port.

<p:declare-step type="p:delete">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

The value of the match option must be an XSLT match pattern. It may match multiple items to be deleted, but note that nested matches are not considered as their ancestors will already have been deleted.

7.1.5 Directory List

The p:directory-list step produces a list of the contents of a specified directory.

<p:declare-step type="p:directory-list">
     <p:output port="result"/>
     <p:option name="path" value="."/>
     <p:option name="filter"/>
</p:declare-step>

The value of the path option must be an anyURI, as defined in [W3C XML Schema: Part 1] or its successor(s). If relative, it is resolved to absolute form. The base URI used for resolution is the base URI of p:option element, if present, otherwise, that is in case the default of '.' is used, the base URI of the p:directory-list element. It is a dynamic error (err:XC0017) if the absolute path does not identify a directory. It is a dynamic error (err:XC0012) if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.

Conformant processors must support directory paths whose scheme is file. It is implementation defined what other schemes are supported, and what the interpretation of 'directory', 'file' and 'contents' is for those schemes. It is a dynamic error (err:XC0018) if the directory path's scheme is not supported.

If present, the value of the filter option must be a regular expression as specified in [XPath 2.0 Functions and Operators], section 7.61 “Regular Expression Syntax”. If the pattern matches a directory entry's name, the entry is included in the output.

The result document produced for the specified directory path has a c:directory document element whose base URI is the directory path and whose name attribute is the last segment of the directory path (that is, the directory's (local) name). Its contents are determined as follows, based on the entries in the directory identified by the directory path:

  • For each entry in the directory, if either no filter was specified, or the (local) name of the entry matches the filter pattern, a c:file, a c:directory, or a c:other element is produced, as follows:

  • A c:file is produced for each file not determined to be special.

  • A c:directory is produced for each subdirectory not determined to be special.

  • Any file or directory determined to be special by the step may be output using a c:other element but the criteria for marking a file as special is implementation defined.

When a directory entry is a subdirectory, that directory's entries are not output as part of that entry's c:directory. A user must apply this step again to the subdirectory to list subdirectory contents.

Each of the elements c:file, c:directory, and c:other has a name attribute when they appear within the top-level c:directory element, whose value is a relative IRI reference, giving the (local) file or directory name.

These elements may have other attributes whose name and values are implementation defined.

7.1.6 Equal

The p:equal step compares two documents for equality.

<p:declare-step type="p:equal">
     <p:input port="source" primary="true"/>
     <p:input port="alternate"/>
     <p:output port="result" primary="false"/>
     <p:option name="fail-if-not-equal" value="false"/>
</p:declare-step>

The value of the fail-if-not-equal option must be a boolean.

This step takes single documents on each of two ports and compares them using the fn:deep-equal (as defined in [XPath 2.0 Functions and Operators]). It is a dynamic error (err:XC0019) if the documents are not equal, and the value of the fail-if-not-equal option is “true”. If the documents are equal, or if the value of the fail-if-not-equal option is “false”, a c:result document is produced with contents “true” if the documents are equal, otherwise “false”.

7.1.7 Error

The c:error step generates a dynamic error using the options specified on the step. The error generated can be caught by a try/catch language construct like any other dynamic error.

<p:declare-step type="p:error">
     <p:option name="code" required="true"/>
     <p:option name="description" required="true"/>
</p:declare-step>

The value of the code option must be a QName

This step has no inputs and no outputs. It needs no input, and since it generates an error upon invocation, there can be no normal output. Instead, an instance of the c:errors element will be produced on the error port, as is always the case for dynamic errors. The presence or absence of a p:try overhead will determine whether or not the error surfaces.

For example, given the following invocation:

<p:error name="bad-document" xmlns:my="http://www.example.org/error">
   <p:option name="code" value="my:unk12">
   <p:option name="description" value="The document element is unknown."/>
</p:error>

The error vocabulary element (and document) generated on the error output port would be:

<c:errors xmlns:c="http://www.w3.org/ns/xproc-step"
          xmlns:p="http://www.w3.org/ns/xproc"
          xmlns:my="http://www.example.org/error">
 <c:error name="bad-document"
          type="p:error" code="my:unk12">The document element is unknown</c:error>
</c:errors>
7.1.8 Escape Markup

The Escape Markup step applies XML serialization to the children of the document element and replaces those children with their serialization. The outcome is a single element with text content that represents the "escaped" syntax of the children if they were serialized.

<p:declare-step type="p:escape-markup">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
     <p:option name="version" value="1.0"/>
</p:declare-step>

This step supports the standard serialization options as specified in Section 7.3, “Serialization Options”. These options control how the "escaped" markup is produced.

For example, the input:

<description>
<div xmlns="http://www.w3.org/1999/xhtml">
<p>This is a chunk of XHTML.</p>
</div>
</description>

produces:

<description>
&lt;div xmlns="http://www.w3.org/1999/xhtml">
&lt;p>This is a chunk of XHTML.&lt;/p>
&lt;/div>
</description>
7.1.9 HTTP Request

<p:declare-step type="p:http-request">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="byte-order-mark"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="normalization-form"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
</p:declare-step>

The HTTP Request step provides interactions with resources identified by URIs over HTTP or HTTPS. The input document provided on the source port specifies the request by a single c:http-request element. This element specifies the method, resource, and other request properties as well as possibly including an entity body (content) for the request.

When the request is formulated, the step and/or protocol implementation may add headers as necessary to either complete the request or as appropriate for the content specified (e.g. transfer encodings). A user of this step is guaranteed that their requested headers and content will be sent with the exception of any conflicts with protocol-related headers. If the user of the step requests a header value (e.g. content-type) that conflicts with a value the step and/or protocol implementation must set, the step will fail.

If the username attribute is specified, the username, password, auth-method, and send-authorization attributes are used to handle authentication as per [RFC 2617]. If the response returns an authentication challenge, the username and password attribute values are used to generate an Authorization header and the request is sent again. If that authorization fails, the request is not retried.

For the purposes of avoiding an authentication challenge, if the send-authorization attribute has a value of “true” and the authentication method specified by the auth-method supports generation of a Authorization header without a challenge, then a Authorization header is generated and sent on the first request. If the response contains an authentication challenge, the request is retried with an appropriate Authorization header.

Appropriate values for the auth-method attribute are "Basic" or "Digest" but other values are allowed. Their interpretation is implementation defined. It is a dynamic error (err:XC0003) if the requested auth-method isn't supported or the authentication challenge contains an authentication method that isn't supported. All implementations are required to support "Basic" and "Digest" authentication per [RFC 2617].

The standard serialization options are provided to control the serialization of the XML content when it is sent. These options are as specified in Section 7.3, “Serialization Options”.

If the value of the detailed attribute is “true”, the response received after making the request is handled as follows:

  1. A single c:http-response element is produced on the output port result with the status attribute containing the status of the response received.

  2. Each response header whose name does not start with "Content-" is translated into a c:header element.

  3. Unless the status-only attribute has a value “true”, the entity body of the response is converted into a c:body or c:multipart element via the rules given in this section.

If the detailed attribute is not specified or its value is “false”, the response received after making the request is handled as follows:

  1. If the media type is an XML media type, the entity is parsed as an XML document and produce on the result output port.

  2. Otherwise, the entity body of the response is converted into a c:body or c:multipart element via the rules given in this section.

It is a dynamic error (err:XC0004) if the status-only attribute has a value of “true” and the detailed attribute does not value of “true”.

7.1.9.1 Converting Response Entities

A request or response may be multipart per RFC 1521. In those situations, the entity is represented by a c:multipart element that contains multiple c:body elements inside. In the case of a request, the media type of the c:multipart must be a multipart media type (i.e. have a main type of 'multipart').

If the media type of the response is a text type with a charset parameter that is a Unicode character encoding, the children of the constructed c:body element is the translation of the text into a Unicode character sequence

If the media type of the response is an XML media type, the content of the constructed c:body element is the result of parsing the body with an XML parser. If the content is not well-formed, the step fails.

For all other media types, the response is encoded as base64 and produced as text children of the c:body element.

In the case of a multipart response, the same rules apply when constructing a c:body element for each body part encountered.

Note

Given the above description, any text/html content return is "escaped" in the c:body element as HTML isn't XML. A user can process this HTML content into XML via the c:unescape-markup step.

7.1.9.2 c:http-request

A HTTP request is represented by a c:http-request element.

<c:http-request
  method? = NCName
  href? = anyURI
  detailed? = boolean
  status-only? = boolean
  username? = string
  password? = string
  auth-method? = string
  send-authorization? = boolean
  override-content-type? = string>
    (c:header*,
     (c:multipart |
      c:body)?)
</c:http-request>

The method attribute specifies the method to be used against the URI specified by the href attribute. If the href attribute is a relative URI, it will resolve against the base URI of the element.

Both the status-only and override-content-type attributes are not used in formulating the response. The override-content-type attribute controls interpretation of the response's content-type. If this attribute is specified, the response will be treated as if it returned that content-type. If the override-content-type value cannot be used (e.g. text/plain to override image/png), the step fails. The original media type value will still be provided in the response XML.

Also, if status-only attribute has the value “true”, the entity of the response will not be processed to produce a c:body or c:multipart element.

It is a dynamic error (err:XC0005) if the request contains a c:body or c:multipart but the method does not allow an entity body being sent with the request.

The base URI of the output document is the URI of the request.

7.1.9.3 c:header

A c:header is a name-value pair passed in the headers of the request or its response.

<c:header
  name = string
  value? = string />

7.1.9.4 c:multipart

The c:multipart element holds a set of body parts for a message request or response.

<c:multipart
  content-type? = string>
    c:body+
</c:multipart>

If the content-type attribute is not specified, a value of "multipart/mixed" will be assumed.

7.1.9.5 c:body

The c:body element holds the body or body part of the message. Each of the attributes holds controls some aspect of the encoding of the body or body part when the request is formulated. These are specified as follows:

  • The content-type attribute specifies the media type of the content. If the media type is not an XML type nor is it text, the content must be already be base64 encoded.

  • The encoding attribute specifies the request's Content-Transfer-Encoding header. If the value of encoding is 'base64' but the content type does not require such an encoding, the c:body element is assumed to contain base64 encoded content of that media type.

  • The id attribute specified the value of the Content-ID header for body parts.

  • The description attribute specified the value of the Content-Description header for body parts.

For any XML media type, the document is assumed to be the first child of the c:body element in unescaped form. That is, the following is the request that sends a small XML document as the entity's body:


<c:http-request method="POST" href="http://example.com/someservice">
<c:body xmlns:c="http://www.w3.org/2007/03/xproc-step" content-type="application/xml">
<doc>
<title>My document</title>
</doc>
</c:body>
</c:http-request>

When used to create a request, the serialization of the document is controlled by the serialization options on the step.

<c:body
  content-type = string
  encoding? = string
  id? = string
  description? = string>
    anyElement*
</c:body>

7.1.9.6 c:http-response

The c:http-response element represents an HTTP response. The response's status code is encoded in the status attribute and the headers and entity body are processing into the c:header and c:multipart or c:body, respectively.

<c:http-response
  status? = integer>
    (c:header*,
     (c:multipart |
      c:body)?)
</c:http-response>

7.1.9.7 HTTP Request Examples

For example, a form post would be formulated as:

<c:http-request method="POST" href="http://www.example.com/form-action" xmlns:c="http://www.w3.org/2007/03/xproc-step">
<c:body content-type="application/x-www-form-urlencoded">
name=W3C&spec=XProc
</c:body>
</c:http-request>

and if the response was an XHTML document, the response would be:

<c:http-response status="200" xmlns:c="http://www.w3.org/2007/03/xproc-step">
<c:header name="Date" value=" Wed, 09 May 2007 23:12:24 GMT"/>
<c:header name="Server" value="Apache/1.3.37 (Unix) PHP/4.4.5"/>
<c:header name="Vary" value="negotiate,accept"/>
<c:header name="TCN" value="choice"/>
<c:header name="P3P" value="policyref=&quot;http://www.w3.org/2001/05/P3P/p3p.xml&quot;"/>
<c:header name="Cache-Control" value="max-age=600"/>
<c:header name="Expires" value="Wed, 09 May 2007 23:22:24 GMT"/>
<c:header name="Last-Modified" value="Tue, 08 May 2007 16:10:49 GMT"/>
<c:header name="ETag" value="&quot;4640a109;42380ddc&quot;"/>
<c:header name="Accept-Ranges" value="bytes"/>
<c:header name="Keep-Alive" value="timeout=2, max=100"/>
<c:header name="Connection" value="Keep-Alive"/>
<c:body content-type="application/xhtml+xml">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title>OK</title></head>
<body><p>OK!</p></body>
</html>
</c:body>
</c:http-response>
7.1.10 Identity

The identity step makes a verbatim copy of its input available on its output.

<p:declare-step type="p:identity">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true"/>
</p:declare-step>

7.1.11 Insert

The Insert step inserts the insertion port's document as a child of matching elements in the source port's document. The insertion copies the document element of the insertion document into the position specified by the options on the step. In some cases, multiple insertions may be performed by this step.

<p:declare-step type="p:insert">
     <p:input port="source" primary="true"/>
     <p:input port="insertion"/>
     <p:output port="result"/>
     <p:option name="match"/>
     <p:option name="position" required="true"/>
</p:declare-step>

The matching nodes in the source document are specified as a match pattern in the match option that must target an element. If no match pattern is supplied, the document element is the only match.

The position option takes one of the following values:

  • first-child” - the insertion is made as the first child of the match,

  • last-child” - the insertion is made as the last child of the match,

  • before” - the insertion is made as the immediate preceding sibling of the match,

  • after” - the insertion is made as the immediate following sibling of the match.

As the inserted elements are part of the output of the step they are not considered in determining matching elements.

7.1.12 Label Elements

The Label Elements step labels each element with a unique xml:id value. If the element already has an xml:id value, that value is preserved. A user may specify the prefix and/or suffix options for prefixing or suffixing the generated value of the xml:id attribute. These prefixes or suffixes do not affect existing xml:id values.

If a select option is specified, only elements which match that XPath 1.0 select expression are modified.

It is a dynamic error (err:XC0006) if an existing xml:id value conflicts with a previously generated value.

<p:declare-step type="p:label-elements">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="select"/>
     <p:option name="prefix"/>
     <p:option name="suffix"/>
</p:declare-step>

7.1.13 Load

The Load step has no inputs but takes a option that specifies a URI of an XML resource that should be loaded and provided as the result.

<p:declare-step type="p:load">
     <p:output port="result"/>
     <p:option name="href" required="true"/>
     <p:option name="validate"/>
</p:declare-step>

Load attempts to read an XML document from the specified URI. If the document does not exist, or is not well-formed, the step fails. Otherwise, the document read is produced on the “result” port.

If the value of the validate option is “true”, the XML processor is invoked as a validating XML processor and DTD validation is performed. If the document is not valid or the step doesn't support validating processors, the step fails.

As the value of the href is a URI, an implementation may support multiple URI schemes. An implementation is required to support the file and http schemes. It is a dynamic error (err:XC0007) if the scheme of the URI is not supported.

The base URI of the output document is the URI used to load the document.

It is a dynamic error dynamic error (err:XC0011) if the step is not allowed to load document from the location.

7.1.14 Make Absolute URIs

This steps makes an element or attribute's value in the source document an absolute URI value in the result document. The text value of match is resolved against a base URI value and the resulting absolute value is used as the match's text value in the output. In the case of elements, this replaces all the element's children with a single sequence of characters that contain the absolute URI.

The match contains a match pattern that identifies the element or attribute whose text value is to be changed. It is a dynamic error (err:XC0008) if the pattern does not match an element or attribute.

The base URI used for resolution defaults to the matched attribute's element or the matched element's base URI unless the base-uri is specified. When the base-uri option is specified, the option value is used as the base URI regardless of any contextual base URI value in the document. This option value is resolved against the base URI of the p:option element used to set the option.

<p:declare-step type="p:make-absolute-uris">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="base-uri"/>
</p:declare-step>

If the initial URI is not valid, or if the document has no base URI, the results are implementation dependent.

7.1.15 Namespace Rename

The Namespace Rename step renames any namespace declaration or use of a namespace in a document to a new URI value. The source namespaces is identified by the from option and the target namespace is identified by the to option.

If either the from or to options are not specified or have an empty string as their value, the result is to rename from or to the no namespace, respectively. In the case of the from option, when the no namespace is specified, only elements or attributes that have no namespace associated with their name are renamed. Since many attributes have no namespace associated with their name, the elements-only may be used to avoid renaming attributes.

If elements-only has the value “true”, then only elements will be renamed in the instance. If references to the target namespace remain, namespace declarations for the target namespace may remain in the document.

When a namespace declaration attribute is encountered and the value of the target namespace is the same as the value of the from, the attribute value is changed to the new namespace. If the elements-only option has the value “true”, the step must ensure that he remaining references to the namespace are modified to point to a new namespace declaration and prefix.

It is a dynamic error (err:XC0014) if the XML namespace (http://www.w3.org/XML/1998/namespace) or the XMLNS namespace (http://www.w3.org/2000/xmlns/) is used in either the from or to options.

<p:declare-step type="p:namespace-rename">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="elements-only"/>
     <p:option name="from"/>
     <p:option name="to"/>
</p:declare-step>

It is not an error to specify the same namespace in the from and to options, but it will have no observable effect.

7.1.16 Parameters

The Parameters step exposes a set of parameters as a sequence of c:parameter documents.

<p:declare-step type="p:parameters">
     <p:input port="parameters" kind="parameter" primary="false" sequence="true"/>
     <p:output port="result" sequence="true" primary="false"/>
</p:declare-step>

Each parameter passed to the step is converted into a c:parameter element and written to the “result” port as a document. The step resolves duplicate parameters in the normal way; the order in which the parameters are written is implementation dependent.

For consistency and user convenience, if any of the parameters have names that are in a namespace, the namespace attribute on the c:parameter element must be used. Each name will be an NCName.

The base URI of the output document is the URI of the pipeline document that contains the step.

7.1.17 Rename

The rename step renames elements, attributes, or processing-instruction targets in a document based on option values.

<p:declare-step type="p:rename">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="new-name" required="true"/>
</p:declare-step>

Each element, attribute, or processing-instruction matched by the match pattern specified in the match is renamed to the name specified by the new-name option. This option takes a QName value whose prefixes are resolved as specified in Section 5.7.3, “Option and Parameter Namespaces”.

It is a dynamic error (err:XC0009) if the specified new-name is not a valid QName.

It is a dynamic error (err:XC0015) if the renaming would introduce a syntactic error into the document (i.e., if it would create two attributes with the same name on the same element).

7.1.18 Replace

The Replace step replaces a matching node in the source input port's document with the document element of the replacement port's document. The result is a single document with all the matching nodes so replaced.

The elements to be replaced are specified by the match pattern in the match option. If there are multiple matches, only non-nested matches are replaced. That is, once an element is replaced, its descendants cannot be matched.

<p:declare-step type="p:replace">
     <p:input port="source" primary="true"/>
     <p:input port="replacement"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

7.1.19 Set Attributes

The Set Attributes step sets attribute values on the matching elements using the attribute values provided on the attributes port's document element. That is, it copies the attributes on the document element on the attributes port to the matching elements found in the source port's document. If the same attribute exists on the matching element, the value specified in the attribute port's document is used. The result port of this step produces a copy of the source port's document with the matching elements' attributes modified.

The matching elements are specified by the match pattern in the match option that must target an element. If there are multiple matches, all elements are processed.

<p:declare-step type="p:set-attributes">
     <p:input port="source" primary="true"/>
     <p:input port="attributes"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

7.1.20 Sink

The Sink step accepts a sequence of documents and discards them. It has no output.

<p:declare-step type="p:sink">
     <p:input port="source" sequence="true"/>
</p:declare-step>

7.1.21 Split Sequence

The Split Sequence step accepts a sequence of documents and produces two subsequences of that input by applying a test expression to each document. For each document on the source input port, if the XPath expression provided by the test option evaluates to true, the document is reproduced on the matched output port. If the expression evaluates to false, the document is reproduced on the not-matched output port.

<p:declare-step type="p:split-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="matched" sequence="true" primary="true"/>
     <p:output port="not-matched" sequence="true"/>
     <p:option name="test" required="true"/>
</p:declare-step>

The XPath context for the test option changes over time. For each document that appears on the source port, the expression is evaluated with that document as the context document. The context position is the position of that document within the sequence and the context size is the total number of documents in the sequence.

Note

In principle, this component cannot stream because it must buffer all of the input sequence in order to find the context size. In practice, if the test expression does not use the last() function, the implementation can stream and ignore the context size.

7.1.22 String Replace

The String Replace step matches nodes in the document provided on the source input port and replaces them with the string result of evaluating an XPath expression. The matched nodes are specified by the match pattern in the match option. For each matching node, the XPath expression provided by the replace option is applied and the string value that results is used in constructing the node's replacement in the output.

The output of this step is much like an identity transformation with exceptions for the set of matching nodes as follows:

  • For any matching node, the string value S is the result from evaluating the replace XPath expression with the matching node as the context node.

  • For a matching node that is not an attribute, the node is replaced by the string value S in the output document.

  • For a matching node that is an attribute, the string value of the attribute is replaced by the string value S in the output document.

<p:declare-step type="p:string-replace">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="replace" required="true"/>
</p:declare-step>

7.1.23 Store

The store step stores a serialized version of its input to a URI. The URI is either specified explicitly by the 'href' option or implicitly by the base URI of the document. This step outputs a reference to the location of the stored document.

<p:declare-step type="p:store">
     <p:input port="source"/>
     <p:output port="result" primary="false"/>
     <p:option name="href"/>
     <p:option name="byte-order-mark"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="normalization-form"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
     <p:option name="version" value="1.0"/>
</p:declare-step>

The step attempts to store the XML document to the specified URI. If that URI scheme is not supported or such storage is not allowed, the step fails.

The output of this step is a document containing a single c:result element whose content contains the same value as the href option.

The standard serialization options are provided to control the serialization of the XML content when it is stored. These options are as specified in Section 7.3, “Serialization Options”.

7.1.24 Unescape Markup

The Unescape Markup step takes the text value of the document element and parses the content as if it was a Unicode character stream containing XML. The outcome is a single element with children from the parsing of the XML content. This is the reverse of the p:escape-markup step.

When the text value is parsed, a document element wrapper must be assumed so that element siblings can be parsed back into XML. Further, if the namespace option is specified, the default namespace is declared on that wrapper element.

If the content-type option is specified, an implementation can use a different parser to produce XML content. Such a behavior is implementation defined. For example, for the mime type 'text/html', an implementation might provide an HTML to XHTML parser (e.g. Tidy).

In the case of where Unicode data has been encoded the encoding may specify a the type of encoding. Only the value "base64" is required to be supported by this step.

Further, once the content is decoded the Unicode encoding can be specified by the charset. If this option is missing, a value of "UTF-8" is assumed. While any valid Unicode encoding name is allowed for this option, it is a dynamic error (err:XC0010) if the encoding is not supported by the implementation.

<p:declare-step type="p:unescape-markup">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="namespace"/>
     <p:option name="content-type"/>
     <p:option name="encoding"/>
     <p:option name="charset"/>
</p:declare-step>

For example, with the 'namespace' option set to the XHTML namespace, the following input:

<description>
&lt;p>This is a chunk.&lt;/p>
&lt;p>This is a another chunk.&lt;/p>
</description>

would produce:

<description>
<p xmlns="http://www.w3.org/1999/xhtml">This is a chunk.</p>
<p xmlns="http://www.w3.org/1999/xhtml">This is a another chunk.</p>
</description>
7.1.25 Unwrap

The Unwrap step matches a certain number of elements and replaces them with their children. The source port input document is processed by applying the match pattern specified by the match. If the match is an element, the element is replaced with its children in the output document produced on the result port. A single document is produced and if unwrapping causes a non-well-formed document (e.g. more than one document element), the step fails.

<p:declare-step type="p:unwrap">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

7.1.26 Wrap

The Wrap step wraps matches items in the source port's input document with a new element. The document is processed by applying the match pattern specified by the match. For each match, the match is wrapped with a new element in the output document. The wrapper is used to specify the name of the element and takes a QName value whose prefixes are resolved as specified in Section 5.7.3, “Option and Parameter Namespaces”. A single document is produced on the result output port.

If the group-adjacent is specified, adjacent matches are grouped by evaluating the XPath specified by this option with the content node set to the matched node. If the XPath evaluates to the same string value, the matches are grouped into the same wrapper element. While processing the document for grouping, two matches are considered adjacent if they are either siblings or all intervening siblings are whitespace text, comments, or processing instruction nodes.

<p:declare-step type="p:wrap">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="wrapper" required="true"/>
     <p:option name="match" required="true"/>
     <p:option name="group-adjacent"/>
</p:declare-step>

7.1.27 Wrap Sequence

The Wrap Sequence step converts the sequence of documents on the source port into a single document on the result port. The document produced has a document element whose name is specified via the wrapper option and whose children are the contents of the documents received on source port, in the order they were received. All of the top-level nodes (white space, comments, processing-instructions, and one element node) of each document are added to the children of the new wrapper document. The wrapper option takes a QName value whose prefixes are resolved as specified in Section 5.7.3, “Option and Parameter Namespaces”

If the group-adjacent is specified, adjacent documents in the sequence are grouped by evaluating the XPath specified by this option with the context node set to the document node. If the XPath evaluates to the same string value, the documents are grouped into the same wrapper element.

<p:declare-step type="p:wrap-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true"/>
     <p:option name="wrapper" required="true"/>
     <p:option name="group-adjacent"/>
</p:declare-step>

7.1.28 XInclude

The XInclude step applies xinclude processing semantics to the document. The referenced documents are calculated against the base URI and are not provided as input to the step.

<p:declare-step type="p:xinclude">
     <p:input port="source"/>
     <p:output port="result"/>
</p:declare-step>

It is a dynamic error (err:XC0011) if an XInclude error occurs during processing and the step fails.

7.1.29 XSLT

The xslt step applies an XSLT 1.0 transformation to a document. The transformation is supplied by a single document on the input port named stylesheet. That transformation is applied to the primary source document supplied on the input port named source. The result of the transformation is a sequence of documents on its result port.

<p:declare-step type="p:xslt">
     <p:input port="source" primary="true"/>
     <p:input port="stylesheet"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result"/>
</p:declare-step>

All of the specified parameters are made available to the XSLT processor. If the XSLT processor signals a fatal error, the step fails. Otherwise, the result of the transformation is produced on the “result” port.

Since this step does not serialize the result document, all serialization parameters specified on the xsl:output element inside the transformation are ignored. Further, the output on the result port must be a well-formed XML document. As such, certain transformations that use non-XML output (e.g. 'text' method) may cause a dynamic error during execution of the transformation.

If the transformation terminates due to a xsl:message instruction with a terminate attribute value of “yes”, this step throws a dynamic error.

The base URI of the output document is the URI of the document on the source port.

7.2 Optional Steps

The following steps are optional. If they are supported by a processor, they must conform to the semantics outlined here, but a conformant processor is not required to support all (or any) of these steps.

Note

The Working Group is considering moving the optional steps to a separate document. User feedback on this point is encouraged.

7.2.1 Relax NG Validate

The Relax NG Validate step applies RELAX NG validation to an XML document input.

<p:declare-step type="p:validate-relax-ng">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
     <p:option name="dtd-compatibility" value="false"/>
</p:declare-step>

If the dtd-compatibility option is “true”, then the conventions of [RELAX NG DTD Compatibility] are also applied.

7.2.2 Schematron Validate

The Schematron Validate step applies Schematron validation to an XML document input.

<p:declare-step type="p:validate-schematron">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
</p:declare-step>

7.2.3 XML Schema Validate

The XML Schema Validate step applies XML Schema's validity assessment to an XML document input. The set of known available schemata are specified via a sequence of documents provided on the schema input port.

<p:declare-step type="p:validate-xml-schema">
     <p:input port="source" primary="true"/>
     <p:input port="schema" sequence="true"/>
     <p:output port="result"/>
     <p:option name="assert-valid" value="true"/>
     <p:option name="mode" value="strict"/>
</p:declare-step>

If assert-valid option has a value of “true”, the step will fail if the XML Schema validation assessment reports any errors. When XML Schema validation assessment is performed, the processor is invoked in the mode specified by the mode option. The result of the assessment produces an infoset with the Post-Schema-Validation-Infoset (PSVI) ([W3C XML Schema: Part 1]) annotations if the pipeline implementation supports such annotations. Otherwise, the input document is reproduced with any defaulting of attributes and elements performed as specified by the XML Schema recommendation.

Whether or not the pipeline processor supports passing PSVI annotations between steps is implementation-defined.

7.2.4 XSLT 2.0

The XSLT 2.0 step applies an XSLT 2.0 transformation to a document. The transformation is supplied on the port named stylesheet and the primary input document is supplied on the port named source. The application of the transformation produces the primary result document on the port named result.

<p:declare-step type="p:xslt2">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="stylesheet"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="true"/>
     <p:output port="secondary" sequence="true"/>
     <p:option name="initial-mode"/>
     <p:option name="template-name"/>
     <p:option name="allow-version-mismatch" value="true"/>
     <p:option name="output-base-uri"/>
     <p:option name="allow-collections" value="true"/>
</p:declare-step>

If a sequence of documents is provided on the input port named source, the first document is assumed to be the primary input document. By default, this sequence is also the default collection unless the allow-collections option is set to “false”.

All of the specified parameters are made available to the XSLT processor. If the XSLT processor signals a fatal error, the step fails. Otherwise, the result of the transformation is produced on the “result” port.

The invocation of the transformation is controlled by the initial-mode and template-name options that set the initial mode and/or named template in the XSLT transformation that should initiate processing. If these values do not match the transformation specified, a dynamic error must be thrown.

The allow-version-mismatch option indicates whether an XSLT 1.0 transformation should be allowed to be run through the XSLT 2.0 processor. A value of “true” means that it should be allow.

The output-base-uri option sets the context's output base URI per the XSLT 2.0 specification.

If more than one document is produced, the secondary result documents are produced on the output port named secondary. Otherwise, the secondary port produces an empty sequence.

If the transformation terminates due to a xsl:message instruction with a terminate attribute value of “yes”, this step throws a dynamic error.

The base URI of the output document is the base URI of the first document in the source port's sequence.

7.2.5 XSL Formatter

The XSL Formatter step receives an [XSL 1.1] document and renders the content. The result of rendering is stored to the URI provided via the 'uri' option. A reference to that result is produced on the output port.

The output content type is controlled by the 'output' option which contains a media type as specified by [IANA Media Types]. In addition, any media type parameters may be specified in this option (e.g. "text/html; charset=UTF-8" but their use are implementation defined.

If no output value is specified and the implementation supports PDF output, PDF output is assumed.

A formatter may take any number of optional rendering parameters via the step's parameters. Such parameters are defined by the XSL implementation used and are implementation defined.

<p:declare-step type="p:xsl-formatter">
     <p:input port="source"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="false"/>
     <p:option name="uri" required="true"/>
     <p:option name="output"/>
</p:declare-step>

The output of this step is a document containing a single c:result whose contents contains a URI that points to the output of the XSL formatter.

7.2.6 XQuery 1.0

The XQuery 1.0 step applies an XQuery to a sequence of documents treated as the default collection. The source input port allows a sequence of documents and specifies each document that should be in the default collection. The result of the xquery is a sequence of documents constructed from a XPath 2.0 sequence of elements. Each element in the sequence is assumed to be the document element of a separate document. It is an error if the sequence contains items other than elements.

<p:declare-step type="p:xquery">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="query"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" sequence="true"/>
</p:declare-step>

The query port must receive a single document whose element is c:query. As XQuery is not necessarily well-formed XML, the text descendants of this element are considered the query.

Each base URI of the output documents is the base URI of the first document in the source port's sequence.

<c:query>
    string
</c:query>

For example:

<c:query>
declare namespace atom="http://www.w3.org/2005/Atom";
/atom:feed/atom:entry
</c:query>

7.3 Serialization Options

Several steps in this step library require serialization options to control the serialization of XML. These options are used to control serialization as in the [XML Serialization] specification.

The following options may be present on steps that perform serialization:

  • byte-order-mark - A boolean.
  • cdata-section-elements - A list of QName values that are elements names
  • doctype-public - The public identifier of the doctype.
  • doctype-system - The system identifier of the doctype.
  • encoding - A character set name.
  • escape-uri-attributes - A boolean.
  • include-content-type - A boolean.
  • indent - A boolean.
  • media-type - A string of Unicode characters specifying the media type (MIME content type).
  • method - A QName value that specifies the serialization method.
  • normalization-form - One of the enumerated values NFC, NFD, NFKC, NFKD, fully-normalized, none or an implementation-defined value.
  • omit-xml-declaration - A boolean.
  • standalone - One of the enumerated values true, false, or omit.
  • undeclare-prefixes - A boolean.
  • version - A string of Unicode characters.

In order to be consistent with the rest of this specification, boolean values for the serialization parameters use “true” and “false” where the serialization specification uses “yes” and “no”. No change in semantics is implied by this different spelling.

The method option controls the serialization method used by this component with standard values of 'html', 'xml', 'xhtml', and 'text' but only the 'xml' value is required to be supported. The interpretation of the remaining options are as specified in [XML Serialization].

Implementations may support other method values but their results are implementation defined. It is a dynamic error (err:XC0001) if the requested method is not supported.

A minimally conforming implementation must support the xml output method with the following option values:

  • The version must support the value 1.0.

  • The encoding must support the values UTF-8.

  • The omit-xml-declaration must support be supported. If the value is not specified or has the value no, an XML declaration must be produced.

All other option values may be ignored for the xml output method.

If a processor chooses to implement an option for serialization, it must conform to the semantics defined in the [XML Serialization] specification.

Note

The use-character-maps parameter in [XML Serialization] specification has not been provided in the standard serialization options provided by this specification.

A Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1 Implementation-defined features

The following features are implementation-defined:

A.2 Implementation-dependent features

The following features are implementation-dependent:

B References

[XML Core Req] XML Processing Model Requirements. Dmitry Lenkov, Norman Walsh, editors. W3C Working Group Note 05 April 2004

[Infoset] XML Information Set (Second Edition). John Cowan, Richard Tobin, editors. W3C Working Group Note 04 February 2004.

[XML 1.0] Extensible Markup Language (XML) 1.0 (Fourth Edition). Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, et. al. editors. W3C Recommendation 16 August 2006.

[Namespaces 1.0] Namespaces in XML 1.0 (Second Edition). Tim Bray, Dave Hollander, Andrew Layman, et. al., editors. W3C Recommendation 16 August 2006.

[XML 1.1] Extensible Markup Language (XML) 1.1 (Second Edition). Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, et. al. editors. W3C Recommendation 16 August 2006.

[Namespaces 1.1] Namespaces in XML 1.1 (Second Edition). Tim Bray, Dave Hollander, Andrew Layman, et. al., editors. W3C Recommendation 16 August 2006.

[XPath 1.0] XML Path Language (XPath) Version 1.0. James Clark and Steve DeRose, editors. W3C Recommendation. 16 November 1999.

[XSLT 1.0] XSL Transformations (XSLT) Version 1.0. James Clark, editor. W3C Recommendation. 16 November 1999.

[XPath 2.0] XML Path Language (XPath) 2.0. Anders Berglund, Scott Boag, Don Chamberlin, et. al., editors. W3C Recommendation. 23 January 2007.

[XPath 2.0 Functions and Operators] XQuery 1.0 and XPath 2.0 Functions and Operators. Ashok Malhotra, Jim Melton, and Norman Walsh, editors. W3C Recommendation. 23 January 2007.

[XSLT 2.0] XSL Transformations (XSLT) Version 2.0. Michael Kay, editor. W3C Recommendation. 23 January 2007.

[XSL 1.1] Extensible Stylesheet Language (XSL) Version 1.1. Anders Berglund, editor. W3C Recommendation. 5 December 2006.

[XQuery 1.0] XQuery 1.0: An XML Query Language. Scott Boag, Don Chamberlin, Mary Fernández, et. al., editors. W3C Recommendation. 23 January 2007.

[RELAX NG] ISO/IEC JTC 1/SC 34. ISO/IEC FDIS 19757-2:2002(E) Document Schema Definition Languages (DSDL) — Part 2: Grammar-based validation — RELAX NG 2002.

[RELAX NG DTD Compatibility] RELAX NG DTD Compatibility. OASIS Committee Specification. 3 December 2001.

[Schematron] ISO/IEC JTC 1/SC 34. ISO/IEC FDIS 19757-2:2002(E) Document Schema Definition Languages (DSDL) — Part 3: Rule-based validation — Schematron 2004.

[W3C XML Schema: Part 1] XML Schema Part 1: Structures Second Edition. Henry S. Thompson, David Beech, Murray Maloney, et. al., editors. World Wide Web Consortium, 28 October 2004.

[W3C XML Schema: Part 2] XML Schema Part 2: Structures Second Edition. Paul V. Biron and Ashok Malhotra, editors. World Wide Web Consortium, 28 October 2004.

[xml:id] xml:id Version 1.0. Jonathan Marsh, Daniel Veillard, and Norman Walsh, editors. W3C Recommendation. 9 September 2005.

[XInclude] XML Inclusions (XInclude) Version 1.0 (Second Edition). Jonathan Marsh, David Orchard, and Daniel Veillard, editors. W3C Recommendation. 15 November 2005.

[XML Base] XML Base. Jonathan Marsh, editor. W3C Recommendation. 27 June 2001.

[XPointer Framework] XPointer Framework. Paul Grosso, Eve Maler, Jonathan Marsh, et. al., editors. W3C Recommendation. 25 March 2003.

[XPointer element() Scheme] XPointer element() Scheme. Paul Grosso, Eve Maler, Jonathan Marsh, et. al., editors. W3C Recommendation. 25 March 2003.

[XML Serialization] XSLT 2.0 and XQuery 1.0 Serialization. Scott Boag, Michael Kay, Joanne Tong, Norman Walsh, and Henry Zongaro, editors. W3C Recommendation. 23 January 2007.

[RFC 1521] RFC 1521: MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies. N. Borenstein, N. Freed, editors. Internet Engineering Task Force. September, 2003.

[RFC 2616] RFC 2616: Hypertext Transfer Protocol — HTTP/1.1. R. Fielding, J. Gettys, J. Mogul, et. al., editors. Internet Engineering Task Force. June, 1999.

[RFC 2617] RFC 2617: HTTP Authentication: Basic and Digest Access Authentication. J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart. June, 1999 .

[RFC 3023] RFC 3023: XML Media Types. M. Murata, S. St. Laurent, and D. Kohn, editors. Internet Engineering Task Force. January, 2001.

[RFC 3548] RFC 3548: The Base16, Base32, and Base64 Data Encodings. S. Josefsson, Editor. Internet Engineering Task Force. July, 2003.

[RFC 3986] RFC 3986: Uniform Resource Identifier (URI): General Syntax. T. Berners-Lee, R. Fielding, and L. Masinter, editors. Internet Engineering Task Force. January, 2005.

[RFC 3987] RFC 3987: Internationalized Resource Identifiers (URIs). M. Duerst and M. Suignard, editors. Internet Engineering Task Force. January, 2005.

[IANA Media Types] IANA MIME Media Types . Internet Engineering Task Force.

C The XProc Media Type

This appendix registers a new MIME media type, “application/xproc+xml”.

C.1 Registration of MIME media type application/xproc+xml

MIME media type name:

application

MIME subtype name:

xproc+xml

Required parameters:

None.

Optional parameters:
charset

This parameter has identical semantics to the charset parameter of the application/xml media type as specified in [RFC 3023] or its successors.

Encoding considerations:

The XProc syntax is XML; it has the same considerations when sent as “application/xproc+xml” as does XML. See [RFC 3023], Section 3.2.

Security considerations:

XProc elements may refer to arbitrary URIs. In this case, the security issues of [RFC 3986], section 7, should be considered.

Interoperability considerations:

None.

Published specification:

This media type registration is for XProc documents as described by this document.

Applications which use this media type:

There is no experimental, vendor specific, or personal tree predecessor to “application/xproc+xml”, reflecting the fact that no applications currently recognize it. This new type is being registered in order to allow for the deployment of XProc on the World Wide Web, as a first class XML application.

Additional information:
Magic number(s):

There is no single initial octet sequence that is always present in XProc documents.

File extension(s):

XProc documents are most often identified with the extension “.xpl”.

Macintosh File Type Code(s):

TEXT

Person & email address to contact for further information:

The XML Processing Model Working Group at the W3C, .

Intended usage:

COMMON

Author/Change controller:

The XProc specification is a work product of the XML Processing Model Working Group at the W3C.

C.2 Fragment Identifiers

The fragment identifier notation for documents labeled “application/xproc+xml” is an extension of the [XPointer Framework].

  1. If the fragment identifier is a SchemeBased pointer, then the semantics are determined by the relevant XPointer scheme. Only the [XPointer element() Scheme] is mandated by this specification.

  2. If the fragment identifier begins with a slash (“/”) and consists of one or more slash-separated strings then each string is interpreted as the name of a step. The first such string identifies the first step (in document order) with the specified name. The second and subsequent strings, if present, identify the first step with the specified name within the descendants of the currently identified step. If no step is identified by the sequence of names, the pointer is in error.

    For the purposes of pointer resolution, the defaulted names must be supported.

  3. If the fragment identifier is a Shorthand pointer, then it has the semantics of an [XPointer Framework] shorthand pointer.

  4. Any other pointer is in error.

D Glossary

Namespaces in XML

Unless otherwise noted, the term Namespaces in XML refers equally to [Namespaces 1.0] and [Namespaces 1.1].

QName

In the context of XProc, a QName is almost always a QName in the Namespaces in XML sense. Note, however, that p:option and p:parameter values can get their namespace declarations in a non-standard way (with p:namespaces) and QNames that have no prefix are always in no-namespace, irrespective of the default namespace.

XML

XProc is intended to work equally well with [XML 1.0] and [XML 1.1]. Unless otherwise noted, the term “XML” refers equally to both versions.

atomic step

An atomic step is a step that performs a unit of XML processing, such as XInclude or transformation, and has no internal subpipeline.

binding

A binding associates an input or output port with some data source.

by URI

A document is specified by URI if it is referenced with a URI.

by source

A document is specified by source if it references a specific port on another step.

compound step

A compound step is a step that contains one or more subpipelines. That is, a compound step differs >From an atomic step in that its semantics are at least partially determined by the steps that it contains.

contained steps

The steps that occur directly inside a compound step are called contained steps.

container

A compound step which immediately contains another step is called its container.

declared inputs

The input ports declared on a step are its declared inputs.

declared options

The options declared on a step are its declared options.

declared outputs

The output ports declared on a step are its declared outputs.

default readable port

The default readable port, which may be undefined, is a specific step name/port name pair from the set of readable ports.

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

empty environment

The empty environment contains no readable ports, no in-scope options, and an undefined default readable port.

empty sequence

An empty sequence of documents is specified with the p:empty element.

environment

The environment of a step is the static information available to each instance of a step in a pipeline.

expanded pipeline name

The expanded pipeline name of a pipeline is the expanded name denoted by its type, if it has one, otherwise the expanded name specified by the namespace of its containing pipeline-library and its name.

extension element

An extension element is any element that is not in the XProc namespace and is not a step.

extension attribute

An element from the XProc namespace may have any attribute not from the XProc namespace, provided that the expanded-QName of the attribute has a non-null namespace URI. Such an attribute is called an extension attribute.

ignorable element

Any element in an ignored namespace is an ignorable element.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.

in-scope options

The in-scope options are the set of options that are visible to a step.

inherited environment

The inherited environment of a contained step is an environment that is the same as the environment of its container with the standard modifications.

inline document

An inline document is specified directly in the body of the element that binds it.

last step

The last step in a subpipeline is the last step in document order within its container.

matches

A step matches its signature if and only if it specifies an input for each declared input, it specifies no inputs that are not declared, it specifies an option for each option that is declared to be required, and it specifies no options that are not declared.

option

An option is a name/value pair where the name is an expanded name and the value must be a string.

parameter

A parameter is a name/value pair where the name is an expanded name and the value must be a string.

parameter input port

A parameter input port is a distinguished kind of input port which accepts (only) dynamically constructed parameter name/value pairs.

pipeline

A pipeline is a set of connected steps, outputs flowing into inputs, without any loops (no step can read its own output, directly or indirectly).

primary input port

If a step has a document input port which is explicitly marked “primary='true'”, or if it has exactly one document input port and that port is not explicitly marked “primary='false'”, then that input port is the primary input port of the step.

primary output port

If a step has a document output port which is explicitly marked “primary='true'”, or if it has exactly one document output port and that port is not explicitly marked “primary='false'”, then that output port is the primary output port of the step.

primary parameter input port

If a step has a parameter input port which is explicitly marked “primary='true'”, or if it has exactly one parameter input port and that port is not explicitly marked “primary='false'”, then that parameter input port is the primary parameter input port of the step.

readable ports

The readable ports are the step name/output port name pairs that are visible to the step.

signature

The signature of a step is the set of inputs, outputs, and options that it is declared to accept.

specified options

The options on a step which have specified values, either because a p:option element specifies a value or because the declaration included a default value, are its specified options.

static error

A static error is one which can be detected before pipeline evaluation is even attempted.

step

A step is the basic computational unit of a pipeline.

subpipeline

The steps (and the connections between them) within a compound step form a subpipeline.

E Pipeline Language Summary

This appendix summarizes the XProc pipeline language. Machine readable descriptions of this language are available in RELAX NG (and the RELAX NG compact syntax), W3C XML Schema, and DTD syntaxes.

<p:pipeline
  name? = NCName
  type? = QName
  ignore-prefixes? = prefix list>
    (p:input |
     p:output |
     p:option |
     p:import |
     p:declare-step |
     p:log |
     p:serialization)*,
    subpipeline
</p:pipeline>

<p:for-each
  name? = NCName>
    (p:iteration-source?,
     (p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:for-each>

<p:viewport
  name? = NCName
  match = XSLT Match pattern>
    ((p:viewport-source?,
      p:output?,
      p:log?,
      p:option*),
     subpipeline)
</p:viewport>

<p:choose
  name? = NCName>
    (p:xpath-context?,
     p:when*,
     p:otherwise?)
</p:choose>

<p:xpath-context>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?
</p:xpath-context>

<p:when
  name? = NCName
  test = XPath expression>
    (p:xpath-context?,
     (p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:when>

<p:otherwise
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:otherwise>

<p:group
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:group>

<p:try
  name? = NCName>
    (p:group,
     p:catch)
</p:try>

<p:catch
  name? = NCName>
    ((p:output |
      p:option |
      p:log)*,
     subpipeline)
</p:catch>

<pfx:other-atomic-step
  name? = NCName>
    (p:input |
     p:option |
     p:parameter |
     p:log)*
</pfx:other-atomic-step>

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind? = "document" />

<p:input
  port = NCName
  select? = XPath expression>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:input>

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind = "parameter" />

<p:iteration-source
  select? = XPath expression>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:iteration-source>

<p:viewport-source>
    (p:pipe |
     p:document |
     p:inline)?
</p:viewport-source>

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean />

<p:output
  port = NCName
  sequence? = boolean
  primary? = boolean>
    (p:empty |
     (p:pipe |
      p:document |
      p:inline)+)?
</p:output>

<p:log
  port = NCName
  href? = anyURI />

<p:serialization
  port = NCName
  byte-order-mark? = boolean
  cdata-section-elements? = NMTOKENS
  doctype-public? = string
  doctype-system? = string
  encoding? = string
  escape-uri-attributes? = boolean
  include-content-type? = boolean
  indent? = boolean
  media-type? = string
  method? = QName
  normalization-form? = NFC|NFD|NFKC|NFKD|fully-normalized|none
  omit-xml-declaration? = boolean
  standalone? = true|false|omit
  undeclare-prefixes? = boolean
  version? = string />

<p:option
  name = QName
  required? = boolean />

<p:option
  name = QName
  select = XPath expression
  required? = boolean>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?,
    p:namespaces*
</p:option>

<p:option
  name = QName
  value = string
  required? = boolean>
    p:namespaces*
</p:option>

<p:parameter
  name = QName
  select = XPath expression
  port? = NCName>
    (p:empty |
     p:pipe |
     p:document |
     p:inline)?,
    p:namespaces*
</p:parameter>

<p:parameter
  name = QName
  value = string
  port? = NCName>
    p:namespaces*
</p:parameter>

<p:namespaces
  option? = QName
  element? = XPath expression
  except-prefixes? = prefix list />

<p:declare-step
  name? = NCName
  type = QName>
    (p:input |
     p:output |
     p:option)*
</p:declare-step>

<p:pipeline-library
  namespace? = anyURI
  name? = NCName
  ignore-prefixes? = prefix list>
    (p:import |
     p:declare-step |
     p:pipeline)*
</p:pipeline-library>

<p:import
  href = anyURI />

<p:pipe
  step = NCName
  port = NCName />

<p:inline>
    anyElement
</p:inline>

<p:document
  href = anyURI />

<p:empty />

<p:documentation>
    any-well-formed-content*
</p:documentation>

The core steps are also summarized here.

<p:declare-step type="p:add-attribute">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="attribute-name" required="true"/>
     <p:option name="attribute-value" required="true"/>
</p:declare-step>

<p:declare-step type="p:add-xml-base">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="all" value="false"/>
     <p:option name="relative" value="true"/>
</p:declare-step>

<p:declare-step type="p:count">
     <p:input port="source" sequence="true"/>
     <p:output port="result"/>
</p:declare-step>

<p:declare-step type="p:delete">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

<p:declare-step type="p:directory-list">
     <p:output port="result"/>
     <p:option name="path" value="."/>
     <p:option name="filter"/>
</p:declare-step>

<p:declare-step type="p:equal">
     <p:input port="source" primary="true"/>
     <p:input port="alternate"/>
     <p:output port="result" primary="false"/>
     <p:option name="fail-if-not-equal" value="false"/>
</p:declare-step>

<p:declare-step type="p:error">
     <p:option name="code" required="true"/>
     <p:option name="description" required="true"/>
</p:declare-step>

<p:declare-step type="p:escape-markup">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
     <p:option name="version" value="1.0"/>
</p:declare-step>

<p:declare-step type="p:http-request">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="byte-order-mark"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="normalization-form"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
</p:declare-step>

<p:declare-step type="p:identity">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true"/>
</p:declare-step>

<p:declare-step type="p:insert">
     <p:input port="source" primary="true"/>
     <p:input port="insertion"/>
     <p:output port="result"/>
     <p:option name="match"/>
     <p:option name="position" required="true"/>
</p:declare-step>

<p:declare-step type="p:label-elements">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="select"/>
     <p:option name="prefix"/>
     <p:option name="suffix"/>
</p:declare-step>

<p:declare-step type="p:load">
     <p:output port="result"/>
     <p:option name="href" required="true"/>
     <p:option name="validate"/>
</p:declare-step>

<p:declare-step type="p:make-absolute-uris">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="base-uri"/>
</p:declare-step>

<p:declare-step type="p:namespace-rename">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="elements-only"/>
     <p:option name="from"/>
     <p:option name="to"/>
</p:declare-step>

<p:declare-step type="p:parameters">
     <p:input port="parameters" kind="parameter" primary="false" sequence="true"/>
     <p:output port="result" sequence="true" primary="false"/>
</p:declare-step>

<p:declare-step type="p:rename">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="new-name" required="true"/>
</p:declare-step>

<p:declare-step type="p:replace">
     <p:input port="source" primary="true"/>
     <p:input port="replacement"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

<p:declare-step type="p:set-attributes">
     <p:input port="source" primary="true"/>
     <p:input port="attributes"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

<p:declare-step type="p:sink">
     <p:input port="source" sequence="true"/>
</p:declare-step>

<p:declare-step type="p:split-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="matched" sequence="true" primary="true"/>
     <p:output port="not-matched" sequence="true"/>
     <p:option name="test" required="true"/>
</p:declare-step>

<p:declare-step type="p:string-replace">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
     <p:option name="replace" required="true"/>
</p:declare-step>

<p:declare-step type="p:store">
     <p:input port="source"/>
     <p:output port="result" primary="false"/>
     <p:option name="href"/>
     <p:option name="byte-order-mark"/>
     <p:option name="cdata-section-elements"/>
     <p:option name="doctype-public"/>
     <p:option name="doctype-system"/>
     <p:option name="encoding"/>
     <p:option name="escape-uri-attributes"/>
     <p:option name="include-content-type"/>
     <p:option name="indent" value="false"/>
     <p:option name="media-type"/>
     <p:option name="method" value="xml"/>
     <p:option name="normalization-form"/>
     <p:option name="omit-xml-declaration"/>
     <p:option name="standalone"/>
     <p:option name="undeclare-prefixes"/>
     <p:option name="version" value="1.0"/>
</p:declare-step>

<p:declare-step type="p:unescape-markup">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="namespace"/>
     <p:option name="content-type"/>
     <p:option name="encoding"/>
     <p:option name="charset"/>
</p:declare-step>

<p:declare-step type="p:unwrap">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="match" required="true"/>
</p:declare-step>

<p:declare-step type="p:wrap">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="wrapper" required="true"/>
     <p:option name="match" required="true"/>
     <p:option name="group-adjacent"/>
</p:declare-step>

<p:declare-step type="p:wrap-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true"/>
     <p:option name="wrapper" required="true"/>
     <p:option name="group-adjacent"/>
</p:declare-step>

<p:declare-step type="p:xinclude">
     <p:input port="source"/>
     <p:output port="result"/>
</p:declare-step>

<p:declare-step type="p:xslt">
     <p:input port="source" primary="true"/>
     <p:input port="stylesheet"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result"/>
</p:declare-step>

As are the optional steps.

<p:declare-step type="p:validate-relax-ng">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
     <p:option name="dtd-compatibility" value="false"/>
</p:declare-step>

<p:declare-step type="p:validate-schematron">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
</p:declare-step>

<p:declare-step type="p:validate-xml-schema">
     <p:input port="source" primary="true"/>
     <p:input port="schema" sequence="true"/>
     <p:output port="result"/>
     <p:option name="assert-valid" value="true"/>
     <p:option name="mode" value="strict"/>
</p:declare-step>

<p:declare-step type="p:xslt2">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="stylesheet"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="true"/>
     <p:output port="secondary" sequence="true"/>
     <p:option name="initial-mode"/>
     <p:option name="template-name"/>
     <p:option name="allow-version-mismatch" value="true"/>
     <p:option name="output-base-uri"/>
     <p:option name="allow-collections" value="true"/>
</p:declare-step>

<p:declare-step type="p:xsl-formatter">
     <p:input port="source"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="false"/>
     <p:option name="uri" required="true"/>
     <p:option name="output"/>
</p:declare-step>

<p:declare-step type="p:xquery">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="query"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" sequence="true"/>
</p:declare-step>

And the step vocabulary elements.

<c:parameter
  name = QName
  namespace? = anyURI
  value = string />

<c:parameter-set>
    c:parameter*
</c:parameter-set>

<c:result>
    string
</c:result>

<c:http-request
  method? = NCName
  href? = anyURI
  detailed? = boolean
  status-only? = boolean
  username? = string
  password? = string
  auth-method? = string
  send-authorization? = boolean
  override-content-type? = string>
    (c:header*,
     (c:multipart |
      c:body)?)
</c:http-request>

<c:header
  name = string
  value? = string />

<c:multipart
  content-type? = string>
    c:body+
</c:multipart>

<c:body
  content-type = string
  encoding? = string
  id? = string
  description? = string>
    anyElement*
</c:body>

<c:http-response
  status? = integer>
    (c:header*,
     (c:multipart |
      c:body)?)
</c:http-response>

<c:query>
    string
</c:query>