XSL Transformations (XSLT) Version 4.0

1.1 What is XSLT?

XSLT is a programming language designed principally to transform data.

A transformation in the XSLT language is expressed in the form of a stylesheet. A stylesheet is made up of one or more well-formed XML [XML 1.0] documents conforming to the Namespaces in XML Recommendation [Namespaces in XML].

A stylesheet generally includes elements that are defined by XSLT as well as elements that are not defined by XSLT. XSLT-defined elements are distinguished by use of the namespace http://www.w3.org/1999/XSL/Transform (see 3.1.1 XSLT Namespace), which is referred to in this specification as the XSLT namespace. Thus this specification is a definition of the syntax and semantics of the XSLT namespace.

The term stylesheet reflects the fact that one of the important roles of XSLT is to add styling information to an XML source document, by transforming it into a document consisting of XSL formatting objects (see [XSL-FO]), or into another presentation-oriented format such as HTML, XHTML, or SVG. However, XSLT is used for a wide range of transformation tasks, not exclusively for formatting and presentation applications.

A transformation expressed in XSLT describes rules for transforming input data into output data. The inputs and outputs will all be instances of the XDM data model, described in [XDM 3.04.0]. In the simplest and most common case, the input is an XML document referred to as the source document or source tree, and the output is an XML document referred to as the result tree. It is also possible to process multiple source documents, to generate multiple result documents, and to handle formats other than XML.

The transformation is achieved by a set of template rules. A template rule associates a pattern, which typically matches nodes in the source document, with a sequence constructor. In many cases, evaluating the sequence constructor will cause new nodes to be constructed, which can be used to produce part of a result tree. The structure of the result trees can be completely different from the structure of the source trees. In constructing a result tree, nodes from the source trees can be filtered and reordered, and arbitrary structure can be added. Because patterns can point to nodes according to typological features, a stylesheet can be applicable to a wide class of source documents that have similar tree structures.

Stylesheets are modular; they may contain several packages developed independently of each other, and each package may consist of several stylesheet modules.

[Definition: A stylesheet consists of one or more packages: specifically, one top-level package and zero or more library packages.]

[Definition: For a given transformation, one package functions as the top-level package. The complete stylesheet is assembled by finding the packages referenced directly or indirectly from the top-level package using xsl:use-package declarations: see 3.5.2 Dependencies between Packages.]

[Definition: Every package within a stylesheet, other than the top-level package, is referred to as a library package.]

[Definition: Within a package, one stylesheet module functions as the principal stylesheet module. The complete package is assembled by finding the stylesheet modules referenced directly or indirectly from the principal stylesheet module using xsl:include and xsl:import elements: see 3.11.2 Stylesheet Inclusion and 3.11.3 Stylesheet Import.]

1.2 What’s New in XSLT 4.0?

XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation [XSLT 3.0] published on 8 June 2017.

The changes in this version of the language are relatively minor usability enhancements. There are no changes to the data model or processing model. Instead, the specification attempts to fill a number of gaps in functionality resulting from feedback from XSLT 3.0 users. The main areas covered are:

• Enhancements to the type system to allow more expressive constraints, especially for maps and atomic values.

• Additional functionality for processing arrays.

• Exploitation of the power afforded by first-class function items.

XSLT 4.0 also includes optional facilities to serialize the results of a transformation, by means of an interface to the serialization component described in [XSLT and XQuery Serialization 4.0].

XSLT 4.0 requires support for XPath 4.0.

A full list of changes is at I Changes since XSLT 3.0.

2.1 Terminology

For a full glossary of terms, see B Glossary.

[Definition: The software responsible for transforming source trees into result trees using an XSLT stylesheet is referred to as the processor. This is sometimes expanded to XSLT processor to avoid any confusion with other processors, for example an XML processor.]

[Definition: A specific product that performs the functions of an XSLT processor is referred to as an implementation.]

[Definition: The term tree is used (as in [XDM 3.0]) to refer to the aggregate consisting of a parentless node together with all its descendant nodes, plus all their attributes and namespaces.][Definition: The term tree is used (as in [XDM 4.0]) to refer to the aggregate consisting of a parentless node together with all its descendant nodes, plus all their attributes and namespaces.][Definition: The term tree is used (as in [XDM 3.04.0]) to refer to the aggregate consisting of a parentless node together with all its descendant nodes, plus all their attributes and namespaces.]

The output of a transformation consists of the following:

1. [Definition: A principal result: this can be any sequence of items (as defined in [XDM 3.0]).] The principal result is the value returned by the function or template in the stylesheet that is nominated as the entry point, as described in 2.3 Initiating a Transformation.[Definition: A principal result: this can be any sequence of items (as defined in [XDM 4.0]).] The principal result is the value returned by the function or template in the stylesheet that is nominated as the entry point, as described in 2.3 Initiating a Transformation.[Definition: A principal result: this can be any sequence of items (as defined in [XDM 3.04.0]).] The principal result is the value returned by the function or template in the stylesheet that is nominated as the entry point, as described in 2.3 Initiating a Transformation.

2. [Definition: Zero or more secondary results: each secondary result can be any sequence of items (as defined in [XDM 3.0]).] A secondary result is the value returned by evaluating the body of an xsl:result-document instruction.[Definition: Zero or more secondary results: each secondary result can be any sequence of items (as defined in [XDM 4.0]).] A secondary result is the value returned by evaluating the body of an xsl:result-document instruction.[Definition: Zero or more secondary results: each secondary result can be any sequence of items (as defined in [XDM 3.04.0]).] A secondary result is the value returned by evaluating the body of an xsl:result-document instruction.

3. Zero or more messages. Messages are generated by the xsl:message and xsl:assert instructions, and are described in 23.1 Messages and 23.2 Assertions.

4. Static or dynamic errors: see 2.14 Error Handling.

The principal result and the secondary results may be post-processed as described in 2.3.6 Post-processing the Raw Result.

[Definition: The term result tree is used to refer to any tree constructed by instructions in the stylesheet. A result tree is either a final result tree or a temporary tree.]

[Definition: A final result tree is a result tree that forms part of the output of a transformation: specifically, a tree built by post-processing the items in the principal result or in a secondary result. Once created, the contents of a final result tree are not accessible within the stylesheet itself.] Any final result tree may be serialized as described in 26 Serialization.

[Definition: The term source tree means any tree provided as input to the transformation. This includes the document containing the global context item if any, documents containing nodes present in the initial match selection, documents containing nodes supplied as the values of stylesheet parameters, documents obtained from the results of functions such as document, doc, and collection, documents read using the xsl:source-document instruction, and documents returned by extension functions or extension instructions. In the context of a particular XSLT instruction, the term source tree means any tree provided as input to that instruction; this may be a source tree of the transformation as a whole, or it may be a temporary tree produced during the course of the transformation.]

[Definition: The term temporary tree means any tree that is neither a source tree nor a final result tree.] Temporary trees are used to hold intermediate results during the execution of the transformation.

Unless otherwise stated, the term “tree” refers to a tree rooted at a parentless node: that is, the term does not include subtrees of larger trees. Every node therefore belongs to exactly one tree.

In this specification the phrases must, must not, should, should not, may, required, and recommended, when used in normative text and rendered in small capitals, are to be interpreted as described in [RFC2119].

Where the phrase must, must not, or required relates to the behavior of the XSLT processor, then an implementation is not conformant unless it behaves as specified, subject to the more detailed rules in 27 Conformance.

Where the phrase must, must not, or required relates to a stylesheet then the processor must enforce this constraint on stylesheets by raising an error if the constraint is not satisfied.

Where the phrase should, should not, or recommended relates to a stylesheet then a processor may produce warning messages if the constraint is not satisfied, but must not treat this as an error.

[Definition: In this specification, the term implementation-defined refers to a feature where the implementation is allowed some flexibility, and where the choices made by the implementation must be described in documentation that accompanies any conformance claim.]

[Definition: The term implementation-dependent refers to a feature where the behavior may vary from one implementation to another, and where the vendor is not expected to provide a full specification of the behavior.] (This might apply, for example, to limits on the size of source documents that can be transformed.)

In all cases where this specification leaves the behavior implementation-defined or implementation-dependent, the implementation has the option of providing mechanisms that allow the user to influence the behavior.

A paragraph labeled as a Note or described as an example is non-normative.

Many terms used in this document are defined in the XPath specification [XPath 4.0] or the XDM specification [XDM 3.04.0]. Particular attention is drawn to the following:

• [Definition: The term atomization is defined in Section 2.5.3 Atomization^XP. It is a process that takes as input a sequence of items, and returns a sequence of atomic items, in which the nodes are replaced by their typed values as defined in [XDM 3.0]. Arrays (see 22 Arrays) are atomized by atomizing their members, recursively.] For some items (for example, elements with element-only content, function items, and maps, atomization raises a dynamic error.[Definition: The term atomization is defined in [XPath 4.0] section 2.5.3 Atomization. It is a process that takes as input a sequence of items, and returns a sequence of atomic items, in which the nodes are replaced by their typed values as defined in [XDM 4.0]. Arrays (see 22 Arrays) are atomized by atomizing their members, recursively.] For some items (for example, elements with element-only content, function items, and maps, atomization raises a dynamic error.[Definition: The term atomization is defined in [XPath 4.0] section Section 2.5.3 AtomizationXP. It is a process that takes as input a sequence of items, and returns a sequence of atomic items, in which the nodes are replaced by their typed values as defined in [XDM 3.04.0]. Arrays (see 22 Arrays) are atomized by atomizing their members, recursively.] For some items (for example, elements with element-only content, function items, and maps, atomization raises a dynamic error.

• [Definition: The term typed value is defined in Section 5.15 typed-value Accessor ^DM30. Every node, other than an element whose type annotation identifies it as having element-only content, has a typed value. For example, the typed value of an attribute of type xs:IDREFS is a sequence of zero or more xs:IDREF values.][Definition: The term typed value is defined in [XDM 4.0] section 7.5.14 typed-value Accessor. Every node, other than an element whose type annotation identifies it as having element-only content, has a typed value. For example, the typed value of an attribute of type xs:IDREFS is a sequence of zero or more xs:IDREF values.][Definition: The term typed value is defined in [XDM 4.0] section Section 5.157.5.14 typed-value Accessor DM30. Every node, other than an element whose type annotation identifies it as having element-only content, has a typed value. For example, the typed value of an attribute of type xs:IDREFS is a sequence of zero or more xs:IDREF values.]

• [Definition: The term string value is defined in Section 5.13 string-value Accessor ^DM30. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.][Definition: The term string value is defined in [XDM 4.0] section 7.5.12 string-value Accessor. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.][Definition: The term string value is defined in [XDM 4.0] section Section 5.137.5.12 string-value Accessor DM30. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.]

• [Definition: The term XPath 1.0 compatibility mode is defined in Section 2.2.1 Static Context^XP. This is a setting in the static context of an XPath expression; it has two values, true and false. When the value is set to true, the semantics of function calls and certain other operations are adjusted to give a greater degree of backwards compatibility between XPath 4.0 and XPath 1.0.][Definition: The term XPath 1.0 compatibility mode is defined in [XPath 4.0] section 2.2.1 Static Context. This is a setting in the static context of an XPath expression; it has two values, true and false. When the value is set to true, the semantics of function calls and certain other operations are adjusted to give a greater degree of backwards compatibility between XPath 4.0 and XPath 1.0.][Definition: The term XPath 1.0 compatibility mode is defined in [XPath 4.0] section Section 2.2.1 Static ContextXP. This is a setting in the static context of an XPath expression; it has two values, true and false. When the value is set to true, the semantics of function calls and certain other operations are adjusted to give a greater degree of backwards compatibility between XPath 4.0 and XPath 1.0.]

• [Definition: The term function definition is defined in Section 2.2.1 Static Context^XP. It is the definition of a function that can be called statically from within an XPath expression: in the case of XSLT it typically means either a stylesheet function, or a built-in function such as those defined in [Functions and Operators 4.0]][Definition: The term function definition is defined in [XPath 4.0] section 2.2.1 Static Context. It is the definition of a function that can be called statically from within an XPath expression: in the case of XSLT it typically means either a stylesheet function, or a built-in function such as those defined in [Functions and Operators 4.0]][Definition: The term function definition is defined in [XPath 4.0] section Section 2.2.1 Static ContextXP. It is the definition of a function that can be called statically from within an XPath expression: in the case of XSLT it typically means either a stylesheet function, or a built-in function such as those defined in [Functions and Operators 4.0]]

• [Definition: A function definition has an arity range, which defines the minimum and maximum number of arguments that must be supplied in a call to the function. The static context can contain multiple function definitions with the same name, provided that their arity ranges do not overlap.]

2.3 Initiating a Transformation

This document does not specify any application programming interfaces or other interfaces for initiating a transformation. This section, however, describes the information that is supplied when a transformation is initiated. Except where otherwise indicated, the information is required.

The execution of a stylesheet necessarily involves two activities: static analysis and dynamic evaluation. Static analysis consists of those tasks that can be performed by inspection of the stylesheet alone, including the binding of static variables, the evaluation of [xsl:]use-when expressions (see 3.13.3 Conditional Element Inclusion) and shadow attributes (see 3.13.4 Shadow Attributes), and the detection of static errors. Dynamic evaluation consists of tasks which in general cannot be carried out until a source document is available.

Dynamic evaluation is further divided into two activities: priming the stylesheet, and invoking a selected component.

• Priming the stylesheet provides the dynamic context for evaluation, and supplies all the information needed to establish the values of global variables.

• Invoking a component (such as a template or function) causes evaluation of that template or function to produce a result, which is an arbitrary XDM value.

  [Definition: The result of invoking the selected component, after any required conversion to the declared result type of the component, is referred to as the raw result.]

  The raw result of the invocation is the immediate result of evaluating the sequence constructor contained in the target template or function, modified by applying the coercion rules to convert the immediate result to the type declared in the as attribute of the xsl:template or xsl:function declaration, if present.

  This raw result may optionally be post-processed to construct a result tree, to serialize the result, or both, as described in 2.3.6 Post-processing the Raw Result.

Implementations may allow static analysis and dynamic evaluation to be initiated independently, so that the cost of static analysis can be amortized over multiple transformations using the same stylesheet. Implementations may also allow priming of a stylesheet and invocation of components to be initiated independently, in which case a single act of priming the stylesheet may be followed by a series of independent component invocations. Although this specification does not require such a separation, this section distinguishes information that is needed before static analysis can proceed, information that is needed to prime the stylesheet, and information that is needed when invoking components.

The language is designed to allow the static analysis of each package to be performed independently of other packages, with only basic knowledge of the properties of components made available by used packages. Beyond this, the specification leaves it to implementations to decide how to organize this process. When packages are not used explicitly, the entire stylesheet is treated as a single package.

2.7 Parsing and Serialization

An XSLT stylesheet describes a process that constructs a set of results from a set of inputs. The inputs are the data provided at stylesheet invocation, as described in 2.3 Initiating a Transformation. The results include the principal result (an arbitrary sequence), which is the result of the initial component invocation, together with any secondary results produced using xsl:result-document instructions.

The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [XDM 3.0]. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build a source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM Level 2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the XDM data model as described in [XDM 3.0], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [XDM 4.0]. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build a source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM Level 2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the XDM data model as described in [XDM 4.0], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [XDM 3.04.0]. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build a source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM Level 2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the XDM data model as described in [XDM 3.04.0], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.

[Definition: A frequent requirement is to output a final result tree as an XML document (or in other formats such as HTML). This process is referred to as serialization.]

Like parsing, serialization is not part of the transformation process, and it is not required that an XSLT processor must be able to perform serialization. However, for pragmatic reasons, this specification describes declarations (the xsl:output element and the xsl:character-map declarations, see 26 Serialization), and attributes on the xsl:result-document instruction, that allow a stylesheet to specify the desired properties of a serialized output file. When serialization is not being performed, either because the implementation does not support the serialization option, or because the user is executing the transformation in a way that does not invoke serialization, then the content of the xsl:output and xsl:character-map declarations has no effect. Under these circumstances the processor may raise any errors in an xsl:output or xsl:character-map declaration, or in the serialization attributes of xsl:result-document, but is not required to do so.

2.10 Stylesheets and XML Schemas

An XSLT stylesheet can make use of information from a schema. An XSLT transformation can take place in the absence of a schema (and, indeed, in the absence of a DTD), but where the source document has undergone schema validity assessment, the XSLT processor has access to the type information associated with individual nodes, not merely to the untyped text.

Information from a schema can be used both statically (when the stylesheet is compiled), and dynamically (during evaluation of the stylesheet to transform a source document).

There are places within a stylesheet, and within XPath expressions and patterns in a stylesheet, where it is possible to refer to named type definitions in a schema, or to element and attribute declarations. For example, it is possible to declare the types expected for the parameters of a function. This is done using a SequenceType.

[Definition: A SequenceType constrains the type and number of items in a sequence. The term is used both to denote the concept, and to refer to the syntactic form in which sequence types are expressed in the XPath grammar: specifically SequenceType^XP in [XPath 4.0].]

[Definition: Type definitions and element and attribute declarations are referred to collectively as schema components.]

[Definition: The schema components that may be referenced by name in a package are referred to as the in-scope schema components.]

The set of in-scope schema components may vary between one package and another, and between different parts of the same package, but as explained in 3.15 Importing Schema Components, the schema components used in different parts of the stylesheet must be consistent with each other.

The conformance rules for XSLT 4.0, defined in 27 Conformance, distinguish between a basic XSLT processor and a schema-aware XSLT processor. As the names suggest, a basic XSLT processor does not support the features of XSLT that require access to schema information, either statically or dynamically. A stylesheet that works with a basic XSLT processor will produce the same results with a schema-aware XSLT processor provided that the source documents are untyped (that is, they are not validated against a schema). However, if source documents are validated against a schema then the results may be different from the case where they are not validated. Some constructs that work on untyped data may fail with typed data (for example, an attribute of type xs:date cannot be used as an argument of the substring function) and other constructs may produce different results depending on the datatype (for example, given the element <product price="10.00" discount="2.00"/>, the expression @price gt @discount will return true if the attributes have type xs:decimal, but will return false if they are untyped).

There is a standard set of type definitions that are always available as in-scope schema components in every stylesheet. These are defined in 3.14 Built-in Types.

The remainder of this section describes facilities that are available only with a schema-aware XSLT processor.

Additional schema components (type definitions, element declarations, and attribute declarations) may be added to the in-scope schema components by means of the xsl:import-schema declaration in a stylesheet.

The xsl:import-schema declaration may reference an external schema document by means of a URI, or it may contain an inline xs:schema element.

An xsl:import-schema declaration may include a role attribute, which indicates that the schema components are only to be present in the static context of a region of the stylesheet where they are explicitly invoked by means of an [xsl:]schema-role attribute.

It is only necessary to import a schema explicitly if one or more of its schema components are referenced explicitly by name in the stylesheet; it is not necessary to import a schema merely because the stylesheet is used to process a source document that has been assessed against that schema. It is possible to make use of the information resulting from schema assessment (for example, the fact that a particular attribute holds a date) even if no schema has been imported by the stylesheet.

Importing a schema does not of itself say anything about the type of the source document that the stylesheet is expected to process. The imported type definitions can be used for temporary nodes or for nodes on a result tree just as much as for nodes in source documents. It is possible to make assertions about the type of an input document by means of tests within the stylesheet. For example:

<xsl:mode typed="lax"/>
<xsl:global-context-item use="required"
            as="document-node(schema-element(my:invoice))"/>

It is also true that importing a schema does not of itself say anything about the structure of the result tree. It is possible to request validation of a result tree against the schema by using the xsl:result-document instruction, for example:

<xsl:template match="/">
  <xsl:result-document validation="strict">
    <xhtml:html>
      <xsl:apply-templates/>
    </xhtml:html>
  </xsl:result-document>
</xsl:template>

It is possible that a source document may contain nodes whose type annotation is not one of the types imported by the stylesheet. This creates a potential problem because in the case of an expression such as data(.) instance of xs:integer the system needs to know whether the type named in the type annotation of the context node is derived by restriction from the type xs:integer. This information is not explicitly available in an XDM tree, as defined in [XDM 3.0]. The implementation may choose one of several strategies for dealing with this situation:It is possible that a source document may contain nodes whose type annotation is not one of the types imported by the stylesheet. This creates a potential problem because in the case of an expression such as data(.) instance of xs:integer the system needs to know whether the type named in the type annotation of the context node is derived by restriction from the type xs:integer. This information is not explicitly available in an XDM tree, as defined in [XDM 4.0]. The implementation may choose one of several strategies for dealing with this situation:It is possible that a source document may contain nodes whose type annotation is not one of the types imported by the stylesheet. This creates a potential problem because in the case of an expression such as data(.) instance of xs:integer the system needs to know whether the type named in the type annotation of the context node is derived by restriction from the type xs:integer. This information is not explicitly available in an XDM tree, as defined in [XDM 3.04.0]. The implementation may choose one of several strategies for dealing with this situation:

1. The processor may raise a dynamic error if a source document is found to contain a type annotation that is not known to the processor.

2. The processor may maintain additional metadata, beyond that described in [XDM 3.04.0], that allows the source document to be processed as if all the necessary schema information had been imported using xsl:import-schema. Such metadata might be held in the data structure representing the source document itself, or it might be held in a system catalog or repository.

3. The processor may be configured to use a fixed set of schemas, which are automatically used to validate all source documents before they can be supplied as input to a transformation. In this case it is impossible for a source document to have a type annotation that the processor is not aware of.

4. The processor may be configured to treat the source document as if no schema processing had been performed, that is, effectively to strip all type annotations from elements and attributes on input, marking them instead as having type xs:untyped and xs:untypedAtomic respectively.

Where a stylesheet author chooses to make assertions about the types of nodes or of variables and parameters, it is possible for an XSLT processor to perform static analysis of the stylesheet (that is, analysis in the absence of any source document). Such analysis may reveal errors that would otherwise not be discovered until the transformation is actually executed. An XSLT processor is not required to perform such static type-checking. Under some circumstances (see 2.14 Error Handling) type errors that are detected early may be raised as static errors. In addition an implementation may report any condition found during static analysis as a warning, provided that this does not prevent the stylesheet being evaluated as described by this specification.

A stylesheet can also control the type annotations of nodes that it constructs in a result tree. This can be done in a number of ways.

• It is possible to request explicit validation of a complete document, that is, a result tree rooted at a document node. Validation is either strict or lax, as described in [XML Schema Part 1]. If validation of a result tree fails (strictly speaking, if the outcome of the validity assessment is invalid), then the transformation fails, but in all other cases, the element and attribute nodes of the tree will be annotated with the names of the types to which these nodes conform. These type annotations will be discarded if the result tree is serialized as an XML document, but they remain available when the result tree is passed to an application (perhaps another stylesheet) for further processing.

• It is also possible to validate individual element and attribute nodes as they are constructed. This is done using the type and validation attributes of the xsl:element, xsl:attribute, xsl:copy, and xsl:copy-of instructions, or the xsl:type and xsl:validation attributes of a literal result element.

• When elements, attributes, or document nodes are copied, either explicitly using the xsl:copy or xsl:copy-of instructions, or implicitly when nodes in a sequence are attached to a new parent node, the options validation="strip" and validation="preserve" are available, to control whether existing type annotations are to be retained or not.

When nodes in a temporary tree are validated, type information is available for use by operations carried out on the temporary tree, in the same way as for a source document that has undergone schema assessment.

For details of how validation of element and attribute nodes works, see 25.4 Validation.

2.14 Error Handling

[Definition: An error that can be detected by examining a stylesheet before execution starts (that is, before the source document and values of stylesheet parameters are available) is referred to as a static error.]

Generally, errors in the structure of the stylesheet, or in the syntax of XPath expressions contained in the stylesheet, are classified as static errors. Where this specification states that an element in the stylesheet must or must not appear in a certain position, or that it must or must not have a particular attribute, or that an attribute must or must not have a value satisfying specified conditions, then any contravention of this rule is a static error unless otherwise specified.

A processor must provide a mode of operation that takes a (possibly erroneous) stylesheet package as input and enables the user to determine whether or not that package contains any static errors.

A processor may also provide a mode of operation in which static errors in parts of the stylesheet that are not evaluated can go unreported.

[Definition: An error that is not capable of detection until a source document is being transformed is referred to as a dynamic error.]

When a dynamic error occurs, and is not caught using xsl:catch, the processormust raise the error, and the transformation fails.

Because different implementations may optimize execution of the stylesheet in different ways, the detection of dynamic errors is to some degree implementation-dependent. In cases where an implementation is able to produce a principal result or secondary result without evaluating a particular construct, the implementation is never required to evaluate that construct 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 variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will raise this error and others will not.

There are some cases where this specification requires that a construct must not be evaluated: for example, the content of an xsl:if instruction must not be evaluated if the test condition is false. This means that an implementation must not raise any dynamic errors that would arise if the construct were evaluated.

An implementation may raise a dynamic error before any source document is available, but only if it can determine that the error would be raised for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see 9.11 Circular Definitions.

There are also some dynamic errors where the specification gives a processor license to raise the error during the analysis phase even if the construct might never be executed; an example is the use of an invalid QName as a literal argument to a function such as key, or the use of an invalid regular expression in the regex attribute of the xsl:analyze-string instruction.

A dynamic error is also raised during the static analysis phase if the error occurs during evaluation of a static expression.

The XPath specification states (see Section 2.4.1 Kinds of Errors^XP) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be raised as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be raised as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be raised as dynamic errors, and raised only if the XPath expression is actually evaluated.The XPath specification states (see [XPath 4.0] section 2.4.1 Kinds of Errors) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be raised as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be raised as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be raised as dynamic errors, and raised only if the XPath expression is actually evaluated.The XPath specification states (see [XPath 4.0] section Section 2.4.1 Kinds of ErrorsXP) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be raised as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be raised as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be raised as dynamic errors, and raised only if the XPath expression is actually evaluated.

<xsl:choose>
  <xsl:when test="system-property('xsl:version') = '1.0'">
    <xsl:value-of select="1 div 0"/>
  </xsl:when>
  <xsl:otherwise>
    <xsl:value-of select="xs:double('INF')"/>
  </xsl:otherwise>
</xsl:choose>

[Definition: Certain errors are classified as type errors. A type error occurs when the value supplied as input to an operation is of the wrong type for that operation, for example when an integer is supplied to an operation that expects a node.] If a type error occurs in an instruction that is actually evaluated, then it must be raised in the same way as a dynamic error. Alternatively, an implementation may raise a type error during the analysis phase in the same way as a static error, even if it occurs in part of the stylesheet that is never evaluated, provided it can establish that execution of a particular construct would never succeed.

It is implementation-defined whether type errors are raised statically.

<xsl:if test="false()">
  <xsl:number select="42"/>
</xsl:if>

<xsl:template match="para">
  <xsl:param name="p" as="item()"/>
  <xsl:number select="$p"/>
</xsl:template>

If more than one error arises, an implementation is not required to raise any errors other than the first one that it detects. It is implementation-dependent which of the several errors is raised. This applies both to static errors and to dynamic errors. An implementation is allowed to raise more than one error, but if any errors have been raised, it must not finish as if the transformation were successful.

When a transformation raises one or more dynamic errors, the final state of any persistent resources updated by the transformation is implementation-dependent. Implementations are not required to restore such resources to their initial state. In particular, where a transformation produces multiple result documents, it is possible that one or more serialized result documents may be written successfully before the transformation terminates, but the application cannot rely on this behavior.

Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.

[Definition: If a transformation has successfully produced a principal result or secondary result, it is still possible that errors may occur in serializing that result . For example, it may be impossible to serialize the result using the encoding selected by the user. Such an error is referred to as a serialization error.] If the processor performs serialization, then it must do so as specified in 26 Serialization, and in particular it must raise any serialization errors that occur.

Errors are identified by a QName. For errors defined in this specification, the namespace of the QName is always http://www.w3.org/2005/xqt-errors (and is therefore not given explicitly), while the local part is an 8-character code in the form PPSSNNNN. Here PP is always XT (meaning XSLT), and SS is one of SE (static error), DE (dynamic error), or TE (type error). Note that the allocation of an error to one of these categories is purely for convenience and carries no normative implications about the way the error is handled. Many errors, for example, can be raised either dynamically or statically. These error codes are used to label error conditions in this specification, and are summarized in D Summary of Error Conditions.

Errors defined in related specifications ([XPath 4.0], [Functions and Operators 4.0][XSLT and XQuery Serialization]) use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.Errors defined in related specifications ([XPath 4.0], [Functions and Operators 4.0][xslt-xquery-serialization-30]) use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.Errors defined in related specifications ([XPath 4.0], [Functions and Operators 4.0][XSLT and XQuery Serialization][xslt-xquery-serialization-30]) use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.

Implementations must use the codes defined in these specifications when raising dynamic errors, to ensure that xsl:catch behaves in an interoperable way across implementations. Stylesheet authors should note, however, that there are many examples of errors where more than one rule in this specification is violated, and where the processor therefore has discretion in deciding which error code to associate with the condition: there is therefore no guarantee that different processors will always use the same error code for the same erroneous input.

Additional errors defined by an implementation (or by an application) may use QNames in an implementation-defined (or user-defined) namespace without risk of collision.

3.1 Namespaces

A stylesheet module is typically written as a namespace well-formed XML document: more formally, as described in 3.6 Stylesheet Modules, a stylesheet module takes the form of an XDM tree rooted at an element node.

The names of elements and attributes in source documents and result documents are namespace-qualified names. In addition, as described in 5.1.1 Qualified Names, XSLT uses namespace-qualified names to identify variables, functions, templates, and other components. These names generally use namespace prefixes that are resolved to namespace URIs using a set of prefix-uri namespace bindings.

There are two ways namespace bindings can be established in a stylesheet module:

• [Definition:  The native namespace bindings for any element in an XSLT stylesheet module are the prefix-uri mappings defined by the namespace nodes of that element, according to the rules in [XDM 3.0].][Definition:  The native namespace bindings for any element in an XSLT stylesheet module are the prefix-uri mappings defined by the namespace nodes of that element, according to the rules in [XDM 4.0].][Definition:  The native namespace bindings for any element in an XSLT stylesheet module are the prefix-uri mappings defined by the namespace nodes of that element, according to the rules in [XDM 3.04.0].]

  For example, a namespace declaration of the form xmlns:math="http://www.w3.org/2005/xpath-functions/math establishes a binding of the prefix math to the namespace URI http://www.w3.org/2005/xpath-functions/math, thereby enabling functions in that namespace to be invoked using an expression such as math:sin($theta)

• [Definition:  The fixed namespace bindings for a stylesheet module are established using the fixed-namespaces attribute on the xsl:stylesheet, xsl:transform, or xsl:package element enclosing the stylesheet module.]

  For example, the attribute fixed-namespaces="math map array" establishes bindings for the prefixes math, map, and array to the namespace URIs conventionally associated with these prefixes as described in 5.1.3 Reserved Namespaces.

Prefixes used in element and attribute names in the stylesheet, because these are interpreted by the XML parser and not only by the XSLT processor, must be bound using native namespace bindings. In particular, the XSLT namespace is used in the names of XSLT elements, so it must be declared in every stylesheet module using a namespace declaration such as xmlns:xsl="http://www.w3.org/1999/XSL/Transform. (A different prefix can be used: some users prefer xslt, some favor the default namespace.) But namespace prefixes that are only used within the content of attribute and text nodes in the stylesheet (for example, select="math:sin($theta)") can be declared in fixed namespace bindings.

[Definition:  The applicable static namespaces for an element in a stylesheet module are the fixed namespace bindings for the module if the root element of the module has a fixed-namespaces attribute, or the native namespace bindings of the element otherwise. ]

The effect of declaring fixed namespace bindings is described in more detail in 3.7.1 The fixed-namespaces Attribute.

3.2 Extension Attributes

[Definition: An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded QName (see [XPath 4.0]) of the attribute has a non-null namespace URI. These attributes are referred to as extension attributes.] The presence of an extension attribute must not cause the principal result or any secondary result of the transformation to be different from the results that a conformant XSLT 4.0 processor might produce. They must not cause the processor to fail to raise an error that a conformant processor is required to raise. This means that an extension attribute must not change the effect of any instruction except to the extent that the effect is implementation-defined or implementation-dependent.

Furthermore, if serialization is performed using one of the serialization methods described in [XSLT and XQuery Serialization][xslt-xquery-serialization-30], the presence of an extension attribute must not cause the serializer to behave in a way that is inconsistent with the mandatory provisions of that specification.

<xsl:message abc:pause="yes"
    xmlns:abc="http://vendor.example.com/xslt/extensions">
       Phase 1 complete
</xsl:message>

[ERR XTSE0090] It is a static error for an element from the XSLT namespace to have an attribute whose namespace is either null (that is, an attribute with an unprefixed name) or the XSLT namespace, other than attributes defined for the element in this document.

3.5 Packages

[Definition: An explicit package is represented by an xsl:package element, which will generally be the outermost element of an XML document. When the xsl:package element is not used explicitly, the entire stylesheet comprises a single implicit package.] (This specification does not preclude the xsl:package being embedded in another XML document, but it will never have any other XSLT element as an ancestor).

<xsl:package
  id? = id
  name? = uri
  package-version? = string〔'1'〕
  version = decimal
  input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
  declared-modes? = boolean〔'yes'〕
  default-mode? = eqname | "#unnamed"〔'#unnamed'〕
  default-validation? = "preserve" | "strip"〔'strip'〕
  default-collation? = uris
  extension-element-prefixes? = prefixes
  exclude-result-prefixes? = prefixes
  expand-text? = boolean〔'no'〕
  fixed-namespaces? = string
  schema-role? = ncname
  use-when? = expression〔true()〕
  xpath-default-namespace? = uri >
  <!-- Content: ((xsl:expose | declarations)*) -->
</xsl:package>

[Definition: The content of the xsl:package element is referred to as the package manifest].

The version attribute indicates the version of the XSLT language specification to which the package manifest conforms. The value should normally be 4.0. If the value is numerically less than 4.0, the content of the xsl:package element is processed using the rules for backwards compatible behavior (see 3.9 Backwards Compatible Processing). If the value is numerically greater than 4.0, it is processed using the rules for forwards compatible behavior (see 3.10 Forwards Compatible Processing).

A package typically has a name, given in its name attribute, which must be an absolute URI. Unnamed packages are allowed, but they can only be used as the “top level” of an application; they cannot be the target of an xsl:use-package declaration in another package.

A package may have a version identifier, given in its package-version attribute. This is used to distinguish different versions of a package. The value of the version attribute, after trimming leading and trailing whitespace, must conform to the syntax given in 3.5.1 Versions of a Package. If no version number is specified for a package, version 1 is assumed.

The attributes default-collation, default-mode, default-validation, exclude-result-prefixes, expand-text, extension-element-prefixes, use-when, version, and xpath-default-namespace are standard attributes that can appear on any XSLT element, and potentially affect all descendant elements. Their meaning is described in 3.4 Standard Attributes.

The package manifest contains the following elements, arbitrarily ordered:

1. Zero or more xsl:expose declarations that define the interface offered by this package to the outside world. An xsl:expose declaration may appear only as a child of xsl:package.

2. Zero or more additional declarations. These are the same as the declarations permitted as children of xsl:stylesheet or xsl:transform.

   Some declarations of particular relevance to packages include:

   1. The xsl:use-package declaration, which declares the names and versions of the packages on which this package depends.

   2. The optional xsl:global-context-item element; if present this element defines constraints on the existence and type of the global context item.

   3. Zero or more xsl:include and xsl:import declarations, which define additional stylesheet modules to be incorporated into this package.

   4. Zero or more ordinary declarations, that is, elements that are permitted as children of xsl:stylesheet or xsl:transform. One possible coding style is to include in the package manifest just a single xsl:import or xsl:include declaration as a reference to the effective top-level stylesheet module; this approach is particularly suitable when writing code that is required to run under releases of XSLT earlier than 3.0. Another approach is to include the substance of the top-level stylesheet module inline within the package manifest.

<xsl:package
  name="http://example.org/complex-arithmetic.xsl"
  package-version="1.0"
  version="3.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:f="http://example.org/complex-arithmetic.xsl">
  
  <xsl:function name="f:complex-number" 
                as="map(xs:integer, xs:double)" visibility="public">
    <xsl:param name="real" as="xs:double"/>
    <xsl:param name="imaginary" as="xs:double"/>
    <xsl:sequence select="{ 0: $real, 1: $imaginary }"/>
  </xsl:function>
  
  <xsl:function name="f:real" 
                as="xs:double" visibility="public">
    <xsl:param name="complex" as="map(xs:integer, xs:double)"/>
    <xsl:sequence select="$complex(0)"/>
  </xsl:function>
  
  <xsl:function name="f:imag" 
                as="xs:double" visibility="public">
    <xsl:param name="complex" as="map(xs:integer, xs:double)"/>
    <xsl:sequence select="$complex(1)"/>
  </xsl:function>
  
  <xsl:function name="f:add" 
                as="map(xs:integer, xs:double)" visibility="public">
    <xsl:param name="x" as="map(xs:integer, xs:double)"/>
    <xsl:param name="y" as="map(xs:integer, xs:double)"/>
    <xsl:sequence select="
         f:complex-number(
           f:real($x) + f:real($y), 
           f:imag($x) + f:imag($y))"/>
  </xsl:function>
  
  <xsl:function name="f:multiply" 
                as="map(xs:integer, xs:double)" visibility="public">
    <xsl:param name="x" as="map(xs:integer, xs:double)"/>
    <xsl:param name="y" as="map(xs:integer, xs:double)"/>
    <xsl:sequence select="
         f:complex-number(
           f:real($x)*f:real($y) - f:imag($x)*f:imag($y),
           f:real($x)*f:imag($y) + f:imag($x)*f:real($y))"/>
  </xsl:function>
  
  <!-- etc. -->
  
</xsl:package>

A package that does not itself expose any components may be written using a simplified syntax: the xsl:package element is omitted, and the xsl:stylesheet or xsl:transform element is now the outermost element of the stylesheet module. For compatibility reasons, all the named templates and modes declared in the package are made public. More formally, the principal stylesheet module of the top-level package may be expressed as an xsl:stylesheet or xsl:transform element, which is equivalent to the package represented by the output of the following transformation, preserving the base URI of the source:

<xsl:transform version="3.0" 
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:t="http://www.w3.org/1999/XSL/TransformAlias">
 
    <xsl:namespace-alias stylesheet-prefix="t" result-prefix="xsl"/>
    
    <xsl:template match="xsl:stylesheet|xsl:transform">
      <t:package declared-modes="no">
        <xsl:copy-of select="@*"/>
        <t:expose component="mode" names="*" visibility="public"/>
        <t:expose component="template" names="*" visibility="public"/>
        <xsl:copy-of select="node()"/>
      </t:package>
    </xsl:template>
 </xsl:transform>

The effect of the input-type-annotations attribute is defined in 4.3.1 Stripping Type Annotations from a Source Tree.

A more extensive example of a package, illustrating how components in a package can be overridden in a client package, is given in 3.5.8 Worked Example of a Library Package.

3.6 Stylesheet Modules

[Definition: A package consists of one or more stylesheet modules, each one forming all or part of an XML document.]

The principal stylesheet module of a package may take one of three forms:

• A package manifest, as described in 3.5 Packages, which is a subtree rooted at an xsl:package element

• An implicit package, which is a subtree rooted at an xsl:stylesheet or xsl:transform element. This is transformed automatically to a package as described in 3.5 Packages.

• A simplified stylesheet, which is a subtree rooted at a literal result element, as described in 3.8 Simplified Stylesheet Modules. This is first converted to an implicit package by wrapping it in an xsl:stylesheet element using the transformation described in 3.8 Simplified Stylesheet Modules, and then to an explicit package (rooted at an xsl:package element) using the transformation described in 3.5 Packages.

A stylesheet module other than the principal stylesheet module of a package may take either of two forms:

• [Definition: A standard stylesheet module, which is a subtree rooted at an xsl:stylesheet or xsl:transform element.]

• [Definition: A simplified stylesheet, which is a subtree rooted at a literal result element, as described in 3.8 Simplified Stylesheet Modules. This is first converted to a standard stylesheet module by wrapping it in an xsl:stylesheet element using the transformation described in 3.8 Simplified Stylesheet Modules.]

Whichever of the above forms a module takes, the outermost element (xsl:package, xsl:stylesheet, or a literal result element) may either be the outermost element of an XML document, or it may be a child of some (non-XSLT) element in a host document.

[Definition: A stylesheet module whose outermost element is the child of a non-XSLT element in a host document is referred to as an embedded stylesheet module. See 3.12 Embedded Stylesheet Modules.]

3.7 Stylesheet Element

<xsl:stylesheet
  id? = id
  version = decimal
  default-mode? = eqname | "#unnamed"〔'#unnamed'〕
  default-validation? = "preserve" | "strip"〔'strip'〕
  input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
  default-collation? = uris
  extension-element-prefixes? = prefixes
  exclude-result-prefixes? = prefixes
  expand-text? = boolean
  fixed-namespaces? = string
  main-module? = uri
  schema-role? = ncname
  use-when? = expression〔true()〕
  xpath-default-namespace? = uri >
  <!-- Content: (declarations) -->
</xsl:stylesheet>

<xsl:transform
  id? = id
  version = decimal
  default-mode? = eqname | "#unnamed"〔'#unnamed'〕
  default-validation? = "preserve" | "strip"〔'strip'〕
  input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
  default-collation? = uris
  extension-element-prefixes? = prefixes
  exclude-result-prefixes? = prefixes
  expand-text? = boolean〔'no'〕
  fixed-namespaces? = string
  main-module? = uri
  schema-role? = ncname
  use-when? = expression〔true()〕
  xpath-default-namespace? = uri >
  <!-- Content: (declarations) -->
</xsl:transform>

A stylesheet module is represented by an xsl:stylesheet element in an XML document. xsl:transform is allowed as a synonym for xsl:stylesheet; everything this specification says about the xsl:stylesheet element applies equally to xsl:transform.

The version attribute indicates the version of XSLT that the stylesheet module requires. The attribute is required.

[ERR XTSE0110] The value of the version attribute must be a number: specifically, it must be a valid instance of the type xs:decimal as defined in [XML Schema Part 2].

The version attribute is intended to indicate the version of the XSLT specification against which the stylesheet is written. In a stylesheet written to use XSLT 4.0, the value should normally be set to 4.0. If the value is numerically less than 4.0, the stylesheet is processed using the rules for backwards compatible behavior (see 3.9 Backwards Compatible Processing). If the value is numerically greater than 4.0, the stylesheet is processed using the rules for forwards compatible behavior (see 3.10 Forwards Compatible Processing).

The effect of the input-type-annotations attribute is described in 4.3.1 Stripping Type Annotations from a Source Tree.

The [xsl:]default-validation attribute defines the default value of the validation attribute of all relevant instructions appearing within its scope. For details of the effect of this attribute, see 25.4 Validation.

The optional main-module attribute is purely documentary. By including this attribute in every stylesheet module of a package, an XSLT editing tool may be enabled to locate the top-level module of the relevant package, and thus to gather information about all the global variables, templates, and functions available within the module being edited. This information can be used (for example) to enable auto-completion and error highlighting of the code as it is entered. Note that it may be inconvenient or misleading to use this attribute when the stylesheet module is used as a shared component within multiple stylesheets.

[ERR XTSE0120] An xsl:stylesheet, xsl:transform, or xsl:package element must not have any text node children. (This rule applies after stripping of whitespace text nodes as described in 3.13.1 Stripping Whitespace and Commentary from the Stylesheet.)

[Definition: An element occurring as a child of an xsl:package, xsl:stylesheet, xsl:transform, or xsl:override element is called a top-level element.]

[Definition: Top-level elements fall into two categories: declarations, and user-defined data elements. Top-level elements whose names are in the XSLT namespace are declarations. Top-level elements in any other namespace are user-defined data elements (see 3.7.4 User-defined Data Elements)].

The declaration elements permitted in the xsl:stylesheet element are:

xsl:accumulator
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:global-context-item
xsl:import
xsl:import-schema
xsl:include
xsl:item-type
xsl:key
xsl:mode
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:record-type
xsl:strip-space
xsl:template
xsl:use-package
xsl:variable

Note that the xsl:variable and xsl:param elements can act either as declarations or as instructions. A global variable or parameter is defined using a declaration; a local variable or parameter using an instruction.

The child elements of the xsl:stylesheet element may appear in any order. In most cases, the ordering of these elements does not affect the results of the transformation; however:

• As described in 6.6 Conflict Resolution for Template Rules, when two template rules with the same priority match the same nodes, there are situations where the order of the template rules will affect which is chosen.

• Forwards references to static variables are not allowed in static expressions.

3.9 Backwards Compatible Processing

[Definition: The effective version of an element in a stylesheet module or package manifest is the decimal value of the [xsl:]version attribute (see 3.4 Standard Attributes) on that element or on the innermost ancestor element that has such an attribute, subject to special rules for the xsl:output and xsl:fallback elements.]

These rules do not apply to the xsl:output element, whose version attribute has an entirely different purpose: it is used to define the version of the output method to be used for serialization. The effective version of an xsl:output element is the effective version of its parent element.

There are additional rules for an xsl:fallback element: see 3.10 Forwards Compatible Processing.

[Definition: An element is processed with backwards compatible behavior if its effective version is less than 4.0.]

Specifically:

• If the effective version is equal to 1.0, then the element is processed with XSLT 1.0 behavior as described in 3.9.1 XSLT 1.0 Compatibility Mode.

• If the effective version is equal to 2.0, then the element is processed with XSLT 2.0 behavior as described in 3.9.2 XSLT 2.0 Compatibility Mode.

• If the effective version is equal to 3.0, then the element is processed with XSLT 3.0 behavior as described in 3.9.3 XSLT 3.0 Compatibility Mode.

• If the effective version is any other value less than 4.0, the recommended action is to raise a static error; however, processors may recognize such values and process the element in an implementation-defined way.

  Note:

  XSLT 1.0 allowed the version attribute to take any decimal value, and invoked forwards compatible processing for any value other than 1.0. XSLT 2.0 allowed the attribute to take any decimal value, and invoked backwards compatible (i.e. 1.0-compatible) processing for any value less than 2.0. Some stylesheets may therefore be encountered that use values other than 1.0 or 2.0. In particular, the value 1.1 is sometimes encountered, as it was used at one stage in a draft language proposal.

It is implementation-defined whether a particular XSLT 4.0 implementation supports backwards compatible behavior for any XSLT version earlier than XSLT 4.0.

[ERR XTDE0160] It is a dynamic error if an element has an effective version of V (with V < 4.0) when the implementation does not support backwards compatible behavior for XSLT version V.

3.12 Embedded Stylesheet Modules

An embedded stylesheet module is a stylesheet module whose containing element is not the outermost element of the containing XML document. Both standard stylesheet modules and simplified stylesheet modules may be embedded in this way.

Two situations where embedded stylesheets may be useful are:

• The stylesheet may be embedded in the source document to be transformed.

• The stylesheet may be embedded in an XML document that describes a sequence of processing of which the XSLT transformation forms just one part.

The xsl:stylesheet element may have an id attribute to facilitate reference to the stylesheet module within the containing document.

<?xml-stylesheet type="application/xslt+xml" href="#style1"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc>
  <head>
    <xsl:stylesheet id="style1"
                    version="3.0"
                    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format">
    <xsl:import href="doc.xsl"/>
    <xsl:template match="id('foo')">
      <fo:block font-weight="bold"><xsl:apply-templates/></fo:block>
    </xsl:template>
    <xsl:template match="xsl:stylesheet">
      <!-- ignore -->
    </xsl:template>
    </xsl:stylesheet>
  </head>
  <body>
    <para id="foo">
    ...
    </para>
  </body>
</doc>

4.1 XML Versions

The XDM data model defined in [XDM 3.04.0] is capable of representing either an XML 1.0 document (conforming to [XML 1.0] and [Namespaces in XML]) or an XML 1.1 document (conforming to [XML 1.1] and [Namespaces in XML 1.1]), and it makes no distinction between the two. In principle, therefore, XSLT 4.0 can be used with either of these XML versions.

Construction of the XDM tree is outside the scope of this specification, so XSLT 4.0 places no formal requirements on an XSLT processor to accept input from either XML 1.0 documents or XML 1.1 documents or both. This specification does define a serialization capability (see 26 Serialization), though from a conformance point of view it is an optional feature. Although facilities are described for serializing the XDM tree as either XML 1.0 or XML 1.1 (and controlling the choice), there is again no formal requirement on an XSLT processor to support either or both of these XML versions as serialization targets.

Because the XDM tree is the same whether the original document was XML 1.0 or XML 1.1, the semantics of XSLT processing do not depend on the version of XML used by the original document. There is no reason in principle why all the input and output documents used in a single transformation must conform to the same version of XML.

Some of the syntactic constructs in XSLT 4.0 and XPath 3.0, for example the productions Char^XML and NCName^Names, are defined by reference to the XML and XML Namespaces specifications. There are slight variations between the XML 1.0 and XML 1.1 versions of these productions (and, indeed, between different editions of XML 1.0). Implementations may support any version; it is recommended that an XSLT 4.0 processor that implements the 1.1 versions should also provide a mode that supports the 1.0 versions. It is thus implementation-defined which versions and editions of XML and XML Namespaces are supported by the implementation.

The current version of [XML Schema 1.1 Part 2] references the XML 1.1 specifications, but the previous version ([XML Schema Part 2]) (that is, XSD 1.0) remains in widespread use, and only references XML 1.0. With processors lacking support for XSD 1.1, therefore, datatypes such as xs:NCName and xs:ID may be constrained by the XML 1.0 rules, and not allow the full range of values permitted by XML 1.1. It is recommended that implementers wishing to support XML 1.1 should consult [XML Schema 1.0 and XML 1.1] for guidance.

4.2 XDM versions

XSLT 4.0 requires a processor to support XDM 3.1 as defined in [XDM 3.1].XSLT 4.0 requires a processor to support XDM 4.0 as defined in [XDM 4.0].XSLT 4.0 requires a processor to support XDM 3.14.0 as defined in [XDM 3.14.0].

A processor may also provide a user option to support versions of XDM later than 3.1, in which case the way it does so is implementation-defined.

4.3 Preprocessing Source Documents

Source documents supplied as input to a transformation may be subject to preprocessing. Two kinds of preprocessing are defined: stripping of type annotations (see 4.3.1 Stripping Type Annotations from a Source Tree), and stripping of whitespace text nodes (see 4.3.2 Stripping Whitespace from a Source Tree).

Stripping of type annotations happens before stripping of whitespace text nodes.

The source documents to which this applies are as follows:

• The document containing the global context item if it is a node;

• Any documents containing a node present in the initial match selection;

• Any document containing a node that is returned by the functions document, doc, or collection;

• Any document read using xsl:source-document.

If a node other than a document node is supplied (for example as the global context item), then the preprocessing is applied to the entire document containing that node. If several nodes within the same document are supplied (for example as nodes in the initial match selection, or as nodes returned by the collection function), then the preprocessing is only applied to that document once. If a whitespace text node is supplied (for example as the global context item) and the rules cause this node to be stripped from its containing tree, then the behavior is as if this node had not been supplied (which may cause an error, for example if a global context item is required.)

The rules determining whether or not stripping of annotations and/or whitespace happens are defined at the level of a package. Declarations within a library package only affect the handling of documents loaded using a call on the document, doc, or collection functions or an evaluation of an xsl:source-document instruction appearing lexically within the same package. Declarations within the top-level package also affect the processing of the global context item and the initial match selection.

The semantics of the document, doc, and collection functions are formally defined in terms of mappings from URIs to document nodes maintained within the dynamic context (see 5.3.3 Initializing the Dynamic Context). The effect of the declarations that control stripping of type annotations and whitespace is therefore to modify this mapping (so it now maps the URI to a stripped document). The modification applies to the dynamic context for calls to these function appearing within a particular package; each package therefore has a different set of mappings. This means that when two calls to the doc function appear in different packages, specifying the same absolute URI, then in general different documents are returned. An implementation may return the same document for two such calls if it is able to determine that the effect of the annotation and whitespace stripping rules in both packages is the same.

The effect of dynamic calls to the document, doc, and collection functions is defined in the same way as for other functions with dependencies on the dynamic context. As described in 5.3.4 Additional Dynamic Context Components used by XSLT, named function references (such as doc#1) and calls on function-lookup (for example, function-lookup("doc", 1)) are defined to retain the XPath static and dynamic context at the point of invocation as part of the closure of the resulting function item, and to use this preserved context when a dynamic function call is subsequently made using the function item.

4.4 Attribute Types and DTD Validation

The mapping from the Infoset to the XDM data model, described in [XDM 3.0], does not retain attribute types. This means, for example, that an attribute described in the DTD as having attribute type NMTOKENS will be annotated in the XDM tree as xs:untypedAtomic rather than xs:NMTOKENS, and its typed value will consist of a single xs:untypedAtomic item rather than a sequence of xs:NMTOKEN items.The mapping from the Infoset to the XDM data model, described in [XDM 4.0], does not retain attribute types. This means, for example, that an attribute described in the DTD as having attribute type NMTOKENS will be annotated in the XDM tree as xs:untypedAtomic rather than xs:NMTOKENS, and its typed value will consist of a single xs:untypedAtomic item rather than a sequence of xs:NMTOKEN items.The mapping from the Infoset to the XDM data model, described in [XDM 3.04.0], does not retain attribute types. This means, for example, that an attribute described in the DTD as having attribute type NMTOKENS will be annotated in the XDM tree as xs:untypedAtomic rather than xs:NMTOKENS, and its typed value will consist of a single xs:untypedAtomic item rather than a sequence of xs:NMTOKEN items.

Attributes with a DTD-derived type of ID, IDREF, or IDREFS will be marked in the XDM tree as having the is-id or is-idrefs properties. It is these properties, rather than any type annotation, that are examined by the functions id and idref described in [Functions and Operators 4.0].

4.6 Limits

The XDM data model (see [XDM 3.04.0]) leaves it to the host language to define limits. This section describes the limits that apply to XSLT.

Limits on some primitive datatypes are defined in [XML Schema Part 2]. Other limits, listed below, are implementation-defined. Note that this does not necessarily mean that each limit must be a simple constant: it may vary depending on environmental factors such as available resources.

The following limits are implementation-defined:

1. For the xs:decimal type, the maximum number of decimal digits (the totalDigits facet). This must be at least 18 digits. (Note, however, that support for the full value range of xs:unsignedLong requires 20 digits.)

2. For the types xs:date, xs:time, xs:dateTime, xs:gYear, and xs:gYearMonth: the range of values of the year component, which must be at least +0001 to +9999; and the maximum number of fractional second digits, which must be at least 3.

3. For the xs:duration type: the maximum absolute values of the years, months, days, hours, minutes, and seconds components.

4. For the xs:yearMonthDuration type: the maximum absolute value, expressed as an integer number of months.

5. For the xs:dayTimeDuration type: the maximum absolute value, expressed as a decimal number of seconds.

6. For the types xs:string, xs:hexBinary, xs:base64Binary, xs:QName, xs:anyURI, xs:NOTATION, and types derived from them: the maximum length of the value.

7. For sequences, the maximum number of items in a sequence.

5.1 Names

5.2 Expressions

XSLT uses the expression language defined by XPath 4.0 [XPath 4.0]. Expressions are used in XSLT for a variety of purposes including:

• selecting nodes for processing;

• specifying conditions for different ways of processing a node;

• generating text to be inserted in a result tree.

[Definition: Within this specification, the term XPath expression, or simply expression, means a string that matches the production Expr^XP defined in [XPath 4.0].]

XPath expressions may occur:

• As the value of certain attributes on XSLT-defined instructions (for example, the select attribute of the xsl:apply-templates instruction)

• Within curly brackets in attribute value templates and text value templates.

• As the content of a text node within an xsl:select instruction.

In the above cases, the static processing (compilation) of XPath expressions takes place at the same time as the static processing of the stylesheet itself, while evaluation of the XPath expressions takes place dynamically during stylesheet evaluation. There are also, however:

• XPath expressions where both the static processing and dynamic evaluation of the XPath expression takes place during static processing of the stylesheet. These are referred to as static expressions, and they perform the same function as preprocessing directives in other languages.

• XPath expressions that are dynamically constructed (as character strings): both the static processing and dynamic evaluation of these expressions occurs during stylesheet evaluation. See ???.

In general:

• It is a static error if an XPath expression does not match the XPath production Expr^XP, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope. Error codes are defined in [XPath 4.0].

• The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error. Error codes are defined in [XPath 4.0].

• The transformation fails with a type error if an XPath expression raises a type error, or if the result of evaluating the XPath expression is evaluated and raises a type error, or if the XPath processor raises a type error during static analysis of an expression. Error codes are defined in [XPath 3.0][xpath-30].

There are some exceptions to these rules, for example:

• Static errors may be suppressed where forwards compatible behavior is enabled (see 3.10 Forwards Compatible Processing).

• Dynamic errors may be caught using xsl:try and xsl:catch.

• Dynamic errors evaluating a predicate within a pattern do not cause the transformation to fail, they merely cause the pattern not to match.

[Definition: The context within a stylesheet where an XPath expression appears may specify the required type of the expression. The required type indicates the type of the value that the expression is expected to return.] If no required type is specified, the expression may return any value: in effect, the required type is then item()*.

[Definition:  The term coercion rules means the coercion rules defined in [XPath 4.0], applied unless otherwise specified with XPath 1.0 compatibility mode set to false.]

This specification also invokes the XPath coercion rules to convert the result of evaluating an XSLT sequence constructor to a required type (for example, the sequence constructor enclosed in an xsl:variable, xsl:template, or xsl:function element).

Any dynamic error or type error that occurs when applying the coercion rules to convert a value to a required type results in the transformation failing, in the same way as if the error had occurred while evaluating an expression.

The XPath specification states (see Section A.3.3 End-of-Line Handling^XP) that the host language must specify whether the XPath processor normalizes all line breaks on input, before parsing, and if it does so, whether it uses the rules of [XML 1.0] or [XML 1.1]. In the case of XSLT, all handling of line breaks is the responsibility of the XML parser (which may support either XML 1.0 or XML 1.1); the XSLT and XPath processors perform no further changes.The XPath specification states (see [XPath 4.0] section A.3.3 End-of-Line Handling) that the host language must specify whether the XPath processor normalizes all line breaks on input, before parsing, and if it does so, whether it uses the rules of [XML 1.0] or [XML 1.1]. In the case of XSLT, all handling of line breaks is the responsibility of the XML parser (which may support either XML 1.0 or XML 1.1); the XSLT and XPath processors perform no further changes.The XPath specification states (see [XPath 4.0] section Section A.3.3 End-of-Line HandlingXP) that the host language must specify whether the XPath processor normalizes all line breaks on input, before parsing, and if it does so, whether it uses the rules of [XML 1.0] or [XML 1.1]. In the case of XSLT, all handling of line breaks is the responsibility of the XML parser (which may support either XML 1.0 or XML 1.1); the XSLT and XPath processors perform no further changes.

5.3 The Static and Dynamic Context

XPath defines the concept of an expression context^XP which contains all the information that can affect the result of evaluating an expression. The expression context has two parts, the static context^XP, and the dynamic context^XP. The components that make up the expression context are defined in the XPath specification (see Section 2.2 Expression Context^XP). This section describes the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.XPath defines the concept of an expression context^XP which contains all the information that can affect the result of evaluating an expression. The expression context has two parts, the static context^XP, and the dynamic context^XP. The components that make up the expression context are defined in the XPath specification (see [XPath 4.0] section 2.2 Expression Context). This section describes the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.XPath defines the concept of an expression context^XP which contains all the information that can affect the result of evaluating an expression. The expression context has two parts, the static context^XP, and the dynamic context^XP. The components that make up the expression context are defined in the XPath specification (see [XPath 4.0] section Section 2.2 Expression ContextXP). This section describes the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.

This section does not apply to static expressions (whose context is defined in 9.7 Static Expressions), nor to XPath expressions evaluated using xsl:evaluate (whose context is defined in 10.5.2 Dynamic context for the target expression). [XSLT 3.0 Erratum E24, bug 30241]

As well as providing values for the static and dynamic context components defined in the XPath specification, XSLT defines additional context components of its own. These context components are used by XSLT instructions (for example, xsl:next-match and xsl:apply-imports), and also by the functions in the extended function library described in this specification.

The following four sections describe:

5.3.1 Initializing the Static Context
5.3.2 Additional Static Context Components used by XSLT
5.3.3 Initializing the Dynamic Context
5.3.4 Additional Dynamic Context Components used by XSLT

5.4 Named Types

XSLT 4.0 introduces two new and closely-related constructs allowing item types to be given names, and to be referred to by name anywhere that item types are used, for example in function declarations and variable declarations.

The xsl:item-type declaration allows any item type to be given a name. It is particularly useful to avoid repetitive use of the same choice types, enumeration types, or function types, and means that if the definition changes, the change only needs to be made in one place.

The xsl:record-type declaration takes this a step further. Like xsl:item-type, it allows a name to be given to any record type. In addition, though, it offers two further capabilities:

• Named record types can be recursive, allowing definitions of recursive data structures such as lists and trees.

• Declaring a named record type automatically establishes a constructor function for records of that type; the constructor function has the same name as the record type itself.

<xsl:record-type name="cx:complex">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double"/>
</xsl:record-type>
   
<xsl:variable name="i" as="cx:complex" select="cx:complex(0, 1)"/>
   
<xsl:function name="cx:add" as="cx:complex">
  <xsl:param name="x" as="cx:complex"/>
  <xsl:param name="y" as="cx:complex"/>
  <xsl:sequence select="cx:complex($x?r + $y?r, $x?i + $y?i)"/>
</xsl:function>

<xsl:template match="xsl:record-type" expand-text="yes">
   <t:item-type name="{@name}"
                visibility="{@visibility otherwise 'private'}">
     <xsl:attribute name="as">
        <xsl:text>record(</xsl:text>
        <xsl:for-each select="xsl:field" separator=", ">
           <xsl:variable name="optional"
                         as="xs:boolean"
                         select="normalize-space(@required) = ('no','false','0')"/>
           {@name}{'?'[$optional]} as {@as otherwise 'item()*'}
        </xsl:for-each>
        <xsl:if test="normalize-space(@extensible) = ('yes','true','1')">
           <xsl:text>, *</xsl:text>
        </xsl:if>
        <xsl:text>)</xsl:text>
      </xsl:attribute>  
   </t:item-type>
</xsl:template>

<xsl:record-type name="cx:complex" extensible="yes">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no" default="0"/>
</xsl:record-type>

<xsl:item-type name="cx:complex"
       as="record(r as xs:double, i? as xs:double, *)"/>

<xsl:template match="xsl:record-type">
    <t:function name="{@name}"
                as="{@name}"
                visibility="{(@visibility otherwise 'private')}">
                
      <!-- if the record type is extensible, choose a name for the options parameter -->
      <xsl:variable name="options-param" as="xs:string?">
         <xsl:if test="normalize-space(@extensible) = ('yes', 'true', 'a')"
                 then="('options', (1 to count(xsl:field)) ! `options{.}`)
                         [not(. = current()/xsl:field/@name)][1]"/>
      </xsl:variable>                   
      
      <!-- declare the parameters -->
      <xsl:for-each select="xsl:field">
         <t:param name="{@name}"
                  required="{@required otherwise 'yes'}">
            <xsl:attribute name="as">
               <xsl:variable name="as" 
                             select="normalize-space(@as otherwise 'item()*')"/>
               <xsl:variable name="optional" 
                             select="normalize-space(@required) = ('no', 'false', '0')"/>
               <xsl:choose>
                  <xsl:when test="not($optional)" select="$as"/>
                  <!-- for optional fields, amend the required type to allow () -->
                  <xsl:when test="matches($as, '[?*]$')" select="$as"/>
                  <xsl:when test="matches($as, '\+$')" select="replace($as, '\+$', '*')"/>
                  <xsl:otherwise select="$as || '?'"/>
               </xsl:choose>
            </xsl:attribute>
            <xsl:if test="@default">
               <xsl:attribute name="select" select="@default"/>
            </xsl:if>   
         </t:param>
      </xsl:for-each>
      
      <!-- for an extensible record type, declare the options parameter -->
      <xsl:if test="exists($options-param)">
         <t:param name="{$options-param}" as="map(*)" required="no" select="{}"/>
      </xsl:if>           
      
      <!-- function body: construct a map -->
      <t:map duplicates="fn($first, $second){{$first}}">
         <xsl:for-each select="xsl:field">
            <xsl:variable name="optional" 
                          select="normalize-space(@required) = ('no', 'false', '0')"/>
            <xsl:choose>
              <xsl:when test="$optional and not(@default)">
                 <!-- omit map entries for optional fields if no value is supplied -->
                 <t:if test="exists(${@name})">
                    <t:map-entry key="'{@name}'" select="${@name}"/>
                 </t:if>
              </xsl:when>
              <xsl:otherwise>
                <t:map-entry key="'{@name}'" select="${@name}"/>
              </xsl:otherwise>  
            </xsl:choose>  
         </xsl:for-each>
        
         <!-- if the record type is extensible, 
              add entries from the options parameter -->
              
         <xsl:if test="exists($options-param)">
            <t:sequence select="${$options-param}"/>
         </xsl:if>   

      </t:map>
    </t:function>          
</xsl:template>

<xsl:record-type name="cx:complex">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no" default="0"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="private">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double" required="no" select="0"/>
    <xsl:map>
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:map-entry key="'i'" select="$i"/>
    </xsl:map>
</xsl:function>

<xsl:record-type name="cx:complex" visibility="public">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double" required="no"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="public">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double?" required="no"/>
    <xsl:map>
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:if test="exists($i)">
          <xsl:map-entry key="'i'" select="$i"/>
       </xsl:if>   
    </xsl:map>
</xsl:function>

<xsl:record-type name="cx:complex" extensible="yes">
    <xsl:field name="r" as="xs:double"/>
    <xsl:field name="i" as="xs:double"/>
</xsl:record-type>

<xsl:function name="cx:complex" as="cx:complex" visibility="private">
    <xsl:param name="r" as="xs:double"/>
    <xsl:param name="i" as="xs:double"/>
    <xsl:param name="options" as="map(*)" required="no" default="{}"/>
    <xsl:map duplicates="fn($first, $second){$first}">
       <xsl:map-entry key="'r'" select="$r"/>
       <xsl:map-entry key="'i'" select="$i"/>
       <xsl:sequence select="$options"/>   
    </xsl:map>
</xsl:function>

<xsl:record-type name="my:binary-tree">
   <xsl:field name="left" as="my:binary-tree?"/>
   <xsl:field name="payload" as="item()*"/>
   <xsl:field name="right" as="my:binary-tree?"/>
   <xsl:field name="depth" as="fn(my:binary-tree) as xs:integer"
      default="fn {1 + max((?left ?> depth(), ?right ?> depth())) otherwise 0)}"/>
</xsl:record-type>