XProc 3.1: Standard Step Library

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 selection 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 matched elements is copied to the output with the addition of the specified attribute with the specified value.

The value of the match option must be an XSLTSelectionPattern. It is a dynamic error (err:XC0023) if the selection pattern matches a node which is not an element.

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

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

This step cannot be used to add namespace declarations. It is a dynamic error (err:XC0059) if the QName value in the attribute-name option is “xmlns” or uses the prefix “xmlns” or any other prefix that resolves to the namespace name http://www.w3.org/2000/xmlns/. Note, however, that while namespace declarations cannot be added explicitly by this step, adding an attribute whose name is in a namespace for which there is no namespace declaration in scope on the matched element may result in a namespace binding being added by namespace fixup.

If an attribute named xml:base is added or changed, the base URI of the element must also be amended accordingly.

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

The value of the all option must be a boolean.

The value of the relative option must be a boolean.

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

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

The p:archive step outputs on its result port an archive (usually binary) document, for instance a ZIP file. A specification of the contents of the archive may be specified in a manifest XML document on the manifest port. The step produces a report on the report port, which contains the manifest, amended with additional information about the archiving.

The p:archive step can perform several different operations on archives. The most common one will likely be creating an archive, but it could also, depending on the archive format, provide services like update, freshen or even merge. The only format implementations must support is [ZIP]. The list of formats supported by the p:archive step is implementation-defined.

The p:archive step has the following input ports:

The p:archive step has the following output ports:

The p:archive step has the following options:

The format of the archive is determined as follows:

It is a dynamic error (err:XC0085) if the format of the archive cannot be understood, determined and/or processed.

The p:archive-manifest creates an XML manifest file describing the contents of the archive appearing on its source port.

The p:archive-manifest step inspects the archive appearing on its source port and outputs a manifest describing the contents of the archive on its result port.

The format of the archive is determined as follows:

It is a dynamic error (err:XC0085) if the format of the archive cannot be understood, determined and/or processed.

The parameters option can be used to supply parameters to control the archive manifest generation. The semantics of the keys and the allowed values for these keys are implementation-defined. It is a dynamic error (err:XC0079) if the map parameters contains an entry whose key is defined by the implementation and whose value is not valid for that key.

The relative-to option, when present, is used in creating the value of the manifest's c:entry/@href attribute. If the option is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or the step in case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

The generated manifest has the format as described in Section 2.3.1, “The archive manifest”. Implementations must supply an c:entry element and its name and content-type attributes for every entry in the archive. The value of the generated manifest's c:entry/@href attribute will be determined in the same way as a base URI of an unarchived document by Section 2.39, “p:unarchive”. It is a dynamic error (err:XC0120) if the relative-to option is not present and the document on the source port does not have a base URI. Additional information provided for entries in p:archive-manifest is implementation-defined.

The p:cast-content-type step creates a new document by changing the media type of its input. If the value of the content-type option and the current media type of the document on source port are the same, this document will appear unchanged on result port.

The input document is transformed from one media type to another. 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 a dynamic error (err:XC0071) if the p:cast-content-type step cannot perform the requested cast.

The parameters can be used to supply parameters to control casting. The semantics of the keys and the allowed values for these keys are implementation-defined. It is a dynamic error (err:XC0079) if the map parameters contains an entry whose key is defined by the implementation and whose value is not valid for that key.

The p:compare step compares two documents for equality.

This step takes single documents on each of two ports and compares them. If method is not specified, or if deep-equal is specified, the comparison uses fn:deep-equal (as defined in [XPath and XQuery Functions and Operators 3.1]). Implementations of p:compare must support the deep-equal method; other supported methods are implementation-defined. It is a dynamic error (err:XC0076) if the comparison method specified in p:compare is not supported by the implementation. It is a dynamic error (err:XC0077) if the media types of the documents supplied are incompatible with the comparison method.

It is a dynamic error (err:XC0019) if the documents are not equal according to the specified comparison method, 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.

If fail-if-not-equal is false, and the documents differ, an implementation-defined summary of the differences between the two documents may appear on the differences port.

The p:compress step serializes the document appearing on its source port and outputs a compressed version of this on its result port.

The p:compress step first serializes the document appearing on its source. It then compresses the outcome of this serialization and outputs the result on its result port.

The p:compress step has the following options:

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.

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

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

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

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

It is a dynamic error (err:XC0023) if the match option matches the document node.

This step cannot be used to remove namespaces. It is a dynamic error (err:XC0062) if the match option matches a namespace node. Also, note that deleting an attribute named xml:base does not change the base URI of the element on which it occurred.

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

The p:error step always fails. It generates a single error with the error code specified in the code option. It also produces a c:errors document that will be visible on the error port inside a p:catch. (The error vocabulary is described in [XProc 3.1].)

This step should include the content of the document that appears on the source port in the error. If more than one document appears on the source port of the p:error step, all of the documents must be added to a single c:error element.

For authoring convenience, the p:error step is declared with a single, primary output port. With respect to connections, this port behaves like any other output port even though nothing can ever appear on it since the step always fails.

For example, given the following invocation:

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

The errors document generated on the error output port might be:

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

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

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

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

The p:hash step generates a hash, or digital “fingerprint”, for some value and injects it into the source document.

The value of the algorithm option must be a QName. If it does not have a prefix, then it must be one of the following values: “crc”, “md”, or “sha”.

If a version is not specified, the default version is algorithm-defined. For “crc” it is 32, for “md” it is 5, for “sha” it is 1.

A hash is constructed from the string specified in the value option using the specified algorithm and version. Implementations must support [CRC32], [RFC 1321], and [SHA1] hashes. It is implementation-defined what other algorithms are supported. The resulting hash should be returned as a string of hexadecimal characters.

The value of the match option must be an XSLTSelectionPattern.

The hash of the specified value is computed using the algorithm and parameters specified. It is a dynamic error (err:XC0036) if the requested hash algorithm is not one that the processor understands or if the value or parameters are not appropriate for that algorithm.

The matched nodes are specified with the selection pattern in the match option. For each matching node, the string value of the computed hash is used in the output (if more than one node matches, the same hash value is used in each match). Nodes that do not match are copied without change.

If the expression given in the match option matches an attribute, the hash is used as the new value of the attribute in the output. If the attribute is named “xml:base”, the base URI of the element must also be amended accordingly.

If the document node is matched, the result is a text document.

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

The p:http-request step allows authors to interact with resources over HTTP or related protocols. Implementations must support the http and https protocols.

The p:http-request step performs the HTTP request specified by the method option against the URI specified in the href option. In simple cases, for example, a GET request on an unauthenticated URI, nothing else is necessary to form a complete request. (Implementors are encouraged to support as many protocols as practical. In particular, pipeline authors may attempt to use p:http-request to load documents with computed URIs using the file: scheme.)

If the method, for example, POST, supports a body, the request body is constructed using the document(s) appearing on the source port. For the convenience of pipeline authors, documents may appear on the source port even when the request method (such as GET or HEAD) does not define the semantics of a payload. If the semantics are undefined, the documents are ignored when constructing the request unless the parameters option specifies “send-body-anyway” as true().

The headers for the request come from the headers option (see below). If exactly one document appears on the source port, its document properties also contribute to the overall request headers.

The response from the HTTP request appears on the result and report ports. Any documents contained in the response body will appear on the result port. Each document in the response will be parsed according to its content-type (but see “override-content-type” in the parameters option). Details about the outcome of the request will appear as a map on the report port. The map will always contain:

The p:http-request step has the following options:

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

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

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

The value of the match option must be an XSLTSelectionPattern. It is a dynamic error (err:XC0023) if that pattern matches an attribute or a namespace node. Multiple matches are allowed, in which case multiple copies of the insertion documents will occur. If no elements match, then the document is unchanged.

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

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

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

The p:json-join step joins the sequence of documents on port source into a single JSON document (an array) appearing on port result. If the sequence on port source is empty, the empty sequence is returned on port result.

The step inspects the documents on port source in turn to create the resulting array:

The option flatten-to-depth controls whether and to which depth members of an array appearing on port source are flattened. It is a dynamic error (err:XC0119) if flatten is neither “unbounded”, nor a string that may be cast to a non-negative integer. An integer value of 0, which is the default, means that no flattening takes place, so the array appearing on port source will be contained as an array in the resulting array. An integer value of 1 means that an array on port source is flattened, i.e. the members of that array will appear as individual members in the resulting array. Any value greater than 1 means that the flattening is applied recursively to arrays in arrays up to the given depth. A value of “unbounded” means that all arrays in arrays will be flattened. As a consequence, the resulting array appearing on port result will not have any arrays as members.

The p:json-merge step merges the sequence of appearing on port source into a single JSON object appearing on port result. If the sequence on port source is empty, the empty sequence is returned on port result.

The step inspects the documents on port source in turn to create the resulting map:

An implementation must bind the variable “p:index” in the static context of each evaluation of the XPath expression to the position of the document in the sequence of documents on port source, starting with “1”.

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

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

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

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

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

If this step is used to add or change the value of an attribute named “xml:base”, the base URI of the element must also be amended accordingly.

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

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

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

If the href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:load in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

The document identified by the href URI is loaded and returned. If the URI protocol supports redirection, then redirects must be followed.

It is a dynamic error (err:XD0011) if the resource referenced by a p:load element does not exist or cannot be accessed.

The behavior of this step depends on the content type of the document loaded. The content type of a document is determined as follows:

The parameters map contains additional, optional parameters that may influence the way that content is loaded. The interpretation of this map varies according to the content type. Parameter names that are in no namespace are treated as strings using only the local-name where appropriate.

Broadly speaking, there are five categories of data that might be loaded: XML, text, JSON, HTML, and “other” binary data.

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.

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

The value of the base-uri option must be an anyURI. It is interpreted as an IRI reference. If it is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:make-absolute-uris in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

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

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

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

The p:namespace-delete step deletes all of the namespaces identified by the specified prefixes from the document appearing on port source.

The value of option prefixes is taken as a space separated list of prefixes. It is a dynamic error (err:XC0108) if any prefix is not in-scope at the point where the p:namespace-delete occurs.

For any prefix the associated namespace is removed from the elements and attributes in the document appearing on port source. The respective elements or attributes in the document appearing on port result will be in no namespace.

It is a dynamic error (err:XC0109) if a namespace is to be removed from an attribute and the element already has an attribute with the resulting name.

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

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

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

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

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

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

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

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.

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

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

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

If the match option matches an attribute and if the element on which it occurs already has an attribute whose expanded name is the same as the expanded name of the specified new-name, then the results is as if the current attribute named “new-name” was deleted before renaming the matched attribute.

With respect to attributes named “xml:base”, the following semantics apply: renaming an from “xml:base” to something else has no effect on the underlying base URI of the element; however, if an attribute is renamed from something else to “xml:base”, the base URI of the element must also be amended accordingly.

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

The p:replace step replaces matching nodes in its primary input with the content of the document that appears on the replacement port.

The value of the match option must be an XSLTSelectionPattern. It is a dynamic error (err:XC0023) if that pattern matches an attribute or a namespace nodes. Multiple matches are allowed, in which case multiple copies of the replacement document will occur.

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

If the document node is matched, and the replacement document is a text document, the result is a text document.

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

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

A new attribute is created for each entry in the map appearing on the attributes option. The attribute name is taken from the entry's key while the attribute value is taken from the string value of the entry's value.

If an attribute with the same name as one of the attributes to be created already exists, the value specified on the attributes option 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 selection pattern in the match option. All matching elements are processed. If no elements match, the step will not change any elements.

This step cannot be used to add namespace declarations. It is a dynamic error (err:XC0059) if the name of any attribute is “xmlns” or uses the prefix “xmlns” or any other prefix that resolves to the namespace name http://www.w3.org/2000/xmlns/. However, if the attributes taken from the attributes use namespaces, prefixes, or prefixes bound to different namespaces, the document produced on the result output port will require namespace fixup.

If an attribute named xml:base is added or changed, the base URI of the element must also be amended accordingly.

The p:set-properties step sets document properties on the source document.

The document properties of the document on the source port are augmented with the values specified in the properties option. The document produced on the result port has the same representation but the adjusted property values.

If the merge option is true, then the supplied properties are added to the existing properties, overwriting already existing values for a given key. If it is false, the document’s properties are replaced by the new set.

It is a dynamic error (err:XD0070) if a value is assigned to the serialization document property that cannot be converted into map(xs:QName, item()*) according to the rules in section “QName handling” of [XProc 3.1].

It is a dynamic error (err:XC0069) if the properties map contains a key equal to the string “content-type”.

If the properties map contains a key equal to the string “base-uri” the associated value is taken as the new base URI of the resulting document. It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986].

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

The p:sleep step introduces a delay.

The p:sleep step copies each of the documents on the source port to the result port without changing them. Before copying the documents, it pauses for a period of time not less than duration milliseconds.

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