1.1. Pipeline examples

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

Figure 1. A simple, linear XInclude/Validate pipeline

This is a pipeline that consists of two atomic steps, XInclude and Validate with XML Schema. The pipeline itself has two inputs, “source” (a source document) and “schemas” (a sequence of W3C XML Schemas). The XInclude step reads the pipeline input “source” and produces a result document. The Validate with XML Schema step reads the pipeline input “schemas” and the result of the XInclude step and produces its own result document. The result of the validation, “result”, is the result of the pipeline. (For consistency across the step vocabulary, the standard input is usually named “source” and the standard output is usually named “result”.)

The pipeline document determines how the steps are connected together inside the pipeline, that is, how the output of one step becomes the input of another.

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

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                name="xinclude-and-validate"
                version="3.1">
  <p:input port="source" primary="true"/>
  <p:input port="schemas" sequence="true"/>
  <p:output port="result">
    <p:pipe step="validated" port="result"/>
  </p:output>
 
  <p:xinclude name="included">
    <p:with-input port="source">
      <p:pipe step="xinclude-and-validate" port="source"/>
    </p:with-input>
  </p:xinclude>
 
  <p:validate-with-xml-schema name="validated">
    <p:with-input port="source">
      <p:pipe step="included" port="result"/>
    </p:with-input>
    <p:with-input port="schema">
      <p:pipe step="xinclude-and-validate" port="schemas"/>
    </p:with-input>
  </p:validate-with-xml-schema>
</p:declare-step>

Example 1, “A simple, linear XInclude/Validate pipeline” is very verbose. It makes all of the connections seen in the figure explicit. In practice, pipelines do not have to be this verbose. By default, where inputs and outputs are connected between sequential sibling steps, they do not have to be made explicit.

The same pipeline, using XProc defaults, is shown in Example 2, “A simple, linear XInclude/Validate pipeline (simplified)”.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                name="xinclude-and-validate"
                version="3.1">
  <p:input port="source" primary="true"/>
  <p:input port="schemas" sequence="true"/>
  <p:output port="result"/>
 
  <p:xinclude/>
 
  <p:validate-with-xml-schema>
    <p:with-input port="schema">
      <p:pipe step="xinclude-and-validate" port="schemas"/>
    </p:with-input>
  </p:validate-with-xml-schema>
</p:declare-step>

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

Figure 2. A validate and transform pipeline

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

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                name="xinclude-and-validate"
                version="3.1">
  <p:input port="source"/>
  <p:input port="schemas" sequence="true"/>
  <p:output port="result"/>
 
  <p:choose>
    <p:when test="/*[@version &lt; 2.0]">
      <p:validate-with-xml-schema>
        <p:with-input port="schema" href="v1schema.xsd"/>
      </p:validate-with-xml-schema>
    </p:when>
 
    <p:otherwise>
      <p:validate-with-xml-schema>
        <p:with-input port="schema" href="v2schema.xsd"/>
      </p:validate-with-xml-schema>
    </p:otherwise>
  </p:choose>
 
  <p:xslt>
    <p:with-input port="stylesheet" href="stylesheet.xsl"/>
  </p:xslt>
</p:declare-step>

This example, like the preceding, relies on XProc defaults for simplicity. It is always valid to write the fully explicit form if you prefer. This example also takes advantage of using the href attribute directly on p:with-input as a shortcut for the p:document connection.

2.1. Steps

A step is the basic computational unit of a pipeline. A typical step has inputs, from which it receives documents to process, outputs, to which it sends result documents, and options which influence its behavior.

There are two kinds of steps: atomic and compound:

• An atomic step is a step that performs a unit of processing on its input, such as validation or transformation, and has no internal subpipeline. Atomic steps carry out fundamental operations and can perform arbitrary amounts of computation, but they are indivisible.

  There are many types of atomic steps. The standard library of atomic steps is described in Steps 3.1, 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, providing familiar programming language functionality such as conditionals, iterators and exception handling. They contain other steps, whose evaluation they control.

A compound step is a step that contains one or more subpipelines. That is, a compound step differs from an atomic step in that its semantics are at least partially determined by the steps that it contains.

Compound steps either directly contain a single subpipeline or contain several subpipelines and select one or more to evaluate dynamically. In the latter case, alternate subpipelines are identified by non-step wrapper elements that each contain a single subpipeline.

A container is either a compound step or one of the non-step wrapper elements in a compound step that contains several subpipelines. The steps that occur directly within a container are called that step’s contained steps. In other words, “container” and “contained steps” are inverse relationships. The ancestors of a step, if it has any, are its container and the ancestors of its container.

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

subpipeline = (p:variable|p:for-each|p:viewport|p:choose|p:if|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. 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.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1" 
    name="main-step">
 
  <p:input port="source" primary="true"/>
  <p:input port="extra"/>
  <p:output port="result" primary="true"/>
 
  <p:add-attribute attribute-name="timestamp"
                   attribute-value="{current-dateTime()}" 
      name="add-timestamp">
    <p:with-input port="source">
      <p:pipe step="main-step" port="extra"/>
    </p:with-input>
  </p:add-attribute>
 
  <p:insert match="/*" position="first-child">
    <p:with-input port="source">
      <p:pipe step="main-step" port="source"/>
    </p:with-input>
    <p:with-input port="insertion">
      <p:pipe step="add-timestamp" port="result"/>
    </p:with-input>
  </p:insert>
 
</p:declare-step>

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1" 
    name="main-step">
 
  <p:input port="source" primary="true"/>
  <p:input port="extra"/>
  <p:output port="result" primary="true"/>
 
  <p:add-attribute attribute-name="timestamp"
                   attribute-value="{current-dateTime()}" 
      name="add-timestamp">
    <p:with-input port="source" pipe="extra@main-step"/>
  </p:add-attribute>
 
  <p:insert match="/*" position="first-child">
    <p:with-input port="source" pipe="source@main-step"/>
    <p:with-input port="insertion" pipe="result@add-timestamp"/>
  </p:insert>
 
</p:declare-step>

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"
  xmlns:mysteps="http://.../ns/mysteps">
 
  <p:input port="source"/>
  <p:output port="result"/>
 
  <p:declare-step type="mysteps:add-timestamp-attribute"> 
    <p:input port="source"/>
    <p:output port="result"/>
    <p:add-attribute attribute-name="timestamp"
                     attribute-value="{current-dateTime()}"/>
  </p:declare-step>
  
  ...
  <mysteps:add-timestamp-attribute/>
  ...
  <mysteps:add-timestamp-attribute/>
  ...
 
</p:declare-step>

<p:declare-step type="mysteps:add-timestamp-attribute" version="3.1"
                xmlns:p="http://www.w3.org/ns/xproc"
                xmlns:mysteps="http://.../ns/mysteps">
  <p:input port="source"/>
  <p:output port="result"/>
  <p:add-attribute attribute-name="timestamp"
                   attribute-value="{current-dateTime()}"/>
</p:declare-step>

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.1"
  xmlns:mysteps="http://.../ns/mysteps">
 
  <p:import href="add-timestamp-attribute.xpl"/>
 
  <p:input port="source"/>
  <p:output port="result"/>
 
  ...
  <mysteps:add-timestamp-attribute/>
  ...
 
</p:declare-step>

<p:library version="3.1" xmlns:p="http://www.w3.org/ns/xproc" 
  xmlns:mysteps="http://.../ns/mysteps">
 
  <p:declare-step type="mysteps:add-timestamp-attribute">
    <p:input port="source"/>
    <p:output port="result"/>
    <p:add-attribute attribute-name="timestamp"
                     attribute-value="{current-dateTime()}"/>
  </p:declare-step>
 
  ... more library steps
 
</p:library>

3.1. Document Properties

Documents have associated with them a set of properties. The document properties are key/value pairs; they are exposed to the XProc pipeline as a map (map(xs:QName, item()*)).

Several properties are defined by this specification:

content-type

The value of the “content-type” property identifies the media type (RFC 2046) of the representation. The “content-type” must always be present. The processor is responsible for assuring that the content-type property matches the content type of each document produced on every output port.

base-uri

The value of the “base-uri” property identifies the base URI of the document; it will only be present if the document has a base URI. For XML documents, HTML documents, and text documents, the value of “base-uri” is the base URI property of the document node. For other document types it is a property the processor keeps track of. If no such key is present, the document has no base URI.

serialization

The value of the (optional) “serialization” property holds serialization properties for the document. If present, it’s value must be of type map(xs:QName, item()*). It is a dynamic error (err:XD0070) if a value is assigned to the serialization document property that cannot be converted into map(xs:QName, item()*) according to the rules in Implicit Casting. Serialization properties control XML serialization as defined by Serialization. See also Section 16.3.1, “Serialization parameters”.

Some steps, like p:xslt and p:xquery, can specify serialization properties (for instance using an XSLT xsl:output element). If this is the case, the specified serialization properties should be returned in the result document(s) serialization property, as an appropriate serialization properties map.

If a step serializes a document whose document properties contain a serialization property, it must use these serialization properties. If the step itself allows specification of serialization properties (usually by a serialization option), the serialization properties are merged. Serialization properties specified on the document have precedence over serialization properties specified on the step. See Section 3.1.1, “Managing properties”.

Other property keys may also be present, including user defined properties.

Steps are responsible for describing how document properties are transformed as documents flow through them. Many steps claim that the specified properties are preserved. Generally, it is the responsibility of the pipeline author to determine when this is inappropriate and take corrective action. However, it is the responsibility of the pipeline processor to assure that the content-type property is correct. If a step transforms a document in a manner that is inconsistent with the content-type property (accepting an XML document on the source port but producing a text document on the result, for example), the processor must assure that the content-type property is appropriate. If a step changes the content-type in this way, it must also remove the serialization property.

<p:set-properties xmlns:map="http://www.w3.org/2005/xpath-functions/map"
                  xmlns:xs="http://www.w3.org/2001/XMLSchema"
                  properties="
map{'serialization':
   map:remove(map:get(p:document-properties(.), xs:QName('serialization')),
              xs:QName('indent'))}"/>

3.2. Document Types

XProc 3.1 has been designed to make it possible to process any kind of document. Each document has a representation in the XQuery and XPath Data Model 3.1. This is necessary so that any kind of document can be passed as an argument to XPath functions, such as p:document-properties. Practically speaking, there are five kinds of documents:

1. XML documents

2. HTML documents

3. Text documents

4. JSON documents

5. Other documents

3.3. Creating documents from XDM step results

Some steps like p:xslt, p:xquery etc. create a sequence of new XDM instances. The same is true for the result of a select expression on p:with-input. Values in such a sequence can be of any XDM type (except attribute or function). Every item in such a sequence is converted into a separate document that will appear on the output port of that particular step or as the result of the p:with-input. The following rules apply to each of the items in the output sequence:

• If the item is a text node, it is wrapped in a document node and the document’s content-type is text/plain.

• If the item is an element, comment or processing-instruction node, a document node is wrapped around the node and the document’s content-type is set to application/xml.

• If the item is a document node, content-type "application/xml" is used.

• If the item is a map, array or any atomic value, content-type application/json is used.

  ⓘ

  Note

  Setting the content-type to application/json for any map, array or atomic value means that a document with content-type application/json is not guaranteed serializable using the json serialization method. For instance, a map with values that contain sequences cannot be serialized.

3.4. Specifying content types

In some contexts (step inputs, and step outputs, for example), XProc allows the pipeline author to specify a list of content types to identify what kinds of documents are allowed. Each content type in this list must have one of the following forms:

• A fully qualified type of the form “type/subtype+ext” where “+ext” is optional and any of type, subtype, and ext can be specified as “*” meaning “any”. For example: text/plain (only plain text documents), text/* (any “text” content type), */*+xml (any “+xml” content type), and */* (any content type).

• A fully qualified type preceded by a minus sign (“-”) indicates that the specified type is forbidden. For example: -image/svg forbids SVG images, -text/* forbids “text” content types, and -text/html forbids HTML documents.

• A single token (without a “/”), is considered a shortcut form. The following shortcuts must be supported by the processor:

  xml

  Expands to “application/xml text/xml */*+xml -application/xhtml+xml”.

  html

  Expands to “text/html application/xhtml+xml”.

  text

  Expands to: “text/* -text/html -text/xml”.

  json

  Expands to “application/json”.

  any

  Expands to “*/*”.

• A shortcut form preceded by a minus sign (“-”) indicates that the specified types are forbidden. When expanding a negated shortcut, any forbidden types in the expansion are ignored. In other words, -xml expands to “-application/xml -text/xml -*/*+xml”, the exclusion on HTML documents is ignored.

It is a dynamic error (err:XD0079) if a supplied content-type is not a valid media type of the form “type/subtype+ext” or “type/subtype”. It is implementation-defined if a processor accepts any other content type shortcuts. It is a static error (err:XS0111) if an unrecognized content type shortcut is specified.

To determine if a document is acceptable, the (expanded) list of content types is considered from left to right. If the actual content type matches an acceptable content type, the document is acceptable. If it matches a forbidden content type, then it is not. A content type that isn’t matched is ignored. The document is considered acceptable if and only if it matches at least one acceptable content type and the last content type that matched was not forbidden.

For example: a document with the content type “image/svg” is acceptable if the content type list expands to “image/* application/xml” but it is not acceptable if the content type list expands to “image/* -image/svg”. (Note that order matters; the document would be considered acceptable if the content type list expands to “-image/svg image/*”.)

In the particular case of shortcut values, note that “application/xhtml+xml” is acceptable if the content type list is “xml html” but not if it is “html xml”.

It is a dynamic error (err:XD0038) if an input document arrives on a port and it does not match the allowed content types.

4.1. External Documents

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

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

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

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

Version 3.1 of XProc does not require implementations to guarantee that multiple attempts to dereference the same URI always produce the same results.

6.1. Connections and the Default Readable Port

The default readable port is a convenience for pipeline authors. In the document which describes a pipeline, steps are sequential elements and it is very common for the output of one step to form the natural input to the step described by its immediately following sibling. Consider the following fragment:

<p:add-xml-base/>
 
<p:add-attribute attribute-name="element-count"
                 attribute-value="{count(/*/*)}"/>

The output from the add XML base step is the natural input to the add-attribute step. The add XML base step is the source for both the document that will be processed by the add-attribute step and the document that will be used as the context item for the expression in the attribute-value attribute.

The fact that the output of the default readable port is used by the following step establishes a connection between the add XML base step and the add-attribute step.

However, unlike an explicit binding which always forms a connection, the default readable port only forms a connection if it is used. If the processor determines that the default readable port is not used, then it must forgo the connection and the steps can run in parallel.

Consider the following fragment:

<p:add-xml-base/>
 
<p:add-attribute attribute-name="class"
                 attribute-value="homepage">
  <p:with-input port="source">
    <p:document href="http://example.com/"/>
  </p:with-input>

The output of the add XML base step is still the default readable port, but it isn’t the source for the add-attribute step nor is the context item used in evaluating the attribute-value option (or any other option, including the default values of unspecified options), so the processor must omit the connection. This leads to increased parallelism and possibly improved performance.

However, it can cause unexpected results when steps have side-effects. Consider this slightly contrived pipeline fragment:

<p:file-touch href="tempdoc.stamp"/>
 
<p:file-copy href="tempdoc.stamp" target="time.stamp"/>
 
<p:file-delete href="tempdoc.stamp"/>

Each of the file steps has a primary output port and consequently provides a default readable port to the following step. Even though the file steps don’t have input ports, the document on the default readable port is the context item for evaluating the options on each step.

However, an implementation will observe that none of the options use the context item (and there are no inputs). Consequently, there are no connections between these steps and they can be run in an arbitrary order, or even in parallel. Running delete, followed by copy, followed by touch would be perfectly correct but would not have the side-effects expected by the pipeline author.

There’s a trade-off here between giving implementations the freedom to execute pipelines more efficiently and not violating user expectations. In practice, this problem only arises when scheduling steps that have side effects, steps with side effects are (relatively) uncommon, and by their nature are impossible for the processor to schedule with complete confidence.

The pipeline author can make the dependencies explicit in the pipeline, which will ensure that the processor schedules the steps in an order that has the desired the side-effects:

<p:file-touch name="touchstamp" href="tempdoc.stamp"/>
 
<p:file-copy name="copystamp" depends="touchstamp"
             href="tempdoc.stamp" target="time.stamp"/>
 
<p:file-delete depends="copystamp"
               href="tempdoc.stamp"/>

Explicitly marking the dependencies between steps that have side effects is good practice.

6.2. Namespace Fixup on XML Outputs

XProc processors are expected, and sometimes required, to perform namespace fixup on XML outputs. Unless the semantics of a step explicitly says otherwise:

• The in-scope namespaces associated with a node (even those that are inherited from namespace bindings that appear among its ancestors in the document in which it appears initially) are assumed to travel with that node.

• Changes to one part of a tree (wrapping or unwrapping a node or renaming an element, for example) do not change the in-scope namespaces associated with the descendants of the node so changed.

As a result, some steps can produce XML documents which have no direct serialization (because they include nodes with conflicting or missing namespace declarations, for example). To produce a serializable XML document, the XProc processor must sometimes add additional namespace nodes, perhaps even renaming prefixes, to satisfy the constraints of Namespaces in XML. This process is referred to as namespace fixup.

Implementors are encouraged to perform namespace fixup before passing documents between steps, but they are not required to do so. Conversely, an implementation which does serialize between steps and therefore must perform such fixups, or reject documents that cannot be serialized, is also conformant.

Except where the semantics of a step explicitly require changes, processors are required to preserve the information in the documents and fragments they manipulate. In particular, the information corresponding to the Infoset properties [attributes], [base URI], [children], [local name], [namespace name], [normalized value], [owner], and [parent] must be preserved.

The information corresponding to [prefix], [in-scope namespaces], [namespace attributes], and [attribute type] should be preserved, with changes to the first three only as required for namespace fixup. In particular, processors are encouraged to take account of prefix information in creating new namespace bindings, to minimize negative impact on prefixed names in content.

Except for cases which are specifically called out in Steps 3.1, the extent to which namespace fixup, and other checks for outputs which cannot be serialized, are performed on intermediate outputs is implementation-defined.

Whenever an implementation serializes XML, for example for pipeline outputs, logging, or as part of steps such as p:store or p:http-request, it is a dynamic error if that serialization can not be done so as to produce a document which is both well-formed and namespace-well-formed, as specified in XML and Namespaces in XML.

7.1. Evaluating expressions during static analysis

Several kinds of expressions are evaluated during static analysis:

1. The select expressions on static options.

2. Value templates in the attributes or descendants of p:input and p:output and map attributes on those descendants.

3. Expressions in use-when attributes used for conditional element exclusion.

For the purposes of evaluating a these expressions, the initial context node, position, and size are all undefined. The in-scope bindings are limited to the lexically preceding, statically declared options. There are no available collections.

Options declared as the direct children of p:library in imported libraries are considered in-scope for the declarations that follow.

The entire expression must be evaluated without reference to the non-static inputs to the pipeline. Expressions can access documents as long as they are available statically.

Consider:

<p:declare-step version="3.1"
                xmlns:p="http://www.w3.org/ns/xproc">
  <p:input port="source"/>
  <p:option name="A" static="true"
            select="5"/>
  <p:option name="B" static="true"
            select="$A + count(doc('doc.xml')//*)" />
  <p:variable name="D" select="count(//*)"/>
 
  …
</p:declare-step>

The value of $A will be 5, unless a different value is provided before static analysis. The value of $B will be the value of $A plus the number of elements in doc.xml which must be successfully resolved during static analysis. Although $D can reference the document provided dynamically on the source port, neither $A nor $B may.

The results of XProc extension functions may differ during static analysis, as described in the description of each function.

Any errors that occur while evaluating expressions during static analysis will be raised statically.

7.2. Dynamic evaluation of the pipeline

Dynamic evaluation of the pipeline occurs when it begins to process documents. The processor evaluates any expressions necessary to provide all of the input documents and options required. The step processes the input documents and produces outputs which flow through the pipeline.

Unless otherwise specified, expressions that appear in attribute values (attribute value templates, map and array initializers that are always treated as expressions, etc.) get their context item from the default readable port. If there is no default readable port, the context item is undefined.

<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:with-input port="source" select="//section"/>
</p:split-sequence>

8.1. System Properties

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

xs:string p:system-property(xs:string property);

The $property string must have the form of an EQName. If it is a QName, it is expanded using the namespace declarations in scope for the expression. It is a dynamic error (err:XD0015) if a QName is specified and it cannot be resolved with the in-scope namespace declarations. The p:system-property function returns the string representing the value of the system property identified by the EQName. If there is no such property, the empty string must be returned.

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

p:episode

Returns a string which should be unique for each invocation of the pipeline processor. In other words, if a processor is run several times in succession, or if several processors are running simultaneously, each invocation of each processor should get a distinct value from p:episode.

The unique identifier must be a valid XML name.

p:locale

Returns a string which identifies the current environment (usually the OS) language. This is useful for, for example, message localization purposes. The exact format of the language string is implementation-defined but should be consistent with the xml:lang attribute.

p:product-name

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

p:product-version

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

p:vendor

Returns a string which identifies the vendor of the processor.

p:vendor-uri

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

p:version

Returns the version(s) of XProc implemented by the processor as a space-separated list. For example, a processor that supports XProc 1.0 would return “1.0”; a processor that supports XProc 1.0 and 3.0 would return “1.0 3.0”; a processor that supports only XProc 3.0 would return “3.0”.

p:xpath-version

Returns the version(s) of XPath implemented by the processor for evaluating XPath expressions on XProc elements. The result is a space-separated list of versions supported. For example, a processor that only supports XPath 3.1 would return “3.1”; a processor that supports XPath 3.1 and XPath 3.2 could return “3.1 3.2”.

p:psvi-supported

Returns true if the implementation supports passing PSVI annotations between steps, false otherwise.

Implementations may support additional system properties but such properties must be in a namespace and must not be in the XProc namespace.

The p:system-property function behaves normally during static analysis. It is implementation-defined which additional system properties are available during static analysis. If an additional system property is not available during static analysis, an empty string must be returned.

8.2. Step Available

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

xs:boolean p:step-available(xs:string step-type);

The $step-type string must have the form of an EQName. If it is a QName, it is expanded using the namespace declarations in scope for the expression. It is a dynamic error (err:XD0015) if a QName is specified and it cannot be resolved with the in-scope namespace declarations. The p:step-available function returns true if and only if the processor knows how to evaluate a step of the specified type where the function is called.

In case the argument of p:step-available refers to a step that is currently being defined, the function returns false. In practice this occurs only if:

• p:step-available is used in a use-when expression on or within the p:declare-step that defines the step to which it refers.

• p:step-available is used in a use-when expression on a p:library that contains the declaration of the step to which it refers.

The p:step-available behaves normally during static analysis.

8.3. Iteration Position

Some compound steps, such as p:for-each and p:viewport, process a sequence of documents. The iteration position is the position of the current document in that sequence: the first document has position 1, the second 2, etc. The p:iteration-position function returns the iteration position of the nearest compound step that processes a sequence of documents.

xs:integer p:iteration-position();

If there is no compound step that processes a sequence of documents among the ancestors of the element on which the expression involving p:iteration-position occurs, it returns 1.

The value of the p:iteration-position function during static analysis is 1.

8.4. Iteration Size

Both p:for-each and p:viewport process a sequence of documents. The iteration size is the total number of documents in that sequence. The p:iteration-size function returns the iteration size of the nearest ancestor compound step that processes a sequence of documents.

xs:integer p:iteration-size();

If there is no p:for-each or p:viewport among the ancestors of the element on which the expression involving p:iteration-size occurs, it returns 1.

The value of the p:iteration-size function during static analysis is 1.

8.5. Version Available

Returns true if and only if the processor supports the XProc version specified.

xs:boolean p:version-available(xs:string version);

A version 3.1 processor will return true() when p:version-available('3.1') is evaluated.

The p:version-available function behaves normally during static analysis.

8.6. XPath Version Available

Returns true if and only if the processor supports the XPath version specified.

xs:boolean p:xpath-version-available(xs:string version);

A processor that supports XPath 3.1 will return true() when p:xpath-version-available('3.1') is evaluated.

The p:xpath-version-available function behaves normally during static analysis.

8.7. Document properties

This function retrieves the document properties of a document as a map.

map(xs:QName,item()*) p:document-properties(item() doc);

The map returned contains (exclusively) the document properties associated with the doc specified. If the item is not associated with a document, the resulting map will be empty.

Document properties are associated with documents that flow out of steps. Documents loaded with XPath functions or through other out-of-band means may not have properties associated with them. In order to provide a consistent interface for pipeline authors, the base URI of a node is always returned in the base-uri property and the content-type property always contains at least the most general appropriate content type: If the document node has a single text node child, text/plain is used, application/xml otherwise.

The p:document-properties function behaves normally during static analysis.

8.8. Document property

This function retrieves a single value from the document properties of a document.

item()* p:document-property(item() doc,
                            item() key);

The item returned is the value of the property named $key in the document properties. An empty sequence is returned if $doc is not associated with a document or no such key exists. $key is interpreted as follows:

• If $key is of type xs:QName, its value is used unchanged.

• If $key is an instance of type xs:string (or a type derived from xs:string) its value is transformed into a xs:QName using the XPath EQName production rules. That is, it can be written as a local-name only, as a prefix plus local-name or as a URI plus local-name (using the Q{} syntax).

  It is a dynamic error (err:XD0061) if $key is of type xs:string and cannot be converted into a xs:QName.

• If $key is of any other type, the function returns the empty sequence.

The p:document-property function behaves normally during static analysis.

8.9. Transform file system paths into URIs and normalize URIs

Most web technologies identify resources with URIs, but XProc must also operate with resources that are identified with strings encoded in other ways, for example, file system paths and the names of resources in archive files.

The p:urify function attempts to transform file system paths into file URIs (RFC 3986). If a presumptive yet not fully compliant URI is given as an argument, p:urify attempts to resolve the string into a URI.

The p:urify function resolves a string into a URI by employing a series of heuristics. These have been selected so that p:urify will not corrupt any actual, valid URIs and with the goal that it will return the least surprising result for any other string. If a pipeline author has more context to determine how a string should be transformed into a URI, writing the conversion process “by hand” in the pipeline may achieve better results.

xs:string p:urify(xs:string filepath,
                  xs:string? basedir);

xs:string p:urify(xs:string filepath);

If the single-argument version of the function is used, the result is the same as calling the two-argument version with basedir set to the empty sequence.

The p:urify function behaves normally during static analysis.

The heuristics that p:urify performs occur in two stages: first, the input string is analyzed to identify its features, then these features are used to construct a final URI string. An additional “fixup” process may be performed on portions of the URI.

To make the operation of the p:urify function easier to understand, the description that follows is presented as an algorithm with regular expressions. Implementors are not required to implement it this way, any implementation that achieves the correct results can be used.

The function may be implemented as an operation on strings; it need not try to determine the existence of a file or directory, and it should not follow symbolic links. However, two pieces of information need to be known from the environment: Whether the operating system identifies as “Windows” and the value of the file separator. More precisely, the operating system identifies as Windows if the os-name property as returned by the p:os-info steps starts with the string “Windows”. The file separator is what p:os-info returns as the file-separator property. If either of them are not known, it is assumed that the operating system is not Windows and the file separator is the forward slash, “/”.

The comparisons and regular expressions that follow are presented in lower case, but all of the operations performed are case blind: “file”, “FILE”, “File”, and “FiLe” are all identical.

8.10. Function library importable

The p:function-library-importable function reports whether or not function libraries of a particular type can be imported.

xs:boolean p:function-library-importable(xs:string library-type);

The $library-type string is interpreted as a content type. If the processor understands (i.e. if p:import-functions understands) how to load function libraries of that type, this function returns true(), otherwise it returns false().

The p:function-library-importable function behaves normally during static analysis.

8.11. Lookup URI

The p:lookup-uri function attempts to determine what URI would be dereferenced if an attempt was made to retrieve a resource.

xs:anyURI p:lookup-uri(xs:anyURI href);

Many systems employ some form of URI resolver. A URI resolver allows one resource to be substituted for another, perhaps loading file:/system/xml/doc.rng when https://example.com/schemas/doc.rng is requested. It is implementation-defined which kinds of URI resolvers a processor supports, if any, and how they are configured.

If the processor has a URI resolver, the p:lookup-uri function allows the pipeline to “peek” at what URI will be used in the request if an attempt is made to retrieve $href. If the URI resolver maps A.xml to B.xml, then p:lookup-uri('A.xml') should return B.xml.

If the processor can’t determine what the mapping is (because the resolver being used doesn’t provide an API to do so, for example), or doesn’t support a resolver, the function should return the original URI.

The implementation must not attempt to dereference the resource in order to identify the mapping. Consequently, this function cannot determine if one or more server side redirects may occur and it has no insight into what caching proxies may be involved if the request accesses the network.

The p:lookup-uri function behaves normally during static analysis but note that it is possible that a processor might use different resolvers at compile-time and run-time.

8.12. Other XPath Extension Functions

It is implementation-defined if the processor supports any other XPath extension functions. Additional extension functions, if any, must not use any of the XProc namespaces.

The value of the any other XPath extension functions during static analysis is implementation-defined.

10.1. Attribute Value Templates

In an attribute that is designated as an attribute value template, an expression can be used by surrounding the expression with curly brackets ({}), following the general rules for value templates.

Curly brackets are not treated specially in an attribute value in an XProc pipeline unless the attribute is specifically designated as one that permits an attribute value template. Option shortcuts permit attribute value templates. Whether or not an extension attribute permits attribute value templates is implementation-defined. In element syntax summaries in this specification, the value of an attribute that allows attribute value templates is surrounded by curly brackets.

An attribute value template can be seen as an alternating sequence of zero or more “fixed” (non-expression) parts and expression parts.

The result of the attribute value template is the concatenation of the fixed parts and the string-value of the result of evaluating each expression part.

The value of an attribute that contains attribute value templates is a single string (the concatenation of the string values of the evaluated templates and non-template parts) as an xs:untypedAtomic.

10.2. Text Value Templates

In a text node that is designated as a text value template, expressions can be used by surrounding each expression with curly brackets ({}), following the general rules for value templates.

Text nodes that are descendants of a p:inline and text nodes that are descendants of an element node in an implicit inline may be text value templates. No other text node is a text value template.

Whether or not a text node that may be a text value template is designated one is determined by expand-text and p:inline-expand-text attributes, see Section 14.9.1, “Expand text attributes”.

A text value template can be seen as an alternating sequence of zero or more “fixed” (non-expression) parts and expression parts.

This produces a sequence of strings (the fixed parts) and items (the results of evaluating each expression). Any items that are non-string atomic values are converted to strings by taking their string value. Strings are converted into text nodes.

The result of the text value template is this sequence of nodes.

If a node to be inserted with a text value template is a document node, all the children of the document node are inserted.

How the nodes are inserted depends on the content type of the p:inline.

1. If the content type is an XML media type or an HTML media type, the nodes are added to the XML document where they occur. This is analogous to the way element constructors work in XQuery 1.0.

   If the node is an attribute it is added to an element parent if and only if the attribute either has no preceding nodes in the sequence of nodes or has only attributes as preceding nodes. It is a dynamic error (err:XD0052) if the XPath expression in a TVT evaluates to an attribute and either the parent is not an element or the attribute has a preceding node that it not an attribute.

2. If the content type is not an XML media type or an HTML media type, each text value template is replaced by the concatenation of the serialization of the nodes that result from evaluating the template.

   ☝

   Important

   This is a backwards incompatible change from XProc 3.0 where the “xml” serialization method was specified. Using the XML serialization, it was very difficult to get un-escaped markup into text content. Although, as the examples showed, it could be useful for JSON content, even that was unlikely to work in the general case because of problems with attribute value quotation.

This serialization is performed with the following serialization parameters:

Any other text output parameters used when serializing a text value template are implementation-defined. It is a dynamic error (err:XD0052) if the XPath expression in a TVT evaluates to an attribute node when the content type is not an XML media type or an HTML media type.

Interpretation of the character content of the p:inline according to the media type occurs after text value templates have been replaced.

<p:inline content-type="application/xml">
  <attribution>{$name/node()}</attribution>
</p:inline>

<attribution><given>Mary</given> <surname>Smith</surname></attribution>

<p:inline content-type="application/json">
  {{ "name": "{$name/node()}" }}
</p:inline>

{ "name": "Mary Smith" }

<p:inline content-type="application/json">
  {{ "name": "{
     replace(
       serialize($name/node(), map{'method':'xml'}),
       '&quot;', '\\&quot;')}" }}
</p:inline>

{"name":"<given>Mary<\/given> <surname>Smith<\/surname>"}

11.1. Variables

Pipeline authors can create variables to hold computed values.

A variable is a name/value pair. The name must be an expanded name. The value may be any XPath data model value. Variable names are always expressed as literal values, pipelines cannot construct variable names dynamically.

The names of variables and options are not distinct and are lexically scoped. We say that a variable shadows another variable (or option) if it has the same name and appears later in the same lexical scope.

Consider this pipeline:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
  xmlns:xs="http://www.w3.org/2001/XMLSchema" version="3.1">
  
  <p:option name="bname" as="xs:integer" select="1"/>
  <p:identity message="NAME1={$bname}">
    <p:with-input port="source">
      <p:empty/>
    </p:with-input>
  </p:identity>
  
  
  <p:variable name="bname" select="$bname + 1"/>
  <p:identity message="NAME2={$bname}"/>
  
  <p:variable name="bname" select="7"/>
  <p:identity message="NAME3={$bname}"/>
  
</p:declare-step>

If no overriding value is provided for $bname at runtime, the pipeline will produce three messages: “NAME1=1”, “NAME2=2”, and “NAME3=7”. (If an overriding value is provided at runtime, “NAME1” will have that value, “NAME2” will have one more than that value, and “NAME3” will have the value 7.

11.2. Options

Some steps accept options. The value of an option is the default value specified in its declaration, or a value provided by the caller of the step (overriding the default). If it has neither a default value nor a provided value, its value is the empty sequence.

An option is a name/value pair. The name must be an expanded name. The value may be any XPath data model value. Option names are always expressed as literal values, pipelines cannot construct option names dynamically.

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.

Some steps require a set of name/value pairs for the operations they perform. For example, an XSLT stylesheet might have required parameters or an XQuery query might have external variables. In the XProc Step Library, the standard way to pass such values to the step is to use an option named “parameters” whose value is a map.

11.3. Static Options

A p:option may be declared “static”; options declared within a p:library must be static. It is a static error (err:XS0109) if options that are the direct children of p:library are not declared “static”.

The values of static options are computed during static analysis. Consequently, expressions which initialize static options may not refer to the context item, variables, or other options that are not static.

Every static option must have exactly one in-scope declaration. It is a static error (err:XS0088) if the qualified name of a static option shadows the name of another static option or a variable.

It is not an error if two static options with the same name appear in different scopes, but it is not good practice. Bear in mind, for example, that if the implementation provides a mechanism for specifying default values for static options at compile time, the value provided for any option must satisfy the type specified on every static option declaration with that name. Any mechanism for specifying default values for static options applies equally to options whether they are public or private.

Libraries that define static options, especially private ones, are encouraged to use namespaces so that collision with the names of options in the calling pipeline, or other imported libraries are unlikely.

11.4. Variable and option types

Variables and options may declare that they have a type using the as attribute. The attribute value must be an XPath 3.1 sequence type. It is a static error (err:XS0096) if the sequence type is not syntactically valid. The sequence type item()* is assumed if no explicit type is provided.

If a variable or option declares a type, the supplied value of the variable or option is converted to the required type, using the function conversion rules specified by XPath 3.1. It is a dynamic error (err:XD0036) if the supplied or defaulted value of a variable or option cannot be converted to the required type.

11.5. Implicit casting

For the most part, the rules for casting between types in XPath work the way authors expect. You can type “3” for a decimal, you don’t have to type “3.0”, and an untyped atomic value, for example in an attribute such as limit="3", is implicitly cast to a number if that’s the required type. You don’t have to type limit="{xs:integer(3)}".

Unfortunately, there are two common cases in XProc that are not handled by the XPath conversion rules: conversions from strings to QNames or URIs. (Technically, conversions from xs:untypedAtomic or xs:string, or from types derived from xs:string, values to xs:QName or xs:anyURI values.) XProc defines additional implicit casting rules for the case where an expression is evaluated to provide the value of a variable or option. (These are not extensions to the XPath rules in the general case and do not apply in arbitrary expressions.)

11.6. Namespaces on variables and options

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

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

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

The default namespace bindings associated with a variable or option value are computed as follows:

1. If the select attribute was used to specify the value and it consisted of a single VariableReference (per XPath 3.1), then the namespace bindings from the referenced option or variable are used.

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

   The expression is evaluated in the appropriate context, See Section 7.2.2, “XPath in XProc”.

3. Otherwise, the in-scope namespaces from the element providing the value are used. (For options specified using syntactic shortcuts, the step element itself is providing the value.)

The default namespace is never included in the namespace bindings for a variable or option value. Unqualified names are always in no-namespace.

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

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
	        xmlns:ex="http://example.org/ns/ex"
	        xmlns:h="http://www.w3.org/1999/xhtml"
                type="ex:delete-in-div" version="3.1">
<p:input port="source"/>
<p:output port="result"/>
<p:option name="divchild" required="true"/>
 
<p:delete>
  <p:with-option name="match" select="concat('h:div/',$divchild)"/>
</p:delete>
 
</p:declare-step>

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

<ex:delete-in-div 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']"/>

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

If pipeline authors cannot arrange for all of the necessary namespace bindings to be in scope, then EQNames can be used to remove the dependency on namespace bindings:

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

In this example, the expression will match “p” elements in the XHTML namespace irrespective of any bindings that may or may not be in scope.

14.1. XProc Namespaces

There are three namespaces associated with XProc:

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

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

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

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

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

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

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 and the prefix “xsi:” to refer to the namespace http://www.w3.org/2001/XMLSchema-instance

14.2. Scoping of Names

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

Within a p:library, declaring that the visibility of a step or static option is “private” limits its visibility outside of the library. Note, however, that if other declarations of the same name are visible from the point where the private declaration occurs, that is still an error.

14.3. Base URIs and xml:base

If a relative URI appears in an option of type xs:anyURI, the base URI against which it must be made absolute is the base URI of the p:option element. If the option value is specified using a syntactic shortcut, the base URI of the step element on which the shortcut attribute appears must be used. In general, whenever a relative URI appears in an xs:anyURI, 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.

As a consequence of the fact that XProc uses the semantics of XML Base for all xml:base attributes that appear in an XProc pipeline, a pipeline author cannot set the literal xml:base attribute on an inline element with an attribute value template. This is an error:

<p:identity>
  <p:with-input>
    <p:inline>
      <doc>
        <page xml:base="{$someExpression}">somefile.xml</page>
      </doc>
    </p:inline>
  </p:with-input>
</p:identity>

The XML base value “{$someExpression}” is not a valid URI. Instead, you must use p:add-attribute or p:set-attributes. For example:

<p:identity>
  <p:with-input>
    <p:inline>
      <doc>
        <page>somefile.xml</page>
      </doc>
    </p:inline>
  </p:with-input>
</p:identity>
 
<p:add-attribute match="/doc/page"
                 attribute-name="xml:base"
                 attribute-value="{$someExpression}"/>

For XML documents, HTML documents, and text documents, the pipeline author can control the base URI of the document node by manipulating the document property “base-uri”.

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

The semantics of an xml:id attribute are that it is an ID. An XProc processor does not directly use the ID values, so it is not explicitly required to validate that the values of attributes named xml:id conform to the constraints of XML ID values. It may be possible to set the literal xml:id attribute on an inline element with an attribute value template, but it is not best practice. It is implementation-dependent if a processor validates xml:id attribute values. (The same observations apply to xml:lang and xml:space attributes.)

14.5. Associating Documents with Ports

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 where connections may be made, except that p:input may not include a connection by source.

Specified by URI

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

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

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

See the description of p:document for a complete description of how URIs may be specified.

Specified by source

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

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

<!-- there's no otherstep so this isn't expected to work... -->
<p:xinclude name="expand">
<p:with-input port="source">
<p:pipe step="otherstep" port="result"/>
</p:with-input>
</p:xinclude>

See the description of p:pipe for a complete description of the ports that can be connected.

Specified inline

An inline document is specified directly in the body of the element to which it connects. The content of the p:inline element is used for this purpose.

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

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

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

See the description of p:inline for a complete description of how inline documents may be specified.

Specified explicitly empty

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

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

<p:xslt name="generate" version="2.0">
<p:with-input port="source">
<p:empty/>
</p:with-input>
<p:with-input port="stylesheet">
<p:inline>
<xsl:stylesheet version="2.0">
...
</xsl:stylesheet>
</p:inline>
</p:with-input>
<p:with-option name="template-name" select="'someName'"/>
</p:xslt>

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

See the description of p:empty for a complete description of empty connections.

Note that a p:input, p:with-input, or p:output element may contain more than one p:pipe, p:document, 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.

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

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

14.8. Extension attributes

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.

14.9. Common Attributes

Several attributes can be used on any XProc step, or even any element in a pipeline. For convenience, they are all summarized here.

Attributes from the XML namespace are allowed anywhere. In particular:

• An xml:id attribute is allowed on any element. It has the semantics of xml:id.

• An xml:base attribute is allowed on any element. It has the semantics of XML Base.

• An xml:lang attribute is allowed on any element. It has the semantics of XML 1.0.

• An xml:space attribute is allowed on any element. It has the semantics of XML 1.0.

The remaining attributes are sometimes in no namespace and sometimes explicitly in the XProc namespace. They are in no namespace when they appear on an XProc element; they are in the XProc namespace when they are on an element in any other namespace. In this way, they do not conflict with the names used in other vocabularies. It is a static error (err:XS0097) if an attribute in the XProc namespace appears on an element in the XProc namespace.

<p:declare-step type="ex:A" use-when="p:step-available('ex:B')">
  …
</p:declare-step>
 
<p:declare-step type="ex:B" use-when="p:step-available('ex:A')">
  …
</p:declare-step>

14.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
  reqd-attribute = some-type
  some-attribute? = some-type
  avt-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:

Attributes

• Required attributes are bold. Optional attributes are followed by a question mark.

• If an attribute value may contain an attribute value template, its type is shown in curly brackets: “{ some-type }”. If some-type is xs:anyURI, xs:QName, or a map type with key type of xs:QName, the conversions described in Section 11.5, “Implicit casting” apply.

• An attribute value with a map type marks an XPathExpression expected to deliver a map of the indicated type. If the map type has a key type of xs:QName, the conversions described in Section 11.5, “Implicit casting” apply.

Elements

• A name represent exactly one occurrence of an element with that name.

• Parentheses are used for grouping.

• Elements or groups separated by a comma (“,”) represent an ordered sequence: a followed by b followed by c: (a,b,c).

• Elements or groups separated by a vertical bar (“|”) represent a choice: a or b or c: (a | b | c).

• Elements or groups separated by an ampersand (“&”) represent an unordered sequence: a and b and c, in any order: (a & b & c).

• An element or group followed by a question mark (“?”) is optional; it may or may not occur but if it occurs it can occur only once.

• An element or group followed by an asterisk (“*”) is optional and may be repeated; it may or may not occur and if it occurs it can occur any number of times.

• An element or group followed by a plus (“+”) is required and may be repeated; it must occur at least once, and it can occur any number of times.

For clarity of exposition, the common attributes (see Section 14.9, “Common Attributes”) are elided from the summaries as are the p:documentation and p:pipeinfo elements, which are allowed anywhere, and attributes that are syntactic shortcuts for option values.

The types given for attributes should be understood as follows:

• ID, NCName, NMTOKEN, NMTOKENS, anyURI, boolean, integer, string: As per W3C XML Schema: Part 2 including whitespace normalization as appropriate.

• EQName: With whitespace normalization as per W3C XML Schema: Part 2 for QNames. Note, however, that QNames that have no prefix are always in no-namespace, irrespective of the default namespace.

• EQNameList: As a whitespace separated list of EQNames, per the definition above.

• PrefixList: As a list with [item type] NMTOKEN, per W3C XML Schema: Part 2, including whitespace normalization.

• ExcludeInlinePrefixes: As a PrefixList per the definition above, with the following extensions: the tokens #all and #default may appear.

• XPathExpression, XSLTSelectionPattern: As a string per W3C XML Schema: Part 2, including whitespace normalization, and the further requirement to be a conformant Expression per XPath 3.1 or selection pattern per XSLT 3.0.

• MediaTypes: As a whitespace separated list of media types as defined in RFC 2046.

14.11. Common errors

A number of errors apply generally:

• It is a static error (err:XS0059) if the pipeline element is not p:declare-step or p:library.

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

• It is a static error (err:XS0038) if any required attribute is not provided.

• It is a static error (err:XS0077) if the value on an attribute of an XProc element does not satisfy the type required for that attribute.

• It is a dynamic error (err:XD0028) if any attribute value does not satisfy the type required for that attribute.

• It is a static error (err:XS0044) if any step contains an atomic step for which there is no visible declaration.

• It is a static error (err:XS0037) if any user extension step or any element in the XProc namespace other than p:inline directly contains text nodes that do not consist entirely of whitespace.

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

• It is a dynamic error (err:XD0012) if any attempt is made to dereference a URI where the scheme of the URI reference is not supported. Implementations are encouraged to support as many schemes as is practical and, in particular, they should support both the file: and http(s): schemes. The set of URI schemes actually supported is implementation-defined.

• It is a dynamic error (err:XD0030) if a step is unable or incapable of performing its function. This is a general error code for “step failed” (e.g., if the input isn't of the expected type or if attempting to process the input causes the implementation to abort). Users and implementers who create extension steps are encouraged to use this code for general failures.

• In most steps which use a select expression or selection pattern, any kind of node can be identified by the expression or pattern. However, some expressions and patterns on some steps are only applicable to some kinds of nodes (e.g., it doesn't make sense to speak of adding attributes to a comment!).

  It is a dynamic error (err:XC0023) if a select expression or selection pattern returns a node type that is not allowed by the step.

• It is a static error (err:XS0100) if the pipeline document does not conform to the grammar for pipeline documents. This is a general error code indicating that the pipeline is syntactically incorrect in some way not identified more precisely in this specification.

• It is a dynamic error (err:XD0083) if an expression in the pipeline is cannot be evaluated (because of errors in expression syntax, references to unbound namespace prefixes, references to unknown variables or functions, etc.). This is a general error code indicating that dynamic expression evaluation failed for some reason not identified more precisely in this specification.

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.

15.1. Pipelines

The document element of a pipeline document is p:declare-step which 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.

Viewed from the outside, a p:declare-step 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.

A p:declare-step element can also be nested inside other p:declare-step or p:library elements in which case it simply declares a pipeline that will be run elsewhere.

For more details, see Section 16.5, “p:declare-step”.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
                version="3.1">
<p:input port="source"/>
<p:output port="result"/>
 
<p:xinclude/>
 
<p:validate-with-xml-schema>
  <p:with-input port="schema">
    <p:document href="http://example.com/path/to/schema.xsd"/>
  </p:with-input>
</p:validate-with-xml-schema>
 
<p:xslt>
  <p:with-input port="stylesheet">
    <p:document href="http://example.com/path/to/stylesheet.xsl"/>
  </p:with-input>
</p:xslt>
 
</p:declare-step>

15.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:with-input? & 
      p:output*),
     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:for-each has a single anonymous input: its connection is provided by the p:with-input. 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:

• The port named “current” on the p:for-each is added to the readable ports.

• The port named “current” on the p:for-each is made the default readable port.

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:with-input 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:with-input port="stylesheet"
href="http://example.com/xsl/html.xsl"/>
</p:xslt>
 
<p:xslt name="make-fo">
<p:with-input port="source" pipe="current@chapters"/>
<p:with-input port="stylesheet"
href="http://example.com/xsl/fo.xsl"/>
</p:xslt>
</p:for-each>

15.3. p:viewport

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

<p:viewport
  name? = NCName
  match = XSLTSelectionPattern>
    ((p:with-input? & 
      p:output?),
     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 has a single anonymous input: its connection is provided by the p:with-input. If no document is explicitly provided, then the viewport source is read from the default readable port. If the p:viewport input is a sequence, each document in the sequence is processed in turn producing a sequence on the output. It is a dynamic error (err:XD0072) if a document appearing on the input port of p:viewport is neither an XML document nor an HTML document.

The match attribute specifies an XSLT selection 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 node. It is a dynamic error (err:XD0010) if the match expression on p:viewport matches an attribute or a namespace node.

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 port named “current” on the p:viewport is added to the readable ports.

• The port named “current” on the p:viewport is made the default readable port.

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 selection pattern matches a particular node then that node 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 node.

If a document resulting from applying the subpipeline to the matched node is an XML document, an HTML document, or a text document, all child nodes of the document node will be used to replace the matched node. It is a dynamic error (err:XD0073) if the document returned by applying the subpipeline to the matched node is not an XML document, an HTML document, or a text document.

If no documents appear on the output port, the matched node will effectively be deleted. If exactly one document appears, the contents of that document will replace the matched node. 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 node.

The output of the p:viewport itself is a sequence of documents that appear 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.

For the documents appearing on port result all document properties will be preserved, except when option match matches a document node and the result from applying the subpipeline to the document node is a (sequence of) text document(s). In this case the content-type property is changed to “text/plain” and the serialization property is removed, while all other document properties are preserved.

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

15.4. p:choose

A choose step is specified by the p:choose element. It is a compound step that contains several, alternate subpipelines. One subpipeline is selected based on the evaluation of XPath expressions.

<p:choose
  name? = NCName>
    (p:with-input?,
     ((p:when+,
       p:otherwise?) | 
      (p:when*,
       p:otherwise)))
</p:choose>

A p:choose contains an arbitrary number of alternative subpipelines, at most one of which will be evaluated. It is a static error (err:XS0074) if a p:choose has neither a p:when nor a p:otherwise.

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. After a subpipeline is selected, no further guard expressions are evaluated. If there are no subpipelines for which the expression evaluates to true then, if a default subpipeline was specified, it is selected, otherwise, no subpipeline 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 outputs available from the p:choose are union of all of the outputs declared in any of its alternative subpipelines. In order to maintain consistency with respect to the default readable port, if any subpipeline has a primary output port, even implicitly, then every subpipline must have a primary output port with the same name. In some cases, this may require making the implicit primary output explicit in order to assure that it has the same name. It is a static error (err:XS0102) if alternative subpipelines have different primary output ports.

Consider a p:choose that has two alternative subpipelines where one declares output ports “A” and “B” and the other declares output ports “B” and “C”. The outputs available from the p:choose are “A”, “B”, and “C”. No documents appear on any outputs not declared in the subpipline actually selected.

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. The content types that can appear on the port are the union of the content types that might be produced by any of the p:when or the p:otherwise. If a primary output port is (explicitly or implicitly) defined and p:otherwise is missing, documents with any content type can appear on that port.

The p:choose can specify the context item against which the XPath expressions that occur on each branch are evaluated. The context item is specified as a connection in the p:with-input. If no explicit connection is provided, the default readable port is used. If the context item is connected to p:empty, or is connected to more than one document, or is unconnected and the default readable port is undefined, the context item is undefined. It is a dynamic error (err:XD0001) if an XPath expression makes reference to the context item, size, or position when 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. These elements are not sibling steps in the usual sense, the names of sibling p:when elements and the p:otherwise element are not in the same scope.

If the following conditions apply:

• The p:choose does not contain a p:otherwise child element

• The p:when branches all define a primary output port (either implicitly or explicitly)

• None of the effective boolean values of the p:when test expressions evaluates to true

Then the p:choose copies any documents that appear on its default readable port to its primary output port. No documents will be written to the primary output port if there isn’t a default readable port, but that is not an error in this case. No documents will ever be written to any non-primary output ports in this case.

Informally: the default sub-pipeline for a missing p:otherwise is a p:identity step (with the additional feature that it isn’t an error if there’s no default readable port). If the p:when branches do not have a primary output port, no output will be produced on any port.

<p:when
  name? = NCName
  test = XPathExpression
  collection? = boolean>
    (p:with-input?,
     p:output*,
     subpipeline)
</p:when>

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

<p:choose name="version">
<p:when test="/*[@version = 2]">
<p:validate-with-xml-schema>
<p:with-input port="schema" href="v2schema.xsd"/>
</p:validate-with-xml-schema>
</p:when>
 
<p:when test="/*[@version = 1]">
<p:validate-with-xml-schema>
<p:with-input port="schema" href="v1schema.xsd"/>
</p:validate-with-xml-schema>
</p:when>
 
<p:when test="/*[@version]">
<p:identity/>
</p:when>
 
<p:otherwise>
<p:error code="NOVERSION">
<p:with-input port="source">
<p:inline>
<message>Required version attribute missing.</message>
</p:inline>
</p:with-input>
</p:error>
</p:otherwise>
</p:choose>

15.5. p:if

A p:if specifies a single subpipeline guarded by a test expression.

<p:if
  name? = NCName
  test = XPathExpression
  collection? = boolean>
    (p:with-input?,
     p:output*,
     subpipeline)
</p:if>

The p:if step has a test attribute which must contain an XPath expression. That XPath expression’s effective boolean value is the guard for the subpipeline contained within it.

The p:if step can specify a context item against which its test expression is to be evaluated. That context node is specified as a connection for the p:with-input. If no context is specified on the p:if, the context comes from the default readable port. If no context is specified and there is no default readable port, the context item is undefined. The context item is also undefined, if no or more than one document is provided. It is a dynamic error (err:XD0001) if an XPath expression makes reference to the context item, size, or position when the context item is undefined.

If the collection attribute has the value true, then the default collection will contain all of the documents that appeared on that input and the context item will be undefined.

The p:if must specify a primary output port (either implicitly or explicitly). It is a static error (err:XS0108) if the p:if step does not specify a primary output port.

The requirement for a primary output port stems from the semantics of p:if:

• If the effective boolean value of the test expression is true, then the subpipline will be run. The output of the p:if in this case is determined by the output ports of the step and what the subpipeline sends to them.

• If the effective boolean value of the test expression is false, then p:if copies any documents that appear on its default readable port to its primary output port. No documents will be written to the primary output port if there isn’t a default readable port, but that is not an error in this case. No documents will ever be written to any non-primary output ports if the test expression is false.

Informally, if the test expression is false, then p:if acts like the identity step (with the additional feature that it isn’t an error if there’s no default readable port). A primary output port is required in order to make these semantics meaningful and consistent.

The sequence attribute and the content-types attribute of the primary output port only apply to the subpipeline of p:if. From the outside a primary output port of a p:if produces sequences and allows documents of any content type. For all other output ports the sequence attribute only applies to the subpipeline, while on the outside these ports may produce sequences.

15.6. p:group

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

<p:group
  name? = NCName>
    (p:output*,
     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-option name="parameters" select="map {'key': $db-key }"/>
<p:with-input port="stylesheet" href="fo.xsl"/>
</p:xslt>
</p:when>
<p:when test="/config/output = 'svg'">
<p:xslt>
<p:with-option name="parameters" select="map {'key': $db-key }"/>
<p:with-input port="stylesheet" href="svg.xsl"/>
</p:xslt>
</p:when>
<p:otherwise>
<p:xslt>
<p:with-option name="parameters" select="map {'key': $db-key }"/>
<p:with-input port="stylesheet" href="html.xsl"/>
</p:xslt>
</p:otherwise>
</p:choose>
</p:group>

15.7. p:try

A try/catch step is specified by the p:try element. It is a compound step that isolates its initial subpipeline, preventing dynamic errors that arise within it from being exposed to the rest of the pipeline. The p:try includes alternate recovery subpipelines, and may include a “finally” subpipeline to perform post-processing irrespective of the outcome of the p:try.

<p:try
  name? = NCName>
    (p:output*,
     subpipeline,
     ((p:catch+,
        p:finally?) | 
       (p:catch*,
        p:finally)))
</p:try>

The step begins with the initial subpipeline; the recovery (or “catch”) pipelines are identified with p:catch elements; a “finally” pipeline is identified with a p:finally element.

It is a static error (err:XS0075) if a p:try does not have at least one subpipeline step, at least one of p:catch or p:finally, and at most one p:finally.

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 considers the recovery subpipelines. If there is no matching recovery subpipeline, the p:try fails.

If a 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.

Irrespective of whether the initial subpipeline succeeds or fails, if any recovery pipeline is selected, and whether it succeeds or fails, the p:finally block is always run after all other processing of the p:try has finished.

The outputs of the p:try are taken from the outputs of the initial subpipeline or the recovery subpipline if an error occurred in the initial subpipeline. The outputs available from the p:try are union of all of the outputs declared (explicitly or implicitly in the absence of any p:output elements if the last step has a primary output port) in any of its alternative subpipelines. In order to maintain consistency with respect to the default readable port, if any subpipeline has a primary output port, even implicitly, then every subpipline must have a primary output port with the same name. In some cases, this may require making the implicit primary output explicit in order to assure that it has the same name. It is a static error (err:XS0102) if alternative subpipelines have different primary output ports.

Consider a p:try that has an initial subpipeline that declares output ports “A” and “B” and a recovery subpipeline that declares output ports “B” and “C”. The outputs available from the p:try are “A”, “B”, and “C”. No documents appear on any outputs not declared in the subpipeline whose results are actually returned.

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. The content types that can appear on the port are the union of the content types that might be produced by the initial subpipeline and any of the recovery subpipelines.

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

If we assume that an absent p:finally always succeeds, evaluation of a p:try falls into one of these cases:

• If the initial pipeline succeeds:

  • If the p:finally succeeds, the p:try succeeds and the outputs of the initial subpipeline are the outputs of the p:try.

  • If the p:finally fails, the p:try fails and the error raised by the p:finally is reported as the cause of the failure.

• If the initial pipeline fails and a recovery subpipeline is selected:

  • If the recovery pipeline succeeds:

    • If the p:finally succeeds, the p:try succeeds and the outputs of the recovery subpipeline are the outputs of the p:try.

    • If the p:finally fails, the p:try fails and the error raised by the p:finally is reported as the cause of the failure.

  • If the recovery pipeline fails:

    • If the p:finally succeeds, the p:try fails and the error raised by the recovery subpipeline is reported as the cause of the failure.

    • If the p:finally fails, the p:try fails and the error raised by the recovery subpipeline must be reported as the cause of the failure. The error raised by the finally pipeline may also be reported in addition to the error raised by the recovery pipeline.

• If the initial pipeline fails and a recovery subpipeline is not selected:

  • If the p:finally succeeds, the p:try fails and the error raised by the initial subpipeline is reported as the cause of the failure.

  • If the p:finally fails, the p:try fails and the error raised by the initial subpipeline must be reported as the cause of the failure. The error raised by the finally pipeline may also be reported in addition to the error raised by the initial subpipeline.

The p:catch and p:finally elements are not sibling steps, the names of sibling p:catch elements and the p:finally element are not in the same scope. The elements of the initial subpipeline are also not in the same scope as the p:catch and p:finally elements or their descendants.

<p:catch
  name? = NCName
  code? = EQNameList>
    (p:output*,
     subpipeline)
</p:catch>

<p:finally
  name? = NCName>
    (p:output*,
     subpipeline)
</p:finally>

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

<c:error
  name? = NCName
  type? = EQName
  code? = EQName
  cause? = EQName
  href? = anyURI
  line? = integer
  column? = integer
  offset? = integer>
    anyNode*
</c:error>

<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:http-request method="post" href="http://example.com/form-action">
<p:with-input>
<p:inline content-type="application/x-www-form-urlencoded"
>name=W3C&amp;spec=XProc</p:inline>
</p:with-input>
</p:http-request>
<p:catch>
<p:identity>
<p:with-input port="source">
<p:inline>
<c:error>HTTP Request Failed</c:error>
</p:inline>
</p:with-input>
</p:identity>
</p:catch>
</p:try>

15.8. Atomic Steps

An atomic step is a step that does not contain a subpipline when it is invoked. The built-in steps described in Steps 3.1 are atomic. Steps like p:for-each and p:try that always have a subpipline are not atomic.

Steps declared with p:declare-step are atomic when they are invoked. It is implementation-dependent whether or not atomic steps can be defined through some other means.

The following table gives an overview over the types of atomic steps and the terms associated with these types: