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 “!n” where “n” is the ordinal number of the step, considering all steps in document order. For example, consider the pipeline in Example 3, “A validate and transform pipeline”. The p:pipeline step has no name, so it gets the default name “!1”; the p:choose gets the name “!2”; the first p:when gets the name “!3”, etc. If the p:choose had had a name, it would not have received a default name, but it would still have been counted and its first p:when would still have been “!3”.

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

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 or not (and when and how) the intermediate results that pass between steps are ever written to a filesystem is implementation dependent.

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

2.8.1 Processor XPath Context

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

2.8.2 Step XPath Context

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

2.8.3 XProc Extension Functions

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

4.1.1 Example

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

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

<p:xinclude/>

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

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

</p:pipeline>

4.2.1 XPath Context

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

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

4.2.2 Example

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

<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 size; the ordinal value of the current document (the document appearing on the current port) is the position.

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

4.3.2 Example

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

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

</p:pipeline>

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

4.4.1 p:xpath-context

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

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

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

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

4.4.2 p:when

A when specifies one subpipeline guarded by a test expression.

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

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

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

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

4.4.3 p:otherwise

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

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

4.4.4 Example

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

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

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

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

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

4.5.1 Example

<p:group>
  <p:option name="db-key" value="some-long-string-of-nearly-random-characters"/>

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

4.6.1 The Error Vocabulary

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

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

<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/2007/03/xproc-step">
  <c:error name="xform" type="p:xslt"
             href="style.xsl" line="6">This stylesheet is <emph>pointless</emph>.</c:error>
</c:errors>

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

4.7.1 Syntactic Shortcut for Option Values

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

The first step uses the standard p:option syntax:

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

The second step uses the syntactic shortcut:

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

Note that there are significant limitations to this shortcut syntax:

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

5.1.1 Document Inputs

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

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

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

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

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

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

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

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

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

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

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

provides a single document, but

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

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

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

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

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

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

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

5.1.2 Parameter Inputs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</p:pipeline>

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

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

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

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

5.7.1 p:option Element

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

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

5.7.2 p:parameter Element

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

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

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

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

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

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

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

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

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

5.7.3 Option and Parameter Namespaces

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

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

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

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

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

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

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

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

</p:pipeline>

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

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

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

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

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

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

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

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

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

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

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

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

</p:pipeline>

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

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

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

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

</p:pipeline>

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

7.1.1 Add Attribute

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

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

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

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

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

7.1.2 Add xml:base

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

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

The value of the all option must be a boolean.

The value of the relative option must be a boolean.

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

7.1.3 Count

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

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

7.1.4 Delete

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

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

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

7.1.5 Directory List

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

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

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

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

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

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

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

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

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

7.1.6 Equal

The p:equal step compares two documents for equality.

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

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

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

7.1.7 Error

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

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

The value of the code option must be a QName

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

For example, given the following invocation:

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

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

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

7.1.8 Escape Markup

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

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

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

For example, the input:

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

produces:

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

7.1.9 HTTP Request

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

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

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

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

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

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

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

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

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

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

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

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

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

7.1.10 Identity

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

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

7.1.11 Insert

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

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

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

The position option takes one of the following values:

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

7.1.12 Label Elements

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

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

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

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

7.1.13 Load

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

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

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

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

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

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

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

7.1.14 Make Absolute URIs

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

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

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

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

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

7.1.15 Namespace Rename

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

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

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

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

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

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

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

7.1.16 Parameters

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

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

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

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

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

7.1.17 Rename

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

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

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

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

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

7.1.18 Replace

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

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

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

7.1.19 Set Attributes

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

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

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

7.1.20 Sink

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

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

7.1.21 Split Sequence

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

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

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

7.1.22 String Replace

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

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

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

7.1.23 Store

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

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

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

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

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

7.1.24 Unescape Markup

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

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

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

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

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

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

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

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

would produce:

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

7.1.25 Unwrap

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

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

7.1.26 Wrap

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

If the group-adjacent is specified, adjacent matches are grouped by evaluating the XPath specified by this option with the content node set to the matched node. If the XPath evaluates to the same string value, the matches are grouped into the same wrapper element. While processing the document for grouping, two matches are considered adjacent if they are either siblings or all intervening siblings are whitespace text, comments, or processing instruction nodes.

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

7.1.27 Wrap Sequence

The Wrap Sequence step converts the sequence of documents on the source port into a single document on the result port. The document produced has a document element whose name is specified via the wrapper option and whose children are the contents of the documents received on source port, in the order they were received. All of the top-level nodes (white space, comments, processing-instructions, and one element node) of each document are added to the children of the new wrapper document. The wrapper option takes a QName value whose prefixes are resolved as specified in Section 5.7.3, “Option and Parameter Namespaces”

If the group-adjacent is specified, adjacent documents in the sequence are grouped by evaluating the XPath specified by this option with the context node set to the document node. If the XPath evaluates to the same string value, the documents are grouped into the same wrapper element.

<p:declare-step type="p:wrap-sequence">
     <p:input port="source" sequence="true"/>
     <p:output port="result" sequence="true"/>
     <p:option name="wrapper" required="true"/>
     <p:option name="group-adjacent"/>
</p:declare-step>

7.1.28 XInclude

The XInclude step applies xinclude processing semantics to the document. The referenced documents are calculated against the base URI and are not provided as input to the step.

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

It is a dynamic error (err:XC0011) if an XInclude error occurs during processing and the step fails.

7.1.29 XSLT

The xslt step applies an XSLT 1.0 transformation to a document. The transformation is supplied by a single document on the input port named stylesheet. That transformation is applied to the primary source document supplied on the input port named source. The result of the transformation is a sequence of documents on its result port.

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

All of the specified parameters are made available to the XSLT processor. If the XSLT processor signals a fatal error, the step fails. Otherwise, the result of the transformation is produced on the “result” port.

Since this step does not serialize the result document, all serialization parameters specified on the xsl:output element inside the transformation are ignored. Further, the output on the result port must be a well-formed XML document. As such, certain transformations that use non-XML output (e.g. 'text' method) may cause a dynamic error during execution of the transformation.

If the transformation terminates due to a xsl:message instruction with a terminate attribute value of “yes”, this step throws a dynamic error.

The base URI of the output document is the URI of the document on the source port.

7.2.1 Relax NG Validate

The Relax NG Validate step applies RELAX NG validation to an XML document input.

<p:declare-step type="p:validate-relax-ng">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
     <p:option name="dtd-compatibility" value="false"/>
</p:declare-step>

If the dtd-compatibility option is “true”, then the conventions of [RELAX NG DTD Compatibility] are also applied.

7.2.2 Schematron Validate

The Schematron Validate step applies Schematron validation to an XML document input.

<p:declare-step type="p:validate-schematron">
     <p:input port="source" primary="true"/>
     <p:input port="schema"/>
     <p:output port="result"/>
</p:declare-step>

7.2.3 XML Schema Validate

The XML Schema Validate step applies XML Schema's validity assessment to an XML document input. The set of known available schemata are specified via a sequence of documents provided on the schema input port.

<p:declare-step type="p:validate-xml-schema">
     <p:input port="source" primary="true"/>
     <p:input port="schema" sequence="true"/>
     <p:output port="result"/>
     <p:option name="assert-valid" value="true"/>
     <p:option name="mode" value="strict"/>
</p:declare-step>

If assert-valid option has a value of “true”, the step will fail if the XML Schema validation assessment reports any errors. When XML Schema validation assessment is performed, the processor is invoked in the mode specified by the mode option. The result of the assessment produces an infoset with the Post-Schema-Validation-Infoset (PSVI) ([W3C XML Schema: Part 1]) annotations if the pipeline implementation supports such annotations. Otherwise, the input document is reproduced with any defaulting of attributes and elements performed as specified by the XML Schema recommendation.

Whether or not the pipeline processor supports passing PSVI annotations between steps is implementation-defined.

7.2.4 XSLT 2.0

The XSLT 2.0 step applies an XSLT 2.0 transformation to a document. The transformation is supplied on the port named stylesheet and the primary input document is supplied on the port named source. The application of the transformation produces the primary result document on the port named result.

<p:declare-step type="p:xslt2">
     <p:input port="source" sequence="true" primary="true"/>
     <p:input port="stylesheet"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="true"/>
     <p:output port="secondary" sequence="true"/>
     <p:option name="initial-mode"/>
     <p:option name="template-name"/>
     <p:option name="allow-version-mismatch" value="true"/>
     <p:option name="output-base-uri"/>
     <p:option name="allow-collections" value="true"/>
</p:declare-step>

If a sequence of documents is provided on the input port named source, the first document is assumed to be the primary input document. By default, this sequence is also the default collection unless the allow-collections option is set to “false”.

All of the specified parameters are made available to the XSLT processor. If the XSLT processor signals a fatal error, the step fails. Otherwise, the result of the transformation is produced on the “result” port.

The invocation of the transformation is controlled by the initial-mode and template-name options that set the initial mode and/or named template in the XSLT transformation that should initiate processing. If these values do not match the transformation specified, a dynamic error must be thrown.

The allow-version-mismatch option indicates whether an XSLT 1.0 transformation should be allowed to be run through the XSLT 2.0 processor. A value of “true” means that it should be allow.

The output-base-uri option sets the context's output base URI per the XSLT 2.0 specification.

If more than one document is produced, the secondary result documents are produced on the output port named secondary. Otherwise, the secondary port produces an empty sequence.

If the transformation terminates due to a xsl:message instruction with a terminate attribute value of “yes”, this step throws a dynamic error.

The base URI of the output document is the base URI of the first document in the source port's sequence.

7.2.5 XSL Formatter

The XSL Formatter step receives an [XSL 1.1] document and renders the content. The result of rendering is stored to the URI provided via the 'uri' option. A reference to that result is produced on the output port.

The output content type is controlled by the 'output' option which contains a media type as specified by [IANA Media Types]. In addition, any media type parameters may be specified in this option (e.g. "text/html; charset=UTF-8" but their use are implementation defined.

If no output value is specified and the implementation supports PDF output, PDF output is assumed.

A formatter may take any number of optional rendering parameters via the step's parameters. Such parameters are defined by the XSL implementation used and are implementation defined.

<p:declare-step type="p:xsl-formatter">
     <p:input port="source"/>
     <p:input port="parameters" kind="parameter" sequence="true"/>
     <p:output port="result" primary="false"/>
     <p:option name="uri" required="true"/>
     <p:option name="output"/>
</p:declare-step>

The output of this step is a document containing a single c:result whose contents contains a URI that points to the output of the XSL formatter.

7.2.6 XQuery 1.0

The XQuery 1.0 step applies an XQuery to a sequence of documents treated as the default collection. The source input port allows a sequence of documents and specifies each document that should be in the default collection. The result of the xquery is a sequence of documents constructed from a XPath 2.0 sequence of elements. Each element in the sequence is assumed to be the document element of a separate document. It is an error if the sequence contains items other than elements.

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

The query port must receive a single document whose element is c:query. As XQuery is not necessarily well-formed XML, the text descendants of this element are considered the query.

Each base URI of the output documents is the base URI of the first document in the source port's sequence.

<c:query>
    string
</c:query>

For example:

<c:query>
declare namespace atom="http://www.w3.org/2005/Atom";
/atom:feed/atom:entry
</c:query>