XSL Transformations (XSLT) Version 4.0

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 J Changes since XSLT 3.0I Changes since XSLT 3.0JI Changes since XSLT 3.0.

2.1 Terminology

For a full glossary of terms, see C GlossaryB GlossaryCB 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.]

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.

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.

3. Zero or more messages. Messages are generated by the xsl:message and xsl:assert instructions, and are described in 24.1 Messages23.1 Messages24.123.1 Messages and 24.2 Assertions23.2 Assertions24.223.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 27 Serialization27 Serialization.[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 Serialization26 Serialization.[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 27 Serialization26 Serialization2726 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 28 Conformance28 Conformance. 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 Conformance27 Conformance. 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 28 Conformance27 Conformance2827 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 3.0] or the XDM specification [XDM 3.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 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 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 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 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: 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.2 Notation

[Definition: An XSLT element is an element in the XSLT namespace whose syntax and semantics are defined in this specification.] For a non-normative list of XSLT elements, see D Element Syntax SummaryD Element Syntax Summary.[Definition: An XSLT element is an element in the XSLT namespace whose syntax and semantics are defined in this specification.] For a non-normative list of XSLT elements, see C Element Syntax SummaryC Element Syntax Summary.[Definition: An XSLT element is an element in the XSLT namespace whose syntax and semantics are defined in this specification.] For a non-normative list of XSLT elements, see D Element Syntax SummaryC Element Syntax SummaryDC Element Syntax Summary.

In this document the specification of each XSLT element is preceded by a summary of its syntax in the form of a model for elements of that element type. A full list of all these specifications can be found in D Element Syntax SummaryC Element Syntax SummaryDC Element Syntax Summary. The meaning of the syntax summary notation is as follows:

• An attribute that is required is shown with its name in bold. An attribute that may be omitted is shown with a question mark following its name.

• An attribute that is deprecated is shown in a grayed font within square brackets.

• The string that occurs in the place of an attribute value specifies the allowed values of the attribute. If this is surrounded by curly brackets ({...}), then the attribute value is treated as an attribute value template, and the string occurring within curly brackets specifies the allowed values of the result of evaluating the attribute value template. Alternative allowed values are separated by |. A quoted string indicates a value equal to that specific string. An unquoted, italicized name specifies a particular type of value.

  The types used, and their meanings, are as follows:

  boolean

  One of the strings "yes", "true", or "1" to indicate the value true, or one of the strings "no", "false", or "0" to indicate the value false. Note: the values are synonyms; where this specification uses a phrase such as “If required='yes' is specified ...” this is to be interpreted as meaning “If the attribute named required is present, and has the value yes, true, or 1 (after stripping leading and trailing whitespace) ...”.

  string

  Any string.

  expression

  An XPath expression.

  pattern

  A pattern as described in 5.4 Patterns.

  item-type

  An ItemType^XP as defined in the XPath 4.0 specification.

  sequence-type

  A SequenceType^XP as defined in the XPath 4.0 specification.

  uri; uris

  A URI, for example a namespace URI or a collation URI; a whitespace-separated list of URIs.

  qname

  A lexical QName as defined in 5.1.1 Qualified Names.

  eqname; eqnames

  An EQName as defined in 5.1.1 Qualified Names; a whitespace-separated list of EQNames.

  token; tokens

  A string containing no significant whitespace; a whitespace-separated list of such strings.

  nmtoken; nmtokens

  A string conforming to the XML schema rules for the type xs:NMTOKEN; a whitespace-separated list of such strings.

  char

  A string comprising a single Unicode character.

  language

  A string in the value space of xs:language, or a zero-length string.

  integer

  An integer, that is, a string that is castable to the schema type xs:integer.

  decimal

  A decimal value, that is, a string that is castable to the schema type xs:decimal.

  ncname; ncnames

  An unprefixed name: a string that is castable to the schema type xs:NCName; a whitespace-separated list of such strings.

  prefix; prefixes

  An xs:NCName representing a namespace prefix, which must be in scope for the element on which it appears; a whitespace-separated list of such strings.

  id

  An xs:NCName used as a unique identifier for an element in the containing XML document.

  Except where the set of allowed values of an attribute is specified using the italicized name string or char, leading and trailing whitespace in the attribute value is ignored. In the case of an attribute value template, this applies to the effective value obtained when the attribute value template is expanded.

  XPath comments (delimited by (: ... :)) are permitted anywhere that inter-token whitespace is permitted in attributes whose type is given as expression, pattern, item-type, or sequence-type, and are not permitted in attributes of other types (other than within expressions enclosed by curly braces within an attribute value template).

• If an attribute has a simple default value, this is shown between tortoise-shell brackets (for example 〔'no'〕). Where no default is shown, the consequence of omitting the attribute is explained in the prose narrative. Default values shown in the summary apply only where the attribute itself is applicable; if an attribute is not permitted to appear in the particular context, then its default value should be ignored. (For example, the stable attribute of xsl:sort is shown as having a default value of 'yes', but the attribute is allowed only on the first of a sequence of adjacent xsl:sort elements.) The quotation marks around a default value are not part of the value.

• Unless the element is required to be empty, the model element contains a comment specifying the allowed content. The allowed content is specified in a way similar to an element type declaration in XML; sequence constructor means that any mixture of text nodes, literal result elements, extension instructions, and XSLT elements from the instruction category is allowed; other-declarations means that any mixture of XSLT elements from the declaration category is allowed, together with user-defined data elements.

• The element is prefaced by comments indicating if it belongs to the instruction category or declaration category or both. The category of an element affects only whether it is allowed in the content of elements that allow a sequence constructor or other-declarations.

[ERR XTSE0010] It is a static error if an XSLT-defined element is used in a context where it is not permitted, if a required attribute is omitted, or if the content of the element does not correspond to the content that is allowed for the element.

The rules in the element syntax summary (both for the element structure and for its attributes) apply to the stylesheet content after preprocessing as described in 3.13 Stylesheet Preprocessing.

[Definition: The effective value of an attribute or text node in the stylesheet is the value after any required expansion or normalization.]

More specifically, the effective value is the value after:

• Expanding shadow attributes as described in 3.13.4 Shadow Attributes;

• Expanding defaults (for example, if an xsl:message instruction has no terminate attribute, then the effective value of the terminate attribute is no);

• Stripping ignored whitespace (for example, the effective value of a boolean attribute written as terminate=" no " is no);

• Replacing synonyms (for example in boolean attributes, 1 and true are synonyms of yes);

• Expanding attribute value templates and text value templates.

• Applying rules from the static context: for example, the effective value of a collation attribute is the value after expanding a relative URI against the static base URI.

Attributes are validated as follows. These rules apply to the value of the attribute after removing leading and trailing whitespace.

• [ERR XTSE0020] It is a static error if an attribute (other than an attribute written using curly brackets in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute.

• [ERR XTDE0030] It is a dynamic error if the effective value of an attribute written using curly brackets, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute. If the processor is able to detect the error statically (for example, when any XPath expressions within the curly brackets can be evaluated statically), then the processor may optionally raise this as a static error.

Special rules apply if the construct appears in part of the stylesheet that is processed with forwards compatible behavior: see 3.10 Forwards Compatible Processing.

[Definition: Some constructs defined in this specification are described as being deprecated. The use of this term implies that stylesheet authors should not use the construct, and that the construct may be removed in a later version of this specification.]

XSLT defines a set of standard functions which are additional to those defined in [Functions and Operators 4.0]. A list of these functions appears in H.2 List of XSLT-defined functionsG.2 List of XSLT-defined functionsHG.2 List of XSLT-defined functions. The signatures of these functions are described using the same notation as used in [Functions and Operators 4.0]. The names of many of these functions are in the standard function namespace.

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

The main executable components of a stylesheet are templates and functions. The body of a template or function is a sequence constructor, which is a sequence of elements and text nodes that can be evaluated to produce a result.

A sequence constructor is a sequence of sibling nodes in the stylesheet, each of which is either an XSLT instruction, a literal result element, a text node, or an extension instruction.

[Definition: An instruction is either an XSLT instruction or an extension instruction.]

[Definition: An XSLT instruction is an XSLT element whose syntax summary in this specification contains the annotation <!-- category: instruction -->.]

Extension instructions are described in 25.2 Extension Instructions24.2 Extension Instructions25.224.2 Extension Instructions.

The main categories of XSLT instruction are as follows:

• instructions that create new nodes: xsl:document, xsl:element, xsl:attribute, xsl:processing-instruction, xsl:comment, xsl:value-of, xsl:text, xsl:namespace;

• instructions that construct maps and arrays: xsl:array, xsl:array-member, xsl:map, xsl:map-entry;

• instructions that copy nodes: xsl:copy, xsl:copy-of;

• an instruction that returns an arbitrary sequence by evaluating an XPath expression: xsl:sequence;

• instructions that cause conditional or repeated evaluation of nested instructions: xsl:if, xsl:choose, xsl:switch, xsl:try, xsl:for-each, xsl:for-each-group, xsl:fork, xsl:iterate and its subordinate instructions xsl:next-iteration and xsl:break;

• instructions that generate output conditionally if elements are or are not empty: xsl:on-empty, xsl:on-non-empty, xsl:where-populated;

• instructions that invoke templates: xsl:apply-templates, xsl:apply-imports, xsl:call-template, xsl:next-match;

• Instructions that declare variables: xsl:variable;

• Instructions to assist debugging: xsl:message, xsl:assert;

• other specialized instructions: xsl:number, xsl:analyze-string, xsl:fork, xsl:result-document, xsl:source-document, xsl:perform-sort, xsl:merge.

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.

[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 27 Serialization27 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.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 Serialization26 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.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 27 Serialization26 Serialization2726 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.9 Extensibility

XSLT defines a number of features that allow the language to be extended by implementers, or, if implementers choose to provide the capability, by users. These features have been designed, so far as possible, so that they can be used without sacrificing interoperability. Extensions other than those explicitly defined in this specification are not permitted.

These features are all based on XML namespaces; namespaces are used to ensure that the extensions provided by one implementer do not clash with those of a different implementer.

The most common way of extending the language is by providing additional functions, which can be invoked from XPath expressions. These are known as extension functions, and are described in 25.1 Extension Functions24.1 Extension Functions25.124.1 Extension Functions.

It is also permissible to extend the language by providing new instructions. These are referred to as extension instructions, and are described in 25.2 Extension Instructions25.2 Extension Instructions. A stylesheet that uses extension instructions in a particular namespace must declare that it is doing so by using the [xsl:]extension-element-prefixes attribute.It is also permissible to extend the language by providing new instructions. These are referred to as extension instructions, and are described in 24.2 Extension Instructions24.2 Extension Instructions. A stylesheet that uses extension instructions in a particular namespace must declare that it is doing so by using the [xsl:]extension-element-prefixes attribute.It is also permissible to extend the language by providing new instructions. These are referred to as extension instructions, and are described in 25.2 Extension Instructions24.2 Extension Instructions25.224.2 Extension Instructions. A stylesheet that uses extension instructions in a particular namespace must declare that it is doing so by using the [xsl:]extension-element-prefixes attribute.

Extension instructions and extension functions defined according to these rules may be provided by the implementer of the XSLT processor, and the implementer may also provide facilities to allow users to create further extension instructions and extension functions.

This specification defines how extension instructions and extension functions are invoked, but the facilities for creating new extension instructions and extension functions are implementation-defined. For further details, see 25 Extensibility and Fallback24 Extensibility and Fallback2524 Extensibility and Fallback.

The XSLT language can also be extended by the use of extension attributes (see 3.2 Extension Attributes), and by means of user-defined data elements (see 3.7.4 User-defined Data Elements).

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 3.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, but as explained in 3.15 Importing Schema Components, the schema components used in different packages must be consistent with each other.

The conformance rules for XSLT 4.0, defined in 28 Conformance28 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).The conformance rules for XSLT 4.0, defined in 27 Conformance27 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).The conformance rules for XSLT 4.0, defined in 28 Conformance27 Conformance2827 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.

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:

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.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 26.4 Validation25.4 Validation26.425.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.

<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 27 Serialization27 Serialization, and in particular it must raise any serialization errors that occur.[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 Serialization26 Serialization, and in particular it must raise any serialization errors that occur.[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 27 Serialization26 Serialization2726 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 E Summary of Error ConditionsE Summary of Error Conditions. 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 ConditionsD Summary of Error Conditions. 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 E Summary of Error ConditionsD Summary of Error ConditionsED 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.

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

  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.4 Standard Attributes

[Definition: There are a number of standard attributes that may appear on any XSLT element: specifically default-collation, default-mode, default-validation, exclude-result-prefixes, expand-text, extension-element-prefixes, use-when, version, and xpath-default-namespace.]

These attributes may also appear on a literal result element, but in this case, to distinguish them from user-defined attributes, the names of the attributes are in the XSLT namespace. They are thus typically written as xsl:default-collation, xsl:default-mode, xsl:default-validation, xsl:exclude-result-prefixes, xsl:expand-text, xsl:extension-element-prefixes, xsl:use-when, xsl:version, or xsl:xpath-default-namespace.

It is recommended that all these attributes should also be permitted on extension instructions, but this is at the discretion of the implementer of each extension instruction. They may also be permitted on user-defined data elements, though they will only have any useful effect in the case of data elements that are designed to behave like XSLT declarations or instructions.

In the following descriptions, these attributes are referred to generically as [xsl:]version, and so on.

These attributes all affect the element they appear on, together with any elements and attributes that have that element as an ancestor. The two forms with and without the XSLT namespace have the same effect; the XSLT namespace is used for the attribute if and only if its parent element is not in the XSLT namespace.

In the case of [xsl:]default-collation, [xsl:]expand-text, [xsl:]version, and [xsl:]xpath-default-namespace, the value can be overridden by a different value for the same attribute appearing on a descendant element. The effective value of the attribute for a particular stylesheet element is determined by the innermost ancestor-or-self element on which the attribute appears.

In an embedded stylesheet module, standard attributes appearing on ancestors of the outermost element of the stylesheet module have no effect.

In the case of [xsl:]exclude-result-prefixes and [xsl:]extension-element-prefixes the values are cumulative. For these attributes, the value is given as a whitespace-separated list of namespace prefixes, and the effective value for an element is the combined set of namespace URIs designated by the prefixes that appear in this attribute for that element and any of its ancestor elements. Again, the two forms with and without the XSLT namespace are equivalent.

The effect of the [xsl:]use-when attribute is described in 3.13.3 Conditional Element Inclusion.

Because these attributes may appear on any XSLT element, they are not listed in the syntax summary of each individual element. Instead they are listed and described in the entry for the xsl:stylesheet, xsl:transform, and xsl:package elements only. This reflects the fact that these attributes are often used on the outermost element of the stylesheet, in which case they apply to the entire stylesheet module or package manifest.

Note that the effect of these attributes does not extend to stylesheet modules referenced by xsl:include or xsl:import declarations, nor to packages referenced using xsl:use-package.

For the detailed effect of each attribute, see the following sections:

[xsl:]default-collation

see 3.7.2 The default-collation Attribute

[xsl:]default-mode

see 3.7.3 The default-mode Attribute

[xsl:]default-validation

see 26.4 Validation25.4 Validation26.425.4 Validation

[xsl:]exclude-result-prefixes

see 11.1.3 Namespace Nodes for Literal Result Elements

[xsl:]expand-text

see 5.7.2 Text Value Templates

[xsl:]extension-element-prefixes

see 25.2 Extension Instructions24.2 Extension Instructions25.224.2 Extension Instructions

[xsl:]use-when

see 3.13.3 Conditional Element Inclusion

[xsl:]version

see 3.9 Backwards Compatible Processing and 3.10 Forwards Compatible Processing

[xsl:]xpath-default-namespace

see 5.1.2 Unprefixed Lexical QNames in Expressions and Patterns

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
  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
  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 26.4 Validation26.4 Validation.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 Validation25.4 Validation.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 26.4 Validation25.4 Validation26.425.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.5 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.10 Forwards Compatible Processing

The intent of forwards compatible behavior is to make it possible to write a stylesheet that takes advantage of features introduced in some version of XSLT subsequent to XSLT 4.0, while retaining the ability to execute the stylesheet with an XSLT 4.0 processor using appropriate fallback behavior.

It is always possible to write conditional code to run under different XSLT versions by using the use-when feature described in 3.13.3 Conditional Element Inclusion. The rules for forwards compatible behavior supplement this mechanism in two ways:

• Certain constructs in the stylesheet that mean nothing to an XSLT 4.0 processor are ignored, rather than being treated as errors.

• Explicit fallback behavior can be defined for instructions defined in a future XSLT release, using the xsl:fallback instruction.

The detailed rules follow.

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

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

When an element is processed with forwards compatible behavior:

• If the element is in the XSLT namespace and appears as a child of the xsl:stylesheet element, and XSLT 4.0 does not allow the element to appear as a child of the xsl:stylesheet element, then the element and its content must be ignored.

• If the element has an attribute that XSLT 4.0 does not allow the element to have, then the attribute must be ignored.

• If the element is in the XSLT namespace and appears as a child of an element whose content model requires a sequence constructor, and XSLT 4.0 does not allow such elements to appear as part of a sequence constructor, then:

  1. If the element has one or more xsl:fallback children, then no error is raised either statically or dynamically, and the result of evaluating the instruction is the concatenation of the sequences formed by evaluating the sequence constructors within its xsl:fallback children, in document order. Siblings of the xsl:fallback elements are ignored, even if they are valid XSLT 4.0 instructions.

  2. If the element has no xsl:fallback children, then a static error is raised in the same way as if forwards compatible behavior were not enabled.

<xsl:stylesheet version="17.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/">
    <xsl:exciting-new-17.0-feature>
      <xsl:fly-to-the-moon/>
      <xsl:fallback>
        <html>
          <head>
            <title>XSLT 17.0 required</title>
          </head>
          <body>
            <p>Sorry, this stylesheet requires XSLT 17.0.</p>
          </body>
        </html>
      </xsl:fallback>
    </xsl:exciting-new-17.0-feature>
  </xsl:template>
</xsl:stylesheet>

<xsl:stylesheet version="18.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:important-new-17.0-declaration/>

  <xsl:template match="/">
    <xsl:choose>
      <xsl:when test="number(system-property('xsl:version')) lt 17.0">
        <xsl:message terminate="yes">
          <xsl:text>Sorry, this stylesheet requires XSLT 17.0.</xsl:text>
        </xsl:message>
      </xsl:when>
      <xsl:otherwise>
        ...
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
  ...
</xsl:stylesheet>

For an XSLT 4.0 processor, the effective version of an xsl:fallback element that has no explicit version attribute is 4.0: more generally, it is the version of XSLT supported by the processor. This rule is designed to ensure that the xsl:fallback element itself is not processed with forwards compatible behavior, which would be pointless since the whole purpose of the instruction is to provide code that can be evaluated with an earlier version of XSLT.

3.14 Built-in Types

Every XSLT 4.0 processor includes the following named type definitions in the in-scope schema components:

• All built-in types defined in [XML Schema Part 2], including xs:anyType and xs:anySimpleType.

• The following types defined in [XPath 3.0]: xs:yearMonthDuration, xs:dayTimeDuration, xs:anyAtomicType, xs:untyped, and xs:untypedAtomic.

XSLT 4.0 processors may optionally include types defined in XSD 1.1 (see [XML Schema 1.1 Part 1]). XSD 1.1 adopts the types xs:yearMonthDuration, xs:dayTimeDuration, and xs:anyAtomicType previously defined in XPath 2.0, and adds one new type: xs:dateTimeStamp. XSD 1.1 also allows implementers to define additional primitive types, and XSLT 4.0 permits such types to be supported by an XSLT processor.

A schema-aware XSLT processor additionally supports:

• User-defined types, and element and attribute declarations, that are imported using an xsl:import-schema declaration as described in 3.15 Importing Schema Components. These may include both simple and complex types.

An implementation may define mechanisms that allow additional schema components to be added to the in-scope schema components for the stylesheet. For example, the mechanisms used to define extension functions (see 25.1 Extension Functions24.1 Extension Functions25.124.1 Extension Functions) may also be used to import the types used in the interface to such functions.

These schema components are the only ones that may be referenced in XPath expressions within the stylesheet, or in the [xsl:]type and as attributes of those elements that permit these attributes.

3.15 Importing Schema Components

<!-- Category: declaration -->
<xsl:import-schema
  namespace? = uri
  schema-location? = uri >
  <!-- Content: xs:schema? -->
</xsl:import-schema>

The xsl:import-schema declaration is used to identify schema components (that is, top-level type definitions and top-level element and attribute declarations) that need to be available statically, that is, before any source document is available. Names of such components used statically within the stylesheet must refer to an in-scope schema component, which means they must either be built-in types as defined in 3.14 Built-in Types, or they must be imported using an xsl:import-schema declaration.

The xsl:import-schema declaration identifies a namespace containing the names of the components to be imported (or indicates that components whose names are in no namespace are to be imported). The effect is that the names of top-level element and attribute declarations and type definitions from this namespace (or non-namespace) become available for use within XPath expressions in the package, and within other stylesheet constructs such as the type and as attributes of various XSLT elements.

The same schema components are available in all stylesheet modules within the declaring package; importing components in one stylesheet module makes them available throughout the package.

The schema components imported into different packages within a stylesheet must be compatible^DM. Specifically, it is not permitted to use the same name in the same XSD symbol space to refer to different schema components within different packages; and the union of the schema components imported into the packages of a stylesheet must constitute a valid schema (as well as the set of schema components imported into each package forming a valid schema in its own right).

The namespace and schema-location attributes are both optional.

If the xsl:import-schema element contains an xs:schema element, then the schema-location attribute must be absent, and one of the following must be true:

• the namespace attribute of the xsl:import-schema element and the targetNamespace attribute of the xs:schema element are both absent (indicating a no-namespace schema), or

• the namespace attribute of the xsl:import-schema element and the targetNamespace attribute of the xs:schema element are both present and both have the same value, or

• the namespace attribute of the xsl:import-schema element is absent and the targetNamespace attribute of the xs:schema element is present, in which case the target namespace is as given on the xs:schema element.

[ERR XTSE0215] It is a static error if an xsl:import-schema element that contains an xs:schema element has a schema-location attribute, or if it has a namespace attribute that conflicts with the target namespace of the contained schema.

If two xsl:import-schema declarations specify the same namespace, or if both specify no namespace, then only the one with highest import precedence is used. If this leaves more than one, then all the declarations at the highest import precedence are used (which may cause conflicts, as described below).

After discarding any xsl:import-schema declarations under the above rule, the effect of the remaining xsl:import-schema declarations is defined in terms of a hypothetical document called the synthetic schema document, which is constructed as follows. The synthetic schema document defines an arbitrary target namespace that is different from any namespace actually used by the application, and it contains xs:import elements corresponding one-for-one with the xsl:import-schema declarations in the stylesheet, with the following correspondence:

• The namespace attribute of the xs:import element is copied from the namespace attribute of the xsl:import-schema declaration if it is explicitly present, or is implied by the targetNamespace attribute of a contained xs:schema element, and is absent if it is absent.

• The schemaLocation attribute of the xs:import element is copied from the schema-location attribute of the xsl:import-schema declaration if present, and is absent if it is absent. If there is a contained xs:schema element, the effective value of the schemaLocation attribute is a URI referencing a document containing a copy of the xs:schema element.

• The base URI of the xs:import element is the same as the base URI of the xsl:import-schema declaration.

The schema components included in the in-scope schema components (that is, the components whose names are available for use within the stylesheet) are the top-level element and attribute declarations and type definitions that are available for reference within the synthetic schema document. See [XML Schema Part 1] (section 4.2.3, References to schema components across namespaces).

[ERR XTSE0220] It is a static error if the synthetic schema document does not satisfy the constraints described in [XML Schema Part 1] (section 5.1, Errors in Schema Construction and Structure). This includes, without loss of generality, conflicts such as multiple definitions of the same name.

The use of a namespace in an xsl:import-schema declaration does not by itself associate any namespace prefix with the namespace. If names from the namespace are used within the stylesheet module then a namespace declaration must be included in the stylesheet module, in the usual way.

<xsl:import-schema>
  <xs:schema targetNamespace="http://example.com/ns/yes-no"
             xmlns:xs="http://www.w3.org/2001/XMLSchema"
             xmlns:local="http://example.com/ns/yes-no">
    <xs:simpleType name="yes-no">
      <xs:restriction base="xs:string">
        <xs:enumeration value="yes"/>
        <xs:enumeration value="no"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:schema>
</xsl:import-schema>

<xsl:variable name="condition" select="local:yes-no('yes')" 
                               as="local:yes-no"/>

There are two built-in functions (analyze-string and json-to-xml) whose result is an XML structure for which a schema is defined. The namespace for these schema definitions is (in both cases) http://www.w3.org/2005/xpath-functions. Schema components for these namespaces are available for reference within the stylesheet if and only if an xsl:import-schema declaration is present referencing this namespace. If such a declaration is present, then the schema that is imported is the schema defined in the specification of these functions: the schemaLocation attribute has no effect.

4.1 XML Versions

The XDM data model defined in [XDM 3.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 27 Serialization26 Serialization2726 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.7 Disable Output Escaping

For backwards compatibility reasons, XSLT 4.0 continues to support the disable-output-escaping feature introduced in XSLT 1.0. This is an optional feature and implementations are not required to support it. A new facility, that of named character maps (see 27.3 Character Maps27.3 Character Maps) was introduced in XSLT 2.0. It provides similar capabilities to disable-output-escaping, but without distorting the data model.For backwards compatibility reasons, XSLT 4.0 continues to support the disable-output-escaping feature introduced in XSLT 1.0. This is an optional feature and implementations are not required to support it. A new facility, that of named character maps (see 26.3 Character Maps26.3 Character Maps) was introduced in XSLT 2.0. It provides similar capabilities to disable-output-escaping, but without distorting the data model.For backwards compatibility reasons, XSLT 4.0 continues to support the disable-output-escaping feature introduced in XSLT 1.0. This is an optional feature and implementations are not required to support it. A new facility, that of named character maps (see 27.3 Character Maps26.3 Character Maps27.326.3 Character Maps) was introduced in XSLT 2.0. It provides similar capabilities to disable-output-escaping, but without distorting the data model.

If an implementation supports the disable-output-escaping attribute of xsl:text and xsl:value-of, (see 27.5 Disabling Output Escaping27.5 Disabling Output Escaping), then the data model for trees constructed by the processor is augmented with a boolean value representing the value of this property. This boolean value, however, can be set only within a final result tree that is being passed to the serializer.If an implementation supports the disable-output-escaping attribute of xsl:text and xsl:value-of, (see 26.5 Disabling Output Escaping26.5 Disabling Output Escaping), then the data model for trees constructed by the processor is augmented with a boolean value representing the value of this property. This boolean value, however, can be set only within a final result tree that is being passed to the serializer.If an implementation supports the disable-output-escaping attribute of xsl:text and xsl:value-of, (see 27.5 Disabling Output Escaping26.5 Disabling Output Escaping27.526.5 Disabling Output Escaping), then the data model for trees constructed by the processor is augmented with a boolean value representing the value of this property. This boolean value, however, can be set only within a final result tree that is being passed to the serializer.

Conceptually, each character in a text node on such a result tree has a boolean property indicating whether the serializer is to disable the normal rules for escaping of special characters (for example, outputting of & as &) in respect of this character.

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.

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

In XSLT 4.0, patterns can match any kind of item: atomic items and function items as well as nodes.

A template rule identifies the items to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see 12 Numbering), for grouping (see 14 Grouping), and for declaring keys (see 20.2 Keys).

[Definition: A pattern specifies a set of conditions on an item. An item that satisfies the conditions matches the pattern; an item that does not satisfy the conditions does not match the pattern.]

There are three kinds of pattern: predicate patterns, type patterns, and node patterns:

• [Definition: A predicate pattern is written as . (dot) followed by zero or more predicates in square brackets, and it matches any item for which each of the predicates evaluates to true.]

  A predicate pattern .[P1][P2]... can be regarded as an abbreviation for the type pattern type(item())[P1][P2]....

  The detailed semantics are given in 5.4.2.1 Predicate Patterns. This construct can be used to match items of any kind (nodes, atomic items, and function items). For example, the pattern .[starts-with(., '$')] matches any string that starts with the character $, or a node whose atomized value starts with $. This example shows a predicate pattern with a single predicate, but the grammar allows any number of predicates (zero or more).

• [Definition: A type pattern can be written as type(T) (where T is an ItemType^XP followed by zero or more predicates in square brackets, and it matches any item of type T which each of the predicates evaluates to true.]

  The parameter T can also be a list of item types, separated by "|". For example, type(array(*) | map(*)) matches arrays and maps, while type(text() | comment()) matches text nodes and comment nodes.

  The most commonly used type patterns can be abbreviated. For example, match="type(record(F1, F2, *))" can be abbrevated to match="record(F1, F2, *)", and match="type(array(xs:string))" can be abbreviated to match="array(xs:string)". The main case where such abbreviation is not possible is with atomic items: match="type(xs:date)" cannot be abbreviated because a bare QName is interpreted as a node pattern, matching elements named xs:date. The pattern match="type(text() | comment())" has almost the same effect as match="text() | comment()", except that the rules for calculating a default priority are different.

• [Definition: A node pattern uses a subset of the syntax for path expressions, and is defined to match a node if the corresponding path expression would select the node. Node patterns may also be formed by combining other patterns using union, intersection, and difference operators.]

  The syntax for node patterns (UnionExprP in the grammar: see 5.4.2 Syntax of Patterns) is a subset of the syntax for expressions. Node patterns are used only for matching nodes; an item other than a node will never match a node pattern. As explained in detail below, a node matches a node pattern if the node can be selected by deriving an equivalent expression, and evaluating this expression with respect to some possible context.

5.8 Sequence Constructors

[Definition: A sequence constructor is a sequence of zero or more sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes, atomic items, and function items. The way that the resulting sequence is used depends on the containing instruction.]

Many XSLT elements, and also literal result elements, are defined to take a sequence constructor as their content.

Four kinds of nodes may be encountered in a sequence constructor:

1. A Text node appearing in the stylesheet (if it has not been removed in the process of whitespace stripping: see 3.13.1 Stripping Whitespace and Commentary from the Stylesheet) is processed as follows:

   1. if the effective value of the standard attribute [xsl:]expand-text is no, or in the absence of this attribute, the text node in the stylesheet is copied to create a new parentless text node in the result of the sequence constructor.

   2. Otherwise (the effective value of [xsl:]expand-text is yes), the text node in the stylesheet is processed as described in 5.7.2 Text Value Templates.

2. A literal result element is evaluated to create a new parentless element node, having the same expanded QName as the literal result element: see 11.1 Literal Result Elements.

3. An XSLT instruction produces a sequence of zero, one, or more items as its result. For most XSLT instructions, these items are nodes, but some instructions (such as xsl:sequence and xsl:copy-of) can also produce atomic items or function items. Several instructions, such as xsl:element, return a newly constructed parentless node (which may have its own attributes, namespaces, children, and other descendants). Other instructions, such as xsl:if, pass on the items produced by their own nested sequence constructors. The xsl:sequence instruction may return atomic items, function items, or existing nodes.

4. An extension instruction (see 25.2 Extension Instructions24.2 Extension Instructions25.224.2 Extension Instructions) also produces a sequence of items as its result.

[Definition: The result of evaluating a sequence constructor is the sequence of items formed by concatenating the results of evaluating each of the nodes in the sequence constructor, retaining order. This is referred to as the immediate result of the sequence constructor.]

However:

• For the effect of the xsl:fallback instruction, see 25.2.3 Fallback24.2.3 Fallback25.2.324.2.3 Fallback.

• For the effect of the xsl:on-empty and xsl:on-non-empty instructions, see 8.5 Conditional Content Construction.

The way that immediate result of a sequence constructor is used depends on the containing element in the stylesheet, and is specified in the rules for that element. It is typically one of the following:

• The immediate result may be bound to a variable or delivered as the result of a stylesheet function. In this case the as attribute of the containing xsl:variable or xsl:function element may be used to declare its required type, and the immediate result is then converted to the required type by applying the coercion rules.

  Note:

  • In the absence of an as attribute, the result of a function is the immediate result of the sequence constructor; but the value of a variable (for backwards compatibility reasons) is a document node whose content is formed by applying the rules in 5.8.1 Constructing Complex Content to the immediate result.

  • The coercion rules do not merge adjacent text nodes or insert separators between adjacent items. This means it is often inappropriate to use xsl:value-of in the body of xsl:variable or xsl:function, especially when the intent is to return an atomic result. The xsl:sequence instruction is designed for this purpose, and is usually a better choice.

  • The result of a function, or the value of a variable, may contain nodes (such as elements, attributes, and text nodes) that are not attached to any parent node in a result tree. The semantics of XPath expressions when applied to parentless nodes are well-defined; however, such expressions should be used with care. For example, the expression / causes a type error if the root of the tree containing the context node is not a document node.

  • Parentless attribute nodes require particular care because they have no namespace nodes associated with them. A parentless attribute node is not permitted to contain namespace-sensitive content (for example, a QName or an XPath expression) because there is no information enabling the prefix to be resolved to a namespace URI. Parentless attributes can be useful in an application (for example, they provide an alternative to the use of attribute sets: see 10.2 Named Attribute Sets) but they need to be handled with care.

• The sequence may be returned as the result of the containing element. This happens, for example, when the element containing the sequence constructor is xsl:break, xsl:catch, xsl:fallback, xsl:for-each, xsl:for-each-group, xsl:fork, xsl:if, xsl:iterate, xsl:matching-substring, xsl:non-matching-substring, xsl:on-completion, xsl:otherwise, xsl:perform-sort, xsl:sequence, xsl:try, or xsl:when.

• The sequence may be used to construct the content of a new element or document node. This happens when the sequence constructor appears as the content of a literal result element, or of one of the instructions xsl:copy, xsl:element, xsl:document, xsl:result-document, xsl:assert, or xsl:message. It also happens when the sequence constructor is contained in one of the elements xsl:variable, xsl:param, or xsl:with-param, when this instruction has no as attribute. For details, see 5.8.1 Constructing Complex Content.

• The sequence may be used to construct the string value of an attribute node, text node, namespace node, comment node, or processing instruction node. This happens when the sequence constructor is contained in one of the elements xsl:attribute, xsl:value-of, xsl:namespace, xsl:comment, or xsl:processing-instruction. For details, see 5.8.2 Constructing Simple Content.

10.4 Dynamic XPath Evaluation

<!-- Category: instruction -->
<xsl:evaluate
  xpath = expression
  as? = sequence-type〔'item()*'〕
  base-uri? = { uri }
  with-params? = expression
  context-item? = expression
  namespace-context? = expression
  schema-aware? = { boolean }〔'no'〕 >
  <!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:evaluate>

The xsl:evaluate instruction constructs an XPath expression in the form of a string, evaluates the expression in a specified context, and returns the result of the evaluation.

The expression given as the value of the xpath attribute is evaluated and the result is converted to a string using the coercion rules.

[Definition: The string that results from evaluating the expression in the xpath attribute is referred to as the target expression.]

[ERR XTDE3160] It is a dynamic error if the target expression is not a valid expression (that is, if a static error occurs when analyzing the string according to the rules of the XPath specification).

The as attribute, if present, indicates the required type of the result. If the attribute is absent, the required type is item()*, which allows any result. The result of evaluating the target expression is converted to the required type using the coercion rules. This may cause a type error if conversion is not possible. The result after conversion is returned as the result of the xsl:evaluate instruction.

The target expression may contain variable references; the values of such variables may be supplied using an xsl:with-param child instruction if the names of the variables are known statically, or using a map supplied as the value of the expression in the with-params attribute if the names are only known dynamically. If the with-params attribute is present then it must contain an expression whose value, when evaluated, is of type map(xs:QName, item()*) (see 21 Maps for details of maps).

[ERR XTTE3165] It is a type error if the result of evaluating the expression in the with-params attribute of the xsl:evaluate instruction is anything other than a single map of type map(xs:QName, item()*).

<xsl:variable name="isValid" as="xs:boolean">
  <xsl:evaluate xpath="$validityCondition">
     <xsl:fallback><xsl:sequence select="true()"/></xsl:fallback>
  </xsl:evaluate>
</xsl:variable>

11.1 Literal Result Elements

[Definition: In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 25.2 Extension Instructions25.2 Extension Instructions) is classified as a literal result element.] A literal result element is evaluated to construct a new element node with the same expanded QName (that is, the same namespace URI, local name, and namespace prefix). The result of evaluating a literal result element is a node sequence containing one element, the newly constructed element node.[Definition: In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 24.2 Extension Instructions24.2 Extension Instructions) is classified as a literal result element.] A literal result element is evaluated to construct a new element node with the same expanded QName (that is, the same namespace URI, local name, and namespace prefix). The result of evaluating a literal result element is a node sequence containing one element, the newly constructed element node.[Definition: In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 25.2 Extension Instructions24.2 Extension Instructions25.224.2 Extension Instructions) is classified as a literal result element.] A literal result element is evaluated to construct a new element node with the same expanded QName (that is, the same namespace URI, local name, and namespace prefix). The result of evaluating a literal result element is a node sequence containing one element, the newly constructed element node.

The content of the element is a sequence constructor (see 5.8 Sequence Constructors). The sequence obtained by evaluating this sequence constructor, after prepending any attribute nodes produced as described in 11.1.2 Attribute Nodes for Literal Result Elements and namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements, is used to construct the content of the element, following the rules in 5.8.1 Constructing Complex Content

The base URI of the new element is copied from the base URI of the literal result element in the stylesheet, unless the content of the new element includes an xml:base attribute, in which case the base URI of the new element is the value of that attribute, resolved (if it is a relative URI reference) against the base URI of the literal result element in the stylesheet. (Note, however, that this is only relevant when creating a parentless element. When the literal result element is copied to form a child of an element or document node, the base URI of the new copy is taken from that of its new parent.)

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:a="a.uri"
  xmlns:b="b.uri"
  exclude-result-prefixes="#all">
  
<xsl:template match="/">
  <foo xmlns:c="c.uri" xmlns:d="d.uri" xmlns:a2="a.uri" 
       xsl:exclude-result-prefixes="c"/>
</xsl:template>

</xsl:stylesheet>

<foo xmlns:d="d.uri"/>

11.2 Creating Element Nodes Using xsl:element

<!-- Category: instruction -->
<xsl:element
  name = { qname }
  namespace? = { uri }
  inherit-namespaces? = boolean〔'yes'〕
  use-attribute-sets? = eqnames〔''〕
  type? = eqname
  validation? = "strict" | "lax" | "preserve" | "strip" >
  <!-- Content: sequence-constructor -->
</xsl:element>

The xsl:element instruction allows an element to be created with a computed name. The expanded QName of the element to be created is specified by a requiredname attribute and an optional namespace attribute.

The result of evaluating the xsl:element instruction, in usual circumstances, is the newly constructed element node.

11.3 Creating Attribute Nodes Using xsl:attribute

<!-- Category: instruction -->
<xsl:attribute
  name = { qname }
  namespace? = { uri }
  select? = expression
  separator? = { string }
  type? = eqname
  validation? = "strict" | "lax" | "preserve" | "strip" >
  <!-- Content: sequence-constructor -->
</xsl:attribute>

The xsl:attribute element can be used to add attributes to result elements whether created by literal result elements in the stylesheet or by instructions such as xsl:element or xsl:copy. The expanded QName of the attribute to be created is specified by a requiredname attribute and an optional namespace attribute. Except in error cases, the result of evaluating an xsl:attribute instruction is the newly constructed attribute node.

The string value of the new attribute node may be defined either by using the select attribute, or by the sequence constructor that forms the content of the xsl:attribute element. These are mutually exclusive: if the select attribute is present then the sequence constructor must be empty, and if the sequence constructor is non-empty then the select attribute must be absent. If the select attribute is absent and the sequence constructor is empty, then the string value of the new attribute node will be a zero-length string. The way in which the value is constructed is specified in 5.8.2 Constructing Simple Content.

[ERR XTSE0840] It is a static error if the select attribute of the xsl:attribute element is present unless the element has empty content.

If the separator attribute is present, then the effective value of this attribute is used to separate adjacent items in the result sequence, as described in 5.8.2 Constructing Simple Content. In the absence of this attribute, the default separator is U+0020 (SPACE) when the content is specified using the select attribute, or a zero-length string when the content is specified using a sequence constructor.

The name attribute is interpreted as an attribute value template, whose effective valuemust be a lexical QName.

[ERR XTDE0850] It is a dynamic error if the effective value of the name attribute is not a lexical QName.

[ERR XTDE0855] In the case of an xsl:attribute instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is the string xmlns.

[ERR XTDE0860] In the case of an xsl:attribute instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a lexical QName whose prefix is not declared in the applicable static namespaces for the xsl:attribute instruction.

If the namespace attribute is not present, then the lexical QName is expanded into an expanded QName using the namespace declarations in effect for the xsl:attribute element, not including any default namespace declaration.

If the namespace attribute is present, then it too is interpreted as an attribute value template. The effective valuemust be in the lexical space of the xs:anyURI type. If the string is zero-length, then the expanded QName of the attribute has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded QName of the attribute to be created. The local part of the lexical QName specified by the name attribute is used as the local part of the expanded QName of the attribute to be created.

[ERR XTDE0865] It is a dynamic error if the effective value of the namespace attribute is not in the lexical space of the xs:anyURI datatype or if it is the string http://www.w3.org/2000/xmlns/.

The prefix of the lexical QName specified in the name attribute (or the absence of a prefix) is copied to the prefix part of the expanded QName representing the name of the new attribute node. In the event of a conflict this prefix may subsequently be added, changed, or removed during the namespace fixup process (see 5.8.3 Namespace Fixup). If the attribute is in a non-null namespace and no prefix is specified, then the namespace fixup process will invent a prefix. The term conflict here means any violation of the constraints defined in [XDM 3.0], for example the use of the same prefix to refer to two different namespaces in the element and in one of its attributes, the use of the prefix xml to refer to a namespace other than the XML namespace, or any use of the prefix xmlns.

If the name of a constructed attribute is xml:id, the processor must perform attribute value normalization by effectively applying the normalize-space function to the value of the attribute, and the resulting attribute node must be given the is-id property. This applies whether the attribute is constructed using the xsl:attribute instruction or whether it is constructed using an attribute of a literal result element. This does not imply any constraints on the value of the attribute, or on its uniqueness, and it does not affect the type annotation of the attribute, unless the containing document is validated.

<xsl:attribute name="colors" select="'red', 'green', 'blue'"/>

<xsl:attribute name="xmlns:xsl" 
   namespace="file://some.namespace"
   select="'http://www.w3.org/1999/XSL/Transform'"/>

As described in 5.8.1 Constructing Complex Content, in a sequence that is used to construct the content of an element, any attribute nodes must appear in the sequence before any element, text, comment, or processing instruction nodes. Where the sequence contains two or more attribute nodes with the same expanded QName, the one that comes last is the only one that takes effect.

11.4 Creating Text Nodes

This section describes three different ways of creating text nodes: by means of literal text nodes in the stylesheet, or by using the xsl:text and xsl:value-of instructions. It is also possible to create text nodes using the xsl:number instruction described in 12 Numbering.

If and when the sequence that results from evaluating a sequence constructor is used to form the content of a node, as described in 5.8.2 Constructing Simple Content and 5.8.1 Constructing Complex Content, adjacent text nodes in the sequence are merged. Within the sequence itself, however, they exist as distinct nodes.

<xsl:function name="f:wrap">
  <xsl:param name="s"/>
  <xsl:text>(</xsl:text>
  <xsl:value-of select="$s"/>
  <xsl:text>)</xsl:text>
</xsl:function>

<xsl:value-of select="f:wrap('---')"/>

(---)

<xsl:value-of select="data(f:wrap('---'))"/>

( --- )

It is possible to construct text nodes whose string value is zero-length. A zero-length text node, when atomized, produces a zero-length string. However, zero-length text nodes are ignored when they appear in a sequence that is used to form the content of a node, as described in 5.8.1 Constructing Complex Content and 5.8.2 Constructing Simple Content.

<x><xsl:value-of select="1 to 4" separator="|"/></x>

<x>1|2|3|4</x>

11.5 Creating Document Nodes

<!-- Category: instruction -->
<xsl:document
  validation? = "strict" | "lax" | "preserve" | "strip"
  type? = eqname >
  <!-- Content: sequence-constructor -->
</xsl:document>

The xsl:document instruction is used to create a new document node. The content of the xsl:document element is a sequence constructor for the children of the new document node. A document node is created, and the sequence obtained by evaluating the sequence constructor is used to construct the content of the document, as described in 5.8.1 Constructing Complex Content.

Except in error situations, the result of evaluating the xsl:document instruction is a single node, the newly constructed document node.

The optional attributes type and validation may be used on the xsl:document instruction to validate the contents of the new document, and to determine the type annotation that elements and attributes within the result tree will carry. The permitted values and their semantics are described in 26.4.2 Validating Document Nodes26.4.2 Validating Document Nodes.The optional attributes type and validation may be used on the xsl:document instruction to validate the contents of the new document, and to determine the type annotation that elements and attributes within the result tree will carry. The permitted values and their semantics are described in 25.4.2 Validating Document Nodes25.4.2 Validating Document Nodes.The optional attributes type and validation may be used on the xsl:document instruction to validate the contents of the new document, and to determine the type annotation that elements and attributes within the result tree will carry. The permitted values and their semantics are described in 26.4.2 Validating Document Nodes25.4.2 Validating Document Nodes26.4.225.4.2 Validating Document Nodes.

The base URI of the new document node is taken from the base URI of the xsl:document instruction.

The document-uri and unparsed-entities properties of the new document node are set to empty.

<xsl:variable name="tree" as="document-node()">
  <xsl:document validation="strict">
    <xsl:apply-templates/>
  </xsl:document>
</xsl:variable>

11.6 Creating Processing Instructions

<!-- Category: instruction -->
<xsl:processing-instruction
  name = { ncname }
  select? = expression >
  <!-- Content: sequence-constructor -->
</xsl:processing-instruction>

The xsl:processing-instruction element is evaluated to create a processing instruction node.

The xsl:processing-instruction element has a requiredname attribute that specifies the name of the processing instruction node. The value of the name attribute is interpreted as an attribute value template.

The string value of the new processing-instruction node may be defined either by using the select attribute, or by the sequence constructor that forms the content of the xsl:processing-instruction element. These are mutually exclusive: if the select attribute is present then the sequence constructor must be empty, and if the sequence constructor is non-empty then the select attribute must be absent. If the select attribute is absent and the sequence constructor is empty, then the string value of the new processing-instruction node will be a zero-length string. The way in which the value is constructed is specified in 5.8.2 Constructing Simple Content.

[ERR XTSE0880] It is a static error if the select attribute of the xsl:processing-instruction element is present unless the element has empty content.

Except in error situations, the result of evaluating the xsl:processing-instruction instruction is a single node, the newly constructed processing instruction node.

<xsl:processing-instruction name="xml-stylesheet"
  select="('href=&quot;book.css&quot;', 'type=&quot;text/css&quot;')"/>

<?xml-stylesheet href="book.css" type="text/css"?>

[ERR XTDE0890] It is a dynamic error if the effective value of the name attribute is not both an NCName^Names and a PITarget^XML.

If the result of evaluating the content of the xsl:processing-instruction contains the string ?>, this string is modified by inserting a space between the ? and > characters.

The base URI of the new processing-instruction is copied from the base URI of the xsl:processing-instruction element in the stylesheet. (Note, however, that this is only relevant when creating a parentless processing instruction. When the new processing instruction is copied to form a child of an element or document node, the base URI of the new copy is taken from that of its new parent.)

11.9 Copying Nodes

15.3 Selecting the Sequences to be Merged

<xsl:merge-source
  name? = ncname
  for-each-item? = expression
  for-each-source? = expression
  select = expression
  streamable? = boolean
  use-accumulators? = tokens〔''〕
  sort-before-merge? = boolean〔'no'〕
  validation? = "strict" | "lax" | "preserve" | "strip"
  type? = eqname >
  <!-- Content: xsl:merge-key+ -->
</xsl:merge-source>

Each xsl:merge-source element defines one or more merge input sequences.

The name attribute provides a means of distinguishing items from different merge sources within the xsl:merge-action instructions. If the name attribute is present on an xsl:merge-source element, then it must not be equal to the name attribute of any sibling xsl:merge-source element. If the name attribute is absent, then an implementation-dependent name, different from all explicitly specified names, is allocated to the merge source.

[ERR XTSE3195] If the for-each-item attribute is present then the for-each-source, use-accumulators, and streamable attributes must all be absent. If either or both of the use-accumulators or streamable attributes is present then the for-each-source attribute must be present. If the for-each-source attribute is present then the for-each-item attribute must be absent. [XSLT 3.0 Erratum E40, bugs 30265 and 30378].

The use-accumulators attribute defines the set of accumulators that are applicable to the streamed document, as explained in 18.2.2 Applicability of Accumulators.

If neither of for-each-item and for-each-source is present, the xsl:merge-source element defines a single merge input sequence. This sequence is the result of evaluating the expression in the select attribute. This is evaluated using the dynamic context of the containing xsl:merge instruction. This sequence will be merged with the sequences defined by other xsl:merge-source elements, if present.

When the for-each-item attribute is present, the xsl:merge-source element defines a collection of merge input sequences. The selection of items in these input sequences is a two-stage process: the for-each-item attribute of the xsl:merge-source element is an expression that selects a sequence of anchor items, and for each anchor item, the select attribute is evaluated to select the items that make up one merge input sequence. The for-each-item expression is evaluated with the dynamic context of the containing xsl:merge instruction, while the select attribute is evaluated with the focus for the evaluation as follows:

• The context item is the anchor item

• The context position is the position of the anchor item within the sequence of anchor items

• The context size is the number of anchor items.

When the for-each-source attribute is present, its value must be an expression that returns a sequence of URIs. The expression is evaluated with the same dynamic context as the containing xsl:merge instruction. The expected type of the expression is xs:string*, and the actual result of the expression is converted to this type using the coercion rules. Each of these URIs is used to obtain a document node. Each must be a valid URI reference. If it is an absolute URI reference, it is used as is; if it is a relative URI reference, it is made absolute by resolving it against the base URI of the xsl:merge-source element. The process of obtaining a document node given a URI is the same as for the doc function, and may trigger the same error conditions. However, unlike the doc function, the xsl:merge instruction offers no guarantee that the resulting document will be stable (that is, that multiple calls specifying the same URI will return the same document). The resulting document nodes act as the anchor items. These anchor items are then used in the same way as a sequence of anchor items selected directly using the for-each-item attribute: in particular, the focus is determined in the same way.

The attributes validation and type are used to control schema validation of documents read by virtue of their appearance in the result of the for-each-source expression. These attributes are mutually exclusive [see ERR XTSE1505]. If the for-each-source attribute is absent, then the validation and type attributes must both be absent. The process of validation follows the rules defined in 26.4 Validation26.4 Validation [XSLT 3.0 Erratum E44, bug 30384].The attributes validation and type are used to control schema validation of documents read by virtue of their appearance in the result of the for-each-source expression. These attributes are mutually exclusive [see ERR XTSE1505]. If the for-each-source attribute is absent, then the validation and type attributes must both be absent. The process of validation follows the rules defined in 25.4 Validation25.4 Validation [XSLT 3.0 Erratum E44, bug 30384].The attributes validation and type are used to control schema validation of documents read by virtue of their appearance in the result of the for-each-source expression. These attributes are mutually exclusive [see ERR XTSE1505]. If the for-each-source attribute is absent, then the validation and type attributes must both be absent. The process of validation follows the rules defined in 26.4 Validation25.4 Validation26.425.4 Validation [XSLT 3.0 Erratum E44, bug 30384].

If the sort-before-merge attribute is absent or has the value no, then each merge input sequence must already be in the correct order for merging (a dynamic error occurs if it is not). If the attribute is present with the value yes, then each input sequence will first be sorted to ensure that it is in the correct order. The sorting is carried out as if by evaluating an xsl:perform-sort instruction with xsl:sort children corresponding one-to-one with the xsl:merge-key children of the xsl:merge-source element, differing only (a) in the change of element name, and (b) in the addition of the attribute stable="yes" to the first such element. [XSLT 3.0 Erratum E41, bug 30380].

<xsl:merge-source for-each-source="'log-A.xml', 'log-B.xml'"
                  streamable="yes"
                  select="events/event">
   <xsl:merge-key select="@timestamp" order="ascending"/>
</xsl:merge-source>