XProc: An XML Pipeline Language

2.1.1 Step names

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

If the pipeline author does not provide an explicit name, the processor manufactures a default name. All default names are of the form “!1.m.n…” where “m” is the position (in the sense of counting sibling elements) of the step's highest ancestor element within the pipeline document or library which contains it, “n” is the position of the next-highest ancestor, and so on, including both steps and non-step wrappers. For example, consider the pipeline in Example 3, “A validate and transform pipeline”. The p:pipeline step has no name, so it gets the default name “!1”; the p:choose gets the name “!1.2”; the first p:when gets the name “!1.2.1”, etc. If the p:choose had had a name, it would not have received a default name, but it would still have been counted and its first p:when would still have been “!1.2.1”.

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

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

2.2.1 External Documents

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

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

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

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

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

2.2.2 Non-XML Documents

XProc is designed to allow pipeline authors to specify how an XML document, or sequence of XML documents, flows through a series of steps. For the most part, non-XML documents are considered out-of-scope.

However, to be useful, XProc pipelines must interact with the real world where non-XML documents (HTML documents, raster images, non-XML encodings of data, etc.) are a fact of life.

Accordingly, some pipelines may need to access non-XML documents and some non-XML documents may “leak” into pipelines. XProc provides a limited set of tools for processing these documents. In particular, XProc offers the ability to turn some “almost-XML” documents into XML and to allow some non-XML documents to flow quietly through the pipeline.

It is not a goal of XProc that it should be a general-purpose pipeline language for manipulating arbitrary, non-XML resources.

There are two standard ways that a non-XML document may enter a pipeline: directly through p:data or as the result of performing an p:http-request step. Loading non-XML data with a computed URI requires the p:http-request step. Implementors are encouraged to support the file: URI scheme so that users can load local data from computed URIs.

In either case, non-XML documents are converted into text or are base64-encoded, depending on their content type and character encoding. The result is an XML document that consists of a document element containing either escaped text or base64-encoded text. This document can be processed like any other XML document.

The p:unescape-markup step can be used to (attempt to) convert a non-XML document into XML. Well-formed XML that just happens to be represented with escaped markup can always be recovered. For other media types, the ability to construct XML and the precise mechanisms used to make the markup well-formed are implementation-defined.

XProc provides no standard means to save encoded data in its unencoded binary form. Implementors may provide extension methods to allow the p:store step to save the binary data. For example, an implementation might provide a ext:binary serialization method that decoded base64 encoded data before saving it:

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

2.4.1 Namespace Fixup on Outputs

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

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). [Definition: 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 Section 7, “Standard Step Library”, 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 pipeline contents, 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 could 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, regardless of what serialization method, if any, is called for.

2.6.1 XPath 1.0 processors

XProc processors that support only XPath 1.0 do not support any types (or features) beyond those described in [XPath 1.0]. They use the XPath 1.0 data model. Processors must implement all of the XPath 1.0 functions, but are not expect to implement the functions described in [XSLT 1.0].

2.6.2 XPath 2.0 processors

XProc processors that support XPath 2.0 are XPath 2.0 processors. Such processors can refer to the primitive atomic schema types, but cannot import additional types.

XPath 2.0 processors must implement all of the XPath 2.0 functions, but are not expect to implement the functions described in [XSLT 2.0].

2.7.1 System Properties

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

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

The property string must have the form of a QName; the QName is expanded into a name using the namespace declarations in scope for the expression. It is a dynamic error (err:XD0015) if the specified QName 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 QName. If there is no such property, the empty string must be returned.

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

2.7.2 Step Available

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

Function: boolean p:step-available(string step-type)

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

2.7.3 Iteration Position

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

Function: integer p:iteration-position()

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

2.7.4 Iteration Size

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

Function: integer p:iteration-size()

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

2.7.5 Base URI

Returns the base URI of the specified node, if it has one. This function provides an interoperable way for XPath 1.0 based processors to access the base URI of a node. It is conceptually the same as the XPath 2.0 fn:base-uri() function.

Function: string p:base-uri()

Function: string p:base-uri(Node node)

If no argument is specified, the context node is taken to be the argument.

This function returns the [base-uri] property of its argument, or the empty string if no base URI is defined for that argument or argument type.

2.7.6 Resolve URI

Resolves a relative URI with respect to a particular base URI. This function provides an interoperable way for XPath 1.0 based processors to compose URI references. It is conceptually the same as the XPath 2.0 fn:resolve-uri() function.

Function: string p:resolve-uri(String relative)

Function: string p:resolve-uri(String relative, String base)

If no base is specified, the base URI of the context node is used.

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

4.1.1 Example

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

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

<p:xinclude/>

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

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

</p:pipeline>

4.2.1 XPath Context

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

4.2.2 Example

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

<p:for-each name="chapters">
  <p:iteration-source select="//chapter"/>
  <p:output port="html-results">
    <p:pipe step="make-html" port="result"/>
  </p:output>
  <p:output port="fo-results">
    <p:pipe step="make-fo" port="result"/>
  </p:output>

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

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

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

4.3.1 XPath Context

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

4.3.2 Example

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

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

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

4.4.1 p:xpath-context

A p:xpath-context element specifies the context against which an XPath expression will be evaluated. When it appears in a p:when, it specifies the context for that p:when’s test attribute. When it appears in p:choose, it specifies the default context for all of the p:when elements in that p:choose.

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

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

In an XPath 1.0 implementation, if the context node is bound to p:empty, or is unbound and the default readable port is undefined, an empty document node is used instead as the context. In an XPath 2.0 implementation, the context item is undefined.

4.4.2 p:when

A when specifies one subpipeline guarded by a test expression.

<p:when
  test = XPathExpression>
    (p:xpath-context?,
     (p:output |
      p:log)*,
     subpipeline)
</p:when>

Each p:when branch of the p:choose 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 that p:when.

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

4.4.3 p:otherwise

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

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

4.4.4 Example

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

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

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

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

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

4.5.1 Example

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

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

4.6.1 The Error Vocabulary

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

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

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

4.6.2 Example

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

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

4.8.1 Syntactic Shortcut for Option Values

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

The first step uses the standard p:with-option syntax:

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

The second step uses the syntactic shortcut:

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

Note that there are significant limitations to this shortcut syntax:

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

The syntactic shortcuts apply equally to standard atomic steps and extension atomic steps.

5.1.1 Document Inputs

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

An input declaration has the following form:

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind? = "document"
  select? = XPathExpression>
    (p:empty |
      (p:document |
       p:inline |
       p:data)+)?
</p:input>

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

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

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

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

If a binding is provided in the declaration, then select may be used to select a portion of the input identified by the p:empty, p:document, p:data, or p:inline elements in the p:input.

On a p:declare-step for an atomic step, the p:input simply declares the input port. It is a static error (err:XS0042) to attempt to provide a binding for an input port on the declaration of an atomic step.

An input binding has the following form:

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

If no binding is provided for a primary input port, the input will be bound to the default readable port. It is a static error (err:XS0032) if no binding is provided and the default readable port is undefined.

A select expression may also be provided with a binding. The select expression, if specified, applies the specified XPath select expression to the document(s) that are read. Each selected node is wrapped in a document (unless it is a document) and provided to the input port. In other words,

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

provides a single document, but

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

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

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

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

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

It is a dynamic error (err:XD0016) if the select expression on a p:input returns atomic values or anything other than element or document nodes.

An input declaration may include a default binding. If no binding is provided for an input port which has a default binding, then the input is treated as if the default binding appeared.

A default binding does not satisfy the requirement that a primary input port is automatically connected by the processor, nor is it used when no default readable port is defined. In other words, a p:declare-step or a p:pipeline can define defaults for all of its inputs, whether they are primary or not, but defining a default for a primary input usually has no effect. It's never used by an atomic step since the step, when it's called, will always bind the primary input port to the default readable port (or cause a static error). The only case where it has value is on a p:pipeline when that pipeline is invoked directly by the processor. In that case, the processor must use the default binding if no external binding is provided for the port.

5.1.2 Parameter Inputs

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

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  kind = "parameter">
    (p:empty |
      (p:document |
       p:inline)+)?
</p:input>

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

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

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

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

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

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

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

If a parameter input port on a p:pipeline is not bound, it is treated as if it was bound to an automatically created p:sink step. In other words, if a p:pipeline does not contain any steps that have parameter input ports, or if those ports are all explicitly bound elsewhere, the parameter input port is ignored. In this one case, it is not an error for an input port to be unbound.

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

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

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

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

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

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

</p:pipeline>

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

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

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

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

5.7.1 p:variable

A p:variable declares a variable and associates a value with it.

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

The variable's value is specified with a select attribute. It is a static error (err:XS0016) if the select attribute is not specified. The content of the select attribute is an XPath expression which will be evaluated to provide the value of the variable.

<p:variable
  name = QName
  select = XPathExpression>
    ((p:empty |
      p:pipe |
      p:document |
      p:inline |
      p:data)? &
     p:namespaces*)
</p:variable>

If a select expression is given, it is evaluated as an XPath expression using the appropriate context as described in Section 2.6, “XPaths in XProc”, for the enclosing container, with the addition of bindings for all preceding-sibling p:variable and p:option elements. Regardless of the implicit type of the expression, when XPath 1.0 is being used, the string value of the expression becomes the value of the variable; when XPath 2.0 is being used, the type is treated as an xs:untypedAtomic.

Since all in-scope bindings are present in the Processor XPath Context as variable bindings, select expressions may refer to the value of in-scope bindings by variable reference. If a variable reference uses a QName that is not the name of an in-scope binding, an XPath evaluation error will occur.

If a select expression is given, the readable ports available for document binding are the readable ports in the environment inherited by the first step in the surrounding container's contained steps. However, in order to avoid ordering paradoxes, it is a static error (err:XS0019) for a variable's document binding to refer to the output port of any step in the surrounding container's contained steps.

If a select expression is given but no document binding is provided, the implicit binding is to the default readable port in the environment inherited by the first step in the surrounding container's contained steps. It is a static error (err:XS0032) if no document binding is provided and the default readable port is undefined. It is a dynamic error (err:XD0008) if a document sequence is specified in the document binding for a p:variable. In an XPath 1.0 implementation, if p:empty is given as the document binding, an empty document node is used as the context node. In an XPath 2.0 implementation, the context item is undefined.

5.7.2 p:option

A p:option declares an option and may associate a default value with it. The p:option tag can only be used in a p:declare-step or a p:pipeline (which is a syntactic abbreviation for a step declaration).

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

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

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

An option may be declared as required. If an option is required, it is a static error (err:XS0018) to invoke the step without specifying a value for that option.

If an option is not declared to be required, it may be given a default value. The value is specified with a select attribute.

It is a static error (err:XS0017) to specify that an option is both required and has a default value.

If a select attribute is specified, its content is an XPath expression which will be evaluated to provide the value of the variable, which may differ from one instance of the step type to another.

<p:option
  name = QName
  select = XPathExpression />

The select expression is only evaluated when its actual value is needed by an instance of the step type being declared. In this case, it is evaluated as described in Section 5.7.3, “p:with-option” except that

It is a dynamic error (err:XD0026) if the select expression refers to the context or to a QName that is not the name of a preceding sibling p:option.

Regardless of the implicit type of the expression, when XPath 1.0 is being used, the string value of the expression becomes the value of the option; when XPath 2.0 is being used, the value is an xs:untypedAtomic.

5.7.3 p:with-option

A p:with-option provides an actual value for an option when a step is invoked.

The name of the option must be a QName. If it does not contain a prefix then it is in no namespace. It is a static error (err:XS0031) to use an option name in p:with-option if the step type being invoked has not declared an option with that name.

It is a static error (err:XS0004) to include more than one p:with-option with the same option name as part of the same step invocation.

The actual value is specified with a select attribute. It is a static error (err:XS0016) if the select attribute is not specified. The value of the select attribute is an XPath expression which will be evaluated to provide the value of the variable.

<p:with-option
  name = QName
  select = XPathExpression>
    ((p:empty |
      p:pipe |
      p:document |
      p:inline |
      p:data)? &
     p:namespaces*)
</p:with-option>

Regardless of the implicit type of the expression, when XPath 1.0 is being used, the string value of the expression becomes the value of the option; when XPath 2.0 is being used, the value is an xs:untypedAtomic.

All in-scope bindings for the step instance itself are present in the Processor XPath Context as variable bindings, so select expressions may refer to any option or variable bound in those in-scope bindings by variable reference. If a variable reference uses a QName that is not the name of an in-scope binding or preceding sibling option, an XPath evaluation error will occur.

If a select expression is used but no document binding is provided, the implicit binding is to the default readable port. It is a static error (err:XS0032) if no document binding is provided and the default readable port is undefined. It is a dynamic error (err:XD0008) if a document sequence is specified in the binding for a p:with-option. In an XPath 1.0 implementation, if p:empty is given as the document binding, an empty document node is used as the context node. In an XPath 2.0 implementation, the context item is undefined.

5.7.4 p:with-param

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

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

The value is specified with a select attribute. It is a static error (err:XS0016) if the select attribute is not specified. The content of the select attribute is an XPath expression which will be evaluated to provide the value of the variable.

<p:with-param
  name = QName
  select = XPathExpression
  port? = NCName>
    ((p:empty |
      p:pipe |
      p:document |
      p:inline |
      p:data)? &
     p:namespaces*)
</p:with-param>

The values of parameters for a step must be computed after all the options in the step's signature have had their values computed. If a select expression is given on a p:with-param, it is evaluated as an XPath expression using the appropriate context as described in Section 2.6, “XPaths in XProc”, for the containing step, with the addition of variable bindings for all options declared in the containing step's signature.

Regardless of the implicit type of the expression, when XPath 1.0 is being used, the string value of the expression becomes the value of the parameter; when XPath 2.0 is being used, the value is an xs:untypedAtomic.

All in-scope bindings for the step instance itself are present in the Processor XPath Context as variable bindings, so select expressions may refer to any option or variable bound in those in-scope bindings, as well as to any option declared in the step signature, by variable reference. If a variable reference uses a QName that is not the name of an in-scope binding or declared option, an XPath evaluation error will occur.

If a select expression is used but no document binding is provided, the implicit binding is to the default readable port. It is a static error (err:XS0032) if no document binding is provided and the default readable port is undefined. It is a dynamic error (err:XD0008) if a document sequence is specified in the binding for a p:with-param. In an XPath 1.0 implementation, if p:empty is given as the document binding, an empty document node is used as the context node. In an XPath 2.0 implementation, the context item is undefined.

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

5.7.5 Namespaces on variables, options, and parameters

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

<p:delete 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, option or parameter value are computed as follows:

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

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

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

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

</p:pipeline>

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.

The p:namespaces element can be used as a child of p:variable, p:with-option or p:with-param to provide explicit bindings.

<p:namespaces
  binding? = QName
  element? = XPathExpression
  except-prefixes? = prefix list />

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

Irrespective of how the set of namespaces are determined, the except-prefixes attribute can be used to exclude one or more namespaces. The value of the except-prefixes attribute must be a sequence of tokens, each of which must be a prefix bound to a namespace in the in-scope namespaces of the p:namespaces element. All bindings of prefixes to each of the namespaces thus identified are excluded. It is a static error (err:XS0051) if the except-prefixes attribute on p:namespaces does not contain a list of tokens or if any of those tokens is not a prefix bound to a namespace in the in-scope namespaces of the p:namespaces element.

It is a static error (err:XS0041) to specify both binding and element on the same p:namespaces element.

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

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

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

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

</p:pipeline>

The p:namespaces element provides namespace bindings for both of the prefixes necessary to correctly interpret the expression ultimately passed to the p:delete step (the binding for html: is explicitly provided and the binding for h: is in-scope).

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

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

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

</p:pipeline>

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

5.8.1 Declaring atomic steps

When declaring an atomic step, the subpipeline in the declaration must be empty. And, conversely, if the subpipeline in a declaration is empty, the declaration must be for an atomic step.

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

It is not an error for a pipeline to include declarations for steps that a particular processor does not know how to implement. It is, of course, an error to attempt to evaluate such steps.

If p:log or p:serialization elements appear in the declaration of an atomic step, they will only be used if the atomic step is directly evaluated by the processor. They have no effect if the step appears in a subpipeline; only the serialization options of the “top level” step or pipeline are used because that is the only step which the processor is required to serialize.

5.8.2 Declaring pipelines

When a p:declare-step declares a pipeline, that pipeline encapsulates the behavior of the specified subpipeline. Its children declare inputs, outputs, and options that the pipeline exposes and identify the steps in its subpipeline.

The subpipeline may include declarations of additional steps (e.g., other pipelines or other step types that are provided by a particular implementation or in some implementation-defined way) and import other pipelines. If a pipeline has been imported, it may be invoked as a step within the subpipeline that imported it.

The environment inherited by the subpipeline is the empty environment with these modifications:

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

The requested xpath-version must be used to evaluate XPath expressions subject to the constraints outlined in Section 2.6, “XPaths in XProc”.

The psvi-required attribute allows the author to declare that a step relies on the processor's ability to pass PSVI annotations between steps, see Section 2.8, “PSVIs in XProc”. If the attribute is not specified, the value “false” is assumed.

7.1.1 p:add-attribute

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

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

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

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

The value of the attribute-name option must be a QName. The corresponding expanded name is used to construct the added attribute.

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

If an attribute with the same name as the expanded name from the attribute-name option exist on the matched element, the value specified in the attribute-value option is used to set the value of that existing attribute. That is, the value of the existing attribute is changed to the attribute-value value.

This step cannot be used to add namespace declarations. It is a dynamic error (err:XC0059) if the QName value in the attribute-name option uses the prefix 'xmlns' or any other prefix that resolves to the same namespace name as 'xmlns'.

7.1.2 p:add-xml-base

The p:add-xml-base step exposes the base URI via explicit xml:base attributes. The input document from the source port is replicated to the result port with xml:base attributes added to or corrected on each element as specified by the options on this step.

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

The value of the all option must be a boolean.

The value of the relative option must be a boolean.

It is a dynamic error (err:XC0058) if the all and relative options are both true.

The p:add-xml-base step modifies its input as follows:

7.1.3 p:compare

The p:compare step compares two documents for equality.

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

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

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

7.1.4 p:count

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

<p:declare-step type="p:count">
     <p:input port="source" sequence="true"/>
     <p:output port="result"/>
     <p:option name="limit" select="0"/>                           <!-- integer -->
</p:declare-step>

If the limit option is specified and is greater than zero, the p:count step will count at most that many documents. This provides a convenient mechanism to discover, for example, if a sequence consists of more than 1 document, without requiring every single document to be buffered before processing can continue.

7.1.5 p:delete

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

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

The value of the match option must be an XSLTMatchPattern. A match pattern may match multiple items to be deleted.

If an element is selected by the match option, the entire subtree rooted at that element is deleted.

7.1.6 p:directory-list

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

<p:declare-step type="p:directory-list">
     <p:output port="result"/>
     <p:option name="path" required="true"/>                       <!-- anyURI -->
     <p:option name="include-filter"/>                             <!-- RegularExpression -->
     <p:option name="exclude-filter"/>                             <!-- RegularExpression -->
</p:declare-step>

The value of the path option must be an anyURI. It is interpreted as an IRI reference. If it is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:directory-list in the case of a syntactic shortcut value).

It is a dynamic error (err:XC0017) if the absolute path does not identify a directory. It is a dynamic error (err:XC0012) if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.

Conformant processors must support directory paths whose scheme is file. It is implementation-defined what other schemes are supported by p:directory-list, and what the interpretation of 'directory', 'file' and 'contents' is for those schemes.

If present, the value of the include-filter or exclude-filter option must be a regular expression as specified in [XPath 2.0 Functions and Operators], section 7.61 “Regular Expression Syntax”.

If the include-filter pattern matches a directory entry's name, the entry is included in the output. If the exclude-filter pattern matches a directory entry's name, the entry is excluded in the output. If both options are provided, the include filter is processed first, then the exclude filter.

The result document produced for the specified directory path has a c:directory document element whose base URI is the directory path and whose name attribute is the last segment of the directory path (that is, the directory's (local) name).

<c:directory
  name = string>
    (c:file |
     c:directory |
     c:other)*
</c:directory>

Its contents are determined as follows, based on the entries in the directory identified by the directory path. For each entry in the directory, if either no filter was specified, or the (local) name of the entry matches the filter pattern, a c:file, a c:directory, or a c:other element is produced, as follows:

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

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

Any attributes other than name on c:file, c:directory, or c:other are implementation-defined.

7.1.7 p:error

The c:error step generates a dynamic error using the input provided to the step.

<p:declare-step type="p:error">
     <p:input port="source" primary="false"/>
     <p:option name="code" required="true"/>                       <!-- QName -->
</p:declare-step>

The value of the code option must be a QName

This step uses the document provided on its input as the content of the error raised. Since it generates an error upon invocation, there can be no normal output; instead, an instance of the c:errors element will be produced on the error output port, as is always the case for dynamic errors. The error generated can be caught by a p:try just like any other dynamic error.

For example, given the following invocation:

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

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

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

The href, line and column, or offset, might also be present on the c:error to identify the location of the p:error element in the pipeline.

7.1.8 p:escape-markup

The p:escape-markup step applies XML serialization to the children of the document element and replaces those children with their serialization. The outcome is a single element with text content that represents the "escaped" syntax of the children as they were serialized.

<p:declare-step type="p:escape-markup">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="cdata-section-elements" select="''"/>         <!-- ListOfQNames -->
     <p:option name="doctype-public"/>                             <!-- string -->
     <p:option name="doctype-system"/>                             <!-- anyURI -->
     <p:option name="escape-uri-attributes" select="'false'"/>     <!-- boolean -->
     <p:option name="include-content-type" select="'true'"/>       <!-- boolean -->
     <p:option name="indent" select="'false'"/>                    <!-- boolean -->
     <p:option name="media-type"/>                                 <!-- string -->
     <p:option name="method" select="'xml'"/>                      <!-- QName -->
     <p:option name="omit-xml-declaration" select="'true'"/>       <!-- boolean -->
     <p:option name="standalone" select="'omit'"/>                 <!-- "true" | "false" | "omit" -->
     <p:option name="undeclare-prefixes"/>                         <!-- boolean -->
     <p:option name="version" select="'1.0'"/>                     <!-- string -->
</p:declare-step>

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

For example, the input:

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

produces:

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

By default, this step must not generate an XML declaration in the escaped result.

7.1.9 p:filter

The p:filter step selects portions of the source document based on a (possibly dynamically constructed) XPath select expression.

<p:declare-step type="p:filter">
     <p:input port="source"/>
     <p:output port="result" sequence="true"/>
     <p:option name="select" required="true"/>                     <!-- XPathExpression -->
</p:declare-step>

This step behaves just like an p:input with a select expression except that the select expression is computed dynamically.

7.1.10 p:http-request

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

<p:declare-step type="p:http-request">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="byte-order-mark"/>                            <!-- boolean -->
     <p:option name="cdata-section-elements" select="''"/>         <!-- ListOfQNames -->
     <p:option name="doctype-public"/>                             <!-- string -->
     <p:option name="doctype-system"/>                             <!-- anyURI -->
     <p:option name="encoding"/>                                   <!-- string -->
     <p:option name="escape-uri-attributes" select="'false'"/>     <!-- boolean -->
     <p:option name="include-content-type" select="'true'"/>       <!-- boolean -->
     <p:option name="indent" select="'false'"/>                    <!-- boolean -->
     <p:option name="media-type"/>                                 <!-- string -->
     <p:option name="method" select="'xml'"/>                      <!-- QName -->
     <p:option name="normalization-form" select="'none'"/>         <!-- NormalizationForm -->
     <p:option name="omit-xml-declaration" select="'true'"/>       <!-- boolean -->
     <p:option name="standalone" select="'omit'"/>                 <!-- "true" | "false" | "omit" -->
     <p:option name="undeclare-prefixes"/>                         <!-- boolean -->
     <p:option name="version" select="'1.0'"/>                     <!-- string -->
</p:declare-step>

The standard serialization options are provided to control the serialization of any XML content which is sent as part of the request. The effect of these options is as specified in Section 7.3, “Serialization Options”. See Section 7.1.10.2, “Request Entity body conversion” for a discussion of when serialization occurs in constructing a request.

It is a dynamic error (err:XC0040) if the document element of the document that arrives on the source port is not c:request.

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

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

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

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

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

7.1.11 p:identity

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

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

If the implementation supports passing PSVI annotations between steps, the p:identity step must preserve any annotations that appear in the input.

7.1.12 p:insert

The p:insert step inserts the insertion port's document into the source port's document relative to the matching elements in the source port's document.

<p:declare-step type="p:insert">
     <p:input port="source" primary="true"/>
     <p:input port="insertion" sequence="true"/>
     <p:output port="result"/>
     <p:option name="match" select="'/*'"/>                        <!-- XSLTMatchPattern -->
     <p:option name="position" required="true"/>                   <!-- "first-child" | "last-child" | "before" | "after" -->
</p:declare-step>

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if that pattern matches anything other than element, text, processing-instruction, or comment nodes. Multiple matches are allowed, in which case multiple copies of the insertion documents will occur. If no elements match, then the document is unchanged.

The value of the position option must be an NMTOKEN in the following list:

It is a dynamic error (err:XC0025) if the match pattern matches anything other than an element node and the value of the position option is “first-child” or “last-child”.

As the inserted elements are part of the output of the step they are not considered in determining matching elements. If an empty sequence appears on the insertion port, the result will be the same as the source.

7.1.13 p:label-elements

The p:label-elements step generates a label for each matched element and stores that label in the specified attribute.

<p:declare-step type="p:label-elements">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="attribute" select="'xml:id'"/>                <!-- QName -->
     <p:option name="label" select="'concat("_",$p:index)'"/>      <!-- string -->
     <p:option name="match" select="'*'"/>                         <!-- XSLTMatchPattern -->
     <p:option name="replace" select="'true'"/>                    <!-- boolean -->
</p:declare-step>

The value of the attribute option must be a QName.

The value of the label option is an XPath expression used to generate the value of the attribute label.

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if that expression matches anything other than element nodes.

The value of the replace must be a boolean value and is used to indicate whether existing attribute values are replaced.

This step operates by generating attribute labels for each element matched. For every matched element, the expression is evaluated with the context node set to the matched element. An attribute is added to the matched element using the attribute name is specified the attribute option and the string value of result of evaluating the expression. If the attribute already exists on the matched element, the value is replaced with the string value of the expression evaluation result only if the replace option has the value of true.

An implementation must bind the variable “p:index” in the static context of each evaluation of the XPath expression to the position of the element in the sequence of matched elements. In other words, the first element (in document order) matched gets the value “1”, the second gets the value “2”, the third, “3”, etc.

The result of the p:label-elements step is the input document with the attribute labels associated with matched elements. All other non-matching content remains the same.

7.1.14 p:load

The p:load step has no inputs but produces as its result an XML resource specified by an IRI.

<p:declare-step type="p:load">
     <p:output port="result"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="dtd-validate" select="'false'"/>              <!-- boolean -->
</p:declare-step>

The value of the href option must be an anyURI. It is interpreted as an IRI reference. If it is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:load in the case of a syntactic shortcut value).

The value of the dtd-validate option must be a boolean.

Load attempts to read an XML document from the specified IRI reference, which may be relative, in which case it will be resolved relative to the base URI of the element on which it is specified (p:option or p:load in the case of a syntactic shortcut value).

It is a dynamic error (err:XC0026) if the document does not exist or is not well-formed. It is a dynamic error (err:XC0011) if the step is not allowed to retrieve from the specified location. Otherwise, the retrieved document is produced on the result port. The base URI of the result is the (absolute) IRI used to retrieve it.

If the value of the dtd-validate option is true, DTD validation is performed on the retrieved document. It is a dynamic error (err:XC0027) if the document is not valid or the step doesn't support DTD validation.

7.1.15 p:make-absolute-uris

The p:make-absolute-uris step makes an element or attribute's value in the source document an absolute IRI value in the result document.

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

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if the pattern matches anything other than element or attribute nodes.

The value of the base-uri option must be an anyURI. It is interpreted as an IRI reference. If it is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:make-absolute-uris in the case of a syntactic shortcut value).

For every element or attribute in the input document which matches the specified pattern, its XPath string-value is resolved against the specified base URI and the resulting absolute IRI is used as the matched node's entire contents in the output.

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

If the IRI reference specified by the base-uri option on p:make-absolute-uris is not valid, or if it is absent and the input document has no base URI, the results are implementation-dependent.

7.1.16 p:namespace-rename

The p:namespace-rename step renames any namespace declaration or use of a namespace in a document to a new IRI value.

<p:declare-step type="p:namespace-rename">
     <p:input port="source"/>
     <p:output port="result"/>
     <p:option name="from"/>                                       <!-- anyURI -->
     <p:option name="to"/>                                         <!-- anyURI -->
     <p:option name="apply-to" select="'all'"/>                    <!-- "all" | "elements" | "attributes" -->
</p:declare-step>

The value of the from option must be an anyURI. It should be either empty or absolute, but will not be resolved in any case.

The value of the to option must be an anyURI. It should be empty or absolute, but will not be resolved in any case.

The value of the apply-to option must be one of “all”, “elements”, or “attributes”. If the value is “elements”, only elements will be renamed, if the value is “attributes”, only attributes will be renamed, if the value is “all”, both elements and attributes will be renamed.

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

If the value of the from option is the same as the value of the to option, the input is reproduced unchanged on the output. Otherwise, namespace bindings, namespace attributes and element and attribute names are changed as follows:

7.1.17 p:pack

The p:pack step merges two document sequences in a pair-wise fashion.

<p:declare-step type="p:pack">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="alternate" sequence="true"/>
     <p:output port="result" sequence="true"/>
     <p:option name="wrapper" required="true"/>                    <!-- QName -->
</p:declare-step>

The value of the wrapper option must be a QName.

The step takes each pair of documents, in order, one from the source port and one from the alternate port, wraps them with a new element node whose QName is the value specified in the wrapper option, and writes that element to the result port as a document.

If the step reaches the end of one input sequence before the other, then it simply wraps each of the remaining documents in the longer sequence.

7.1.18 p:parameters

The p:parameters step exposes a set of parameters as a c:param-set document.

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

Each parameter passed to the step is converted into a c:param element. The step resolves duplicate parameters in the normal way (see Section 5.1.2, “Parameter Inputs”) so at most one parameter with any given name will appear in the result. The resulting c:param elements are wrapped in a c:param-set and the parameter set document is written to the result port. The order in which c:param elements occur in the c:param-set is implementation-dependent.

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

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

7.1.19 p:rename

The p:rename step renames elements, attributes, or processing-instruction targets in a document.

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

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if the pattern matches anything other than element, attribute or processing instruction nodes.

The value of the new-name option must be a QName.

Each element, attribute, or processing-instruction in the input matched by the match pattern specified in the match option is renamed in the output to the name specified by the new-name option.

If the pattern matches processing instructions, then it is the processing instruction target that is renamed. It is a dynamic error (err:XC0013) if the pattern matches a processing instruction and the new name has a non-null namespace.

7.1.20 p:replace

The p:replace step replaces matching elements in its primary input with the document element of the replacement port's document.

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

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if that pattern matches anything other than element, text, processing-instruction, or comment nodes. Multiple matches are allowed, in which case multiple copies of the replacement document will occur.

Every element in the primary input matching the specified pattern is replaced in the output is replaced by the document element of the replacement document. Only non-nested matches are replaced. That is, once an element is replaced, its descendants cannot be matched.

7.1.21 p:set-attributes

The p:set-attributes step sets attributes on matching elements.

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

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0023) if that pattern matches anything other than element nodes.

Each attribute on the document element of the document that appears on the attributes port is copied to each element that matches the match expression.

If an attribute with the same name as one of the attributes to be copied already exists, the value specified on the attribute port's document is used. The result port of this step produces a copy of the source port's document with the matching elements' attributes modified.

The matching elements are specified by the match pattern in the match option. All matching elements are processed. If no elements match, the step will not change any elements.

This step must not copy namespace declarations. If the attributes copied from the attributes use namespaces, prefixes, or prefixes bound to different namespaces, the document produced on the result output port will require namespace fixup.

7.1.22 p:sink

The p:sink step accepts a sequence of documents and discards them. It has no output.

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

7.1.23 p:split-sequence

The p:split-sequence step accepts a sequence of documents and divides it into two sequences.

<p:declare-step type="p:split-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="matched" sequence="true" primary="true"/>
     <p:output port="not-matched" sequence="true"/>
     <p:option name="initial-only" select="'false'"/>              <!-- boolean -->
     <p:option name="test" required="true"/>                       <!-- XPathExpression -->
</p:declare-step>

The value of the test option must be an XPathExpression.

The XPath expression in the test option is applied to each document in the input sequence. If the effective boolean value of the expression is true, the document is copied to the matched port; otherwise it is copied to the not-matched port.

If the initial-only option is true, then when the first document that does not satisfy the test expression is encountered, it and all the documents that follow it are written to the not-matched port. In other words, it only writes the initial series of matched documents (which may be empty) to the matched port. All other documents are written to the not-matched port, irrespective of whether or not they match.

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

If the implementation supports passing PSVI annotations between steps, the p:split-sequence step must preserve any annotations that appear in the input.

7.1.24 p:store

The p:store step stores a serialized version of its input to a URI. This step outputs a reference to the location of the stored document.

<p:declare-step type="p:store">
     <p:input port="source"/>
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="byte-order-mark"/>                            <!-- boolean -->
     <p:option name="cdata-section-elements" select="''"/>         <!-- ListOfQNames -->
     <p:option name="doctype-public"/>                             <!-- string -->
     <p:option name="doctype-system"/>                             <!-- anyURI -->
     <p:option name="encoding"/>                                   <!-- string -->
     <p:option name="escape-uri-attributes" select="'false'"/>     <!-- boolean -->
     <p:option name="include-content-type" select="'true'"/>       <!-- boolean -->
     <p:option name="indent" select="'false'"/>                    <!-- boolean -->
     <p:option name="media-type"/>                                 <!-- string -->
     <p:option name="method" select="'xml'"/>                      <!-- QName -->
     <p:option name="normalization-form" select="'none'"/>         <!-- NormalizationForm -->
     <p:option name="omit-xml-declaration" select="'true'"/>       <!-- boolean -->
     <p:option name="standalone" select="'omit'"/>                 <!-- "true" | "false" | "omit" -->
     <p:option name="undeclare-prefixes"/>                         <!-- boolean -->
     <p:option name="version" select="'1.0'"/>                     <!-- string -->
</p:declare-step>