fn:transform

Invokes a transformation using a dynamically-loaded XSLT stylesheet.

Signature

fn:transform($options as map(*)) as map(*)

Properties

This function is nondeterministic, context-dependent, and focus-independent.

Rules

This function loads an XSLT stylesheet and invokes it to perform a transformation.

The inputs to the transformation are supplied in the form of a map. The option parameter conventions apply to this map; they do not apply to any nested map unless otherwise specified.

The function first identifies the requested XSLT version, as follows:

If the xslt-version option is present, the requested XSLT version is the value of that option.
Otherwise, the requested XSLT version is the value of the [xsl:]version attribute of the outermost element in the supplied stylesheet or package.

The function then attempts to locate an XSLT processor that implements the requested XSLT version.

If a processor that implements the requested XSLT version is available, then it is used.
Otherwise, if a processor that implements a version later than the requested version is available, then it is used.
Otherwise, the function fails indicating that no suitable XSLT processor is available.

The phrase locate an XSLT processor includes the possibility of locating a software product and configuring it to act as an XSLT processor that implements the requested XSLT version.

If more than one XSLT processor is available under the above rules, then the one that is chosen may be selected according to the availability of requested features: see below.

Once an XSLT processor has been selected that implements a given version of XSLT, the processor follows the rules of that version of the XSLT specification. This includes any decision to operate in backwards or forwards compatibility mode. For example, if an XSLT 2.0 processor is selected, and the stylesheet specifies version="1.0", then the processor will operate in backwards compatibility mode; if the same processor is selected and the stylesheet specifies version="3.0", the processor will operate in forwards compatibility mode.

The combinations of options that are relevant to each version of XSLT, other than xslt-version itself, are listed below. This is followed by a table giving the meaning of each option.

For invocation of an XSLT 1.0 processor (see [XSL Transformations (XSLT) Version 1.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
1. The stylesheet, provided by supplying exactly one of the following:
  
  stylesheet-location
  stylesheet-node
  stylesheet-text
2. The source tree, provided as the value of the source-node option.
3. Zero or more of the following additional options:
  
  stylesheet-base-uri
  stylesheet-params (defaults to an empty map)
  initial-mode (defaults to the unnamed mode)
  delivery-format (defaults to document)
  serialization-params (defaults to an empty map)
  enable-messages (default is implementation-defined)
  requested-properties (default is an empty map)
  vendor-options (defaults to an empty map)
  cache (default is implementation-defined)
For invocation of an XSLT 2.0 processor (see [XSLT 2.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
1. The stylesheet, provided by supplying exactly one of the following:
  
  stylesheet-location
  stylesheet-node
  stylesheet-text
2. Invocation details, as exactly one of the following:
  1. For apply-templates invocation, all of the following:
    
    source-node
    
    Optionally, initial-mode (defaults to the unnamed mode)
  2. For call-template invocation, all of the following:
    
    initial-template
    
    Optionally, source-node
3. Zero or more of the following additional options:
  
  stylesheet-base-uri
  stylesheet-params (defaults to an empty map)
  base-output-uri (defaults to absent)
  delivery-format (defaults to document)
  serialization-params (defaults to an empty map)
  enable-messages (default is implementation-defined)
  enable-trace (default is implementation-defined)
  requested-properties (default is an empty map)
  vendor-options (defaults to an empty map)
  cache (default is implementation-defined)
For invocation of an XSLT 3.0 processor (see [XSLT 3.0]), the supplied options must include all of the following (if anything else is present, it is ignored):
1. The stylesheet, provided either by supplying exactly one of the following:
  
  stylesheet-location
  stylesheet-node
  stylesheet-text
  
  Or by supplying exactly one of the following:
  
  package-location
  package-node
  package-text
  package-name plus optionally package-version
2. Invocation details, as exactly one of the following combinations:
  1. For apply-templates invocation, all of the following:
    
    Exactly one of source-node or initial-match-selection
    
    Optionally, initial-mode
    
    Optionally, template-params
    
    Optionally, tunnel-params
  2. For call-template invocation using an explicit template name, all of the following:
    
    initial-template
    
    Optionally, template-params
    
    Optionally, tunnel-params
    
    Optionally, source-node
  3. For call-template invocation using the defaulted template name xsl:initial-template, all of the following:
    
    Optionally, template-params
    
    Optionally, tunnel-params
    
    If the source-node option is present and initial-template is absent, then apply-templates invocation will be used. To use call-template invocation on the template named xsl:initial-template while also supplying a context item for use when evaluating global variables, either (a) supply the context item using the global-context-item option, or (b) supply source-node, and set the initial-template option explicitly to the QName xsl:initial-template
  4. For call-function invocation, all of the following:
    
    initial-function
    
    function-params
  The invocation method can be determined as the first of the following which applies:
  - If initial-function is present, then call-function invocation.
  - If initial-template is present, then call-template invocation.
  - If source-node or initial-match-selection is present, then apply-templates invocation.
  - Otherwise, call-template invocation using the default entry point xsl:initial-template.
3. Zero or more of the following additional options:
  
  stylesheet-base-uri
  static-params (defaults to an empty map)
  stylesheet-params (defaults to an empty map)
  global-context-item (defaults to absent)
  base-output-uri (defaults to absent)
  delivery-format
  serialization-params (defaults to an empty map)
  enable-assertions (default is false)
  enable-messages (default is implementation-defined)
  enable-trace (default is implementation-defined)
  requested-properties (default is an empty map)
  vendor-options (defaults to an empty map)
  cache (default is implementation-defined)

The meanings of each option are defined in the table below.

Key	Applies to	Value	Meaning
`base-output-uri`	1.0, 2.0, 3.0	The URI of the principal result document; also used as the base URI for resolving relative URIs of secondary result documents. If the value is a relative reference, it is resolved against the static base URI of the `fn:transform` function call. Type: `xs:string` Default: `The effect of not supplying a base output URI is defined by the XSLT specification; the implementation may supply a default, for example the directory containing the stylesheet, or the current working directory.`
`cache`	1.0, 2.0, 3.0	This option has no effect on the result of the transformation but may affect efficiency. The value `true` indicates an expectation that the same stylesheet is likely to be used for more than one transformation; the value `false` indicates an expectation that the stylesheet will be used once only. Type: `xs:boolean` Default: `true()`
`delivery-format`	1.0, 2.0, 3.0	The manner in which the transformation results should be delivered. Applies both to the principal result document and to secondary result documents created using `xsl:result-document`. Type: `xs:string` Default: `document, unless the relevant xsl:output or xsl:result-document element specifies build-tree="no" (applies to XSLT 3.0 only), in which case the default is raw.`
		`document`	The result is delivered as a document node.
		`serialized`	The result is delivered as a string, representing the results of serialization. Note that (as with the `fn:serialize` function) the final encoding stage of serialization (which turns a sequence of characters into a sequence of octets) is either skipped, or reversed by decoding the octet stream back into a character stream.
		`raw`	The result of the initial template or function is returned as an arbitrary XDM value (after conversion to the declared type, but without wrapping in a document node, and without serialization): when this option is chosen, the returned map contains the raw result.
`enable-assertions`	3.0	Indicates whether any `xsl:assert` instructions in the stylesheet are to be evaluated. Type: `xs:boolean` Default: `false()`
`enable-messages`	1.0, 2.0, 3.0	Indicates whether any `xsl:message` instructions in the stylesheet are to be evaluated. The destination and formatting of any such messages is implementation-defined. Type: `xs:boolean` Default: `Implementation-defined`
`enable-trace`	2.0, 3.0	Indicates whether any `fn:trace` functions in the stylesheet are to generate diagnostic messages. The destination and formatting of any such messages is implementation-defined. Type: `xs:boolean` Default: `Implementation-defined`
`function-params`	3.0	An array of values to be used as the arguments to the initial function call. The value is converted to the required type of the declared parameter using the function conversion rules. Type: `array(item()*)` Default: `Empty array`
`global-context-item`	3.0	The value of the global context item, as defined in XSLT 3.0 Type: `item()` Default: `The value of source-node`
`initial-function`	3.0	The name of the initial function to be called for call-function invocation. The arity of the function is inferred from the length of `function-params`. Type: `xs:QName` Default: `n/a`
`initial-match-selection`	3.0	The value of the initial match selection, as defined in XSLT 3.0 Type: `item()*` Default: `The value of source-node`
`initial-mode`	1.0, 2.0, 3.0	The name of the initial processing mode. Type: `xs:QName` Default:
`initial-template`	2.0, 3.0	The name of a named template in the stylesheet to act as the initial entry point. Type: `xs:QName` Default: `xsl:initial-template`
`package-name`	3.0	The name of the top-level stylesheet package to be invoked (an absolute URI) Type: `xs:string` Default: `n/a`
`package-location`	3.0	The location of the top-level stylesheet package, as a relative or absolute URI Type: `xs:string` Default: `n/a`
`package-node`	3.0	A document or element node containing the top-level stylesheet package Type: `node()` Default: `n/a`
`package-text`	3.0	The top-level stylesheet package in the form of unparsed lexical XML. Type: `xs:string` Default: `n/a`
`package-version`	3.0	The version of the top-level stylesheet package to be invoked. Type: `xs:string` Default: `"*" (any version)`
`post-process`	1.0 2.0 3.0	A function that is used to post-process each result document of the transformation (both the principal result and secondary results), in whatever form it would otherwise be delivered (document, serialized, or raw). The first argument of the function is the key used to identify the result in the map return by the `fn:transform` function (for example, this will be the supplied base output URI in the case of the principal result, or the string "output" if no base output URI was supplied). The second argument is the actual value. The value that is returned in the result of the `fn:transform` function is the result of applying this post-processing. If the implementation provides a way of writing or invoking functions with side-effects, this post-processing function might be used to save a copy of the result document to persistent storage. For example, if the implementation provides access to the EXPath File library [EXPath], then a serialized document might be written to filestore by calling the `file:write` function. Similar mechanisms might be used to issue an HTTP POST request that posts the result to an HTTP server, or to send the document to an email recipient. The semantics of calling functions with side-effects are entirely implementation-defined. If the primary purpose of the post-processing function is achieved by means of such side-effects, and if the actual results are not needed by the caller of the `fn:transform` function, then it does not matter what the post-processing function actually returns (it could be an empty sequence, for example). Calls to `fn:transform` can potentially have side-effects even in the absence of the post-processing option, because the XSLT specification allows a stylesheet to invoke extension functions that have side-effects. The semantics in this case are implementation-defined. Type: `function(xs:string, item()) as item()` Default: `function($a, $b) { $b }`
`requested-properties`	1.0, 2.0, 3.0	The keys in the map are QNames that could legitimately be supplied in a call to the XSLT `system-property` function; the values in the map are the requested settings of the corresponding property. The boolean values `true()` and `false()` are equivalent to the string values `yes` and `no`. As a special case, setting a value for `xsl:version` has no effect, because of the potential for conflict with other options. For example: Setting `xsl:product-name` to a particular value requests a particular XSLT software product. Setting `xsl:product-version` requests a specific version of that product. Setting `xsl:is-schema-aware` to `true()` requests a schema-aware processor. Setting `xsl:xsd-version` to `"1.1"` requests a processor that supports XML Schema version 1.1. Setting a boolean property such as `xsl:supports-dynamic-evaluation` to `false()` is interpreted as an explicit request for a processor in which the value of the property is false. The effect if the requests cannot be precisely met is implementation-defined. In some cases it may be appropriate to ignore the request or to provide an alternative (for example, a later version of the product than the one requested); in other cases it may be more appropriate to raise an error [ERRFOXT0001] indicating that no suitable XSLT processor is available. Type: `map(xs:QName, xs:anyAtomicType)` Default: `Empty map`
`serialization-params`	1.0, 2.0, 3.0	Serialization parameters for the principal result document. The supplied map follows the same rules that apply to a map supplied as the second argument of `fn:serialize`. When a parameter is supplied, the corresponding value overrides or augments the value specified in the unnamed `xsl:output` declaration (or its default), following the same rules as when one `xsl:output` declaration overrides another with lower import precedence. When a parameter is supplied and the corresponding value is an empty sequence (for example, `map{"standalone":()}`), any value specified in the unnamed `xsl:output` declaration is overridden by the default value. When a parameter is not supplied in `serialization-params` (that is, when the key is absent) the value that applies is the value appearing in the unnamed `xsl:output` declaration, or its default. Type: `map(xs:anyAtomicType, item()*)` Default: `Empty map`
`source-node`	1.0, 2.0, 3.0	When `source-node` is supplied then the `global-context-item` (the context item for evaluating global variables) is the root of the tree containing the supplied node. In addition, for apply-templates invocation, the `source-node` acts as the `initial-match-selection`, that is, stylesheet execution starts by applying templates to this node. Type: `node()` Default: `n/a`
`static-params`	3.0	The values of static parameters defined in the stylesheet; the keys are the names of the parameters, and the associated values are their values. The value is converted to the required type of the declared parameter using the function conversion rules. Type: `map(xs:QName, item()*)` Default: `Empty map`
`stylesheet-base-uri`	1.0, 2.0, 3.0	A string intended to be used as the static base URI of the principal stylesheet module. This value must be used if no other static base URI is available. If the supplied stylesheet already has a base URI (which will generally be the case if the stylesheet is supplied using `stylesheet-node` or `stylesheet-location`) then it is implementation-defined whether this parameter has any effect. If the value is a relative reference, it is resolved against the static base URI of the `fn:transform` function call. Type: `xs:string` Default: `n/a`
`stylesheet-location`	1.0, 2.0, 3.0	URI that can be used to locate the principal stylesheet module. If relative, it is resolved against the static base URI of the `fn:transform` function call. The value also acts as the default for stylesheet-base-uri. Type: `xs:string` Default: `n/a`
`stylesheet-node`	1.0, 2.0, 3.0	Root of the tree containing the principal stylesheet module, as a document or element node. The base URI of the node acts as the default for stylesheet-base-uri. Type: `node()` Default: `n/a`
`stylesheet-params`	1.0, 2.0, 3.0	A map holding values to be supplied for stylesheet parameters. The keys are the parameter names; the values are the corresponding parameter values. The values are converted if necessary to the required type using the function conversion rules. The default is an empty map. Type: `map(xs:QName, item()*)` Default: `Empty map`
`stylesheet-text`	1.0, 2.0, 3.0	The principal stylesheet module in the form of unparsed lexical XML. Type: `xs:string` Default: `n/a`
`template-params`	3.0	The values of non-tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the function conversion rules. Type: `map(xs:QName, item()*)` Default:
`tunnel-params`	3.0	The values of tunnel parameters to be supplied to the initial template, used with both apply-templates and call-template invocation. Each value is converted to the required type of the declared parameter using the function conversion rules. Type: `map(xs:QName, item()*)` Default: `Empty map`
`vendor-options`	1.0, 2.0, 3.0	Values for vendor-defined configuration options for the XSLT processor used to process the request. The key is the name of an option, expressed as a QName: the namespace URI of the QName should be a URI controlled by the vendor of the XSLT processor. The meaning of the associated value is implementation-defined. Implementations should ignore options whose names are in an unrecognized namespace. Default is an empty map. Type: `map{xs:QName, item()*}` Default: `Empty map`
`xslt-version`	1.0, 2.0, 3.0	The minimum level of the XSLT language that the processor must support. Type: `xs:decimal` Default: `The [xsl:]version attribute at the outermost level of the stylesheet.`

The result of the transformation is returned as a map. There is one entry in the map for the principal result document, and one for each secondary result document. The key is a URI in the form of an xs:string value. The key for the principal result document is the base output URI if specified, or the string "output" otherwise. The key for secondary result documents is the URI of the document, as an absolute URI. The associated value in each entry depends on the requested delivery format. If the delivery format is document, the value is a document node. If the delivery format is serialized, the value is a string containing the serialized result. If the delivery format is saved, the value is the absolute URI of the location where the serialized result has been saved. The saved document will not be accessible at this location within the current execution scope (this is to prevent any dependency on order of execution).

Where nodes are passed to or from the transformation, for example as the value of a stylesheet parameter or the result of a function, they should if possible retain their node identity, their base URI, their type annotations, and their relationships to all other nodes in the containing tree (including ancestors and siblings). If this is not possible, for example because the only way of passing nodes to the chosen XSLT implementation is by serializing and re-parsing, then a node may be passed in the form of a deep copy, which may lose information about the identity of the node, about its ancestors and siblings, about its base URI, about its type annotation, and about its relationships to other nodes passed across the interface.

It is implementation-defined whether the XSLT transformation is executed within the same execution scope as the calling code.

The function is nondeterministic in that it is implementation-dependent whether running the function twice against the same inputs produces identical results. The results of two invocations may differ in the identity of any returned nodes; they may also differ in other respects, for example because the value of fn:current-dateTime is different for the two invocations, or because the contents of external documents accessed using fn:doc or xsl:source-document change between one invocation and the next.

The delivery format saved indicates that the transformation should modify the state of the external environment. This has two noteworthy consequences:

It creates a potential security risk.
The fn:transform function ceases to be a pure function, because it has side-effects.

Implementations may mitigate these problems in a number of ways, including the following:

Use of the delivery-format=saved option may be disallowed, either completely or at user option.
The environment that the delivery-format=saved option is allowed to modify may be sand-boxed in some way. For example: resources that are created using this option may be accessible only via some special interface; the resource may become available only on completion of the execution scope in which the fn:transform function is evaluated; or the implementation may prevent the use functions such as fn:doc and fn:collection to access such resources.
Creating multiple resources with the same URI may be disallowed.
The implementation may define circumstances in which the side-effect of creating external resources is thwarted as a consequence of query optimization (for example, any situation in which a query calls fn:transform but has no functional dependency on the result of the call).
There may be restrictions on the URIs that can be used to identify saved resources

Error Conditions

A dynamic error is raised [ERRFOXT0001] if the transformation cannot be invoked because no suitable XSLT processor is available. This includes (but is not limited to) the following cases:

No XSLT processor is available;
No XSLT processor supporting the requested version of XSLT is available;
The XSLT processor API does not support some requested feature (for example, the ability to supply tunnel parameters externally);

A dynamic error is raised [ERRFOXT0002] if an error is detected in the supplied parameters (for example if two mutually-exclusive parameters are supplied).

If a static or dynamic error is reported by the XSLT processor, this function fails with a dynamic error, retaining the XSLT error code.

A dynamic error is raised [ERRFOXT0003] if the XSLT transformation invoked by a call on fn:transform fails with a static or dynamic error, and no more specific error code is available.

XSLT 1.0 does not define any error codes, so this is the likely outcome with an XSLT 1.0 processor. XSLT 2.0 and 3.0 do define error codes, but some APIs do not expose them. If multiple errors are signaled by the transformation (which is most likely to happen with static errors) then the error code should where possible be that of one of these errors, chosen arbitrarily; the processor may make details of additional errors available to the application in an implementation-defined way.

A dynamic error is raised [ERRFOXT0004] if the use of this function (or of selected options) has been externally disabled, for example for security reasons.

A dynamic error is raised [ERRFOXT0005] if delivery-format is saved and the results cannot be saved at the specified location.

A dynamic error is raised [ERRFOXT0006] if the transformation produces output containing characters available only in XML 1.1, and the calling processor cannot handle such characters.

A dynamic error is raised [ERRFOXT0007] if the option delivery-format:saved is used in a way that violates any implementation-defined restrictions on its use.

Recursive use of the fn:transform function may lead to catastrophic failures such as non-termination or stack overflow. No error code is assigned to such conditions, since they cannot necessarily be detected by the processor.

Notes

As with all other functions in this specification, conformance requirements depend on the host language. For example, a host language might specify that provision of this function is optional, or that it is excluded entirely, or that implementations are required to support a particular set of values for the xslt-version parameter.

Even where support for this function is mandatory, it is recommended for security reasons that implementations should provide a user option to disable its use, or to disable aspects of its functionality such as the ability to write to persistent resources.

Examples

The following example loads a stylesheet from the location render.xsl, applies it to a document loaded from test.xml, and uses an XPath expression to examine the result:

let $result := fn:transform(
  map {
    "stylesheet-location" : "render.xsl",
    "source-node"    : fn:doc('test.xml')
  })
return $result?output//body