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.6.1 Namespace Fixup on Outputs

What flows between steps are exclusively XML documents. The inputs and outputs can be implemented as sequences of characters, sequences of events, object models, or any other representation that the implementation chooses.

Most steps in this specification manipulate XML documents, or portions of XML documents. In these cases, we speak of changing elements, attributes, or nodes without prejudice to the actual representation used by an implementation. 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.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/ns/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/ns/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

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

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/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: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/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: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/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: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 XSLTMatchPattern. It is a dynamic error (err:XC0013) 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.

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 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" 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.4 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.5 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 XSLTMatchPattern. 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.6 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. It is interpreted as an IRI reference. 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 by p:directory-list, 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.

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

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

7.1.9 HTTP Request

The p:http-request step provides for interaction with resources identified by IRIs over HTTP or HTTPS. The input document provided on the source port specifies a 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.

<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 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 are as specified in Section 7.3, “Serialization Options”. See Section 7.1.9.2, “Request Entity body conversion” for a discussion of when serialization occurs in constructing a request.

<c:http-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:http-request>

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


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

7.1.11 Insert

The p:insert step inserts the insertion port's document as a child of matching elements in the source port's document.

<p:declare-step type="p:insert">
     <p:input port="source" primary="true"/>
     <p:input port="insertion"/>
     <p:output port="result"/>
     <p:option name="match" value="/*"/>
     <p:option name="position" required="true"/>
</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. Multiple matches are allowed, in which case multiple copies of the insertion document will occur.

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 the document element and the value of the position option is ”before” or ”after”.

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 p:label-elements step generates a label for each selected 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" value="xml:id"/>
     <p:option name="prefix" value="_"/>
     <p:option name="suffix" value=""/>
     <p:option name="select" value="*"/>
     <p:option name="scheme" value="count-elements"/>
</p:declare-step>

The value of the attribute option must be a QName.

The value of the select option must be an XPathExpression. It is a dynamic error (err:XC0024) if that expression selects anything other than element nodes.

The value of the scheme option must be a QName. If it does not have a prefix, it must have the value count-elements.

This step operates by generating labels for each element selected. The algorithm by which label values are generated depends on the scheme value specified. If a selected element already has an attribute whose name is the value of the attribute option, that attribute is not changed, otherwise an attribute with that name is added, with a value consisting of the concatenation of the value of the prefix option, the computed label, and the value of the suffix option.

If the value of the scheme option is count-elements, then the label for each selected element is its position in the sequence of selected elements. In other words, the first element (in document order) selected gets the label “1”, the second gets the label “2”, the third, “3”, etc. The labeling process counts every element, even those which already have an attribute whose name is the value of the attribute option.

All implementations must support the scheme value count-elements. Support for scheme values other than count-elements on the p:label-elements step is implementation-defined.

The p:label-elements step must not generate two labels with the same value in the course of processing any single document. However, no attempt must be made to assure that the generated attribute values are unique with respect to attribute values already present in the document.

It is a dynamic error (err:XC0032) if the value specified for the scheme option is not one of the values supported by the implementation.

7.1.13 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"/>
     <p:option name="validate"/>
</p:declare-step>

The value of the href option must be an anyURI. It is interpreted as an IRI reference.

The value of the 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 its p:option element. 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 validate option is “true”, namespace-aware 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.

Implementations must support the file and http URI schemes on p:load. It is implementation-defined what other URI schemes are supported. It is a dynamic error (err:XC0007) if the scheme of the IRI reference is not supported.

7.1.14 Make Absolute IRIs

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"/>
     <p:option name="base-uri"/>
</p:declare-step>

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0008) 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.

For every element or attribute in the input document which matches the specified pattern, its string-value (as defined in [XPath 1.0]) 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 specifed 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.15 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"/>
     <p:option name="to"/>
     <p:option name="elements-only"/>
</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.

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.16 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"/>
</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.17 Parameters

The p: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 (see Section 5.1.2, “Parameter Inputs”). The order in which parameters are written to the parameter port of p:parameters 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 must be an NCName.

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

7.1.18 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"/>
     <p:option name="new-name" required="true"/>
</p:declare-step>

The value of the match option must be an XSLTMatchPattern. It is a dynamic error (err:XC0031) 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.

7.1.19 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"/>
</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. 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.20 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"/>
</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.

7.1.21 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.22 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="test" required="true"/>
</p:declare-step>

The value of the test option must be an XPathExpression.

The [XPath 1.0] 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.

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.23 String Replace

The p:string-replace step matches nodes in the document provided on the source port and replaces them with the string result of evaluating an XPath expression.

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

The value of the match option must be an XSLTMatchPattern.

The value of the replace option must be an XPathExpression.

The matched nodes are specified with the match pattern in the match option. For each matching node, the XPath expression provided by the replace option is evaluated and the string value of the result is used in the output. Nodes that do not match are copied without change.

If the expression given in the match option matches an attribute, the string value of the expression is used as the new value of the attribute in the output.

If the expression matches any other kind of node, the entire node (and not just its contents) is replaced by the string value.

7.1.24 Store

The p: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. It is a dynamic error (err:XC0050) if the URI scheme is not supported or the step cannot store to the specified location.

The output of this step is a document containing a single c:result element whose content is the absolute URI of the document stored by the step.

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.25 Unescape Markup

The p:unescape-markup step takes the string value of the document element and parses the content as if it was a Unicode character stream containing serialized XML. The output consists of the same document element with children that result from the parse. This is the reverse of the p:escape-markup step.

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

The value of the namespace option must be an anyURI. It should be absolute, but will not be resolved.

When the string value is parsed, the original document element is preserved so that the result will be well-formed XML even if the content consists of multiple, sibling elements.

The namespace option specifies the default namespace. If it is provided, it will be declared as the default namespace on the document element.

The content-type option may be used to specify an alternate content type for the string value. An implementation may use a different parser to produce XML content depending on the specified content-type. For example, an implementation might provide an HTML to XHTML parser (e.g. [HTML Tidy] or [TagSoup]) for the content type 'text/html'.

Behavior of p:unescape-markup for content-types other than application/xml is implementation-defined.

All implementations must support the content type application/xml, and must use a standard XML parser for it. It is a dynamic error (err:XC0051) if the content-type specified is not supported by the implementation.

The encoding option specifies how the data is encoded. All implementations must support the base64 encoding (and the absence of an encoding option, which implies that the content is plain Unicode text). It is a dynamic error (err:XC0052) if the encoding specified is not supported by the implementation.

If an encoding is specified, a charset may also be specified. The octet-stream that results from decoding the text must be interpreted using the specified encoding to produce a sequence of Unicode characters to parse. If the option is not specified, the value “UTF-8” must be used.

It is a dynamic error (err:XC0010) if the charset specified is not supported by the implementation or if charset is specified when encoding is not.

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 xmlns="http://www.w3.org/1999/xhtml">
<p>This is a chunk.</p>
<p>This is a another chunk.</p>
</description>

7.1.26 Unwrap

The p:unwrap step replaces matched elements with their children.

<p:declare-step type="p:unwrap">
     <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 XSLTMatchPattern. It is a dynamic error (err:XC0023) if that pattern matches anything other than element nodes.

Every element in the source document that matches the specified match pattern is replaced by its children, effectively “unwrapping” the children from their parent. Non-element nodes and unmatched elements are passed through unchanged.

This step produces a single document; if the document element is unwrapped, the result may not be well-formed XML.

7.1.27 Wrap

The p:wrap step wraps matching nodes in the source document with a new parent element.

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

The value of the wrapper option must be a QName.

The value of the match option must be an XSLTMatchPattern.

The value of the group-adjacent option must be an XPathExpression.

Every node that matches the specified match pattern is replaced with a new element node whose QName is the value specified in the wrapper option. The content of that new element is a copy of the original, matching node.

The group-adjacent option can be used to group adjacent matching nodes in a single wrapper element. The specified XPath expression is evaluated for each matching node with that node as the XPath context node. Whenever two or more adjacent matching nodes have the same “group adjacent” value, they are wrapped together in a single wrapper element.

Two matching nodes are considered adjacent if and only if they are siblings and either there are no nodes between them or all intervening nodes are whitespace text, comment, or processing instruction nodes.

7.1.28 Wrap Sequence

The p:wrap-sequence step accepts a sequence of documents and produces either a single document or a new sequence of documents.

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

The value of the wrapper option must be a QName.

The value of the group-adjacent option must be an XPathExpression.

In its simplest form, p:wrap-sequence takes a sequence of documents and produces a single, new document by placing each document in the source sequence inside a new document element as sequential siblings. The name of the document element is the value specified in the wrapper option.

The group-adjacent option can be used to group adjacent documents. The specified XPath expression is evaluated for each document with that document as the XPath context node. Whenever two or more sequentially adjacent documents have the same “group adjacent” value, they are wrapped together in a single wrapper element.

7.1.29 XInclude

The p:xinclude step applies [XInclude] processing to the source document.

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

The included documents are located with the base URI of the input document and are not provided as input to the step.

It is a dynamic error (err:XC0029) if an XInclude error occurs during processing.

7.1.30 XSLT

The p:xslt step applies an [XSLT 1.0] stylesheet to a document.

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

The XSLT stylesheet provided on the stylesheet port is applied to the document on the source port. The result of the transformation appears on the result port. All of the specified parameters are made available (as XSLT parameters) to the XSLT processor.

A dynamic error occurs if the XSLT processor signals a fatal error. This includes the case where the transformation terminates due to a xsl:message instruction with a terminate attribute value of “yes”. How XSLT message termination errors are reported to the XProc processor is implementation-dependent.

This step does not serialize the result document. Any serialization parameters specified on a xsl:output element inside the stylesheet are ignored. Further, the output on the result port must be a well-formed XML document; transformations that use non-XML output methods (e.g. the 'text' method) may cause 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 p:validate-relax-ng step applies [RELAX NG] validation to the source document.

<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:option name="assert-valid" value="true"/>
</p:declare-step>

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

The value of the assert-valid option must be a boolean.

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

It is a dynamic error (err:XC0053) if the assert-valid option is true and the input document is not valid.

The output from this step is a copy of the input, possibly augmented by application of the [RELAX NG DTD Compatibility].

7.2.2 Schematron Validate

The p:validate-schematron step applies [Schematron] processing to the source document.

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

It is a dynamic error (err:XC0054) if any Schematron assertions fail.

The output from this step is a copy of the input.

7.2.3 XML Schema Validate

The p:validate-xml-schema step applies [W3C XML Schema: Part 1] validity assessment to the source input.

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

The value of the assert-valid option must be a boolean.

The value of the mode option must be an NMTOKEN whose vlaue is either “strict” or “lax”.

Validation is performed against the set of schemas represented by the documents on the schema port.

It is a dynamic error (err:XC0053) if the assert-valid option is true and the input document is not valid.

When XML Schema validation assessment is performed, the processor is invoked in the mode specified by the mode option. It is a dynamic error (err:XC0055) if the implementation does not support the specified mode.

The result of the assessment is a document with the Post-Schema-Validation-Infoset (PSVI) ([W3C XML Schema: Part 1]) annotations, if the pipeline implementation supports such annotations. If not, 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 XQuery 1.0

The p:xquery step applies an [XQuery 1.0] query to the sequence of documents provided on the source port.

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