XSL Transformations (XSLT) Version 4.0

3 Stylesheet Structure

This section describes the overall structure of a stylesheet as a collection of XML documents.

[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 >  </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:

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.
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.

Example: An example package

The following example shows a package that offers a number of functions for manipulating complex numbers. A complex number is represented as a map with two entries, the keys being 0 for the real part, and 1 for the imaginary part.

<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 more complex package might include private or abstract functions as well as public functions; it might expose components other than functions (for example, templates or global variables), and it might contain xsl:use-package elements to allow it to call on the services of other packages.

Note:

In this example, the way in which complex numbers are represented is exposed to users of the package. It would be possible to hide the representation by declaring the types on public functions simply as item(); but this would be at the cost of type safety.

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.5.4 Named Components in Packages

This section discusses the use of named components in packages.

The components which can be declared in one package and referenced in another are: functions, named templates, attribute sets, modes, and global variables and parameters.

In addition, keys and accumulators are classified as named components because they can contain references to components in another package, even though they cannot themselves be referenced from outside the package.

Named and unnamed modes come within the scope of this section, but there are differences noted in 3.5.5 Overriding Template Rules from a Used Package.

Not all declarations result in components:

Named declarations that can neither be referenced from outside their containing package, nor can contain references to components in other packages (examples are xsl:output, xsl:character-map, and xsl:decimal-format) are not considered to be components and are therefore outside the scope of this section.
Some declarations, such as xsl:decimal-format and xsl:strip-space, declare aspects of the processing context which are not considered to be components as defined here.
Template rules (xsl:template with a match attribute) are also not considered to be components for the purposes of this section, which is concerned only with components that are bound by name. However, when an xsl:template has both a match attribute and a name attribute, then it establishes both a template rule and a named template, and in its role as a named template it comes within the scope of this discussion.
A named declaration, for example a named template, a function, or a global variable, may be overridden within the same package by another like-named declaration having higher import precedence. When a declaration is overridden in this way it cannot be referenced by name either from within its containing package or from outside that package.
In the case of xsl:attribute-set and xsl:key declarations, several declarations combine to form a single component.

The section is largely concerned with details of the rules that affect references from one component to another by name, whether the components are in the same package or in different packages. The rules are designed to meet a number of requirements:

A component defined in one package can be overridden by a component in another package, provided the signatures are type-compatible.
The author of a package can declare whether the components in the package are public or private (that is, whether or not they can be used from outside the package) and whether they are final, overridable, or abstract (that is whether they can or must be overridden by the using package).
Within an application, two packages can make use of a common library and override its components in different ways.
Visibility of components can be defined either as part of the declaration of the component, or in the package manifest.
An application that wishes to make use of a library package can be selective about which components from the library it acquires, perhaps to avoid name clashes between components acquired from different libraries.

[Definition: The term component is used to refer to any of the following: a stylesheet function, a named template, a mode, an accumulator, an attribute set, a key, global variable, or a mode.]

[Definition: The symbolic identifier of a component is a composite name used to identify the component uniquely within a package. The symbolic identifier comprises the kind of component (stylesheet function, named template, accumulator, attribute set, global variable, key, or mode), the expanded QName of the component (namespace URI plus local name), and in the case of stylesheet functions, the upper bound of the arity range.]

Note:

In the case of the unnamed mode, the expanded QName of the component may be considered to be some system-allocated name different from any user-defined mode name.

[Definition: Two components are said to be homonymous if they have the same symbolic identifier.]

Every component has a declaration in some stylesheet module and therefore within some package. In the case of attribute sets and keys, there may be several declarations. The declaration is an element in an XDM tree representing the stylesheet module. Declarations therefore have identity, based on XDM node identity.

[Definition: The declaring package of a component is the package that contains the declaration (or, in the case of xsl:attribute-set and xsl:key, multiple declarations) of the component.]

When a component declared in one package is made available in another, the using package will contain a separate component that can be regarded as a modified copy of the original. The new component shares the same symbolic identifier as the original, and it has the same declaration, but it has other properties such as its visibility that may differ from the original.

[Definition: A component declaration results in multiple components, one in the package in which the declaration appears, and potentially one in each package that uses the declaring package, directly or indirectly, subject to the visibility of the component. Each of these multiple components has the same declaring package, but each has a different containing package. For the original component, the declaring package and the containing package are the same; for a copy of a component made as a result of an xsl:use-package declaration, the declaring package will be the original package, and the containing package will be the package in which the xsl:use-package declaration appears.]

Note:

Within this specification, we generally use the notation C_P for a component named C whose declaring package and containing package are both P; and the notation C_PQ for a component whose containing package is P and whose declaring package is Q (that is, a component in P that is derived from a component C_Q in the used package Q).

The properties of a component are as follows:

The original declaration of the component.
The package to which the component belongs (called its containing package, not to be confused with the declaring package).
The symbolic identifier of the component.
The visibility of the component, which determines the way in which the component is seen by other components within the same package and within using packages. This is one of public, private, abstract, final, or hidden. The visibility of components is discussed further in 3.5.4.1 Visibility of Components.
A set of bindings for the symbolic references in the component. The way in which these bindings are established is discussed further in 3.5.4.5 Binding References to Components.

Note:

When a function F defined in a package P is acquired by two using packages Q and R, we may think of P, Q, and R as all providing access to the “same” function. The detailed semantics, however, demand an understanding that there is one function declaration, but three components. The three components representing the function F within packages P, Q, and R have some properties in common (the same symbolic identifier, the same declaration), but other properties (the visibility and the bindings of symbolic references) that may vary from one of these components to another.

[Definition: The declaration of a component includes constructs that can be interpreted as references to other components by means of their symbolic identifiers. These constructs are generically referred to as symbolic references. Examples of constructs that give rise to symbolic references are the name attribute of xsl:call-template; the [xsl:]use-attribute-sets attribute of xsl:copy, xsl:element, and literal result elements; the explicit or implicit mode attribute of xsl:apply-templates; XPath variable references referring to global variables; XPath static function calls (including partial function applications) referring to stylesheet functions; and named function references (example: my:f#1) referring to stylesheet functions. ]

Symbolic references exist as properties of the declaration of a component. The symbolic identifier being referred to can be determined straightforwardly from the syntactic form and context of the reference: for example, the instruction <xsl:value-of select="f:price($o)" xmlns:f="http://f.com/"/> contains a symbolic reference to a function with expanded name {http://f.com/}price and with arity=1. However, because there may be several (homonymous) function components with this symbolic identifier, translating this symbolic reference into a reference to a specific component (a process called “binding”) is less straightforward, and is described in the text that follows.

The process of assembling a stylesheet from its constituent packages is primarily a process of binding these symbolic references to actual components. Within any component whose declaration is D, there is a set of bindings; each binding is an association between a symbolic reference in D and a component whose symbolic identifier matches the outward reference. Outward references for which a component C contains a binding are said to be bound in C; those for which C contains no binding are said to be unbound.

For example, suppose that in some package Q, function A calls B, which in turn calls C, and that B is private. Now suppose that in some package P which uses Q, C is overridden. The effect of the binding process is that P will contain three components corresponding to A, B, and C, which we might call A_P, B_P, and C_P. The declarations of A_P and B_P are in package Q, but the declaration of C_P is in P. The internal visibility of B_P will be hidden (meaning that it cannot be referenced from within P), and B_P will contain a binding for the component C_P that corresponds to the outward reference from B to C. The effect is that when A calls B and B calls C, it is the overriding version of C that is executed.

In another package R that uses Q without overriding C, there will be three different components A_R, B_R, and C_R. This time the declaration of all three components is in the original package Q. Component B_R will contain a binding to C_R, so in this package, the original version of C is executed. The fact that one package P overrides C thus has no effect on R, which does not override it.

The binding process outlined above is described in more detail in 3.5.4.5 Binding References to Components.

Template rules are not components in their own right; unlike named templates, they are never referenced by name. Component references within a template rule (for example, references to functions, global variables, or named templates) are treated as occurring within the component that represents the containing mode. This includes component references within the match patterns of template rules. If a template rule lists several modes, it is treated as if there were multiple template rules one in each mode.

An xsl:apply-templates instruction with no mode attribute is treated as a reference to the default mode defined for that instruction (see 3.7.3 The default-mode Attribute), which in turn defaults to the unnamed mode. An implicit reference to the unnamed made is treated in the same way as any other symbolic reference. Note that there is an unnamed mode in every package, and the unnamed mode always has private visibility.

Where an xsl:template element has both a name and a match attribute, it is treated as if there were two separate xsl:template elements, one with a name attribute and one with a match attribute.

Keys and accumulators behave rather differently from other components. Their visibility is always private, which means they can only be used within their declaring package. In addition, the component binding is generally made dynamically rather than statically, by virtue of a string passed as an argument to the function key, accumulator-before, or accumulator-after. (In the case of accumulators, there can also be static references: see the use-accumulators attribute of xsl:source-document, xsl:merge-source, and xsl:mode.) However, outward references from key definitions and accumulators to other components (such as global variables and functions) behave in the same way as component references contained in any other private component, in that they may be re-bound to an overriding declaration of the target component.

3.5.4.6 Dynamic References to Components

There are several functions in which a dynamically evaluated QName is used to identify a component: these include key, accumulator-before, accumulator-after, apply-templates, function-lookup, and function-available. Dynamic references can also occur in the XPath expression supplied to the xsl:evaluate instruction.

In all these cases, the set of components that are available to be referenced are those that are declared in the package where this function call appears, including components declared within an xsl:override declaration in that package, but excluding components declared with visibility="abstract". If the relevant component has been overridden in a different package, the overriding declarations are not considered.

If one of these functions (for example key or accumulator-before) is invoked via a dynamic function invocation, then the relevant package is the one in which the function item is created (using a construct such as key#2, key('my-key', ?), or function-lookup($KEYFN, 2)). Function items referring to context-dependent functions bind the context at the point where the function item is created, not the context at the point where the function item is invoked.

Note:

This means that if a package wishes to make a key available for use by a calling package, it can do so by creating a public global variable whose value is a partial application of the key function:

<xsl:variable name="get-order" select="key('orders-key', ?, ?)"/>

which the calling code can invoke as $get-order('123-456', /).

6 Template Rules

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

6.7 Modes

[Definition: A mode is a set of template rules; when the xsl:apply-templates instruction selects a set of items for processing, it identifies the rules to be used for processing those items by nominating a mode, explicitly or implicitly.] Modes allow a node in a source tree (for example) to be processed multiple times, each time producing a different result. They also allow different sets of template rules to be active when processing different trees, for example when processing documents loaded using the document function (see 20.1 fn:document).

Modes are identified by an expanded QName; in addition to any named modes, there is always one unnamed mode available. Whether a mode is named or unnamed, its properties may be defined in an xsl:mode declaration. If a mode name is used (for example in an xsl:template declaration or an xsl:apply-templates instruction) and no declaration of that mode appears in the stylesheet, the mode is implicitly declared with default properties.

6.7.3 The `apply-templates` Function

Changes in 4.0 ⬇ ⬆

A new function fn:apply-templates is introduced. [IssueIssues 2005 2038 PR 2006 16 May 2025]

Sometimes it is useful to be able to apply templates from within an XPath expression. A common example is when using XPath expressions to construct maps and arrays. For example, an array of maps might be constructed by the following code:

<xsl:array>
  <xsl:for-each select="*">
    <xsl:array-member>
      <xsl:map>
        <xsl:for-each select="@*">
          <xsl:map-entry key="local-name()">
            <xsl:apply-templates select="."/>
          </xsl:map-entry>
        </xsl:for-each>
      </xsl:map>
    </xsl:array-member>  
  </xsl:for-each>
</xsl:array>

Such code can become verbose, so XSLT 4.0 offers the alternative of writing it like this:

<xsl:sequence select="array{ * ! map:build(@*, local-name#1, apply-templates#1) }"/>

To make this possible, a subset of the functionality of the xsl:apply-templates instruction is available via the (XSLT-only) apply-templates function, whose specification follows.

6.7.3.1 fn:apply-templates

Summary

Applies template rules to selected items.

Signature

`fn:apply-templates`(
`$select`	`as` `item()*`,
`$options`	`as` `map(*)?`	`:=` `{}`
) `as` `item()*`

Properties

This function is deterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

The function call apply-templates(X), used within an XPath expression, returns the same result as the instruction <xsl:apply-templates select="X"/>

The entries that may appear in the $options map are as follows. The option parameter conventions^FO apply.

<record>$params as map(xs:QName, item()*), $tunnel-params as map(xs:QName, item()*), $mode as (xs:QName | enum("#current", "#unnamed", "#default"))</record>

Key	Value	Meaning
`params?`	Supplies values for non-tunnel parameters. Each entry in the `params` map binds a parameter (identified by an `xs:QName` value) to a supplied value. Type: `map(xs:QName, item())` Default:* `{}`
`tunnel-params?`	Supplies values for tunnel parameters. Each entry in the `tunnel-params` map binds a tunnel parameter (identified by an `xs:QName` value) to a supplied value. Type: `map(xs:QName, item())` Default:* `{}`
`mode?`	Selects the mode to be used. The value may be set to an `xs:QName` that matches a declared mode in the stylesheet, or to one of the special values `#current`, or `#unnamed`, or #default. Type: `(xs:QName \| enum("#current", "#unnamed", "#default"))` Default: `"#default"`Default: `"#unnamed"`Default: `"#defaultunnamed"`
	`xs:QName`	Selects a declared mode by name.
	`#current`	Selects the current mode.
	`#unnamed#unnamed#unnamed`	Selects the unnamed mode.
`#default`	Selects the default mode from the static context.
`#default`	Selects the default mode from the static context.

For each item in the value of the $select argument, the function finds the best matching template rule in the selected mode and invokes that template rule with the supplied parameters (if any). The result of the function is the sequence concatenation of the results of performing this process for each item in the selected input, in turn.

Error Conditions

Errors may arise in the same situations as for the xsl:apply-templates instruction: for example, if the xsl:mode declaration specifies on-no-match="fail" and no matching template rule is found.

[ERR XTDE0565] It is a dynamic error if a call on the apply-templates function selects a mode that is not explicitly declared in the containing package, or accepted from a used package, or whose visibility is private.

Note:

Modes are private by default: for a mode to be available for reference by the apply-templates function, it must be explicitly declared with visibility="public".

Notes

Unlike the xsl:apply-templates instruction, the name of the required mode, and the names of the supplied parameters, can be evaluated dynamically.

If no mode is specified, the function uses the unnamed mode. It does not use the default mode (as defined by a containing [xsl:]default-mode attribute). This decision was made in order to avoid having to retain the default mode for each XPath expression at evaluation time, and to avoid complex rules for edge cases involving dynamic function calls.

See also the rules in 3.5.4.6 Dynamic References to Components, which are relevant to resolution of the mode name.

Examples

The function call:
`apply-templates(*, {'mode': '#current', 'params': { #expand : false() } })`
has the same effect as the instruction:
<xsl:apply-templates select="*" mode="#current"> <xsl:with-param name="expand" select="false()"/> </xsl:apply-templates>

XSL Transformations (XSLT) Version 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

3 Stylesheet Structure

3.5 Packages

3.5.4 Named Components in Packages

3.5.4.6 Dynamic References to Components

6 Template Rules

6.7 Modes

6.7.3 The `apply-templates` Function

6.7.3.1 fn:apply-templates

XSL Transformations (XSLT) Version 4.0

W3C Editor's Draft 23 February 2026

Abstract

Status of this Document

Dedication

3 Stylesheet Structure

3.5 Packages

3.5.4 Named Components in Packages

3.5.4.6 Dynamic References to Components

6 Template Rules

6.7 Modes

6.7.3 The apply-templates Function

6.7.3.1 fn:apply-templates

6.7.3 The `apply-templates` Function