View Old View New View Both View Only Previous Next

This draft contains only sections that have differences from the version that it modified.

W3C

XSL Transformations (XSLT) Version 4.0

W3C Editor's Draft 23 February 2026

This version:
https://qt4cg.org/specifications/xslt-40/
Latest version:
https://qt4cg.org/specifications/xslt-40/
Most recent Recommendation of XSL Transformations (XSLT):
https://www.w3.org/TR/xslt-30/
Editor:
Michael Kay, Saxonica <http://www.saxonica.com/>

The following associated resources are available: Specification in XML format, XSD 1.1 Schema for XSLT 4.0 Stylesheets (non-normative), Relax-NG Schema for XSLT 4.0 Stylesheets (non-normative), Stylesheet for XML-to-JSON conversion (non-normative)

Copyright © 2026 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

Abstract

This specification defines the syntax and semantics of XSLT 4.0, a language designed primarily for transforming XML documents into other XML documents.

XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation [XSLT 3.0] published on 8 June 2017. Changes are presented in 1.2 What’s New in XSLT 4.0?.

XSLT 4.0 is designed to be used in conjunction with XPath 4.0, which is defined in [XPath 4.0]. XSLT shares the same data model as XPath 4.0, which is defined in [XDM 3.0], and it uses the library of functions and operators defined in [Functions and Operators 4.0]. XPath 4.0 and the underlying function library introduce a number of enhancements, for example the availability of union and record types.

This document contains hyperlinks to specific sections or definitions within other documents in this family of specifications. These links are indicated visually by a superscript identifying the target specification: for example XP for XPath 4.0, DM for the XDM data model version 4.0, FO for Functions and Operators version 4.0.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document has no official standing. It is produced by the editor as a proposal for community review. Insofar as it copies large amounts of text from the W3C XSLT 3.0 Recommendation, W3C copyright and similar provisions apply.

Dedication

The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).

6 Template Rules

Template rules define the processing that can be applied to items that match a particular pattern.

6.9 Overriding Template Rules

Changes in 4.0 ⬇ ⬆

  1. The xsl:apply-imports and xsl:next-match instructions automatically pass supplied parameters to the overridden template rule.   [Issue 1861 ]

<!-- Category: instruction -->
<xsl:apply-imports>
  <!-- Content: xsl:with-param* -->
</xsl:apply-imports>

<!-- Category: instruction -->
<xsl:next-match>
  <!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:next-match>

A template rule that is being used to override another template rule (see 6.5 Conflict Resolution for Template Rules) can use the xsl:apply-imports or xsl:next-match instruction to invoke the overridden template rule. The xsl:apply-imports instruction only considers template rules in imported stylesheet modules; the xsl:next-match instruction considers all template rules that have not already been used. Both instructions will invoke the built-in template rule for the context item (see 6.8 Built-in Template Rules) if no other template rule is found.

[Definition: At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen as a result of evaluating xsl:apply-templates, xsl:apply-imports, or xsl:next-match, the template rule becomes the current template rule for the evaluation of the rule’s sequence constructor.]

The current template rule is cleared (becomes absent) by any instruction that evaluates an operand with changed focus. It is therefore cleared when evaluating instructions contained within:

Note:

The current template rule is not affected by invoking named attribute sets (see 10.2 Named Attribute Sets), or named templates (see 10.1 Named Templates) unless <xsl:context-item use="absent"/> is specified. While evaluating a global variable or the default value of a stylesheet parameter (see 9.5 Global Variables and Parameters) the current template rule is absent.

These rules ensure that when xsl:apply-imports or xsl:next-match is called, the context item is the same as when the current template rule was invoked.

Both xsl:apply-imports and xsl:next-match search for a template rule that matches the context item, and that is applicable to the current mode (see 6.7 Modes). In choosing a template rule, they use the usual criteria such as the priority and import precedence of the template rules, but they consider as candidates only a subset of the template rules in the stylesheet. This subset differs between the two instructions:

  • The xsl:apply-imports instruction considers as candidates only those template rules contained in stylesheet levels that are descendants in the import tree of the stylesheet level that contains the current template rule.

    Note:

    This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.

    [ERR XTSE3460] It is a static error if an xsl:apply-imports element appears in a template rule declared within an xsl:override element. (To invoke the template rule that is being overridden, xsl:next-match should therefore be used.)

  • The xsl:next-match instruction considers as candidates all those template rules that come after the current template rule in the ordering of template rules implied by the conflict resolution rules given in 6.5 Conflict Resolution for Template Rules.

    This process could be implemented by the following algorithm:

    1. Set a flag active to false.

    2. Follow the rules in 6.5 Conflict Resolution for Template Rules to find the best matching rule, without raising any errors or warnings if there are multiple matches.

    3. If the template rule identified is the current template rule, discard this rule, and repeat the process from step 2 with the flag active set to true.

    4. Otherwise, if active is set to false, discard this rule, and repeat the process from step 2, with the flag active still set to false

    5. Otherwise (if active is set to true) use the selected rule.

    Note:

    An alternative implementation would be to maintain, not just the current template rule, but a list of rules that have been used to process the context item. The implementation of xsl:next-match can then eliminate these rules from the search.

    In the absence of type patterns, it is possible to define a total ordering of template rules for each mode, and to exclude those rules that appear before the current template rule in this ordering. The introduction of type patterns makes this approach more challenging, since types are partially ordered.

    Note:

    Because a template rule declared as a child of xsl:override has higher precedence than any template rule declared in the used package (see 3.5.4 Overriding Template Rules from a Used Package), the effect of xsl:next-match within such a template rule is to consider as candidates first any other template rules for the same mode within the same xsl:use-package element (taking into account explicit and implicit priority, and document order, in the usual way), and then all template rules in the used package.

If no matching template rule is found, both xsl:apply-imports and xsl:next-match cause the built-in template rule for the mode to be invoked.

If multiple matching template rules with the same explicit or implicit priority are found, both xsl:apply-imports and xsl:next-match respect the on-multiple-match and warning-on-multiple-match attributes of the mode declaration.

Note:

If is entirely possible for xsl:apply-templates to identify a template rule unambiguously, and for xsl:apply-imports or xsl:next-match then to fail because there is no unambiguous second-choice template rule.

If a matching template rule R is found, then the result of the xsl:next-match or xsl:apply-imports instruction is the result of invoking R. The parameters that are passed to R are as follows:

Note:

The implicit passing of non-tunnel parameters is new in XSLT 4.0, and happens only if [xsl:]version is set to 4.0 (or greater) on the instruction, or on some ancestor element in the stylesheet. There may be cases where this change introduces a backward incompatibility: specifically, if the invoked template rule declares a default value for an optional parameter, it will now take the implicitly passed value rather than the default value. The 3.0 behavior can be therefore be retained by setting version="3.0" on the xsl:next-match or xsl:apply-imports instruction.

The template rule R is evaluated with the same focus as the xsl:next-match or xsl:apply-imports instruction. The current template rule changes to be R. The current mode does not change.

Note:

In the case where the current template rule T is declared within an xsl:override element in a using package P, while the selected rule R is declared within a different package Q, and where the current mode is MP (mode M in package P), the effect is that the current mode for evaluation of R remains MP rather than reverting to its corresponding mode MQ (mode M in package Q). If R contains an xsl:apply-templates instruction that uses mode="#current", then the set of template rules considered by this instruction will therefore include any overriding template rules declared in P as well as the original rules declared in Q.

If no matching template rule is found that satisfies these criteria, the built-in template rule for the context item is used (see 6.8 Built-in Template Rules).

[ERR XTDE0560] It is a dynamic error if xsl:apply-imports or xsl:next-match is evaluated when the current template rule is absent.

Example: Using xsl:apply-imports

For example, suppose the stylesheet doc.xsl contains a template rule for example elements:

<xsl:template match="example">
  <pre><xsl:apply-templates/></pre>
</xsl:template>

Another stylesheet could import doc.xsl and modify the treatment of example elements as follows:

<xsl:import href="doc.xsl"/>

<xsl:template match="example">
  <div style="border: solid red">
     <xsl:apply-imports/>
  </div>
</xsl:template>

The combined effect would be to transform an example into an element of the form:

<div style="border: solid red"><pre>...</pre></div>

An xsl:fallback instruction appearing as a child of an xsl:next-match instruction is ignored by an XSLT 2.0 or 3.0 processor, but can be used to define fallback behavior when the stylesheet is processed by an XSLT 1.0 processor with forwards compatible behavior.

27 Conformance

Changes in 4.0 ⬆

  1. The higher-order-function feature no longer exists; higher-order functions are now a core part of XSLT, no longer an optional extra.   [Issue 205 PR 326 1 February 2023]

A processor that claims conformance with this specification must satisfy the conformance requirements for a basic XSLT processor and for each of the optional features with which it claims conformance.

The following optional features are defined:

  1. The schema-awareness feature, defined in 27.2 Schema-Awareness Conformance Feature

  2. The serialization feature, defined in 27.3 Serialization Feature

  3. The backwards compatibility feature, defined in 27.4 Compatibility Features

  4. The streaming feature, defined in 27.5 Streaming Feature.

  5. The dynamic evaluation feature, defined in 27.6 Dynamic Evaluation Feature.

A processor that does not claim conformance with an optional feature must satisfy the requirements for processors that do not implement that feature.

An XSLT processor takes as its inputs a stylesheet and zero or more XDM trees conforming to the data model defined in [XDM 3.0]. It is not required that the processor supports any particular method of constructing XDM trees, but conformance can only be tested if it provides a mechanism that enables XDM trees representing the stylesheet and primary source document to be constructed and supplied as input to the processor.

The output of the XSLT processor consists of zero or more final result trees. It is not required that the processor supports any particular method of accessing a final result tree, but if it does not support the serialization feature, conformance can only be tested if it provides some alternative mechanism that enables access to the results of the transformation.

Certain facilities in this specification are described as producing implementation-defined results. A claim that asserts conformance with this specification must be accompanied by documentation stating the effect of each implementation-defined feature. For convenience, a non-normative checklist of implementation-defined features is provided at F Checklist of Implementation-Defined Features.

A conforming processormust raise any static error occurring in the stylesheet, or in any XPath expression, except where specified otherwise either for individual error conditions or under the general provisions for forwards compatible behavior (see 3.10 Forwards Compatible Processing). After raising such an error, the processor may continue for the purpose of raising additional errors, but must terminate abnormally without performing any transformation.

When a dynamic error occurs during the course of a transformation, and is not caught using xsl:catch, the processor must raise it and must eventually terminate abnormally.

Some errors, notably type errors, may be treated as static errors or dynamic errors at the discretion of the processor.

A conforming processor may impose limits on the processing resources consumed by the processing of a stylesheet.

A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

Some of the optional features are defined in such a way that if the feature is not provided, the data model is constrained to exclude certain kinds of item. For example:

[ERR XTDE1665] A dynamic errormay be raised if the input to the processor includes an item that requires availability of an optional feature that the processor does not provide.

Note:

It is not necessarily possible to trigger this error. A processor that does not provide an optional feature might not define or recognize any representation of the items that are disallowed. The error code is provided for use in cases where a processor is able to interoperate with other software that does not have the same constraints — for example, where a package compiled with a non-schema-aware processor is able to invoke functions in a package that was compiled with a schema-aware processor. Even in that case, processors have the option of filtering or converting the input so that it meets the relevant constraints: for example, a non-schema-aware processor when presented with a schema-validated document in the form of a PSVI might simply ignore the properties it does not understand.

The dynamic error is optional: for example a processor might report no error if the offending item is not actually used.

The phrase input to the processor is deliberately wide: it includes (inter alia) the global context item, items present in the initial match selection, items passed as stylesheet parameters, items returned by functions such as document, doc, and collection, items returned by extension functions and extension instructions, items supplied in function or template parameters or results across package boundaries, and nodes reachable from any of the above by axis navigation.

27.4 Compatibility Features

[Definition: A processor that claims conformance with the XSLT 1.0 compatibility featuremust support the processing of stylesheet instructions and XPath expressions with XSLT 1.0 behavior, as defined in 3.9 Backwards Compatible Processing.]

Note that a processor that does not claim conformance with the XSLT 1.0 compatibility featuremust raise a dynamic error if an instruction is evaluated whose effective version is 1.0. [see ERR XTDE0160].

Note:

The reason this is a dynamic error rather than a static error is to allow stylesheets to contain conditional logic, following different paths depending on whether the XSLT processor implements XSLT 1.0, 2.0, or 3.0. The selection of which path to use can be controlled by using the system-property function to test the xsl:version system property.

A processor that claims conformance with the XSLT 1.0 compatibility featuremust permit the use of the namespace axis in XPath expressions when backwards compatible behavior is enabled. In all other circumstances, support for the namespace axis is optional.

Note:

There are no incompatibilities between 3.0 and 2.0 that would justify a 2.0-compatibility mode. When a 3.0 processor encounters a stylesheet that specifies version="2.0", evaluation therefore proceeds exactly as if it specified version="3.0". However, a software product may invoke an XSLT 2.0 processor in preference to an XSLT 3.0 processor when the stylesheet specifies version="2.0", in which case any use of new 3.0 constructs will be rejected.

There are cases where setting [xsl:]version to a value less than 4.0 affects the behavior of an XSLT 4.0 stylesheet: see J Incompatibilities with XSLT 3.0. However these are sufficiently minor that they do not warrant the introduction of a separate conformance option.

J Incompatibilities with XSLT 3.0 (Non-Normative)

This section lists all known incompatibilities with XSLT 3.0, that is, situations where a stylesheet that is error-free according to the XSLT 3.0 specification and where all elements have an effective version of 3.0 or less, will produce different results depending on whether it is run under an XSLT 3.0 processor or an XSLT 4.0 processor.

  1. The rules for comparing values in xsl:for-each-group now reference the rules for distinct-values, which have themselves changed to be compatible with fn:atomic-equal. This change eliminates the intransitivity in the previous specification, which meant that in edge cases involving rounding of numeric values of different types, two items in different groups could compare equal. Any change in behavior is confined to this edge case.

  2. The rules for matching nodes against patterns using the intersect and except operators have changed to deliver a more intuitive result.

  3. The rules for comparing values in keys have changed, to align with the rules for maps. The changes affect edge cases involving rounding of numeric values of different types, and the comparison of date/time values with and without timezones.

  4. In previous versions, a template rule whose match pattern was a union pattern and that had no explicity priority was treated as equivalent to a set of template rules, one for each alternative in the union, each potentially with different default priority. This rule has not been carried forward into XSLT 4.0: instead, the priority of the rule is taken as being the highest priority of any of the alternatives.

  5. In XSLT 4.0, an xsl:apply-imports or xsl:next-match instruction automatically passes on the values of any non-tunnel parameters that were present in its own invocation. This means that the template rule invoked by xsl:apply-imports or xsl:next-match, if it declares a default value for such a parameter, will take the explicitlyimplicitly-supplied value in preference to the default value.

    This change in the specification applies only if the effective version of the xsl:apply-imports or xsl:next-match is 4.0 or greater. This means that 3.0 behavior can be retained by adding the attribute version="3.0" to the instruction, or to some ancestor element (for example, the xsl:stylesheet or xsl:transform element).

This specification also corrects a number of errors and omissions in XSLT 3.0, in a way that might create incompatibilities for some processors, depending on how they interpreted the XSLT 3.0 specification:

  1. XSLT 3.0 (and earlier releases) did not fully define the evaluation context for the default values of template parameters. For example, if the default value of a parameter of a template rule invoked xsl:next-match, it was not specified whether the current template rule should be the calling template or the called template. This omission has been corrected.

  2. Where different packages import different schemas, the specification is now more prescriptive about which schema is used for validation. The rules may differ from the conventions adopted by implementations of XSLT 3.0.

  3. XSLT 3.0 failed to specify a default value for the serialization parameter indent where the serialization method is json or adaptive. XSLT 4.0 specifies a default value of no.

See also [XPath 4.0], [Functions and Operators 4.0], and [XSLT and XQuery Serialization 4.0] for incompatibilities in other related specifications that may affect XSLT stylesheets.