XProc: An XML Pipeline Language

2.1 Steps

[Definition: A step is the basic computational unit of a pipeline.] A typical step has zero or more inputs, from which it receives XML documents to process, zero or more outputs, to which it sends XML document results, and can have options and/or parameters.

There are three kinds of steps: atomic, compound, and multi-container.

[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; a Validate with XML Schema 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. It is implementation-defined what additional step types, if any, are provided. 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 a subpipeline.] 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.

Finally, there are two “multi-container steps”: p:choose and p:try. [Definition: A multi-container step is a step that contains several alternate subpipelines. ] Each subpipeline is identified by a non-step wrapper element: p:when and p:otherwise in the case of p:choose, p:group and p:catch in the case of p:try.

The output of a multi-container step is the output of exactly one of its subpipelines. In this sense, a multi-container step functions like a compound step. However, evaluating a multi-container step may involve evaluating, or partially evaluating, more than one of its subpipelines. It's possible for steps in a partially evaluated pipeline to have side effects that are visible outside the processor, even if the final output of the multi-container step is the result of some other subpipeline. For example, a web server might record that some interaction was performed, or a file on the local file system might have been modified.

[Definition: A compound step or multi-container step is a container for the steps directly within it or within non-step wrappers directly within it.] [Definition: The steps that occur directly within, or within non-step wrappers directly within, a step are called that step's contained steps. In other words, “container” and “contained steps” are inverse relationships.] [Definition: The ancestors of a step, if it has any, are its container and the ancestors of its container.]

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

subpipeline = p:variable*, (p:for-each|p:viewport|p:choose|p:group|p:try|p:standard-step|pfx:user-pipeline)+

Steps have “ports” into which inputs and outputs are connected. 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”).

A Step may have zero or more options, all with unique names.

Steps may have parameter input ports, on which parameters can be passed. A step can have zero, one, or many parameter input ports, and each parameter input port can have zero or more parameters passed on it. If more than one parameter with the same name is passed to any given parameter input port, only the last value specified will be available to the step; the names of the parameters passed to the step are unique on each port. Parameters with the same name can be passed to different ports, the uniqueness constraint on names only applies to the parameters passed on each individual port.

All of the different instances of steps (atomic or compound) in a pipeline can be distinguished from one another by name. If the pipeline author does not provide a name for a step, a default name is manufactured automatically.

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.

For the purposes of this specification, an XML document is an [Infoset]. Implementations are free to transmit Infosets as sequences of characters, sequences of events, object models, or any other representation that preserves the necessary Infoset properties (see Section A.3, “Infoset Conformance”).

Most steps in this specification manipulate XML documents, or portions of XML documents. In these cases, we speak of changing elements, attributes, or nodes without prejudice to the actual representation used by an implementation.

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 data cannot arrive on an input port to a step.

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

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

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

Like atomic steps, top level, user-defined pipelines also have declarations. The situation is slightly more complicated for the other compound steps because they don't have separate declarations; each instance of the compound step serves as its own declaration. On these 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 subpipeline and 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

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

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

It is a static error (err:XS0003) if any declared input is not connected.

The declared outputs of a step may be connected to:

The primary output port of a step must be connected. It is a static error (err:XS0005) if the primary output port of any step is not connected. Other outputs can remain unconnected. Any documents produced on an unconnected output port are discarded.

Primary input and primary output ports may be implicitly connected if no explicit connection is given, see Section 2.3, “Primary Inputs and Outputs”.

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 subpipeline inside the compound step, they are inputs into which something may be connected.

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

If a (non-primary) output port of a compound step is left unconnected, it produces an empty sequence of documents from the perspective of its siblings.

Each input and output on a step 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.

It is also not an error to connect a port that is declared to produce a single document to a port that is declared to accept a sequence. A single document is the same as a sequence of one document.

An output port may have more than one connection: it may be connected to more than one input port, more than one of its container's output ports, or both. At runtime this will result in distinct copies of the output.

[Definition: The signature of a step is the set of inputs, outputs, and options that it is declared to accept.] The declaration for a step provides a fixed signature which all its instances share.

[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 are captured and provided on the error port inside of a p:catch. Outside of a try/catch, the disposition of error messages is implementation-dependent.

How inputs are connected to XML documents outside the pipeline is implementation-defined. In order to be consistent with the XPath data model, all general and external parsed entities in such documents must be fully expanded; they must not contain any representation of [Infoset] [unexpanded entity reference information items].

How pipeline outputs are connected to XML documents outside the pipeline is implementation-defined.

<p:store method="ext:binary" href="my.png">
  <p:input port="source">
    <p:inline>
      <c:data content-type="image/png">BASE64ENCODEDDATA</c:data>
    </p:inline>
  </p:input>
</p:store>

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. A step can have at most one primary input port.

[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. A step can have at most one primary output port.

The special significance of primary input and output ports is that they are connected automatically by the processor if no explicit connection 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 compound step has no declared outputs and the last step in its subpipeline has an unconnected primary output, then an implicit primary output port will be added to the compound step (and consequently the last step's primary output will be connected to it). This implicit output port has no name. It inherits the sequence property of the port connected to it. This rule does not apply to p:declare-step; step declarations must provide explicit names for all of their outputs.

2.4 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.5 Environment

[Definition: The environment is a context-dependent collection of information available within subpipelines.] Most of the information in the environment is static and can be computed for each subpipeline before evaluation of the pipeline as a whole begins. The in-scope bindings have to be calculated as the pipeline is being evaluated.

The environment consists of:

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

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:

A step with no parent inherits the empty environment.

2.6 XPaths in XProc

XProc uses XPath as an expression language. XPath expressions are evaluated by the XProc processor in several places: on compound steps, to compute the default values of options and the values of variables; on atomic steps, to compute the actual values of options and the values of parameters.

XPath expressions are also passed to some steps. These expressions are evaluated by the implementations of the individual steps.

This distinction can be seen in the following example:

<p:variable name="home" select="'http://example.com/docs'"/>

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

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

The select expression on the variable “home” is evaluated by the XProc processor. The value of the variable is “http://example.com/docs”.

The href option of the p:load 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 select expression on the source input of the p:split-sequence step is also evaluated by the XProc processor.)

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 variables, options, parameters, and inputs, in match attributes on p:viewport, and in test attributes on p:when steps.

An XProc implementation can use either [XPath 1.0] or [XPath 2.0] to evaluate these expressions.

Many, many expressions that are likely to be used in XProc pipelines are the same in both versions (simple element tests, ancestor and descendant tests, string-based attribute tests, etc.).

As an aid to interoperability, pipeline authors may indicate the version of XPath that they require. The attribute xpath-version may be used on p:pipeline, p:declare-step, or p:library to identify the XPath version that must be used to evaluate XPath expressions on the pipeline(s). The attribute is lexically scoped, but see below.

If an xpath-version is specified on a p:pipeline or p:declare-step, then that is the version of XPath that the step requires. If it does not specify a version, but a version is specified on one of its ancestors, the nearest ancestor version specified is the version that it requires. An xpath-version attribute on a p:library specifies a default version for all steps defined in that library. If no version is specified on the step or among its ancestors, then its XPath version is implementation-defined.

The following rules determine how the indicated version and the implementation's actual version interact:

XProc processors divide naturally into two classes: XPath 1.0 processors and XPath 2.0 processors.

Irrespective of which version of XPath is used, all expressions evaluated by XProc or passed to steps for evaluation must be valid XPath expressions. It is a dynamic error (err:XD0023) if an XPath expression is encountered which cannot be evaluated (because it is syntactically incorrect, contains references to unbound variables or unknown functions, or for any other reason).

2.7 XPath Extension Functions

The XProc processor must support the additional functions described in this section in XPath expressions evaluated by the processor.

In the following descriptions, the names of types (string, boolean, etc.) should be taken to mean the corresponding [W3C XML Schema: Part 2] data types for an implementation that uses XPath 2.0 and as the most appropriate XPath 1.0 types for an XPath 1.0 implementation.

<p:declare-step type="ex:dir-list">
  <p:output port="result"/>
  <p:option name="path"/>

  <p:choose>
    <p:when test="p:value-available('path')">
      <p:directory-list>
        <p:with-option name="path" select="$path"/>
      </p:directory-list>
    </p:when>
    <p:otherwise>
      <p:directory-list path="."/>
    </p:otherwise>
  </p:choose>
</p:declare-step>

2.8 PSVIs in XProc

XML documents flow between steps in an XProc pipeline. Section A.3, “Infoset Conformance” identifies the properties of those documents that must be available. Implementations may also have the ability to pass PSVI annotations between steps.

Whether or not the pipeline processor supports passing PSVI annotations between steps is implementation-defined. The exact PSVI properties that are preserved when documents are passed between steps is implementation-defined.

A pipeline can use the p:psvi-supported system property to determine whether or not PSVI properties can be passed between steps.

A pipeline can assert that PSVI support is required with the psvi-required attribute:

Many of the steps that an XProc pipeline can use are transformative in nature. The p:delete step, for example, can remove elements and attributes; the p:label-elements step can add attributes; etc. If PSVI annotations were always preserved, the use of such steps could result in documents that were inconsistent with their schema annotations.

In order to avoid these inconsistencies, most steps must not produce PSVI annotated results even when PSVI passing is supported.

If PSVI passing is supported, the following constraints apply:

2.9 Variables

Variables are name/value pairs. Pipeline authors can create variables to hold computed values.

[Definition: A variable is a name/value pair where the name is an expanded name and the value must be a string or xs:untypedAtomic.]

Variables and options share the same scope and may shadow each other.

2.10 Options

Some steps accept options. Options are name/value pairs, like variables. Unlike variables, the value of an option can be changed by the caller.

[Definition: An option is a name/value pair where the name is an expanded name and the value must be a string or xs:untypedAtomic.]

[Definition: The options declared on a step are its declared options.] 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:with-option element specifies a value or because the declaration included a default value, are its specified options.]

How outside values are specified for pipeline options on the pipeline initially invoked by the processor is implementation-defined. In other words, the command line options, APIs, or other mechanisms available to specify such options values are outside the scope of this specification.

2.11 Parameters

Some steps accept parameters. Parameters are name/value pairs, like variables and options. Unlike variables and 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 is a name/value pair where the name is an expanded name and the value must be a string or xs:untypedAtomic.]

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

How outside values are specified for pipeline parameters on the pipeline initially invoked by the processor is implementation-defined. In other words, the command line options, APIs, or other mechanisms available to specify such parameter values are outside the scope of this specification.

2.12 Security Considerations

An XProc pipeline may attempt to access arbitrary network resources: steps such as p:load and p:http-request can attempt to read from an arbitrary URI; steps such as p:store can attempt to write to an arbitrary location; p:exec can attempt to execute an arbitrary program. Note, also, that some steps, such as p:xslt and p:xquery, include extension mechanisms which may attempt to execute arbitrary code.

In some environments, it may be inappropriate to provide the XProc pipeline with access to these resources. In a server environment, for example, it may be impractical to allow pipelines to store data. In environments where the pipeline cannot be trusted, allowing the pipeline to access arbitrary resources or execute arbitrary code may be a security risk.

It is a dynamic error (err:XD0021) for a pipeline to attempt to access a resource for which it has insufficient privileges or perform a step which is forbidden. Which steps are forbidden, what privileges are needed to access resources, and under what circumstances these security constraints apply is implementation-dependent.

Steps in a pipeline may call themselves recursively which could result in pipelines which will never terminate.

A conformant XProc processor may limit the resources available to any or all steps in a pipeline. A conformant implementation may raise dynamic errors, or take any other corrective action, for any security problems that it detects.

2.13 Versioning Considerations

A pipeline author may identify the version of XProc for which a particular pipeline was authored by setting the version attribute. The version attribute can be specified on p:declare-step, p:pipeline, or p:library. If specified, the value of the version attribute must be a xs:decimal. It is a static error (err:XS0063) if the value of the version attribute is not a xs:decimal.

The version of XProc defined by this specification is “1.0”.

A pipeline author must identify the version of XProc on the document element of a pipeline document. It is a static error (err:XS0062) if a required version attribute is not present.

The version identified applies to the element on which the version attribute appears and all of its descendants, unless or until another version is explicitly identified.

When a processor encounters an explicit version (other than a version which it implements), it proceeds in backwards- or forwards-compatible mode.

<p:string-replace match="div/@class" replace="newclass">
  <p:input port="ancillary">
    <p:document href="doc.xml"/>
  </p:input>
</p:string-replace>

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
            version="2.0">

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

  <p:sink/>

  <p:count>
    <p:input port="source">
      <p:pipe step="style" port="messages"/>
    </p:input>
  </p:count>
</p:pipeline>

3.1 XProc Namespaces

There are three namespaces associated with XProc:

This specification also makes use of the prefix “xs:” to refer to the [W3C XML Schema: Part 1] namespace http://www.w3.org/2001/XMLSchema.

3.2 Scoping of Names

Names are used to identify step types, steps, ports, options and variables, and parameters. Step types, options, variables, and parameters are named with QNames. Steps and ports are named with NCNames. The scope of a name is a measure of where it is available in a pipeline. [Definition: If two names are in the same scope, we say that they are visible to each other. ]

The scope of the names of the step types is the pipeline in which they are declared, including any declarations imported from libraries via p:import. Nested pipelines inherit the step types in scope for their parent.

In other words, the step types that are in scope in a p:pipeline or p:declare-step are:

The step types that are in scope in a p:library are:

All the step types in a pipeline or library 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 the siblings of its ancestors are all in a common scope. All 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 and variable names is determined by where they are declared. When an option is declared with p:option (or a variable with p:variable), unless otherwise specified, its scope consists of the sibling elements that follow its declaration and the descendants of those siblings. It is a static error (err:XS0004) if an option or variable declaration duplicates the name of any other option or variable in the same environment. That is, no option or variable may lexically shadow another option or variable with the same name.

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

3.3 Base URIs and xml:base

When a relative URI appears in an option value, the base URI against which it must be made absolute is the base URI of the p:option element. If an option value is specified using a syntactic shortcut, the base URI of the step on which the shortcut attribute appears must be used. In general, whenever a relative URI appears, its base URI is the base URI of the nearest ancestor element.

The pipeline author can control the base URIs of elements within the pipeline document with the xml:base attribute. The xml:base attribute may appear on any element in a pipeline and has the semantics outlined in [XML Base].

3.4 Unique identifiers

A pipeline author can provide a globally unique identifier for any element in a pipeline with the xml:id attribute.

The xml:id attribute may appear on any element in a pipeline and has the semantics outlined in [xml:id].

3.5 Associating Documents with Ports

[Definition: A connection associates an input or output port with some data source.] A document or a sequence of documents can be connected 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.

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

3.6 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. The p:documentation element has no special semantics when it appears in documents that flow through the pipeline.

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 p:pipeinfo.

3.7 Processor annotations

Pipeline authors may add annotations to their pipeline documents with the p:pipeinfo element. The semantics of p:pipeinfo elements are implementation-defined. Processors should specify a way for their annotations to be identified, perhaps with extension attributes.

Where p:documentation is intended for human consumption, p:pipeinfo elements are intended for processor consumption. A processor might, for example, use annotations to identify some particular aspect of an implementation, to request additional, perhaps non-standard features, to describe parallelism constraints, etc.

When a p:pipeinfo appears as a descendant of p:inline, it has no special semantics; in that context it must be treated literally as part of the document to be provided on that port. The p:pipeinfo element has no special semantics when it appears in documents that flow through the pipeline.

3.8 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 would arise in the absence of the attribute. They must not cause the processor to fail to signal an error that would be signaled in the absence of the attribute.

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

3.9 Conditional Element Exclusion

Any element in the XProc namespace may have a use-when attribute which must contain an XPath expression that can be evaluated statically. If the attribute is present and the effective boolean value of the expression is false, then the element and all of its descendants are effectively excluded from the pipeline document. If a node is effectively excluded, the processor must behave as if the element was not present in the document.

Elements that are not in the XProc namespace may also have a use-when attribute, but the attribute must be in the XProc namespace. The semantics of a p:use-when attribute on an element not in the XProc namespace are the same as the semantics of a use-when attribute on an element in the XProc namespace.

Conditional element exclusion occurs before any static analysis of the pipeline.

For the purposes of evaluating a use-when expression, the context node, position, and size are all undefined. No in-scope bindings are available. There are no readable ports. There are no available documents or available collections.

There are some additional restrictions on the XPath extension functions that are available in a use-when expression:

It is a static error (err:XS0061) if a use-when expression refers to the context or attempts to refer to any documents or collections.

3.10 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>

The content model fragments in these tableaux are presented in a simple, compact notation. In brief:

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

The types given for attributes should be understood as follows:

3.11 Common errors

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 provided that the error does not occur among the descendants of a p:try. Dynamic errors inside a p:try must not be reported statically. They must be raised dynamically so that p:catch processing can be performed on them.

4.1 p:pipeline

A p:pipeline declares a pipeline that can be evaluated by an XProc processor. It encapsulates the behavior of a subpipeline. Its children declare inputs, outputs, and options that the pipeline exposes and identify the steps in its subpipeline. (A p:pipeline is a simplified form of step declaration.)

All p:pipeline pipelines have an implicit primary input port named “source”, an implicit primary parameter input port named “parameters”, and an implicit primary output port named “result”. Any input or output ports that the p:pipeline declares explicitly are in addition to those ports and may not be declared primary.

<p:pipeline
  name? = NCName
  type? = QName
  psvi-required? = boolean
  xpath-version? = string
  exclude-inline-prefixes? = prefix list
  version? = string>
    (p:input |
     p:output |
     p:option |
     p:log |
     p:serialization)*,
    (p:declare-step |
     p:pipeline |
     p:import)*,
    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 version attribute identifies the version of XProc for which this pipeline was authored. If the p:pipeline has no ancestors in the XProc namespace, then it must have a version attribute. See Section 2.13, “Versioning Considerations”.

If a pipeline does not have a type then that pipeline cannot be invoked as a step.

The p:pipeline element is just a simplified form of step declaration. A document that reads:

<p:pipeline some-attributes>
  some-content
</p:pipeline>

can be interpreted as if it read:

<p:declare-step some-attributes>
  <p:input port='source' primary='true'/>
  <p:input port='parameters' kind='parameter' primary='true'/>
  <p:output port='result' primary='true'/>
  some-content
</p:declare-step>

See p:declare-step for more details.

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc" version="1.0">

<p:xinclude/>

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

<p:xslt>
  <p:input port="stylesheet">
    <p:document href="http://example.com/path/to/stylesheet.xsl"/>
  </p:input>
</p:xslt>

</p:pipeline>

4.2 p:for-each

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

<p:for-each
  name? = NCName>
    ((p:iteration-source? &
      (p:output |
       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. If the iteration source for a p:for-each is an empty sequence, then the subpipeline is never run and an empty sequence is produced on all of the outputs.

The p:iteration-source is an anonymous input: its connection 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.

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 (explicit or supplied by default) and that port has no connection, then it is connected 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 explicit connection and the last step in the subpipeline does not have a primary output port.

Note that outputs declared for a p:for-each serve a dual role. Inside the p:for-each, they are used to read results from the subpipeline. Outside the p:for-each, they provide the aggregated results.

The sequence attribute on a p:output inside a p:for-each only applies inside the step. From the outside, all of the outputs produce sequences.

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

4.3 p:viewport

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

<p:viewport
  name? = NCName
  match = XSLTMatchPattern>
    ((p:viewport-source? &
      p:output? &
      p:log?),
     subpipeline)
</p:viewport>

The result of the p:viewport is a copy of the original document where the selected subtrees have been replaced by the results of applying the subpipeline to them.

The p:viewport-source is an anonymous input: its connection 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. It is a dynamic error (err:XD0003) if the viewport source does not provide exactly one document.

The match attribute specifies an XSLT match pattern. Each matching node in the source document is wrapped in a document node, as necessary, and provided, one at a time, to the viewport's subpipeline on a port named current. The base URI of the resulting document that is passed to the subpipeline is the base URI of the matched element or document. It is a dynamic error (err:XD0010) if the match expression on p:viewport does not match an element or document.

After a match is found, the entire subtree rooted at that match is processed as a unit. No further attempts are made to match nodes among the descendants of any matched node.

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

The p:viewport must contain a single, primary output port declared explicitly or supplied by default. If that port has no connection, then it is connected to the primary output port of the last step in the subpipeline. It is a static error (err:XS0006) if the primary output port is unconnected and the last step in the subpipeline does not have a primary output port.

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. In other words, if the match pattern matches a particular element then that element is wrapped in a document node and provided on the current port, the subpipeline in the p:viewport is evaluated, and the result that appears on the output port replaces the matched element.

If no documents appear on the output port, the matched element will effectively be deleted. If exactly one document appears, the contents of that document will replace the matched element. If a sequence of documents appears, then the contents of each document in that sequence (in the order it appears in the sequence) will replace the matched element.

The output of the p:viewport itself is a single document that appears on a port named “result”. Note that the semantics of p:viewport are special. The output port in the p:viewport is used only to access the results of the subpipeline. The output of the step itself appears on a port with the fixed name “result” that is never explicitly declared.

<p:viewport match="h:div[@class='chapter']"
            xmlns:h="http://www.w3.org/1999/xhtml">
  <p:insert position="first-child">
    <p:input port="insertion">
      <p:inline>
        <hr xmlns="http://www.w3.org/1999/xhtml"/>
      </p:inline>
    </p:input>
  </p:insert>
</p:viewport>

4.4 p:choose

A choose is specified by the p:choose element. It is a multi-container step that selects exactly one of a list of alternative subpipelines based on the evaluation of XPath expressions.

<p:choose
  name? = NCName>
    (p:xpath-context?,
     p:variable*,
     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 outputs of the p:choose are taken from the outputs of the selected subpipeline. The p:choose has the same number of outputs as the selected subpipeline with the same names. If the selected subpipeline has a primary output port, the port with the same name on the p:choose is also a primary output port.

In order to ensure that the output 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.

As a convenience to authors, it is not an error if some subpipelines declare outputs that can produce sequences and some do not. Each output of the p:choose is declared to produce a sequence if that output is declared to produce a sequence in any of its subpipelines.

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 expressions that occur on each branch are evaluated. The context node is specified as a connection in the p:xpath-context. If no explicit connection is provided, the default readable port is used. In an XPath 1.0 implementation, if the context node is connected to p:empty, or is unconnected and the default readable port is undefined, an empty document node is used instead as the context. In an XPath 2.0 implementation, the context item is undefined.

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

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

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

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

  <p:otherwise>
    <p:error code="NOVERSION">
      <p:input port="source">
        <p:inline>
          <message>Required version attribute missing.</message>
        </p:inline>
      </p:input>
    </p:error>
  </p:otherwise>
</p:choose>

4.5 p:group

A group is specified by the p:group element. In a p:try, it is a non-step wrapper, everywhere else, it is a compound step. A group encapsulates the behavior of its subpipeline.

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

A p:group is a convenience wrapper for a collection of steps.

<p:group>
  <p:variable name="db-key"
              select="'some-long-string-of-nearly-random-characters'"/>

  <p:choose>
    <p:when test="/config/output = 'fo'">
      <p:xslt>
        <p:with-param 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:with-param 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:with-param 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

A try/catch is specified by the p:try element. It is a multi-container step that 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:variable*,
      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 outputs of that pipeline are the outputs of the p:try step. However, if any errors occur, the p:try abandons the first subpipeline, discarding any output that it might have generated, and evaluates the recovery subpipeline.

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

The outputs of the p:try are taken from the outputs of the initial subpipeline or the recovery subpipeline if an error occurred in the initial subpipeline. The p:try has the same number of outputs as the selected subpipeline with the same names. If the selected subpipeline has a primary output port, the port with the same name on the p:try is also a primary output port.

In order to ensure that the output 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.

As a convenience to authors, it is not an error if an output port can produce a sequence in the initial subpipeline but not in the recovery subpipeline, or vice versa. Each output of the p:try is declared to produce a sequence if that output is declared to produce a sequence in either of its subpipelines.

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

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

<p:catch
  name? = NCName>
    ((p:output |
      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 output 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 output 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.

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

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

<p:try>
  <p:group>
    <p:http-request>
      <p:input port="source">
        <p:inline>
          <c:request method="post" href="http://example.com/form-action">
            <c:body content-type="application/x-www-form-urlencoded">name=W3C&amp;spec=XProc</c:body>
          </c: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 Atomic Steps

In addition to the six step types described in the preceding sections, XProc provides a standard library of atomic step types. The full vocabulary of standards steps is described in Section 7, “Standard Step Library”.

All of the standard, atomic steps are invoked in the same way:

<p:atomic-step
  name? = NCName>
    (p:input |
     p:with-option |
     p:with-param |
     p:log)*
</p:atomic-step>

Where “p:atomic-step” must be in the XProc namespace and must be declared in either the standard library for the XProc version supported by the processor or explicitly imported by the surrounding pipeline (see Section 2.13, “Versioning Considerations”).

4.8 Extension Steps

Pipeline authors may also have access to additional steps not defined or described by this specification. Atomic extension steps are invoked just like standard steps:

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

Extension steps must not be in the XProc namespace and there must be a visible step declaration at the point of use (see Section 3.2, “Scoping of Names”).

If the relevant step declaration has no subpipeline, then that step invokes the declared atomic step, which the processor must know how to perform. These steps are implementation-defined extensions.

If the relevant step declaration has a subpipeline, then that step runs the declared subpipeline. These steps are user- or implementation-defined extensions. 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.

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.

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:XS0048) to use a declared step as a compound step.

<ex:stepType>
  <p:with-option name="option-name" select="'some value'"/>
</ex:stepType>

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

5.1 p:input

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 connection for a port declared elsewhere. And 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.

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

<p:input port="source" select="//html:div" xmlns:html="http://www.w3.org/1999/xhtml">
  <p:document href="http://example.org/input.html"/>
</p:input>

<p:input port="source" select="//html:div" xmlns:html="http://www.w3.org/1999/xhtml">
  <p:pipe step="origin" port="result"/>
</p:input>

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="1.0">
<p:input port="source"/>
<p:output port="result"/>

<p:xslt>
  <p:input port="stylesheet">
    <p:document href="http://example.com/stylesheets/doc.xsl"/>
  </p:input>
</p:xslt>

</p:declare-step>

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="1.0">
<p:input port="source"/>
<p:output port="result"/>

<p:xslt>
  <p:input port="stylesheet">
    <p:document href="http://example.com/stylesheets/doc.xsl"/>
  </p:input>
  <p:with-param name="mode" select="'debug'"/>
</p:xslt>

</p:declare-step>

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc" version="1.0">

<p:xslt>
  <p:input port="stylesheet">
    <p:document href="http://example.com/stylesheets/doc.xsl"/>
  </p:input>
  <p:with-param name="mode" select="'debug'"/>
</p:xslt>

</p:pipeline>

<p:pipeline xmlns:p="http://www.w3.org/ns/xproc"
            version="1.0"
            name="main">

<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:with-param name="output-type" select="'html'"/>
  <p:input port="parameters">
    <p:pipe step="main" port="parameters"/>
  </p:input>
</p:xslt>

</p:pipeline>

5.2 p:iteration-source

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

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

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

5.3 p:viewport-source

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

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

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

5.4 p:output

A p:output identifies an output port, optionally connecting an input for 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.

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 connection for the output.

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

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

If a connection is provided for a p:output, documents are read from that connection 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

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 IRI whatever document or documents appear on the specified port. If the href attribute is not specified, the location of the log file or files is implementation-defined.

How each document or sequence of documents is represented in a p:log is implementation-defined. Pipelines are not expected to be able to consume their own logging output. The ability of a step to read the p:log output of some former step is implementation-dependent.

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.

5.6 p:serialization

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|xs:NMTOKEN
  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 serialization options not specified on a particular p:serialization element is implementation-defined. The allowed options are defined by [Serialization]. It is a dynamic error (err:XD0020) if the combination of serialization options specified or defaulted is not allowed. Implementations must check that all of the specified serialization options are allowed if they serialize the specified output. If the specified output is not being serialized (because it is being returned as the result of a call from within another pipeline, for example) implementations may but are not required to check that the specified options are allowed.

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 Variables, Options, and Parameters

Variables, options, and parameters provide a mechanism for pipeline authors to construct temporary results and hold onto them for reuse.

Variables are created in compound steps and, like XSLT variables, are single assignment, though they may be shadowed by subsequent declarations of other variables with the same name.

Options can be declared on atomic or compound steps. The value of an option can be specified by the caller invoking the step. Any value specified by the caller takes precedence over any default value specified in the declaration.

Parameters, unlike options and variables, have names that can be computed at runtime. The most common use of parameters is to pass parameter values to XSLT stylesheets.

<p:delete xmlns:p="http://www.w3.org/ns/xproc">
  <p:with-option name="match" select="'html:div'"
                 xmlns:html="http://www.w3.org/1999/xhtml"/>
</p:delete>

<p:pipeline type="ex:delete-in-div"
            version="1.0"
            xmlns:p="http://www.w3.org/ns/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:with-option name="match" select="concat('h:div/',$divchild)"/>
</p:delete>

</p:pipeline>

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

<p:pipeline type="ex:delete-in-div"
            version="1.0"
            xmlns:p="http://www.w3.org/ns/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:with-option name="match" select="concat('h:div/',$divchild)">
    <p:namespaces xmlns:html="http://www.w3.org/1999/xhtml"/>
  </p:with-option>
</p:delete>

</p:pipeline>

<p:pipeline type="ex:delete-in-div"
            version="1.0"
            xmlns:p="http://www.w3.org/ns/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:with-option name="match" select="concat('h:div/',$divchild)">
    <p:namespaces binding="divchild"/>
    <p:namespaces xmlns:h="http://www.w3.org/1999/xhtml"/>
  </p:with-option>
</p:delete>

</p:pipeline>

5.8 p:declare-step

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

<p:declare-step
  name? = NCName
  type? = QName
  psvi-required? = boolean
  xpath-version? = string
  exclude-inline-prefixes? = prefix list
  version? = string>
    (p:input |
     p:output |
     p:option |
     p:log |
     p:serialization)*,
    ((p:declare-step |
      p:pipeline |
      p:import)*,
     subpipeline)?
</p:declare-step>

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 or in the XProc namespace. Except as described in Section 2.13, “Versioning Considerations”, the XProc namespace must not be used in the type of steps. Neither users nor implementers may define additional steps in the XProc namespace.

Irrespective of the context in which the p:declare-step occurs, there are initially no option or variable names in-scope inside a p:declare-step. That is, p:option and p:variable elements can refer to values declared by their preceding siblings, but not by any of their ancestors.

When a declared step is evaluated directly by the XProc processor (as opposed to occurring as an atomic step in some container), how the input and output ports are connected to documents is implementation-defined.

A step declaration is not a step in its own right. Sibling steps cannot refer to the inputs or outputs of a p:declare-step using p:pipe; only instances of the type can be referenced.

The version attribute identifies the version of XProc for which this step declaration was authored. If the p:declare-step has no ancestors in the XProc namespace, then it must have a version attribute. See Section 2.13, “Versioning Considerations”.

For a description of psvi-required, see Section 2.8, “PSVIs in XProc”. For xpath-version, see Section 2.6, “XPaths in XProc”. For exclude-inline-prefixes, see p:inline.

5.9 p:library

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

<p:library
  psvi-required? = boolean
  xpath-version? = string
  exclude-inline-prefixes? = prefix list
  version? = string>
    (p:import |
     p:declare-step |
     p:pipeline)*
</p:library>

The version attribute identifies the version of XProc for which this library was authored. If the p:library has no ancestors in the XProc namespace, then it must have a version attribute. See Section 2.13, “Versioning Considerations”.

For a description of psvi-required, see Section 2.8, “PSVIs in XProc”; for xpath-version, see Section 2.6, “XPaths in XProc”; for exclude-inline-prefixes, see p:inline.

Libraries can import pipelines and/or other libraries. See also Appendix G, Handling Circular and Re-entrant Library Imports (Non-Normative).

5.10 p:import

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 IRI and makes any pipelines declared within it available to the current pipeline.

It is a static error (err:XS0052) if the URI of a p:import cannot be retrieved or if, once retrieved, it does not point to a p:library, p:declare-step, or p:pipeline. It is a static error (err:XS0053) to import a single pipeline if that pipeline does not have a type.

Attempts to retrieve the library identified by the URI value may be redirected at the parser level (for example, in an entity resolver) or below (at the protocol level, for example, via an HTTP Location: header). In the absence of additional information outside the scope of this specification within the resource, the base URI of the library is always the URI of the actual resource returned. In other words, it is the URI of the resource retrieved after all redirection has occurred.

As imports are processed, a processor may encounter new p:import elements whose library URI is the same as one it has already processed in some other context. This may happen as a consequence of resolving the URI. If the actual base URI is the same as one that has already been processed, the implementation must recognize it as the same library and should not need to process the resource. Also, a duplicate, circular chain of imports, or a re-entrant import is not an error and implementations must take the necessary steps to avoid infinite loops and/or incorrect notification of duplicate step definitions. It is not an error for a library to import itself. An example of such steps is listed in Appendix G, Handling Circular and Re-entrant Library Imports (Non-Normative).

A library is considered the same library if the URI of the resource retrieved is the same. If a pipeline or library author uses two different URI values that resolve to the same resource, they must not be considered the same imported library.

5.11 p:pipe

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 connection 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

A p:inline provides a document inline.

<p:inline
  exclude-inline-prefixes? = prefix list>
    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 (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.

The in-scope namespaces of the inline document differ from the in-scope namespace of the content of the p:inline element in that bindings for all its excluded namespaces, as defined below, are removed:

The value of each exclude-inline-prefixes attribute is interpreted as follows:

The value of the attribute is either #all, or a whitespace-separated list of tokens, each of which is either a namespace prefix or #default. The namespace bound to each of the prefixes is designated as an excluded namespace. It is a static error (err:XS0057) if the exclude-inline-prefixes attribute does not contain a list of tokens or if any of those tokens (except #all or #default) is not a prefix bound to a namespace in the in-scope namespaces of the element on which it occurs.

The default namespace of the element on which exclude-inline-prefixes occurs may be designated as an excluded namespace by including #default in the list of namespace prefixes. It is a static error (err:XS0058) if the value #default is used within the exclude-inline-prefixes attribute and there is no default namespace in scope.

The value #all indicates that all namespaces that are in scope for the element on which exclude-inline-prefixes occurs are designated as excluded namespaces.

The XProc processor must include all in-scope prefixes that are not explicitly excluded. If the namespace associated with an excluded prefix is used in the expanded-QName of a descendant element or attribute, the processor may include that prefix anyway, or it may generate a new prefix.

Consider this example:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="1.0">
  <p:output port="result"/>
  <p:serialization port="result" indent="true"/>

  <p:identity xmlns:a="http://example.com/a"
              xmlns:b="http://example.com/b"
              xmlns:c="http://example.com/c">
    <p:input port="source">
      <p:inline exclude-inline-prefixes="a b">
        <doc>
          <b:part/>
        </doc>
      </p:inline>
    </p:input>
  </p:identity>

</p:declare-step>

which might produce a result like this:

<doc xmlns:c="http://example.com/c">
   <b:part xmlns:b="http://example.com/b"/>
 </doc>

The declaration for “c” must be present because it was not excluded. The “part” element uses the namespace bound to “b”, so some binding must be present. In this example, the original prefix has been preserved, but it would be equally correct if a different prefix had been used.

5.13 p:document

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. If the URI protocol supports redirection, then redirects must be followed.

It is a dynamic error (err:XD0011) if the resource 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 process the external subset; all general and external parsed entities must be fully expanded. It may perform xml:id processing, but it must not perform any other processing, such as expanding XIncludes. The parser must be conformant to Namespaces in XML. Loading the document must not fail due to validation errors.

Use the p:load step if you need to perform DTD-based validation.

5.14 p:data

A p:data reads an arbitrary resource from a URI.

<p:data
  href = anyURI
  wrapper? = QName
  wrapper-prefix? = string
  wrapper-namespace? = string
  content-type? = string />

The resource identified by the URI in the href attribute is loaded, encoded, wrapped in the wrapper element, and returned as a document. If the URI protocol supports redirection, then redirects must be followed.

The value of the wrapper attribute must be a QName. If the lexical value does not contain a colon, then the wrapper-namespace may be used to specify the namespace of the wrapper. In that case, the wrapper-prefix may be specified to suggest a prefix for the wrapper element. It is a dynamic error (err:XD0034) to specify a new namespace or prefix if the lexical value of the specified name contains a colon (or if no wrapper is explicitly specified).

In other words, these two p:data elements produce equivalent wrappers:

<p:data href="..."
        xmlns:x="http://example.com/ns/"
        wrapper="x:wrap"/>
<p:data href="..."
        wrapper="wrap" wrapper-prefix="x"
        wrapper-namespace="http://example.com/ns/"/>

but this p:data element will raise an error:

<p:data href="..."
        xmlns:x="http://example.com/ns/"
        wrapper="x:wrap" wrapper-prefix="x"
        wrapper-namespace="http://example.com/ns/"/>

If no wrapper element is specified, the default is c:data:

<c:data
  content-type? = string
  charset? = string
  encoding? = string>
    string
</c:data>

It is a dynamic error (err:XD0029) if the document referenced by a p:data element does not exist, cannot be accessed, or cannot be encoded as specified.

Exactly how the data is encoded depends on the media type of the resource. If the resource has a content type associated with it (e.g., if the resource was retrieved with HTTP), then that content type must be used, otherwise, if the user specified a content-type on the p:data, then that content type should be assumed. If no content type was specified or is associated with the resource, the inferred content type is implementation-dependent.

The resulting data is wrapped in an element with the name specified in the wrapper attribute (or c:data if no wrapper is specified).

Implementations should add a content-type attribute to the wrapper element which indicates the specified or inferred media type of the resource (including any parameters). If the content was base64-encoded, the wrapper must have an encoding attribute which specifies “base64”.

If an encoding is specified, a charset may also be specified. The character set may be specified as a parameter on the content-type or via the separate charset option. If it is specified in both places, the values must be consistent.

If content-type, encoding, or charset attributes are specified on a c:data wrapper, they must not be in a namespace; if the user-specified wrapper is not c:data, then the attributes must be in the http://www.w3.org/ns/xproc-step namespace.

Implementations may record additional details in extension attributes.

For example, this p:identity step:

<p:identity name="readcsv">
  <p:input port="source">
    <p:data href="stateabbr.csv"/>
  </p:input>
</p:identity>

might produce output like this:

<c:data xmlns:c="http://www.w3.org/2007/03/xproc-step"
        content-type="text/plain">
AL,Alabama
AK,Alaska
AZ,Arizona
…
</c:data>

Whereas this pipeline fragment:

<p:identity name="readpng">
  <p:input port="source">
    <p:data href="icon.png" content-type="image/png"/>
  </p:input>
</p:identity>

<p:add-attribute name="makeimg" match="img" attribute-name="src">
  <p:input port="source"><p:inline><img/></p:inline></p:input>
  <p:with-option name="attribute-value"
                 select="concat('data:image/png;base64,',/*/node())">
    <p:pipe step="readpng" port="result"/>
  </p:with-option>
</p:add-attribute>

produces a single img element with an inline graphic (represented using a data: URI):

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBI
WXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH1QsEDycHOWjhgQAAAB10RVh0Q29tbWVudABDcmVhdGVk
IHdpdGggVGhlIEdJTVDvZCVuAAABjklEQVQ4y42Tv0tbcRTFz3t5kuQFwUVFEYIGU6q4mU0RlCDR
qYO2g4gdghUyKSFDwD/AwS2IoIMSHOLgpOLg4CIOWdy76GBoqQUJLlr66aCW6LuoF+7wvefcc3/w
vZLgpbe0wOoqn/Ro5TKRVIpLi6tkkpoFpFJUj48JSVI2y4LnBTm+D1paYqa5OQiGw5DN8nV7m1hv
L99f4o4Dk5Mc6Pwcd2yMXauL/n5+FAqsWdXjca5LJbokSXt7fOzu5toSaWsLxpqaIJcjr0ZbXGQh
HDaWZPjQEGc7O3jPBC4u8EZHOXkruaODPxsbDMuylRWSra3cviYwO0upMcdtfNRqGq/X5esVu7nR
BxMol4knEtTfGsH3+bu8zLdnydUqXjrN/nsWKEEiwdXmJp3/BYpFctFokOi6EIsF444DU1McSZLW
1+nq6eGnVWlkhNrcHBXXNUe5z+f5rEyGA8cxD+pufp7BYtH+yhL09fFbkYjd4vQ0W08jFgp8se7l
wY3gwAC/KhXanwROTwlNTHBocf8BTQe7F9dc2bMAAAAASUVORK5CYII="/>

Some steps, such as p:xquery and p:validate-with-relax-ng, are designed to process non-XML inputs. If a base64-encoded input occurs in such a context, it should be decoded before processing. In this way, for example, an XQuery document can be read with p:data and passed to the p:xquery step without regard to how the data was encoded.

5.15 p:empty

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

<p:empty />

5.16 p:documentation

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. See Section 3.6, “Documentation”.

5.17 p:pipeinfo

A p:pipeinfo contains ancillary information for steps in the pipeline.

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

There are no constraints on the content of the p:pipeinfo element, see Section 3.7, “Processor annotations”.

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 and incorrect specification of inputs and outputs.

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

For a complete list of static errors, see Section E.1, “Static Errors”.

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.

For a complete list of dynamic errors, see Section E.2, “Dynamic Errors”.

6.3 Step Errors

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

For a complete list of the dynamic errors raised by builtin pipeline steps, see Section E.3, “Step Errors”.

7.1 Required Steps

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

<p:error xmlns:my="http://www.example.org/error"
         name="bad-document" code="my:unk12">
   <p:input port="source">
     <p:inline>
       <message>The document element is unknown.</message>
     </p:inline>
   </p:input>
</p:error>

<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"><message>The document element is unknown.</message>
</c:error>
</c:errors>

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

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

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

POST http://example.com/someservice HTTP/1.1
Host: example.com
Content-Type: application/xml; charset="utf-8"

<?xml version='1.0'?>
<doc>
<title>My document</title>
</doc>

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

<c:response status="200" xmlns:c="http://www.w3.org/ns/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='http://www.w3.org/2001/05/P3P/p3p.xml'"/>
<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="'4640a109;42380ddc'"/>
<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:response>