XProc: An XML Pipeline Language

2.1 Steps

[Definition: A step is the basic computational unit of a pipeline. 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.] Atomic steps can perform arbitrary amounts of computation but they are indivisible. Atomic steps carry out fundamental XML operations. 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.

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 additional steps. 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 zero or more steps. [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.]

[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. ]

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

Steps have “ports” into which inputs and outputs are connected. Each step has a number of input ports and a number of output ports, all with unique names. A step can have zero input ports and/or zero output ports. (All steps have an implicit standard output port for reporting errors that must not be declared.)

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

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

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 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 disk—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 or pipeline.

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.

Figure 3. An atomic step

Each step declares its input and output ports. [Definition: The input ports declared on a step are its declared inputs.] [Definition: The output ports declared on a step are its declared outputs.]

All of the declared inputs of a step (atomic or compound) must be connected. Inputs may be connected to:

Unconnected output ports are allowed; any documents produced on those ports are simply discarded.

For atomic steps, the inputs and outputs are declared once (with p:declare-step) for each type of atomic step and every instance of that type has the same inputs and outputs. For example, every XSLT step has exactly the same inputs and outputs with the same names.

The situation is slightly more complicated for compound steps. Compound steps don't typically have declared inputs, but they do have declared outputs. 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.

Figure 4. A compound step

Output ports on compound steps have a dual nature: from the perspective of the compound step's siblings, it's outputs are just outputs and they can either be connected up or not. 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 a compound step can be connected to:

Each step may have a default output port. [Definition: If a step has exactly one output port, or if one of its output ports is explicitly designated as the default, then that output port is the default output port of the step.] If a step has more than one output port and none is explicitly designated the default, then the default output port of that step is undefined.

Each input and output is declared to accept or produce either a single document or a sequence of documents. It is not a static 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, a dynamic error if the former step actually produces more than a single document at run time.

[Definition: The signature of a step is the set of inputs, outputs, options, and parameters 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 signature declared locally.

[Definition: A step matches its signature if and only if it specifies an input for each declared input and it specifies no inputs that are not declared; it specifies no options that are not declared; it specifies a parameter for each parameter that is declared to be required; and it specifies no parameters that are not declared.] In other words, every input and required parameter must be specified and only inputs, outputs, options, and parameters that are declared may be specified. Outputs and optional parameters do not have to be specified.

Steps may also produce error, warning, and informative messages. These messages appear on a special “error output” port defined (only) in the catch clause of a try/catch.

2.3 Options and parameters

Some steps accept options and/or parameters. Both are name/value pairs. The distinction between options and parameters is simply that options are used by the XProc processor to configure the step; the step never sees them. Parameters are passed to the step for its use, the XProc processor does not use them.

[Definition: An option is a name/value pair.] The name of an option must be an expanded name. The value of an option 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.]

[Definition: A parameter is a name/value pair.] The name of a parameter must be an expanded name. The value of a parameter 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 parameters declared on a step are its declared parameters.]

2.4 Connections

Steps are connected together by their input ports and output ports. 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.

2.5 Environment

[Definition: The environment of a step is the static information available to that step.]

The environment consists of:

[Definition: The empty environment contains no readable ports, no in-scope parameters, an undefined default readable port, and an empty set of ignored namespaces.]

Unless otherwise specified, the environment of each step is its inherited environment, the environment of its parent, with the following standard modifications:

A step with no parent inherits the empty environment.

Unless otherwise specified, the inherited environment for the contained steps of a compound step is the standard inheritance, which is the environment of that compound step, with the following modification:

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

3.1 Scoping of Names

The scope of the names of step types is the pipeline. Each pipeline processor has some number of built in step types and may declare (directly, or by reference to an external library) additional step types.

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 in-scope steps must have unique names: it is a static error 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 appear.

The scope of parameter names is essentially the same as the scope of step names, with the following caveat. Whereas step names must be unique, parameter names may be repeated. The declaration of a parameter on a step shadows any declaration that may already be in-scope.

3.2 Global Attributes

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

The following attributes may appear on any step element:

3.3 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 three ways: by source, by URI, or by providing it inline. Each of these mechanisms is supported on the p:input, p:output, p:xpath-context, p:iteration-source, and p:viewport-source elements.

Note that an 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.

3.4 Ignored namespaces

The element children of a compound step fall into four classes: elements that provide bindings for input and output ports, elements that provide bindings for options and parameters, other elements that identify steps that are part of its subpipeline, and extension elements. Extension elements may be used for documentation or to provide additional information for a specific processor.

To determine which elements are extension elements and which are expected to identify steps, a set of ignored namespaces is maintained in the environment of each step.

The ignored namespaces are a set of namespaces which do not identify steps. They are ignored by the processor unless the processor happens to recognize one or more of them as extension elements. The initial set of ignored namespaces is empty.

Syntactically, a pipeline author can add namespaces to the set of ignored namespaces with the p:ignore-prefixes attribute. This attribute can appear on any element in the pipeline namespace which identifies a step. It is a static error if the p:ignore-prefixes attribute appears on any element which does not identify a step.

The value of the p: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 if any token specified in the p:ignore-prefixes attribute is not the prefix of an in-scope namespace.

Each of the namespaces identified by the specified prefix is added to the set of ignored namespaces in the environment of the step on which the attribute occurs.

3.5 Documentation

Pipeline authors may add documentation to their pipeline documents with the p:doc element. Except when it appears as a descendant of p:inline, the p:doc element is completely ignored by pipeline processors, it exists simply for documentation purposes. (If a p:doc 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:doc elements and behave differently on the basis of what they find are not conformant. Processor extensions must be specified with extension elements.

3.6 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.] 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.7 Extension elements

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.

There are three contexts in which an extension element might occur:

3.8 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:

4.1 Pipeline

A Pipeline is specified by the p:pipeline element. It encapsulates the behavior of a subpipeline. Its children declare the inputs, outputs, and parameters 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.

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

Viewed from the outside, a 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 of a pipeline is its inherited environment with the standard modifications.

The environment inherited by its contained steps is the empty environment with these modifications:

If there is no binding for any of the declared outputs of the pipeline, then those outputs are bound to the default output port of the last step in the subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

There are two additional constraints on pipelines:

<p:pipeline name="pipeline" xmlns:p="http://www.w3.org/2007/03/xproc">
<p:input port="document"/>
<p:input port="stylesheet"/>
<p:output port="result"/>

<p:xinclude>
  <p:input port="source">
    <p:pipe step="pipeline" port="document"/>
  </p:input>
</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 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
  select? = xpath expression
  p:ignore-prefixes? = prefix list>
   (p:iteration-source?,
    (p:output |
    p:parameter)*,
    subpipeline)
</p:for-each>

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

The result of the for-each is a sequence of documents produced by processing each individual document in the input sequence. If the subpipeline is connected to one or more output ports on the for-each, what appears on each of those ports is the sequence of documents produced by each iteration of the loop.

The p:iteration-source is an anonymous input: its binding provides a sequence of documents to the 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 of a for-each is its inherited environment with the standard modifications.

The environment inherited by its contained steps is the standard inheritance with these modifications:

If there is no binding for any of the declared outputs of the for-each, then those outputs are bound to the default output port of the last step in the subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

<p:for-each name="chapters" 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="stylesheet">
      <p:document href="http://example.com/xsl/fo.xsl"/>
    </p:input>
  </p:xslt>
</p:for-each>

4.3 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 = xpath expression
  p:ignore-prefixes? = prefix list>
   (p:viewport-source?,
    p:output,
    p:parameter*,
    subpipeline)
</p:viewport>

The result of the 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 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. After a node has been matched, its descendants are not considered for further matching. In other words, a node is passed at most once to the 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 if the viewport source is a sequence of more than one document or if the output from any iteration is a sequence of more than one document.

The environment of a viewport is its inherited environment with the standard modifications.

The environment inherited by its contained steps is the standard inheritance with this modification:

If there is no binding for any of the declared outputs of the viewport, then those outputs are bound to the default output port of the last step in the subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

<p:viewport match="h:div[@class='chapter']">
  <p:output port="result"/>
  <p:insert>
    <p:input port="insertion">
      <p:inline>
        <hr xmlns="http://www.w3.org/1999/xhtml"/>
      </p:inline>
    </p:input>
    <p:option name="at-start" value="true"/>
  </p:insert>
</p:viewport>

4.4 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:ignore-prefixes? = prefix list>
   (p:xpath-context?,
    p:when*,
    p:otherwise?)
</p:choose>

A 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, each guarded by an XPath expression (with an associated context), followed optionally by a single default subpipeline.

The 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 choose is the result of the selected subpipeline.

In order to ensure that the result of the choose is consistent irrespective of the subpipeline chosen, each subpipeline must declare the same number outputs with the same names. It is a static error if two subpipelines in a choose declare different outputs.

It is a dynamic error if no subpipeline is selected by the 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 xpath-context. If no binding is provided, the default xpath-context is the document on the default readable port.

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

The environment of a choose is its inherited environment with the standard modifications.

Each conditional subpipeline is represented by a p:when element.

<p:when
  test = expression
  p:ignore-prefixes? = prefix list>
   (p:xpath-context?,
    (p:output |
    p:parameter)*,
    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.

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 xpath-context. If no context is specified on the p:when, the context of the p:choose is used. It is a static error if no context is specified in either the p:choose or the p:when and the default readable port is undefined.

The default branch is represented by a p:otherwise element.

<p:otherwise>
   ((p:output |
    p:parameter)*,
    subpipeline)
</p:otherwise>

The environment of the selected subpipeline is the inherited environment with the standard modifications.

The environment inherited by its contained steps is the standard inheritance.

If there is no binding for any of the declared outputs of the selected subpipeline, then those outputs are bound to the default output port of the last step in the selected subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

<p:choose name="version">
  <p:when test="/*[@version = 2]">
    <p:output port="result"/>
    <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:output port="result"/>
    <p:validate-xml-schema>
      <p:input port="schema">
        <p:document href="v1schema.xsd"/>
      </p:input>
    </p:validate-xml-schema>
  </p:when>

  <p:otherwise>
    <p:output port="result"/>
    <p:identity/>
  </p:otherwise>
</p:choose>

4.5 Group

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

<p:group
  name? = NCName
  p:ignore-prefixes? = prefix list>
   ((p:output |
    p:parameter)*,
    subpipeline)
</p:group>

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

The environment of a group is its inherited environment with the standard modifications.

The environment inherited by its contained steps is the standard inheritance.

If there is no binding for any of the declared outputs of the group, then those outputs are bound to the default output port of the last step in the subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

<p:pipeline name="pipeline" xmlns:p="http://www.w3.org/2007/03/xproc">
<p:input port="document"/>
<p:input port="config"/>
<p:output port="result"/>

<p:group>
  <p:parameter name="profile" select="/config/profile">
    <p:pipe step="pipeline" port="config"/>
  </p:parameter>
  <p:output port="result"/>

  <p:choose>
    <p:when test="/config/output = 'fo'">
      <p:xpath-context>
        <p:pipe step="pipeline" port="config"/>
      </p:xpath-context>
      <p:output port="result"/>
      <p:xslt>
        <p:input port="source">
          <p:pipe step="pipeline" port="document"/>
        </p:input>
        <p:input port="stylesheet">
          <p:document href="http://example.com/style/fo.xsl"/>
        </p:input>
        <p:parameter name="profile" select="$profile"/>
      </p:xslt>
    </p:when>
    <p:otherwise>
      <p:output port="result"/>
      <p:xslt>
        <p:input port="source">
          <p:pipe step="pipeline" port="document"/>
        </p:input>
        <p:input port="stylesheet">
          <p:document href="http://example.com/style/xhtml.xsl"/>
        </p:input>
        <p:parameter name="profile" select="$profile"/>
      </p:xslt>
    </p:otherwise>
  </p:choose>
</p:group>

</p:pipeline>

4.6 Try/Catch

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

<p:try
  name? = NCName
  p:ignore-prefixes? = prefix list>
   (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 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 try step. If the recovery subpipeline is evaluated and a step within that subpipeline fails, the try fails.

In order to ensure that the result of the 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. It is a static error if the p:group and p:catch subpipelines declare different outputs.

The environment of a try is its inherited environment with the standard modifications.

The environment inherited by its initial subpipeline, the p:group, is the environment of the try.

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

<p:catch
  p:ignore-prefixes? = prefix list>
   ((p:output |
    p:parameter)*,
    subpipeline)
</p:catch>

The environment of a p:catch is the environment of its containing p:try.

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

If there is no binding for any of the declared outputs of the catch, then those outputs are bound to the default output port of the last step in the subpipeline. It is a static error if an output is bound to the default output port and the default output port is undefined.

<p:try>
  <p:group>
    <p:output port="result"/>
    <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:output port="result"/>
    <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.

<pfx:other-step
  name? = NCName
  p:ignore-prefixes? = prefix list>
   ((p:input |
    p:output |
    p:option |
    p:import-parameter |
    p:parameter)*,
    subpipeline?)
</pfx:other-step>

Each of these steps must have been declared with p:declare-step or it must be the name of an imported p:pipeline (or a p:pipeline in the same library).

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

The environment of such a step is its inherited environment with the standard modifications.

If the step element 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 is the name of a p:pipeline, then that step runs the named pipeline.

5.1 p:input Element

A p:input identifies input for a step, optionally declaring it, if necessary.

<p:input
  port = NCName
  sequence? = yes|no />

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

On compound steps and p:declare-step, an input declaration can indicate if a sequence of documents is allowed to appear on the port. If sequence is specified with the value “yes”, then a sequence is allowed. If sequence is not specified on p:input, or has the value “no”, then it is a dynamic error for a sequence of more than one document to appear on the declared port.

The declaration may be accompanied by a binding for the input:

<p:input
  port = NCName
  sequence? = yes|no
  select? = xpath expression>
   (p:pipe |
    p:document |
    p:inline)*
</p:input>

If a binding is provided, a select expression may also be provided. The select expression, if specified, applies the specified [XPath 1.0] select expression to the document(s) that are read. Each node that matches is wrapped in a document and provided to the input port. After a node has been matched, its descendants are not considered for further matching; a node is passed at most once as input. 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 matching html:div (that is not itself a descendant of an html:div) in http://example.org/input.html.

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 matching html:div in the document (or each of the documents) that is read from the portname port of the step named origin.

In contexts where a binding is required, an empty p:input is bound to an empty sequence of documents.

5.2 p:iteration-source Element

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

<p:iteration-source
  select? = xpath expression>
   (p:pipe |
    p:document |
    p:inline)*
</p:iteration-source>

The select attribute and binding elements 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 viewport.

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

Exactly one binding element is allowed and it works the same way that binding elements work in a p:input. No select expression is allowed.

5.4 p:xpath-context Element

A p:xpath-context identifies a context against which an [XPath 1.0] expression will be evaluated for a p:when.

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

Exactly one binding element is allowed and it works the same way that binding elements work in a p:input. No select expression is allowed.

5.5 p:output Element

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

<p:output
  port = NCName
  sequence? = yes|no
  default? = yes|no />

The port attribute defines the name of the port. It is a static error to identify two ports with the same name on the same step. It is a static error 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 “yes”, then a sequence is allowed. If sequence is not specified on p:output, or has the value “no”, then it is a dynamic error if the step produces a sequence of more than one document on the declared port.

An output declaration can indicate if it is to be considered the default output for the step. If default is specified with the value “yes”, then the named port will be treated as the default output port. It is a static error to identify two different output ports as the default.

It is a static error to specify default="no" on the p:output of a step which has exactly one output. In other words, if any step or step has exactly one output, that output is always the default output.

The declaration may be accompanied by a binding for the output.

<p:output
  port = NCName
  sequence? = yes|no
  default? = yes|no>
   (p:pipe |
    p:document |
    p:inline)*
</p:output>

5.6 p:option Element

The p:option element is used both to declare options and to establish values for them. When used on a p:declare-step or compound step, p:option declares the option and may associate a default value with it. Used elsewhere, p:option associates a value with the option.

Options are declared, used, and have values assigned in a manner exactly analogous to the p:parameter element.

5.7 p:parameter Element

The p:parameter element is used both to declare parameters and to establish values for them. When used on a p:declare-step or compound step, p:parameter declares the parameter and may associate a default value with it. Used elsewhere, p:parameter associates a value with the parameter.

5.8 p:import-parameter Element

An p:import-parameter provides a set of in-scope parameters to a step.

<p:import-parameter
  name = token />

All in-scope parameters which match the name are made available to the step as if they had been specified with individual p:parameter elements.

The name attribute must be a single asterisk (*), a QName, or a string of the form *:NCName or NCName:*.

5.9 p:declare-step Element

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

<p:declare-step
  type = QName
  p:ignore-prefixes? = prefix list>
   (p:input*,
    p:output*,
    p:option*,
    p:parameter*)
</p:declare-step>

It is a static error to identify an unrecognized step in a subpipeline. It is not an error to declare such a step, only to use it.

Exactly one input declaration of a p:declare-step may use the name “*” to indicate that the step accepts an arbitrary number of inputs.

Exactly one output declaration of a p:declare-step may use the name “*” to indicate that the step can produce an arbitrary number of outputs.

5.10 p:pipeline-library Element

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

<p:pipeline-library
  p:ignore-prefixes? = prefix list
  namespace? = URI>
   (p:import*,
    p:declare-step*,
    p:pipeline*)
</p:pipeline-library>

Libraries can import pipelines and/or other libraries. It is a static error 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 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">
  …
</p:pipeline>

<p:pipeline name="format">
  …
</p:pipeline>

</p:pipeline-library>

The pipelines named “validate” and “format” are in the namespace http://example.com/ns/pipelines. That means that those pipelines must be invoked from the importing pipeline with qualified names:

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

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

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.

5.11 p:import Element

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

<p:import
  href = URI />

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, options, and parameters declared on it.

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. It is a dynamic error to import a single pipeline if that pipeline does not have a name.

5.12 p:pipe Element

A p:pipe reads from the output port of another step.

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

The p:pipe element connects to the output port of another step. It identifies the output port two 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 if the port identified by a p:pipe is not in the readable ports of the environment of the step that contains the p:pipe.

It is a static error if the port identified by a p:pipe in the p:output of a compound step is not in the readable ports of the environment inherited by the contained steps of the compound step.

In other words, the output of a compound step must be bound to the output of one of its contained steps. All other bindings must be to ports that are already readable in the current environment.

5.13 p:inline Element

A p:inline provides a document or a sequence of documents 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.

It is a static error if the content of the p:inline element is not a well-formed XML document.

5.14 p:document Element

A p:document reads an XML document from a URI.

<p:document
  href = URI />

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

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.

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

Use the load step if you need to perform DTD-based validation or if you wish to load documents that are not namespace well-formed.

5.15 p:doc Element

A p:doc contains human-readable documentation.

<p:doc>
   any-well-formed-content
</p:doc>

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

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

• 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.

  Connections

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

  Scoping of Names

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

  Associating Documents with Ports

• It is a static error if the p:ignore-prefixes attribute appears on any element which does not identify a step.

  Ignored namespaces

• It is a static error if any token specified in the p:ignore-prefixes attribute is not the prefix of an in-scope namespace.

  Ignored namespaces

• It is a static error if an output is bound to the default output port and the default output port is undefined.

  Pipeline, For-Each, Viewport, Choose, Group, Try/Catch

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

  Choose

• It is a static error if no context is specified in either the p:choose or the p:when and the default readable port is undefined.

  Choose

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

  Try/Catch

• It is a static error if a pipeline contains a step that is not declared or imported or if the specified inputs, outputs, and parameters do not match the signature for steps of that type.

  Other Steps

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

  p:input Element, p:output Element

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

  p:input Element

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

  p:output Element

• It is a static error to identify two different output ports as the default.

  p:output Element

• It is a static error to specify default="no" on the p:output of a step which has exactly one output.

  p:output Element

• It is a static error to specify that the parameter is required or that it has a default value if the name given is not a QName.

  Declaring Parameters

• It is a static error to specify that the parameter is both required and has a default value.

  Declaring Parameters

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

  Declaring Parameters

• It is a static error if the variable reference uses a QName that is not the name of an in-scope parameter or if the reference is circular, either directly or indirectly.

  Assigning Values to Parameters

• It is a static error to identify an unrecognized step in a subpipeline.

  p:declare-step Element

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

  p:pipeline-library Element

• It is a static error if the port identified by a p:pipe in the p:output of a compound step is not in the readable ports of the environment inherited by the contained steps of the compound step.

  p:pipe Element

• It is a static error if the content of the p:inline element is not a well-formed XML document.

  p:inline Element

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 try is encountered or the entire pipeline fails. In other words, outside of a try, step failure causes the entire pipeline to fail.

Dynamic Errors

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

  Inputs and Outputs

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

  Associating Documents with Ports

• It is a dynamic error if the viewport source is a sequence of more than one document or if the output from any iteration is a sequence of more than one document.

  Viewport

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

  Choose

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

  Choose

• If sequence is not specified on p:input, or has the value “no”, then it is a dynamic error for a sequence of more than one document to appear on the declared port.

  p:input Element

• If sequence is not specified on p:output, or has the value “no”, then it is a dynamic error if the step produces a sequence of more than one document on the declared port.

  p:output Element

• It is a dynamic error if a document sequence is specified in the binding for a p:parameter.

  Assigning Values to Parameters

• 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.

  p:import Element

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

  p:import Element

• 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.

  p:document Element