XProc 3.1: An XML Pipeline Language

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

Figure 1. A simple, linear XInclude/Validate pipeline

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

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

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

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

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

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

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

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

Figure 2. A validate and transform pipeline

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

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

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

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

There are two kinds of steps: atomic and compound:

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

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

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

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

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

Steps have “ports” into which inputs and outputs are connected. Each step has a number of input ports and a number of output ports; a step can have zero input ports and/or zero output ports. The names of all ports on each step must be unique on that step (you can't have two input ports named “source”, nor can you have an input port named “schema” and an output port named “schema”).

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

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

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

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

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

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

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

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

Several properties are defined by this specification:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Consider the following fragment:

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

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

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

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

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

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

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

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

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

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

XProc processors are expected, and sometimes required, to perform namespace fixup on XML outputs. 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 [Steps 3.0], the extent to which namespace fixup, and other checks for outputs which cannot be serialized, are performed on intermediate outputs is implementation-defined.

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

Several kinds of expressions are evaluated during static analysis:

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

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

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

Consider:

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

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

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

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

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

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

<p:variable name="home" select="'http://example.com/docs'"/> <p:load name="read-from-home"> <p:with-option name="href" select="concat($home,'/document.xml')"/> </p:load> <p:split-sequence name="select-chapters" test="@role='chapter'"> <p:with-input port="source" select="//section"/> </p:split-sequence>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The p:urify function behaves normally during static analysis.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 { "name": "Mary Smith" }

Pipeline authors can create variables to hold computed values.

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

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

Consider this pipeline:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There are three namespaces associated with XProc:

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

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

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

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

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

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

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

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

A document or a sequence of documents can be connected to a port in four ways: by source, by URI, by providing an inline document, or by making it explicitly empty. Each of these mechanisms is allowed where connections may be made, except that p:input may not include a connection by source.

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

Pipeline authors may add documentation to their pipeline documents with the p:documentation element. Except when it appears as a descendant of p:inline, the p:documentation element is completely ignored by pipeline processors, it exists simply for documentation purposes. If a p:documentation is provided as a descendant of p:inline, it has no special semantics, it is treated literally as part of the document to be provided on that port. The p:documentation element has no special semantics when it appears in documents that flow through the pipeline.

Pipeline processors that inspect the contents of p:documentation elements and behave differently on the basis of what they find are not conformant. Processor extensions must be specified with p:pipeinfo.

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

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

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

[Definition: An element from the XProc namespace may have any attribute not from the XProc namespace, provided that the expanded-QName of the attribute has a non-null namespace URI. Such an attribute is called an extension attribute.]

The presence of an extension attribute must not cause the connections between steps to differ from the connections that would arise in the absence of the attribute. They must not cause the processor to fail to signal an error that would be signaled in the absence of the attribute.

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

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

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

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

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

The description of each element in the pipeline namespace is accompanied by a syntactic summary that provides a quick overview of the element’s syntax:

<p:some-element
  reqd-attribute = some-type
  some-attribute? = some-type
  avt-attribute? = { some-type }>
    (some |
     elements |
     allowed)*,
    other-elements?
</p:some-element>

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

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

The types given for attributes should be understood as follows:

A number of errors apply generally:

If an XProc processor can determine statically that a dynamic error will always occur, it may report that error statically provided that the error does not occur among the descendants of a p:try. Dynamic errors inside a p:trymust not be reported statically. They must be raised dynamically so that p:catch processing can be performed on them.

The document element of a pipeline document is p:declare-step which declares a pipeline that can be evaluated by an XProc processor.

It encapsulates the behavior of a subpipeline. Its children declare inputs, outputs, and options that the pipeline exposes and identify the steps in its subpipeline.

Viewed from the outside, a p:declare-step is a black box which performs some calculation on its inputs and produces its outputs. From the pipeline author’s perspective, the computation performed by the pipeline is described in terms of contained steps which read the pipeline’s inputs and produce the pipeline’s outputs.

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

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

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

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

<p:for-each
  name? = NCName>
    ((p:with-input? &
      p:output*),
     subpipeline)
</p:for-each>

When a pipeline needs to process a sequence of documents using a subpipeline that only processes a single document, the p:for-each construct can be used as a wrapper around that subpipeline. The p:for-each will apply that subpipeline to each document in the sequence in turn.

The result of the p:for-each is a sequence of documents produced by processing each individual document in the input sequence. If the p:for-each has one or more output ports, what appears on each of those ports is the sequence of documents that is the concatenation of the sequence produced by each iteration of the loop on the port to which it is connected. If the iteration source for a p:for-each is an empty sequence, then the subpipeline is never run and an empty sequence is produced on all of the outputs.

The p:for-each has a single anonymous input: its connection is provided by the p:with-input. If no iteration sequence is explicitly provided, then the iteration source is read from the default readable port.

The processor provides each document, one at a time, to the subpipeline represented by the children of the p:for-each on a port named current.

For each declared output, the processor collects all the documents that are produced for that output from all the iterations, in order, into a sequence. The result of the p:for-each on that output is that sequence of documents.

The environment inherited by the contained steps of a p:for-each is the inherited environment with these modifications:

If the p:for-each has a primary output port (explicit or supplied by default) and that port has no connection, then it is connected to the primary output port of the last step in the subpipeline. It is a static error (err:XS0006) if the primary output port has no explicit connection and the last step in the subpipeline does not have a primary output port.

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

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

<p:for-each name="chapters"> <p:with-input select="//chapter"/> <p:output port="html-results"> <p:pipe step="make-html" port="result"/> </p:output> <p:output port="fo-results"> <p:pipe step="make-fo" port="result"/> </p:output> <p:xslt name="make-html"> <p:with-input port="stylesheet" href="http://example.com/xsl/html.xsl"/> </p:xslt> <p:xslt name="make-fo"> <p:with-input port="source" pipe="current@chapters"/> <p:with-input port="stylesheet" href="http://example.com/xsl/fo.xsl"/> </p:xslt> </p:for-each>

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

<p:viewport
  name? = NCName
  match = XSLTSelectionPattern>
    ((p:with-input? &
      p:output?),
     subpipeline)
</p:viewport>

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

The p:viewport has a single anonymous input: its connection is provided by the p:with-input. If no document is explicitly provided, then the viewport source is read from the default readable port. If the p:viewport input is a sequence, each document in the sequence is processed in turn producing a sequence on the output. It is a dynamic error (err:XD0072) if a document appearing on the input port of p:viewport is neither an XML document nor an HTML document.

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

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

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

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

What appears on the output from the p:viewport will be a copy of the input document where each matching node is replaced by the result of applying the subpipeline to the subtree rooted at that node. In other words, if the selection pattern matches a particular node then that node is wrapped in a document node and provided on the current port, the subpipeline in the p:viewport is evaluated, and the result that appears on the output port replaces the matched node.

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

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

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

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

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

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

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

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

The list of alternative subpipelines consists of zero or more subpipelines guarded by an XPath expression, followed optionally by a single default subpipeline.

The p:choose considers each subpipeline in turn and selects the first (and only the first) subpipeline for which the guard expression evaluates to true in its context. After a subpipeline is selected, no further guard expressions are evaluated. If there are no subpipelines for which the expression evaluates to true then, if a default subpipeline was specified, it is selected, otherwise, no subpipeline is selected.

After a subpipeline is selected, it is evaluated as if only it had been present.

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

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

As a convenience to authors, it is not an error if some subpipelines declare outputs that can produce sequences and some do not. Each output of the p:choose is declared to produce a sequence. The content types that can appear on the port are the union of the content types that might be produced by any of the p:when or the p:otherwise. If a primary output port is (explicitly or implicitly) defined and p:otherwise is missing, documents with any content type can appear on that port.

The p:choose can specify the context item against which the XPath expressions that occur on each branch are evaluated. The context item is specified as a connection in the p:with-input. If no explicit connection is provided, the default readable port is used. If the context item is connected to p:empty, or is connected to more than one document, or is unconnected and the default readable port is undefined, the context item is undefined. It is a dynamic error (err:XD0001) if an XPath expression makes reference to the context item, size, or position when the context item is undefined.

Each conditional subpipeline is represented by a p:when element. The default branch is represented by a p:otherwise element. These elements are not sibling steps in the usual sense, the names of sibling p:when elements and the p:otherwise element are not in the same scope.

If the following conditions apply:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<p:group> <p:variable name="db-key" select="'some-long-string-of-nearly-random-characters'"/> <p:choose> <p:when test="/config/output = 'fo'"> <p:xslt> <p:with-option name="parameters" select="map {'key': $db-key }"/> <p:with-input port="stylesheet" href="fo.xsl"/> </p:xslt> </p:when> <p:when test="/config/output = 'svg'"> <p:xslt> <p:with-option name="parameters" select="map {'key': $db-key }"/> <p:with-input port="stylesheet" href="svg.xsl"/> </p:xslt> </p:when> <p:otherwise> <p:xslt> <p:with-option name="parameters" select="map {'key': $db-key }"/> <p:with-input port="stylesheet" href="html.xsl"/> </p:xslt> </p:otherwise> </p:choose> </p:group>

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

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

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

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

The p:try step evaluates the initial subpipeline and, if no errors occur, the outputs of that pipeline are the outputs of the p:try step. However, if any errors occur, the p:try abandons the first subpipeline, discarding any output that it might have generated, and considers the recovery subpipelines. If there is no matching recovery subpipeline, the p:try fails.

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

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

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

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

As a convenience to authors, it is not an error if an output port can produce a sequence in the initial subpipeline but not in the recovery subpipeline, or vice versa. Each output of the p:try is declared to produce a sequence. The content types that can appear on the port are the union of the content types that might be produced by the initial subpipeline and any of the recovery subpipelines.

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

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

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

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="/"> <xsl:message terminate="yes"> <xsl:text>This stylesheet is </xsl:text> <emph>pointless</emph> <xsl:text>.</xsl:text> </xsl:message> </xsl:template> </xsl:stylesheet>

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

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

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

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

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

The declaration of an input identifies the name of the port, whether or not the port accepts a sequence, whether or not the port is a primary input port, what content types it accepts, and may provide a connection to default inputs for the port.

An input declaration has the following form:

<p:input
  port = NCName
  sequence? = boolean
  primary? = boolean
  select? = XPathExpression
  content-types? = ContentTypes
  href? = { anyURI }
  exclude-inline-prefixes? = ExcludeInlinePrefixes>
    ((p:empty |
       (p:document |
        p:inline)*) |
     anyElement*)
</p:input>

The attributes that can appear on p:input are the common attributes and:

On p:declare-step, any binding provided in p:input is a default connection for the port, if no other connection is provided, see Section 16.2.1, “Connection precedence”.

The p:pipe element is explicitly excluded from a declaration because it would make the default value of an input dependent on the execution of some part of the pipeline. If a runtime binding is provided for an input port, implementations must not attempt to dereference the default bindings. In the case of p:document connections, the URI is dereferenced only when the default connection is actually used, not during static analysis.

An input connection has the following form:

<p:with-input
  port? = NCName
  select? = XPathExpression
  href? = { anyURI }
  pipe? = string
  exclude-inline-prefixes? = ExcludeInlinePrefixes>
    ((p:empty |
       (p:document |
        p:pipe |
        p:inline)*) |
     anyElement*)
</p:with-input>

The attributes that can appear on p:with-input are the common attributes and:

A p:with-input element with no children (e.g., “<p:with-input/>”) is treated implicitly as if it contained only “<p:pipe/>”, which is in turn equivalent to a binding to the default readable port.

If the p:with-input contains elements not in the XProc namespace, they are implicit inlines.

A p:output identifies an output port.

<p:output
  port? = NCName
  sequence? = boolean
  primary? = boolean
  content-types? = ContentTypes />

The attributes that can appear on p:output are the common attributes and:

On compound steps, the declaration may be accompanied by a connection for the output.

<p:output
  port? = NCName
  sequence? = boolean
  primary? = boolean
  content-types? = ContentTypes
  href? = { anyURI }
  pipe? = string
  exclude-inline-prefixes? = ExcludeInlinePrefixes>
    ((p:empty |
       (p:document |
        p:pipe |
        p:inline)*) |
     anyElement*)
</p:output>

The additional attributes that can appear on an output declaration on a compound step are:

Finally, on a p:declare-step that declares a pipeline, the p:output can specify serialization options.

<p:output
  port? = NCName
  sequence? = boolean
  primary? = boolean
  content-types? = ContentTypes
  href? = { anyURI }
  pipe? = string
  exclude-inline-prefixes? = ExcludeInlinePrefixes
  serialization? = map(xs:QName,item()*)>
    ((p:empty |
       (p:document |
        p:pipe |
        p:inline)*) |
     anyElement*)
</p:output>

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

If a connection is provided for a p:output, documents are read from that connection and those documents form the output that is written to the output port. In other words, placing a p:document inside a p:output causes the processor to read that document and provide it on the output port. It does not cause the processor to write the output to that document.

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

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

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

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

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

A p:declare-step provides the type and signature of a pipeline or an external step. Pipelines contain a subpipeline which defines what the declared step does. [Definition: An external step is one supported by the implementation, but which has no exposed subpipeline.]

The standard XProc atomic steps (p:add-attribute, p:add-xml-base …) are all external steps. Whether or not an implementation allows users to provide their own external steps is implementation-dependent. A p:declare-step must be provided for every pipeline and external step that is used in a pipeline.

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

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

A p:library is a collection of static options, and step declarations.

<p:library
  psvi-required? = boolean
  xpath-version? = decimal
  exclude-inline-prefixes? = ExcludeInlinePrefixes
  version? = 3.0>
    (p:import |
     p:import-functions)*,
    p:option*,
    p:declare-step*
</p:library>

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

The requested xpath-versionmust be used to evaluate XPath expressions subject to the constraints outlined in Section 7.2.2, “XPath in XProc”. If the attribute is not specified, the value “3.1” is assumed. It is a static error (err:XS0110) if the requested XPath version is less than “3.1”.

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

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

Like p:declare-step, within a library, imports must precede the prologue (any static options), which must precede any declared steps.

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

A p:import loads a pipeline or pipeline library, making it available in the pipeline or library which contains the p:import.

<p:import
  href = anyURI />

An import statement loads the specified IRI and makes any public options or pipelines declared within it available to the current pipeline.

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

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

Library imports can nest. An imported pipeline or library may contain additional p:imports which must be processed. Two imported pipelines or libraries are considered the same if the base URI of the resource retrieved is the same. If otherwise identical resources are retrieved with different base URIs (for instance when a web server returns the same document for different request URIs), they must not be considered the same imported library.

When resolving p:imports, a processor may encounter multiple imports of the same pipeline or library. A duplicate import, circular chain of imports (even a library that imports itself), or a re-entrant import is not an error and implementations must take the necessary steps to avoid infinite loops and/or incorrect notification of duplicate step definitions. An example of such steps is listed in Appendix H, Handling Circular and Re-entrant Library Imports (Non-Normative).

In some URI schemes, it is possible for different URIs to identify “the same” resource. Consider, for example, file:/path/file and file:/path/to/../file. To the extent practical, implementations should attempt to resolve these differences before deciding if a particular library URI has already been imported. Note that this is distinct from the case where two genuinely different URIs happen to resolve to the same document. The processor isn’t expected to detect that case and errors are likely.

An p:import-functions element identifies a library of externally defined functions to be imported into the pipeline. After the functions have been imported, they are available in the processor XPath context.An p:import-functions element identifies a library of externally defined functions to be imported into the pipeline. After the functions have been imported, they are available in the processor XPath context.An p:import-functions element identifies a library of externally defined functions to be imported into the pipeline. After the functions have been imported, they are available in the processor XPath contextprocessor XPath context.

<p:import-functions
  href = anyURI
  content-type? = ContentType
  namespace? = string />

Imported functions are loaded during static analysis. In particular, they can be used in [p:]use-when expressions and in expressions that initialize static options.

The ability to import functions is optional. Whether or not a processor can import functions, and if it can, what kinds of function libraries it can import from is implementation-defined. Pipeline authors can use p:function-library-importable to test whether or not a particular kind of library can be loaded.

Importing functions from a library implies loading and processing that library according to its conventions (loading imports, resolving dependencies, etc.). It is a static error (err:XS0104) if the processor cannot load the function library. This may occur because the format is unknown, because it is a version of the library that the processor does not recognize, or if it’s uninterpretable for any other reason. It is a static error (err:XS0106) if the processor detects that a particular library is unloadable. This may occur if the processor is, in principle, able to load libraries of the specified format, but detects that the particuar library requested is somehow ill-formed (syntactically invalid, has unsatisfiable dependencies or circular imports, etc.).

Imported functions must be unique (they must not have the same name, namespace, and arity). It is a static error (err:XS0105) if a function imported from a library has the same name and arity as a function already imported.

A p:pipe connects an input to a port on another step.

<p:pipe
  step? = NCName
  port? = NCName />

The p:pipe element connects to a readable port of another step. It identifies the readable port to which it connects with the name of the step in the step attribute and the name of the port on that step in the port attribute. It is a static error (err:XS0099) if step or port are not valid instances of NCName.

If the step attribute is not specified, it defaults to the step which provides the default readable port. If the port attribute is not specified, it defaults to the primary output port of the step identified (explicitly or implicitly).

It is a static error (err:XS0067) if the step attribute is not specified, and there is no default readable port. It is a static error (err:XS0068) if the port attribute is not specified, and the step identified has no primary output port.

In all cases except when the p:pipe is within an p:output of a compound step, it is a static error (err:XS0022) if the port identified by the p:pipe is not in the readable ports of the step that contains the p:pipe.

A p:pipe that is a connection for an p:output of a compound step may connect to one of the readable ports of the compound step or to an output port on one of the compound step’s contained steps. In other words, the output of a compound step can simply be a copy of one of the available inputs or it can be the output of one of its children.

When the p:pipe is within an p:output of a compound step, it is a static error (err:XS0078) if the port identified by the p:pipe is not in the readable ports of the compound step and is not a readable port of a contained step.

A p:inline provides a document inline.

<p:inline
  exclude-inline-prefixes? = ExcludeInlinePrefixes
  content-type? = string
  document-properties? = map(xs:QName,item()*)
  encoding? = string>
    anyNode*
</p:inline>

The content-type attribute can be used to set the content type of the provided document; the document-properties attribute can be used to set the document properties of the provided document.

The document’s content type is determined statically. If a content-type is specified, that is the content type. Otherwise, the content type is “application/xml”.

It is a dynamic error (err:XD0062) if the document-properties map contains a content-type key and that key has a value that differs from the statically determined content type.

The base URI of the document is the base URI of the p:inline element or of the parent element in the case of an implicit inline. If document-properties provides a value for “base-uri”, this value is the base URI of the document. It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

How the content of a p:inline element is interpreted depends on the document’s content type and the encoding attribute.

It is a dynamic error (err:XD0054) if an encoding is specified and the content type is an XML media type or an HTML media type.

It is a dynamic error (err:XD0055) if the content type value specifies a character set and the encoding attribute is absent.

It is a dynamic error (err:XD0039) if the encoding attribute is present and content type value specifies a character set that is not supported by the implementation.

It is a dynamic error (err:XD0056) if an encoding is specified and the content of the p:inline contains any XML markup. It is a dynamic error (err:XD0063) if the p:inline contains any XML markup and has a content type that is not an XML media type or an HTML media type. In other words, in these cases, the entire content must be a single text node. CDATA sections and character references do not count as markup for this purpose because they will already have been replaced by the XML parser that read the pipeline.

If the encoding attribute is present, the content must be decoded. The encoding value “base64” must be supported and identifies the content as being base64-encoded. An implementation may support encodings other than base64, but these encodings and their names are implementation-defined.It is a static error (err:XS0069) if the encoding specified is not supported by the implementation. It is a dynamic error (err:XD0040) if the body is not correctly encoded per the value of the encoding attribute.

If an encoding attribute is present, value templates are never expanded. The value of [p:]expand-text is irrelevant and always ignored. Otherwise, the text content of p:inline is subject to text value template expansion irrespective of its content type. (Attribute value template expansion only applies to XML and HTML media types.)

The interpretation of the (possibly decoded) content depends on the document’s content type.

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step" version="3.0"> <p:output port="result" serialization="map { 'indent': true() }"/> <p:identity xmlns:a="http://example.com/a" xmlns:b="http://example.com/b" xmlns:c="http://example.com/c"> <p:with-input port="source"> <p:inline exclude-inline-prefixes="a b"> <doc> <b:part/> </doc> </p:inline> </p:with-input> </p:identity> </p:declare-step>

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

<p:identity name="identity" code="my:implicitinline1"> <p:with-input port="source"> <p xmlns="http://example.org/ns">Text</p> <p xmlns="http://example.org/ns">Other text</p> </p:with-input> </p:identity>

<p:identity name="identity" code="my:implicitinline2"> <p:with-input port="source"> <p:inline><p xmlns="http://example.org/ns">Text</p></p:inline> <p:inline><p xmlns="http://example.org/ns">Other text</p></p:inline> </p:with-input> </p:identity>

A p:document reads a document from a URI.

<p:document
  href = { anyURI }
  content-type? = string
  document-properties? = map(xs:QName,item()*)
  parameters? = map(xs:QName,item()*) />

The value of the href attribute, after expanding any attribute value templates, is a URI. The URI is interpreted as an IRI reference. If it is relative, it is made absolute against the base URI of the p:document element. It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

The semantics of p:document are the same as the semantics of p:load where the href option is the URI, the content-type option comes from content-type attribute, the document-properties option comes from the document-properties attribute, and the parameters option comes from the parameters attribute.

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

<p:empty />

If an empty binding is used, it must be the only binding for the port. It is a static error (err:XS0089) if the p:empty binding appears as a sibling of any other binding, including itself.

A p:documentation contains human-readable documentation.

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

There are no constraints on the content of the p:documentation element. Documentation is ignored by pipeline processors. See Section 14.6, “Documentation”.

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

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

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

[Definition: A static error is one which can be detected before pipeline evaluation is even attempted.] Examples of static errors include cycles in the pipeline graph and incorrect specification of inputs and outputs.

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

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

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated (and cannot be detected before evaluation begins).] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space).

Implementations are required to evaluate the pipeline graph according to the rules of this specification, but they may choose to optimize pipeline execution in different ways. This may cause steps to be evaluated in different orders which consequently has an impact on error detection. The detection of dynamic errors is somewhat implementation-dependent because the order of step execution may vary. In cases where an implementation is able to run a pipeline without evaluating a particular expression, or running a particular step, the implementation is never required evaluate the expression or run the step solely in order to determine whether doing so causes a dynamic error. For example, if a variable is declared but never referenced, an implementation may choose whether or not to evaluate the expression which initializes the variable, which means that if evaluating the variable’s initializer causes a dynamic error, some implementations will signal this error and others will not.

There are some cases where this specification requires that steps must not be executed: for example, the content of a p:whenmust not be executed if the test condition is false. This means that an implementation must not signal any dynamic errors that would arise if the contents of the p:when were executed.

An implementation may signal a dynamic error before any source document is available, but only if it can determine that the error would be signaled for every possible source document and every possible set of parameter values.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

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

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

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