XSL Transformations (XSLT) Version 2.1 -- Review Version

1 Introduction

1.1 What is XSLT?

This specification defines the syntax and semantics of the XSLT 2.1 language.

[Definition: A transformation in the XSLT language is expressed in the form of a stylesheet, whose syntax is well-formed XML [XML 1.0] conforming to the Namespaces in XML Recommendation [Namespaces in XML].]

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

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

A transformation expressed in XSLT describes rules for transforming zero or more source trees into one or more result trees. The structure of these trees is described in [Data Model]. The transformation is achieved by a set of template rules. A template rule associates a pattern, which matches nodes in the source document, with a sequence constructor. In many cases, evaluating the sequence constructor will cause new nodes to be constructed, which can be used to produce part of a result tree. The structure of the result trees can be completely different from the structure of the source trees. In constructing a result tree, nodes from the source trees can be filtered and reordered, and arbitrary structure can be added. This mechanism allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

[Definition: A stylesheet may consist of several stylesheet modules, contained in different XML documents. For a given transformation, one of these functions as the principal stylesheet module. The complete stylesheet is assembled by finding the stylesheet modules referenced directly or indirectly from the principal stylesheet module using xsl:include and xsl:import elements: see 3.10.2 Stylesheet Inclusion and 3.10.3 Stylesheet Import.]

1.2 What's New in XSLT 2.1?

The main focus for enhancements in XSLT 2.1 is the requirement to enable streaming of source documents. This is needed when source documents become too large to hold in main memory, and also for applications where it is important to start delivering results before the entire source document is available.

While implementations of XSLT that use streaming have always been theoretically possible, the nature of the language has made it very difficult to achieve this in practice. The approach adopted in this specification is twofold: it identifies a set of restrictions which, if followed by stylesheet authors, will enable implementations to adopt a streaming mode of operation without placing excessive demands on the optimization capabilities of the processor; and it provides new constructs to indicate that streaming is required, or to express transformations in a way that makes it easier for the processor to adopt a streaming execution plan.

Capabilities provided in this category include:

A new xsl:stream instruction, which reads and processes a source document in streaming mode;
The ability to declare that a mode is a streaming mode, in which case all the template rules using that mode must be streamable;
A new xsl:iterate instruction, which iterates over the items in a sequence, allowing parameters for the processing of one item to be set during the processing of the previous item;
A new xsl:merge instruction, allowing multiple input streams to be merged into a single output stream;
A new xsl:fork instruction, allowing multiple computations to be performed in parallel during a single pass through an input document.

Other significant features in XSLT 2.1 include:

An xsl:evaluate instruction allowing evaluation of XPath expressions that are dynamically constructed as strings, or that are read from a source document;
Enhancements to the syntax of patterns, in particular enabling the matching of atomic values as well as nodes;
An xsl:try instruction to allow recovery from dynamic errors;
The element xsl:context-item, used to declare the stylesheet's expectations of the initial context item (notably, its type), given the initial mode.

XSLT 2.1 also delivers enhancements made to the XPath language and to the standard function library, including the following:

Variables can now be bound in XPath using the let expression.
Functions are now first class values, and can be passed as arguments to other (higher-order) functions, making XSLT a fully-fledged functional programming language.
A number of new functions are available, for example trigonometric functions, and the functions parse^FO and serialize^FO to convert between lexical and tree representations of XML.

The XSL Working Group is designing other new features which it hopes to include in the final XSLT 2.1 Recommendation, but which are not yet advanced enough to include in this Working Draft.

A full list of changes is at J Changes since XSLT 2.0.

2 Concepts

2.1 Terminology

For a full glossary of terms, see B Glossary.

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

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

[Definition: The term 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 final output of a transformation. Once created, the contents of a final result tree are not accessible within the stylesheet itself.] The xsl:result-document instruction always creates a final result tree, and a final result tree may also be created implicitly by the initial template. The conditions under which this happens are described in 2.4 Executing a Transformation. A final result tree may be serialized as described in 23 Serialization.

[Definition: The term source tree means any tree provided as input to the transformation. This includes the document containing the initial context item if any, documents containing nodes supplied as the values of stylesheet parameters, documents obtained from the results of functions such as document, doc^FO, and collection^FO, documents read using the xsl:stream 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.

The use of the term "tree" in phrases such as source tree, result tree, and temporary tree is not confined to documents that the processor materializes in memory in their entirety. The processor may, and in some cases must, use streaming techniques to limit the amount of memory used to hold source and result documents. When streaming is used, the nodes of the tree may never all be in memory at the same time, but at an abstract level the information is still modeled as a tree of nodes, and the document is therefore still described as a tree.

In this specification the phrases must, must not, should, should not, may, required, and recommended, when used in normative text and rendered in 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 24 Conformance.

Where the phrase must, must not, or required relates to a stylesheet then the processor must enforce this constraint on stylesheets by reporting 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 2.1] or the XDM specification [Data Model]. Particular attention is drawn to the following:

[Definition: The term atomization is defined in Section 2.4.2 Atomization^XP21. It is a process that takes as input a sequence of items, and returns a sequence of atomic values, in which the nodes are replaced by their typed values as defined in [Data Model].] For some items (for example, elements with element-only content, and function items), atomization generates a dynamic error.
[Definition: The term typed value is defined in Section 5.15 typed-value Accessor^DM11. Every node except an element defined in the schema with 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^DM11. 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.1.1 Static Context^XP21. 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 2.1 and XPath 1.0.]

[Definition: The term core function means a function that is specified in [Functions and Operators] and that is in the standard function namespace.]

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 C 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 C Element Syntax Summary. The meaning of 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.

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.
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 similar way 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, other than xsl:import, 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 only affects whether it is allowed in the content of elements that allow a sequence constructor or other-declarations.

Example: Syntax Notation

This example illustrates the notation used to describe XSLT elements.

 <xsl:example-element select = expression debug? = { "yes" | "no" } >  </xsl:example-element>

This example defines a (non-existent) element xsl:example-element. The element is classified as an instruction. It takes a mandatory select attribute, whose value is an XPath expression, and an optional debug attribute, whose value must be either yes or no; the curly brackets indicate that the value can be defined as an attribute value template, allowing a value such as debug="{$debug}", where the variable debug is evaluated to yield "yes" or "no" at run-time.

The content of an xsl:example-element instruction is defined to be a sequence of zero or more xsl:variable and xsl:param elements, followed by an xsl:sequence element.

[ERR XTSE0010] A static error is signaled 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.

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 non-recoverable 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 signal 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.9 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.] All constructs that are deprecated in this specification are also (as it happens) optional features that implementations are not required to provide.

Note:

This working draft includes a non-normative XML Schema for XSLT stylesheet modules (see G Schema for XSLT Stylesheets). The syntax summaries described in this section are normative.

XSLT defines a set of standard functions which are additional to those defined in [Functions and Operators]. The signatures of these functions are described using the same notation as used in [Functions and Operators]. The names of these functions are all 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.

Implementations may allow a transformation to run as two or more phases, for example parsing, compilation and execution. Such a distinction is outside the scope of this specification, which treats transformation as a single process controlled using a set of stylesheet modules, supplied in the form of XML documents.

The following information is supplied to execute a transformation:

The stylesheet module that is to act as the principal stylesheet module for the transformation. The complete stylesheet is assembled by recursively expanding the xsl:import and xsl:include declarations in the principal stylesheet module, as described in 3.10.2 Stylesheet Inclusion and 3.10.3 Stylesheet Import.
A set (possibly empty) of values for stylesheet parameters (see 9.5 Global Variables and Parameters). These values are available for use within expressions in the stylesheet.
[Definition: An item that acts as the initial context item for the transformation. This item is accessible within the stylesheet as the initial value of the XPath expressions . (dot) and self::node(), as described in 5.4.3.1 Maintaining Position: the Focus ].

The value that can be supplied as the initial context item is constrained by the xsl:context-item element, if defined for the chosen initial mode.

If no initial context item is supplied, then the context item, context position, and context size will initially be undefined, and the evaluation of any expression that references these values will result in a dynamic error. (Note that the initial context size and context position will always be 1 (one) when an initial context item is supplied, and will be undefined if no initial context item is supplied).
Optionally, the name of a named template which is to be executed as the entry point to the transformation. This template must exist within the stylesheet. If no named template is supplied, then the transformation starts with the template rule that best matches the initial context item, according to the rules defined in 6.4 Conflict Resolution for Template Rules. Either a named template, or an initial context item, or both, must be supplied.
Optionally, an initial mode.

[Definition: The initial mode, if specified, must either be the default mode, or a mode that is explicitly named in the mode attribute of an xsl:template declaration within the stylesheet. If an initial mode is supplied, then in searching for the template rule that best matches the initial context item, the processor considers only those rules that apply to the initial mode. If no initial mode is supplied, then the mode named in the default-mode attribute of the xsl:stylesheet element of the principal stylesheet module is used; or in the absence of such an attribute, the unnamed mode.]

Note:

If the initial mode is a streamable mode, then streaming will only be possible if the initial context item is a node that is supplied in a form that allows such processing: for example, as a reference to a stream of parsing events.

Note:

The design of the API for invoking a transformation should provide some means for users to designate the unnamed mode as the initial mode in cases where it is not the default mode.
A base output URI. [Definition: The base output URI is a URI to be used as the base URI when resolving a relative URI reference allocated to a final result tree. If the transformation generates more than one final result tree, then typically each one will be allocated a URI relative to this base URI. ] The way in which a base output URI is established is implementation-defined.
A mechanism for obtaining a document node and a media type, given an absolute URI. The total set of available documents (modeled as a mapping from URIs to document nodes) forms part of the context for evaluating XPath expressions, specifically the doc^FO function. The XSLT document function additionally requires the media type of the resource representation, for use in interpreting any fragment identifier present within a URI Reference.

Note:

The set of documents that are available to the stylesheet is implementation-dependent, as is the processing that is carried out to construct a tree representing the resource retrieved using a given URI. Some possible ways of constructing a document (specifically, rules for constructing a document from an Infoset or from a PSVI) are described in [Data Model].

[ERR XTDE0040] It is a non-recoverable dynamic error if the invocation of the stylesheet specifies a template name that does not match the expanded-QName of a named template defined in the stylesheet.

[ERR XTDE0045] It is a non-recoverable dynamic error if the invocation of the stylesheet specifies an initial mode (other than the default mode) that does not match the expanded-QName in the mode attribute of any template defined in the stylesheet.

[ERR XTDE0047] It is a non-recoverable dynamic error if the invocation of the stylesheet specifies both an initial mode and an initial template.

[ERR XTDE0050] It is a non-recoverable dynamic error if the stylesheet that is invoked declares a visible stylesheet parameter with required="yes" and no value for this parameter is supplied during the invocation of the stylesheet. A stylesheet parameter is visible if it is not masked by another global variable or parameter with the same name and higher import precedence.

[Definition: The transformation is performed by evaluating an initial template. If a named template is supplied when the transformation is initiated, then this is the initial template; otherwise, the initial template is the template rule selected according to the rules of the xsl:apply-templates instruction for processing the initial context item in the initial mode.]

Parameters passed to the transformation by the client application are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the initial template. All template parameters within the initial template to be executed will take their default values.

[ERR XTDE0060] It is a non-recoverable dynamic error if the initial template defines a template parameter that specifies required="yes".

A stylesheet can process further source documents in addition to those supplied when the transformation is invoked. These additional documents can be loaded using the functions document (see 19.1.1 The document function) or doc^FO or collection^FO (see [Functions and Operators]), or using the xsl:stream instruction; alternatively, they can be supplied as stylesheet parameters (see 9.5 Global Variables and Parameters), or returned as the result of an extension function (see 21.1 Extension Functions).

2.4 Executing a Transformation

[Definition: A stylesheet contains a set of template rules (see 6 Template Rules). A template rule has three parts: a pattern that is matched against nodes, a (possibly empty) set of template parameters, and a sequence constructor that is evaluated to produce a sequence of items.] In many cases these items are newly constructed nodes, which are then written to a result tree.

A transformation as a whole is executed by evaluating the sequence constructor of the initial template as described in 5.7 Sequence Constructors.

The result sequence produced by evaluating the initial template is handled as follows:

If the initial template has an as attribute, then the result sequence of the initial template is checked against the required type in the same way as for any other template.
If the result sequence is non-empty, then it is used to construct an implicit final result tree, following the rules described in 5.7.1 Constructing Complex Content: the effect is as if the initial template T were called by an implicit template of the form:
```
<xsl:template name="IMPLICIT">
  <xsl:result-document href="">
    <xsl:call-template name="T"/>
  </xsl:result-document>
</xsl:template>
```

An implicit result tree is also created when the result sequence is empty, provided that no xsl:result-document instruction has been evaluated during the course of the transformation. In this situation the implicit result tree will consist of a document node with no children.

Note:

This means that there is always at least one result tree. It also means that if the content of the initial template is a single xsl:result-document instruction, as in the example above, then only one result tree is produced, not two. It is useful to make the result document explicit as this is the only way of invoking document-level validation.

If the result of the initial template is non-empty, and an explicit xsl:result-document instruction has been evaluated with the empty attribute href="", then an error will occur [see ERR XTDE1490], since it is not possible to create two final result trees with the same URI.

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

Extension instructions are described in 21.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;
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:try, xsl:for-each, xsl:for-each-group, xsl:fork, xsl:iterate and its subordinate instructions xsl:next-iteration and xsl:break;
instructions that invoke templates: xsl:apply-templates, xsl:apply-imports, xsl:call-template, xsl:next-match;
Instructions that declare variables: xsl:variable, xsl:param;
other specialized instructions: xsl:number, xsl:analyze-string, xsl:message, xsl:result-document, xsl:stream, xsl:perform-sort, xsl:merge.

Often, a sequence constructor will include an xsl:apply-templates instruction, which selects a sequence of nodes to be processed. Each of the selected nodes is processed by searching the stylesheet for a matching template rule and evaluating the sequence constructor of that template rule. The resulting sequences of items are concatenated, in order, to give the result of the xsl:apply-templates instruction, as described in 6.3 Applying Template Rules; this sequence is often added to a result tree. Since the sequence constructors of the selected template rules may themselves contain xsl:apply-templates instructions, this results in a cycle of selecting nodes, identifying template rules, constructing sequences, and constructing result trees, that recurses through a source tree.

2.5 The Evaluation Context

The results of some expressions and instructions in a stylesheet may depend on information provided contextually. This context information is divided into two categories: the static context, which is known during static analysis of the stylesheet, and the dynamic context, which is not known until the stylesheet is evaluated. Although information in the static context is known at analysis time, it is sometimes used during stylesheet evaluation.

Some context information can be set by means of declarations within the stylesheet itself. For example, the namespace bindings used for any XPath expression are determined by the namespace declarations present in containing elements in the stylesheet. Other information may be supplied externally or implicitly: an example is the current date and time.

The context information used in processing an XSLT stylesheet includes as a subset all the context information required when evaluating XPath expressions. The XPath 2.1 specification defines a static and dynamic context that the host language (in this case, XSLT) may initialize, which affects the results of XPath expressions used in that context. XSLT augments the context with additional information: this additional information is used firstly by XSLT constructs outside the scope of XPath (for example, the xsl:sort element), and secondly, by functions that are defined in the XSLT specification (such as key and current-group) that are available for use in XPath expressions appearing within a stylesheet.

The static context for an expression or other construct in a stylesheet is determined by the place in which it appears lexically. The details vary for different components of the static context, but in general, elements within a stylesheet module affect the static context for their descendant elements within the same stylesheet module.

The dynamic context is maintained as a stack. When an instruction or expression is evaluated, it may add dynamic context information to the stack; when evaluation is complete, the dynamic context reverts to its previous state. An expression that accesses information from the dynamic context always uses the value at the top of the stack.

The most commonly used component of the dynamic context is the context item. This is an implicit variable whose value is the item currently being processed (it may be a node, an atomic value, or a function item). The value of the context item can be referenced within an XPath expression using the expression . (dot).

Full details of the static and dynamic context are provided in 5.4 The Static and Dynamic Context.

2.6 Parsing and Serialization

An XSLT stylesheet describes a process that constructs a set of final result trees from a set of source trees.

The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [Data Model]. 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 [Data Model], 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 23 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 report 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.7 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 21.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 21.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 21 Extensibility and Fallback.

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

2.8 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 the SequenceType^XP21 syntax defined in [XPath 2.1].

[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 stylesheet are referred to as the in-scope schema components. This set is the same throughout all the modules of a stylesheet.]

The conformance rules for XSLT 2.1, defined in 24 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^FO function) and other constructs may produce different results depending on the data type (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.13 Built-in Types. The set of built-in types varies between a basic XSLT processor and a schema-aware XSLT processor.

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:

Example: Asserting the Required Type of the Source Document

<xsl:mode initial="yes">
  <xsl:context-item required="yes"
                    as="document-node(schema-element(my:invoice))"/>
</xsl:mode>

This example will cause the transformation to fail with an error message when the initial mode is the unnamed mode, unless the document element of the source document is valid against the top-level element declaration my:invoice, and has been annotated as such.

Equally, 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:

Example: Requesting Validation of the Result Document

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

This example will cause the transformation to fail with an error message unless the document element of the result document is valid against the top-level element declaration xhtml:html.

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 [Data Model]. The implementation may choose one of several strategies for dealing with this situation:

The processor may signal a non-recoverable dynamic error if a source document is found to contain a type annotation that is not known to the processor.
The processor may maintain additional metadata, beyond that described in [Data Model], 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.
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.
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.10 Error Handling) type errors that are detected early may be reported 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 final result tree, or in temporary trees. This can be done in a number of ways.

It is possible to request explicit validation of a complete document, that is, a tree rooted at a document node. This applies both to temporary trees constructed using the xsl:document (or xsl:copy) instruction and also to final result trees constructed using xsl:result-document. 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 22.2 Validation.

2.9 Streaming

[Definition: The term streaming refers to a manner of processing in which documents (such as source and result documents) are not represented by a complete tree of nodes occupying memory proportional to document size, but instead are processed "on the fly" as a sequence of events, similar in concept to the stream of events notified by an XML parser to represent markup in lexical XML.]

[Definition: A streamed document is a source tree that is processed using streaming, that is, without constructing a complete tree of nodes in memory.]

[Definition: A streamed node is a node in a streamed document.]

Many processors implementing earlier versions of this specification have adopted an architecture that allows streaming of the result tree directly to a serializer, without first materializing the complete result tree in memory. Streaming of the source tree, however, has proved to be more difficult without subsetting the language. This has created a situation where documents exceeding the capacity of virtual memory could not be transformed. XSLT 2.1 therefore introduces facilities allowing stylesheets to be written in a way that makes streaming of source documents possible, without excessive reliance on processor-specific optimization techniques.

Streaming achieves two important objectives: it allows large documents to be transformed without requiring correspondingly large amounts of memory; and it allows the processor to start producing output before it has finished receiving its input, thus reducing latency.

This specification does not attempt to legislate precisely which implementation techniques fall under the definition of streaming, and which do not. A number of techniques are available that reduce memory requirements, while still requiring a degree of buffering, or allocation of memory to partial results. A stylesheet that requests streaming of a source document is indicating that the processor should avoid assuming that the entire source document will fit in memory; in return, the stylesheet must be written in a way that makes streaming possible. This specification does not attempt to describe the algorithms that the processor should actually use, or to impose quantitative constraints on the resources that these algorithms should consume.

Nothing in this specification, nor in its predecessors [XSLT 1.0] and [XSLT 2.0], prevents a processor using streaming whenever it sees an opportunity to do so. However, experience has shown that in order to achieve streaming, it is often necessary to write stylesheet code in such a way as to make this possible. Therefore, XSLT 2.1 provides explicit constructs allowing the stylesheet author to request streaming, and defines explicit static constraints on the structure of the code which are designed to make streaming possible.

A processor that claims conformance with the streaming option offers a guarantee that when streaming is requested for a source document, and when the stylesheet conforms to the rules that make the processing guaranteed-streamable, then an algorithm will be adopted in which memory consumption is either completely independent of document size, or increases only very slowly as document size increases, allowing documents to be processed that are orders-of-magnitude larger than the physical memory available. A processor that does not claim conformance with the streaming option must still process a stylesheet and deliver the correct results, but is not required to use streaming algorithms, and may therefore fail with out-of-memory errors when presented with large source documents.

Apart from the fact that there are constructs to request streaming, and rules that must be followed to guarantee that streaming is possible, the language has been designed so there are as few differences as possible between streaming and non-streaming evaluation. The semantics of the language continue to be expressed in terms of the XDM data model, which is substantively unchanged; but readers must take care to observe that when terms like "node" and "axis" are used, the concepts are completely abstract and may have no direct representation in the run-time execution environment.

Streamed processing of a document can be initiated in one of two ways:

The initial mode can be declared as a streamable mode. In this case the initial context item will generally be a document node, and it will be supplied by the calling application in a form that allows streaming (that is, in some form other than a tree in memory; for example, as a reference to a push or pull XML parser primed to deliver a stream of events). The type of the initial context item can be constrained using the xsl:context-item element. In this case the template rule that matches the document node (in this mode) must be a streamable template, which means that it (as well as all other template rules using this mode) must satisfy certain statically checkable constraints to ensure that streaming is possible.
Streamed processing of any document can be initiated using the xsl:stream instruction. This has an attribute href whose value is the URI of a document to be processed using streaming, and the actual processing to be applied is defined by the instructions written as children of the xsl:stream instruction. These instructions must satisfy the same rules as for a streamable template.

The rules for streamability, which are defined in detail in 18.4 Streamability Analysis, impose two main constraints:

The only nodes reachable from the node that is currently being processed are its attributes and namespaces, its ancestors and their attributes and namespaces, and its descendants and their attributes and namespaces. The siblings of the node, and the siblings of its ancestors, are not reachable in the tree, and any attempt to use their values is a static error. However, constructs (for example, simple forms of xsl:number, and simple positional patterns) that require knowledge of the number of preceding elements by name are permitted.
When processing a given node in the tree, each descendant node can only be visited once. Essentially this allows two styles of processing: either visit each of the children once, and then process that child with the same restrictions applied; or process all the descendants in a single pass, in which case it is not possible while processing a descendant to make any further downward selection.

The second restriction, that only one visit to the children is allowed, means that XSLT code that was not designed with streaming in mind will often need to be rewritten to make it streamable. In many cases it is possible to do this using a technique sometimes called windowing or burst-mode streaming (note this is not quite the same meaning as windowing in XQuery 1.1.). Many XML documents consist of a large number of elements, each of manageable size, representing transactions or business objects where each such element can be processed independently: in such cases, an effective design pattern is to write a streaming transformation that takes a snapshot of each element in turn, processing the snapshot using the full power of the XSLT language. Each snapshot is a tree built in memory and is therefore fully navigable. For details see the snapshot and copy-of functions.

Streaming applications often fall into one of the following categories:

Aggregation applications, where a single aggregation operation (perhaps count^FO, sum^FO, exists^FO, or distinct-values^FO) is applied to a set of elements selected from the streamed source document by means of a path expression.
Record-at-a-time applications, where the source document consists of a long sequence of elements with similar structure ("records"), and each "record" is processed using the same logic, independently of any other "records". This kind of processing is facilitated using the snapshot and copy-of function mentioned earlier.
Grouping applications, where the output follows the structure of the input, except that an extra layer of hierarchy is added. For example, the input might be a flat series of banking transactions in date/time order, and the output might contain the same transactions grouped by date.
Accumulator applications, which are the same as record-at-a-time applications, except that the processing of one "record" might depend on data encountered earlier in the document. A classical example is processing a sequence of banking transactions in which the input transaction contains a debit or credit amount, and the output adds a running total (the account balance). The xsl:iterate instruction has been introduced to facilitate this style of processing.
Isomorphic transformations, in which there is an ordered (often largely one-to-one) relationship between the nodes of the source tree and the nodes of the result tree: for example, transformations that involve only the renaming or selective deletion of nodes, or scalar manipulations of the values held in the leaf nodes. Such transformations are most conveniently expressed using recursive application of template rules. This is possible with a streamed input document only if all the template rules adhere to the constraints required for streamability. To enforce these rules, while still allowing unrestricted processing of other documents within the same transformation, all streaming evaluation must be carried out using a specific mode, which is declared to be a streaming mode by means of an xsl:mode declaration in the stylesheet.

There are important classes of application in which streaming is possible only if multiple streams can be processed in parallel. This specification therefore provides facilities:

allowing two sorted input sequences to be merged into one sorted output sequence (the xsl:merge instruction)
allowing multiple output sequences to be generated during a single pass of an input sequence (the xsl:fork instruction).

These facilities have been designed in such a way that they can readily be implemented using streaming, that is, without materializing the input or output sequences in memory.

Issue 1 (streaming-pessimism):

The design adopted in this specification works on the basis that decisions about streamability should be made statically (at compile time). Sometimes this means taking a pessimistic approach, that is, rejecting a construct as non-streamable based on worst-case assumptions. Two examples of this are (a) disallowing <xsl:with-param name="p" select="@code"/> when calling a streamable template, on the grounds that the called template might perform disallowed navigation from the attribute node; (b) disallowing use of the descendant axis in cases where it might select two elements, one of which is an ancestor of the other. An alternative design approach would allow optimistic assumptions to be made in such cases, creating the risk of dynamic errors: for example it might be a dynamic error in the first case if the called template performs disallowed navigation from the attribute node, and in the second case if the descendant axis actually selects a node that is a descendant of another selected node. The decision to make the analysis pessimistic interacts with the strategy for fallback if streaming is not possible; a non-streaming fallback is feasible if decisions are made statically, but is not realistically possible if the problems are only detected at execution time. The Working Group welcomes discussion of this decision.

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

Errors classified in this specification as static errors must be signaled by all implementations: that is, the processor must indicate that the error is present. A static error must be signaled even if it occurs in a part of the stylesheet that is never evaluated. Static errors are never recoverable. After signaling a static error, a processor may continue for the purpose of signaling additional errors, but it must eventually terminate abnormally without producing any final result tree.

There is an exception to this rule when the stylesheet specifies forwards compatible behavior (see 3.9 Forwards Compatible Processing).

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.

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

[Definition: Some dynamic errors are classed as recoverable errors. When a recoverable error occurs, this specification allows the processor either to signal the error (by reporting the error condition and terminating execution) or to take a defined recovery action and continue processing.] It is implementation-defined whether the error is signaled or the recovery action is taken. If the processor chooses to signal the error rather than taking the recovery action, the error is then treated in the same way as a non-recoverable dynamic error and is therefore eligible to be caught using xsl:try/xsl:catch.

[Definition: If an implementation chooses to recover from a recoverable dynamic error, it must take the optional recovery action defined for that error condition in this specification.]

When the implementation makes the choice between signaling a dynamic error or recovering, it is not restricted in how it makes the choice; for example, it may provide options that can be set by the user. When an implementation chooses to recover from a dynamic error, it may also take other action, such as logging a warning message.

[Definition: A dynamic error that is not recoverable is referred to as a non-recoverable dynamic error. When a non-recoverable dynamic error occurs, the processor must signal the error, and (unless the error is caught using xsl:catch) the transformation fails.]

Note:

The term non-recoverable is retained from earlier XSLT versions, and implies that the processor will not recover from the error on its own initiative. However, the introduction of xsl:try and xsl:catch in XSLT 2.1 means that such errors can now be recovered by means of application logic.

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 the final result trees 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 signal 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 signal any dynamic errors that would arise if the construct were evaluated.

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

There are also some dynamic errors where the specification gives a processor license to signal 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.

The XPath specification states (see Section 2.3.1 Kinds of Errors^XP21) 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 reported as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be reported as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be signaled as dynamic errors, and signaled only if the XPath expression is actually evaluated.

Example: Errors in Constant Subexpressions

An XPath processor may report statically that the expression 1 div 0 fails with a "divide by zero" error. But suppose this XPath expression occurs in an XSLT construct such as:

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

Then the XSLT processor must not report an error, because the relevant XPath construct appears in a context where it will never be executed by an XSLT 2.0 or 2.1 processor. (An XSLT 1.0 processor will execute this code successfully, returning positive infinity, because it uses double arithmetic rather than decimal arithmetic.)

[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 signaled in the same way as a non-recoverable dynamic error. Alternatively, an implementation may signal 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 signaled statically.

Example: A Type Error

The following construct contains a type error, because 42 is not allowed as the value of the select expression of the xsl:number instruction (it must be a node). An implementation may optionally signal this as a static error, even though the offending instruction will never be evaluated, and the type error would therefore never be signaled as a dynamic error.

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

On the other hand, in the following example it is not possible to determine statically whether the operand of xsl:number will have a suitable dynamic type. An implementation may produce a warning in such cases, but it must not treat it as an error.

<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 signal any errors other than the first one that it detects. It is implementation-dependent which of the several errors is signaled. This applies both to static errors and to dynamic errors. An implementation is allowed to signal more than one error, but if any errors have been signaled, it must not finish as if the transformation were successful.

When a transformation signals 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 final result tree, it is still possible that errors may occur in serializing the result tree. For example, it may be impossible to serialize the result tree 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 23 Serialization, and in particular it must signal 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), RE (recoverable 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 reported either dynamically or statically. These error codes are used to label error conditions in this specification, and are summarized in D Summary of Error Conditions). They are provided primarily for ease of reference. Implementations may use these error codes when signaling errors, but they are not required to do so. An API specification, however, may require the use of error codes based on these QNames.

Errors defined in related specifications ([XPath 2.1], [Functions and Operators] [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 signaling 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 Stylesheet Structure

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

Note:

A stylesheet module is represented by an XDM element node (see [Data Model]). In the case of a standard stylesheet module, this will be an xsl:stylesheet or xsl:transform element. In the case of a simplified stylesheet module, it can be any element (not in the XSLT namespace) that has an xsl:version attribute.

Although stylesheet modules will commonly be maintained in the form of documents conforming to XML 1.0 or XML 1.1, this specification does not mandate such a representation. As with source trees, the way in which stylesheet modules are constructed, from textual XML or otherwise, is outside the scope of this specification.

A stylesheet module is either a standard stylesheet module or a simplified stylesheet module:

[Definition: A standard stylesheet module is a tree, or part of a tree, consisting of an xsl:stylesheet or xsl:transform element (see 3.6 Stylesheet Element) together with its descendant nodes and associated attributes and namespaces.]
[Definition: A simplified stylesheet module is a tree, or part of a tree, consisting of a literal result element together with its descendant nodes and associated attributes and namespaces. This element is not itself in the XSLT namespace, but it must have an xsl:version attribute, which implies that it must have a namespace node that declares a binding for the XSLT namespace. For further details see 3.7 Simplified Stylesheet Modules. ]

Both forms of stylesheet module (standard and simplified) can exist either as an entire XML document, or embedded as part of another XML document, typically but not necessarily a source document that is to be processed using the stylesheet.

[Definition: A standalone stylesheet module is a stylesheet module that comprises the whole of an XML document.]

[Definition: An embedded stylesheet module is a stylesheet module that is embedded within another XML document, typically the source document that is being transformed.] (see 3.11 Embedded Stylesheet Modules).

There are thus four kinds of stylesheet module:

standalone standard stylesheet modules
standalone simplified stylesheet modules
embedded standard stylesheet modules
embedded simplified stylesheet modules

3.1 XSLT Namespace

[Definition: The XSLT namespace has the URI http://www.w3.org/1999/XSL/Transform. It is used to identify elements, attributes, and other names that have a special meaning defined in this specification.]

Note:

The 1999 in the URI indicates the year in which the URI was allocated by the W3C. It does not indicate the version of XSLT being used, which is specified by attributes (see 3.6 Stylesheet Element and 3.7 Simplified Stylesheet Modules).

XSLT processors must use the XML namespaces mechanism [Namespaces in XML] to recognize elements and attributes from this namespace. Elements from the XSLT namespace are recognized only in the stylesheet and not in the source document. The complete list of XSLT-defined elements is specified in C Element Syntax Summary. Implementations must not extend the XSLT namespace with additional elements or attributes. Instead, any extension must be in a separate namespace. Any namespace that is used for additional instruction elements must be identified by means of the extension instruction mechanism specified in 21.2 Extension Instructions.

This specification uses a prefix of xsl: for referring to elements in the XSLT namespace. However, XSLT stylesheets are free to use any prefix, provided that there is a namespace declaration that binds the prefix to the URI of the XSLT namespace.

Note:

Throughout this specification, an element or attribute that is in no namespace, or an expanded-QName whose namespace part is an empty sequence, is referred to as having a null namespace URI.

Note:

The conventions used for the names of XSLT elements, attributes and functions are that names are all lower-case, use hyphens to separate words, and use abbreviations only if they already appear in the syntax of a related language such as XML or HTML. Names of types defined in XML Schema are regarded as single words and are capitalized exactly as in XML Schema. This sometimes leads to composite function names such as current-dateTime^FO.

3.2 Reserved Namespaces

[Definition: The XSLT namespace, together with certain other namespaces recognized by an XSLT processor, are classified as reserved namespaces and must be used only as specified in this and related specifications.] The reserved namespaces are those listed below.

The XSLT namespace, described in 3.1 XSLT Namespace, is reserved.
[Definition: The standard function namespace http://www.w3.org/2005/xpath-functions is used for functions in the function library defined in [Functions and Operators] and for standard functions defined in this specification.]
The namespace http://www.w3.org/2005/xpath-functions/math is used for mathematical functions in the function library defined in [Functions and Operators].
[Definition: The XML namespace, defined in [Namespaces in XML] as http://www.w3.org/XML/1998/namespace, is used for attributes such as xml:lang, xml:space, and xml:id.]
[Definition: The schema namespace http://www.w3.org/2001/XMLSchema is used as defined in [XML Schema Part 1]]. In a stylesheet this namespace may be used to refer to built-in schema datatypes and to the constructor functions associated with those datatypes.
[Definition: The schema instance namespace http://www.w3.org/2001/XMLSchema-instance is used as defined in [XML Schema Part 1]]. Attributes in this namespace, if they appear in a stylesheet, are treated by the XSLT processor in the same way as any other attributes.
[Definition: The standard error namespace http://www.w3.org/2005/xqt-errors is used for error codes defined in this specification and related specifications. It is also used for the names of certain predefined variables accessible within the scope of an xsl:catch element.]
The namespace http://www.w3.org/2000/xmlns/ is reserved for use as described in [Namespaces in XML]. No element or attribute node can have a name in this namespace, and although the prefix xmlns is implicitly bound to this namespace, no namespace node will ever define this binding.

Reserved namespaces may be used without restriction to refer to the names of elements and attributes in source documents and result documents. As far as the XSLT processor is concerned, reserved namespaces other than the XSLT namespace may be used without restriction in the names of literal result elements and user-defined data elements, and in the names of attributes of literal result elements or of XSLT elements: but other processors may impose restrictions or attach special meaning to them. Reserved namespaces must not be used, however, in the names of stylesheet-defined objects such as variables and stylesheet functions.

Note:

With the exception of the XML namespace, any of the above namespaces that are used in a stylesheet must be explicitly declared with a namespace declaration. Although conventional prefixes are used for these namespaces in this specification, any prefix may be used in a user stylesheet.

[ERR XTSE0080] It is a static error to use a reserved namespace in the name of a named template, a mode, an attribute set, a key, a decimal-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.

3.3 Extension Attributes

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

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

Note:

Extension attributes may be used to modify the behavior of extension functions and extension instructions. They may be used to select processing options in cases where the specification leaves the behavior implementation-defined or implementation-dependent. They may also be used for optimization hints, for diagnostics, or for documentation.

Extension attributes may also be used to influence the behavior of the serialization methods xml, xhtml, html, or text, to the extent that the behavior of the serialization method is implementation-defined or implementation-dependent. For example, an extension attribute might be used to define the amount of indentation to be used when indent="yes" is specified. If a serialization method other than one of these four is requested (using a prefixed QName in the method parameter) then extension attributes may influence its behavior in arbitrary ways. Extension attributes must not be used to cause the four standard serialization methods to behave in a non-conformant way, for example by failing to report serialization errors that a serializer is required to report. An implementation that wishes to provide such options must create a new serialization method for the purpose.

An implementation that does not recognize the name of an extension attribute, or that does not recognize its value, must perform the transformation as if the extension attribute were not present. As always, it is permissible to produce warning messages.

The namespace used for an extension attribute will be copied to the result tree in the normal way if it is in scope for a literal result element. This can be prevented using the [xsl:]exclude-result-prefixes attribute.

Example: An Extension Attribute for xsl:message

The following code might be used to indicate to a particular implementation that the xsl:message instruction is to ask the user for confirmation before continuing with the transformation:

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

Implementations that do not recognize the namespace http://vendor.example.com/xslt/extensions will simply ignore the extra attribute, and evaluate the xsl:message instruction in the normal way.

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

3.4 XSLT Media Type

The media type application/xslt+xml has been registered for XSLT stylesheet modules.

The definition of the media type is at [XSLT Media Type].

This media type should be used for an XML document containing a standard stylesheet module at its top level, and it may also be used for a simplified stylesheet module. It should not be used for an XML document containing an embedded stylesheet module.

3.5 Standard Attributes

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

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:version, xsl:exclude-result-prefixes, xsl:extension-element-prefixes, xsl:xpath-default-namespace, xsl:default-collation, or xsl:use-when.

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:]version, [xsl:]xpath-default-namespace, and [xsl:]default-collation, 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.12 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 and xsl:transform elements only. This reflects the fact that these attributes are often used on the xsl:stylesheet element only, in which case they apply to the entire stylesheet module.

Note that the effect of these attributes does not extend to stylesheet modules referenced by xsl:include or xsl:import declarations.

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

[xsl:]version: see 3.8 Backwards Compatible Processing and 3.9 Forwards Compatible Processing
[xsl:]xpath-default-namespace: see 5.2 Unprefixed QNames in Expressions and Patterns
[xsl:]exclude-result-prefixes: see 11.1.3 Namespace Nodes for Literal Result Elements
[xsl:]extension-element-prefixes: see 21.2 Extension Instructions
[xsl:]use-when: see 3.12 Conditional Element Inclusion
[xsl:]default-collation: see 3.6.1 The default-collation attribute

3.6 Stylesheet Element

<xsl:stylesheet id? = id extension-element-prefixes? = tokens exclude-result-prefixes? = tokens version = number xpath-default-namespace? = uri default-validation? = "preserve" | "strip" default-collation? = uri-list default-mode? = qname | "#unnamed" input-type-annotations? = "preserve" | "strip" | "unspecified" >  </xsl:stylesheet>

<xsl:transform id? = id extension-element-prefixes? = tokens exclude-result-prefixes? = tokens version = number xpath-default-namespace? = uri default-validation? = "preserve" | "strip" default-collation? = uri-list default-mode? = qname | "#unnamed" input-type-annotations? = "preserve" | "strip" | "unspecified" >  </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.

An xsl:stylesheet element must have a version attribute, indicating the version of XSLT that the stylesheet module requires.

[ERR XTSE0110] The value of the version attribute must be a number: specifically, it must be a 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 2.1, the value should normally be set to 2.1. If the value is numerically less than 2.1, the stylesheet is processed using the rules for backwards compatible behavior (see 3.8 Backwards Compatible Processing). If the value is numerically greater than 2.1, the stylesheet is processed using the rules for forwards compatible behavior (see 3.9 Forwards Compatible Processing).

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

The default-validation attribute defines the default value of the validation attribute of all xsl:document, xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, and xsl:result-document instructions, and of the xsl:validation attribute of all literal result elements. It also determines the validation applied to the implicit final result tree created in the absence of an xsl:result-document instruction. This default applies within the stylesheet module: it does not extend to included or imported stylesheet modules. If the attribute is omitted, the default is strip. The permitted values are preserve and strip. For details of the effect of this attribute, see 22.2 Validation.

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

[Definition: An element occurring as a child of an xsl:stylesheet 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.6.3 User-defined Data Elements)].

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

xsl:import
xsl:include
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:import-schema
xsl:key
xsl:mode
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:strip-space
xsl:template
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.

If there are xsl:import elements, these must come before any other elements. Apart from this, 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.4 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.

3.6.1 The `default-collation` attribute

The default-collation attribute is a standard attribute that may appear on any element in the XSLT namespace, or (as xsl:default-collation) on a literal result element.

The attribute is used to specify the default collation used by all XPath expressions appearing in the attributes of this element, or attributes of descendant elements, unless overridden by another default-collation attribute on an inner element. It also determines the collation used by certain XSLT constructs (such as xsl:key and xsl:for-each-group) within its scope.

The value of the attribute is a whitespace-separated list of collation URIs. If any of these URIs is a relative URI reference, then it is resolved relative to the base URI of the attribute's parent element. If the implementation recognizes one or more of the resulting absolute collation URIs, then it uses the first one that it recognizes as the default collation.

[ERR XTSE0125] It is a static error if the value of an [xsl:]default-collation attribute, after resolving against the base URI, contains no URI that the implementation recognizes as a collation URI.

Note:

The reason the attribute allows a list of collation URIs is that collation URIs will often be meaningful only to one particular XSLT implementation. Stylesheets designed to run with several different implementations can therefore specify several different collation URIs, one for use with each. To avoid the above error condition, it is possible to specify the Unicode Codepoint Collation as the last collation URI in the list.

The [xsl:]default-collation attribute does not affect the collation used by xsl:sort.

3.6.2 The `default-mode` attribute

The default-mode attribute defines the default value for the mode attribute of all xsl:template and xsl:apply-templates elements within the stylesheet module. It also determines which mode is referred to when the token #default is used in either of these attributes.

The value must either be a lexical QName, or the token #unnamed which refers to the unnamed mode. It is not necessary for the referenced mode to be explicitly declared in an xsl:mode declaration.

If the default-mode attribute is omitted, then the default mode for the stylesheet module is the unnamed mode. This is equivalent to specifying #unnamed.

Note:

This attribute is provided to support an approach to stylesheet modularity in which all the template rules for one mode are collected together into a single stylesheet module. Using this attribute reduces the risk of forgetting to specify the mode in one or more places where it is needed, and it also makes it easier to reuse an existing stylesheet module that does not use modes in an application where modes are needed to avoid conflicts with existing template rules.

Issue 2 (chameleon-modes):

Would it be useful to be able to specify the default mode for an included module on the xsl:include element, in the style of chameleon includes in XSD? The WG has discussed such a feature; it is recognized that it would be useful, but it is not clear whether it would be useful enough to justify the extra complexity.

3.6.3 User-defined Data Elements

[Definition: In addition to declarations, the xsl:stylesheet element may contain among its children any element not from the XSLT namespace, provided that the expanded-QName of the element has a non-null namespace URI. Such elements are referred to as user-defined data elements.]

[ERR XTSE0130] It is a static error if the xsl:stylesheet element has a child element whose name has a null namespace URI.

An implementation may attach an implementation-defined meaning to user-defined data elements that appear in particular namespaces. The set of namespaces that are recognized for such data elements is implementation-defined. The presence of a user-defined data element must not change the behavior of XSLT elements and functions defined in this document; for example, it is not permitted for a user-defined data element to specify that xsl:apply-templates should use different rules to resolve conflicts. The constraints on what user-defined data elements can and cannot do are exactly the same as the constraints on extension attributes, described in 3.3 Extension Attributes. Thus, an implementation is always free to ignore user-defined data elements, and must ignore such data elements without giving an error if it does not recognize the namespace URI.

User-defined data elements can provide, for example,

information used by extension instructions or extension functions (see 21 Extensibility and Fallback),
information about what to do with any final result tree,
information about how to construct source trees,
optimization hints for the processor,
metadata about the stylesheet,
structured documentation for the stylesheet.

A user-defined data element must not precede an xsl:import element within a stylesheet module [see ERR XTSE0200]

3.7 Simplified Stylesheet Modules

A simplified syntax is allowed for a stylesheet module that defines only a single template rule for the document node. The stylesheet module may consist of just a literal result element (see 11.1 Literal Result Elements) together with its contents. The literal result element must have an xsl:version attribute (and it must therefore also declare the XSLT namespace). Such a stylesheet module is equivalent to a standard stylesheet module whose xsl:stylesheet element contains a template rule containing the literal result element, minus its xsl:version attribute; the template rule has a match pattern of /.

Example: A Simplified Stylesheet

For example:

<html xsl:version="2.1"
      xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Expense Report Summary</title>
  </head>
  <body>
    <p>Total Amount: <xsl:value-of select="expense-report/total"/></p>
  </body>
</html>

has the same meaning as

<xsl:stylesheet version="2.1"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns="http://www.w3.org/1999/xhtml">
<xsl:template match="/">
<html>
  <head>
    <title>Expense Report Summary</title>
  </head>
  <body>
    <p>Total Amount: <xsl:value-of select="expense-report/total"/></p>
  </body>
</html>
</xsl:template>
</xsl:stylesheet>

Note that it is not possible, using a simplified stylesheet, to request that the serialized output contains a DOCTYPE declaration. This can only be done by using a standard stylesheet module, and using the xsl:output element.

More formally, a simplified stylesheet module is equivalent to the standard stylesheet module that would be generated by applying the following transformation to the simplified stylesheet module, invoking the transformation by calling the named template expand, with the containing literal result element as the context node:

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

<xsl:template name="expand">
  <xsl:element name="xsl:stylesheet">
    <xsl:attribute name="version" select="@xsl:version"/>
    <xsl:element name="xsl:template">
      <xsl:attribute name="match" select="'/'"/>
      <xsl:copy-of select="."/>
    </xsl:element>
  </xsl:element>
</xsl:template>  

</xsl:stylesheet>

[ERR XTSE0150] A literal result element that is used as the outermost element of a simplified stylesheet module must have an xsl:version attribute. This indicates the version of XSLT that the stylesheet requires. For this version of XSLT, the value will normally be 2.1 ; the value must be a valid instance of the type xs:decimal as defined in [XML Schema Part 2].

Other literal result elements may also have an xsl:version attribute. When the xsl:version attribute is numerically less than 2.0, backwards compatible behavior is enabled (see 3.8 Backwards Compatible Processing). When the xsl:version attribute is numerically greater than 2.0, forwards compatible behavior is enabled (see 3.9 Forwards Compatible Processing).

The allowed content of a literal result element when used as a simplified stylesheet is the same as when it occurs within a sequence constructor. Thus, a literal result element used as the document element of a simplified stylesheet cannot contain declarations. Simplified stylesheets therefore cannot use template rules, global variables, stylesheet parameters, stylesheet functions, keys, attribute-sets, or output definitions. In turn this means that the only useful way to initiate the transformation is to supply a document node as the initial context item, to be matched by the implicit match="/" template rule using the unnamed mode.

3.8 Backwards Compatible Processing

[Definition: The effective version of an element in the stylesheet is the decimal value of the [xsl:]version attribute (see 3.5 Standard Attributes) on that element or on the innermost ancestor element that has such an attribute, excluding the version attribute on an xsl:output element.]

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

Specifically:

If the effective version is equal to 1.0, then the element is processed with XSLT 1.0 behavior as described in 3.8.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.8.2 XSLT 2.0 compatibility mode.
If the effective version is any other value less than 2.1, the recommended action is to report 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.

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.

An element that has an [xsl:]version attribute whose value is greater than or equal to 2.0 disables backwards compatible behavior for itself, its attributes, its descendants and their attributes. The compatibility behavior established by an element overrides any compatibility behavior established by an ancestor element.

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

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

Note:

By making use of backwards compatible behavior, it is possible to write the stylesheet in a way that ensures that its results when processed with an XSLT 2.1 processor are identical to the effects of processing the same stylesheet using a processor for an earlier version of XSLT. To assist with transition, some parts of a stylesheet may be processed with backwards compatible behavior enabled, and other parts with this behavior disabled.

All data values manipulated by an XSLT 2.1 processor are defined by the XDM data model, whether or not the relevant expressions use backwards compatible behavior. Because the same data model is used in both cases, expressions are fully composable. The result of evaluating instructions or expressions with backwards compatible behavior is fully defined in the XSLT 2.1 and XPath 2.1 specifications, it is not defined by reference to earlier versions of the XSLT and XPath specifications.

To write a stylesheet that makes use of features that are new in version N, while also working with a processor that only supports XSLT version M (M < N), it is necessary to understand both the rules for backwards compatible behavior in XSLT version N, and the rules for forwards compatible behavior in XSLT version M. If the xsl:stylesheet element specifies version="2.0" or version="2.1", then an XSLT 1.0 processor will ignore XSLT 2.0 and XSLT 2.1declarations that were not defined in XSLT 1.0, for example xsl:function and xsl:import-schema. If any new XSLT 2.1 instructions are used (for example xsl:evaluate or xsl:stream), or if new XPath 2.1 features are used (for example, new functions, or let expressions), then the stylesheet must provide fallback behavior that relies only on facilities available in the earliest XSLT version supported. The fallback behavior can be invoked by using the xsl:fallback instruction, or by testing the results of the function-available or element-available functions, or by testing the value of the xsl:version property returned by the system-property function.

3.8.1 XSLT 1.0 compatibility mode

[Definition: An element in the stylesheet is processed with XSLT 1.0 behavior if its effective version is equal to 1.0.]

In this mode, if any attribute contains an XPath expression, then the expression is evaluated with XPath 1.0 compatibility mode set to true. For details of this mode, see Section 2.1.1 Static Context^XP21.

Furthermore, in such an expression any function call for which no implementation is available (unless it uses the standard function namespace) is bound to a fallback error function whose effect when evaluated is to raise a dynamic error [see ERR XTDE1425] . The effect is that with backwards compatible behavior enabled, calls on extension functions that are not available in a particular implementation do not cause an error unless the function call is actually evaluated. For further details, see 21.1 Extension Functions.

Note:

This might appear to contradict the specification of XPath 2.1, which states that a static error [XPST0017] is raised when an expression contains a call to a function that is not present (with matching name and arity) in the static context. This apparent contradiction is resolved by specifying that the XSLT processor constructs a static context for the expression in which every possible function name and arity (other than names in the standard function namespace) is present; when no other implementation of the function is available, the function call is bound to a fallback error function whose run-time effect is to raise a dynamic error.

Certain XSLT constructs also produce different results when XSLT 1.0 compatibility mode is enabled. This is described separately for each such construct.

3.8.2 XSLT 2.0 compatibility mode

[Definition: An element is processed with XSLT 2.0 behavior if its effective version is equal to 2.0.]

In this working draft, no differences are defined for XSLT 2.0 behavior. An XSLT 2.1 processor will therefore produce the same results whether the effective version of an element is set to 2.0 or 2.1.

Note:

An XSLT 2.0 processor, by contrast, will in some cases produce different results in the two cases. For example, if the stylesheet contains an xsl:iterate instruction with an xsl:fallback child, an XSLT 2.1 processor will process the xsl:iterate instruction regardless whether the effective version is 2.0 or 2.1, while an XSLT 2.0 processor will report a static error if the effective version is 2.0, and will take the fallback action if the effective version is 2.1.

3.9 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 2.1, while retaining the ability to execute the stylesheet with an XSLT 2.1 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.12 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 2.1 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 2.1.]

An element that has an [xsl:]version attribute whose value is less than or equal to 2.1 disables forwards compatible behavior for itself, its attributes, its descendants and their attributes. The compatibility behavior established by an element overrides any compatibility behavior established by an ancestor element.

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 2.1 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 2.1 does not allow the element to have, then the attribute must be ignored.
if the element is in the XSLT namespace and appears as part of a sequence constructor, and XSLT 2.1 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 reported 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 2.1 instructions.
2. If the element has no xsl:fallback children, then a static error is reported in the same way as if forwards compatible behavior were not enabled.

Example: Forwards Compatible Behavior

For example, an XSLT 2.1 processor will process the following stylesheet without error, although the stylesheet includes elements from the XSLT namespace that are not defined in this specification:

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

Note:

If a stylesheet depends crucially on a declaration introduced by a version of XSLT after 2.1, then the stylesheet can use an xsl:message element with terminate="yes" (see 20 Messages) to ensure that implementations that conform to an earlier version of XSLT will not silently ignore the declaration.

Example: Testing the XSLT Version

For example,

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

3.10 Combining Stylesheet Modules

XSLT provides two mechanisms to construct a stylesheet from multiple stylesheet modules:

an inclusion mechanism that allows stylesheet modules to be combined without changing the semantics of the modules being combined, and
an import mechanism that allows stylesheet modules to override each other.

3.10.1 Locating Stylesheet Modules

The include and import mechanisms use two declarations, xsl:include and xsl:import, which are defined in the sections that follow.

These declarations use an href attribute, whose value is a URI reference, to identify the stylesheet module to be included or imported. If the value of this attribute is a relative URI reference, it is resolved as described in 5.8 URI References.

After resolving against the base URI, the way in which the URI reference is used to locate a representation of a stylesheet module, and the way in which the stylesheet module is constructed from that representation, are implementation-defined. In particular, it is implementation-defined which URI schemes are supported, whether fragment identifiers are supported, and what media types are supported. Conventionally, the URI is a reference to a resource containing the stylesheet module as a source XML document, or it may include a fragment identifier that selects an embedded stylesheet module within a source XML document; but the implementation is free to use other mechanisms to locate the stylesheet module identified by the URI reference.

The referenced stylesheet module may be any of the four kinds of stylesheet module: that is, it may be standalone or embedded, and it may be standard or simplified. If it is a simplified stylesheet module then it is transformed into the equivalent standard stylesheet module by applying the transformation described in 3.7 Simplified Stylesheet Modules.

Implementations may choose to accept URI references containing a fragment identifier defined by reference to the XPointer specification (see [XPointer Framework]). Note that if the implementation does not support the use of fragment identifiers in the URI reference, then it will not be possible to include an embedded stylesheet module.

[ERR XTSE0165] It is a static error if the processor is not able to retrieve the resource identified by the URI reference, or if the resource that is retrieved does not contain a stylesheet module conforming to this specification.

3.10.2 Stylesheet Inclusion

 <xsl:include href = uri-reference />

A stylesheet module may include another stylesheet module using an xsl:include declaration.

The xsl:include declaration has a required href attribute whose value is a URI reference identifying the stylesheet module to be included. This attribute is used as described in 3.10.1 Locating Stylesheet Modules.

[ERR XTSE0170] An xsl:include element must be a top-level element.

[Definition: A stylesheet level is a collection of stylesheet modules connected using xsl:include declarations: specifically, two stylesheet modules A and B are part of the same stylesheet level if one of them includes the other by means of an xsl:include declaration, or if there is a third stylesheet module C that is in the same stylesheet level as both A and B.]

[Definition: The declarations within a stylesheet level have a total ordering known as declaration order. The order of declarations within a stylesheet level is the same as the document order that would result if each stylesheet module were inserted textually in place of the xsl:include element that references it.] In other respects, however, the effect of xsl:include is not equivalent to the effect that would be obtained by textual inclusion.

[ERR XTSE0180] It is a static error if a stylesheet module directly or indirectly includes itself.

Note:

It is not intrinsically an error for a stylesheet to include the same module more than once. However, doing so can cause errors because of duplicate definitions. Such multiple inclusions are less obvious when they are indirect. For example, if stylesheet B includes stylesheet A, stylesheet C includes stylesheet A, and stylesheet D includes both stylesheet B and stylesheet C, then A will be included indirectly by D twice. If all of B, C and D are used as independent stylesheets, then the error can be avoided by separating everything in B other than the inclusion of A into a separate stylesheet B' and changing B to contain just inclusions of B' and A, similarly for C, and then changing D to include A, B', C'.

3.10.3 Stylesheet Import

 <xsl:import href = uri-reference />

A stylesheet module may import another stylesheet module using an xsl:import declaration. Importing a stylesheet module is the same as including it (see 3.10.2 Stylesheet Inclusion) except that template rules and other declarations in the importing module take precedence over template rules and declarations in the imported module; this is described in more detail below.

The xsl:import declaration has a required href attribute whose value is a URI reference identifying the stylesheet module to be included. This attribute is used as described in 3.10.1 Locating Stylesheet Modules.

[ERR XTSE0190] An xsl:import element must be a top-level element.

[ERR XTSE0200] The xsl:import element children must precede all other element children of an xsl:stylesheet element, including any xsl:include element children and any user-defined data elements.

Example: Using xsl:import

For example,

<xsl:stylesheet version="2.1"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:import href="article.xsl"/>
  <xsl:import href="bigfont.xsl"/>
  <xsl:attribute-set name="note-style">
    <xsl:attribute name="font-style">italic</xsl:attribute>
  </xsl:attribute-set>
</xsl:stylesheet>

[Definition: The stylesheet levels making up a stylesheet are treated as forming an import tree. In the import tree, each stylesheet level has one child for each xsl:import declaration that it contains.] The ordering of the children is the declaration order of the xsl:import declarations within their stylesheet level.

[Definition: A declaration D in the stylesheet is defined to have lower import precedence than another declaration E if the stylesheet level containing D would be visited before the stylesheet level containing E in a post-order traversal of the import tree (that is, a traversal of the import tree in which a stylesheet level is visited after its children). Two declarations within the same stylesheet level have the same import precedence.]

For example, suppose

stylesheet module A imports stylesheet modules B and C in that order;
stylesheet module B imports stylesheet module D;
stylesheet module C imports stylesheet module E.

Then the import tree has the following structure:

Here you should see a diagram. If it does not appear correctly in your browser, you need to install an SVG Plugin.

The order of import precedence (lowest first) is D, B, E, C, A.

In general, a declaration with higher import precedence takes precedence over a declaration with lower import precedence. This is defined in detail for each kind of declaration.

[ERR XTSE0210] It is a static error if a stylesheet module directly or indirectly imports itself.

Note:

The case where a stylesheet module with a particular URI is imported several times is not treated specially. The effect is exactly the same as if several stylesheet modules with different URIs but identical content were imported. This might or might not cause an error, depending on the content of the stylesheet module.

3.11 Embedded Stylesheet Modules

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

Two situations where embedded stylesheets may be useful are:

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

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

Note:

In order for such an attribute value to be used as a fragment identifier in a URI, the XDM attribute node must generally have the is-id property: see Section 5.5 is-id Accessor^DM11. This property will typically be set if the attribute is defined in a DTD as being of type ID, or if is defined in a schema as being of type xs:ID. It is also necessary that the media type of the containing document should support the use of ID values as fragment identifiers. Such support is widespread in existing products, and is expected to be endorsed in respect of the media type application/xml by a future revision of [RFC3023] Such support is widespread in existing products, and is endorsed in respect of the media type application/xml by [XPointer Framework].

An alternative, if the implementation supports it, is to use an xml:id attribute. XSLT allows this attribute (like other namespaced attributes) to appear on any XSLT element.

Example: The xml-stylesheet Processing Instruction

The following example shows how the xml-stylesheet processing instruction (see [XML Stylesheet]) can be used to allow a source document to contain its own stylesheet. The URI reference uses a relative URI with a fragment identifier to locate the xsl:stylesheet element:

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

Note:

A stylesheet module that is embedded in the document to which it is to be applied typically needs to contain a template rule that specifies that xsl:stylesheet elements are to be ignored.

Note:

The above example uses the pseudo-attribute type="application/xslt+xml" in the xml-stylesheet processing instruction to denote an XSLT stylesheet. This is the officially registered media type for XSLT: see 3.4 XSLT Media Type. However, browsers developed before this media type was registered are more likely to accept the unofficial designation type="text/xsl".

Note:

Support for the xml-stylesheet processing instruction is not required for conformance with this Recommendation. Implementations are not constrained in the mechanisms they use to identify a stylesheet when a transformation is initiated: see 2.3 Initiating a Transformation.

3.12 Conditional Element Inclusion

Any element in the XSLT namespace may have a use-when attribute whose value is an XPath expression that can be evaluated statically. If the attribute is present and the effective boolean value^XP21 of the expression is false, then the element, together with all the nodes having that element as an ancestor, is effectively excluded from the stylesheet module. When a node is effectively excluded from a stylesheet module the stylesheet module has the same effect as if the node were not there. Among other things this means that no static or dynamic errors will be reported in respect of the element and its contents, other than errors in the use-when attribute itself.

Note:

This does not apply to XML parsing or validation errors, which will be reported in the usual way. It also does not apply to attributes that are necessarily processed before [xsl:]use-when, examples being xml:space and [xsl:]xpath-default-namespace.

A literal result element, or any other element within a stylesheet module that is not in the XSLT namespace, may similarly carry an xsl:use-when attribute.

If the xsl:stylesheet or xsl:transform element itself is effectively excluded, the effect is to exclude all the children of the xsl:stylesheet or xsl:transform element, but not the xsl:stylesheet or xsl:transform element or its attributes.

Note:

This allows all the declarations that depend on the same condition to be included in one stylesheet module, and for their inclusion or exclusion to be controlled by a single use-when attribute at the level of the module.

Conditional element exclusion happens after stripping of whitespace text nodes from the stylesheet, as described in 4.2 Stripping Whitespace from the Stylesheet.

There are no syntactic constraints on the XPath expression that can be used as the value of the use-when attribute. However, there are severe constraints on the information provided in its evaluation context. These constraints are designed to ensure that the expression can be evaluated at the earliest possible stage of stylesheet processing, without any dependency on information contained in the stylesheet itself or in any source document.

Specifically, the components of the static and dynamic context are defined by the following two tables:

Static Context Components for `use-when` Expressions
Component	Value
XPath 1.0 compatibility mode	false
In scope namespaces	determined by the in-scope namespaces for the containing element in the stylesheet
Default element/type namespace	determined by the `xpath-default-namespace` attribute if present (see 5.2 Unprefixed QNames in Expressions and Patterns); otherwise the null namespace
Default function namespace	The standard function namespace
In scope type definitions	The type definitions that would be available in the absence of any `xsl:import-schema` declaration
In scope element declarations	None
In scope attribute declarations	None
In scope variables	None
In scope functions	The core functions defined in [Functions and Operators], together with the functions `element-available`, `function-available`, `type-available`, and `system-property` defined in this specification, plus the set of extension functions that are present in the static context of every XPath expression (other than a use-when expression) within the content of the element that is the parent of the `use-when` attribute. Note that stylesheet functions are not included in the context, which means that the function `function-available` will return `false` in respect of such functions. The effect of this rule is to ensure that `function-available` returns true in respect of functions that can be called within the scope of the `use-when` attribute. It also has the effect that these extensions functions will be recognized within the `use-when` attribute itself; however, the fact that a function is available in this sense gives no guarantee that a call on the function will succeed.
In scope collations	Implementation-defined
Default collation	The Unicode Codepoint Collation
Base URI	The base URI of the containing element in the stylesheet
Statically known documents	None
Statically known collections	None
Statically known decimal formats	A single unnamed decimal format equivalent to the decimal format that is created by an `xsl:decimal-format` declaration with no attributes.

Dynamic Context Components for `use-when` Expressions
Component	Value
Context item, position, and size	Undefined
Dynamic variables	None
Current date and time	Implementation-defined
Implicit timezone	Implementation-defined
Available documents	None
Available collections	None

Within a stylesheet module, all expressions contained in [xsl:]use-when attributes are evaluated in a single execution scope^FO. This need not be the same execution scope as that used for [xsl]:use-when expressions in other stylesheet modules, or as that used when evaluating XPath expressions appearing elsewhere in the stylesheet module. This means that a function such as current-date^FO will return the same result when called in different [xsl:]use-when expressions within the same stylesheet module, but will not necessarily return the same result as the same call in an [xsl:]use-when expression within a different stylesheet module, or as a call on the same function executed during the transformation proper.

The use of [xsl:]use-when is illustrated in the following examples.

Example: Using Conditional Exclusion to Achieve Portability

This example demonstrates the use of the use-when attribute to achieve portability of a stylesheet across schema-aware and non-schema-aware processors.

<xsl:import-schema schema-location="http://example.com/schema"
              use-when="system-property('xsl:is-schema-aware')='yes'"/>

<xsl:template match="/" 
              use-when="system-property('xsl:is-schema-aware')='yes'" 
              priority="2">
  <xsl:result-document validation="strict">
    <xsl:apply-templates/>
  </xsl:result-document>
</xsl:template>

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

The effect of these declarations is that a non-schema-aware processor ignores the xsl:import-schema declaration and the first template rule, and therefore generates no errors in respect of the schema-related constructs in these declarations.

Example: Including Variant Stylesheet Modules

This example includes different stylesheet modules depending on which XSLT processor is in use.

<xsl:include href="module-A.xsl" 
     use-when="system-property('xsl:vendor')='vendor-A'"/>
<xsl:include href="module-B.xsl" 
     use-when="system-property('xsl:vendor')='vendor-B'"/>

3.13 Built-in Types

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

All the primitive atomic types defined in [XML Schema Part 2] with the exception of xs:NOTATION. That is: xs:string, xs:boolean, xs:decimal, xs:double, xs:float, xs:date, xs:time, xs:dateTime, xs:duration, xs:QName, xs:anyURI, xs:gDay, xs:gMonthDay, xs:gMonth, xs:gYearMonth, xs:gYear, xs:base64Binary, and xs:hexBinary. All built-in types defined in [XML Schema Part 2], including xs:anyType and xs:anySimpleType.
The following types defined in [XPath 2.1]: xs:yearMonthDuration, xs:dayTimeDuration, xs:anyAtomicType, xs:untyped, and xs:untypedAtomic.

Issue 3 (additional-types):

It is likely that the new types from XSD 1.1 will be added to this list when XSD 1.1 becomes a Recommendation.

A schema-aware XSLT processor additionally supports:

All other built-in types defined in [XML Schema Part 2]
User-defined types, and element and attribute declarations, that are imported using an xsl:import-schema declaration as described in 3.14 Importing Schema Components. These may include both simple and complex types.

Note:

The names that are imported from the XML Schema namespace do not include all the names of top-level types defined in either the Schema for Schemas or the Schema for Datatypes. The Schema for Datatypes, as well as defining built-in types such as xs:integer and xs:double, also defines types that are intended for use only within the Schema for DataTypes, such as xs:derivationControl. A stylesheet that is designed to process XML Schema documents as its input or output may import the Schema for Schemas.

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

For a Basic XSLT Processor, schema built-in types that are not included in the static context (for example, xs:NCName) are "unknown types" in the sense of Section 2.5.4 SequenceType Matching^XP21. In the language of that section, a Basic XSLT Processor must be able to determine whether these unknown types are derived from known schema types such as xs:string. The purpose of this rule is to ensure that system functions such as local-name-from-QName^FO, which is defined to return an xs:NCName, behave correctly. A stylesheet that uses a Basic XSLT Processor will not be able to test whether the returned value is an xs:NCName, but it will be able to use it as if it were an xs:string.

3.14 Importing Schema Components

Note:

The facilities described in this section are not available with a basic XSLT processor. They require a schema-aware XSLT processor, as described in 24 Conformance.

 <xsl:import-schema namespace? = uri-reference schema-location? = uri-reference >  </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.13 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 stylesheet, 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; importing components in one stylesheet module makes them available throughout the stylesheet.

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.

Note:

The synthetic schema document does not need to be constructed by a real implementation. It is purely a mechanism for defining the semantics of xsl:import-schema in terms of rules that already exist within the XML Schema specification. In particular, it implicitly defines the rules that determine whether the set of xsl:import-schema declarations are mutually consistent.

These rules do not cause names to be imported transitively. The fact that a name is available for reference within a schema document A does not of itself make the name available for reference in a stylesheet that imports the target namespace of schema document A. (See [XML Schema Part 1] section 3.15.3, Constraints on XML Representations of Schemas.) The stylesheet must import all the namespaces containing names that it actually references.

The namespace attribute indicates that a schema for the given namespace is required by the stylesheet. This information may be enough on its own to enable an implementation to locate the required schema components. The namespace attribute may be omitted to indicate that a schema for names in no namespace is being imported. The zero-length string is not a valid namespace URI, and is therefore not a valid value for the namespace attribute.

The schema-location attribute is a URI Reference that gives a hint indicating where a schema document or other resource containing the required definitions may be found. It is likely that a schema-aware XSLT processor will be able to process a schema document found at this location.

The XML Schema specification gives implementations flexibility in how to handle multiple imports for the same namespace. Multiple imports do not cause errors if the definitions do not conflict.

A consequence of these rules is that it is not intrinsically an error if no schema document can be located for a namespace identified in an xsl:import-schema declaration. This will cause an error only if it results in the stylesheet containing references to names that have not been imported.

An inline schema document (using an xs:schema element as a child of the xsl:import-schema element) has the same status as an external schema document, in the sense that it acts as a hint for a source of schema components in the relevant namespace. To ensure that the inline schema document is always used, it is advisable to use a target namespace that is unique to this schema document.

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.

Example: An Inline Schema Document

The following example shows an inline schema document. This declares a simple type local:yes-no, which the stylesheet then uses in the declaration of a variable.

The example assumes the namespace declaration xmlns:local="http://localhost/ns/yes-no"

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

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

4 Data Model

The data model used by XSLT is the XPath 2.1 and XQuery 1.1 data model (XDM), as defined in [Data Model]. XSLT operates on source, result and stylesheet documents using the same data model.

This section elaborates on some particular features of XDM as it is used by XSLT:

The rules in 4.2 Stripping Whitespace from the Stylesheet and 4.4 Stripping Whitespace from a Source Tree make use of the concept of a whitespace text node.

[Definition: A whitespace text node is a text node whose content consists entirely of whitespace characters (that is, #x09, #x0A, #x0D, or #x20).]

Note:

Features of a source XML document that are not represented in the XDM tree will have no effect on the operation of an XSLT stylesheet. Examples of such features are entity references, CDATA sections, character references, whitespace within element tags, and the choice of single or double quotes around attribute values.

4.1 XML Versions

The XDM data model defined in [Data Model] 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 2.1 can be used with either of these XML versions.

Construction of the XDM tree is outside the scope of this specification, so XSLT 2.1 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 23 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 2.1 and XPath 2.1, 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 2.1 processor that implements the 1.1 versions should also provide a mode that supports the 1.0 versions. It is thus implementation-defined whether the XSLT processor supports XML 1.0 with XML Namespaces 1.0, or XML 1.1 with XML Namespaces 1.1, or supports both versions at user option.

Note:

The specification referenced as [Namespaces in XML] was actually published without a version number.

The current version of [XML Schema Part 2] (that is, XSD 1.0) does not reference the XML 1.1 specifications. This means that data types such as xs:NCName and xs:ID are constrained by the XML 1.0 rules, and do not allow the full range of values permitted by XML 1.1. This situation will not be resolved until a new version of [XML Schema Part 2] becomes available; in the meantime, it is recommended that implementers wishing to support XML 1.1 should consult [XML Schema 1.0 and XML 1.1] for guidance. An XSLT 2.1 processor that supports XML 1.1 should implement the rules in later versions of [XML Schema Part 2] as they become available.

4.2 Stripping Whitespace from the Stylesheet

The tree representing the stylesheet is preprocessed as follows:

All comments and processing instructions are removed.
Any text nodes that are now adjacent to each other are merged.
Any whitespace text node that satisfies both the following conditions is removed from the tree:
- The parent of the text node is not an xsl:text element
- The text node does not have an ancestor element that has an xml:space attribute with a value of preserve, unless there is a closer ancestor element having an xml:space attribute with a value of default.
Any whitespace text node whose parent is one of the following elements is removed from the tree, regardless of any xml:space attributes:

xsl:analyze-string
xsl:apply-imports
xsl:apply-templates
xsl:attribute-set
xsl:call-template
xsl:character-map
xsl:choose
xsl:evaluate
xsl:merge
xsl:merge-source
xsl:next-iteration
xsl:next-match
xsl:stylesheet
xsl:transform
Any whitespace text node whose immediate following-sibling node is an xsl:merge-key, xsl:param, or xsl:sort element is removed from the tree, regardless of any xml:space attributes.
Any whitespace text node whose immediate preceding-sibling node is an xsl:catch or xsl:on-completion element is removed from the tree, regardless of any xml:space attributes.

[ERR XTSE0260] Within an XSLT element that is required to be empty, any content other than comments or processing instructions, including any whitespace text node preserved using the xml:space="preserve" attribute, is a static error.

Note:

Using xml:space="preserve" in parts of the stylesheet that contain sequence constructors will cause all text nodes in that part of the stylesheet, including those that contain whitespace only, to be copied to the result of the sequence constructor. When the result of the sequence constructor is used to form the content of an element, this can cause errors if such text nodes are followed by attribute nodes generated using xsl:attribute.

Note:

If an xml:space attribute is specified on a literal result element, it will be copied to the result tree in the same way as any other attribute.

4.3 Stripping Type Annotations from a Source Tree

[Definition: The term type annotation is used in this specification to refer to the value returned by the dm:type-name accessor of a node: see Section 5.14 type-name Accessor^DM11.]

There is sometimes a requirement to write stylesheets that produce the same results whether or not the source documents have been validated against a schema. To achieve this, an option is provided to remove any type annotations on element and attribute nodes in a source tree, replacing them with an annotation of xs:untyped in the case of element nodes, and xs:untypedAtomic in the case of attribute nodes.

Such stripping of type annotations can be requested by specifying input-type-annotations="strip" on the xsl:stylesheet element. This attribute has three permitted values: strip, preserve, and unspecified. The default value is unspecified. Stripping of type annotations takes place if at least one stylesheet module in the stylesheet specifies input-type-annotations="strip".

[ERR XTSE0265] It is a static error if there is a stylesheet module in the stylesheet that specifies input-type-annotations="strip" and another stylesheet module that specifies input-type-annotations="preserve".

The source trees to which this applies are the same as those affected by xsl:strip-space and xsl:preserve-space: see 4.4 Stripping Whitespace from a Source Tree.

When type annotations are stripped, the following changes are made to the source tree:

The type annotation of every element node is changed to xs:untyped
The type annotation of every attribute node is changed to xs:untypedAtomic
The typed value of every element and attribute node is set to be the same as its string value, as an instance of xs:untypedAtomic.
The is-nilled property of every element node is set to false.

The values of the is-id and is-idrefs properties are not changed.

Note:

Stripping type annotations does not necessarily return the document to the state it would be in had validation not taken place. In particular, any defaulted elements and attributes that were added to the tree by the validation process will still be present , and elements and attributes validated as IDs will still be accessible using the id^FO function.

4.4 Stripping Whitespace from a Source Tree

A source tree supplied as input to the transformation process may contain whitespace text nodes that are of no interest, and that do not need to be retained by the transformation. Conceptually, an XSLT processor makes a copy of the source tree from which unwanted whitespace text nodes have been removed. This process is referred to as whitespace stripping.

For the purposes of this section, the term source tree means the document containing the initial context item if it is a node, and any document returned by the functions document, doc^FO, or collection^FO. It does not include documents passed as the values of stylesheet parameters or returned from extension functions.

The stripping process takes as input a set of element names whose child whitespace text nodes are to be preserved. The way in which this set of element names is established using the xsl:strip-space and xsl:preserve-space declarations is described later in this section.

A whitespace text node is preserved if either of the following apply:

The element name of the parent of the text node is in the set of whitespace-preserving element names.
An ancestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default.

Otherwise, the whitespace text node is stripped.

The xml:space attributes are not removed from the tree.

 <xsl:strip-space elements = tokens />

 <xsl:preserve-space elements = tokens />

The set of whitespace-preserving element names is specified by xsl:strip-space and xsl:preserve-space declarations. Whether an element name is included in the set of whitespace-preserving names is determined by the best match among all the xsl:strip-space or xsl:preserve-space declarations: it is included if and only if there is no match or the best match is an xsl:preserve-space element. The xsl:strip-space and xsl:preserve-space elements each have an elements attribute whose value is a whitespace-separated list of NameTests^XP21; an element name matches an xsl:strip-space or xsl:preserve-space element if it matches one of the NameTests^XP21. An element matches a NameTest^XP21 if and only if the NameTest^XP21 would be true for the element as an XPath node test. When more than one xsl:strip-space and xsl:preserve-space element matches, the best matching element is determined by the best matching NameTest^XP21. This is determined in the same way as with template rules:

First, any match with lower import precedence than another match is ignored.
Next, any match that has a lower default priority than the default priority of another match is ignored.

[ERR XTRE0270] It is a recoverable dynamic error if this leaves more than one match, unless all the matched declarations are equivalent (that is, they are all xsl:strip-space or they are all xsl:preserve-space). The optional recovery action is to select, from the matches that are left, the one that occurs last in declaration order.

Issue 4 (multiple-match-on-strip-space):

We have changed the rules for handling ambiguous matches on template rules. Should we make a corresponding change for ambiguous matches on xsl:strip-space, or is this overkill? What is the corresponding change anyway?

If an element in a source document has a type annotation that is a simple type or a complex type with simple content, then any whitespace text nodes among its children are preserved, regardless of any xsl:strip-space declarations. The reason for this is that stripping a whitespace text node from an element with simple content could make the element invalid: for example, it could cause the minLength facet to be violated.

Stripping of type annotations happens before stripping of whitespace text nodes, so this situation will not occur if input-type-annotations="strip" is specified.

Note:

In [Data Model], processes are described for constructing an XDM tree from an Infoset or from a PSVI. Those processes deal with whitespace according to their own rules, and the provisions in this section apply to the resulting tree. In practice this means that elements that are defined in a DTD or a Schema to contain element-only content will have whitespace text nodes stripped, regardless of the xsl:strip-space and xsl:preserve-space declarations in the stylesheet.

However, source trees are not necessarily constructed using those processes; indeed, they are not necessarily constructed by parsing XML documents. Nothing in the XSLT specification constrains how the source tree is constructed, or what happens to whitespace text nodes during its construction. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the XSLT processor. The XSLT processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.

4.5 Attribute Types and DTD Validation

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

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

4.6 Data Model for Streaming

The data model for nodes in a document that is being streamed is no different from the standard XDM data model, in that it contains the same objects (nodes) with the same properties and relationships. The facilities for streaming do not change the data model; instead they impose rules that limit the ability of stylesheets to navigate the data model.

A useful way to visualize streaming is to suppose that at any point in time, there is a current position in the streamed input document which may be the start or end of the document, the start or end tag of an element, or a text, comment, or processing instruction node. From this position, the stylesheet has access to the following information:

Properties intrinsic to the node, such as its name, its base URI, its type annotation, and its is-id and is-idref properties.
The ancestors of the node (but navigation downwards from the ancestors is not permitted).
The attributes of the node, and the attributes of its ancestors. For each such attribute, all the properties of the node including its string value and typed value are available, but there are limitations that restrict navigation from the attribute node to other nodes in the document.
The in-scope namespace bindings of the node.
In the case of attributes, text nodes, comments, and processing instructions, the string value and typed value of the node.
Summary data about the preceding siblings of the node, and of each of its ancestor nodes: specifically, for each distinct combination of node kind, node name, and type annotation, a count of the number of preceding siblings that have that combination of properties. This information allows patterns such as match="para[1]" to be used, and it permits some limited use of the xsl:number instruction.

The children and other descendants of a node are not accessible except as a by-product of changing the current position in the document. The same applies to properties of an element or document node that require examination of the node's descendants, that is, the string value and typed value. This is enforced by means of a rule that only one expression requiring downward navigation from a node is permitted.

The detailed rules are defined in 18.4 Streamability Analysis.

4.7 Limits

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

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

The following limits are implementation-defined:

For the xs:decimal type, the maximum number of decimal digits (the totalDigits facet). This must be at least 18 digits. (Note, however, that support for the full value range of xs:unsignedLong requires 20 digits.)
For the types xs:date, xs:time, xs:dateTime, xs:gYear, and xs:gYearMonth: the range of values of the year component, which must be at least +0001 to +9999; and the maximum number of fractional second digits, which must be at least 3.
For the xs:duration type: the maximum absolute values of the years, months, days, hours, minutes, and seconds components.
For the xs:yearMonthDuration type: the maximum absolute value, expressed as an integer number of months.
For the xs:dayTimeDuration type: the maximum absolute value, expressed as a decimal number of seconds.
For the types xs:string, xs:hexBinary, xs:base64Binary, xs:QName, xs:anyURI, xs:NOTATION, and types derived from them: the maximum length of the value.
For sequences, the maximum number of items in a sequence.

4.8 Disable Output Escaping

For backwards compatibility reasons, XSLT 2.1 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 23.1 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 23.2 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 or attribute node.

Note:

In practice, the nodes in a final result tree will often be streamed directly from the XSLT processor to the serializer. In such an implementation, disable-output-escaping can be viewed not so much a property stored with nodes in the tree, but rather as additional information passed across the interface between the XSLT processor and the serializer.

5 Features of the XSLT Language

5.1 Qualified Names

The name of a stylesheet-defined object, specifically a named template, a mode, an attribute set, a key, a decimal-format, a variable or parameter, a stylesheet function, a named output definition, or a character map is specified as a QName using the syntax for QName^Names as defined in [Namespaces in XML].

[Definition: A QName is always written in the form (NCName ":")? NCName, that is, a local name optionally preceded by a namespace prefix. When two QNames are compared, however, they are considered equal if the corresponding expanded-QNames are the same, as described below.]

Because an atomic value of type xs:QName is sometimes referred to loosely as a QName, this specification also uses the term lexical QName to emphasize that it is referring to a QName^Names in its lexical form rather than its expanded form. This term is used especially when strings containing lexical QNames are manipulated as run-time values.

[Definition: A lexical QName is a string representing a QName in the form (NCName ":")? NCName, that is, a local name optionally preceded by a namespace prefix.]

[Definition: A string in the form of a lexical QName may occur as the value of an attribute node in a stylesheet module, or within an XPath expression contained in such an attribute node, or as the result of evaluating an XPath expression contained in such an attribute node. The element containing this attribute node is referred to as the defining element of the QName.]

[Definition: An expanded-QName contains a pair of values, namely a local name and an optional namespace URI. It may also contain a namespace prefix. Two expanded-QNames are equal if the namespace URIs are the same (or both absent) and the local names are the same. The prefix plays no part in the comparison, but is used only if the expanded-QName needs to be converted back to a string.]

If the QName has a prefix, then the prefix is expanded into a URI reference using the namespace declarations in effect on its defining element. The expanded-QName consisting of the local part of the name and the possibly null URI reference is used as the name of the object. The default namespace of the defining element (see Section 6.2 Element Nodes^DM11) is not used for unprefixed names.

There are three cases where the default namespace of the defining element is used when expanding an unprefixed QName:

Where a QName is used to define the name of an element being constructed. This applies both to cases where the name is known statically (that is, the name of a literal result element) and to cases where it is computed dynamically (the value of the name attribute of the xsl:element instruction).
The default namespace is used when expanding the first argument of the function element-available.
The default namespace applies to any unqualified element names appearing in the cdata-section-elements attribute of xsl:output or xsl:result-document

In the case of an unprefixed QName used as a NameTest within an XPath expression (see 5.3 Expressions) , and in certain other contexts, the namespace to be used in expanding the QName may be specified by means of the [xsl:]xpath-default-namespace attribute, as specified in 5.2 Unprefixed QNames in Expressions and Patterns.

[ERR XTSE0280] In the case of a prefixed QName used as the value of an attribute in the stylesheet, or appearing within an XPath expression in the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the QName.

[ERR XTDE0290] Where the result of evaluating an XPath expression (or an attribute value template) is required to be a lexical QName, then unless otherwise specified it is a non-recoverable dynamic error if the defining element has no namespace node whose name matches the prefix of the lexical QName. This error may be signaled as a static error if the value of the expression can be determined statically.

5.2 Unprefixed QNames in Expressions and Patterns

The attribute [xsl:]xpath-default-namespace (see 3.5 Standard Attributes) may be used on an element in the stylesheet to define the namespace that will be used for an unprefixed element name or type name within an XPath expression, and in certain other contexts listed below.

The value of the attribute is the namespace URI to be used.

For any element in the stylesheet, this attribute has an effective value, which is the value of the [xsl:]xpath-default-namespace on that element or on the innermost containing element that specifies such an attribute, or the zero-length string if no containing element specifies such an attribute.

For any element in the stylesheet, the effective value of this attribute determines the value of the default namespace for element and type names in the static context of any XPath expression contained in an attribute of that element (including XPath expressions in attribute value templates). The effect of this is specified in [XPath 2.1]; in summary, it determines the namespace used for any unprefixed type name in the SequenceType production, and for any element name appearing in a path expression or in the SequenceType production.

The effective value of this attribute similarly applies to any of the following constructs appearing within its scope:

any unprefixed element name or type name used in a pattern
any unprefixed element name used in the elements attribute of the xsl:strip-space or xsl:preserve-space instructions
any unprefixed element name or type name used in the as attribute of an XSLT element
any unprefixed type name used in the type attribute of an XSLT element
any unprefixed type name used in the xsl:type attribute of a literal result element.

The [xsl:]xpath-default-namespace attribute must be in the XSLT namespace if and only if its parent element is not in the XSLT namespace.

If the effective value of the attribute is a zero-length string, which will be the case if it is explicitly set to a zero-length string or if it is not specified at all, then an unprefixed element name or type name refers to a name that is in no namespace. The default namespace of the parent element (see Section 6.2 Element Nodes^DM11) is not used.

The attribute does not affect other names, for example function names, variable names, or template names, or strings that are interpreted as lexical QNames during stylesheet evaluation, such as the effective value of the name attribute of xsl:element or the string supplied as the first argument to the key function.

5.3 Expressions

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

selecting nodes for processing;
specifying conditions for different ways of processing a node;
generating text to be inserted in a result tree.

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

An XPath expression may occur as the value of certain attributes on XSLT-defined elements, and also within curly brackets in attribute value templates.

Except where forwards compatible behavior is enabled (see 3.9 Forwards Compatible Processing), it is a static error if the value of such an attribute, or the text between curly brackets in an attribute value template, does not match the XPath production Expr^XP21, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope. Error codes are defined in [XPath 2.1].

The transformation fails with a non-recoverable dynamic error if any XPath expression is evaluated and raises a dynamic error. Error codes are defined in [XPath 2.1].

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

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

[Definition: Except where otherwise indicated, the actual value of an expression is converted to the required type using the function conversion rules. These are the rules defined in [XPath 2.1] for converting the supplied argument of a function call to the required type of that argument, as defined in the function signature. The relevant rules are those that apply when XPath 1.0 compatibility mode is set to false.]

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

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

Note:

Note the distinction between the two kinds of error that may occur. Attempting to convert an integer to a date is a type error, because such a conversion is never possible. Type errors can be reported statically if they can be detected statically, whether or not the construct in question is ever evaluated. Attempting to convert the string 2003-02-29 to a date is a dynamic error rather than a type error, because the problem is with this particular value, not with its type. Dynamic errors are reported only if the instructions or expressions that cause them are actually evaluated.

5.4 The Static and Dynamic Context

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

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.4.1 Initializing the Static Context
5.4.2 Additional Static Context Components used by XSLT
5.4.3 Initializing the Dynamic Context
5.4.4 Additional Dynamic Context Components used by XSLT

5.4.1 Initializing the Static Context

The static context^XP21 of an XPath expression appearing in an XSLT stylesheet is initialized as follows. In these rules, the term containing element means the element within the stylesheet that is the parent of the attribute whose value contains the XPath expression in question, and the term enclosing element means the containing element or any of its ancestors.

XPath 1.0 compatibility mode is set to true if and only if the containing element is processed with XSLT 1.0 behavior (see 3.8 Backwards Compatible Processing).
The statically known namespaces^XP21 are the namespace declarations that are in scope for the containing element.
The default element/type namespace^XP21 is the namespace defined by the [xsl:]xpath-default-namespace attribute on the innermost enclosing element that has such an attribute, as described in 5.2 Unprefixed QNames in Expressions and Patterns. The value of this attribute is a namespace URI. If there is no [xsl:]xpath-default-namespace attribute on an enclosing element, the default namespace for element names and type names is the null namespace.
The default function namespace^XP21 is the standard function namespace, defined in [Functions and Operators]. This means that it is not necessary to declare this namespace in the stylesheet, nor is it necessary to use the prefix fn (or any other prefix) in calls to the core functions.
The in-scope schema definitions^XP21 for the XPath expression are the same as the in-scope schema components for the stylesheet, and are as specified in 3.13 Built-in Types.
The in-scope variables^XP21 are defined by the variable binding elements that are in scope for the containing element (see 9 Variables and Parameters).
The context item static type^XP21 may be determined by an XSLT processor that performs static type inferencing, using rules that are outside the scope of this specification; if no static type inferencing is done, then the context item static type for every XPath expression is item().
The function signatures^XP21 are the core functions defined in [Functions and Operators], the constructor functions for all the atomic types in the in-scope schema definitions^XP21, the additional functions defined in this specification, the stylesheet functions defined in the stylesheet, plus any extension functions bound using implementation-defined mechanisms (see 21 Extensibility and Fallback).

Note:

It follows from the above that a conformant XSLT processor must implement the entire library of core functions defined in [Functions and Operators].
The statically known collations^XP21 are implementation-defined. However, the set of in-scope collations must always include the Unicode codepoint collation, defined in Section 7.3 Equality and Comparison of Strings^FO.
The default collation^XP21 is defined by the value of the [xsl:]default-collation attribute on the innermost enclosing element that has such an attribute. For details, see 3.6.1 The default-collation attribute.

[Definition: In this specification the term default collation means the collation that is used by XPath operators such as eq and lt appearing in XPath expressions within the stylesheet.]

This collation is also used by default when comparing strings in the evaluation of the xsl:key and xsl:for-each-group elements. This may also (but need not necessarily) be the same as the default collation used for xsl:sort elements within the stylesheet. Collations used by xsl:sort are described in 13.1.3 Sorting Using Collations.
The base URI^XP21 is the base URI of the containing element in the stylesheet. The concept of the base URI of a node is defined in Section 5.2 base-uri Accessor^DM11
The set of statically known documents^XP21 is implementation-defined, and by default is empty.
The set of statically known collections^XP21 is implementation-defined, and by default is empty.
The statically known default collection type^XP21 is implementation-defined, and by default is node()*.
The set of statically known decimal formats^XP21 is the set of decimal formats defined by xsl:decimal-format declarations in the stylesheet.

Issue 5 (recommended-initial-context):

In the rules for defining the initial static context, we sometimes say that the value is implementation-defined, and then give a default. We need to be clearer what we are saying here. Essentially the "default" is a recommendation to implementors about what the value should be when users don't select anything different. Perhaps if we have recommended defaults for some of these values, we should have them for all.

5.4.2 Additional Static Context Components used by XSLT

Some of the components of the XPath static context are used also by XSLT elements. For example, the xsl:sort element makes use of the collations defined in the static context, and attributes such as type and as may reference types defined in the in-scope schema components.

Many top-level declarations in a stylesheet, and attributes on the xsl:stylesheet element, affect the behavior of instructions within the stylesheet. Each of these constructs is described in its appropriate place in this specification.

A number of these constructs are of particular significance because they are used by functions defined in XSLT, which are added to the library of functions available for use in XPath expressions within the stylesheet. These are:

The set of named keys, used by the key function
The set of named decimal formats, used by the format-number^FO function
The values of system properties, used by the system-property function
The set of available instructions, used by the element-available function

5.4.3 Initializing the Dynamic Context

For convenience, the dynamic context is described in two parts: the focus, which represents the place in the source document that is currently being processed, and a collection of additional context variables.

A number of functions specified in [Functions and Operators] are defined to be stable^FO, meaning that if they are called twice during the same execution scope^FO, with the same arguments, then they return the same results (see Section 1.7 Terminology^FO). In XSLT, the execution of a stylesheet defines the execution scope. This means, for example, that if the function current-dateTime^FO is called repeatedly during a transformation, it produces the same result each time. By implication, the components of the dynamic context on which these functions depend are also stable for the duration of the transformation. Specifically, the following components defined in Section 2.1.2 Dynamic Context^XP21 must be stable: function implementations, current dateTime, implicit timezone, available documents, available collections, and default collection. The values of global variables and stylesheet parameters are also stable for the duration of a transformation. The focus is not stable; the additional dynamic context components defined in 5.4.4 Additional Dynamic Context Components used by XSLT are also not stable.

As specified in [Functions and Operators], implementations may provide user options that relax the requirement for the doc^FO and collection^FO functions (and therefore, by implication, the document function) to return stable results. By default, however, the functions must be stable. The manner in which such user options are provided, if at all, is implementation-defined.

XPath expressions contained in [xsl:]use-when attributes are not considered to be evaluated "during the transformation" as defined above. For details see 3.12 Conditional Element Inclusion.

5.4.3.1 Maintaining Position: the Focus

[Definition: When a sequence constructor is evaluated, the processor keeps track of which items are being processed by means of a set of implicit variables referred to collectively as the focus.] More specifically, the focus consists of the following three values:

[Definition: The context item is the item currently being processed. An item (see [Data Model]) is either an atomic value (such as an integer, date, or string), a node, or a function item. The context item is initially set to the initial context item supplied when the transformation is invoked (see 2.3 Initiating a Transformation). It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; each item in such a sequence becomes the context item while that item is being processed.] The context item is returned by the XPath expression . (dot).
[Definition: The context position is the position of the context item within the sequence of items currently being processed. It changes whenever the context item changes. When an instruction such as xsl:apply-templates or xsl:for-each is used to process a sequence of items, the first item in the sequence is processed with a context position of 1, the second item with a context position of 2, and so on.] The context position is returned by the XPath expression position().
[Definition: The context size is the number of items in the sequence of items currently being processed. It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; during the processing of each one of those items, the context size is set to the count of the number of items in the sequence (or equivalently, the position of the last item in the sequence).] The context size is returned by the XPath expression last().

[Definition: If the context item is a node (as distinct from an atomic value such as an integer), then it is also referred to as the context node. The context node is not an independent variable, it changes whenever the context item changes. When the context item is an atomic value or a function item, there is no context node.] The context node is returned by the XPath expression self::node(), and it is used as the starting node for all relative path expressions.

Where the containing element of an XPath expression is an instruction or a literal result element, the initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing instruction or literal result element.

In other cases (for example, where the containing element is xsl:sort, xsl:with-param, or xsl:key), the rules are given in the specification of the containing element.

The current function can be used within any XPath expression to select the item that was supplied as the context item to the XPath expression by the XSLT processor. Unlike . (dot) this is unaffected by changes to the context item that occur within the XPath expression. The current function is described in 19.5.1 current.

On completion of an instruction that changes the focus (such as xsl:apply-templates or xsl:for-each), the focus reverts to its previous value.

When a stylesheet function is called, the focus within the body of the function is initially undefined. The focus is also undefined on initial entry to the stylesheet if no initial context item is supplied.

When the focus is undefined, evaluation of any expression that references the context item, context position, or context size results in a non-recoverable dynamic error [XPDY0002]

The description above gives an outline of the way the focus works. Detailed rules for the effect of each instruction are given separately with the description of that instruction. In the absence of specific rules, an instruction uses the same focus as its parent instruction.

[Definition: A singleton focus based on an item J has the context item (and therefore the context node, if J is a node) set to J, and the context position and context size both set to 1 (one).]

5.4.3.2 Other components of the XPath Dynamic Context

The previous section explained how the focus for an XPath expression appearing in an XSLT stylesheet is initialized. This section explains how the other components of the dynamic context^XP21 of an XPath expression are initialized.

The dynamic variables^XP21 are the current values of the in-scope variable binding elements.
The current date and time represents an implementation-dependent point in time during processing of the transformation; it does not change during the course of the transformation.
The implicit timezone^XP21 is implementation-defined.
The available documents^XP21, and the available collections^XP21 are determined as part of the process for initiating a transformation (see 2.3 Initiating a Transformation).

The available documents^XP21 are defined as part of the XPath 2.1 dynamic context to support the doc^FO function, but this component is also referenced by the similar XSLT document function: see 19.1.1 The document function. This variable defines a mapping between URIs passed to the doc^FO or document function and the document nodes that are returned.

Note:

Defining this as part of the evaluation context is a formal way of specifying that the way in which URIs get turned into document nodes is outside the control of the language specification, and depends entirely on the run-time environment in which the transformation takes place.

The XSLT-defined document function allows the use of URI references containing fragment identifiers. The interpretation of a fragment identifier depends on the media type of the resource representation. Therefore, the information supplied in available documents^XP21 for XSLT processing must provide not only a mapping from URIs to document nodes as required by XPath, but also a mapping from URIs to media types.
The default collection^XP21 is implementation-defined. This allows options such as setting the default collection to be an empty sequence, or to be undefined.

5.4.4 Additional Dynamic Context Components used by XSLT

In addition to the values that make up the focus, an XSLT processor maintains a number of other dynamic context components that reflect aspects of the evaluation context. These components are fully described in the sections of the specification that maintain and use them. They are:

The current template rule, which is the template rule most recently invoked by an xsl:apply-templates, xsl:apply-imports, or xsl:next-match instruction: see 6.8 Overriding Template Rules;
The current mode, which is the mode set by the most recent call of xsl:apply-templates (for a full definition see 6.6 Modes);
The current group and current grouping key, which provide information about the collection of items currently being processed by an xsl:for-each-group instruction: see 14.1 The Current Group and 14.2 The Current Grouping Key;
The current captured substrings: this is a sequence of strings, which is maintained when a string is matched against a regular expression using the xsl:analyze-string instruction, and which is accessible using the regex-group function: see 17.2 Captured Substrings.
The output state: this is a flag whose two possible values are final output state and temporary output state. This flag indicates whether instructions are currently writing to a final result tree or to an internal data structure. The initial setting is final output state, and it is switched to temporary output state by instructions such as xsl:variable. For more details, see 22.1 Creating Final Result Trees.

The following non-normative table summarizes the initial state of each of the components in the evaluation context, and the instructions which cause the state of the component to change.

Issue 6 (normative-evaluation-context):

Although this table is described as non-normative, it may be more complete than the same information given normatively elsewhere.

Component	Initial Setting	Set by	Cleared by
focus	singleton focus based on the initial context item if supplied	`xsl:apply-templates`, `xsl:for-each`, `xsl:for-each-group`, `xsl:analyze-string`	non-contextual function calls
current template rule	If a named template is supplied as the entry point to the transformation, then null; otherwise the initial template	`xsl:apply-templates`, `xsl:apply-imports`, `xsl:next-match`	`xsl:for-each`, `xsl:for-each-group`, `xsl:analyze-string`, `xsl:iterate`, `xsl:stream`, `xsl:merge`, `xsl:evaluate`, and non-contextual function calls. Also cleared while evaluating global variables or default values of stylesheet parameters, and the sequence constructors contained in `xsl:key` and `xsl:sort`.
current mode	the initial mode	`xsl:apply-templates`	non-contextual function calls, evaluation of global variables and stylesheet parameters, evaluation of the sequence constructor contained in `xsl:key` or `xsl:sort`. Clearing the current mode causes the current mode to be set to the default (unnamed) mode.
current group	empty sequence	`xsl:for-each-group`	non-contextual function calls
current grouping key	empty sequence	`xsl:for-each-group`	non-contextual function calls
current captured substrings	empty sequence	`xsl:matching-substring`	`xsl:non-matching-substring`; non-contextual function calls
output state	final output state	Set to temporary output state by instructions such as `xsl:variable`, `xsl:attribute`, etc., and by calls on stylesheet functions	None

[Definition: The term non-contextual function call is used to refer to function calls that do not pass the dynamic context to the called function. This includes all calls on stylesheet functions and all [TERMDEF dt-dynamic-func-invoke IN XP21]dynamic function invocations, (that is calls to function items as permitted by XPath 2.1). It does not include calls to all core functions in particular those that explicitly depend on the context, such as the current-group and regex-group functions. It is implementation-defined whether, and under what circumstances, calls to extension functions are non-contextual.]

Note:

A consequence of these rules is that whereas the function call current-group() returns the contents of the current group, the dynamic function invocation current-group#0() always returns the empty sequence.

5.5 Patterns

In XSLT 2.1, patterns can match any kind of item: atomic values 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 19.3 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 two basic kinds of pattern: type patterns, and path patterns. Patterns may also be formed by combining other patterns using union, intersection, and difference operators.

A type pattern is written with a leading ~ (tilde) followed by an ItemType^XP21 and an optional list of predicates: for example, ~xs:anyAtomicValue matches any atomic value, ~xs:integer[. mod 2 = 0] matches any even integer, ~node() matches any node, and ~function()[empty(function-name(.))] matches any function item that refers to an anonymous function. An item matches a type pattern if and only if the item is an instance of the specified type and satisfies all the predicates.

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

5.5.1 Examples of Patterns

Example: Patterns

Here are some examples of patterns:

para matches any para element.
* matches any element.
chapter|appendix matches any chapter element and any appendix element.
olist/entry matches any entry element with an olist parent.
appendix//para matches any para element with an appendix ancestor element.
schema-element(us:address) matches any element that is annotated as an instance of the type defined by the schema element declaration us:address, and whose name is either us:address or the name of another element in its substitution group.
attribute(*, xs:date) matches any attribute annotated as being of type xs:date.
/ matches a document node.
document-node() matches a document node.
document-node(schema-element(my:invoice)) matches the document node of a document whose document element is named my:invoice and matches the type defined by the global element declaration my:invoice.
text() matches any text node.
namespace-node() matches any namespace node.
node() matches any node other than an attribute node, namespace node, or document node.
id("W33") matches the element with unique ID W33.
para[1] matches any para element that is the first para child element of its parent. It also matches a parentless para element.
//para matches any para element that has a parent node.
bullet[position() mod 2 = 0] matches any bullet element that is an even-numbered bullet child of its parent.
div[@class="appendix"]//p matches any p element with a div ancestor element that has a class attribute with value appendix.
@class matches any class attribute (not any element that has a class attribute).
@* matches any attribute node.
$xyz matches any node that is present in the value of the variable $xyz.
$xyz//* matches any element that is a descendant of a node that is present in the value of the variable $xyz.
doc('product.xml')//* matches any element within the document whose document URI is 'product.xml'.
~item() matches any item whatsoever.
~node() matches any node. (Note the distinction from the pattern node().)
~element() matches any element. (This is precisely equivalent to the pattern element().)
~xs:date matches any atomic value of type xs:date (or a type derived by restriction from xs:date).
~xs:date[. gt current-date()] matches any date in the future.
~function() matches any function item.
~function(xs:integer) as xs:integer matches any function item whose underlying function takes an integer argument and returns an integer result.

5.5.2 Syntax of Patterns

[ERR XTSE0340] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern.

The grammar for patterns uses the notation defined in Section A.1.1 Notation^XP21.

The lexical rules for patterns are the same as the lexical rules for XPath expressions, as defined in Section A.2 Lexical structure^XP21. Comments are permitted between tokens, using the syntax (: ... :). All other provisions of the XPath grammar apply where relevant, for example the rules for whitespace handling and extra-grammatical constraints.

Every pattern is a legal XPath expression, but the converse is not true: 2+2 is an example of a legal XPath expression that is not a pattern. The XPath expressions that can be used as patterns are those that match the grammar for Pattern, given below.

Informally, a Pattern is a set of path expressions separated by |, where each step in the path expression is constrained to be an AxisStep^XP21 that uses only the child or attribute axes. Patterns may also use the // operator. A Predicate^XP21 within the PredicateList^XP21 in a pattern can contain arbitrary XPath expressions (enclosed between square brackets) in the same way as a predicate^XP21 in a path expression.

Patterns may start with an id^FO or key function call, provided that the value to be matched is supplied as either a literal or a reference to a variable or parameter, and the key name (in the case of the key function) is supplied as a string literal. These patterns will never match a node in a tree whose root is not a document node.

If a pattern appears in an attribute of an element that is processed with XSLT 1.0 behavior (see 3.8 Backwards Compatible Processing), then the semantics of the pattern are defined on the basis that the equivalent XPath expression is evaluated with XPath 1.0 compatibility mode set to true.

Patterns

[1]	`Pattern`	::=	`PatternTerm ( ('\|' \| 'union') PatternTerm )*`
[2]	`PatternTerm`	::=	`BasicPattern ( ('intersect' \| 'except') BasicPattern )*`
[3]	`BasicPattern`	::=	`TypePattern \| PathPattern \| QualifiedPattern`
[4]	`QualifiedPattern`	::=	`'(' Pattern ')' PredicateList^XP21`
[5]	`TypePattern`	::=	`'~' ItemType^XP21 PredicateList^XP21`
[6]	`PathPattern`	::=	`RelativePathPattern`
			`\| '/' RelativePathPattern?`
			`\| '//' RelativePathPattern`
			`\| RootedPattern`
[7]	`RootedPattern`	::=	`( VarRefRoot \| DocCall \| IdCall \| ElementWithIdCall \| KeyCall )`
			`(('/' \| '//') RelativePathPattern)?`
[8]	`VarRefRoot`	::=	`VarRef^XP21`
[9]	`RelativePathPattern`	::=	`PatternStep (('/' \| '//') PatternStep)*`
[10]	`PatternStep`	::=	`PatternAxis? NodeTest^XP21 PredicateList^XP21`
[11]	`PatternAxis`	::=	`(('child' \| 'attribute' \| 'descendant' \| 'descendant-or-self') '::') \| '@'`
[12]	`DocCall`	::=	`'doc' '(' ArgValue ')'`
[13]	`IdCall`	::=	`'id' '(' ArgValue (',' ArgValue )? ')'`
[14]	`ElementWithIdCall`	::=	`'element-with-id' '(' ArgValue (',' ArgValue )? ')'`
[15]	`KeyCall`	::=	`'key' '(' ArgValue ',' ArgValue (',' ArgValue )? ')'`
[16]	`ArgValue`	::=	`Literal^XP21 \| VarRef^XP21`

The constructs ItemType^XP21, NodeTest^XP21, PredicateList^XP21, VarRef^XP21, and Literal^XP21 are part of the XPath expression language, and are defined in [XPath 2.1].

In a DocCall, IdCall, ElementWithIdCall, or KeyCall, the construct has the same semantics as a call to the corresponding function in an XPath expression. In particular, the arguments must (after conversion using the function conversion rules if necessary) be of the correct type required by the signature of the function. The function conversion rules are applied with XPath 1.0 compatibility mode set to false. If an argument cannot be converted to the required type, a type error results: if the type error can be detected statically then it may be signalled statically.

5.5.3 The Meaning of a Pattern

The meaning of a pattern is defined formally as follows, where "if" is to be read as "if and only if".

An item matches the Pattern A | B (or equivalently, A union B) if it matches either A or B or both. (The operators | and union are synonyms.)
An item matches the PatternTerm A intersect B if it matches both A and B.

Note:

The operators union, |, intersect, and except are analogous to the XPath operators with the same representation, but there is a difference: in patterns, the definition above gives these operators a meaning when matching atomic values as well as when matching nodes.

Note:

As with XPath expressions, the pattern / union /* can be parsed in two different ways, and the chosen interpretation is to treat union as an element name rather than as an operator. The other interpretation can b be achieved by writing (/) union (/*)
An item matches the PatternTerm A except B if it matches A and does not match B.
Multiple intersect and except operators are applied from left to right: for example A intersect B except C means (A intersect B) except C: that is, the item must match both A and B, and must not match C.
An item J matches a QualifiedPattern if J matches the parenthesized Pattern and satisfies each of the predicates in the PredicateList^XP21. The predicates are evaluated with a singleton focus based on J.
An item J matches a TypePattern if J is an instance of the specified ItemType^XP21 and satisfies each of the predicates in the PredicateList^XP21. The predicates are evaluated with a singleton focus based on J.
An item N matches a PathPattern if N is a node and the result of evaluating the expression root(.)//(EE) with a singleton focus based on N is a sequence that includes the node N, where EE is the equivalent expression to the PathPattern, as defined below.

The concept of an equivalent expression is defined as follows. In general, the equivalent expression to a PathPattern is the XPath expression that takes the same lexical form as the PathPattern as written. However, if the PathPattern is a RelativePathPattern, then the first PatternStep PS of this RelativePathPattern is adjusted to allow it to match a parentless element, attribute, or namespace node. The adjustment depends on the axis used in this step, whether it appears explicitly or implicitly (according to the rules of Section 3.2.4 Abbreviated Syntax^XP), and is made as follows:
1. If the NodeTest in PS is document-node() (optionally with arguments), and if no explicit axis is specified, then the axis in step PS is taken as self rather than child.
2. If PS uses the child axis (explicitly or implicitly), and if the NodeTest in PS is not document-node() (optionally with arguments), then the axis in step PS is replaced by child-or-top, which is defined as follows. If the context node is a parentless element, comment, processing-instruction, or text node then the child-or-top axis selects the context node; otherwise it selects the children of the context node. It is a forwards axis whose principal node kind is element.
3. If PS uses the attribute axis (explicitly or implicitly), then the axis in step PS is replaced by attribute-or-top, which is defined as follows. If the context node is an attribute node with no parent, then the attribute-or-top axis selects the context node; otherwise it selects the attributes of the context node. It is a forwards axis whose principal node kind is attribute.
4. If PS uses the namespace axis (implicitly, by using namespace-node() as a KindTest), then the axis in step PS is replaced by namespace-or-top, which is defined as follows. If the context node is a namespace node with no parent, then the namespace-or-top axis selects the context node; otherwise it selects the namespace nodes of the context node. It is a forwards axis whose principal node kind is namespace.
  
  Issue 7 (implicit-namespace-axis):
  
  In XPath 2.1, as currently defined, the path expression A/B/namespace-node() selects nothing, because the default axis for the abbreviated step namespace-node() is child rather than namespace. This has been raised as bug 9298. Perhaps we should allow the namespace axis to be explicit in a pattern.
The axes child-or-top, attribute-or-top, and namespace-or-top are introduced only for definitional purposes. They cannot be used explicitly in a user-written pattern or expression.

Note:

The purpose of these adjustments is to ensure that a pattern such as person matches any element named person, even if it has no parent; and similarly, that the pattern @width matches any attribute named width, even a parentless attribute. The rule also ensures that a pattern using a NodeTest of the form document-node(...) matches a document node. The pattern node() will match any element, text node, comment, or processing instruction, whether or not it has a parent. For backwards compatibility reasons, the pattern node(), when used without an explicit axis, does not match document nodes, attribute nodes, or namespace nodes. The rules are also phrased to ensure that positional patterns of the form para[1] continue to count nodes relative to their parent, if they have one. To match any node at all, XSLT 2.1 allows the pattern ~node() to be used (note the tilde).

Example: The Semantics of Path Patterns

The path pattern p matches any p element, because a p element will always be present in the result of evaluating the expression root(.)//(child-or-top::p). Similarly, / matches a document node, and only a document node, because the result of the expression root(.)//(/) returns the root node of the tree containing the context node if and only if it is a document node.

The path pattern node() matches all nodes selected by the expression root(.)//(child-or-top::node()), that is, all element, text, comment, and processing instruction nodes, whether or not they have a parent. It does not match attribute or namespace nodes because the expression does not select nodes using the attribute or namespace axes. It does not match document nodes because for backwards compatibility reasons the child-or-top axis does not match a document node.

The path pattern $V matches all nodes selected by the expression root(.)//($V), that is, all nodes in the value of $V (which will typically be a global variable, though when the pattern is used in contexts such as the xsl:number or xsl:for-each-group instructions, it can also be a local variable).

The path pattern doc('product.xml')//product matches all nodes selected by the expression root(.)//(doc('product.xml')//product), that is, all product elements in the document whose URI is product.xml.

Although the semantics of path patterns are specified formally in terms of expression evaluation, it is possible to understand pattern matching using a different model. A path pattern such as book/chapter/section can be examined from right to left. A node will only match this pattern if it is a section element; and then, only if its parent is a chapter; and then, only if the parent of that chapter is a book. When the pattern uses the // operator, one can still read it from right to left, but this time testing the ancestors of a node rather than its parent. For example appendix//section matches every section element that has an ancestor appendix element.

The formal definition, however, is useful for understanding the meaning of a pattern such as para[1]. This matches any node selected by the expression root(.)//(child-or-top::para[1]): that is, any para element that is the first para child of its parent, or a para element that has no parent.

Note:

An implementation, of course, may use any algorithm it wishes for evaluating patterns, so long as the result corresponds with the formal definition above. An implementation that followed the formal definition by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.

5.5.4 Errors in Patterns

Any dynamic error or type error that occurs during the evaluation of a pattern against a particular item is treated as a recoverable error even if the error would not be recoverable under other circumstances. The optional recovery action is to treat the pattern as not matching that node.

Note:

The reason for this provision is that it is difficult for the stylesheet author to predict which predicates in a pattern will actually be evaluated. In the case of match patterns in template rules, it is not even possible to predict which patterns will be evaluated against a particular node. Making errors in patterns recoverable enables an implementation, if it chooses to do so, to report such errors while stylesheets are under development, while masking them if they occur during production running.

There are several particular cases where a processor must not raise a dynamic error:

When evaluating a PathPattern that starts with / or // or with a call on id^FO, element-with-id^FO, or key, the result of testing this pattern against a node in a tree whose root is not a document node must be a non-match, rather than a dynamic error. This rule applies to each PathPattern within a Pattern.

Note:

Without the above rule, any attempt to apply templates to a parentless element node would create the risk of a dynamic error if the stylesheet has a template rule specifying match="/".
When matching an atomic value against a PathPattern, the result must always be a non-match, rather than a dynamic error.
A processor must not evaluate a predicate within a pattern unless the item matches the part of the pattern that is qualified by the predicate. (Or equivalently, if it does evaluate the predicate, it must not signal an error when the evaluation fails.) For example, evaluation of the pattern ~xs:integer[. gt 5] must not cause an error when testing an item of type xs:date, and the pattern $var[child::*] must not cause an error when testing an atomic value. If there are multiple predicates, they must be evaluated from left to right.

5.6 Attribute Value Templates

[Definition: In an attribute that is designated as an attribute value template, such as an attribute of a literal result element, an expression can be used by surrounding the expression with curly brackets ({})].

An attribute value template consists of an alternating sequence of fixed parts and variable parts. A variable part consists of an XPath expression enclosed in curly brackets ({}). A fixed part may contain any characters, except that a left curly bracket must be written as {{ and a right curly bracket must be written as }}. If the XPath expression ends with a closing curly bracket, this must be separated from the delimiting closing bracket by whitespace.

Note:

An expression within a variable part may contain an unescaped curly bracket within a StringLiteral^XP21 or within a comment.

Currently no XPath expression starts with an opening curly bracket, and the only XPath expression that can end in a closing curly bracket is an inline function literal, which cannot usefully appear in an attribute value template.

[ERR XTSE0350] It is a static error if an unescaped left curly bracket appears in a fixed part of an attribute value template without a matching right curly bracket.

It is a static error if the string contained between matching curly brackets in an attribute value template does not match the XPath production Expr^XP21, or if it contains other XPath static errors. The error is signaled using the appropriate XPath error code.

[ERR XTSE0370] It is a static error if an unescaped right curly bracket occurs in a fixed part of an attribute value template.

[Definition: The result of evaluating an attribute value template is referred to as the effective value of the attribute.] The effective value is the string obtained by concatenating the expansions of the fixed and variable parts:

The expansion of a fixed part is obtained by replacing any double curly brackets ({{ or }}) by the corresponding single curly bracket.
The expansion of a variable part is obtained by evaluating the enclosed XPath expression and converting the resulting value to a string. This conversion is done using the rules given in 5.7.2 Constructing Simple Content.

Note:

This process can generate dynamic errors, for example if the sequence contains an element with a complex content type (which cannot be atomized).

If the element containing the attribute is processed with XSLT 1.0 behavior, then the rules for converting the value of the expression to a string are modified as follows. After atomizing the result of the expression, all items other than the first item in the resulting sequence are discarded, and the effective value is obtained by converting the first item in the sequence to a string. If the atomized sequence is empty, the result is a zero-length string.

Curly brackets are not treated specially in an attribute value in an XSLT stylesheet unless the attribute is specifically designated as one that permits an attribute value template; in an element syntax summary, the value of such attributes is surrounded by curly brackets.

Note:

Not all attributes are designated as attribute value templates. Attributes whose value is an expression or pattern, attributes of declaration elements and attributes that refer to named XSLT objects are generally not designated as attribute value templates (an exception is the format attribute of xsl:result-document). Namespace declarations are not XDM attribute nodes and are therefore never treated as attribute value templates.

Example: Attribute Value Templates

The following example creates an img result element from a photograph element in the source; the value of the src and width attributes are computed using XPath expressions enclosed in attribute value templates:

<xsl:variable name="image-dir" select="'/images'"/>

<xsl:template match="photograph">
  <img src="{$image-dir}/{href}" width="{size/@width}"/>
</xsl:template>

With this source

<photograph>
  <href>headquarters.jpg</href>
  <size width="300"/>
</photograph>

the result would be

<img src="/images/headquarters.jpg" width="300"/>

Example: Producing a Space-Separated List

The following example shows how the values in a sequence are output as a space-separated list. The following literal result element:

<temperature readings="{10.32, 5.50, 8.31}"/>

produces the output node:

<temperature readings="10.32 5.5 8.31"/>

Curly brackets are not recognized recursively inside expressions.

Example: Curly Brackets can not be Nested

For example:

<a href="#{id({@ref})/title}">

is not allowed. Instead, use simply:

<a href="#{id(@ref)/title}">

5.7 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 values, 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:

A Text node appearing in the stylesheet (if it has not been removed in the process of whitespace stripping: see 4.2 Stripping Whitespace from the Stylesheet) is copied to create a new parentless text node.
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.
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 values 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 values, function items, or existing nodes.
An extension instruction (see 21.2 Extension Instructions) also produces a sequence of items as its result.

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.

There are several ways the result of a sequence constructor may be used.

The sequence may be bound to a variable or returned from a stylesheet function, in which case it becomes available as a value to be manipulated in arbitrary ways by XPath expressions. The sequence is bound to a variable when the sequence constructor appears within one of the elements xsl:variable, xsl:param, or xsl:with-param, when this instruction has an as attribute. The sequence is returned from a stylesheet function when the sequence constructor appears within the xsl:function element.

Note:

This will typically expose to the stylesheet elements, attributes, and other nodes that have not yet been attached to a 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 when the element containing the sequence constructor is xsl:analyze-string, xsl:apply-imports, xsl:apply-templates, xsl:break, xsl:call-template, xsl:catch, xsl:choose, xsl:fallback, xsl:for-each, xsl:for-each-group, xsl:fork, xsl:if, xsl:iterate, xsl:matching-substring, xsl:next-match, 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, or xsl:message. It also happens when the sequence constructor is contained in one of the elements xsl:variable, xsl:param, xsl:with-param, or xsl:context-item, when this instruction has no as attribute. For details, see 5.7.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.7.2 Constructing Simple Content.

Note:

The term sequence constructor replaces template as used in XSLT 1.0. The change is made partly for clarity (to avoid confusion with template rules and named templates), but also to reflect a more formal definition of the semantics. Whereas XSLT 1.0 described a template as a sequence of instructions that write to the result tree, XSLT 2.0 describes a sequence constructor as something that can be evaluated to return a sequence of items; what happens to these items depends on the containing instruction.

5.7.1 Constructing Complex Content

This section describes how the sequence obtained by evaluating a sequence constructor may be used to construct the children of a newly constructed document node, or the children, attributes and namespaces of a newly constructed element node. The sequence of items may be obtained by evaluating the sequence constructor contained in an instruction such as xsl:copy, xsl:element, xsl:document, xsl:result-document, or a literal result element.

When constructing the content of an element, the inherit-namespaces attribute of the xsl:element or xsl:copy instruction, or the xsl:inherit-namespaces property of the literal result element, determines whether namespace nodes are to be inherited. The effect of this attribute is described in the rules that follow.

The sequence is processed as follows (applying the rules in the order they are listed):

The containing instruction may generate attribute nodes and/or namespace nodes, as specified in the rules for the individual instruction. For example, these nodes may be produced by expanding an [xsl:]use-attribute-sets attribute, or by expanding the attributes of a literal result element. Any such nodes are prepended to the sequence produced by evaluating the sequence constructor.
Any atomic value in the sequence is cast to a string.

Note:

Casting from xs:QName or xs:NOTATION to xs:string always succeeds, because these values retain a prefix for this purpose. However, there is no guarantee that the prefix used will always be meaningful in the context where the resulting string is used.
Any consecutive sequence of strings within the result sequence is converted to a single text node, whose string value contains the content of each of the strings in turn, with a single space (#x20) used as a separator between successive strings.
Any document node within the result sequence is replaced by a sequence containing each of its children, in document order.
Zero-length text nodes within the result sequence are removed.
Adjacent text nodes within the result sequence are merged into a single text node.
Invalid items in the result sequence are detected as follows.

[ERR XTDE0410] It is a non-recoverable dynamic error if the result sequence used to construct the content of an element node contains a namespace node or attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node.

[ERR XTDE0420] It is a non-recoverable dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node.

[ERR XTDE0430] It is a non-recoverable dynamic error if the result sequence contains two or more namespace nodes having the same name but different string values (that is, namespace nodes that map the same prefix to different namespace URIs).

[ERR XTDE0440] It is a non-recoverable dynamic error if the result sequence contains a namespace node with no name and the element node being constructed has a null namespace URI (that is, it is an error to define a default namespace when the element is in no namespace).

[ERR XTDE0450] It is a non-recoverable dynamic error if the result sequence contains a function item.
If the result sequence contains two or more namespace nodes with the same name (or no name) and the same string value (that is, two namespace nodes mapping the same prefix to the same namespace URI), then all but one of the duplicate nodes are discarded.

Note:

Since the order of namespace nodes is undefined, it is not significant which of the duplicates is retained.
If an attribute A in the result sequence has the same name as another attribute B that appears later in the result sequence, then attribute A is discarded from the result sequence. Before discarding attribute A, the processor may signal any type errors that would be signaled if attribute B were not present.
Each node in the resulting sequence is attached as a namespace, attribute, or child of the newly constructed element or document node. Conceptually this involves making a deep copy of the node; in practice, however, copying the node will only be necessary if the existing node can be referenced independently of the parent to which it is being attached. When copying an element or processing instruction node, its base URI property is changed to be the same as that of its new parent, unless it has an xml:base attribute (see [XML Base]) that overrides this. If the copied element has an xml:base attribute, its base URI is the value of that attribute, resolved (if it is relative) against the base URI of the new parent node.
If the newly constructed node is an element node, then namespace fixup is applied to this node, as described in 5.7.3 Namespace Fixup.
If the newly constructed node is an element node, and if namespaces are inherited, then each namespace node of the newly constructed element (including any produced as a result of the namespace fixup process) is copied to each descendant element of the newly constructed element, unless that element or an intermediate element already has a namespace node with the same name (or absence of a name) or that descendant element or an intermediate element is in no namespace and the namespace node has no name.

Example: A Sequence Constructor for Complex Content

Consider the following stylesheet fragment:

<td>
  <xsl:attribute name="valign">top</xsl:attribute>
  <xsl:value-of select="@description"/>
</td>

This fragment consists of a literal result element td, containing a sequence constructor that consists of two instructions: xsl:attribute and xsl:value-of. The sequence constructor is evaluated to produce a sequence of two nodes: a parentless attribute node, and a parentless text node. The td instruction causes a td element to be created; the new attribute therefore becomes an attribute of the new td element, while the text node created by the xsl:value-of instruction becomes a child of the td element (unless it is zero-length, in which case it is discarded).

Example: Space Separators in Element Content

Consider the following stylesheet fragment:

<doc>
  <e><xsl:sequence select="1 to 5"/></e>
  <f>
    <xsl:for-each select="1 to 5">
      <xsl:value-of select="."/>
    </xsl:for-each>
  </f>
</doc>

This produces the output (when indented):

<doc>
  <e>1 2 3 4 5</e>
  <f>12345</f>
</doc>

The difference between the two cases is that for the e element, the sequence constructor generates a sequence of five atomic values, which are therefore separated by spaces. For the f element, the content is a sequence of five text nodes, which are concatenated without space separation.

It is important to be aware of the distinction between xsl:sequence, which returns the value of its select expression unchanged, and xsl:value-of, which constructs a text node.

5.7.2 Constructing Simple Content

The instructions xsl:attribute, xsl:comment, xsl:processing-instruction, xsl:namespace, and xsl:value-of all create nodes that cannot have children. Specifically, the xsl:attribute instruction creates an attribute node, xsl:comment creates a comment node, xsl:processing-instruction creates a processing instruction node, xsl:namespace creates a namespace node, and xsl:value-of creates a text node. The string value of the new node is constructed using either the select attribute of the instruction, or the sequence constructor that forms the content of the instruction. The select attribute allows the content to be specified by means of an XPath expression, while the sequence constructor allows it to be specified by means of a sequence of XSLT instructions. The select attribute or sequence constructor is evaluated to produce a result sequence, and the string value of the new node is derived from this result sequence according to the rules below.

These rules are also used to compute the effective value of an attribute value template. In this case the sequence being processed is the result of evaluating an XPath expression enclosed between curly brackets, and the separator is a single space character.

Zero-length text nodes in the sequence are discarded.
Adjacent text nodes in the sequence are merged into a single text node.
The sequence is atomized (which may cause a dynamic error).
Every value in the atomized sequence is cast to a string.
The strings within the resulting sequence are concatenated, with a (possibly zero-length) separator inserted between successive strings. The default separator is a single space. In the case of xsl:attribute and xsl:value-of, a different separator can be specified using the separator attribute of the instruction; it is permissible for this to be a zero-length string, in which case the strings are concatenated with no separator. In the case of xsl:comment, xsl:processing-instruction, and xsl:namespace, and when expanding an attribute value template, the default separator cannot be changed.
In the case of xsl:processing-instruction, any leading spaces in the resulting string are removed.
The resulting string forms the string value of the new attribute, namespace, comment, processing-instruction, or text node.

Example: Space Separators in Attribute Content

Consider the following stylesheet fragment:

<doc>
  <xsl:attribute name="e" select="1 to 5"/>
  <xsl:attribute name="f">
    <xsl:for-each select="1 to 5">
      <xsl:value-of select="."/>
    </xsl:for-each>
  </xsl:attribute>
</doc>

This produces the output:

<doc e="1 2 3 4 5" f="12345"/>

The difference between the two cases is that for the e attribute, the sequence constructor generates a sequence of five atomic values, which are therefore separated by spaces. For the f attribute, the content is supplied as a sequence of five text nodes, which are concatenated without space separation.

Specifying separator="" on the first xsl:attribute instruction would cause the attribute value to be e="12345". A separator attribute on the second xsl:attribute instruction would have no effect, since the separator only affects the way adjacent atomic values are handled: separators are never inserted between adjacent text nodes.

Note:

If an attribute value template contains a sequence of fixed and variable parts, no additional whitespace is inserted between the expansions of the fixed and variable parts. For example, the effective value of the attribute a="chapters{4 to 6}" is a="chapters4 5 6".

5.7.3 Namespace Fixup

In a tree supplied to or constructed by an XSLT processor, the constraints relating to namespace nodes that are specified in [Data Model] must be satisfied. For example

If an element node has an expanded-QName with a non-null namespace URI, then that element node must have at least one namespace node whose string value is the same as that namespace URI.
If an element node has an attribute node whose expanded-QName has a non-null namespace URI, then the element must have at least one namespace node whose string value is the same as that namespace URI and whose name is non-empty.
Every element must have a namespace node whose expanded-QName has local-part xml and whose string value is http://www.w3.org/XML/1998/namespace. The namespace prefix xml must not be associated with any other namespace URI, and the namespace URI http://www.w3.org/XML/1998/namespace must not be associated with any other prefix.
A namespace node must not have the name xmlns or the string value http://www.w3.org/2000/xmlns/.

[Definition: The rules for the individual XSLT instructions that construct a result tree (see 11 Creating Nodes and Sequences) prescribe some of the situations in which namespace nodes are written to the tree. These rules, however, are not sufficient to ensure that the prescribed constraints are always satisfied. The XSLT processor must therefore add additional namespace nodes to satisfy these constraints. This process is referred to as namespace fixup.]

The actual namespace nodes that are added to the tree by the namespace fixup process are implementation-dependent, provided firstly, that at the end of the process the above constraints must all be satisfied, and secondly, that a namespace node must not be added to the tree unless the namespace node is necessary either to satisfy these constraints, or to enable the tree to be serialized using the original namespace prefixes from the source document or stylesheet.

Namespace fixup must not result in an element having multiple namespace nodes with the same name.

Namespace fixup may, if necessary to resolve conflicts, change the namespace prefix contained in the QName value that holds the name of an element or attribute node. This includes the option to add or remove a prefix. However, namespace fixup must not change the prefix component contained in a value of type xs:QName or xs:NOTATION that forms the typed value of an element or attribute node.

Note:

Namespace fixup is not used to create namespace declarations for xs:QName or xs:NOTATION values appearing in the content of an element or attribute.

Where values acquire such types as the result of validation, namespace fixup does not come into play, because namespace fixup happens before validation: in this situation, it is the user's responsibility to ensure that the element being validated has the required namespace nodes to enable validation to succeed.

Where existing elements are copied along with their existing type annotations (validation="preserve") the rules require that existing namespace nodes are also copied, so that any namespace-sensitive values remain valid.

Where existing attributes are copied along with their existing type annotations, the rules of the XDM data model require that a parentless attribute node cannot contain a namespace-sensitive typed value; this means that it is an error to copy an attribute using validation="preserve" if it contains namespace-sensitive content.

Namespace fixup is applied to every element that is constructed using a literal result element, or one of the instructions xsl:element, xsl:copy, or xsl:copy-of. An implementation is not required to perform namespace fixup for elements in any source document, that is, for a document in the initial input sequence, documents loaded using the document, doc^FO or collection^FO function, documents supplied as the value of a stylesheet parameter, or documents returned by an extension function or extension instruction.

Note:

A source document (an input document, a document returned by the document, doc^FO or collection^FO functions, a document returned by an extension function or extension instruction, or a document supplied as a stylesheet parameter) is required to satisfy the constraints described in [Data Model], including the constraints imposed by the namespace fixup process. The effect of supplying a pseudo-document that does not meet these constraints is undefined.

In an Infoset (see [XML Information Set]) created from a document conforming to [Namespaces in XML], it will always be true that if a parent element has an in-scope namespace with a non-empty namespace prefix, then its child elements will also have an in-scope namespace with the same namespace prefix, though possibly with a different namespace URI. This constraint is removed in [Namespaces in XML 1.1]. XSLT 2.1 supports the creation of result trees that do not satisfy this constraint: the namespace fixup process does not add a namespace node to an element merely because its parent node in the result tree has such a namespace node. However, the process of constructing the children of a new element, which is described in 5.7.1 Constructing Complex Content, does cause the namespaces of a parent element to be inherited by its children unless this is prevented using [xsl:]inherit-namespaces="no" on the instruction that creates the parent element.

Note:

This has implications on serialization, defined in [XSLT and XQuery Serialization]. It means that it is possible to create final result trees that cannot be faithfully serialized as XML 1.0 documents. When such a result tree is serialized as XML 1.0, namespace declarations written for the parent element will be inherited by its child elements as if the corresponding namespace nodes were present on the child element, except in the case of the default namespace, which can be undeclared using the construct xmlns="". When the same result tree is serialized as XML 1.1, however, it is possible to undeclare any namespace on the child element (for example, xmlns:foo="") to prevent this inheritance taking place.

5.8 URI References

[Definition: Within this specification, the term URI Reference, unless otherwise stated, refers to a string in the lexical space of the xs:anyURI data type as defined in [XML Schema Part 2].] Note that this is a wider definition than that in [RFC3986]: in particular, it is designed to accommodate Internationalized Resource Identifiers (IRIs) as described in [RFC3987], and thus allows the use of non-ASCII characters without escaping.

URI References are used in XSLT with three main roles:

As namespace URIs
As collation URIs
As identifiers for resources such as stylesheet modules; these resources are typically accessible using a protocol such as HTTP. Examples of such identifiers are the URIs used in the href attributes of xsl:import, xsl:include, and xsl:result-document.

The rules for namespace URIs are given in [Namespaces in XML] and [Namespaces in XML 1.1]. Those specifications deprecate the use of relative URI references as namespace URIs.

The rules for collation URIs are given in [Functions and Operators].

URI references used to identify external resources must conform to the same rules as the locator attribute (href) defined in section 5.4 of [XLink]. If the URI reference is relative, then it is resolved (unless otherwise specified) against the base URI of the containing element node, according to the rules of [RFC3986], after first escaping all characters that need to be escaped to make it a valid RFC3986 URI reference. (But a relative URI reference in the href attribute of xsl:result-document is resolved against the Base Output URI.)

Other URI references appearing in an XSLT stylesheet document, for example the system identifiers of external entities or the value of the xml:base attribute, must follow the rules in their respective specifications.

6 Template Rules

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

6.1 Defining Templates

 <xsl:template match? = pattern name? = qname priority? = number mode? = tokens as? = sequence-type >  </xsl:template>

[Definition: An xsl:template declaration defines a template, which contains a sequence constructor for creating nodes, atomic values, and/or function items. A template can serve either as a template rule, invoked by matching items against a pattern, or as a named template, invoked explicitly by name. It is also possible for the same template to serve in both capacities.]

[ERR XTSE0500] An xsl:template element must have either a match attribute or a name attribute, or both. An xsl:template element that has no match attribute must have no mode attribute and no priority attribute.

If an xsl:template element has a match attribute, then it is a template rule. If it has a name attribute, then it is a named template.

A template may be invoked in a number of ways, depending on whether it is a template rule, a named template, or both. The result of invoking the template is the result of evaluating the sequence constructor contained in the xsl:template element (see 5.7 Sequence Constructors).

If an as attribute is present, the as attribute defines the required type of the result. The result of evaluating the sequence constructor is then converted to the required type using the function conversion rules. If no as attribute is specified, the default value is item()*, which permits any value. No conversion then takes place.

[ERR XTTE0505] It is a type error if the result of evaluating the sequence constructor cannot be converted to the required type.

6.2 Defining Template Rules

This section describes template rules. Named templates are described in 10.1 Named Templates.

A template rule is specified using the xsl:template element with a match attribute. The match attribute is a Pattern that identifies the items to which the rule applies. The result of applying the template rule is the result of evaluating the sequence constructor contained in the xsl:template element, with the matching item used as the context item.

Example: A simple Template Rule

For example, an XML document might contain:

This is an <emph>important</emph> point.

The following template rule matches emph elements and produces a fo:wrapper element with a font-weight property of bold.

<xsl:template match="emph">
  <fo:wrapper font-weight="bold" 
              xmlns:fo="http://www.w3.org/1999/XSL/Format">
    <xsl:apply-templates/>
  </fo:wrapper>
</xsl:template>

A template rule is evaluated when an xsl:apply-templates instruction selects an item that matches the pattern specified in the match attribute. The xsl:apply-templates instruction is described in the next section. If several template rules match a selected item, only one of them is evaluated, as described in 6.4 Conflict Resolution for Template Rules.

6.3 Applying Template Rules

 <xsl:apply-templates select? = expression mode? = token >  </xsl:apply-templates>

The xsl:apply-templates instruction takes as input a sequence of items (typically nodes in a source tree), and produces as output a sequence of items; these will often be nodes to be added to a result tree.

If the instruction has one or more xsl:sort children, then the input sequence is sorted as described in 13 Sorting. The result of this sort is referred to below as the sorted sequence; if there are no xsl:sort elements, then the sorted sequence is the same as the input sequence.

Each item in the input sequence is processed by finding a template rule whose pattern matches that item. If there is more than one such template rule, the best among them is chosen, using rules described in 6.4 Conflict Resolution for Template Rules. If there is no template rule whose pattern matches the item, a built-in template rule is used (see 6.7 Built-in Template Rules). The chosen template rule is evaluated. The rule that matches the Nth item in the sorted sequence is evaluated with that item as the context item, with N as the context position, and with the length of the sorted sequence as the context size. Each template rule that is evaluated produces a sequence of items as its result. The resulting sequences (one for each item in the sorted sequence) are then concatenated, to form a single sequence. They are concatenated retaining the order of the items in the sorted sequence. The final concatenated sequence forms the result of the xsl:apply-templates instruction.

Example: Applying Template Rules

Suppose the source document is as follows:

<message>Proceed <emph>at once</emph> to the exit!</message>

This can be processed using the two template rules shown below.

<xsl:template match="message">
  <p>
    <xsl:apply-templates select="child::node()"/>
  </p>
</xsl:template>

<xsl:template match="emph">
  <b>
    <xsl:apply-templates select="child::node()"/>
  </b>
</xsl:template>

There is no template rule for the document node; the built-in template rule for this node will cause the message element to be processed. The template rule for the message element causes a p element to be written to the result tree; the contents of this p element are constructed as the result of the xsl:apply-templates instruction. This instruction selects the three child nodes of the message element (a text node containing the value "Proceed ", an emph element node, and a text node containing the value " to the exit!"). The two text nodes are processed using the built-in template rule for text nodes, which returns a copy of the text node. The emph element is processed using the explicit template rule that specifies match="emph".

When the emph element is processed, this template rule constructs a b element. The contents of the b element are constructed by means of another xsl:apply-templates instruction, which in this case selects a single node (the text node containing the value "at once"). This is again processed using the built-in template rule for text nodes, which returns a copy of the text node.

The final result of the match="message" template rule thus consists of a p element node with three children: a text node containing the value "Proceed ", a b element that is the parent of a text node containing the value "at once", and a text node containing the value " to the exit!". This result tree might be serialized as:

<p>Proceed <b>at once</b> to the exit!</p>

The default value of the select attribute is child::node(), which causes all the children of the context node to be processed.

[ERR XTTE0510] It is a type error if an xsl:apply-templates instruction with no select attribute is evaluated when the context item is not a node.

A select attribute can be used to process items selected by an expression instead of processing all children. The value of the select attribute is an expression. The expression must evaluate to a sequence of nodes (it can contain zero, one, or more nodes).

[ERR XTTE0520] It is a type error if the sequence returned by the select expression contains an item that is not a node.

Note:

In XSLT 1.0, the select attribute selected a set of nodes, which by default were processed in document order. In XSLT 2.0, it selects a sequence of nodes. In cases that would have been valid in XSLT 1.0, the expression will return a sequence of nodes in document order, so the effect is the same.

Example: Applying Templates to Selected Nodes

The following example processes all of the given-name children of the author elements that are children of author-group:

<xsl:template match="author-group">
  <fo:wrapper>
    <xsl:apply-templates select="author/given-name"/>
  </fo:wrapper>
</xsl:template>

Example: Applying Templates to Nodes that are not Descendants

It is also possible to process elements that are not descendants of the context node. This example assumes that a department element has group children and employee descendants. It finds an employee's department and then processes the group children of the department.

<xsl:template match="employee">
  <fo:block>
    Employee <xsl:apply-templates select="name"/> belongs to group
    <xsl:apply-templates select="ancestor::department/group"/>
  </fo:block>
</xsl:template>

Example: Matching Nodes by Schema-Defined Types

It is possible to write template rules that are matched according to the schema-defined type of an element or attribute. The following example applies different formatting to the children of an element depending on their type:

<xsl:template match="product">
  <table>
    <xsl:apply-templates select="*"/>
  </table>
</xsl:template>

<xsl:template match="product/*" priority="3">
  <tr>
    <td><xsl:value-of select="name()"/></td>
    <td><xsl:next-match/></td>
  </tr>
</xsl:template>

<xsl:template match="product/element(*, xs:decimal) | 
                     product/element(*, xs:double)" priority="2">  
  <xsl:value-of select="format-number(xs:double(.), '#,###0.00')"/>
</xsl:template>

<xsl:template match="product/element(*, xs:date)" priority="2">
  <xsl:value-of select="format-date(., '[Mn] [D], [Y]')"/>
</xsl:template>

<xsl:template match="product/*" priority="1.5">
  <xsl:value-of select="."/>
</xsl:template>

The xsl:next-match instruction is described in 6.8 Overriding Template Rules.

Example: Re-ordering Elements in the Result Tree

Multiple xsl:apply-templates elements can be used within a single template to do simple reordering. The following example creates two HTML tables. The first table is filled with domestic sales while the second table is filled with foreign sales.

<xsl:template match="product">
  <table>
    <xsl:apply-templates select="sales/domestic"/>
  </table>
  <table>
    <xsl:apply-templates select="sales/foreign"/>
  </table>
</xsl:template>

Example: Processing Recursive Structures

It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual.

For example, given a source document

<doc><div><div></div></div></doc>

the rule

<xsl:template match="doc">
  <xsl:apply-templates select=".//div"/>
</xsl:template>

will process both the outer div and inner div elements.

This means that if the template rule for the div element processes its own children, then these grandchildren will be processed more than once, which is probably not what is required. The solution is to process one level at a time in a recursive descent, by using select="div" in place of select=".//div"

Example: Applying Templates to Atomic Values

This example reads a non-XML text file and processes it line-by-line, applying different template rules based on the content of each line:

<xsl:template name="main">
  <xsl:apply-templates select="unparsed-text-lines('input.txt')"/>
</xsl:template>

<xsl:template match="~xs:string[starts-with(., '==')]">
  <h2><xsl:value-of select="replace(., '==', '')"/></h2>
</xsl:template>

<xsl:template match="~xs:string[starts-with(., '::')]">
  <p class="indent"><xsl:value-of select="replace(., '::', '')"/></p>
</xsl:template>

<xsl:template match="~xs:string">
  <p class="body"><xsl:value-of select="."/></p>
</xsl:template>

Note:

The xsl:apply-templates instruction is most commonly used to process nodes that are descendants of the context node. Such use of xsl:apply-templates cannot result in non-terminating processing loops. However, when xsl:apply-templates is used to process elements that are not descendants of the context node, the possibility arises of non-terminating loops. For example,

<xsl:template match="foo">
  <xsl:apply-templates select="."/>
</xsl:template>

Implementations may be able to detect such loops in some cases, but the possibility exists that a stylesheet may enter a non-terminating loop that an implementation is unable to detect. This may present a denial of service security risk.

6.4 Conflict Resolution for Template Rules

It is possible for a selected item to match more than one template rule with a given mode M. When this happens, only one template rule is evaluated for the item. The template rule to be used is determined as follows:

First, only the matching template rule or rules with the highest import precedence are considered. Other matching template rules with lower precedence are eliminated from consideration.
Next, of the remaining matching rules, only those with the highest priority are considered. Other matching template rules with lower priority are eliminated from consideration.

[Definition: The priority of a template rule is specified by the priority attribute on the xsl:template declaration. If no priority is specified explicitly for a template rule, its default priority is used, as defined in 6.5 Default Priority for Template Rules.]

[ERR XTSE0530] The value of the priority attribute must conform to the rules for the xs:decimal type defined in [XML Schema Part 2]. Negative values are permitted.
If this leaves more than one matching template rule, then:
1. If the mode M has an xsl:mode declaration, and the attribute value on-multiple-match="fail" is specified in the mode declaration, a dynamic error is signalled. The error is treated as occurring in the xsl:apply-templates instruction, and can be recovered by wrapping that instruction in an xsl:try instruction.
  
  [ERR XTRE0540] It is a non-recoverable dynamic error if the conflict resolution algorithm for template rules leaves more than one matching template rule when the declaration of the relevant mode has in on-multiple-match attribute with the value fail.
2. Otherwise, of the matching template rules that remain, the one that occurs last in declaration order is used.
Note:

This was a recoverable error in XSLT 2.0, meaning that it was implementation-defined whether the error was signaled, or whether the ambiguity was resolved by taking the last matching rule in declaration order. The choice of error code reflects this legacy. In XSLT 2.1 this situation is not an error unless the attribute value on-multiple-match="fail" is specified in the mode declaration. It is also possible to request warnings when this condition arises, by means of the attribute warnings-on-multiple-match="yes".

Issue 8 (define-warning-codes):

Should we define warning codes in the same way as we define error codes?

6.5 Default Priority for Template Rules

[Definition: If no priority attribute is specified on an xsl:template element, a default priority is computed, based on the syntax of the pattern supplied in the match attribute.] The rules are as follows.

If the top-level pattern consists of multiple alternatives separated by | , then the template rule is treated equivalently to a set of template rules, one for each alternative. However, it is not an error if an item matches more than one of the alternatives.
If the top-level pattern is a PatternTerm containing two or more BasicPatterns separated by intersect or except operators, then the priority of the pattern is that of the first BasicPattern.
If the pattern (in its entirety) is a TypePattern with an empty PredicateList^XP21, then:
1. If the ItemType^XP21 is item(), the priority is −2 (minus two).
2. If the ItemType^XP21 is node(), function(), or xs:anyAtomicType, the priority is −1 (minus one).
3. If the ItemType^XP21 is any other atomic type, the priority is the priority associated with its base type plus 1. This means for example that the priority of ~xs:decimal is 0 (zero), and the priority of ~xs:integer is +1 (plus one).
4. If the ItemType^XP21 is any other NodeTest^XP21, the priority is the same as when that NodeTest appears as a pattern in its own right (see below). For example, the priority of ~element() is −0.5 (minus 0.5), while that of ~element(E) is 0 (zero).
5. If the ItemType^XP21 is a TypedFunctionTest^XP21, the priority is 0 (zero).
If the pattern (in its entirety) is a TypePattern with a non-empty PredicateList^XP21, then the priority is that of the ItemType^XP21 in the absence of the PredicateList^XP21, as given above, plus 0.5. So, for example, the priority of the pattern ~xs:integer[. gt 0] is +1.5.
If the pattern is a PathPattern taking the form /, then the priority is −0.5 (minus 0.5).
If the pattern is a PathPattern taking the form of a QName optionally preceded by a PatternAxis or has the form processing-instruction( StringLiteral^XP21 ) or processing-instruction( NCName^Names ) optionally preceded by a PatternAxis, then the priority is 0 (zero).

If the pattern is a PathPattern taking the form of an ElementTest^XP21 or AttributeTest^XP21, optionally preceded by a PatternAxis, then the priority is as shown in the table below. In this table, the symbols E, A, and T represent an arbitrary element name, attribute name, and type name respectively, while the symbol * represents itself. The presence or absence of the symbol ? following a type name does not affect the priority.

Format	Priority	Notes
`element()`	−0.5	(equivalent to `*`)
`element(*)`	−0.5	(equivalent to `*`)
`attribute()`	−0.5	(equivalent to `@*`)
`attribute(*)`	−0.5	(equivalent to `@*`)
`element(E)`	0	(equivalent to E)
`element(*,T)`	0	(matches by type only)
`attribute(A)`	0	(equivalent to `@A`)
`attribute(*,T)`	0	(matches by type only)
`element(E,T)`	0.25	(matches by name and type)
`schema-element(E)`	0.25	(matches by substitution group and type)
`attribute(A,T)`	0.25	(matches by name and type)
`schema-attribute(A)`	0.25	(matches by name and type)

If the pattern is a PathPattern taking the form of a DocumentTest^XP21, then if it includes no ElementTest^XP21 or SchemaElementTest^XP21 the priority is −0.5. If it does include an ElementTest^XP21 or SchemaElementTest^XP21, then the priority is the same as the priority of that ElementTest^XP21 or SchemaElementTest^XP21, computed according to the table above.
If the pattern is a PathPattern taking the form of an NCName^Names:* or *:NCName^Names, optionally preceded by a PatternAxis, then the priority is −0.25.
If the pattern is a PathPattern taking the form of any other NodeTest^XP21, optionally preceded by a PatternAxis, then the priority is −0.5.
In all other cases, the priority is +0.5.

Note:

In many cases this means that highly selective patterns have higher priority than less selective patterns. The most common kind of pattern (a pattern that tests for a node of a particular kind, with a particular expanded-QName or a particular type) has priority 0. The next less specific kind of pattern (a pattern that tests for a node of a particular kind and an expanded-QName with a particular namespace URI) has priority −0.25. Patterns less specific than this (patterns that just test for nodes of a given kind) have priority −0.5. Patterns that specify both the name and the required type have a priority of +0.25, putting them above patterns that only specify the name or the type. Patterns more specific than this, for example patterns that include predicates or that specify the ancestry of the required node, have priority 0.5.

In the case of a TypePattern, the default priority reflects the position of the type in the type hierarchy.

However, it is not invariably true that a more selective pattern has higher priority than a less selective pattern. For example, the priority of the pattern node()[self::*] is higher than that of the pattern salary. Similarly, the patterns attribute(*, xs:decimal) and attribute(*, xs:short) have the same priority, despite the fact that the latter pattern matches a subset of the nodes matched by the former. Therefore, to achieve clarity in a stylesheet it is good practice to allocate explicit priorities.

6.6 Modes

[Definition: Modes allow a node in a source tree to be processed multiple times, each time producing a different result. They also allow different sets of template rules to be active when processing different trees, for example when processing documents loaded using the document function (see 19.1.1 The document function) or when processing temporary trees.]

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

6.6.1 Declaring Modes

[Definition: There is always an unnamed mode available. The unnamed mode is the default mode used when no mode attribute is specified on an xsl:apply-templates instruction or xsl:template declaration, unless a different default mode has been specified using the default-mode attribute of the containing xsl:stylesheet element.]

Every mode other than the unnamed mode is identified by a QName.

A stylesheet may contain multiple xsl:mode declarations and may include or import stylesheet modules that also contain xsl:mode declarations. The name of an xsl:mode declaration is the value of its name attribute, if any.

[Definition: All the xsl:mode declarations in a stylesheet that share the same name are grouped into a named mode definition; those that have no name are grouped into a single unnamed mode definition.]

If a stylesheet does not contain a declaration of the unnamed mode, a declaration is implied equivalent to an xsl:mode element with the single attribute initial="yes". Similarly, if there is a mode that is named in an xsl:template or xsl:apply-templates element, or in the default-mode attribute of an xsl:stylesheet element, and the stylesheet does not contain a declaration of that mode, then a declaration is implied comprising an xsl:mode element with a name attribute plus the attribute initial="yes".

The contained xsl:context-item element, if present, is used to declare requirements for the initial context item when this mode is used as the initial mode. Therefore, there must be no xsl:context-item child if initial="no" is specified.

[ERR XTSE0542] It is a static error if an xsl:mode declaration specifying initial="no" contains an xsl:context-item element.

The attributes of the xsl:mode declaration establish values for a number of properties of a mode. The allowed values and meanings of the attributes are given in the following table.

Editorial note
Need to make the formatting of tables more consistent. Also consider whether a tabular style could be more generally used for describing the attributes of particular elements (and consider custom markup for generating the table).

Attribute	Values	Meaning
name	A lexical QName	Specifies the name of the mode. If omitted, this `xsl:mode` declaration provides properties of the unnamed mode
streamable	`yes` or `no` (default `no`)	Determines whether template rules in this mode are to be capable of being processed using streaming. If the value `yes` is specified, then the body of any template rule that uses this mode must conform to the rules for streamable templates given in 18.2 Streamable Templates.
initial	`yes` or `no` (default `yes`)	Determines whether this mode can be used as the initial mode when the transformation is invoked. If the value `yes` is specified, or if the attribute is omitted, then the mode is eligible to be used as the initial mode; if the value `no` is specified then processing in the mode can only be achieved by means of an `xsl:apply-templates` instruction within the stylesheet that names this mode.
on-no-match	One of `stringify`, `discard`, `copy`, or `fail` (default `stringify`)	Determines selection of the built-in template rules that are used to process a node when an `xsl:apply-templates` instruction selects a node that does not match any user-written template rule in the stylesheet. For details, see 6.7 Built-in Template Rules.
on-multiple-match	One of `fail` or `use-last` (default `use-last`)	Defines the action to be taken when `xsl:apply-templates` is used in this mode and more than one user-written template rule is available to process the node, having the same import precedence and priority. The value `fail` indicates that it is a non-recoverable dynamic error if more than one template rule matches the node. The value `use-last` indicates that the situation is not to be treated as an error (the last template in declaration order is the one that is used).
warning-on-no-match	One of `yes` or `no`. The default is implementation-defined	Requests the processor to output (or not to output) a warning message in the case where an `xsl:apply-templates` instruction selects a node that matches no template rule. The form and destination of such warnings is implementation-defined. The processor may ignore this attribute, for example if the environment provides no suitable means of communicating with the user.
warning-on-multiple-match	One of `yes` or `no`. The default is implementation-defined	Requests the processor to output a warning message in the case where an `xsl:apply-templates` instruction selects a node that matches multiple template rules having the same import precedence and priority. The form and destination of such warnings is implementation-defined. The processor may ignore this attribute, for example if the environment provides no suitable means of communicating with the user.

[Definition: A streamable mode is a mode that is declared in an xsl:mode declaration with the attribute streamable="yes".]

For any named mode, the effective value of each attribute is taken from an xsl:mode declaration that has a matching name in its name attribute, and that specifies an explicit value for the required attribute. If there is more than one such declaration, the one with highest import precedence is used.

For the unnamed mode, the effective value of each attribute is taken from an xsl:mode declaration that has no name attribute, and that specifies an explicit value for the required attribute. If there is no such declaration, the default value of the attribute is used. If there is more than one such declaration, the one with highest import precedence is used.

The above rules apply both to the attributes (other than name) of the xsl:mode element itself, and to the attributes of the contained xsl:context-item element if present.

[ERR XTSE0545] It is a static error if a named or unnamed mode contains two conflicting values for the same attribute in different xsl:mode declarations having the same import precedence, unless there is another definition of the same attribute with higher import precedence. The attributes in question are the attributes other than name on the xsl:mode element, and the as attribute on the contained xsl:context-item element if present.

If the initial context item supplied to a stylesheet is a streamed document node, then it is not permitted for the values of global variables to be dependent on the context item in a way that requires reading of the input stream. This constraint is enforced by the following static rule:

[ERR XTSE0548] It is a static error if there is both (a) a mode definition in the stylesheet that has the effective attribute values streamable="yes" and initial="yes", and (b) a global variable in the stylesheet whose initializing expression is not motionless with respect to its context item, as defined in 18.4 Streamability Analysis.

6.6.2 Declaring the initial context item for a mode

Given a mode that is used as the initial mode, the xsl:context-item element may be used to constrain the type of the initial context item that is supplied by the calling application.

<xsl:context-item as? = ItemType />

If the as attribute is present then its value must be an ItemType^XP21. When this mode (the mode defined in the containing xsl:mode declaration) is used as the initial mode, then an initial context item must be supplied externally, and its value will be converted to this type using the function conversion rules; this may result in a type errors if the conversion is not possible.

If the as attribute is omitted this is equivalent to specifying as="item()".

Note:

If the ItemType is one that can only be satisfied by a schema-validated input document, for example as="schema-element(invoice)", the processor may interpret this as a request to apply schema validation to the input. Similarly, if the KindTest indicates that an element node is required, the processor may interpret this as a request to supply the document element rather than the document node of a supplied input document.

If there is no xsl:context-item element for an xsl:mode that specifies initial="yes", this is equivalent to specifying <xsl:context-item as="item()"/>

A type errors is signalled if the supplied context item does not match its required type. The error codes is the same as for xsl:param [see ERR XTTE0590].

Example: Declaring the Required Context Item

The following example declares two modes, both of which have initial="yes" meaning that they can be used as entry points to the stylesheet. In the first mode, named invoice, the required context item is a schema-validated invoice element. In the second mode, named po, the required context item is a schema-validated purchase-order element. A third mode, format-address is declared with initial="no" so it cannot be used as an initial entry point; this mode might be used when processing content that is common to invoices and purchase orders.

<xsl:mode name="invoice" initial="yes" on-no-match="copy">
  <xsl:context-item as="schema-element(invoice)">
</xsl:mode>
<xsl:mode name="po" initial="yes" on-no-match="copy">
  <xsl:context-item as="schema-element(purchase-order)">
</xsl:mode>
<xsl:mode name="format-address" initial="no"/>

Issue 9 (declaring-context-item-for-initial-template):

It would also be useful to be able to declare the required type of the context item (or to say that there is none) when starting the transformation with an initial named template

6.6.3 Using Modes

A template rule is applicable to one or more modes. The modes to which it is applicable are defined by the mode attribute of the xsl:template element. If the attribute is omitted, then the template rule is applicable to the default mode specified in the default-mode attribute of the containing xsl:stylesheet element, which in turn defaults to the unnamed mode. If the mode attribute is present, then its value must be a non-empty whitespace-separated list of tokens, each of which defines a mode to which the template rule is applicable. Each token must be one of the following:

a QName, which is expanded as described in 5.1 Qualified Names to define the name of the mode
the token #default, to indicate that the template rule is applicable to the default mode for the stylesheet module
the token #unnamed, to indicate that the template rule is applicable to the unnamed mode
the token #all, to indicate that the template rule is applicable to all modes (specifically, to the unnamed mode and to every mode that is named explicitly or implicitly in an xsl:apply-templates instruction or xsl:template declaration anywhere in the stylesheet).

[ERR XTSE0550] It is a static error if the list is empty, if the same token is included more than once in the list, if the list contains an invalid token, or if the token #all appears together with any other value.

The xsl:apply-templates element also has an optional mode attribute. The value of this attribute must be one of the following:

a QName, which is expanded as described in 5.1 Qualified Names to define the name of a mode
the token #default, to indicate that the default mode for the stylesheet module is to be used
the token #unnamed, to indicate that the unnamed mode is to be used
the token #current, to indicate that the current mode is to be used

If the attribute is omitted, the default mode for the stylesheet module is used.

When searching for a template rule to process each item selected by the xsl:apply-templates instruction, only those template rules that are applicable to the selected mode are considered.

[Definition: At any point in the processing of a stylesheet, there is a current mode. When the transformation is initiated, the current mode is the initial mode, as described in 2.3 Initiating a Transformation. Whenever an xsl:apply-templates instruction is evaluated, the current mode becomes the mode selected by this instruction.] When a stylesheet function is called, the current mode is set to the unnamed mode. While evaluating global variables and parameters, and the sequence constructor contained in xsl:key or xsl:sort, the current mode is set to the unnamed mode. No other instruction changes the current mode. The current mode while evaluating an attribute set is the same as the current mode of the caller. On completion of the xsl:apply-templates instruction, or on return from a stylesheet function call, the current mode reverts to its previous value. The current mode is used when an xsl:apply-templates instruction uses the syntax mode="#current"; it is also used by the xsl:apply-imports and xsl:next-match instructions (see 6.8 Overriding Template Rules).

6.7 Built-in Template Rules

When a node is selected by xsl:apply-templates and there is no user-specified template rule in the stylesheet that can be used to process that node, then a built-in template rule is evaluated instead.

The built-in template rules have lower import precedence than all other template rules. Thus, the stylesheet author can override a built-in template rule by including an explicit template rule.

There are four sets of built-in template rules available. The set that is chosen is a property of the mode selected by the xsl:apply-templates instruction. This property is set using the on-no-match attribute of the xsl:mode declaration, which takes one of the four values stringify, copy, discard, or fail, the default being stringify. The effect of these four sets of built-in template rules is explained in the following subsections.

6.7.1 Built-in Templates: stringify

The general effect of choosing on-no-match="stringify" for a mode is to retain the textual content of the source document while losing the markup. When an element is encountered for which there is no explicit template rule, the processing continues with the children of that element. Text nodes are copied to the output.

The built-in rule for document nodes and element nodes is equivalent to calling xsl:apply-templates with no select attribute, and with the mode attribute set to #current. If the built-in rule was invoked with parameters, those parameters are passed on in the implicit xsl:apply-templates instruction.

The built-in template rule for text and attribute nodes and atomic values returns a text node containing the string value of the context node. It is effectively:

<xsl:template match="text()|@*|xs:anyAtomicType" mode="M">
  <xsl:value-of select="string(.)"/>
</xsl:template>

Note:

This text node may have a string value that is zero-length.

The built-in template rule for processing instructions, comments, namespace nodes, and function items does nothing (it returns the empty sequence).

<xsl:template 
   match="processing-instruction()|comment()|namespace-node()|function()" 
   mode="M"/>

The built-in template rule for namespace nodes is also to do nothing. There is no pattern that can match a namespace node, so the built-in template rule is always used when xsl:apply-templates selects a namespace node.

Example: Using a Built-In Template Rule

Suppose the stylesheet contains the following instruction:

<xsl:apply-templates select="title" mode="M">
  <xsl:with-param name="init" select="10"/>
</xsl:apply-templates>

If there is no explicit template rule that matches the title element, then the following implicit rule is used:

<xsl:template match="title" mode="M">
  <xsl:param name="init"/>
  <xsl:apply-templates mode="#current">
    <xsl:with-param name="init" select="$init"/>
  </xsl:apply-templates>
</xsl:template>

6.7.2 Built-in Templates: discard

The general effect of choosing on-no-match="discard" for a mode is to omit both the text and the markup from the result document, except in the case of items that are matched by explicit user-written template rules.

The built-in rule for document nodes and element nodes is the same as for on-no-match="stringify": that is, it is equivalent to calling xsl:apply-templates with no select attribute, and with the mode attribute set to #current. If the built-in rule was invoked with parameters, those parameters are passed on in the implicit xsl:apply-templates instruction.

The built-in template rule for all other kinds of node, and for atomic values and function items, is empty: that is, when the item is matched, the built-in template rule returns an empty sequence.

6.7.3 Built-in Templates: copy

The general effect of choosing on-no-match="copy" for a mode is that the source tree is copied unchanged to the output, except for nodes where different processing is specified using an explicit template rule.

When this default action is selected for a mode M, all items are processed using a template rule that is equivalent to the following, except that all parameters supplied in xsl:with-param elements are passed on implicitly to the called templates:

<xsl:template match="~item()" mode="M">
  <xsl:copy validation="preserve">
    <xsl:apply-templates select="@*" mode="M"/>
    <xsl:apply-templates select="node()" mode="M"/>
  </xsl:copy>
</xsl:template>

This rule is often referred to as the identity template, though it should be noted that it does not preserve node identity.

Note:

This rule differs from the "traditional" identity template rule by using two xsl:apply-templates instructions, one to process the attributes and one to process the children. The only observable difference is that with two separate instructions, the value of position() in the called templates forms one sequence starting at 1 for the attributes, and a new sequence starting at 1 for the children.

Example: Modified Identity Transformation

The following stylesheet transforms an input document by deleting all elements named note, together with their attributes and descendants:

<xsl:stylesheet version="2.1"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
                                  
<xsl:mode on-no-match="copy" streamable="yes"/>

<xsl:template match="note">
  <!-- no action -->
</xsl:template>

</xsl:stylesheet>

6.7.4 Built-in Templates: fail

The general effect of choosing on-no-match="fail" for a mode is that every node selected in an xsl:apply-templates instruction must be matched by an explicit user-written template rules.

The built-in template rule is effectively:

<xsl:template match="~item()" mode="M">
  <xsl:message error-code="err:XTDE0555"/>
</xsl:template>

with an implementation-dependent message body.

[ERR XTDE0555] It is a non-recoverable dynamic error if xsl:apply-templates, xsl:apply-imports or xsl:next-match is used to process a node using a mode whose declaration specifies on-no-match="fail" when there is no template rule in the stylesheet whose match pattern matches that node.

6.8 Overriding Template Rules

 <xsl:apply-imports>  </xsl:apply-imports>

 <xsl:next-match>  </xsl:next-match>

A template rule that is being used to override another template rule (see 6.4 Conflict Resolution for Template Rules) can use the xsl:apply-imports or xsl:next-match instruction to invoke the overridden template rule. The xsl:apply-imports instruction only considers template rules in imported stylesheet modules; the xsl:next-match instruction considers all other template rules of lower import precedence and/or priority. Both instructions will invoke the built-in template rule for the context item (see 6.7 Built-in Template Rules) if no other template rule is found.

[Definition: At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen as a result of evaluating xsl:apply-templates, xsl:apply-imports, or xsl:next-match, the template rule becomes the current template rule for the evaluation of the rule's sequence constructor. When an xsl:for-each, xsl:for-each-group, xsl:analyze-string, xsl:iterate, xsl:stream, xsl:merge, or xsl:evaluate instruction is evaluated, or when evaluating a sequence constructor contained in an xsl:sort or xsl:key element, or when a stylesheet function is called (see 10.3 Stylesheet Functions), the current template rule becomes null for the evaluation of that instruction or function.]

The current template rule is not affected by invoking named templates (see 10.1 Named Templates) or named attribute sets (see 10.2 Named Attribute Sets). While evaluating a global variable or the default value of a stylesheet parameter (see 9.5 Global Variables and Parameters) the current template rule is null.

Note:

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

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

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

Note:

This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.
The xsl:next-match instruction considers as candidates all those template rules that come after the current template rule in the ordering of template rules implied by the conflict resolution rules given in 6.4 Conflict Resolution for Template Rules. That is, it considers all template rules with lower import precedence than the current template rule, plus the template rules that are at the same import precedence that have lower priority than the current template rule, plus the template rules with the same import precedence and priority that occur before the current template rule in declaration order.

Note:

As explained in 6.4 Conflict Resolution for Template Rules, a template rule whose match pattern contains multiple alternatives separated by | is treated equivalently to a set of template rules, one for each alternative. This means that where the same item matches more than one alternative, and the alternatives have different priority, it is possible for an xsl:next-match instruction to cause the current template rule to be invoked recursively. This situation does not occur when the alternatives have the same priority.

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

An xsl:apply-imports or xsl:next-match instruction may use xsl:with-param child elements to pass parameters to the chosen template rule (see 9.8 Setting Parameter Values). It also passes on any tunnel parameters as described in 10.1.2 Tunnel Parameters.

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

Example: Using xsl:apply-imports

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

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

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

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

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

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

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

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

6.9 Passing Parameters to Template Rules

A template rule may have parameters. The parameters are declared in the body of the template using xsl:param elements, as described in 9.2 Parameters.

Values for these parameters may be supplied in the calling xsl:apply-templates, xsl:apply-imports, or xsl:next-match instruction by means of xsl:with-param elements appearing as children of the calling instruction. The expanded QName represented by the name attribute of the xsl:with-param element must match the expanded QName represented by the name attribute of the corresponding xsl:param element.

[ERR XTDE0700] It is a non-recoverable dynamic error if a template that is invoked using xsl:apply-templates, xsl:apply-imports, or xsl:next-match declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction. The same error is reported in the case of a tunnel parameter whether invoked using one of these three instructions or by xsl:call-template, as explained in 10.1.2 Tunnel Parameters.

It is not an error for these instructions to supply a parameter that does not match any parameter declared in the template rule that is invoked; unneeded parameter values are simply ignored.

A parameter may be declared as a tunnel parameter by specifying tunnel="yes" in the xsl:param declaration; in this case the caller must supply the value as a tunnel parameter by specifying tunnel="yes" in the corresponding xsl:with-param element. Tunnel parameters differ from ordinary template parameters in that they are passed transparently through multiple template invocations. They are fully described in 10.1.2 Tunnel Parameters.

7 Repetition

XSLT offers two constructs for processing each item of a sequence: xsl:for-each and xsl:iterate.

The main difference between the two constructs is that with xsl:for-each, the processing applied to each item in the sequence is independent of the processing applied to any other item; this means that the items may be processed in any order or in parallel, though the order of the output sequence is well defined and corresponds to the order of the input (sorted if so requested). By contrast, with xsl:iterate, the processing is explicitly sequential: while one item is being processed, values may be computed which are then available for use while the next item is being processed. This makes xsl:iterate suitable for tasks such as creating a running total over a sequence of financial transactions.

A further difference is that xsl:for-each permits sorting of the input sequence, while xsl:iterate does not.

7.1 The `xsl:for-each` instruction

 <xsl:for-each select = expression >  </xsl:for-each>

The xsl:for-each instruction processes each item in a sequence of items, evaluating the sequence constructor within the xsl:for-each instruction once for each item in that sequence.

The select attribute is required; it contains an expression which is evaluated to produce a sequence, called the input sequence. If there is an xsl:sort element present (see 13 Sorting) the input sequence is sorted to produce a sorted sequence. Otherwise, the sorted sequence is the same as the input sequence.

The xsl:for-each instruction contains a sequence constructor. The sequence constructor is evaluated once for each item in the sorted sequence, with the focus set as follows:

The context item is the item being processed. If this is a node, it will also be the context node. If it is not a node, there will be no context node: that is, any attempt to reference the context node will result in a non-recoverable dynamic error.
The context position is the position of this item in the sorted sequence.
The context size is the size of the sorted sequence (which is the same as the size of the input sequence).

For each item in the input sequence, evaluating the sequence constructor produces a sequence of items (see 5.7 Sequence Constructors). These output sequences are concatenated; if item Q follows item P in the sorted sequence, then the result of evaluating the sequence constructor with Q as the context item is concatenated after the result of evaluating the sequence constructor with P as the context item. The result of the xsl:for-each instruction is the concatenated sequence of items.

Example: Using xsl:for-each

For example, given an XML document with this structure

<customers>
  <customer>
    <name>...</name>
    <order>...</order>
    <order>...</order>
  </customer>
  <customer>
    <name>...</name>
    <order>...</order>
    <order>...</order>
  </customer>
</customers>

the following would create an HTML document containing a table with a row for each customer element

<xsl:template match="/">
  <html>
    <head>
      <title>Customers</title>
    </head>
    <body>
      <table>
        <tbody>
          <xsl:for-each select="customers/customer">
            <tr>
              <th>
                <xsl:apply-templates select="name"/>
              </th>
              <xsl:for-each select="order">
                <td>
                  <xsl:apply-templates/>
                </td>
              </xsl:for-each>
            </tr>
          </xsl:for-each>
        </tbody>
      </table>
    </body>
  </html>
</xsl:template>

7.2 The `xsl:iterate` instruction

 <xsl:iterate select = expression >  </xsl:iterate>

 <xsl:next-iteration>  </xsl:next-iteration>

 <xsl:break>  </xsl:break>

<xsl:on-completion>  </xsl:on-completion>

The select attribute is required; it contains an expression which is evaluated to produce a sequence, called the input sequence.

The sequence constructor contained in the xsl:iterate instruction is evaluated once for each item in the input sequence, in order, or until the loop exits by evaluating an xsl:break instruction, whichever is earlier. Within the sequence constructor that forms the body of the xsl:iterate instruction, the context item is set to each item from the value of the select expression in turn; the context position reflects the position of this item in the input sequence, and the context size is the number of items in the input sequence (which may be greater than the number of iterations, if the loop exits prematurely using xsl:break).

Note:

If xsl:iterate is used in conjunction with xsl:stream to achieve streaming, calls on the function last^FO will be disallowed.

The effect of xsl:next-iteration is to cause the iteration to continue by processing the next item in the input sequence, potentially with different values for the iteration parameters. The effect of xsl:break is to cause the iteration to finish, whether or not all the items in the input sequence have been processed. In both cases the affected iteration is the one controlled by the innermost ancestor xsl:iterate element.

The instructions xsl:next-iteration and xsl:break are allowed only as descendants of an xsl:iterate instruction, and only in a tail position within the sequence constructor forming the body of the xsl:iterate instruction.

[Definition: An instruction J is in a tail position within a sequence constructor SC if it satisfies one of the following conditions:]

J is the last instruction in SC, ignoring any xsl:fallback instructions.
J is in a tail position within the sequence constructor that forms the body of an xsl:if instruction that is itself in a tail position within SC.
J is in a tail position within the sequence constructor that forms the body of an xsl:when or xsl:otherwise branch of an xsl:choose instruction that is itself in a tail position within SC.
J is in a tail position within the sequence constructor that forms the body of an xsl:try instruction that is itself in a tail position within SC (that is, it is immediately followed by an xsl:catch element, ignoring any xsl:fallback elements).
J is in a tail position within the sequence constructor that forms the body of an xsl:catch element within an xsl:try instruction that is itself in a tail position within SC.

[ERR XTSE2110] It is a static error if an xsl:break or xsl:next-iteration element appears other than in a tail position within the sequence constructor forming the body of an xsl:iterate instruction.

[ERR XTSE2120] It is a static error if the name attribute of an xsl:with-param child of an xsl:next-iteration element does not match the name attribute of an xsl:param child of the innermost containing xsl:iterate instruction.

Parameter names in xsl:with-param must be unique: [see ERR XTSE0670].

The result of the xsl:iterate instruction is the concatenation of the sequences that result from the repeated evaluation of the contained sequence constructor, followed by the sequence that results from evaluating the sequence constructor contained within the xsl:break or xsl:on-completion element if any.

Any xsl:param element that appears as a child of xsl:iterate declares a parameter whose value may vary from one iteration to the next. The initial value of the parameter is the value obtained according to the rules given in 9.3 Values of Variables and Parameters. The dynamic context for evaluating the initial value of an xsl:param element is the same as the dynamic context for evaluating the select expression of the xsl:iterate instruction (the context item is thus not the first item in the input sequence).

On the first iteration a parameter always takes its initial value (which may depend on variables or other aspects of the dynamic context). Subsequently:

If an xsl:next-iteration instruction is evaluated, then parameter values for processing the next item in the input sequence can be set in the xsl:with-param children of that instruction; in the absence of an xsl:with-param element that names a particular parameter, that parameter will retain its value from the previous iteration.
If an xsl:break instruction is evaluated, no further items in the input sequence are processed.
If neither an xsl:next-iteration nor an xsl:break instruction is evaluated, then the next item in the input sequence is processed using parameter values that are unchanged from the previous iteration.

The xsl:next-iteration instruction contributes nothing to the result sequence (technically, it returns an empty sequence). The instruction supplies parameter values for the next iteration, which are evaluated according to the rules given in 9.8 Setting Parameter Values; if there are no further items in the input sequence then it supplies parameter values for use while evaluating the body of the xsl:on-completion element if any.

The xsl:break instruction indicates that the iteration should terminate without processing any remaining items from the input sequence. The contained sequence constructor is evaluated using the same context item, position, and size as the xsl:break instruction itself, and the result is appended to the result of the xsl:iterate instruction as a whole.

If neither an xsl:next-iteration nor an xsl:break instruction is evaluated, the next item in the input sequence is processed with parameter values unchanged from the previous iteration; if there are no further items in the input sequence, the iteration terminates.

The optional xsl:on-completion element (which is not technically an instruction and is not technically part of the sequence constructor) is evaluated when the input sequence is exhausted. It is not evaluated if the evaluation is terminated using xsl:break. During evaluation of this sequence constructor the context item, position, and size are undefined (that is, any reference to these values is an error). However, the values of the parameters to xsl:iterate are available, and take the values supplied by the xsl:next-iteration instruction evaluated while processing the last item in the sequence.

If the input sequence is empty, then the result of the xsl:iterate instruction is the result of evaluating the sequence constructor forming the body of the xsl:on-completion element, using the initial values of the xsl:param elements. If there is no xsl:on-completion element, the result is an empty sequence.

Note:

Conceptually, xsl:iterate behaves like a tail-recursive function. The xsl:next-iteration instruction then represents the recursive call, supplying the tail of the input sequence as an implicit parameter. There are two main reasons for providing the xsl:iterate instruction. One is that many XSLT users find writing recursive functions to be a difficult skill, and this construct promises to be easier to learn. The other is that recursive function calls are difficult for an optimizer to analyze. Because xsl:iterate is more constrained than a general-purpose head-tail recursive function, it should be more amenable to optimization. In particular, when the instruction is used in conjunction with xsl:stream, it is designed to make it easy for the implementation to use streaming techniques, processing the nodes in an input document sequentially as they are read, without building the entire document tree in memory.

Issue 10 (iterate-empty):

The Working Group is considering whether more control is needed over how an empty sequence is processed. Currently, whether a sequence is processed using xsl:for-each, xsl:apply-templates, or xsl:iterate, there is no easy way to define special code for handling an empty sequence in a way that satisfies the rules for streamability, because one downward selection is needed to test for emptiness, another to perform iteration when non-empty. One possible solution is the proposed has-children function.

The examples below use xsl:iterate in conjunction with the xsl:stream instruction. This is not the only way of using xsl:iterate, but it illustrates the way in which the two features can be combined to achieve streaming of a large input document.

Example: Using xsl:iterate to compute cumulative totals

Suppose that the input XML document has this structure

<transactions>
  <transaction date="2008-09-01" value="12.00"/>
  <transaction date="2008-09-01" value="8.00"/>
  <transaction date="2008-09-02" value="-2.00"/>
  <transaction date="2008-09-02" value="5.00"/>
</transactions>

and that the requirement is to transform this to:

<account>
  <balance date="2008-09-01" value="12.00"/>
  <balance date="2008-09-01" value="20.00"/>
  <balance date="2008-09-02" value="18.00"/>
  <balance date="2008-09-02" value="23.00"/>
</account>

This can be achieved using the following code, which is designed to process the transaction file using streaming:

<account>
  <xsl:stream href="transactions.xml">
    <xsl:iterate select="transactions/transaction">
      <xsl:param name="balance" select="0.00" as="xs:decimal"/>
      <xsl:variable name="newBalance" 
                    select="$balance + xs:decimal(@value)"/>
      <balance date="{@date}" value="{$newBalance}"/>
      <xsl:next-iteration>
        <xsl:with-param name="balance" select="$newBalance"/>
      </xsl:next-iteration>
    </xsl:iterate>
  </xsl:stream>
</account>

The following example modifies this by only outputting the information for the first day's transactions:

<account>
  <xsl:stream href="'transactions.xml">
    <xsl:iterate select="transactions/transaction">
      <xsl:param name="balance" select="0.00" as="xs:decimal"/>
      <xsl:param name="prevDate" select="()" as="xs:date?"/>
      <xsl:variable name="newBalance" 
                    select="$balance + xs:decimal(@value)"/>
      <xsl:variable name="thisDate" 
                    select="xs:date(@date)"/>
      <xsl:choose>
        <xsl:when test="empty($prevDate) or $thisDate eq $prevDate">
          <balance date="{$thisDate}" 
                   value="{format-number($newBalance, '0.00')}"/>
          <xsl:next-iteration>
            <xsl:with-param name="balance" select="$newBalance"/>
            <xsl:with-param name="prevDate" select="$thisDate"/>
          </xsl:next-iteration>
        </xsl:when>
        <xsl:otherwise>
          <xsl:break/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:iterate>
  </xsl:stream>
</account>

The following code outputs the balance only at the end of each day, together with the final balance:

<account>
  <xsl:stream href="transactions.xml">
    <xsl:iterate select="transactions/transaction">
      <xsl:param name="balance" select="0.00" as="xs:decimal"/>
      <xsl:param name="prevDate" select="()" as="xs:date?"/>
      <xsl:variable name="newBalance" 
                    select="$balance + xs:decimal(@value)"/>
      <xsl:variable name="thisDate" select="xs:date(@date)"/>
      <xsl:if test="exists($prevDate) and $thisDate ne $prevDate">
        <balance date="{$prevDate}" 
                 value="{format-number($balance, '0.00')}"/>
      </xsl:if>
      <xsl:next-iteration>
        <xsl:with-param name="balance" select="$newBalance"/>
        <xsl:with-param name="prevDate" select="$thisDate"/>
      </xsl:next-iteration>
      <xsl:on-completion>
        <balance date="{$prevDate}" 
                 value="{format-number($balance, '0.00')}"/>
      </xsl:on-completion>
    </xsl:iterate>
  </xsl:stream>
</account>

If the sequence of transactions is empty, this code outputs a single element: <balance date="" value="0.00"/>.

Example: Collecting multiple values in a single pass

Problem: Given a sequence of employee elements, find the employees having the highest and lowest salary, while processing each employee only once.

Solution:

<xsl:stream href="employees.xml">
  <xsl:iterate select="employees/employee">
    <xsl:param name="highest" as="element(employee)*"/>
    <xsl:param name="lowest" as="element(employee)*"/>
    <xsl:variable name="is-new-highest" as=xs:boolean"
                  select="empty($highest[@salary ge current()/@salary])"/>
    <xsl:variable name="is-equal-highest" as=xs:boolean" 
                  select="exists($highest[@salary eq current()/@salary])"/> 
    <xsl:variable name="is-new-lowest" as=xs:boolean" 
                  select="empty($lowest[@salary le current()/@salary])"/>
    <xsl:variable name="is-equal-lowest" as=xs:boolean" 
                  select="exists($lowest[@salary eq current()/@salary])"/> 
    <xsl:variable name="new-highest-set" as=element(employee)*"
                  select="if ($is-new-highest) then .
                          else if ($is-equal-highest) then ($highest, .)
                          else $highest"/>
    <xsl:variable name="new-lowest-set" as=element(employee)*"
                  select="if ($is-new-lowest) then .
                          else if ($is-equal-lowest) then ($lowest, .)
                          else $lowest"/>
    <xsl:next-iteration>
      <xsl:with-param name="highest" select="$new-highest-set"/>
      <xsl:with-param name="lowest" select="$new-lowest-set"/>
    </xsl:next-iteration>
    <xsl:on-completion>
      <highest-paid-employees>
        <xsl:value-of select="$highest/name"/>
      </highest-paid-employees>
      <lowest-paid-employees>
        <xsl:value-of select="$lowest/name"/>
      </lowest-paid-employees>  
    </xsl:on-completion>
   </xsl:iterate>
 </xsl:stream>

If the input sequence is empty, this code outputs an empty highest-paid-employees element and an empty lowest-paid-employees element.

Example: Processing the last item in a sequence specially

When streaming, some limited look-ahead is needed to determine whether the item being processed is the last in a sequence. The last^FO function cannot be used in guaranteed-streamable code. The xsl:iterate instruction provides a solution to this problem.

Problem: render the last paragraph in a section in some special way, for example by using bold face. (The actual rendition is achieved by processing the paragraph with mode last-para.)

The solution uses xsl:iterate to maintain a one-element lookahead by explicit coding:

<xsl:template match="section" mode="streaming">
   <xsl:iterate select="para">
     <xsl:param name="prev" select="()" as="element(para)?"/>
     <xsl:if test="$prev">
       <xsl:apply-templates select="$prev"/>
     </xsl:if>
     <xsl:next-iteration>
       <xsl:param name="prev" select="."/>
     </xsl:next-iteration>
     <xsl:on-completion>
       <xsl:apply-templates select="$prev" mode="last-para"/>      
     </xsl:on-completion>
   </xsl:iterate>
 </xsl:template>

8 Conditional Processing

There are two instructions in XSLT that support conditional processing: xsl:if and xsl:choose. The xsl:if instruction provides simple if-then conditionality; the xsl:choose instruction supports selection of one choice when there are several possibilities.

XSLT 2.1 also supports xsl:try and xsl:catch which define conditional processing to handle dynamic errors.

8.1 Conditional Processing with `xsl:if`

 <xsl:if test = expression >  </xsl:if>

The xsl:if element has a mandatory test attribute, which specifies an expression. The content is a sequence constructor.

The result of the xsl:if instruction depends on the effective boolean value^XP21 of the expression in the test attribute. The rules for determining the effective boolean value of an expression are given in [XPath 2.1]: they are the same as the rules used for XPath conditional expressions.

If the effective boolean value of the expression is true, then the sequence constructor is evaluated (see 5.7 Sequence Constructors), and the resulting node sequence is returned as the result of the xsl:if instruction; otherwise, the sequence constructor is not evaluated, and the empty sequence is returned.

Example: Using xsl:if

In the following example, the names in a group of names are formatted as a comma separated list:

<xsl:template match="namelist/name">
  <xsl:apply-templates/>
  <xsl:if test="not(position()=last())">, </xsl:if>
</xsl:template>

The following colors every other table row yellow:

<xsl:template match="item">
  <tr>
    <xsl:if test="position() mod 2 = 0">
       <xsl:attribute name="bgcolor">yellow</xsl:attribute>
    </xsl:if>
    <xsl:apply-templates/>
  </tr>
</xsl:template>

8.2 Conditional Processing with `xsl:choose`

 <xsl:choose>  </xsl:choose>

<xsl:when test = expression >  </xsl:when>

<xsl:otherwise>  </xsl:otherwise>

The xsl:choose element selects one among a number of possible alternatives. It consists of a sequence of one or more xsl:when elements followed by an optional xsl:otherwise element. Each xsl:when element has a single attribute, test, which specifies an expression. The content of the xsl:when and xsl:otherwise elements is a sequence constructor.

When an xsl:choose element is processed, each of the xsl:when elements is tested in turn (that is, in the order that the elements appear in the stylesheet), until one of the xsl:when elements is satisfied. If none of the xsl:when elements is satisfied, then the xsl:otherwise element is considered, as described below.

An xsl:when element is satisfied if the effective boolean value^XP21 of the expression in its test attribute is true. The rules for determining the effective boolean value of an expression are given in [XPath 2.1]: they are the same as the rules used for XPath conditional expressions.

The content of the first, and only the first, xsl:when element that is satisfied is evaluated, and the resulting sequence is returned as the result of the xsl:choose instruction. If no xsl:when element is satisfied, the content of the xsl:otherwise element is evaluated, and the resulting sequence is returned as the result of the xsl:choose instruction. If no xsl:when element is satisfied, and no xsl:otherwise element is present, the result of the xsl:choose instruction is an empty sequence.

Only the sequence constructor of the selected xsl:when or xsl:otherwise instruction is evaluated. The test expressions for xsl:when instructions after the selected one are not evaluated.

Example: Using xsl:choose

The following example enumerates items in an ordered list using arabic numerals, letters, or roman numerals depending on the depth to which the ordered lists are nested.

<xsl:template match="orderedlist/listitem">
  <fo:list-item indent-start='2pi'>
    <fo:list-item-label>
      <xsl:variable name="level"
                    select="count(ancestor::orderedlist) mod 3"/>
      <xsl:choose>
        <xsl:when test='$level=1'>
          <xsl:number format="i"/>
        </xsl:when>
        <xsl:when test='$level=2'>
          <xsl:number format="a"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:number format="1"/>
        </xsl:otherwise>
      </xsl:choose>
      <xsl:text>. </xsl:text>
    </fo:list-item-label>
    <fo:list-item-body>
      <xsl:apply-templates/>
    </fo:list-item-body>
  </fo:list-item>
</xsl:template>

8.3 Try/Catch

The xsl:try instruction can be used to trap dynamic errors occurring within the expression it wraps; the recovery action if such errors occur is defined using a child xsl:catch element.

 <xsl:try select? = expression >  </xsl:try>

Note:

Because a sequence constructor may contain an xsl:fallback element, the effect of this content model is that an xsl:fallback instruction may appear as a child of xsl:try in any position.

<xsl:catch errors? = tokens select? = expression >  </xsl:catch>

An xsl:try instruction evaluates either the expression contained in its select attribute, or its contained sequence constructor, and returns the result of that evaluation if it succeeds without error. If a dynamic error occurs during the evaluation, the processor evaluates the first xsl:catch child element applicable to the error, and returns that result instead.

If the xsl:try element has a select attribute, then it must have no children other than xsl:catch and xsl:fallback. That is, the select attribute and the contained sequence constructor are mutually exclusive. If neither is present, the result of the xsl:try is an empty sequence (no dynamic error can occur in this case).

[ERR XTSE2130] It is a static error if the select attribute of the xsl:try element is present and the element has children other than xsl:catch and xsl:fallback elements.

Any xsl:fallback children of the xsl:try element are ignored by an XSLT 2.1 processor, but can be used to define the recovery action taken by an XSLT 1.0 or XSLT 2.0 processor operating with forwards compatible behavior.

The xsl:catch element has an optional errors attribute, which lists the error conditions that the xsl:catch element is designed to intercept. The default value is errors="*", which catches all errors. The value is a whitespace-separated list of NameTests^XP21; an xsl:catch element catches an error condition if this list includes a NameTest that matches the error code associated with that error condition.

Note:

Error codes are QNames. Those defined in this specification and in related specifications are all in the standard error namespace, and may therefore be caught using an xsl:catch element such as <xsl:catch errors="err:FODC0001 err:FODC0005"> where the namespace prefix err is bound to this namespace. Errors defined by implementors, and errors raised by an explicit call of the error^FO function or by use of the xsl:message instruction, may use error codes in other namespaces.

If more than one xsl:catch element matches an error, the error is processed using the first one that matches, in document order. If no xsl:catch matches the error, then the error is not caught (that is, evaluation of the xsl:try element fails with the dynamic error).

An xsl:catch element may have either a select attribute, or a contained sequence constructor.

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

The result of evaluating the xsl:catch element is the result of evaluating the XPath expression in its select attribute or the result of evaluating the contained sequence constructor; if neither is present, the result is an empty sequence. This result is delivered as the result of the xsl:try instruction.

If a dynamic error occurs during the evaluation of xsl:catch, it causes the containing xsl:try to fail with this error. The error is not caught by other sibling xsl:catch elements within the same xsl:try instruction, but it may be caught by an xsl:try instruction at an outer level, or by an xsl:try instruction nested within the xsl:catch.

Within the select expression, or within the sequence constructor contained by the xsl:catch element, a number of variables are implicitly declared, giving information about the error that occurred. These are lexically scoped to the xsl:catch element. These variables are all in the standard error namespace, and they are initialized as described in the following table:

Variable	Type	Value
err:code	xs:QName	The error code
err:description	xs:string	A description of the error condition
err:value	item()*	Value associated with the error. For an error raised by calling the `error`^FO function, this is the value of the third argument (if supplied). For an error raised by evaluating `xsl:message` with `terminate="yes"`, this is the document node at the root of the tree containing the XML message body.
err:module	xs:string?	The URI (or system ID) of the stylesheet module containing the instruction where the error occurred; an empty sequence if the information is not available.
err:line-number	xs:integer?	The line number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available. The value may be approximate.
err:column-number	xs:integer?	The column number within the stylesheet module of the instruction where the error occurred; an empty sequence if the information is not available. The value may be approximate.

Variables declared within the sequence constructor of the xsl:try element (and not within an xsl:catch) are not visible within the xsl:catch element.

Note:

Within an xsl:catch it is possible to re-throw the error using the function call error($err:code, $err:description, $err:value).

The following additional rules apply to the catching of errors:

All dynamic errors occurring during the evaluation of the xsl:try sequence constructor or select expression are caught (provided they match one of the xsl:catch elements).
- This includes errors occurring in functions or templates invoked in the course of this evaluation, unless already caught by a nested xsl:try.
- It also includes errors caused by calling the error^FO function or the xsl:message instruction with terminate="yes".
- It does not include errors that occur while evaluating references to variables whose declaration and initialization is outside the xsl:try.
The existence of an xsl:try instruction does not affect the right of the processor to recover, or not recover, from errors classified as recoverable dynamic errors. An xsl:catch element will be activated only if the processor chooses to signal the error rather than taking the defined recovery action.
The existence of an xsl:try instruction does not affect the obligation of the processor to signal certain errors as static errors, or its right to choose whether to signal some errors (such as type errors) statically or dynamically. Static errors are never caught.
Some fatal errors arising in the processing environment, such as running out of memory, may cause termination of the transformation despite the presence of an xsl:try instruction. This is implementation-dependent.
If the sequence constructor or select expression of the xsl:try causes execution of xsl:result-document or xsl:message instructions and fails with a dynamic error that is caught, it is implementation-dependent whether these instructions have any externally visible effect. The processor is not required to do a "rollback" of any changes made by these instructions. The same applies to any side effects caused by extension functions or extension instructions.
If the xsl:try element appears in a context where it is required to deliver a value of a specified type (for example, if it appears as the body of a stylesheet function), then any error that occurs because it delivers a value of the wrong type, or an error that occurs during conversion to the required type (for example, during atomization), is treated as occurring within the scope of the xsl:try instruction.
When an instruction J computes a value that will inevitably cause some outer-level instruction O to fail with a dynamic error, then the failure may be treated as occurring in J, in which case it will be caught by an xsl:try instruction whose scope includes J but does not include O. For example, creating an element may fail because the element is not allowed by the content model of a containing element; although the specification describes this as a failure associated with the construction of the containing element, a processor is allowed to detect the error as soon as it becomes inevitable.

Note:

The effect of this rule is that when stylesheet output is streamed to a schema validator or to a serializer, errors detected by the validation or serialization process may be treated if they occurred in the instruction that generated the offending output; however, stylesheet authors cannot rely on this. In fact, where serialization is applied to a final result tree, there is no guarantee that it will be possible to catch the error at all, since serialization is outside the scope of the transformation process proper.
The fact that the application tries to catch errors does not prevent the processor from organizing the evaluation in such a way as to prevent errors occurring. For example exists(//a[10 div . gt 5]) may still do an "early exit", rather than examining every item in the sequence just to see if it triggers a divide-by-zero error.
A failure occurring while evaluating the match pattern of a template rule, if not treated as a recoverable error, is treated as occurring during the evaluation of the calling xsl:apply-templates instruction (or xsl:apply-imports or xsl:next-match if appropriate).
Except as specified above, the optimizer must not rearrange the evaluation (at compile time or at run time) so that expressions written to be subject to to the try/catch are evaluated outside its scope, or expressions written to be external to the try/catch are evaluated within its scope. This does not prevent expressions being rearranged, but any expression that is so rearranged must carry its try/catch context with it.

Note:

If an error occurs while evaluating an instruction within xsl:try, then no instruction within the xsl:try has any effect on the result returned by the xsl:try instruction. This means that if a processor is streaming the output to a serializer, it needs to adopt a strategy such as buffering the output in memory so that nothing is written until successful completion of the xsl:try instruction, or checkpointing the output so it can be rolled back when an error occurs.

Issue 11 (try-catch-output-buffering):

The rules appear inconsistent: if the processor is obliged to buffer "immediate" output from the xsl:try element before sending it the serializer, should not the same requirement apply also to xsl:result-document (rule 5)? And if output has to be buffered, is rule 7 appropriate, allowing serialization errors to be detected "on the fly"?

8.3.1 Try/Catch Examples

Example: Catching a divide-by-zero error

The following example divides an employee's salary by the number of years they have served, catching the error if the latter is zero.

<xsl:try select="salary div length-of-service">
  <xsl:catch errors="err:FAOR0001" select="()"/>
</xsl:try>

Example: Catching an error during result-tree validation

The following example generates a result tree and performs schema validation, outputting a warning message and serializing the invalid tree if validation fails.

<xsl:result-document href="out.xml">
  <xsl:variable name="result">
    <xsl:call-template name="construct-output"/>
  </xsl:variable>
  <xsl:try>
    <xsl:copy-of select="$result" validation="strict"/>
    <xsl:catch>
      <xsl:message>Warning: validation of result document failed:
          Error code: <xsl:value-of select="$err:code"/>
          Reason: <xsl:value-of select="$err:description"/>
      </xsl:message>
      <xsl:sequence select="$result"/>
    </xsl:catch>
  </xsl:try>
</xsl:result-document>

The reason that the result tree is constructed in a variable in this example is so that the unvalidated tree is available to be used within the xsl:catch element. An alternative approach would be to repeat the logic for constructing the tree:

<xsl:try>
  <xsl:result-document href="out.xml" validation="strict">  
    <xsl:call-template name="construct-output"/>
  </xsl:result-document>
  <xsl:catch>
    <xsl:message>Warning: validation of result document failed:
          Error code: <xsl:value-of select="$err:code"/>
          Reason: <xsl:value-of select="$err:description"/>
    </xsl:message>
    <xsl:call-template name="construct-output"/>
  </xsl:catch>
  </xsl:try>

9 Variables and Parameters

[Definition: The two elements xsl:variable and xsl:param are referred to as variable-binding elements ].

[Definition: The xsl:variable element declares a variable, which may be a global variable or a local variable.]

[Definition: The xsl:param element declares a parameter, which may be a stylesheet parameter, a template parameter, a function parameter, or an xsl:iterate parameter. A parameter is a variable with the additional property that its value can be set by the caller.]

[Definition: A variable is a binding between a name and a value. The value of a variable is any sequence (of nodes, atomic values, and/or function items), as defined in [Data Model].]

9.1 Variables

  <xsl:variable name = qname select? = expression as? = sequence-type >  </xsl:variable>

The xsl:variable element has a required name attribute, which specifies the name of the variable. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

The xsl:variable element has an optional as attribute, which specifies the required type of the variable. The value of the as attribute is a SequenceType^XP21, as defined in [XPath 2.1].

[Definition: The value of the variable is computed using the expression given in the select attribute or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters. This value is referred to as the supplied value of the variable.] If the xsl:variable element has a select attribute, then the sequence constructor must be empty.

If the as attribute is specified, then the supplied value of the variable is converted to the required type, using the function conversion rules.

[ERR XTTE0570] It is a type error if the supplied value of a variable cannot be converted to the required type.

If the as attribute is omitted, the supplied value of the variable is used directly, and no conversion takes place.

9.2 Parameters

 <xsl:param name = qname select? = expression as? = sequence-type required? = "yes" | "no" tunnel? = "yes" | "no" >  </xsl:param>

The xsl:param element may be used:

as a child of xsl:stylesheet, to define a parameter to the transformation
as a child of xsl:template to define a parameter to a template, which may be supplied when the template is invoked using xsl:call-template, xsl:apply-templates, xsl:apply-imports or xsl:next-match;
as a child of xsl:function to define a parameter to a stylesheet function, which may be supplied when the function is called from an XPath expression
as a child of xsl:iterate to define a parameter that can vary from one iteration to the next.

The xsl:param element has a required name attribute, which specifies the name of the parameter. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

[ERR XTSE0580] It is a static error if the values of the name attribute of two sibling xsl:param elements represent the same expanded QName.

Note:

For rules concerning stylesheet parameters, see 9.5 Global Variables and Parameters. Local variables may shadow template parameters and function parameters: see 9.7 Scope of Variables.

The supplied value of the parameter is the value supplied by the caller. If no value was supplied by the caller, and if the parameter is not mandatory, then the supplied value is computed using the expression given in the select attribute or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters. If the xsl:param element has a select attribute, then the sequence constructor must be empty.

Note:

This specification does not dictate whether and when the default value of a parameter is evaluated. For example, if the default is specified as <xsl:param name="p"><foo/></xsl:param>, then it is not specified whether a distinct foo element node will be created on each invocation of the template, or whether the same foo element node will be used for each invocation. However, it is permissible for the default value to depend on the values of other parameters, or on the evaluation context, in which case the default must effectively be evaluated on each invocation.

The xsl:param element has an optional as attribute, which specifies the required type of the parameter. The value of the as attribute is a SequenceType^XP21, as defined in [XPath 2.1].

If the as attribute is specified, then the supplied value of the parameter is converted to the required type, using the function conversion rules.

[ERR XTTE0590] It is a type error if the conversion of the supplied value of a parameter to its required type fails.

If the as attribute is omitted, the supplied value of the parameter is used directly, and no conversion takes place.

The optional required attribute may be used to indicate that a parameter is mandatory. This attribute may be specified for stylesheet parameters and for template parameters; it must not be specified for function parameters, which are always mandatory, or for parameters to xsl:iterate, which are always initialized to a default value. A parameter is mandatory if it is a function parameter or if the required attribute is present and has the value yes. Otherwise, the parameter is optional. If the parameter is mandatory, then the xsl:param element must be empty and must not have a select attribute.

[ERR XTTE0600] If a default value is given explicitly, that is, if there is either a select attribute or a non-empty sequence constructor, then it is a type error if the default value cannot be converted to the required type, using the function conversion rules.

If an optional parameter has no select attribute and has an empty sequence constructor, and if there is no as attribute, then the default value of the parameter is a zero length string.

[ERR XTDE0610] If an optional parameter has no select attribute and has an empty sequence constructor, and if there is an as attribute, then the default value of the parameter is an empty sequence. If the empty sequence is not a valid instance of the required type defined in the as attribute, then the parameter is treated as a required parameter, which means that it is a non-recoverable dynamic error if the caller supplies no value for the parameter.

Note:

The effect of these rules is that specifying <xsl:param name="p" as="xs:date" select="2"/> is an error, but if the default value of the parameter is never used, then the processor has discretion whether or not to report the error. By contrast, <xsl:param name="p" as="xs:date"/> is treated as if required="yes" had been specified: the empty sequence is not a valid instance of xs:date, so in effect there is no default value and the parameter is therefore treated as being mandatory.

The optional tunnel attribute may be used to indicate that a parameter is a tunnel parameter. The default is no; the value yes may be specified only for template parameters. Tunnel parameters are described in 10.1.2 Tunnel Parameters

Issue 12 (value-attributes):

The treatment of tunnel and required is inconsistent in the case where the attribute makes no sense. In one case we allow the parameter to be present so long as it has its "fixed" value, in the other case we require it to be omitted. The WG has decided in principle that where only one value makes sense for an attribute, it should be legal to specify the attribute and give it that value. However, where an attribute makes no sense in a particular context, it will still be an error to include it: for example the from attribute of xsl:number must be omitted if the value attribute is present.

Editor to implement WG decision.

9.3 Values of Variables and Parameters

A variable-binding element may specify the supplied value of a variable or the default value of a parameter in four different ways.

If the variable-binding element has a select attribute, then the value of the attribute must be an expression and the supplied value of the variable is the value that results from evaluating the expression. In this case, the content of the variable-binding element must be empty.
If the variable-binding element has empty content and has neither a select attribute nor an as attribute, then the supplied value of the variable is a zero-length string. Thus
```
<xsl:variable name="x"/>
```
is equivalent to
```
<xsl:variable name="x" select="''"/>
```
If a variable-binding element has no select attribute and has non-empty content (that is, the variable-binding element has one or more child nodes), and has no as attribute, then the content of the variable-binding element specifies the supplied value. The content of the variable-binding element is a sequence constructor; a new document is constructed with a document node having as its children the sequence of nodes that results from evaluating the sequence constructor and then applying the rules given in 5.7.1 Constructing Complex Content. The value of the variable is then a singleton sequence containing this document node. For further information, see 9.4 Creating implicit document nodes.
If a variable-binding element has an as attribute but no select attribute, then the supplied value is the sequence that results from evaluating the (possibly empty) sequence constructor contained within the variable-binding element (see 5.7 Sequence Constructors).

These combinations are summarized in the table below.

select attribute	as attribute	content	Effect
present	absent	empty	Value is obtained by evaluating the `select` attribute
present	present	empty	Value is obtained by evaluating the `select` attribute, adjusted to the type required by the `as` attribute
present	absent	present	Static error
present	present	present	Static error
absent	absent	empty	Value is a zero-length string
absent	present	empty	Value is an empty sequence, provided the `as` attribute permits an empty sequence
absent	absent	present	Value is a document node whose content is obtained by evaluating the sequence constructor
absent	present	present	Value is obtained by evaluating the sequence constructor, adjusted to the type required by the `as` attribute

[ERR XTSE0620] It is a static error if a variable-binding element has a select attribute and has non-empty content.

Example: Values of Variables

The value of the following variable is the sequence of integers (1, 2, 3):

<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>

The value of the following variable is an integer, assuming that the attribute @size exists, and is annotated either as an integer, or as xs:untypedAtomic:

<xsl:variable name="i" as="xs:integer" select="@size"/>

The value of the following variable is a zero-length string:

<xsl:variable name="z"/>

The value of the following variable is a document node containing an empty element as a child:

<xsl:variable name="doc"><c/></xsl:variable>

The value of the following variable is a sequence of integers (2, 4, 6):

<xsl:variable name="seq" as="xs:integer*">
  <xsl:for-each select="1 to 3">
    <xsl:sequence select=".*2"/>
  </xsl:for-each>
</xsl:variable>

The value of the following variable is a sequence of parentless attribute nodes:

<xsl:variable name="attset" as="attribute()+">
  <xsl:attribute name="x">2</xsl:attribute>
  <xsl:attribute name="y">3</xsl:attribute>
  <xsl:attribute name="z">4</xsl:attribute>    
</xsl:variable>

The value of the following variable is an empty sequence:

<xsl:variable name="empty" as="empty-sequence()"/>

The actual value of the variable depends on the supplied value, as described above, and the required type, which is determined by the value of the as attribute.

Example: Pitfalls with Numeric Predicates

When a variable is used to select nodes by position, be careful not to do:

<xsl:variable name="n">2</xsl:variable>
...
<xsl:value-of select="td[$n]"/>

This will output the values of all the td elements, space-separated (or with XSLT 1.0 behavior, the value of the first td element), because the variable n will be bound to a node, not a number. Instead, do one of the following:

<xsl:variable name="n" select="2"/>
...
<xsl:value-of select="td[$n]"/>

<xsl:variable name="n">2</xsl:variable>
...
<xsl:value-of select="td[position()=$n]"/>

<xsl:variable name="n" as="xs:integer">2</xsl:variable>
...
<xsl:value-of select="td[$n]"/>

9.4 Creating implicit document nodes

A document node is created implicitly when evaluating an xsl:variable, xsl:param, or xsl:with-param element that has non-empty content and that has no as attribute. The value of the variable is a single node, the document node of a temporary tree. The content of the document node is formed from the result of evaluating the sequence constructor contained within the variable-binding element, as described in 5.7.1 Constructing Complex Content.

Note:

The construct:

<xsl:variable name="tree">
  <a/>
</xsl:variable>

can be regarded as a shorthand for:

<xsl:variable name="tree" as="document-node()">
  <xsl:document validation="preserve">
    <a/>
  </xsl:document>  
</xsl:variable>

The base URI of the document node is taken from the base URI of the variable binding element in the stylesheet. (See Section 5.2 base-uri Accessor^DM11 in [Data Model])

No document-level validation takes place (which means, for example, that there is no checking that ID values are unique). However, type annotations on nodes within the new tree are copied unchanged.

Note:

The base URI of other nodes in the tree is determined by the rules for constructing complex content. The effect of these rules is that the base URI of a node in the temporary tree is determined as if all the nodes in the temporary tree came from a single entity whose URI was the base URI of the variable-binding element. Thus, the base URI of the document node will be equal to the base URI of the variable-binding element, while an xml:base attribute within the temporary tree will change the base URI for its parent element and that element's descendants, just as it would within a document constructed by parsing.

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

A temporary tree is available for processing in exactly the same way as any source document. For example, its nodes are accessible using path expressions, and they can be processed using instructions such as xsl:apply-templates and xsl:for-each. Also, the key and id^FO functions can be used to find nodes within a temporary tree, by supplying the document node at the root of the tree as an argument to the function or by making it the context node.

Example: Two-Phase Transformation

For example, the following stylesheet uses a temporary tree as the intermediate result of a two-phase transformation, using different modes for the two phases (see 6.6 Modes). Typically, the template rules in module phase1.xsl will be declared with mode="phase1", while those in module phase2.xsl will be declared with mode="phase2":

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

<xsl:import href="phase1.xsl"/>
<xsl:import href="phase2.xsl"/>

<xsl:variable name="intermediate">
  <xsl:apply-templates select="/" mode="phase1"/>
</xsl:variable>

<xsl:template match="/">
  <xsl:apply-templates select="$intermediate" mode="phase2"/>
</xsl:template>

</xsl:stylesheet>

Note:

The algorithm for matching nodes against template rules is exactly the same regardless which tree the nodes come from. If different template rules are to be used when processing different trees, then unless nodes from different trees can be distinguished by means of patterns, it is a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.

9.5 Global Variables and Parameters

Both xsl:variable and xsl:param are allowed as declaration elements: that is, they may appear as children of the xsl:stylesheet element.

[Definition: A top-level variable-binding element declares a global variable that is visible everywhere (except where it is shadowed by another binding).]

[Definition: A top-level xsl:param element declares a stylesheet parameter. A stylesheet parameter is a global variable with the additional property that its value can be supplied by the caller when a transformation is initiated.] As described in 9.2 Parameters, a stylesheet parameter may be declared as being mandatory, or may have a default value specified for use when no value is supplied by the caller. The mechanism by which the caller supplies a value for a stylesheet parameter is implementation-defined. An XSLT processor must provide such a mechanism.

It is an error if no value is supplied for a mandatory stylesheet parameter [see ERR XTDE0050].

If a stylesheet contains more than one binding for a global variable of a particular name, then the binding with the highest import precedence is used.

[ERR XTSE0630] It is a static error if a stylesheet contains more than one binding of a global variable with the same name and same import precedence, unless it also contains another binding with the same name and higher import precedence.

For a global variable or the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus based on the root node of the tree containing the initial context item. An XPath error will be reported if the evaluation of a global variable or parameter references the context item, context position, or context size when no initial context item is supplied. The values of other components of the dynamic context are the initial values as defined in 5.4.3 Initializing the Dynamic Context and 5.4.4 Additional Dynamic Context Components used by XSLT.

Example: A Stylesheet Parameter

The following example declares a global parameter para-font-size, which is referenced in an attribute value template.

<xsl:param name="para-font-size" as="xs:string">12pt</xsl:param>

<xsl:template match="para">
 <fo:block font-size="{$para-font-size}">
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

The implementation must provide a mechanism allowing the user to supply a value for the parameter para-font-size when invoking the stylesheet; the value 12pt acts as a default.

9.6 Local Variables and Parameters

[Definition: As well as being allowed as a declaration, the xsl:variable element is also allowed in sequence constructors. Such a variable is known as a local variable.]

An xsl:param element may also be used to create a variable binding with local scope:

[Definition: An xsl:param element may appear as a child of an xsl:template element, before any non-xsl:param children of that element. Such a parameter is known as a template parameter. A template parameter is a local variable with the additional property that its value can be set when the template is called, using any of the instructions xsl:call-template, xsl:apply-templates, xsl:apply-imports, or xsl:next-match.]
[Definition: An xsl:param element may appear as a child of an xsl:function element, before any non-xsl:param children of that element. Such a parameter is known as a function parameter. A function parameter is a local variable with the additional property that its value can be set when the function is called, using a function call in an XPath expression.]
An xsl:param element may appear as a child of an xsl:iterate instruction, before any non-xsl:param children of that element. This defines a parameter whose value may be initialized on entry to the iteration, and which may be varied each time round the iteration by use of an xsl:with-param element in the xsl:next-iteration instruction.

The result of evaluating a local xsl:variable or xsl:param element (that is, the contribution it makes to the result of the sequence constructor it is part of) is an empty sequence.

9.7 Scope of Variables

For any variable-binding element, there is a region (more specifically, a set of element nodes) of the stylesheet within which the binding is visible. The set of variable bindings in scope for an XPath expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.

A global variable binding element is visible everywhere in the stylesheet (including other stylesheet modules) except within the xsl:variable or xsl:param element itself and any region where it is shadowed by another variable binding.

A local variable binding element is visible for all following siblings and their descendants, with the following exceptions:

It is not visible in any region where it is shadowed by another variable binding.
It is not visible within the subtree rooted at an xsl:fallback instruction that is a sibling of the variable binding element.
It is not visible within the subtree rooted at an xsl:catch instruction that is a sibling of the variable binding element.

The binding is not visible for the xsl:variable or xsl:param element itself.

[Definition: A binding shadows another binding if the binding occurs at a point where the other binding is visible, and the bindings have the same name. ] It is not an error if a binding established by a local xsl:variable or xsl:param shadows a global binding. In this case, the global binding will not be visible in the region of the stylesheet where it is shadowed by the other binding.

Example: Local Variable Shadowing a Global Variable

The following is allowed:

<xsl:param name="x" select="1"/>
<xsl:template name="foo">
  <xsl:variable name="x" select="2"/>
</xsl:template>

It is also not an error if a binding established by a local xsl:variable element shadows a binding established by another local xsl:variable or xsl:param.

Example: Misuse of Variable Shadowing

The following is not an error, but the effect is probably not what was intended. The template outputs <x value="1"/>, because the declaration of the inner variable named $x has no effect on the value of the outer variable named $x.

<xsl:variable name="x" select="1"/>
<xsl:template name="foo">
  <xsl:for-each select="1 to 5">
    <xsl:variable name="x" select="$x+1"/>
  </xsl:for-each>
  <x value="{$x}"/>
</xsl:template>

Note:

Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages.

This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.

As well as global variables and local variables, an XPath expression may also declare range variables for use locally within an expression. For details, see [XPath 2.1].

Where a reference to a variable occurs in an XPath expression, it is resolved first by reference to range variables that are in scope, then by reference to local variables and parameters, and finally by reference to global variables and parameters. A range variable may shadow a local variable or a global variable. XPath also allows a range variable to shadow another range variable.

9.8 Setting Parameter Values

<xsl:with-param name = qname select? = expression as? = sequence-type tunnel? = "yes" | "no" >  </xsl:with-param>

Parameters are passed to templates using the xsl:with-param element. The required name attribute specifies the name of the template parameter (the variable the value of whose binding is to be replaced). The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

The xsl:with-param element is also used when passing parameters to an iteration of the xsl:iterate instruction, or to a dynamic invocation of an XPath expression using xsl:evaluate. In consequence, xsl:with-param may appear within xsl:apply-templates, xsl:apply-imports, xsl:call-template, xsl:evaluate, xsl:next-iteration, and xsl:next-match. (Arguments to stylesheet functions, however, are supplied as part of an XPath function call: see 10.3 Stylesheet Functions.)

[ERR XTSE0670] It is a static error if two or more sibling xsl:with-param elements have name attributes that represent the same expanded QName.

The value of the parameter is specified in the same way as for xsl:variable and xsl:param (see 9.3 Values of Variables and Parameters), taking account of the values of the select and as attributes and the content of the xsl:with-param element, if any.

Note:

It is possible to have an as attribute on the xsl:with-param element that differs from the as attribute on the corresponding xsl:param element describing the formal parameters of the called template.

In this situation, the supplied value of the parameter will first be processed according to the rules of the as attribute on the xsl:with-param element, and the resulting value will then be further processed according to the rules of the as attribute on the xsl:param element.

For example, suppose the supplied value is a node with type annotation xs:untypedAtomic, and the xsl:with-param element specifies as="xs:integer", while the xsl:param element specifies as="xs:double". Then the node will first be atomized and the resulting untyped atomic value will be cast to xs:integer. If this succeeds, the xs:integer will then be promoted to an xs:double.

The focus used for computing the value specified by the xsl:with-param element is the same as that used for its parent instruction.

The optional tunnel attribute may be used to indicate that a parameter is a tunnel parameter. The default is no. Tunnel parameters are described in 10.1.2 Tunnel Parameters. They are used only when passing parameters to templates: for an xsl:with-param element that is a child of xsl:evaluate or xsl:next-iteration the tunnel attribute must either be omitted or take the value no.

In other cases it is a non-recoverable dynamic error if the template that is invoked declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction. [see ERR XTDE0700]

9.9 Circular Definitions

[Definition: A circularity is said to exist if a construct such as a global variable, an attribute set, or a key, is defined in terms of itself. For example, if the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. A circularity exists if it is impossible to do this for all global variable definitions.]

Example: Circular Variable Definitions

The following two declarations create a circularity:

<xsl:variable name="x" select="$y+1"/>
<xsl:variable name="y" select="$x+1"/>

Example: Circularity involving Variables and Functions

The definition of a global variable can be circular even if no other variable is involved. For example the following two declarations (see 10.3 Stylesheet Functions for an explanation of the xsl:function element) also create a circularity:

<xsl:variable name="x" select="my:f()"/>

<xsl:function name="my:f">
  <xsl:sequence select="$x"/>
</xsl:function>

Example: Circularity involving Variables and Templates

The definition of a variable is also circular if the evaluation of the variable invokes an xsl:apply-templates instruction and the variable is referenced in the pattern used in the match attribute of any template rule in the stylesheet. For example the following definition is circular:

<xsl:variable name="x">
  <xsl:apply-templates select="//param[1]"/>
</xsl:variable>

<xsl:template match="param[$x]">1</xsl:template>

Example: Circularity involving Variables and Keys

Similarly, a variable definition is circular if it causes a call on the key function, and the definition of that key refers to that variable in its match or use attributes. So the following definition is circular:

<xsl:variable name="x" select="my:f(10)"/>

<xsl:function name="my:f">
  <xsl:param name="arg1"/>
  <xsl:sequence select="key('k', $arg1)"/>
</xsl:function>

<xsl:key name="k" match="item[@code=$x]" use="@desc"/>

[ERR XTDE0640] In general, a circularity in a stylesheet is a non-recoverable dynamic error. However, as with all other dynamic errors, an implementation will signal the error only if it actually executes the instructions and expressions that participate in the circularity. Because different implementations may optimize the execution of a stylesheet in different ways, it is implementation-dependent whether a particular circularity will actually be signaled.

For example, in the following declarations, the function declares a local variable $b, but it returns a result that does not require the variable to be evaluated. It is implementation-dependent whether the value is actually evaluated, and it is therefore implementation-dependent whether the circularity is signaled as an error:

<xsl:variable name="x" select="my:f(1)/>

<xsl:function name="my:f">
  <xsl:param name="a"/>
  <xsl:variable name="b" select="$x"/>  
  <xsl:sequence select="$a + 2"/>
</xsl:function>

Circularities usually involve global variables or parameters, but they can also exist between key definitions (see 19.3 Keys), between named attribute sets (see 10.2 Named Attribute Sets), or between any combination of these constructs. For example, a circularity exists if a key definition invokes a function that references an attribute set that calls the key function, supplying the name of the original key definition as an argument.

Circularity is not the same as recursion. Stylesheet functions (see 10.3 Stylesheet Functions) and named templates (see 10.1 Named Templates) may call other functions and named templates without restriction. With careless coding, recursion may be non-terminating. Implementations are required to signal circularity as a dynamic error, but they are not required to detect non-terminating recursion.

10 Callable Components

This section describes three constructs that can be used to provide subroutine-like functionality that can be invoked from anywhere in the stylesheet: named templates (see 10.1 Named Templates), named attribute sets (see 10.2 Named Attribute Sets), and stylesheet functions (see 10.3 Stylesheet Functions).

10.1 Named Templates

 <xsl:call-template name = qname >  </xsl:call-template>

[Definition: Templates can be invoked by name. An xsl:template element with a name attribute defines a named template.] The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. If an xsl:template element has a name attribute, it may, but need not, also have a match attribute. An xsl:call-template instruction invokes a template by name; it has a required name attribute that identifies the template to be invoked. Unlike xsl:apply-templates, the xsl:call-template instruction does not change the focus.

The match, mode and priority attributes on an xsl:template element have no effect when the template is invoked by an xsl:call-template instruction. Similarly, the name attribute on an xsl:template element has no effect when the template is invoked by an xsl:apply-templates instruction.

[ERR XTSE0650] It is a static error if a stylesheet contains an xsl:call-template instruction whose name attribute does not match the name attribute of any xsl:template in the stylesheet.

[ERR XTSE0660] It is a static error if a stylesheet contains more than one template with the same name and the same import precedence, unless it also contains a template with the same name and higher import precedence.

The target template for an xsl:call-template instruction is the template whose name attribute matches the name attribute of the xsl:call-template instruction and that has higher import precedence than any other template with this name. The result of evaluating an xsl:call-template instruction is the sequence produced by evaluating the sequence constructor contained in its target template (see 5.7 Sequence Constructors).

10.1.1 Passing Parameters to Named Templates

Parameters are passed to named templates using the xsl:with-param element as a child of the xsl:call-template instruction.

[ERR XTSE0680] In the case of xsl:call-template, it is a static error to pass a non-tunnel parameter named x to a template that does not have a template parameter named x, unless the xsl:call-template instruction is processed with XSLT 1.0 behavior. This is not an error in the case of xsl:apply-templates, xsl:apply-imports, and xsl:next-match; in these cases the parameter is simply ignored.

The optional tunnel attribute may be used to indicate that a parameter is a tunnel parameter. The default is no. Tunnel parameters are described in 10.1.2 Tunnel Parameters

[ERR XTSE0690] It is a static error if a template that is invoked using xsl:call-template declares a template parameter specifying required="yes" and not specifying tunnel="yes", if no value for this parameter is supplied by the calling xsl:call-template instruction.

Example: Calling a Named Template with a Parameter

This example defines a named template for a numbered-block with a parameter to control the format of the number.

<xsl:template name="numbered-block">
  <xsl:param name="format">1. </xsl:param>
  <fo:block>
    <xsl:number format="{$format}"/>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="ol//ol/li">
  <xsl:call-template name="numbered-block">
    <xsl:with-param name="format">a. </xsl:with-param>
  </xsl:call-template>
</xsl:template>

10.1.2 Tunnel Parameters

[Definition: A parameter passed to a template may be defined as a tunnel parameter. Tunnel parameters have the property that they are automatically passed on by the called template to any further templates that it calls, and so on recursively.] Tunnel parameters thus allow values to be set that are accessible during an entire phase of stylesheet processing, without the need for each template that is used during that phase to be aware of the parameter.

Note:

Tunnel parameters are conceptually similar to dynamically scoped variables in some functional programming languages.

A tunnel parameter is created by using an xsl:with-param element that specifies tunnel="yes". A template that requires access to the value of a tunnel parameter must declare it using an xsl:param element that also specifies tunnel="yes".

On any template call using an xsl:apply-templates, xsl:call-template, xsl:apply-imports or xsl:next-match instruction, a set of tunnel parameters is passed from the calling template to the called template. This set consists of any parameters explicitly created using <xsl:with-param tunnel="yes">, overlaid on a base set of tunnel parameters. If the xsl:apply-templates, xsl:call-template, xsl:apply-imports or xsl:next-match instruction has an xsl:template declaration as an ancestor element in the stylesheet, then the base set consists of the tunnel parameters that were passed to that template; otherwise (for example, if the instruction is within a global variable declaration, an attribute set declaration, or a stylesheet function), the base set is empty. If a parameter created using <xsl:with-param tunnel="yes"> has the same expanded-QName as a parameter in the base set, then the parameter created using xsl:with-param overrides the parameter in the base set; otherwise, the parameter created using xsl:with-param is added to the base set.

When a template accesses the value of a tunnel parameter by declaring it with xsl:param tunnel="yes", this does not remove the parameter from the base set of tunnel parameters that is passed on to any templates called by this template.

Two sibling xsl:with-param elements must have distinct parameter names, even if one is a tunnel parameter and the other is not. Equally, two sibling xsl:param elements representing template parameters must have distinct parameter names, even if one is a tunnel parameter and the other is not. However, the tunnel parameters that are implicitly passed in a template call may have names that duplicate the names of non-tunnel parameters that are explicitly passed on the same call.

Tunnel parameters are not passed in calls to stylesheet functions.

All other options of xsl:with-param and xsl:param are available with tunnel parameters just as with non-tunnel parameters. For example, parameters may be declared as mandatory or optional, a default value may be specified, and a required type may be specified. If any conversion is required from the supplied value of a tunnel parameter to the required type specified in xsl:param, then the converted value is used within the receiving template, but the value that is passed on in any further template calls is the original supplied value before conversion. Equally, any default value is local to the template: specifying a default value for a tunnel parameter does not change the set of tunnel parameters that is passed on in further template calls.

The set of tunnel parameters that is passed to the initial template is empty.

Tunnel parameters are passed unchanged through a built-in template rule (see 6.7 Built-in Template Rules).

If a tunnel parameter is declared in an xsl:param element with the attribute tunnel="yes", then a non-recoverable dynamic error occurs [see ERR XTDE0700] if the set of tunnel parameters passed to the template does not include a parameter with a matching expanded QName.

Example: Using Tunnel Parameters

Suppose that the equations in a scientific paper are to be sequentially numbered, but that the format of the number depends on the context in which the equations appear. It is possible to reflect this using a rule of the form:

<xsl:template match="equation">
  <xsl:param name="equation-format" select="'(1)'" tunnel="yes"/>
  <xsl:number level="any" format="{$equation-format}"/>
</xsl:template>

At any level of processing above this level, it is possible to determine how the equations will be numbered, for example:

<xsl:template match="appendix">
  ...
  <xsl:apply-templates>
    <xsl:with-param name="equation-format" select="'[i]'" tunnel="yes"/>
  </xsl:apply-templates>
  ...
</xsl:template>

The parameter value is passed transparently through all the intermediate layers of template rules until it reaches the rule with match="equation". The effect is similar to using a global variable, except that the parameter can take different values during different phases of the transformation.

10.2 Named Attribute Sets

 <xsl:attribute-set name = qname use-attribute-sets? = qnames >  </xsl:attribute-set>

[Definition: The xsl:attribute-set element defines a named attribute set: that is, a collection of attribute definitions that can be used repeatedly on different constructed elements.]

The required name attribute specifies the name of the attribute set. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. The content of the xsl:attribute-set element consists of zero or more xsl:attribute instructions that are evaluated to produce the attributes in the set.

The result of evaluating an attribute set is a sequence of attribute nodes. Evaluating the same attribute set more than once can produce different results, because although an attribute set does not have parameters, it may contain expressions or instructions whose value depends on the evaluation context.

Attribute sets are used by specifying a use-attribute-sets attribute on the xsl:element or xsl:copy instruction, or by specifying an xsl:use-attribute-sets attribute on a literal result element. An attribute set may be defined in terms of other attribute sets by using the use-attribute-sets attribute on the xsl:attribute-set element itself. The value of the [xsl:]use-attribute-sets attribute is in each case a whitespace-separated list of names of attribute sets. Each name is specified as a QName, which is expanded as described in 5.1 Qualified Names.

Specifying a use-attribute-sets attribute is broadly equivalent to adding xsl:attribute instructions for each of the attributes in each of the named attribute sets to the beginning of the content of the instruction with the [xsl:]use-attribute-sets attribute, in the same order in which the names of the attribute sets are specified in the use-attribute-sets attribute.

More formally, an xsl:use-attribute-sets attribute is expanded using the following recursive algorithm, or any algorithm that produces the same results:

The value of the attribute is tokenized as a list of QNames.
Each QName in the list is processed, in order, as follows:
- The QName must match the name attribute of one or more xsl:attribute-set declarations in the stylesheet.
- Each xsl:attribute-set declaration whose name matches is processed as follows. Where two such declarations have different import precedence, the one with lower import precedence is processed first. Where two declarations have the same import precedence, they are processed in declaration order.
  - If the xsl:attribute-set declaration has a use-attribute-sets attribute, the attribute is expanded by applying this algorithm recursively.
  - If the xsl:attribute-set declaration contains one or more xsl:attribute instructions, these instructions are evaluated (following the rules for evaluating a sequence constructor: see 5.7 Sequence Constructors) to produce a sequence of attribute nodes. These attribute nodes are appended to the result sequence.

The xsl:attribute instructions are evaluated using the same focus as is used for evaluating the element that is the parent of the [xsl:]use-attribute-sets attribute forming the initial input to the algorithm. However, the static context for the evaluation depends on the position of the xsl:attribute instruction in the stylesheet: thus, only local variables declared within an xsl:attribute instruction, and global variables, are visible.

The set of attribute nodes produced by expanding xsl:use-attribute-sets may include several attributes with the same name. When the attributes are added to an element node, only the last of the duplicates will take effect.

The way in which each instruction uses the results of expanding the [xsl:]use-attribute-sets attribute is described in the specification for the relevant instruction: see 11.1 Literal Result Elements, 11.2 Creating Element Nodes Using xsl:element , and 11.9 Copying Nodes.

[ERR XTSE0710] It is a static error if the value of the use-attribute-sets attribute of an xsl:copy, xsl:element, or xsl:attribute-set element, or the xsl:use-attribute-sets attribute of a literal result element, is not a whitespace-separated sequence of QNames, or if it contains a QName that does not match the name attribute of any xsl:attribute-set declaration in the stylesheet.

[ERR XTSE0720] It is a static error if an xsl:attribute-set element directly or indirectly references itself via the names contained in the use-attribute-sets attribute.

Each attribute node produced by expanding an attribute set has a type annotation determined by the rules for the xsl:attribute instruction that created the attribute node: see 11.3.1 Setting the Type Annotation for a Constructed Attribute Node. These type annotations may be preserved, stripped, or replaced as determined by the rules for the instruction that creates the element in which the attributes are used.

Attribute sets are used as follows:

The xsl:copy and xsl:element instructions have an use-attribute-sets attribute. The sequence of attribute nodes produced by evaluating this attribute is prepended to the sequence produced by evaluating the sequence constructor contained within the instruction.
Literal result elements allow an xsl:use-attribute-sets attribute, which is evaluated in the same way as the use-attribute-sets attribute of xsl:element and xsl:copy. The sequence of attribute nodes produced by evaluating this attribute is prepended to the sequence of attribute nodes produced by evaluating the attributes of the literal result element, which in turn is prepended to the sequence produced by evaluating the sequence constructor contained with the literal result element.

Example: Using Attribute Sets

The following example creates a named attribute set title-style and uses it in a template rule.

<xsl:template match="chapter/heading">
  <fo:block font-stretch="condensed" xsl:use-attribute-sets="title-style">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:attribute-set name="title-style">
  <xsl:attribute name="font-size">12pt</xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:attribute-set>

Example: Overriding Attributes in an Attribute Set

The following example creates a named attribute set base-style and uses it in a template rule with multiple specifications of the attributes:

font-family: is specified only in the attribute set
font-size: is specified in the attribute set, is specified on the literal result element, and in an xsl:attribute instruction
font-style: is specified in the attribute set, and on the literal result element
font-weight: is specified in the attribute set, and in an xsl:attribute instruction

Stylesheet fragment:

<xsl:attribute-set name="base-style">
  <xsl:attribute name="font-family">Univers</xsl:attribute>
  <xsl:attribute name="font-size">10pt</xsl:attribute>
  <xsl:attribute name="font-style">normal</xsl:attribute>
  <xsl:attribute name="font-weight">normal</xsl:attribute>
</xsl:attribute-set>

<xsl:template match="o">
  <fo:block xsl:use-attribute-sets="base-style"
            font-size="12pt"
            font-style="italic">
    <xsl:attribute name="font-size">14pt</xsl:attribute>
    <xsl:attribute name="font-weight">bold</xsl:attribute>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

Result:

<fo:block font-family="Univers"
          font-size="14pt"
          font-style="italic"
          font-weight="bold">
...
</fo:block>

10.3 Stylesheet Functions

[Definition: An xsl:function declaration declares the name, parameters, and implementation of a stylesheet function that can be called from any XPath expression within the stylesheet.]

 <xsl:function name = qname as? = sequence-type override? = "yes" | "no" >  </xsl:function>

The xsl:function declaration defines a stylesheet function that can be called from any XPath expression used in the stylesheet (including an XPath expression used within a predicate in a pattern). The name attribute specifies the name of the function. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

An xsl:function declaration can only appear as a top-level element in a stylesheet module.

[ERR XTSE0740] A stylesheet function must have a prefixed name, to remove any risk of a clash with a function in the default function namespace. It is a static error if the name has no prefix..

Note:

To prevent the namespace declaration used for the function name appearing in the result document, use the exclude-result-prefixes attribute on the xsl:stylesheet element: see 11.1.3 Namespace Nodes for Literal Result Elements.

The prefix must not refer to a reserved namespace: [see ERR XTSE0080]

The content of the xsl:function element consists of zero or more xsl:param elements that specify the formal arguments of the function, followed by a sequence constructor that defines the value to be returned by the function.

[Definition: The arity of a stylesheet function is the number of xsl:param elements in the function definition.] Optional arguments are not allowed.

[ERR XTSE0760] Because arguments to a stylesheet function call must all be specified, the xsl:param elements within an xsl:function element must not specify a default value: this means they must be empty, and must not have a select attribute.

A stylesheet function is included in the in-scope functions of the static context for all XPath expressions used in the stylesheet, unless

there is another stylesheet function with the same name and arity, and higher import precedence, or
the override attribute has the value no and there is already a function with the same name and arity in the in-scope functions.

The optional override attribute defines what happens if this function has the same name and arity as a function provided by the implementer or made available in the static context using an implementation-defined mechanism. If the override attribute has the value yes, then this function is used in preference; if it has the value no, then the other function is used in preference. The default value is yes.

Note:

Specifying override="yes" ensures interoperable behavior: the same code will execute with all processors. Specifying override="no" is useful when writing a fallback implementation of a function that is available with some processors but not others: it allows the vendor's implementation of the function (or a user's implementation written as an extension function) to be used in preference to the stylesheet implementation, which is useful when the extension function is more efficient.

The override attribute does not affect the rules for deciding which of several stylesheet functions with the same name and arity takes precedence.

[ERR XTSE0770] It is a static error for a stylesheet to contain two or more functions with the same expanded-QName, the same arity, and the same import precedence, unless there is another function with the same expanded-QName and arity, and a higher import precedence.

As defined in XPath, the function that is executed as the result of a function call is identified by looking in the in-scope functions of the static context for a function whose name and arity matches the name and number of arguments in the function call.

Note:

Functions are not polymorphic. Although the XPath function call mechanism allows two functions to have the same name and different arity, it does not allow them to be distinguished by the types of their arguments.

The optional as attribute indicates the required type of the result of the function. The value of the as attribute is a SequenceType^XP21, as defined in [XPath 2.1].

[ERR XTTE0780] If the as attribute is specified, then the result evaluated by the sequence constructor (see 5.7 Sequence Constructors) is converted to the required type, using the function conversion rules. It is a type error if this conversion fails. If the as attribute is omitted, the calculated result is used as supplied, and no conversion takes place.

If a stylesheet function has been defined with a particular expanded-QName, then a call on function-available will return true when called with an argument that is a lexical QName that expands to this same expanded-QName.

The xsl:param elements define the formal arguments to the function. These are interpreted positionally. When the function is called using a function-call in an XPath expression, the first argument supplied is assigned to the first xsl:param element, the second argument supplied is assigned to the second xsl:param element, and so on.

The as attribute of the xsl:param element defines the required type of the parameter. The rules for converting the values of the actual arguments supplied in the function call to the types required by each xsl:param element are defined in [XPath 2.1]. The rules that apply are those for the case where XPath 1.0 compatibility mode is set to false.

[ERR XTTE0790] If the value of a parameter to a stylesheet function cannot be converted to the required type, a type error is signaled.

If the as attribute is omitted, no conversion takes place and any value is accepted.

Within the body of a stylesheet function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a non-recoverable dynamic error. [XPDY0002]

It is not possible within the body of the stylesheet function to access the values of local variables that were in scope in the place where the function call was written. Global variables, however, remain available.

Example: A Stylesheet Function

The following example creates a recursive stylesheet function named str:reverse that reverses the words in a supplied sentence, and then invokes this function from within a template rule.

<xsl:transform 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:str="http://example.com/namespace"
  version="2.1"
  exclude-result-prefixes="str">

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs:string"/>
  <xsl:sequence  
     select="if (contains($sentence, ' '))
             then concat(str:reverse(substring-after($sentence, ' ')),
                         ' ',
                         substring-before($sentence, ' '))
             else $sentence"/>
</xsl:function>

<xsl:template match="/">
<output>
  <xsl:value-of select="str:reverse('DOG BITES MAN')"/>
</output>
</xsl:template>

</xsl:transform>

An alternative way of writing the same function is to implement the conditional logic at the XSLT level, thus:

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs:string"/>
  <xsl:choose>
    <xsl:when test="contains($sentence, ' ')">  
      <xsl:sequence 
           select="concat(str:reverse(substring-after($sentence, ' ')),
                                ' ',
                                substring-before($sentence, ' '))"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:sequence select="$sentence"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>

Example: Declaring the Return Type of a Function

The following example illustrates the use of the as attribute in a function definition. It returns a string containing the representation of its integer argument, expressed as a roman numeral. For example, the function call num:roman(7) will return the string "vii". This example uses the xsl:number instruction, described in 12 Numbering. The xsl:number instruction returns a text node, and the function conversion rules are invoked to convert this text node to the type declared in the xsl:function element, namely xs:string. So the text node is atomized to a string.

<xsl:function name="num:roman" as="xs:string">
  <xsl:param name="value" as="xs:integer"/>
  <xsl:number value="$value" format="i"/>
</xsl:function>

Example: A Higher-Order Function

XPath 2.1 introduces the ability to pass function items as argument to a function. A function that takes function items as arguments is known as a higher-order function.

The following example is a higher-order function that operates on any tree-structured data, for example an organization chart. Given as input a function that finds the direct subordinates of a node in this tree structure (for example, the direct reports of a manager, or the geographical subdivisions of an administrative area), it determines whether one object is present in the subtree rooted at another object (for example, whether one person is among the staff managed directly or indirectly by a manager, or whether one parcel of land is contained directly or indirectly within another parcel. The function does not check for cycles in the data.

<xsl:function name="f:is-subordinate" as="xs:boolean">
    <xsl:param name="superior" 
               as="node()"/>
    <xsl:param name="subordinate" 
               as="node()"/>
    <xsl:param name="get-direct-children" 
               as="function(node()) as node()*"/>
    <xsl:sequence select="
               some $sub in $get-direct-children($superior) satisfies
                 ($sub is $subordinate or
                  f:is-subordinate($sub, $subordinate, 
                                      $get-direct-children))"/>
</xsl:function>

Given source data representing an organization chart in the form of elements such as:

<employee id="P57832" manager="P68951"/>

the following function can be defined to get the direct reports of a manager:

<xsl:function name="f:direct-reports" 
               as="element(employee)*">
    <xsl:param name="manager" as="element(employee)"/>
    <xsl:sequence select="$manager/../employee
                               [@manager = current()/@id]"/>
    </xsl:function>

It is then possible to test whether one employee $E reports directly or indirectly to another employee $M by means of the function call:

f:is-subordinate($M, $E, f:direct-reports#1)

10.4 Dynamic XPath Evaluation

 <xsl:evaluate xpath = expression as? = sequence-type base-uri? = { URI } namespace-context? = expression schema-aware? = { "yes" | "no" } >  </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 function conversion rules.

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

[ERR XTDE2150] It is a non-recoverable dynamic error if the target expression is not a legal XPath 2.1 expression (that is, if a static error occurs when analyzing the string according to the rules of the XPath 2.1 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 function conversion 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 static context^XP21 for the target expression is as follows:

XPath 1.0 compatibility mode is false.
Statically known namespaces and default element/type namespace:
- if the namespace-context attribute is present, then its value is an expression whose required type is a single node. The expression is evaluated, and the in-scope namespaces of the resulting node are used as the statically known namespaces for the target expression. The binding for the default namespace in the in-scope namespaces is used as the default namespace for elements and types in the target expression.
  
  [ERR XTTE2160] It is a type error if the result of evaluating the namespace-context attribute of the xsl:evaluate instruction is anything other than a single node.
- if the namespace-context attribute is absent, then the in-scope namespaces of the xsl:evaluate instruction (with the exception of any binding for the default namespace) are used as the statically known namespaces for the target expression, and the value of the innermost [xsl:]xpath-default-namespace attribute, if any, is used as the default namespace for elements and types in the target expression.
Note:

XPath 2.1 allows expanded names to be written in a context-independent way using the syntax "namespace-uri":local-name
Default function namespace: the standard function namespace.
In-scope schema definitions: if the schema-aware attribute is present and has the effective value yes, then the in-scope schema definitions from the stylesheet context (that is, the schema definitions imported using xsl:import-schema). Otherwise, the built-in types (see 3.13 Built-in Types).
In-scope variables: the variables defined in the contained xsl:with-param elements.

Note:

Variables declared in the stylesheet in xsl:variable or xsl:param elements are not in-scope within the target expression.
Function signatures: All core functions; constructor functions for atomic types included in the in-scope schema definitions; user-defined functions declared using xsl:function; and an implementation-defined set of extension functions.

Note that this set deliberately excludes XSLT-defined functions in the standard function namespace including for example, key, current-group, and system-property A list of these functions is in F List of XSLT-defined functions.
Statically known collections: the same as the collations available at this point in the stylesheet.
Default collation: the same as the default collation defined at this point in the stylesheet (for example, by use of the [xsl:]default-collation attribute)
Base URI: if the base-uri attribute is present, then its effective value; otherwise, the base URI of the xsl:evaluate instruction.
Statically known documents: the empty set
Statically known collections: the empty set
Statically known default collection type: node()*

The dynamic context for evaluation of the target expression is the same as the dynamic context for the xsl:evaluate instruction (in particular, the focus is the same), except for the variable values: this consists of the values bound to parameters defined in the contained xsl:with-param elements, which are evaluated as described in 9.3 Values of Variables and Parameters.

An XSLT 2.1 processor will ignore any xsl:fallback children of the xsl:evaluate instruction; they can be used to define the behavior of an XSLT 1.0 or XSLT 2.0 processor when this instruction is encountered.

The XPath expression is evaluated in the same execution scope^FO as the calling XSLT transformation; this means that the results of stable^FO functions such as doc^FO or current-dateTime^FO will be consistent between the calling stylesheet and the called XPath expression.

It is a non-recoverable dynamic error if evaluation of the XPath expression fails with a dynamic error. The XPath-defined error code is used unchanged.

Note:

Implementations wanting to avoid the cost of repeated compilation of the same XPath expression should cache the compiled form internally.

Example: Using a dynamic sort key

A common requirement is to sort a table on the value of an expression which is selected at run-time, perhaps by supplying the expression as a string-valued parameter to the stylesheet. Suppose that such an expression is supplied to the parameter:

<xsl:param name="sortkey" as="xs:string" select="'@name'"/>

Then the data may be sorted as follows:

<xsl:sort>
   <xsl:evaluate xpath="$sortkey" as="xs:string"/>
</xsl:sort>

Note the importance in this use case of caching the compiled expression, since it is evaluated repeatedly, once for each item in the list being sorted.

Issue 13 (evaluate-optional-feature):

The Working Group has not yet decided whether xsl:evaluate will be an optional feature of the language, or whether all implementations will be required to provide it.

11 Creating Nodes and Sequences

This section describes instructions that directly create new nodes, or sequences of nodes, atomic values, and/or function items.

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

11.1.1 Setting the Type Annotation for Literal Result Elements

The attributes xsl:type and xsl:validation may be used on a literal result element to invoke validation of the contents of the element against a type definition or element declaration in a schema, and to determine the type annotation that the new element node will carry. These attributes also affect the type annotation carried by any elements and attributes that have the new element node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted.

The value of the xsl:validation attribute, if present, must be one of the values strict, lax, preserve, or strip. The value of the xsl:type attribute, if present, must be a QName identifying a type definition that is present in the in-scope schema components for the stylesheet. Neither attribute may be specified as an attribute value template. The effect of these attributes is described in 22.2 Validation.

11.1.2 Attribute Nodes for Literal Result Elements

Attribute nodes for a literal result element may be created by including xsl:attribute instructions within the sequence constructor. Additionally, attribute nodes are created corresponding to the attributes of the literal result element in the stylesheet, and as a result of expanding the xsl:use-attribute-sets attribute of the literal result element, if present.

The sequence that is used to construct the content of the literal result element (as described in 5.7.1 Constructing Complex Content) is the concatenation of the following four sequences, in order:

The sequence of namespace nodes produced as described in 11.1.3 Namespace Nodes for Literal Result Elements.
The sequence of attribute nodes produced by expanding the xsl:use-attribute-sets attribute (if present) following the rules given in 10.2 Named Attribute Sets
The attributes produced by processing the attributes of the literal result element itself, other than attributes in the XSLT namespace. The way these are processed is described below.
The sequence produced by evaluating the contained sequence constructor, if the element is not empty.

Note:

The significance of this order is that an attribute produced by an xsl:attribute, xsl:copy, or xsl:copy-of instruction in the content of the literal result element takes precedence over an attribute produced by expanding an attribute of the literal result element itself, which in turn takes precedence over an attribute produced by expanding the xsl:use-attribute-sets attribute. This is because of the rules in 5.7.1 Constructing Complex Content, which specify that when two or more attributes in the sequence have the same name, all but the last of the duplicates are discarded.

Although the above rules place namespace nodes before attributes, this is not strictly necessary, because the rules in 5.7.1 Constructing Complex Content allow the namespaces and attributes to appear in any order so long as both come before other kinds of node. The order of namespace nodes and attribute nodes in the sequence has no effect on the relative position of the nodes in document order once they are added to a tree.

Each attribute of the literal result element, other than an attribute in the XSLT namespace, is processed to produce an attribute for the element in the result tree.

The value of such an attribute is interpreted as an attribute value template: it can therefore contain expressions contained in curly brackets ({}). The new attribute node will have the same expanded-QName (that is, the same namespace URI, local name, and namespace prefix) as the attribute in the stylesheet tree, and its string value will be the same as the effective value of the attribute in the stylesheet tree. The type annotation on the attribute will initially be xs:untypedAtomic, and the typed value of the attribute node will be the same as its string value.

Note:

The eventual type annotation of the attribute in the result tree depends on the xsl:validation and xsl:type attributes of the parent literal result element, and on the instructions used to create its ancestor elements. If the xsl:validation attribute is set to preserve or strip, the type annotation will be xs:untypedAtomic, and the typed value of the attribute node will be the same as its string value. If the xsl:validation attribute is set to strict or lax, or if the xsl:type attribute is used, the type annotation on the attribute will be set as a result of the schema validation process applied to the parent element. If neither attribute is present, the type annotation on the attribute will be xs:untypedAtomic.

[ERR XTRE0795] It is a recoverable dynamic error if the name of a constructed attribute is xml:space and the value is not either default or preserve. The optional recovery action is to construct the attribute with the value as requested. . This applies whether the attribute is constructed using a literal result element, or by using the xsl:attribute, xsl:copy, or xsl:copy-of instructions.

Note:

The xml:base, xml:lang, xml:space, and xml:id attributes have two effects in XSLT. They behave as standard XSLT attributes, which means for example that if they appear on a literal result element, they will be copied to the result tree in the same way as any other attribute. In addition, they have their standard meaning as defined in the core XML specifications. Thus, an xml:base attribute in the stylesheet affects the base URI of the element on which it appears, and an xml:space attribute affects the interpretation of whitespace text nodes within that element. One consequence of this is that it is inadvisable to write these attributes as attribute value templates: although an XSLT processor will understand this notation, the XML parser will not. See also 11.1.4 Namespace Aliasing which describes how to use xsl:namespace-alias with these attributes.

The same is true of the schema-defined attributes xsi:type, xsi:nil, xsi:noNamespaceSchemaLocation, and xsi:schemaLocation. If the stylesheet is processed by a schema processor, these attributes will be recognized and interpreted by the schema processor, but in addition the XSLT processor treats them like any other attribute on a literal result element: that is, their effective value (after expanding attribute value templates) is copied to the result tree in the same way as any other attribute. If the result tree is validated, the copied attributes will again be recognized and interpreted by the schema processor.

None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly, in the same way as any other attribute.

[ERR XTSE0805] It is a static error if an attribute on a literal result element is in the XSLT namespace, unless it is one of the attributes explicitly defined in this specification.

Note:

If there is a need to create attributes in the XSLT namespace, this can be achieved using xsl:attribute, or by means of the xsl:namespace-alias declaration.

11.1.3 Namespace Nodes for Literal Result Elements

The created element node will have a copy of the namespace nodes that were present on the element node in the stylesheet tree with the exception of any namespace node whose string value is designated as an excluded namespace. Special considerations apply to aliased namespaces: see 11.1.4 Namespace Aliasing

The following namespaces are designated as excluded namespaces:

The XSLT namespace URI (http://www.w3.org/1999/XSL/Transform)
A namespace URI declared as an extension namespace (see 21.2 Extension Instructions)
A namespace URI designated by using an [xsl:]exclude-result-prefixes attribute either on the literal result element itself or on an ancestor element. The attribute must be in the XSLT namespace only if its parent element is not in the XSLT namespace.

The value of the attribute is either #all, or a whitespace-separated list of tokens, each of which is either a namespace prefix or #default. The namespace bound to each of the prefixes is designated as an excluded namespace.

[ERR XTSE0808] It is a static error if a namespace prefix is used within the [xsl:]exclude-result-prefixes attribute and there is no namespace binding in scope for that prefix.

The default namespace of the parent element of the [xsl:]exclude-result-prefixes attribute (see Section 6.2 Element Nodes^DM11) may be designated as an excluded namespace by including #default in the list of namespace prefixes.

[ERR XTSE0809] It is a static error if the value #default is used within the [xsl:]exclude-result-prefixes attribute and the parent element of the [xsl:]exclude-result-prefixes attribute has no default namespace.

The value #all indicates that all namespaces that are in scope for the stylesheet element that is the parent of the [xsl:]exclude-result-prefixes attribute are designated as excluded namespaces.

The designation of a namespace as an excluded namespace is effective within the subtree of the stylesheet module rooted at the element bearing the [xsl:]exclude-result-prefixes attribute; a subtree rooted at an xsl:stylesheet element does not include any stylesheet modules imported or included by children of that xsl:stylesheet element.

The excluded namespaces, as described above, only affect namespace nodes copied from the stylesheet when processing a literal result element. There is no guarantee that an excluded namespace will not appear on the result tree for some other reason. Namespace nodes are also written to the result tree as part of the process of namespace fixup (see 5.7.3 Namespace Fixup), or as the result of instructions such as xsl:copy and xsl:element.

Note:

When a stylesheet uses a namespace declaration only for the purposes of addressing a source tree, specifying the prefix in the [xsl:]exclude-result-prefixes attribute will avoid superfluous namespace declarations in the serialized result tree. The attribute is also useful to prevent namespaces used solely for the naming of stylesheet functions or extension functions from appearing in the serialized result tree.

Example: Excluding Namespaces from the Result Tree

For example, consider the following stylesheet:

<xsl:stylesheet xsl: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>

The result of this stylesheet will be:

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

The namespaces a.uri and b.uri are excluded by virtue of the exclude-result-prefixes attribute on the xsl:stylesheet element, and the namespace c.uri is excluded by virtue of the xsl:exclude-result-prefixes attribute on the foo element. The setting #all does not affect the namespace d.uri because d.uri is not an in-scope namespace for the xsl:stylesheet element. The element in the result tree does not have a namespace node corresponding to xmlns:a2="a.uri" because the effect of exclude-result-prefixes is to designate the namespace URI a.uri as an excluded namespace, irrespective of how many prefixes are bound to this namespace URI.

If the stylesheet is changed so that the literal result element has an attribute b:bar="3", then the element in the result tree will typically have a namespace declaration xmlns:b="b.uri" (the processor may choose a different namespace prefix if this is necessary to avoid conflicts). The exclude-result-prefixes attribute makes b.uri an excluded namespace, so the namespace node is not automatically copied from the stylesheet, but the presence of an attribute whose name is in the namespace b.uri forces the namespace fixup process (see 5.7.3 Namespace Fixup) to introduce a namespace node for this namespace.

A literal result element may have an optional xsl:inherit-namespaces attribute, with the value yes or no. The default value is yes. If the value is set to yes, or is omitted, then the namespace nodes created for the newly constructed element are copied to the children and descendants of the newly constructed element, as described in 5.7.1 Constructing Complex Content. If the value is set to no, then these namespace nodes are not automatically copied to the children. This may result in namespace undeclarations (such as xmlns="" or, in the case of XML 1.1, xmlns:p="") appearing on the child elements when a final result tree is serialized.

11.1.4 Namespace Aliasing

When a stylesheet is used to define a transformation whose output is itself a stylesheet module, or in certain other cases where the result document uses namespaces that it would be inconvenient to use in the stylesheet, namespace aliasing can be used to declare a mapping between a namespace URI used in the stylesheet and the corresponding namespace URI to be used in the result document.

[Definition: A namespace URI in the stylesheet tree that is being used to specify a namespace URI in the result tree is called a literal namespace URI.]

[Definition: The namespace URI that is to be used in the result tree as a substitute for a literal namespace URI is called the target namespace URI.]

Either of the literal namespace URI or the target namespace URI can be null: this is treated as a reference to the set of names that are in no namespace.

 <xsl:namespace-alias stylesheet-prefix = prefix | "#default" result-prefix = prefix | "#default" />

[Definition: A stylesheet can use the xsl:namespace-alias element to declare that a literal namespace URI is being used as an alias for a target namespace URI.]

The effect is that when names in the namespace identified by the literal namespace URI are copied to the result tree, the namespace URI in the result tree will be the target namespace URI, instead of the literal namespace URI. This applies to:

the namespace URI in the expanded-QName of a literal result element in the stylesheet
the namespace URI in the expanded-QName of an attribute specified on a literal result element in the stylesheet

Where namespace aliasing changes the namespace URI part of the expanded-QName containing the name of an element or attribute node, the namespace prefix in that expanded-QName is replaced by the prefix indicated by the result-prefix attribute of the xsl:namespace-alias declaration.

The xsl:namespace-alias element declares that the namespace URI bound to the prefix specified by the stylesheet-prefix is the literal namespace URI, and the namespace URI bound to the prefix specified by the result-prefix attribute is the target namespace URI. Thus, the stylesheet-prefix attribute specifies the namespace URI that will appear in the stylesheet, and the result-prefix attribute specifies the corresponding namespace URI that will appear in the result tree.

The default namespace (as declared by xmlns) may be specified by using #default instead of a prefix. If no default namespace is in force, specifying #default denotes the null namespace URI. This allows elements that are in no namespace in the stylesheet to acquire a namespace in the result document, or vice versa.

If a literal namespace URI is declared to be an alias for multiple different target namespace URIs, then the declaration with the highest import precedence is used.

[ERR XTSE0810] It is a static error if there is more than one such declaration with the same literal namespace URI and the same import precedence and different values for the target namespace URI, unless there is also an xsl:namespace-alias declaration with the same literal namespace URI and a higher import precedence.

[ERR XTSE0812] It is a static error if a value other than #default is specified for either the stylesheet-prefix or the result-prefix attributes of the xsl:namespace-alias element when there is no in-scope binding for that namespace prefix.

When a literal result element is processed, its namespace nodes are handled as follows:

A namespace node whose string value is a literal namespace URI is not copied to the result tree.
A namespace node whose string value is a target namespace URI is copied to the result tree, whether or not the URI identifies an excluded namespace.

In the event that the same URI is used as a literal namespace URI and a target namespace URI, the second of these rules takes precedence.

Note:

These rules achieve the effect that the element generated from the literal result element will have an in-scope namespace node that binds the result-prefix to the target namespace URI, provided that the namespace declaration associating this prefix with this URI is in scope for both the xsl:namespace-alias instruction and for the literal result element. Conversely, the stylesheet-prefix and the literal namespace URI will not normally appear in the result tree.

Example: Using xsl:namespace-alias to Generate a Stylesheet

When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet may use an alias.

For example, the stylesheet

<xsl:stylesheet
  version="2.1"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format"
  xmlns:axsl="file://namespace.alias">

<xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/>

<xsl:template match="/">
  <axsl:stylesheet version="2.1">
    <xsl:apply-templates/>
  </axsl:stylesheet>
</xsl:template>

<xsl:template match="elements">
  <axsl:template match="/">
     <axsl:comment select="system-property('xsl:version')"/>
     <axsl:apply-templates/>
  </axsl:template>
</xsl:template>

<xsl:template match="block">
  <axsl:template match="{.}">
     <fo:block><axsl:apply-templates/></fo:block>
  </axsl:template>
</xsl:template>

</xsl:stylesheet>

will generate an XSLT stylesheet from a document of the form:

<elements>
<block>p</block>
<block>h1</block>
<block>h2</block>
<block>h3</block>
<block>h4</block>
</elements>

The output of the transformation will be a stylesheet such as the following. Whitespace has been added for clarity. Note that an implementation may output different namespace prefixes from those appearing in this example; however, the rules guarantee that there will be a namespace node that binds the prefix xsl to the URI http://www.w3.org/1999/XSL/Transform, which makes it safe to use the QName xsl:version in the content of the generated stylesheet.

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

<xsl:template match="/">
  <xsl:comment select="system-property('xsl:version')"/>
  <xsl:apply-templates/>
</xsl:template>
  
<xsl:template match="p">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h1">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h2">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h3">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

<xsl:template match="h4">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

</xsl:stylesheet>

Note:

It may be necessary also to use aliases for namespaces other than the XSLT namespace URI. For example, it can be useful to define an alias for the namespace http://www.w3.org/2001/XMLSchema-instance, so that the stylesheet can use the attributes xsi:type, xsi:nil, and xsi:schemaLocation on a literal result element, without running the risk that a schema processor will interpret these as applying to the stylesheet itself. Equally, literal result elements belonging to a namespace dealing with digital signatures might cause XSLT stylesheets to be mishandled by general-purpose security software; using an alias for the namespace would avoid the possibility of such mishandling.

Example: Aliasing the XML Namespace

It is possible to define an alias for the XML namespace.

<xsl:stylesheet xmlns:axml="http://www.example.com/alias-xml"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version="2.1">

<xsl:namespace-alias stylesheet-prefix="axml" result-prefix="xml"/>

<xsl:template match="/">
  <name axml:space="preserve">
    <first>James</first>
    <xsl:text> </xsl:text>
    <last>Clark</last>
  </name>
</xsl:template>

</xsl:stylesheet>

produces the output:

<name xml:space="preserve"><first>James</first> <last>Clark</last></name>

This allows an xml:space attribute to be generated in the output without affecting the way the stylesheet is parsed. The same technique can be used for other attributes such as xml:lang, xml:base, and xml:id.

Note:

Namespace aliasing is only necessary when literal result elements are used. The problem of reserved namespaces does not arise when using xsl:element and xsl:attribute to construct the result tree. Therefore, as an alternative to using xsl:namespace-alias, it is always possible to achieve the desired effect by replacing literal result elements with xsl:element and xsl:attribute instructions.

11.2 Creating Element Nodes Using `xsl:element`

 <xsl:element name = { qname } namespace? = { uri-reference } inherit-namespaces? = "yes" | "no" use-attribute-sets? = qnames type? = qname validation? = "strict" | "lax" | "preserve" | "strip" >  </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 required name attribute and an optional namespace attribute.

The content of the xsl:element instruction is a sequence constructor for the children, attributes, and namespaces of the created element. The sequence obtained by evaluating this sequence constructor (see 5.7 Sequence Constructors) is used to construct the content of the element, as described in 5.7.1 Constructing Complex Content.

The xsl:element element may have a use-attribute-sets attribute, whose value is a whitespace-separated list of QNames that identify xsl:attribute-set declarations. If this attribute is present, it is expanded as described in 10.2 Named Attribute Sets to produce a sequence of attribute nodes. This sequence is prepended to the sequence produced as a result of evaluating the sequence constructor, as described in 5.7.1 Constructing Complex Content.

The result of evaluating the xsl:element instruction, except in error cases, is the newly constructed element node.

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

[ERR XTDE0820] It is a non-recoverable dynamic error if the effective value of the name attribute is not a lexical QName.

[ERR XTDE0830] In the case of an xsl:element instruction with no namespace attribute, it is a non-recoverable dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:element instruction.

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

If the namespace attribute is present, then it too is interpreted as an attribute value template. The effective value must be in the lexical space of the xs:anyURI type. If the string is zero-length, then the expanded-QName of the element has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded-QName of the element 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 element to be created.

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

Note:

The XDM data model requires the name of a node to be an instance of xs:QName, and XML Schema defines the namespace part of an xs:QName to be an instance of xs:anyURI. However, the schema specification, and the specifications that it refers to, give implementations some flexibility in how strictly they enforce these constraints.

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 element node. In the event of a conflict a prefix may subsequently be added, changed, or removed during the namespace fixup process (see 5.7.3 Namespace Fixup). The term conflict here means any violation of the constraints defined in [Data Model], 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.

The xsl:element instruction has an optional inherit-namespaces attribute, with the value yes or no. The default value is yes. If the value is set to yes, or is omitted, then the namespace nodes created for the newly constructed element (whether these were copied from those of the source node, or generated as a result of namespace fixup) are copied to the children and descendants of the newly constructed element, as described in 5.7.1 Constructing Complex Content. If the value is set to no, then these namespace nodes are not automatically copied to the children. This may result in namespace undeclarations (such as xmlns="" or, in the case of XML Namespaces 1.1, xmlns:p="") appearing on the child elements when a final result tree is serialized.

The base URI of the new element is copied from the base URI of the xsl:element instruction 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) against the base URI of the xsl:element instruction in the stylesheet. (Note, however, that this is only relevant when creating parentless elements. When the new 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.)

11.2.1 Setting the Type Annotation for a Constructed Element Node

The optional attributes type and validation may be used on the xsl:element instruction to invoke validation of the contents of the element against a type definition or element declaration in a schema, and to determine the type annotation that the new element node will carry. These attributes also affect the type annotation carried by any elements and attributes that have the new element node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 22.2 Validation.

Note:

The final type annotation of the element in the result tree also depends on the type and validation attributes of the instructions used to create the ancestors of the element.

11.3 Creating Attribute Nodes Using `xsl:attribute`

 <xsl:attribute name = { qname } namespace? = { uri-reference } select? = expression separator? = { string } type? = qname validation? = "strict" | "lax" | "preserve" | "strip" >  </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 required name 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 neither is present, the value of the new attribute node will be a zero-length string. The way in which the value is constructed is specified in 5.7.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.7.2 Constructing Simple Content. In the absence of this attribute, the default separator is a single space (#x20) 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 value must be a lexical QName.

[ERR XTDE0850] It is a non-recoverable 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 non-recoverable 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 non-recoverable dynamic error if the effective value of the name attribute is a lexical QName whose prefix is not declared in an in-scope namespace declaration 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 value must 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 non-recoverable dynamic error if the effective value of the namespace attribute is not in the lexical space of the xs:anyURI data type or if it is the string http://www.w3.org/2000/xmlns/.

Note:

The same considerations apply as for elements: [see ERR XTDE0835] in 11.2 Creating Element Nodes Using xsl:element .

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.7.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 [Data Model], 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^FO 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.

Note:

The effect of setting the is-id property is that the parent element can be located within the containing document by use of the id^FO function. In effect, XSLT when constructing a document performs some of the functions of an xml:id processor, as defined in [xml:id]; the other aspects of xml:id processing are performed during validation.

Example: Creating a List-Valued Attribute

The following instruction creates the attribute colors="red green blue":

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

Example: Namespaces are not Attributes

It is not an error to write:

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

However, this will not result in the namespace declaration xmlns:xsl="http://www.w3.org/1999/XSL/Transform" being output. Instead, it will produce an attribute node with local name xsl, and with a system-allocated namespace prefix mapped to the namespace URI file://some.namespace. This is because the namespace fixup process is not allowed to use xmlns as the name of a namespace node.

As described in 5.7.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.

Note:

If a collection of attributes is generated repeatedly, this can be done conveniently by using named attribute sets: see 10.2 Named Attribute Sets

11.3.1 Setting the Type Annotation for a Constructed Attribute Node

The optional attributes type and validation may be used on the xsl:attribute instruction to invoke validation of the contents of the attribute against a type definition or attribute declaration in a schema, and to determine the type annotation that the new attribute node will carry. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 22.2 Validation.

Note:

The final type annotation of the attribute in the result tree also depends on the type and validation attributes of the instructions used to create the ancestors of the attribute.

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.7.2 Constructing Simple Content and 5.7.1 Constructing Complex Content, adjacent text nodes in the sequence are merged. Within the sequence itself, however, they exist as distinct nodes.

Example: A sequence of text nodes

The following function returns a sequence of three text 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>

When this function is called as follows:

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

the result is:

(---)

No additional spaces are inserted, because the calling xsl:value-of instruction merges adjacent text nodes before atomizing the sequence. However, the result of the instruction:

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

is:

( --- )

because in this case the three text nodes are atomized to form three strings, and spaces are inserted between adjacent strings.

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.7.1 Constructing Complex Content and 5.7.2 Constructing Simple Content.

11.4.1 Literal Text Nodes

A sequence constructor can contain text nodes. Each text node in a sequence constructor remaining after whitespace text nodes have been stripped as specified in 4.2 Stripping Whitespace from the Stylesheet will construct a new text node with the same string value. The resulting text node is added to the result of the containing sequence constructor.

Text is processed at the tree level. Thus, markup of < in a template will be represented in the stylesheet tree by a text node that includes the character <. This will create a text node in the result tree that contains a < character, which will be represented by the markup < (or an equivalent character reference) when the result tree is serialized as an XML document, unless otherwise specified using character maps (see 23.1 Character Maps) or disable-output-escaping (see 23.2 Disabling Output Escaping).

11.4.2 Creating Text Nodes Using `xsl:text`

 <xsl:text [disable-output-escaping]? = "yes" | "no" >  </xsl:text>

The xsl:text element is evaluated to construct a new text node. The content of the xsl:text element is a single text node whose value forms the string value of the new text node. An xsl:text element may be empty, in which case the result of evaluating the instruction is a text node whose string value is the zero-length string.

The result of evaluating an xsl:text instruction is the newly constructed text node.

A text node that is an immediate child of an xsl:text instruction will not be stripped from the stylesheet tree, even if it consists entirely of whitespace (see 4.4 Stripping Whitespace from a Source Tree).

For the effect of the deprecated disable-output-escaping attribute, see 23.2 Disabling Output Escaping

Note:

It is not always necessary to use the xsl:text instruction to write text nodes to the result tree. Literal text can be written to the result tree by including it anywhere in a sequence constructor, while computed text can be output using the xsl:value-of instruction. The principal reason for using xsl:text is that it offers improved control over whitespace handling.

11.4.3 Generating Text with `xsl:value-of`

Within a sequence constructor, the xsl:value-of instruction can be used to generate computed text nodes. The xsl:value-of instruction computes the text using an expression that is specified as the value of the select attribute, or by means of contained instructions. This might, for example, extract text from a source tree or insert the value of a variable.

 <xsl:value-of select? = expression separator? = { string } [disable-output-escaping]? = "yes" | "no" >  </xsl:value-of>

The xsl:value-of instruction is evaluated to construct a new text node; the result of the instruction is the newly constructed text node.

The string value of the new text node may be defined either by using the select attribute, or by the sequence constructor (see 5.7 Sequence Constructors) that forms the content of the xsl:value-of element. These are mutually exclusive, and one of them must be present. The way in which the value is constructed is specified in 5.7.2 Constructing Simple Content.

[ERR XTSE0870] It is a static error if the select attribute of the xsl:value-of element is present when the content of the element is non-empty, or if the select attribute is absent when the content is empty.

Special rules apply when the instruction is processed with XSLT 1.0 behavior. If no separator attribute is present, and if the select attribute is present, then all items in the atomized result sequence other than the first are ignored.

Example: Generating a List with Separators

The instruction:

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

produces the output:

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

Note:

The xsl:copy-of element can be used to copy a sequence of nodes to the result tree without atomization. See 11.9.2 Deep Copy.

For the effect of the deprecated disable-output-escaping attribute, see 23.2 Disabling Output Escaping

11.5 Creating Document Nodes

 <xsl:document validation? = "strict" | "lax" | "preserve" | "strip" type? = qname >  </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.7.1 Constructing Complex Content. The temporary tree rooted at this document node forms the result tree.

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

Note:

The new document is not serialized. To construct a document that is to form a final result rather than an intermediate result, use the xsl:result-document instruction described in 22.1 Creating Final Result Trees.

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

Example: Checking Uniqueness Constraints in a Temporary Tree

The following example creates a temporary tree held in a variable. The use of an enclosed xsl:document instruction ensures that uniqueness constraints defined in the schema for the relevant elements are checked.

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

11.6 Creating Processing Instructions

 <xsl:processing-instruction name = { ncname } select? = expression >  </xsl:processing-instruction>

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

The xsl:processing-instruction element has a required name 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 neither is present, 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.7.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.

Example: Creating a Processing Instruction

This instruction:

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

creates the processing instruction

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

Note that the xml-stylesheet processing instruction contains pseudo-attributes in the form name="value". Although these have the same textual form as attributes in an element start tag, they are not represented as XDM attribute nodes, and cannot therefore be constructed using xsl:attribute instructions.

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

Note:

Because these rules disallow the name xml, the xsl:processing-instruction cannot be used to output an XML declaration. The xsl:output declaration should be used to control this instead (see 23 Serialization).

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.7 Creating Namespace Nodes

 <xsl:namespace name = { ncname } select? = expression >  </xsl:namespace>

The xsl:namespace element is evaluated to create a namespace node. Except in error situations, the result of evaluating the xsl:namespace instruction is a single node, the newly constructed namespace node.

The xsl:namespace element has a required name attribute that specifies the name of the namespace node (that is, the namespace prefix). The value of the name attribute is interpreted as an attribute value template. If the effective value of the name attribute is a zero-length string, a namespace node is added for the default namespace.

The string value of the new namespace node (that is, the namespace URI) may be defined either by using the select attribute, or by the sequence constructor that forms the content of the xsl:namespace element. These are mutually exclusive. Since the string value of a namespace node cannot be a zero-length string, one of them must be present. The way in which the value is constructed is specified in 5.7.2 Constructing Simple Content.

[ERR XTDE0905] It is a non-recoverable dynamic error if the string value of the new namespace node is not valid in the lexical space of the data type xs:anyURI, or if it is the string http://www.w3.org/2000/xmlns/.

[ERR XTSE0910] It is a static error if the select attribute of the xsl:namespace element is present when the element has content other than one or more xsl:fallback instructions, or if the select attribute is absent when the element has empty content.

Note the restrictions described in 5.7.1 Constructing Complex Content for the position of a namespace node relative to other nodes in the node sequence returned by a sequence constructor.

Example: Constructing a QName-Valued Attribute

This literal result element:

<data xsi:type="xs:integer" 
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <xsl:namespace name="xs" 
                 select="'http://www.w3.org/2001/XMLSchema'"/>
  <xsl:text>42</xsl:text>
</data>

would typically cause the output document to contain the element:

<data xsi:type="xs:integer"
     xmlns:xs="http://www.w3.org/2001/XMLSchema"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">42</data>

In this case, the element is constructed using a literal result element, and the namespace xmlns:xs="http://www.w3.org/2001/XMLSchema" could therefore have been added to the result tree simply by declaring it as one of the in-scope namespaces in the stylesheet. In practice, the xsl:namespace instruction is more likely to be useful in situations where the element is constructed using an xsl:element instruction, which does not copy all the in-scope namespaces from the stylesheet.

[ERR XTDE0920] It is a non-recoverable dynamic error if the effective value of the name attribute is neither a zero-length string nor an NCName^Names, or if it is xmlns.

[ERR XTDE0925] It is a non-recoverable dynamic error if the xsl:namespace instruction generates a namespace node whose name is xml and whose string value is not http://www.w3.org/XML/1998/namespace, or a namespace node whose string value is http://www.w3.org/XML/1998/namespace and whose name is not xml.

[ERR XTDE0930] It is a non-recoverable dynamic error if evaluating the select attribute or the contained sequence constructor of an xsl:namespace instruction results in a zero-length string.

For details of other error conditions that may arise, see 5.7 Sequence Constructors.

Note:

It is rarely necessary to use xsl:namespace to create a namespace node in the result tree; in most circumstances, the required namespace nodes will be created automatically, as a side-effect of writing elements or attributes that use the namespace. An example where xsl:namespace is needed is a situation where the required namespace is used only within attribute values in the result document, not in element or attribute names; especially where the required namespace prefix or namespace URI is computed at run-time and is not present in either the source document or the stylesheet.

Adding a namespace node to the result tree will never change the expanded-QName of any element or attribute node in the result tree: that is, it will never change the namespace URI of an element or attribute. It might, however, constrain the choice of prefixes when namespace fixup is performed.

Namespace prefixes for element and attribute names are initially established by the rules of the instruction that creates the element or attribute node, and in the event of conflicts, they may be changed by the namespace fixup process described in 5.7.3 Namespace Fixup. The fixup process ensures that an element has in-scope namespace nodes for the namespace URIs used in the element name and in its attribute names, and the serializer will typically use these namespace nodes to determine the prefix to use in the serialized output. The fixup process cannot generate namespace nodes that are inconsistent with those already present in the tree. This means that it is not possible for the processor to decide the prefix to use for an element or for any of its attributes until all the namespace nodes for the element have been added.

If a namespace prefix is mapped to a particular namespace URI using the xsl:namespace instruction, or by using xsl:copy or xsl:copy-of to copy a namespace node, this prevents the namespace fixup process (and hence the serializer) from using the same prefix for a different namespace URI on the same element.

Example: Conflicting Namespace Prefixes

Given the instruction:

<xsl:element name="p:item" 
                 xmlns:p="http://www.example.com/p">
  <xsl:namespace name="p">http://www.example.com/q</xsl:namespace>
</xsl:element>

a possible serialization of the result tree is:

<ns0:item 
    xmlns:ns0="http://www.example.com/p" 
    xmlns:p="http://www.example.com/q"/>

The processor must invent a namespace prefix for the URI p.uri; it cannot use the prefix p because that prefix has been explicitly associated with a different URI.

Note:

The xsl:namespace instruction cannot be used to generate a namespace undeclaration of the form xmlns="" (nor the new forms of namespace undeclaration permitted in [Namespaces in XML 1.1]). Namespace undeclarations are generated automatically by the serializer if undeclare-prefixes="yes" is specified on xsl:output, whenever a parent element has a namespace node for the default namespace prefix, and a child element has no namespace node for that prefix.

11.8 Creating Comments

 <xsl:comment select? = expression >  </xsl:comment>

The xsl:comment element is evaluated to construct a new comment node. Except in error cases, the result of evaluating the xsl:comment instruction is a single node, the newly constructed comment node.

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

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

Example: Generating a Comment Node

For example, this

<xsl:comment>This file is automatically generated. Do not edit!</xsl:comment>

would create the comment

<!--This file is automatically generated. Do not edit!-->

In the generated comment node, the processor must insert a space after any occurrence of - that is followed by another - or that ends the comment.

11.9 Copying Nodes

11.9.1 Shallow Copy

 <xsl:copy select? = expression copy-namespaces? = "yes" | "no" inherit-namespaces? = "yes" | "no" use-attribute-sets? = qnames type? = qname validation? = "strict" | "lax" | "preserve" | "strip" >  </xsl:copy>

The xsl:copy instruction provides a way of copying a selected item. The selected item is the item selected by evaluating the expression in the select attribute if present, or the context item otherwise. If the selected item is a node, evaluating the xsl:copy instruction constructs a copy of the selected node, and the result of the xsl:copy instruction is this newly constructed node. By default, the namespace nodes of the context node are automatically copied as well, but the attributes and children of the node are not automatically copied.

When the selected item is an atomic value or function item, the xsl:copy instruction returns this value. The sequence constructor, if present, is not evaluated, and must not generate any type errors.

When the selected item is an attribute node, text node, comment node, processing instruction node, or namespace node, the xsl:copy instruction returns a new node that is a copy of the context node. The new node will have the same node kind, name, and string value as the context node. In the case of an attribute node, it will also have the same values for the is-id and is-idrefs properties. The sequence constructor, if present, is not evaluated, and must not generate any type errors..

When the selected item is a document node or element node, the xsl:copy instruction returns a new node that has the same node kind and name as the selected node. The content of the new node is formed by evaluating the sequence constructor contained in the xsl:copy instruction. The sequence obtained by evaluating this sequence constructor is used (after prepending any attribute nodes or namespace nodes as described in the following paragraphs) to construct the content of the document or element node, as described in 5.7.1 Constructing Complex Content.

If the select expression returns an empty sequence, the xsl:copy instruction returns an empty sequence, and the contained sequence constructor is not evaluated.

[ERR XTTE2170] It is a type error if the result of evaluating the select expression is a sequence of more than one item.

Note:

The xsl:copy instruction is most useful when copying element nodes. In other cases, the xsl:copy-of instruction is more flexible, because it has a select attribute allowing selection of the nodes or values to be copied.

The xsl:copy instruction has an optional use-attribute-sets attribute, whose value is a whitespace-separated list of QNames that identify xsl:attribute-set declarations. This attribute is used only when copying element nodes. This list is expanded as described in 10.2 Named Attribute Sets to produce a sequence of attribute nodes. This sequence is prepended to the sequence produced as a result of evaluating the sequence constructor.

The xsl:copy instruction has an optional copy-namespaces attribute, with the value yes or no. The default value is yes. The attribute is used only when copying element nodes. If the value is set to yes, or is omitted, then all the namespace nodes of the source element are copied as namespace nodes for the result element. These copied namespace nodes are prepended to the sequence produced as a result of evaluating the sequence constructor (it is immaterial whether they come before or after any attribute nodes produced by expanding the use-attribute-sets attribute). If the value is set to no, then the namespace nodes are not copied. However, namespace nodes will still be added to the result element as required by the namespace fixup process: see 5.7.3 Namespace Fixup.

The xsl:copy instruction has an optional inherit-namespaces attribute, with the value yes or no. The default value is yes. The attribute is used only when copying element nodes. If the value is set to yes, or is omitted, then the namespace nodes created for the newly constructed element (whether these were copied from those of the source node, or generated as a result of namespace fixup) are copied to the children and descendants of the newly constructed element, as described in 5.7.1 Constructing Complex Content. If the value is set to no, then these namespace nodes are not automatically copied to the children. This may result in namespace undeclarations (such as xmlns="" or, in the case of XML Namespaces 1.1, xmlns:p="") appearing on the child elements when a final result tree is serialized.

[ERR XTTE0950] It is a type error to use the xsl:copy or xsl:copy-of instruction to copy a node that has namespace-sensitive content if the copy-namespaces attribute has the value no and its explicit or implicit validation attribute has the value preserve. It is also a type error if either of these instructions (with validation="preserve") is used to copy an attribute having namespace-sensitive content, unless the parent element is also copied. A node has namespace-sensitive content if its typed value contains an item of type xs:QName or xs:NOTATION or a type derived therefrom. The reason this is an error is because the validity of the content depends on the namespace context being preserved.

Note:

When attribute nodes are copied, whether with xsl:copy or with xsl:copy-of, the processor does not automatically copy any associated namespace information. The namespace used in the attribute name itself will be declared by virtue of the namespace fixup process (see 5.7.3 Namespace Fixup) when the attribute is added to an element in the result tree, but if namespace prefixes are used in the content of the attribute (for example, if the value of the attribute is an XPath expression) then it is the responsibility of the stylesheet author to ensure that suitable namespace nodes are added to the result tree. This can be achieved by copying the namespace nodes using xsl:copy, or by generating them using xsl:namespace.

The optional attributes type and validation may be used on the xsl:copy instruction to validate the contents of an element, attribute or document node against a type definition, element declaration, or attribute declaration in a schema, and thus to determine the type annotation that the new copy of an element or attribute node will carry. These attributes are ignored when copying an item that is not an element, attribute or document node. When the node being copied is an element or document node, these attributes also affect the type annotation carried by any elements and attributes that have the copied element or document node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 22.2 Validation.

Note:

The final type annotation of the node in the result tree also depends on the type and validation attributes of the instructions used to create the ancestors of the node.

The base URI of a node is copied, except in the case of an element node having an xml:base attribute, in which case the base URI of the new node is taken as the value of the xml:base attribute, resolved if it is relative against the base URI of the xsl:copy instruction. If the copied node is subsequently attached as a child to a new element or document node, the final copy of the node inherits its base URI from its parent node, unless this is overridden using an xml:base attribute.

When an xml:id attribute is copied, using either the xsl:copy or xsl:copy-of instruction, it is implementation-defined whether the value of the attribute is subjected to attribute value normalization (that is, effectively applying the normalize-space^FO function).

Note:

In most cases the value will already have been subjected to attribute value normalization on the source tree, but if this processing has not been performed on the source tree, it is not an error for it to be performed on the result tree.

Issue 14 (context-in-shallow-copy):

Should the contained sequence constructor be evaluated with the selected node as the context item? Use cases such as use in xsl:function probably would suggest yes.

11.9.2 Deep Copy

 <xsl:copy-of select = expression copy-namespaces? = "yes" | "no" type? = qname validation? = "strict" | "lax" | "preserve" | "strip" />

The xsl:copy-of instruction can be used to construct a copy of a sequence of nodes, atomic values, and/or function items with each new node containing copies of all the children, attributes, and (by default) namespaces of the original node, recursively. The result of evaluating the instruction is a sequence of items corresponding one-to-one with the supplied sequence, and retaining its order.

The required select attribute contains an expression, whose value may be any sequence of nodes, atomic values, and/or function items. The items in this sequence are processed as follows:

If the item is an element node, a new element is constructed and appended to the result sequence. The new element will have the same expanded-QName as the original, and it will have deep copies of the attribute nodes and children of the element node.

The new element will also have namespace nodes copied from the original element node, unless they are excluded by specifying copy-namespaces="no". If this attribute is omitted, or takes the value yes, then all the namespace nodes of the original element are copied to the new element. If it takes the value no, then none of the namespace nodes are copied: however, namespace nodes will still be created in the result tree as required by the namespace fixup process: see 5.7.3 Namespace Fixup. This attribute affects all elements copied by this instruction: both elements selected directly by the select expression, and elements that are descendants of nodes selected by the select expression.

The new element will have the same values of the is-id, is-idrefs, and nilled properties as the original element.
If the item is a document node, the instruction adds a new document node to the result sequence; the children of this document node will be one-to-one copies of the children of the original document node (each copied according to the rules for its own node kind).
If the item is an attribute or namespace node, or a text node, a comment, or a processing instruction, the same rules apply as with xsl:copy (see 11.9.1 Shallow Copy).
If the item is an atomic value or a function item, the value is appended to the result sequence, as with xsl:sequence.

The optional attributes type and validation may be used on the xsl:copy-of instruction to validate the contents of an element, attribute or document node against a type definition, element declaration, or attribute declaration in a schema and thus to determine the type annotation that the new copy of an element or attribute node will carry. These attributes are applied individually to each element, attribute, and document node that is selected by the expression in the select attribute. These attributes are ignored when copying an item that is not an element, attribute or document node.

The specified type and validation apply directly only to elements, attributes and document nodes created as copies of nodes actually selected by the select expression, they do not apply to nodes that are implicitly copied because they have selected nodes as an ancestor. However, these attributes do indirectly affect the type annotation carried by such implicitly copied nodes, as a consequence of the validation process.

These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their semantics are described in 22.2 Validation.

Errors may occur when copying namespace-sensitive elements or attributes using validation="preserve". [see ERR XTTE0950].

The base URI of a node is copied, except in the case of an element node having an xml:base attribute, in which case the base URI of the new node is taken as the value of the xml:base attribute, resolved if it is relative against the base URI of the xsl:copy-of instruction. If the copied node is subsequently attached as a child to a new element or document node, the final copy of the node inherits its base URI from its parent node, unless this is overridden using an xml:base attribute.

11.10 Constructing Sequences

 <xsl:sequence select = expression >  </xsl:sequence>

The xsl:sequence instruction may be used within a sequence constructor to construct a sequence of nodes, atomic values, and/or function items. This sequence is returned as the result of the instruction. Unlike most other instructions, xsl:sequence can return a sequence containing existing nodes, rather than constructing new nodes. When xsl:sequence is used to add atomic values or function items to a sequence, the effect is very similar to the xsl:copy-of instruction.

The items comprising the result sequence are evaluated either using the select attribute, or using the contained sequence constructor. These are mutually exclusive; if the instruction has a select attribute, then it must have no children other than xsl:fallback instructions. If there is no select attribute and no contained sequence constructor, the result is an empty sequence.

Any contained xsl:fallback instructions are ignored by an XSLT 2.0 or 2.1 processor, but can be used to define fallback behavior for an XSLT 1.0 processor running in forwards compatibility mode.

Example: Constructing a Sequence of Integers

For example, the following code:

<xsl:variable name="values" as="xs:integer*">
    <xsl:sequence select="(1,2,3,4)"/>
    <xsl:sequence select="(8,9,10)"/>
</xsl:variable>
<xsl:value-of select="sum($values)"/>

produces the output: 37

Example: Using xsl:for-each to Construct a Sequence

The following code constructs a sequence containing the value of the @price attribute for selected elements (which we assume to be typed as xs:decimal), or a computed price for those elements that have no @price attribute. It then returns the average price:

<xsl:variable name="prices" as="xs:decimal*">
  <xsl:for-each select="//product">
    <xsl:choose>
      <xsl:when test="@price">
        <xsl:sequence select="@price"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:sequence select="@cost * 1.5"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:for-each>
</xsl:variable>
<xsl:value-of select="avg($prices)"/>

Note that the existing @price attributes could equally have been added to the $prices sequence using xsl:copy-of or xsl:value-of. However, xsl:copy-of would create a copy of the attribute node, which is not needed in this situation, while xsl:value-of would create a new text node, which then has to be converted to an xs:decimal. Using xsl:sequence, which in this case atomizes the existing attribute node and adds an xs:decimal atomic value to the result sequence, is a more direct way of achieving the same result.

This example could alternatively be solved at the XPath level:

<xsl:value-of select="avg(//product/(+@price, @cost*1.5)[1])"/>

The apparently redundant + operator is there to atomize the attribute value: the expression on the right hand side of the / operator must not return a sequence containing both nodes and non-nodes (atomic values or function items).

Note:

The main use case for allowing xsl:sequence to contain a sequence constructor is to allow the instructions within an xsl:fork element to be divided into groups.

12 Numbering

 <xsl:number value? = expression select? = expression level? = "single" | "multiple" | "any" count? = pattern from? = pattern format? = { string } lang? = { nmtoken } letter-value? = { "alphabetic" | "traditional" } ordinal? = { string } grouping-separator? = { char } grouping-size? = { number } />

The xsl:number instruction is used to create a formatted number. The result of the instruction is a newly constructed text node containing the formatted number as its string value.

[Definition: The xsl:number instruction performs two tasks: firstly, determining a place marker (this is a sequence of integers, to allow for hierarchic numbering schemes such as 1.12.2 or 3(c)ii), and secondly, formatting the place marker for output as a text node in the result sequence.] The place marker to be formatted can either be supplied directly, in the value attribute, or it can be computed based on the position of a selected node within the tree that contains it.

[ERR XTSE0975] It is a static error if the value attribute of xsl:number is present unless the select, level, count, and from attributes are all absent.

Note:

The facilities described in this section are specifically designed to enable the calculation and formatting of section numbers, paragraph numbers, and the like. For formatting of other numeric quantities, the format-number^FO function may be more suitable: see Section 4.6.2 ^FO11.

Furthermore, formatting of integers where there is no requirement to calculate the position of a node in the document can now be accomplished using the format-number^FO function, which borrows many concepts from the xsl:number specification.

Note:

See 18.4.2.1 Expanding the xsl:number instruction for analysis of the effect of the xsl:number instruction on streamability.

12.1 Formatting a Supplied Number

The place marker to be formatted may be specified by an expression. The value attribute contains the expression. The value of this expression is atomized using the procedure defined in [XPath 2.1], and each value $V in the atomized sequence is then converted to the integer value returned by the XPath expression xs:integer(round(number($V))). The resulting sequence of integers is used as the place marker to be formatted.

If the instruction is processed with XSLT 1.0 behavior, then:

all items in the atomized sequence after the first are discarded;
If the atomized sequence is empty, it is replaced by a sequence containing the xs:double value NaN as its only item;
If any value in the sequence cannot be converted to an integer (this includes the case where the sequence contains a NaN value) then the string NaN is inserted into the formatted result string in its proper position. The error described in the following paragraph does not apply in this case.

[ERR XTDE0980] It is a non-recoverable dynamic error if any undiscarded item in the atomized sequence supplied as the value of the value attribute of xsl:number cannot be converted to an integer, or if the resulting integer is less than 0 (zero).

Note:

The value zero does not arise when numbering nodes in a source document, but it can arise in other numbering sequences. It is permitted specifically because the rules of the xsl:number instruction are also invoked by functions such as format-time^FO: the minutes and seconds component of a time value can legitimately be zero.

The resulting sequence is formatted as a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the xsl:number element constructs a new text node containing the resulting string, and returns this node.

Example: Numbering a Sorted List

The following example numbers a sorted list:

<xsl:template match="items">
  <xsl:for-each select="item">
    <xsl:sort select="."/>
    <p>
      <xsl:number value="position()" format="1. "/>
      <xsl:value-of select="."/>
    </p>
  </xsl:for-each>
</xsl:template>

12.2 Numbering based on Position in a Document

If no value attribute is specified, then the xsl:number instruction returns a new text node containing a formatted place marker that is based on the position of a selected node within its containing document. If the select attribute is present, then the expression contained in the select attribute is evaluated to determine the selected node. If the select attribute is omitted, then the selected node is the context node.

[ERR XTTE0990] It is a type error if the xsl:number instruction is evaluated, with no value or select attribute, when the context item is not a node.

[ERR XTTE1000] It is a type error if the result of evaluating the select attribute of the xsl:number instruction is anything other than a single node.

The following attributes control how the selected node is to be numbered:

The level attribute specifies rules for selecting the nodes that are taken into account in allocating a number; it has the values single, multiple or any. The default is single.
The count attribute is a pattern that specifies which nodes are to be counted at those levels. If count attribute is not specified, then it defaults to the pattern that matches any node with the same node kind as the selected node and, if the selected node has an expanded-QName, with the same expanded-QName as the selected node.
The from attribute is a pattern that specifies where counting starts.

In addition, the attributes specified in 12.3 Number to String Conversion Attributes are used for number to string conversion, as in the case when the value attribute is specified.

The xsl:number element first constructs a sequence of positive integers using the level, count and from attributes. Where level is single or any, this sequence will either be empty or contain a single number; where level is multiple, the sequence may be of any length. The sequence is constructed as follows:

Let matches-count($node) be a function that returns true if and only if the given node $node matches the pattern given in the count attribute, or the implied pattern (according to the rules given above) if the count attribute is omitted.

Let matches-from($node) be a function that returns true if and only if the given node $node matches the pattern given in the from attribute, or if $node is the root node of a tree. If the from attribute is omitted, then the function returns true if and only if $node is the root node of a tree.

Let $S be the selected node.

When level="single":

Let $A be the node sequence selected by the following expression:

$S/ancestor-or-self::node()[matches-count(.)][1]

(this selects the innermost ancestor-or-self node that matches the count pattern)
Let $F be the node sequence selected by the expression

$S/ancestor-or-self::node()[matches-from(.)][1]

(this selects the innermost ancestor-or-self node that matches the from pattern):
Let $AF be the value of:

$A[ancestor-or-self::node()[. is $F]]

(this selects $A if it is in the subtree rooted at $F, or the empty sequence otherwise)
If $AF is empty, return the empty sequence, ()
Otherwise return the value of:

1 + count($AF/preceding-sibling::node()[matches-count(.)])

(the number of preceding siblings of the counted node that match the count pattern, plus one).

When level="multiple":

Let $A be the node sequence selected by the expression

$S/ancestor-or-self::node()[matches-count(.)]

(the set of ancestor-or-self nodes that match the count pattern)
Let $F be the node sequence selected by the expression

$S/ancestor-or-self::node()[matches-from(.)][1]

(the innermost ancestor-or-self node that matches the from pattern)
Let $AF be the value of

$A[ancestor-or-self::node()[. is $F]]

(the nodes selected in the first step that are in the subtree rooted at the node selected in the second step)
Return the result of the expression

for $af in $AF return 1+count($af/preceding-sibling::node()[matches-count(.)])

(a sequence of integers containing, for each of these nodes, one plus the number of preceding siblings that match the count pattern)

When level="any":

Let $A be the node sequence selected by the expression

$S/(preceding::node()|ancestor-or-self::node())[matches-count(.)]

(the set of nodes consisting of the selected node together with all nodes, other than attributes and namespaces, that precede the selected node in document order, provided that they match the count pattern)
Let $F be the node sequence selected by the expression

$S/(preceding::node()|ancestor::node())[matches-from(.)][last()]

(the last node in document order that matches the from pattern and that precedes the selected node, using the same definition)
Let $AF be the node sequence $A[. is $F or . >> $F].

(the nodes selected in the first step, excluding those that precede the node selected in the second step)
If $AF is empty, return the empty sequence, ()
Otherwise return the value of the expression count($AF)

The sequence of numbers (the place marker) is then converted into a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is used to create a text node, which forms the result of the xsl:number instruction.

Example: Numbering the Items in an Ordered List

The following will number the items in an ordered list:

<xsl:template match="ol/item">
  <fo:block>
    <xsl:number/>
    <xsl:text>. </xsl:text>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

Example: Multi-Level Numbering

The following two rules will number title elements. This is intended for a document that contains a sequence of chapters followed by a sequence of appendices, where both chapters and appendices contain sections, which in turn contain subsections. Chapters are numbered 1, 2, 3; appendices are numbered A, B, C; sections in chapters are numbered 1.1, 1.2, 1.3; sections in appendices are numbered A.1, A.2, A.3. Subsections within a chapter are numbered 1.1.1, 1.1.2, 1.1.3; subsections within an appendix are numbered A.1.1, A.1.2, A.1.3.

<xsl:template match="title">
  <fo:block>
     <xsl:number level="multiple"
                 count="chapter|section|subsection"
                 format="1.1 "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="appendix//title" priority="1">
  <fo:block>
     <xsl:number level="multiple"
                 count="appendix|section|subsection"
                 format="A.1 "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

Example: Numbering Notes within a Chapter

This example numbers notes sequentially within a chapter:

<xsl:template match="note">
  <fo:block>
     <xsl:number level="any" from="chapter" format="(1) "/>
     <xsl:apply-templates/>
  </fo:block>
</xsl:template>

12.3 Number to String Conversion Attributes

Issue 15 (refactor-format-integer):

The functionality described here has been encapsulated in a new function, format-integer^FO. The specification can be simplified by referring to the specification of that function.

The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than or equal to 0 (zero). The attributes are all optional.

The main attribute is format. The default value for the format attribute is 1. The format attribute is split into a sequence of tokens where each token is a maximal sequence of alphanumeric characters or a maximal sequence of non-alphanumeric characters. Alphanumeric means any character that has a Unicode category of Nd, Nl, No, Lu, Ll, Lt, Lm or Lo. The alphanumeric tokens (format tokens) indicate the format to be used for each number in the sequence; in most cases the format token is the same as the required representation of the number 1 (one).

Each non-alphanumeric token is either a prefix, a separator, or a suffix. If there is a non-alphanumeric token but no format token, then the single non-alphanumeric token is used as both the prefix and the suffix. The prefix, if it exists, is the non-alphanumeric token that precedes the first format token: the prefix always appears exactly once in the constructed string, at the start. The suffix, if it exists, is the non-alphanumeric token that follows the last format token: the suffix always appears exactly once in the constructed string, at the end. All other non-alphanumeric tokens (those that occur between two format tokens) are separator tokens and are used to separate numbers in the sequence.

The nth format token is used to format the nth number in the sequence. If there are more numbers than format tokens, then the last format token is used to format remaining numbers. If there are no format tokens, then a format token of 1 is used to format all numbers. Each number after the first is separated from the preceding number by the separator token preceding the format token used to format that number, or, if that is the first format token, then by . (dot).

Example: Formatting a List of Numbers

Given the sequence of numbers 5, 13, 7 and the format token A-001(i), the output will be the string E-013(vii)

Format tokens are interpreted as follows:

Any token where the last character has a decimal digit value of 1 (as specified in the Unicode character property database), and the Unicode value of preceding characters is one less than the Unicode value of the last character generates a decimal representation of the number where each number is at least as long as the format token. The digits used in the decimal representation are the set of digits containing the digit character used in the format token. Thus, a format token 1 generates the sequence 0 1 2 ... 10 11 12 ..., and a format token 01 generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101. A format token of ١ (Arabic-Indic digit one) generates the sequence ١ then ٢ then ٣ ...
A format token A generates the sequence A B C ... Z AA AB AC....
A format token a generates the sequence a b c ... z aa ab ac....
A format token i generates the sequence i ii iii iv v vi vii viii ix x ....
A format token I generates the sequence I II III IV V VI VII VIII IX X ....
A format token w generates numbers written as lower-case words, for example in English, one two three four ...
A format token W generates numbers written as upper-case words, for example in English, ONE TWO THREE FOUR ...
A format token Ww generates numbers written as title-case words, for example in English, One Two Three Four ...
Any other format token indicates a numbering sequence in which that token represents the number 1 (one) (but see the note below). It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence represented by the given token, it must use a format token of 1.

Note:

In some traditional numbering sequences additional signs are added to denote that the letters should be interpreted as numbers; these are not included in the format token. An example, see also the example below, is classical Greek where a dexia keraia and sometimes an aristeri keraia is added.

For all format tokens other than the first kind above (one that consists of decimal digits), there may be implementation-defined lower and upper bounds on the range of numbers that can be formatted using this format token; indeed, for some numbering sequences there may be intrinsic limits. For example, the formatting token ① (circled digit one) has a range of 1 to 20 imposed by the Unicode character repertoire. For the numbering sequences described above any upper bound imposed by the implementation must not be less than 1000 (one thousand) and any lower bound must not be greater than 1. Numbers that fall outside this range must be formatted using the format token 1. The numbering sequence associated with the format token 1 has a lower bound of 0 (zero).

The above expansions of numbering sequences for format tokens such as a and i are indicative but not prescriptive. There are various conventions in use for how alphabetic sequences continue when the alphabet is exhausted, and differing conventions for how roman numerals are written (for example, IV versus IIII as the representation of the number 4). Sometimes alphabetic sequences are used that omit letters such as i and o. This specification does not prescribe the detail of any sequence other than those sequences consisting entirely of decimal digits.

Many numbering sequences are language-sensitive. This applies especially to the sequence selected by the tokens w, W and Ww. It also applies to other sequences, for example different languages using the Cyrillic alphabet use different sequences of characters, each starting with the letter #x410 (Cyrillic capital letter A). In such cases, the lang attribute specifies which language's conventions are to be used; it has the same range of values as xml:lang (see [XML 1.0]). If no lang value is specified, the language that is used is implementation-defined. The set of languages for which numbering is supported is implementation-defined. If a language is requested that is not supported, the processor uses the language that it would use if the lang attribute were omitted.

If the optional ordinal attribute is present, and if its value is not a zero-length string, this indicates a request to output ordinal numbers rather than cardinal numbers. For example, in English, the value ordinal="yes" when used with the format token 1 outputs the sequence 1st 2nd 3rd 4th ..., and when used with the format token w outputs the sequence first second third fourth .... In some languages, ordinal numbers vary depending on the grammatical context, for example they may have different genders and may decline with the noun that they qualify. In such cases the value of the ordinal attribute may be used to indicate the variation of the ordinal number required. The way in which the variation is indicated will depend on the conventions of the language. For inflected languages that vary the ending of the word, the preferred approach is to indicate the required ending, preceded by a hyphen: for example in German, appropriate values are -e, -er, -es, -en. It is implementation-defined what combinations of values of the format token, the language, and the ordinal attribute are supported. If ordinal numbering is not supported for the combination of the format token, the language, and the actual value of the ordinal attribute, the request is ignored and cardinal numbers are generated instead.

Example: Ordinal Numbering in Italian

The specification format="1" ordinal="-º" lang="it", if supported, should produce the sequence:

1º 2º 3º 4º ...

The specification format="Ww" ordinal="-o" lang="it", if supported, should produce the sequence:

Primo Secondo Terzo Quarto Quinto ...

The letter-value attribute disambiguates between numbering sequences that use letters. In many languages there are two commonly used numbering sequences that use letters. One numbering sequence assigns numeric values to letters in alphabetic sequence, and the other assigns numeric values to each letter in some other manner traditional in that language. In English, these would correspond to the numbering sequences specified by the format tokens a and i. In some languages, the first member of each sequence is the same, and so the format token alone would be ambiguous. A value of alphabetic specifies the alphabetic sequence; a value of traditional specifies the other sequence. If the letter-value attribute is not specified, then it is implementation-dependent how any ambiguity is resolved.

Note:

Implementations may use extension attributes on xsl:number to provide additional control over the way in which numbers are formatted.

The grouping-separator attribute gives the separator used as a grouping (for example, thousands) separator in decimal numbering sequences, and the optional grouping-size specifies the size (normally 3) of the grouping. For example, grouping-separator="," and grouping-size="3" would produce numbers of the form 1,000,000 while grouping-separator="." and grouping-size="2" would produce numbers of the form 1.00.00.00. If only one of the grouping-separator and grouping-size attributes is specified, then it is ignored.

Example: Format Tokens and the Resulting Sequences

These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.

Description	Format Token	Sequence
French cardinal words	`format="Ww" lang="fr"`	Un, Deux, Trois, Quatre
German ordinal words	`format="w" ordinal="-e" lang="de"`	erste, zweite, dritte, vierte
Katakana numbering	`format="ア"`	ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ, ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ, ワ, ヰ, ヱ, ヲ, ン
Katakana numbering in iroha order	`format="イ"`	イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ, ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ, ヒ, モ, セ, ス
Thai numbering	`format="๑"`	๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘, ๑๙, ๒๐
Traditional Hebrew numbering	`format="א" letter-value="traditional"`	א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח, יט, כ
Traditional Georgian numbering	`format="ა" letter-value="traditional"`	ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ, ით, კ
Classical Greek numbering (see note)	`format="α" letter-value="traditional"`	αʹ, βʹ, γʹ, δʹ, εʹ, ϛʹ, ζʹ, ηʹ, θʹ, ιʹ, ιαʹ, ιβʹ, ιγʹ, ιδʹ, ιεʹ, ιϛʹ, ιζʹ, ιηʹ, ιθʹ, κʹ
Old Slavic numbering	`format="а" letter-value="traditional"`	А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ, ѲӀ, К

Note that Classical Greek is an example where the format token is not the same as the representation of the number 1.

13 Sorting

[Definition: A sort key specification is a sequence of one or more adjacent xsl:sort elements which together define rules for sorting the items in an input sequence to form a sorted sequence.]

[Definition: Within a sort key specification, each xsl:sort element defines one sort key component.] The first xsl:sort element specifies the primary component of the sort key specification, the second xsl:sort element specifies the secondary component of the sort key specification, and so on.

A sort key specification may occur immediately within an xsl:apply-templates, xsl:for-each, xsl:perform-sort, or xsl:for-each-group element.

Note:

When used within xsl:for-each, xsl:for-each-group, or xsl:perform-sort, xsl:sort elements must occur before any other children.

13.1 The `xsl:sort` Element

<xsl:sort select? = expression lang? = { nmtoken } order? = { "ascending" | "descending" } collation? = { uri } stable? = { "yes" | "no" } case-order? = { "upper-first" | "lower-first" } data-type? = { "text" | "number" | qname-but-not-ncname } >  </xsl:sort>

The xsl:sort element defines a sort key component. A sort key component specifies how a sort key value is to be computed for each item in the sequence being sorted, and also how two sort key values are to be compared.

The value of a sort key component is determined either by its select attribute or by the contained sequence constructor. If neither is present, the default is select=".", which has the effect of sorting on the actual value of the item if it is an atomic value, or on the typed-value of the item if it is a node. If a select attribute is present, its value must be an XPath expression.

[ERR XTSE1015] It is a static error if an xsl:sort element with a select attribute has non-empty content.

Those attributes of the xsl:sort elements whose values are attribute value templates are evaluated using the same focus as is used to evaluate the select attribute of the containing instruction (specifically, xsl:apply-templates, xsl:for-each, xsl:for-each-group, or xsl:perform-sort).

The stable attribute is permitted only on the first xsl:sort element within a sort key specification

[ERR XTSE1017] It is a static error if an xsl:sort element other than the first in a sequence of sibling xsl:sort elements has a stable attribute.

[Definition: A sort key specification is said to be stable if its first xsl:sort element has no stable attribute, or has a stable attribute whose effective value is yes.]

13.1.1 The Sorting Process

[Definition: The sequence to be sorted is referred to as the initial sequence.]

[Definition: The sequence after sorting as defined by the xsl:sort elements is referred to as the sorted sequence.]

[Definition: For each item in the initial sequence, a value is computed for each sort key component within the sort key specification. The value computed for an item by using the Nth sort key component is referred to as the Nth sort key value of that item.]

The items in the initial sequence are ordered into a sorted sequence by comparing their sort key values. The relative position of two items A and B in the sorted sequence is determined as follows. The first sort key value of A is compared with the first sort key value of B, according to the rules of the first sort key component. If, under these rules, A is less than B, then A will precede B in the sorted sequence, unless the order attribute of this sort key component specifies descending, in which case B will precede A in the sorted sequence. If, however, the relevant sort key values compare equal, then the second sort key value of A is compared with the second sort key value of B, according to the rules of the second sort key component. This continues until two sort key values are found that compare unequal. If all the sort key values compare equal, and the sort key specification is stable, then A will precede B in the sorted sequence if and only if A preceded B in the initial sequence. If all the sort key values compare equal, and the sort key specification is not stable, then the relative order of A and B in the sorted sequence is implementation-dependent.

Note:

If two items have equal sort key values, and the sort is stable, then their order in the sorted sequence will be the same as their order in the initial sequence, regardless of whether order="descending" was specified on any or all of the sort key components.

The Nth sort key value is computed by evaluating either the select attribute or the contained sequence constructor of the Nth xsl:sort element, or the expression . (dot) if neither is present. This evaluation is done with the focus set as follows:

The context item is the item in the initial sequence whose sort key value is being computed.
The context position is the position of that item in the initial sequence.
The context size is the size of the initial sequence.

Note:

As in any other XPath expression, the current function may be used within the select expression of xsl:sort to refer to the item that is the context item for the expression as a whole; that is, the item whose sort key value is being computed.

The sort key values are atomized, and are then compared. The way they are compared depends on their data type, as described in the next section.

13.1.2 Comparing Sort Key Values

It is possible to force the system to compare sort key values using the rules for a particular data type by including a cast as part of the sort key component. For example, <xsl:sort select="xs:date(@dob)"/> will force the attributes to be compared as dates. In the absence of such a cast, the sort key values are compared using the rules appropriate to their data type. Any values of type xs:untypedAtomic are cast to xs:string.

For backwards compatibility with XSLT 1.0, the data-type attribute remains available. If this has the effective value text, the atomized sort key values are converted to strings before being compared. If it has the effective value number, the atomized sort key values are converted to doubles before being compared. The conversion is done by using the string^FO or number^FO function as appropriate. If the data-type attribute has any other effective value, then the value must be a lexical QName with a non-empty prefix, and the effect of the attribute is implementation-defined.

[ERR XTTE1020] If any sort key value, after atomization and any type conversion required by the data-type attribute, is a sequence containing more than one item, then the effect depends on whether the xsl:sort element is processed with XSLT 1.0 behavior. With XSLT 1.0 behavior, the effective sort key value is the first item in the sequence. In other cases, this is a type error.

The set of sort key values (after any conversion) is first divided into two categories: empty values, and ordinary values. The empty sort key values represent those items where the sort key value is an empty sequence. These values are considered for sorting purposes to be equal to each other, but less than any other value. The remaining values are classified as ordinary values.

[ERR XTDE1030] It is a non-recoverable dynamic error if, for any sort key component, the set of sort key values evaluated for all the items in the initial sequence, after any type conversion requested, contains a pair of ordinary values for which the result of the XPath lt operator is an error.

Note:

The above error condition may occur if the values to be sorted are of a type that does not support ordering (for example, xs:QName) or if the sequence is heterogeneous (for example, if it contains both strings and numbers). The error can generally be prevented by invoking a cast or constructor function within the sort key component.

The error condition is subject to the usual caveat that a processor is not required to evaluate any expression solely in order to determine whether it raises an error. For example, if there are several sort key components, then a processor is not required to evaluate or compare minor sort key values unless the corresponding major sort key values are equal.

In general, comparison of two ordinary values is performed according to the rules of the XPath lt operator. To ensure a total ordering, the same implementation of the lt operator must be used for all the comparisons: the one that is chosen is the one appropriate to the most specific type to which all the values can be converted by subtype substitution and/or type promotion. For example, if the sequence contains both xs:decimal and xs:double values, then the values are compared using xs:double comparison, even when comparing two xs:decimal values. NaN values, for sorting purposes, are considered to be equal to each other, and less than any other numeric value. Special rules also apply to the xs:string and xs:anyURI types, and types derived by restriction therefrom, as described in the next section.

13.1.3 Sorting Using Collations

The rules given in this section apply when comparing values whose type is xs:string or a type derived by restriction from xs:string, or whose type is xs:anyURI or a type derived by restriction from xs:anyURI.

[Definition: Facilities in XSLT 2.1 and XPath 2.1 that require strings to be ordered rely on the concept of a named collation. A collation is a set of rules that determine whether two strings are equal, and if not, which of them is to be sorted before the other.] A collation is identified by a URI, but the manner in which this URI is associated with an actual rule or algorithm is implementation-defined.

The one collation URI that must be recognized by every implementation is http://www.w3.org/2005/xpath-functions/collation/codepoint, which provides the ability to compare strings based on the Unicode codepoint values of the characters in the string.

For more information about collations, see Section 7.3 Equality and Comparison of Strings^FO in [Functions and Operators]. Some specifications, for example [UNICODE TR10], use the term "collation" to describe rules that can be tailored or parameterized for various purposes. In this specification, a collation URI refers to a collation in which all such parameters have already been fixed. Therefore, if a collation URI is specified, other attributes such as case-order and lang are ignored.

Note:

The reason XSLT does not provide detailed mechanisms for defining collating sequences is that many implementations will re-use collating mechanisms available from the underlying implementation platform (for example, from the operating system or from the run-time library of a chosen programming language). These will inevitably differ from one XSLT implementation to another.

If the xsl:sort element has a collation attribute, then the strings are compared according to the rules for the named collation: that is, they are compared using the XPath function call compare($a, $b, $collation).

If the effective value of the collation attribute of xsl:sort is a relative URI, then it is resolved against the base URI of the xsl:sort element.

[ERR XTDE1035] It is a non-recoverable dynamic error if the collation attribute of xsl:sort (after resolving against the base URI) is not a URI that is recognized by the implementation as referring to a collation.

Note:

It is entirely for the implementation to determine whether it recognizes a particular collation URI. For example, if the implementation allows collation URIs to contain parameters in the query part of the URI, it is the implementation that determines whether a URI containing an unknown or invalid parameter is or is not a recognized collation URI. The fact that this error is described as non-recoverable thus does not prevent an implementation applying a fallback collation if it chooses to do so.

The lang and case-order attributes are ignored if a collation attribute is present. But in the absence of a collation attribute, these attributes provide input to an implementation-defined algorithm to locate a suitable collation:

The lang attribute indicates that a collation suitable for a particular natural language should be used. The effective value of the attribute must be a value that would be valid for the xml:lang attribute (see [XML 1.0]).
The case-order attribute indicates whether the desired collation should sort upper-case letters before lower-case or vice versa. The effective value of the attribute must be either lower-first (indicating that lower-case letters precede upper-case letters in the collating sequence) or upper-first (indicating that upper-case letters precede lower-case).

When lower-first is requested, the returned collation should have the property that when two strings differ only in the case of one or more characters, then a string in which the first differing character is lower-case should precede a string in which the corresponding character is title-case, which should in turn precede a string in which the corresponding character is upper-case. When upper-first is requested, the returned collation should have the property that when two strings differ only in the case of one or more characters, then a string in which the first differing character is upper-case should precede a string in which the corresponding character is title-case, which should in turn precede a string in which the corresponding character is lower-case.

So, for example, if lang="en", then A a B b are sorted with case-order="upper-first" and a A b B are sorted with case-order="lower-first".

As a further example, if lower-first is requested, then a sorted sequence might be "MacAndrew, macintosh, macIntosh, Macintosh, MacIntosh, macintoshes, Macintoshes, McIntosh". If upper-first is requested, the same sequence would sort as "MacAndrew, MacIntosh, Macintosh, macIntosh, macintosh, MacIntoshes, macintoshes, McIntosh".

If none of the collation, lang, or case-order attributes is present, the collation is chosen in an implementation-defined way. It is not required that the default collation for sorting should be the same as the default collation used when evaluating XPath expressions, as described in 5.4.1 Initializing the Static Context and 3.6.1 The default-collation attribute.

Note:

It is usually appropriate, when sorting, to use a strong collation, that is, one that takes account of secondary differences (accents) and tertiary differences (case) between strings that are otherwise equal. A weak collation, which ignores such differences, may be more suitable when comparing strings for equality.

Useful background information on international sorting is provided in [UNICODE TR10]. The case-order attribute may be interpreted as described in section 6.6 of [UNICODE TR10].

13.2 Creating a Sorted Sequence

 <xsl:perform-sort select? = expression >  </xsl:perform-sort>

The xsl:perform-sort instruction is used to return a sorted sequence.

The initial sequence is obtained either by evaluating the select attribute or by evaluating the contained sequence constructor (but not both). If there is no select attribute and no sequence constructor then the initial sequence (and therefore, the sorted sequence) is an empty sequence.

[ERR XTSE1040] It is a static error if an xsl:perform-sort instruction with a select attribute has any content other than xsl:sort and xsl:fallback instructions.

The result of the xsl:perform-sort instruction is the result of sorting its initial sequence using its contained sort key specification.

Example: Sorting a Sequence of Atomic Values

The following stylesheet function sorts a sequence of atomic values using the value itself as the sort key.

<xsl:function name="local:sort" 
          as="xs:anyAtomicType*">
  <xsl:param name="in" as="xs:anyAtomicType*"/>
  <xsl:perform-sort select="$in">
    <xsl:sort select="."/>
  </xsl:perform-sort>
</xsl:function>

Example: Writing a Function to Perform a Sort

The following example defines a function that sorts books by price, and uses this function to output the five books that have the lowest prices:

<xsl:function name="bib:books-by-price" 
          as="schema-element(bib:book)*">
  <xsl:param name="in" as="schema-element(bib:book)*"/>
  <xsl:perform-sort select="$in">
    <xsl:sort select="xs:decimal(bib:price)"/>
  </xsl:perform-sort>
</xsl:function>
   ...
   <xsl:copy-of select="bib:books-by-price(//bib:book)
                             [position() = 1 to 5]"/>

13.3 Processing a Sequence in Sorted Order

When used within xsl:for-each or xsl:apply-templates, a sort key specification indicates that the sequence of items selected by that instruction is to be processed in sorted order, not in the order of the supplied sequence.

Example: Processing Elements in Sorted Order

For example, suppose an employee database has the form

<employees>
  <employee>
    <name>
      <given>James</given>
      <family>Clark</family>
    </name>
    ...
  </employee>
</employees>

Then a list of employees sorted by name could be generated using:

<xsl:template match="employees">
  <ul>
    <xsl:apply-templates select="employee">
      <xsl:sort select="name/family"/>
      <xsl:sort select="name/given"/>
    </xsl:apply-templates>
  </ul>
</xsl:template>

<xsl:template match="employee">
  <li>
    <xsl:value-of select="name/given"/>
    <xsl:text> </xsl:text>
    <xsl:value-of select="name/family"/>
  </li>
</xsl:template>

When used within xsl:for-each-group, a sort key specification indicates the order in which the groups are to be processed. For the effect of xsl:for-each-group, see 14 Grouping.

14 Grouping

The facilities described in this section are designed to allow items in a sequence to be grouped based on common values; for example it allows grouping of elements having the same value for a particular attribute, or elements with the same name, or elements with common values for any other expression. Since grouping identifies items with duplicate values, the same facilities also allow selection of the distinct values in a sequence of items, that is, the elimination of duplicates.

Note:

Simple elimination of duplicates can also be achieved using the function distinct-values^FO in the core function library: see [Functions and Operators].

In addition these facilities allow grouping based on sequential position, for example selecting groups of adjacent para elements. The facilities also provide an easy way to do fixed-size grouping, for example identifying groups of three adjacent nodes, which is useful when arranging data in multiple columns.

For each group of items identified, it is possible to evaluate a sequence constructor for the group. Grouping is nestable to multiple levels so that groups of distinct items can be identified, then from among the distinct groups selected, further sub-grouping of distinct items in the current group can be done.

It is also possible for one item to participate in more than one group.

14.1 The Current Group

current-group() as item()*

[Definition: The evaluation context for XPath expressions includes a component called the current group, which is a sequence. ]

The current group is bound during evaluation of the xsl:for-each-group instruction and during evaluation of the xsl:merge instruction. If neither instruction is being evaluated, it will be an empty sequence.

The scope of the current group is dynamic: its value is retained through calls on named templates, template rules, functions, and attribute sets.

The function current-group returns the sequence of items making up the current group.

Issue 16 (current-group-source-argument):

The WG has considered a variant of current-group for use within xsl:merge-action which would get the subset of the current group applicable to one named merge source. This is superseded in this draft by the current-merge-inputs function, which provides this capability and more. However, the function call current-group(sourcename) could still be useful because it is simpler. Also, allowing a parameter to current-group opens the way to do similar things in the context of xsl:for-each-group, such as using the source names "matching" and "non-matching" to distinguish nodes that matched (or failed to match) the group-starting-with and group-ending-with patterns.

[ERR XTSE1060] It is a static error if the current-group function is used within a pattern.

14.2 The Current Grouping Key

current-grouping-key() as xs:anyAtomicType?

[Definition: The evaluation context for XPath expressions includes a component called the current grouping key, which is a sequence of atomic values. The current grouping key is the grouping key shared in common by all the items within the current group.]

The current grouping key is bound during evaluation of the xsl:for-each-group instruction and during evaluation of the xsl:merge instruction. If neither instruction is being evaluated, it will be an empty sequence.

While an xsl:for-each-group instruction with a group-by or group-adjacent attribute is being evaluated, the current grouping key will be a single atomic value.

While the xsl:merge-action part of an xsl:merge instruction is being evaluated, the current grouping key will be a sequence of atomic values, one for each component of the grouping key, as defined by the xsl:merge-key elements.

At other times, the current grouping key will be the empty sequence.

The function current-grouping-key returns the current grouping key.

The grouping keys of all items in a group are not necessarily identical. For example, one might be an xs:float while another is a numerically equal xs:decimal. The current-grouping-key function returns the grouping key of the initial item in the group, after atomization and casting of xs:untypedAtomic values to xs:string.

The function takes no arguments.

[ERR XTSE1070] It is a static error if the current-grouping-key function is used within a pattern.

14.3 The `xsl:for-each-group` Element

 <xsl:for-each-group select = expression group-by? = expression group-adjacent? = expression group-starting-with? = pattern group-ending-with? = pattern collation? = { uri } >  </xsl:for-each-group>

This element is an instruction that may be used anywhere within a sequence constructor.

[Definition: The xsl:for-each-group instruction allocates the items in an input sequence into groups of items (that is, it establishes a collection of sequences) based either on common values of a grouping key, or on a pattern that the initial or final item in a group must match.] The sequence constructor that forms the content of the xsl:for-each-group instruction is evaluated once for each of these groups.

[Definition: The sequence of items to be grouped, which is referred to as the population, is determined by evaluating the XPath expression contained in the select attribute.]

[Definition: The population is treated as a sequence; the order of items in this sequence is referred to as population order ].

A group is never empty. If the population is empty, the number of groups will be zero.

The assignment of items to groups depends on the group-by, group-adjacent, group-starting-with, and group-ending-with attributes.

[ERR XTSE1080] These four attributes are mutually exclusive: it is a static error if none of these four attributes is present or if more than one of them is present.

[ERR XTSE1090] It is an error to specify the collation attribute if neither the group-by attribute nor group-adjacent attribute is specified.

[Definition: If either of the group-by or group-adjacent attributes is present, then for each item in the population a set of grouping keys is calculated, as follows: the expression contained in the group-by or group-adjacent attribute is evaluated; the result is atomized; and any xs:untypedAtomic values are cast to xs:string. The grouping keys are the distinct atomic values present in the result sequence. ]

When calculating grouping keys for an item in the population, the expression contained in the group-by or group-adjacent attribute is evaluated with that item as the context item, with its position in population order as the context position, and with the size of the population as the context size. The resulting sequence is atomized, and each atomic value in the atomized sequence acts as a grouping key for that item in the population.

If the group-by attribute is present, then an item in the population may have multiple grouping keys: that is, the group-by expression evaluates to a sequence. The item is included in as many groups as there are distinct grouping keys (which may be zero). If the group-adjacent attribute is used, then each item in the population must have exactly one grouping key value.

[ERR XTTE1100] It is a type error if the result of evaluating the group-adjacent expression is an empty sequence or a sequence containing more than one item.

Grouping keys are compared using the rules for the eq operator appropriate to their dynamic type. Values of type xs:untypedAtomic are cast to xs:string before the comparison. Two items that are not comparable using the eq operator are considered to be not equal, that is, they are allocated to different groups. If the values are strings, or untyped atomic values, then if there is a collation attribute the values are compared using the collation specified as the effective value of the collation attribute, resolved if relative against the base URI of the xsl:for-each-group element. If there is no collation attribute then the default collation is used.

For the purposes of grouping, the value NaN is considered equal to itself.

[ERR XTDE1110] It is a non-recoverable dynamic error if the collation URI specified to xsl:for-each-group (after resolving against the base URI) is a collation that is not recognized by the implementation. (For notes, [see ERR XTDE1035].)

For more information on collations, see 13.1.3 Sorting Using Collations.

[ERR XTTE1120] When the group-starting-with or group-ending-with attribute is used, it is a type error if the result of evaluating the select expression contains an item that is not a node.

The way in which an xsl:for-each-group element is evaluated depends on which of the four group-defining attributes is present:

If the group-by attribute is present, the items in the population are examined, in population order. For each item J, the expression in the group-by attribute is evaluated to produce a sequence of zero or more grouping key values. For each one of these grouping keys, if there is already a group created to hold items having that grouping key value, J is appended to that group; otherwise a new group is created for items with that grouping key value, and J becomes its first member.

An item in the population may thus be appended to zero, one, or many groups. An item will never be appended more than once to the same group; if two or more grouping keys for the same item are equal, then the duplicates are ignored. An item here means the item at a particular position within the population—if the population contains the same node at several different positions in the sequence then a group may indeed contain duplicate nodes.

The number of groups will be the same as the number of distinct grouping key values present in the population.

If the population contains values of different numeric types that differ from each other by small amounts, then the eq operator is not transitive, because of rounding effects occurring during type promotion. The effect of this is described in 14.5 Non-Transitivity.
If the group-adjacent attribute is present, the items in the population are examined, in population order. If an item has the same value for the grouping key as its preceding item within the population (in population order), then it is appended to the same group as its preceding item; otherwise a new group is created and the item becomes its first member.
If the group-starting-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes.

The items in the population are examined in population order. If an item matches the pattern, or is the first item in the population, then a new group is created and the item becomes its first member. Otherwise, the item is appended to the same group as its preceding item within the population.
If the group-ending-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes.

The items in the population are examined in population order. If an item is the first item in the population, or if the previous item in the population matches the pattern, then a new group is created and the item becomes its first member. Otherwise, the item is appended to the same group as its preceding item within the population.

In all cases the order of items within each group is predictable, and reflects the original population order, in that the items are processed in population order and each item is appended at the end of zero or more groups.

Note:

As always, a different algorithm may be used if it achieves the same effect.

[Definition: For each group, the item within the group that is first in population order is known as the initial item of the group.]

[Definition: There is a total ordering among groups referred to as the order of first appearance. A group G is defined to precede a group H in order of first appearance if the initial item of G precedes the initial item of H in population order. If two groups G and H have the same initial item (because the item is in both groups) then G precedes H if the grouping key of G precedes the grouping key of H in the sequence that results from evaluating the group-by expression of this initial item.]

[Definition: There is another total ordering among groups referred to as processing order. If group R precedes group S in processing order, then in the result sequence returned by the xsl:for-each-group instruction the items generated by processing group R will precede the items generated by processing group S.]

If there are no xsl:sort elements immediately within the xsl:for-each-group element, the processing order of the groups is the order of first appearance.

Otherwise, the xsl:sort elements immediately within the xsl:for-each-group element define the processing order of the groups (see 13 Sorting). They do not affect the order of items within each group. Multiple sort key components are allowed, and are evaluated in major-to-minor order. If two groups have the same values for all their sort key components, they are processed in order of first appearance if the sort key specification is stable, otherwise in an implementation-dependent order.

The select expression of an xsl:sort element is evaluated once for each group. During this evaluation, the context item is the initial item of the group, the context position is the position of this item within the set of initial items (that is, one item for each group in the population) in population order, the context size is the number of groups, the current group is the group whose sort key value is being determined, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence.

Example: Sorting Groups

For example, this means that if the grouping key is @category, you can sort the groups in order of their grouping key by writing <xsl:sort select="current-grouping-key()"/>; or you can sort the groups in order of size by writing <xsl:sort select="count(current-group())"/>

The sequence constructor contained in the xsl:for-each-group element is evaluated once for each of the groups, in processing order. The sequences that result are concatenated, in processing order, to form the result of the xsl:for-each-group element. Within the sequence constructor, the context item is the initial item of the relevant group, the context position is the position of this group in the processing order of the groups, the context size is the number of groups, the current group is the group being processed, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence. This has the effect that within the sequence constructor, a call on position() takes successive values 1, 2, ... last().

During the evaluation of a stylesheet function, the current group and current grouping key are set to the empty sequence, and revert to their previous values on completion of evaluation of the stylesheet function.

On completion of the evaluation of the xsl:for-each-group instruction, the current group and current grouping key revert to their previous value.

14.4 Examples of Grouping

Example: Grouping Nodes based on Common Values

The following example groups a list of nodes based on common values. The resulting groups are numbered but unsorted, and a total is calculated for each group.

Source XML document:

<cities>
  <city name="Milano"  country="Italia"      pop="5"/>
  <city name="Paris"   country="France"      pop="7"/>
  <city name="München" country="Deutschland" pop="4"/>
  <city name="Lyon"    country="France"      pop="2"/>
  <city name="Venezia" country="Italia"      pop="1"/>
</cities>

More specifically, the aim is to produce a four-column table, containing one row for each distinct country. The four columns are to contain first, a sequence number giving the number of the row; second, the name of the country, third, a comma-separated alphabetical list of the city names within that country, and fourth, the sum of the pop attribute for the cities in that country.

Desired output:

<table>
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>List of Cities</th>
    <th>Population</th>
  </tr>
  <tr>
    <td>1</td>
    <td>Italia</td>
    <td>Milano, Venezia</td>
    <td>6</td>
  </tr>
  <tr>
    <td>2</td>
    <td>France</td>
    <td>Lyon, Paris</td>
    <td>9</td>
  </tr>  
  <tr>
    <td>3</td>
    <td>Deutschland</td>
    <td>München</td>
    <td>4</td>
  </tr>  
</table>

Solution:

<table xsl:version="2.1" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <tr>
    <th>Position</th>
    <th>Country</th>
    <th>City List</th>
    <th>Population</th>
  </tr>
  <xsl:for-each-group select="cities/city" group-by="@country">
    <tr>
      <td><xsl:value-of select="position()"/></td>
      <td><xsl:value-of select="@country"/></td>
      <td>
        <xsl:value-of select="current-group()/@name" separator=", "/>
      </td>
      <td><xsl:value-of select="sum(current-group()/@pop)"/></td>
    </tr>
  </xsl:for-each-group>
</table>

Example: A Composite Grouping Key

Sometimes it is necessary to use a composite grouping key: for example, suppose the source document is similar to the one used in the previous examples, but allows multiple entries for the same country and city, such as:

<cities>
  <city name="Milano"  country="Italia"  year="1950"   pop="5.23"/>
  <city name="Milano"  country="Italia"  year="1960"   pop="5.29"/>  
  <city name="Padova"  country="Italia"  year="1950"   pop="0.69"/>
  <city name="Padova"  country="Italia"  year="1960"   pop="0.93"/>    
  <city name="Paris"   country="France"  year="1951"   pop="7.2"/>
  <city name="Paris"   country="France"  year="1961"   pop="7.6"/>
</cities>

Now suppose we want to list the average value of @pop for each (country, name) combination. One way to handle this is to concatenate the parts of the key, for example <xsl:for-each-group select="concat(@country, '/', @name)">. A more flexible solution is to nest one xsl:for-each-group element directly inside another:

<xsl:for-each-group select="cities/city" group-by="@country">
  <xsl:for-each-group select="current-group()" group-by="@name">
    <p><xsl:value-of select="@name"/>, <xsl:value-of select="@country"/>:
        <xsl:value-of select="avg(current-group()/@pop)"/></p>
  </xsl:for-each-group>
</xsl:for-each-group>

The two approaches are not precisely equivalent. If the code were changed to output the value of position() alongside @name then the first approach (a single xsl:for-each-group element with a compound key) would number the groups (1, 2, 3), while the second approach (two nested xsl:for-each-group elements) would number them (1, 2, 1).

Example: Identifying a Group by its Initial Element

The next example identifies a group not by the presence of a common value, but rather by adjacency in document order. A group consists of an h2 element, followed by all the p elements up to the next h2 element.

Source XML document:

<body>
  <h2>Introduction</h2>
  <p>XSLT is used to write stylesheets.</p>
  <p>XQuery is used to query XML databases.</p>
  <h2>What is a stylesheet?</h2>
  <p>A stylesheet is an XML document used to define a transformation.</p>
  <p>Stylesheets may be written in XSLT.</p>
  <p>XSLT 2.0 introduces new grouping constructs.</p>
</body>

Desired output:

<chapter>
  <section title="Introduction">
    <para>XSLT is used to write stylesheets.</para>
    <para>XQuery is used to query XML databases.</para>
  </section> 
  <section title="What is a stylesheet?">
    <para>A stylesheet is used to define a transformation.</para>
    <para>Stylesheets may be written in XSLT.</para>
    <para>XSLT 2.0 introduces new grouping constructs.</para>
  </section>
</chapter>

Solution:

<xsl:template match="body">
  <chapter>
        <xsl:for-each-group select="*" group-starting-with="h2"      >
          <section title="{self::h2}">
            <xsl:for-each select="current-group()[self::p]">
              <para><xsl:value-of select="."/></para>
            </xsl:for-each> 
          </section>
        </xsl:for-each-group>
  </chapter>
</xsl:template>

The use of title="{self::h2}" rather than title="{.}" is to handle the case where the first element is not an h2 element.

Example: Identifying a Group by its Final Element

The next example illustrates how a group of related elements can be identified by the last element in the group, rather than the first. Here the absence of the attribute continued="yes" indicates the end of the group.

Source XML document:

<doc>
  <page continued="yes">Some text</page>
  <page continued="yes">More text</page>    
  <page>Yet more text</page>
  <page continued="yes">Some words</page>
  <page continued="yes">More words</page>    
  <page>Yet more words</page>        
</doc>

Desired output:

<doc>
  <pageset>
    <page>Some text</page>
    <page>More text</page>    
    <page>Yet more text</page>
  </pageset>
  <pageset>
    <page>Some words</page>
    <page>More words</page>    
    <page>Yet more words</page>
  </pageset>
</doc>

Solution:

<xsl:template match="doc">
<doc>
  <xsl:for-each-group select="*" 
                      group-ending-with="page[not(@continued='yes')]">
    <pageset>
      <xsl:for-each select="current-group()">
        <page><xsl:value-of select="."/></page>
      </xsl:for-each> 
    </pageset>
  </xsl:for-each-group>
</doc>
</xsl:template>

Example: Adding an Element to Several Groups

The next example shows how an item can be added to multiple groups. Book titles will be added to one group for each indexing term marked up within the title.

Source XML document:

<titles>
    <title>A Beginner's Guide to <ix>Java</ix></title>
    <title>Learning <ix>XML</ix></title>
    <title>Using <ix>XML</ix> with <ix>Java</ix></title>
</titles>

Desired output:

<h2>Java</h2>
    <p>A Beginner's Guide to Java</p>
    <p>Using XML with Java</p>
<h2>XML</h2>
    <p>Learning XML</p>
    <p>Using XML with Java</p>

Solution:

<xsl:template match="titles">
    <xsl:for-each-group select="title" group-by="ix">
      <h2><xsl:value-of select="current-grouping-key()"/></h2>
      <xsl:for-each select="current-group()">
        <p><xsl:value-of select="."/></p>
      </xsl:for-each>
    </xsl:for-each-group>
</xsl:template>

Example: Grouping Alternating Sequences of Elements

In the final example, the membership of a node within a group is based both on adjacency of the nodes in document order, and on common values. In this case, the grouping key is a boolean condition, true or false, so the effect is that a grouping establishes a maximal sequence of nodes for which the condition is true, followed by a maximal sequence for which it is false, and so on.

Source XML document:

<p>Do <em>not</em>:
    <ul>
    <li>talk,</li>
    <li>eat, or</li>
    <li>use your mobile telephone</li>
    </ul>
    while you are in the cinema.</p>

Desired output:

<p>Do <em>not</em>:</p>
    <ul>
    <li>talk,</li>
    <li>eat, or</li>
    <li>use your mobile telephone</li>
    </ul>
    <p>while you are in the cinema.</p>

Solution:

This requires creating a p element around the maximal sequence of sibling nodes that does not include a ul or ol element.

This can be done by using group-adjacent, with a grouping key that is true if the element is a ul or ol element, and false otherwise:

<xsl:template match="p">
    <xsl:for-each-group select="node()" 
            group-adjacent="self::ul or self::ol">
        <xsl:choose>
            <xsl:when test="current-grouping-key()">
                <xsl:copy-of select="current-group()"/>  
            </xsl:when>
            <xsl:otherwise>
                <p>
                    <xsl:copy-of select="current-group()"/>
                </p>
            </xsl:otherwise>  
        </xsl:choose>
    </xsl:for-each-group>
</xsl:template>

14.5 Non-Transitivity

If the population contains values of different numeric types that differ from each other by small amounts, then the eq operator is not transitive, because of rounding effects occurring during type promotion. It is thus possible to have three values A, B, and C among the grouping keys of the population such that A eq B, B eq C, but A ne C.

For example, this arises when computing

      <xsl:for-each-group group-by="." select="
             xs:float('1.0'),
             xs:decimal('1.0000000000100000000001',
             xs:double( '1.00000000001')">

because the values of type xs:float and xs:double both compare equal to the value of type xs:decimal but not equal to each other.

In this situation the results must be equivalent to the results obtained by the following algorithm:

For each item J in the population in population order, for each of the grouping keys K for that item in sequence, the processor identifies those existing groups G such that the grouping key of the initial item of G is equal to K.
If there is exactly one group G, then J is added to this group, unless J is already a member of this group.
If there is no group G, then a new group is created with J as its first item.
If there is more than one group G (which can only happen in exceptional circumstances involving non-transitivity), then one of these groups is selected in an implementation-dependent way, and J is added to this group, unless J is already a member of this group.

The effect of these rules is that (a) every item in a non-singleton group has a grouping key that is equal to that of at least one other item in that group, (b) for any two distinct groups, there is at least one pair of items (one from each group) whose grouping keys are not equal to each other.

15 Merging

The xsl:merge instruction allows a sorted sequence of items to be constructed by merging several input sequences, each of which is already sorted. Each input sequence must have a merge key (one or more atomic values that can be computed as a function of the items in the sequence); the input sequence must be pre-sorted on the value of its merge keys; and the merge keys for the different input sequences must be compatible in the sense that key values from an item in one sequence are always comparable with key values from an item in a different sequence.

For example, if two log files contain details of events sorted by date and time, then the xsl:merge instruction can be used to combine these into a single sequence that is also sorted by date and time.

The data written to the output sequence can be computed in an arbitrary way from the data in the input sequences.

The xsl:merge instruction checks that the input sequences are correctly sorted and signals a dynamic error if they are not. It does not actually perform the sorting.

The xsl:merge instruction can be used to merge several sequences of items that all have the same structure (more precisely, sequences whose merge keys are computed in the same way): for example, log files created by the same application running on different machines in a server farm. Alternatively, xsl:merge can be used to merge sequences that have different structure (sequences whose merge keys are computed in different ways), provided that the computed merge keys are compatible: an example might be two log files created by different applications, using different XML vocabularies, that both contain timestamped events but represent the timestamp in different ways. The xsl:merge-source element represents a set of input sequences that follow common rules, including the rules for computing the merge key. The xsl:merge operation may take any number of xsl:merge-source elements representing different rules for input sequences, and each xsl:merge-source element may describe any number (zero or more) of input sequences. The number of input sequences to the merging operation is thus fixed only at the time the xsl:merge instruction is evaluated, and may vary from one evaluation to another.

The following examples illustrate some of the possibilities. The detailed explanation of the constructs used follows later in this section.

Example: Merging all the files in a collection

This example takes as input a homogeneous collection of XML log files each of which contains a sorted sequence of event elements with a timestamp attribute validated as an instance of xs:dateTime. It merges the events from the input files into a single sorted output file.

<xsl:result-document href="merged-events.xml">
  <events>
    <xsl:merge>
      <xsl:merge-source select="collection('log-files')">
        <xsl:merge-input select="events/event">
          <xsl:merge-key select="@timestamp"/>
        </xsl:merge-input>
      </xsl:merge-source>
      <xsl:merge-action>
        <xsl:copy-of select="current-group()"/>
      </xsl:merge-action>
    </xsl:merge>
  </events>
</xsl:result-document>

The example assumes that there are several input files each of which has a structure similar to the following, in which the timestamp attribute has a typed value that is an instance of xs:dateTime:

<events>
   <event timestamp="2009-08-20T12:01:01Z">Transaction T1234 started</event>
   <event timestamp="2009-08-20T12:01:08Z">Transaction T1235 started</event>
   <event timestamp="2009-08-20T12:01:12Z">Transaction T1235 ended</event>
   <event timestamp="2009-08-20T12:01:15Z">Transaction T1234 ended</event>
</events>

The output file will have the same structure, and will contain copies of all the event elements from all of the input files, in sorted order. Note that multiple events with the same timestamp can occur either within a single file or across multiple files: the order of appearance of these events in the output file corresponds to the order of the log files within the collection (which might or might not be predictable, depending on the implementation).

Example: Merging two heterogeneous files

This example takes as input two log files with different structure, producing a single merged output in which the entries have a common structure:

<xsl:result-document href="merged-events.xml">
  <events>
    <xsl:merge>
      <xsl:merge-source select="doc('log-file-1.xml')">
        <xsl:merge-input select="events/event">
          <xsl:merge-key select="@timestamp"/>
        </xsl:merge-input>
      </xsl:merge-source>
      <xsl:merge-source select="doc('log-files-2.xml')">
        <xsl:merge-input select="log/day/record">
          <xsl:merge-key select="dateTime(../@date, time)"/>
        </xsl:merge-input>
      </xsl:merge-source>
      <xsl:merge-action>
        <xsl:apply-templates select="current-group()" 
                             mode="standardize-log-entry">
      </xsl:merge-action>
    </xsl:merge>
  </events>
</xsl:result-document>

Here the first input file has a structure similar to that shown in the previous example, while the second input has a different structure, of the form:

<log>
  <day date="2009-08-20">
    <record>
      <time>12:01:09-05:00</time>
      <message>Temperature 15.4C</message>
    </record>
    <record>
      <time>12:03:00-05:00</time>
      <message>Temperature 18.2C</message>
    </record>
  </day>
</log>

The templates in mode standardize-log-entry convert the log entries to a common output format, for example:

<xsl:template match="event" mode="standardize-log-entry" 
                            as="schema-element(event)">
  <xsl:copy-of select-"." validation="preserve"/>
</xsl:template>
  
<xsl:template match="record" mode="standardize-log-entry" 
                             as="schema-element(event)">
  <event timestamp="{dateTime(../@date, time)}" xsl:validation="strict">
    <xsl:value-of select="message"/>
  </event>
</xsl:template>

Note:

The xsl:merge instruction is designed to enable streaming of data, so that there is no need to allocate memory to hold the input sequences. However, there is no requirement that an implementation should actually use streaming to perform the processing.

Issue 17 (streamability-of-merge):

The xsl:merge instruction is designed to achieve streamability in the case where the anchor nodes are the document nodes of distinct documents and the merge keys are motionless expressions. However, unlike other constructs, there is no provision for users to indicate that streaming is required, and no analysis of the conditions under which it is guaranteed.

15.1 Terminology for merging

[Definition: A merge source definition is the definition of one kind of input to the merge operation. It selects zero or more merge input sequences, and it includes a merge key specification to define how the merge key values are computed for each such merge input sequence.] A merge source definition corresponds to an xsl:merge-source element in the stylesheet.

[Definition: A merge input sequence is an arbitrary sequence^DM11 of items which is already sorted according to the merge key specification for the corresponding merge source definition.]

[Definition: A merge key specification consists of one or more adjacent xsl:merge-key elements which together define how the merge input sequences selected by a merge source definition are sorted. Each xsl:merge-key element defines one merge key component.] For example, a merge key specification for a log file might specify two merge key components, date and time.

[Definition: A merge key component specifies one component of a merge key specification; it corresponds to a single xsl:merge-key element in the stylesheet.]

[Definition: For each item in a merge input sequence, a value is computed for each merge key component within the merge key specification. The value computed for an item by using the Nth merge key component is referred to as the Nth merge key value of that item.]

[Definition: The ordered collection of merge key values computed for one item in a merge input sequence (one for each merge key component within the merge key specification) is referred to as a composite merge key value.]

15.2 The `xsl:merge` instruction

 <xsl:merge>  </xsl:merge>

The effect of the xsl:merge instruction is to produce a sorted result sequence from a number of pre-sorted input sequences.

The input sequences to the merge operation are defined by the xsl:merge-source child elements, as described in the next section.

The sequence constructor contained in the xsl:merge-action element is evaluated once for each distinct composite merge key value to form a partial result sequence. The result of the xsl:merge instruction is the concatenation of these partial result sequences. For example, the action might be to copy the items from all the input sequences to the result sequence without change; or it might be to select the items from one input sequence in preference to the others. In the general case, the items in the partial result sequence are produced by an arbitrary computation that has access to the items (from the various input sequences) that share the same value for the composite merge key.

The xsl:merge-source and xsl:merge-action elements are described in the following sections.

Any xsl:fallback children of the xsl:merge instruction are ignored by an XSLT 2.1 processor, but are used by an XSLT 1.0 or XSLT 2.0 processor to perform fallback processing.

Note:

An xsl:merge instruction that has no input sequences returns an empty sequence. An xsl:merge instruction with a single input sequence performs processing that is very similar in concept to xsl:for-each-group with the group-adjacent attribute, except that it requires the input to be sorted on the grouping key.

15.3 Selecting the sequences to be merged

<xsl:merge-source select? = expression name? = QName >  </xsl:merge-source>

<xsl:merge-input select? = expression >  </xsl:merge-input>

Each 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 select 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 or sequence constructor of the xsl:merge-input element is evaluated to select the items that make up one merge input sequence.

The select attribute of the xsl:merge-source element is evaluated with the dynamic context of the containing xsl:merge instruction. If the select attribute is omitted, the default value is ., which selects the context item.

The select attribute of xsl:merge-input and the contained sequence constructor are mutually exclusive: if the select attribute is present, the sequence constructor must be empty, and if the sequence constructor is non-empty, the select attribute must be absent.

The select expression or the contained sequence constructor of the xsl:merge-input instruction is evaluated once for each anchor item selected by the containing xsl:merge-source element. Each evaluation produces a sequence, which acts as one of the input sequences for the merge operation. The focus for the evaluation is 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.

Note:

The xsl:merge-key element appears at the end of the sequence constructor because the computation of the merge key takes the result of the sequence constructor as its input.

Example: Merging several documents with the same structure

The following xsl:merge-source element selects two anchor items (the root nodes of two documents), and for each of these it selects an input sequence consisting of selected event elements within the relevant document.

<xsl:merge-source select="doc('log-A.xml'), doc('log-B.xml')">
  <xsl:merge-input select="events/event">
    <xsl:merge-key select="@timestamp" order="ascending"/>
  </xsl:merge-input>
</xsl:merge-source>

This example can be extended to merge any number of input documents with the same structure:

<xsl:merge-source select="collection('log-collection')">
  <xsl:merge-input select="*/event">
    <xsl:merge-key select="@time" order="ascending"/>
  </xsl:merge-input>
</xsl:merge-source>

In both the above examples the anchor items are document nodes, and the items in the input sequence are elements within the document that is rooted at this node. This is a common usage pattern, but by no means the only way in which the construct can be used.

The number of anchor items selected by an xsl:merge-source element, and therefore the number of input sequences, is variable, but the input sequences selected by one xsl:merge-source element must all use the same expressions to select the items in the input sequence and to compute their merge keys. If different expressions are needed for different input sequences, then multiple xsl:merge-source elements can be used.

Example: Merging two documents with different structure

The following code merges two log files having different internal structure:

<xsl:merge-source>
  <xsl:merge-input select="doc('event-log.xml')/*/event">
    <xsl:merge-key select="@timestamp"/>
  </xsl:merge-input>
</xsl:merge-source>
<xsl:merge-source>
  <xsl:merge-input select="doc('error-log.xml')//error">
    <xsl:merge-key select="dateTime(@date, @time)"/>
  </xsl:merge-input>
</xsl:merge-source>

Although the merge keys are computed in different ways for the two input sequences, the keys must be compatible across the two sequences: in this case they are both atomic values of type xs:dateTime.

In the common case where there is only one input sequence of a particular kind, the select attribute of xsl:merge-source may be omitted; its default value is . (dot), which has the effect that the select expression of the xsl:merge-input element is evaluated relative to the focus of the xsl:merge instruction itself.

Example: Sorting before merging

Where one or more of the inputs to the merging process is not pre-sorted, an xsl:perform-sort instruction can be used as a child of xsl:merge-input. For example:

<xsl:merge-source>
  <xsl:merge-input select="doc('event-log.xml')/*/event">
    <xsl:merge-key select="@timestamp"/>
  </xsl:merge-input>
</xsl:merge-source>
<xsl:merge-source>
  <xsl:merge-input>
    <xsl:perform-sort select="doc('error-log.xml')//error">
      <xsl:sort select="@time"/>
    </xsl:perform-sort>
    <xsl:merge-key select="dateTime(current-date(), @time)"/>
  </xsl:merge-input>
</xsl:merge-source>

An xsl:merge-source element has an optional name attribute, whose value is a QName. This name, if specified, may be used while evaluating the xsl:merge-action to identify from which source a particular item was read. For details, see 15.6 Selective processing of merge inputs

[ERR XTSE2185] It is a static error if two sibling xsl:merge-source elements have name attributes whose value is the same expanded QName.

15.4 Defining the merge keys

All the input sequences to the merge operation must be already sorted: the sorting will not be performed by the merge operation. The keys on which the input sequences are sorted are referred to as merge keys.

The merge key for each type of input sequence (that is, for each xsl:merge-source element) is defined by a sequence of xsl:merge-key element children of the xsl:merge-input element. Each xsl:merge-key element defines one merge key component. The syntax and semantics of an xsl:merge-key element are closely based on the rules for the xsl:sort element (the only exception being the absence of the stable attribute); the difference is that xsl:merge-key elements do not cause a sort to take place, they merely declare the existing sort order of the input sequence.

<xsl:merge-key select? = expression lang? = { nmtoken } order? = { "ascending" | "descending" } collation? = { uri } case-order? = { "upper-first" | "lower-first" } data-type? = { "text" | "number" | qname-but-not-ncname } >  </xsl:merge-key>

The select attrbute and the contained sequence constructor are mutually exclusive:

[ERR XTSE2190] It is a static error if an xsl:merge-key element with a select attribute has non-empty content.

The effect of the xsl:merge-key elements is defined in terms of the rules for an equivalent sequence of xsl:sort elements: if the rules for sorting (see 13.1.1 The Sorting Process) with stable="yes" would place an item A before an item B in the sorted sequence produced by the sorting process, then A must precede B in the input sequence to the merging process.

The merge keys of the various input sequences to a merge operation must be compatible with each other, since the merge operation will decide the ordering of the result sequence by comparing merge key values across input sequences. This means that across all the xsl:merge-source children of an xsl:merge instruction:

Each xsl:merge-source element must have the same number of xsl:merge-key grandchild elements; let this number be N
For each integer J in 1..N, consider the set of xsl:merge-key elements that are in position J among the xsl:merge-key children of their parent xsl:merge-input element. All the xsl:merge-key elements in this set must have the same effective value for their lang, order, collation, case-order, and data-type attributes, where having the same effective value in this case means that either both attributes must be absent, or both must be present and evaluate to the same value; and in addition in the case of collation the absolute URI must be the same after resolving against the base URI.

If any of the attributes lang, order, collation, case-order, or data-type are attribute value templates, then their effective values are evaluated using the focus of the containing xsl:merge instruction.

[ERR XTSE2200] It is a static error if the number of xsl:merge-key grandchildren of a xsl:merge-source element is not equal to the number of xsl:merge-key grandchildren of another xsl:merge-source child of the same xsl:merge instruction.

[ERR XTSE2210] It is a static error if there are two xsl:merge-key grandchildren of an xsl:merge instruction that occupy corresponding positions among the xsl:merge-key children of two different xsl:merge-input elements and that have differing effective values for any of the attributes lang, order, collation, case-order, or data-type. Values are considered to differ if the attribute is present on one element and not on the other, or if it is present on both elements with effective values that are not equal to each other. In the case of the collation attribute, the values are compared as absolute URIs after resolving against the base URI.

[ERR XTDE2220] It is a dynamic error if any input sequence to an xsl:merge instruction contains two items that are not correctly sorted according to the merge key values defined on the xsl:merge-key children of the corresponding xsl:merge-input element, when compared using the collation rules defined by the attributes of the corresponding xsl:merge-key children of the xsl:merge instruction.

[ERR XTTE2230] It is a type error if some item selected by a particular merge key in one input sequence is not comparable using the XPath le operator with some item selected by the corresponding sort key in another input sequence.

15.5 The `xsl:merge-action` element

The xsl:merge-action child of an xsl:merge instruction defines the processing to be applied for each distinct set of merge key values found in the input sequences to the xsl:merge instruction.

<xsl:merge-action>  </xsl:merge-action>

The merge key values for each item in an input sequence are calculated based on the corresponding xsl:merge-key elements, in the same way as sort key values are calculated using a sequence of xsl:sort elements (see 13.1.1 The Sorting Process). If several items from the same or from different input sequences have the same values for all their merge keys (comparing pairwise), then they are considered to form a group. The sequence constructor contained in the xsl:merge-action element is evaluated once for each such group of items, and the result of the xsl:merge instruction is the concatenation of the results obtained by processing each group in turn.

The groups are processed one by one, based on the values of the merge keys for the group. If group G has a set of merge key values M, while group H has a set of merge key values N, then in the result of the xsl:merge instruction, the result of processing group G will precede the result of processing H if and only if M precedes N in the sort order defined by the lang, order, collation, case-order, and data-type attributes of the merge key definitions.

Generally, two sets of sort key values are distinct if any corresponding items in the two sets of values do not compare equal under the rules for the XPath eq operator, under the collating rules for the corresponding merge key definition. In rare cases, when considering more than two sets of sort key values, ambiguities may arise because of the non-transitivity of the eq operator when applied across different numeric types. In this situation, the partitioning of items into sets having distinct key values is handled in the same way as for xsl:for-each-group (see 14.5 Non-Transitivity), and is to some extent implementation-dependent.

While evaluating the sequence constructor contained within the xsl:merge-action element, the expression current-grouping-key()[N] returns the value of the Nth merge key. There may be several input items having merge keys that are equal but distinguishable (for example the number 1.0 as a float and as a double, or the strings "A" and "a" under a case-blind collation); in this case the result of the current-grouping-key is the value of the grouping key computed for the first item in the current group, after atomization and casting of xs:untypedAtomic to xs:string.

While evaluating the sequence constructor contained within the xsl:merge-action element, the function current-group() (with no arguments) returns the set of items (zero or more from each input sequence) that have this set of values as their merge key value. It is possible to distinguish which items came from which merge source: see 15.6 Selective processing of merge inputs.

Within the result of the current-group function, the ordering of items from the input sequences is as follows, in major-to-minor order:

Items are first ordered by the xsl:merge-source element that defined the input sequence from which the item was taken; items from xsl:merge-source A precede items from xsl:merge-source B if A precedes B in document order within the stylesheet.
Items from different input sequences selected by the same xsl:merge-source element are then ordered based on the order of the anchor items in the sequence selected by evaluating the select attribute of the xsl:merge-source element.
Finally, duplicate items from the same input sequence retain their order from the input sequence.

The focus for evaluation of the sequence constructor contained in the xsl:merge-source element is as follows:

The context item is the first item in the current group, that is current-group()[1]
The context position is the position of the current group within the sequence of groups (so the first evaluation of xsl:merge-action has position()=1, the second has position()=2, and so on).
The context size is the number of groups, that is, the number of distinct sets of merge key values.

15.6 Selective processing of merge inputs

During the processing of xsl:merge-action, there will in general be one or more items with the same values for their merge keys, together forming the current group. Within the current group, each item originates from one merge input, which in turn is associated with one merge source. A merge source may be identified by a QName (the value of the name attribute on the xsl:merge-source element). For each merge source, there are zero or more merge inputs, which are identified by positive integers representing the position of the anchor item for the merge input within the sequence of anchor items selected by the select attribute of the xsl:merge-source element. Since duplicate merge keys are allowed within a single input, each merge input contributes zero or more items to the current group.

The function current-merge-inputs may be used to obtain the items within the current group that are associated with each named merge source, and with each merge input within that source. The function takes as input the name of the merge source (as a lexical QName, expanded using the in-scope namespaces from the static context), and it returns a sequence of accessors, one accessor for each merge input within the merge source, corresponding one-to-one with the sequence of anchor items selected by the select attribute of the xsl:merge-source element. Each accessor is a zero-argument anonymous function which when invoked returns the sequence of zero or more items (each a member of the current group) that derive from the corresponding merge input.

Example: Selective processing of merge inputs

Consider a situation where there are two merge sources, named "master" and "update"; the master source identifies a single merge input file (the master file), while the update source identifies a set of N update files, perhaps one for each day of the week. The required logic is that if a merge key is present only in the master file, then the corresponding item should be copied to the output; if it is present in a single update file then that item replaces the corresponding item from the master file; if it is present in several update files, then an error is raised. This can be achieved as follows:

<xsl:merge>
  <xsl:merge-source name="master" select="doc('master.xml')">
    <xsl:merge-input select="/*/*">
      <xsl:merge-key select="@key"/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source name="update" select="collection('updates')">
    <xsl:merge-input select="/*/*">
      <xsl:merge-key select="@affected-key"/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:variable name="update-accessors" 
                  select="current-merge-inputs('update')"
                  as="(function() as item()*)*"/>
    <xsl:variable name="number-of-updates" 
                  select="count($update-accessors[exists(.())])"
                  as="xs:integer"/>
    <xsl:choose>
      <xsl:when test="$number-of-updates = 0">
        <xsl:copy-of select="current-merge-inputs('master')()"/>
      </xsl:when>
      <xsl:when test="$number-of-updates = 1">
        <xsl:copy-of select="for $a in $update-accessors return $a()"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:message>
           Multiple updates for the same master record!
        </xsl:message>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:merge-action>
</xsl:merge>

Some words of explanation:

The variable $number-of-updates is computed as the number of accessors for the update source, filtered to select only those for which the accessor returns a non-empty sequence. The expression .() invokes the accessor that is the current item.
The expression current-merge-inputs('master') obtains a sequence of accessors for all the merge inputs associated with the master source. There is only one, so it returns a single accessor, which is invoked directly (using ()) to obtain the item in the master file.
The expression for $a in $update-accessors return $a() invokes all the accessors associated with the update source, and concatenates their results; although all but one of the accessors will return an empty sequence, this is a convenient way of obtaining the one sequence that is non-empty.

The function current-merge-inputs is defined as follows:

current-merge-inputs( $source-name as xs:string) as (function() as item()*)

The function takes as input the name of a merge source, expressed as a lexical QName

[ERR XTDE2240] It is a non-recoverable dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName, or if the name obtained by expanding the QName is not the same as the expanded name of any xsl:merge-source element in the current merge activation, or if there is no current merge activation. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

[Definition: During each evaluation of the sequence constructor contained in an xsl:merge-action element, there is a current merge activation.]

The current merge activation has the following properties:

The xsl:merge element M that is the parent of the xsl:merge-action element being evaluated
A mapping SA from each xsl:merge-source child of M to the sequence of anchor items selected by evaluating the (implicit or explicit) select expression on that xsl:merge-source element
A current composite merge key value

Issue 18 (current-merge-activation):

The concept of the current-merge-activation needs to be and incorporated into the dynamic context.

For each anchor item A in the mapping SA, there is an associated merge input sequence obtained by evaluating the select expression of the xsl:merge-input child of the corresponding xsl:merge-source element with A as the context item.

The current-merge-inputs function returns a sequence of function items, referred to as accessors. Each accessor is an anonymous function with an arity of zero. The sequence of accessors corresponds one-to-one with the sequence of anchor items defined by the mapping SA for the selected xsl:merge-source in the current merge activation. Invoking the Nth accessor function returns selected items from the merge input sequence associated with the Nth anchor item in this sequence. The selected items are those whose whose composite merge key value is equal to the composite merge key value of the current merge activation. The selected items are returned retaining their order from the merge input sequence.

15.7 Merging streamed input documents

An important reason for introducing the xsl:merge instruction is to allow elements from several input documents to be merged without constructing the entire tree representation of the input documents in memory. This can be achieved by using xsl:merge in conjunction with the xsl:stream instruction defined in 18 Streaming.

Example: Merging two streamed documents with different structure

The following code merges two log files having different internal structure:

<xsl:merge>
  <xsl:merge-source>
    <xsl:merge-input>
      <xsl:merge-key select="@timestamp"/>
      <xsl:stream href="event-log.xml">
        <xsl:copy-of select="*/event"/>
      </xsl:stream>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source>
    <xsl:merge-input>
      <xsl:merge-key select="dateTime(@date, @time)"/>
      <xsl:stream href="error-log.xml">
        <xsl:copy-of select="*/event"/>
      </xsl:stream>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:sequence select="current-group()"/>
  </xsl:merge-action>
</xsl:merge>

Within the xsl:stream instructions, it is necessary to use xsl:copy-of rather than xsl:sequence because the xsl:stream instruction is not allowed to return streamed nodes. An intelligent optimizer might be able to use streaming to execute this code, avoiding the need to copy the event elements to temporary trees held in memory.

Example: Merging a collection of streamed documents

The following code merges the top-level elements (that is, the children of the outermost element) of a collection of input documents into a single result document.

<xsl:merge>
  <xsl:merge-source select="uri-collection('log-collection')">
    <xsl:merge-input>
      <xsl:merge-key select="@timestamp" order="ascending"/>
      <xsl:stream href="{.}">
        <xsl:copy-of select="events/event"/>
      </xsl:stream>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:sequence select="current-group()"/>
  </xsl:merge-action>
</xsl:merge>

In this example the uri-collection function is used to retrieve the document URIs of the documents in a collection, without retrieving the documents themselves. These URIs are used as the anchor items of the xsl:merge-source, and the individual input sequences are selected from these URIs by using the xsl:stream instruction. As with the previous example, an intelligent optimizer might avoid building each event element as a tree in memory.

15.8 Examples of xsl:merge

Previous sections introduced examples designed to illustrate some specific features of the xsl:merge instruction. This section provides some further examples to illustrate different ways in which the instruction can be used.

Example: Applying transactions to a master file

This example applies transactions from a transaction file to a master file. Records in the master file for which there is no corresponding transaction are copied unchanged. The transaction file contains instructions to delete, replace, or insert records identified by an ID value. The master file is known to be sorted on the ID value; the transaction file is unsorted.

Master file document structure:

<data>
  <record ID="A0001"><...></record>
  <record ID="A0002"><...></record>
  <record ID="A0003"><...></record>
</data>

Transaction file document structure:

<transactions>
  <update record="A0004" action="insert"><...></update>
  <update record="A0002" action="delete"/>
  <update record="A0003" action="replace"><...></update>
</transactions>

Solution:

<xsl:merge>
  <xsl:merge-source select="doc('master.xml')" name="master">
    <xsl:merge-input select="data/record">
      <xsl:merge-key select="@ID"/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source name="updates">
    <xsl:merge-input>      
      <xsl:perform-sort select="
              doc('transactions.xml')/transactions/update">
        <xsl:sort select="@record" order="ascending"/>
      </xsl:perform-sort>
      <xsl:merge-key select="@record"/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:variable name="master" select="current-group('master')"/>
    <xsl:variable name="update" select="current-group('updates')"/>
    <xsl:choose>
      <xsl:when test="empty($update)">
        <xsl:copy-of select="$master"/>
      </xsl:when>
      <xsl:when test="$update/@action=('insert', 'replace')">
        <record ID="{current-grouping-key()}">
          <xsl:copy-of select="$update/*"/>
        </record>
      </xsl:when>
      <xsl:when test="$update/@action='delete'"/>
    </xsl:choose>
  </xsl:merge-action>
  </xsl:merge>

If there are multiple transaction files, represented say by the contents of a collection named transaction-files.collection, they can be handled by replacing the second xsl:merge-source in the above example with the following code:

  <xsl:merge-source name="updates" 
         select="collection('transaction-files.collection')">
    <xsl:merge-input>
      <xsl:perform-sort select="/transactions/update">
        <xsl:sort select="@record" order="ascending"/>
      </xsl:perform-sort>
      <xsl:merge-key select="@record"/>
    </xsl:merge-input>
  </xsl:merge-source>

Example: Merging two sequences of numbers

The xsl:merge instruction can be used to determine the union, intersection, or difference of two sequences of numbers (or other atomic values). This code gives the union:

<xsl:merge>
  <xsl:merge-source>                  
    <xsl:merge-input select="1 to 30">
      <xsl:merge-key select="."/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source>                  
    <xsl:merge-input select="20 to 40">
      <xsl:merge-key select="."/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:value-of select="current-grouping-key()"/>
  </xsl:merge-action>
</xsl:merge>

While this gives the intersection:

<xsl:merge>
  <xsl:merge-source>                  
    <xsl:merge-input select="1 to 30">
      <xsl:merge-key select="."/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source>                  
    <xsl:merge-input select="20 to 40">
      <xsl:merge-key select="."/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:if test="count(current-group()) eq 2"
      <xsl:value-of select="current-grouping-key()"/>
    </xsl:if>
  </xsl:merge-action>
</xsl:merge>

16 Splitting

16.1 Introduction

Sometimes it is convenient to be able to compute multiple results during a single scan of the input data. For example, a transformation may wish to rename selected elements, and also to output a count of how many elements have been renamed. Traditionally in a functional language this means computing two separate functions of the input sequence, which (in the absence of sophisticated optimization) will result in the input being scanned twice. This is inconsistent with streaming, where the input is only available to be scanned once, and it can also lead to poor performance in non-streaming applications.

To meet this requirement, XSLT 2.1 introduces the instruction xsl:fork. The content of this instruction is a sequence constructor, and in a formal sense the effect of the instruction is simply to return the result of evaluating the sequence constructor. However, the presence of the instruction affects the analysis of streamability (see 18.4 Streamability Analysis). In particular, when xsl:fork is used in a context where streaming is required, each independent instruction within the sequence constructor must be streamable, but the analysis assumes that these instructions can all be evaluated during a single pass of the streamed input document.

Note:

The semantics of the instruction require a number of result sequences to be computed during a single pass of the input. A processor may interpret this as a request to use multiple threads. However, implementations using a single thread are feasible, and this instruction is not intended primarily as a means for stylesheet authors to express their intentions with regard to multi-threaded execution.

Note:

Because multiple results are computed during a single pass of the input, and then concatenated into a single sequence, this instruction will generally involve some buffering of results. The amount of memory used should not exceed that needed to hold the results of the instruction. However, within this principle, implementations may adopt a variety of strategies for evaluation; for example, there may be cases where buffering of the input is more efficient than buffering of output.

Generally, stylesheet authors indicate that buffering of input is the preferred strategy by using the copy-of or snapshot functions, and indicate that buffering of output is preferred by using xsl:fork. However, conformant processors are not constrained in their choice of evaluation strategies.

Example: Splitting a transaction file

Consider a transaction file that contains a sequence of debits and credits:

<transactions>
  <transaction value="5.60"/>
  <transaction value="11.20"/>
  <transaction value="-3.40"/>
  <transaction value="8.90"/>
  <transaction value="-1.99"/>
</transactions>

where the requirement is to split this into two separate files containing credits and debits respectively.

This can be achieved in guaranteed-streamable code as follows:

<xsl:stream href="transactions.xml">
  <xsl:fork>
    <xsl:result-document name="credits.xml">
      <credits>
        <xsl:copy-of select="transactions/transaction[@value ge 0]"/>
      </credits>
    </xsl:result-document>
    <xsl:result-document name="debits.xml">
      <debits>
        <xsl:copy-of select="transactions/transaction[@value lt 0]"/>
      </debits>
    </xsl:result-document>
  </xsl:fork>
</xsl:stream>

In the absence of the xsl:fork instruction, this would not be streamable, because the construct includes two downwards selections in the input document (represented by the path expressions transactions/transaction[@value ge 0] and transactions/transaction[@value lt 0]). With the addition of the xsl:fork instruction, however, each xsl:result-document instruction is allowed to make a downwards selection.

One possible implementation model for this is as follows: a single thread reads the source document, and sends parsing events such as start-element and end-element to two other threads, each of which is writing one of the two result documents. Each of these implements the downwards-selecting path expression using a process that waits until the next transaction start-element event is received; when this event is received, the process examines the @value attribute to determine whether or not this transaction is to be copied; if it is, then all events until the matching transaction end-element event are copied to the serializer for the result document; otherwise, these events are discarded.

The xsl:sequence instruction may be used as a child of xsl:fork to break the instructions within xsl:fork into a number of separate groups, each of which is considered as (and indeed is) a separate instruction operating in a single pass over the data.

The following section describes the xsl:fork instruction more formally.

16.2 The `xsl:fork` instruction

 <xsl:fork>  </xsl:fork>

The result of the xsl:fork instruction is the result of evaluating its contained sequence constructor.

[Definition: Among the instructions directly contained in a sequence constructor, an instruction I is defined to be dependent on an instruction J if J is a variable binding and I contains a reference to that variable, or if there is an instruction K such that I depends on K and K depends on J.]

[Definition: Two instructions with a sequence constructor are defined to be independent if neither depends on the other.]

By using the xsl:fork instruction, the stylesheet author is suggesting to the processor that it would be beneficial to evaluate independent instructions during a single pass of a streamed input document. The processor is not required to take any notice of this suggestion.

The presence of an xsl:fork instruction affects the analysis of streamability, as described in 18.4 Streamability Analysis.

16.3 Examples of splitting with streamed data

This section gives examples of how splitting using xsl:fork can be used to enable streaming of input documents in cases where several results need to be computed during a single pass over the input data.

Example: Deleting elements, and counting deletions

In this example the input is a narrative document containing note elements at any level of nesting. The requirement is to output a copy of the input document in which (a) the note elements have been removed, and (b) a footnote is added at the end indicating how many note elements have been deleted.

<xsl:mode on-no-match="copy" streamable="yes"/>

<xsl:template match="note"/>

<xsl:template match="/*">
  <xsl:fork>
    <xsl:apply-templates/>
    <footnote>
      <p>Removed <xsl:value-of select="count(.//note)"/> 
                 note elements.</p>
    </footnote>
  </xsl:fork>
</xsl:template>

The xsl:fork instruction contains two independent instructions in its sequence constructor. These can therefore be evaluated in the same pass over the input data. The first instruction (the xsl:apply-templates instruction) causes everything except the note elements to be copied to the result; the second instruction (the literal result element footnote) outputs a count of the number of descendant note elements.

Note that although the processing makes a single pass over the input stream, there is some buffering of results required, because the results of the instructions within the xsl:fork instruction need to be concatenated. In this case an intelligent implementation might be able to restrict the buffered data to a single integer.

In a formal sense, however, the result is exactly the same as if the xsl:fork element were not there.

Example: Statistical analysis of a document

This example computes the proportion of the words in a document that are contained in headings and in footnotes. It does this in a single streaming pass of the input document.

<xsl:template match="doc">
  <xsl:fork>
    <xsl:variable name="wordCount" 
            select="count(.//text()/tokenize(., '\s+'))"/>
    <xsl:variable name="footnoteWordCount" 
            select="count(.//footnote/text()/tokenize(., '\s+'))"/>
    <xsl:variable name="headingWordCount" 
            select="count(.//heading/text()/tokenize(., '\s+'))"/>
    <result metric="proportion of words in footnotes" 
            value="{$footnoteWordCount div $wordCount}"/>
    <result metric="proportion of words in headings" 
            value="{$headingWordCount div $wordCount}"/>
  </xsl:fork>
</xsl:template>

In this example, there are five instructions within the xsl:fork instruction. The three variable bindings are independent of each other, and can therefore be evaluated in a single pass through the streamed input document. The two literal result elements cannot be evaluated until the values of the relevant variables are available; but they do not access the source document, and therefore do not place any constraints on streamability.

17 Regular Expressions

The core function library for XPath 2.1 defines three basic functions that make use of regular expressions:

matches^FO returns a boolean result that indicates whether or not a string matches a given regular expression.
replace^FO takes a string as input and returns a string obtained by replacing all substrings that match a given regular expression with a replacement string.
tokenize^FO returns a sequence of strings formed by breaking a supplied input string at any separator that matches a given regular expression.

These functions are described in [Functions and Operators].

For more complex string processing than is possible using these functions, XSLT provides an instruction xsl:analyze-string, which is defined in this section.

The regular expressions used by this instruction, and the flags that control the interpretation of these regular expressions, must conform to the syntax defined in [Functions and Operators] (see Section 7.6.1 Regular Expression Syntax^FO), which is itself based on the syntax defined in [XML Schema Part 2].

Note:

XPath 2.1 adds a fourth function, analyze-string^FO, whose functionality is closely modeled on the xsl:analyze-string instruction described in this section, repackaging the facilities in the form of a function.

17.1 The `xsl:analyze-string` instruction

 <xsl:analyze-string select = expression regex = { string } flags? = { string } >  </xsl:analyze-string>

<xsl:matching-substring>  </xsl:matching-substring>

<xsl:non-matching-substring>  </xsl:non-matching-substring>

The xsl:analyze-string instruction takes as input a string (the result of evaluating the expression in the select attribute) and a regular expression (the effective value of the regex attribute).

If the result of evaluating the select expression is not a string, it is converted to a string by applying the function conversion rules.

The flags attribute may be used to control the interpretation of the regular expression. If the attribute is omitted, the effect is the same as supplying a zero-length string. This is interpreted in the same way as the $flags attribute of the functions matches^FO, replace^FO, and tokenize^FO. Specifically, if it contains the letter m, the match operates in multiline mode. If it contains the letter s, it operates in dot-all mode. If it contains the letter i, it operates in case-insensitive mode. If it contains the letter x, then whitespace within the regular expression is ignored. For more detailed specifications of these modes, see [Functions and Operators] (Section 7.6.1.1 Flags^FO).

Note:

Because the regex attribute is an attribute value template, curly brackets within the regular expression must be doubled. For example, to match a sequence of one to five characters, write regex=".{{1,5}}". For regular expressions containing many curly brackets it may be more convenient to use a notation such as regex="{'[0-9]{1,5}[a-z]{3}[0-9]{1,2}'}", or to use a variable.

The xsl:analyze-string instruction may have two child elements: xsl:matching-substring and xsl:non-matching-substring. Both elements are optional, and neither may appear more than once. At least one of them must be present. If both are present, the xsl:matching-substring element must come first.

The content of the xsl:analyze-string instruction must take one of the following forms:

A single xsl:matching-substring instruction, followed by zero or more xsl:fallback instructions
A single xsl:non-matching-substring instruction, followed by zero or more xsl:fallback instructions
A single xsl:matching-substring instruction, followed by a single xsl:non-matching-substring instruction, followed by zero or more xsl:fallback instructions

[ERR XTSE1130] It is a static error if the xsl:analyze-string instruction contains neither an xsl:matching-substring nor an xsl:non-matching-substring element.

Any xsl:fallback elements among the children of the xsl:analyze-string instruction are ignored by an XSLT 2.0 or 2.1 processor, but allow fallback behavior to be defined when the stylesheet is used with an XSLT 1.0 processor operating with forwards-compatible behavior.

This instruction is designed to process all the non-overlapping substrings of the input string that match the regular expression supplied.

[ERR XTDE1140] It is a non-recoverable dynamic error if the effective value of the regex attribute does not conform to the required syntax for regular expressions, as specified in [Functions and Operators]. If the regular expression is known statically (for example, if the attribute does not contain any expressions enclosed in curly brackets) then the processor may signal the error as a static error.

[ERR XTDE1145] It is a non-recoverable dynamic error if the effective value of the flags attribute has a value other than the values defined in [Functions and Operators]. If the value of the attribute is known statically (for example, if the attribute does not contain any expressions enclosed in curly brackets) then the processor may signal the error as a static error.

[ERR XTDE1150] It is a non-recoverable dynamic error if the effective value of the regex attribute is a regular expression that matches a zero-length string: or more specifically, if the regular expression $r and flags $f are such that matches("", $r, $f) returns true. If the regular expression is known statically (for example, if the attribute does not contain any expressions enclosed in curly brackets) then the processor may signal the error as a static error.

The xsl:analyze-string instruction starts at the beginning of the input string and attempts to find the first substring that matches the regular expression. If there are several matches, the first match is defined to be the one whose starting position comes first in the string. If several alternatives within the regular expression both match at the same position in the input string, then the match that is chosen is the first alternative that matches. For example, if the input string is The quick brown fox jumps and the regular expression is jump|jumps, then the match that is chosen is jump.

Having found the first match, the instruction proceeds to find the second and subsequent matches by repeating the search, starting at the first character that was not included in the previous match.

The input string is thus partitioned into a sequence of substrings, some of which match the regular expression, others which do not match it. Each substring will contain at least one character. This sequence of substrings is processed using the instructions within the contained xsl:matching-substring and xsl:non-matching-substring elements. A matching substring is processed using the xsl:matching-substring element, a non-matching substring using the xsl:non-matching-substring element. Each of these elements takes a sequence constructor as its content. If the element is absent, the effect is the same as if it were present with empty content. In processing each substring, the contents of the substring will be the context item (as a value of type xs:string); the position of the substring within the sequence of matching and non-matching substrings will be the context position; and the number of matching and non-matching substrings will be the context size.

If the input is a zero-length string, the number of substrings will be zero, so neither the xsl:matching-substring nor xsl:non-matching-substring elements will be evaluated.

17.2 Captured Substrings

regex-group($group-number as xs:integer) as xs:string

[Definition: While the xsl:matching-substring instruction is active, a set of current captured substrings is available, corresponding to the parenthesized sub-expressions of the regular expression.] These captured substrings are accessible using the function regex-group. This function takes an integer argument to identify the group, and returns a string representing the captured substring.

The Nth captured substring (where N > 0) is the string matched by the subexpression contained by the Nth left parenthesis in the regex, excluding any non-capturing groups, which are written as (?:xxx). The zeroeth captured substring is the string that matches the entire regex. This means that the value of regex-group(0) is initially the same as the value of . (dot).

The function returns the zero-length string if there is no captured substring with the relevant number. This can occur for a number of reasons:

The number is negative.
The regular expression does not contain a parenthesized sub-expression with the given number.
The parenthesized sub-expression exists, and did not match any part of the input string.
The parenthesized sub-expression exists, and matched a zero-length substring of the input string.

The set of captured substrings is a context variable with dynamic scope. It is initially an empty sequence. During the evaluation of an xsl:matching-substring instruction it is set to the sequence of matched substrings for that regex match. During the evaluation of an xsl:non-matching-substring instruction or a pattern or a stylesheet function it is set to an empty sequence. On completion of an instruction that changes the value, the variable reverts to its previous value.

The value of the current captured substrings is unaffected through calls of xsl:apply-templates, xsl:call-template, xsl:apply-imports or xsl:next-match, or by expansion of named attribute sets.

17.3 Examples of Regular Expression Matching

Example: Replacing Characters by Elements

Problem: replace all newline characters in the abstract element by empty br elements:

Solution:

<xsl:analyze-string select="abstract" regex="\n">
  <xsl:matching-substring>
    <br/>
  </xsl:matching-substring>
  <xsl:non-matching-substring>
    <xsl:value-of select="."/>
  </xsl:non-matching-substring>
</xsl:analyze-string>

Example: Recognizing non-XML Markup Structure

Problem: replace all occurrences of [...] in the body by cite elements, retaining the content between the square brackets as the content of the new element.

Solution:

<xsl:analyze-string select="body" regex="\[(.*?)\]">
  <xsl:matching-substring>
    <cite><xsl:value-of select="regex-group(1)"/></cite>
  </xsl:matching-substring>
  <xsl:non-matching-substring>
    <xsl:value-of select="."/>
  </xsl:non-matching-substring>
</xsl:analyze-string>

Note that this simple approach fails if the body element contains markup that needs to be retained. In this case it is necessary to apply the regular expression processing to each text node individually. If the [...] constructs span multiple text nodes (for example, because there are elements within the square brackets) then it probably becomes necessary to make two or more passes over the data.

Example: Parsing a Date

Problem: the input string contains a date such as 23 March 2002. Convert it to the form 2002-03-23.

Solution (with no error handling if the input format is incorrect):

<xsl:variable name="months" 
        select="'January', 'February', 'March', ..."/>

<xsl:analyze-string select="normalize-space($input)" 
    regex="([0-9]{{1,2}})\s([A-Z][a-z]+)\s([0-9]{{4}})">
    <xsl:matching-substring>
        <xsl:number value="regex-group(3)" format="0001"/>          
        <xsl:text>-</xsl:text>
        <xsl:number value="index-of($months, regex-group(2))" format="01"/>
        <xsl:text>-</xsl:text>
        <xsl:number value="regex-group(1)" format="01"/>
    </xsl:matching-substring>
</xsl:analyze-string>

Note the use of normalize-space to simplify the work done by the regular expression, and the use of doubled curly brackets because the regex attribute is an attribute value template.

18 Streaming

This specification provides a number of facilities designed to enable streaming: that is, transformation of a source document on-the-fly, as it is parsed, without constructing a complete tree representation of the document in memory.

These facilities include:

The xsl:stream instruction, which reads an external document (identified by URI) and initiates streaming of that document.
Streaming templates, which allow rule-based invocation of template rules applied to the nodes in a streamed document.

These facilities impose constraints on the stylesheet code to ensure that a streamable evaluation is possible. Much of this section is concerned with the definition of the rules for streamability.

[Definition: A guaranteed-streamable construct is a construct that follows the rules given in 18.4 Streamability Analysis. Every processor that claims conformance as a streaming processor must be able to process such a construct using streaming, that is, by processing the contents of the source document on the fly as it is read, without the need to buffer the entire document or any entire element in memory. ]

In certain contexts, in particular the xsl:stream instruction and a template rule whose mode is declared with streamable="yes", the stylesheet author has the opportunity to request that evaluation should using streaming. In this case the rules are as follows:

For a streaming processor:

If the construct conforms to the rules for being guaranteed-streamable then it must be processed using streaming.
If the construct is not guaranteed-streamable then it must still be processed: the specification imposes no rules on how it is processed (it might or might not use streaming).
If the evaluation does not use streaming (which will only happen if the construct is not guaranteed-streamable) then the processor should signal a warning indicating that streaming was not possible; the processor may provide a user option to abandon processing in this case.

For a non-streaming processor, the processor must evaluate the construct delivering the same results as if execution used streaming, but with no constraints on the evaluation strategy. (Processing may, of course, fail due to insufficient memory being available, or for other reasons.)

Note:

This specification does not attempt to legislate precisely what constitutes evaluation "using streaming". The most important test is that the amount of memory needed should be for practical purposes independent of the size of the source document, and in particular that the finite size of memory available should not impose a limit on the size of source document that can be processed.

The rules are designed to ensure that streaming processors can analyze streamability using rules different from those in this specification, provided that all constructs that are guaranteed-streamable according to this specification are actually streamable by the implementation. Furthermore, non-streaming processors are not required to analyze streamability at all.

18.1 The `xsl:stream` instruction

 <xsl:stream href = { uri-reference } >  </xsl:stream>

The xsl:stream instruction reads a source document whose URI is supplied, and processes the content of the document using streaming by evaluating the contained sequence constructor.

For example, if a document represents a book holding a sequence of chapters, then the following code can be used to split the book into multiple XML files, one per chapter, without allocating memory to hold the entire book in memory at one time:

<xsl:stream href="book.xml">
  <xsl:for-each select="book/chapter">
    <xsl:result-document href="chapter{position()}.xml">
      <xsl:copy-of select="."/>
    </xsl:result-document>
  </xsl:for-each>
</xsl:stream>

The document to be read is determined by the effective value of the href attribute (which is defined as an attribute value template). This 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:stream element. The process of obtaining a document node given a URI is the same as for the doc^FO function. However, unlike the doc^FO function, the xsl:stream 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).

Specifically, if the xsl:stream instruction is evaluated several times (or if different xsl:stream instructions are evaluated) with the same URI (after making it absolute) as the value of the href attribute, it is implementation-dependent whether the same nodes or different nodes are returned on each occasion; it is also possible that the actual document content will be different.

The result of the xsl:stream instruction is the same as the result of the following (non-streaming) process:

The source document is read from the supplied URI and parsed to form an instance of the XDM data model. This is the streamed document.
The contained sequence constructor is evaluated with the document node of the streamed document as the context item, and with the context position and context size set to one, and the resulting sequence is returned as the result of the xsl:stream instruction.

Note:

The rules for streamability ensure that the sequence constructor (and therefore the xsl:stream instruction) cannot return any nodes from the streamed document. For example, it cannot contain the instruction <xsl:sequence select="//chapter"/>. If nodes from this document are to be returned, they must first be copied, for example by using the xsl:copy-of instruction or by calling the copy-of or snapshot functions.

Because the xsl:stream instruction cannot return nodes from the streamed document, any nodes it does return will be conventional (unstreamed) nodes that can be processed without restriction. For example, if xsl:stream is invoked within a stylesheet function f:firstChapter, and the sequence constructor consists of the instruction <xsl:copy-of select="//chapter"/>, then the calling code can manipulate the resulting chapter elements as ordinary trees rooted at parentless element nodes.

18.1.1 Examples of `xsl:stream`

The xsl:stream instruction can be used to initiate processing of a document using streaming with a variety of coding styles, illustrated in the examples below.

Example: Using xsl:stream with aggregate functions

The following example computes the number of transactions in a transaction file

Input:

<transactions>
  <transaction value="12.51"/>
  <transaction value="3.99"/>
</transactions>

Stylesheet code:

<xsl:stream href="transactions.xml">
  <count>
    <xsl:value-of select="count(transactions/transaction)"/>
  </count>
</xsl:stream>

Result:

<count>2</count>

The following example computes the highest-value transaction in the same input file:

<xsl:stream href="transactions.xml">
  <maxValue>
    <xsl:value-of select="max(transactions/transaction/@value)"/>
  </maxValue>
</xsl:stream>

Result:

<maxValue>12.51</maxValue>

To compute both the count and the maximum value in a single pass over the input, it is necessary to use xsl:fork:

<xsl:stream href="transactions.xml">
  <xsl:fork>
    <count>
      <xsl:value-of select="count(transactions/transaction)"/>
    </count>
    <maxValue>
      <xsl:value-of select="max(transactions/transaction/@value)"/>
    </maxValue>
  </xsl:fork>
</xsl:stream>

Example: Using xsl:stream with xsl:for-each to process a collection of input documents

This example displays a list of the chapter titles extracted from each book in a collection of books.

Each input document is assumed to have a structure such as:

<book>
  <chapter number-of-pages="18">
    <title>The first chapter of book A</title>
    ...
  </chapter>
  <chapter number-of-pages="15">
    <title>The second chapter of book A</title>
    ...
  </chapter>
  <chapter number-of-pages="12">
    <title>The third chapter of book A</title>
    ...
  </chapter>
</book>

Stylesheet code:

<chapter-titles>
  <xsl:for-each select="uri-collection('books')">
    <xsl:stream href="{.}">
      <xsl:for-each select="book/chapter">
        <title><xsl:value-of select="title"/></title>
      </xsl:for-each>
    </xsl:stream>
  </xsl:for-each>
</chapter-titles>

Output:

<chapter-titles>
  <title>The first chapter of book A</title>
  <title>The second chapter of book A</title>
  ...
  <title>The first chapter of book B</title>
  ...
</chapter-titles>

Note:

This example uses the function uri-collection to obtain the document URIs of all the documents in a collection, so that each one can be processed in turn using xsl:stream.

Example: Using xsl:stream with xsl:iterate

This example assumes that the input is a book with multiple chapters, as shown in the previous example, with the page count for each chapter given as an attribute of the chapter. The transformation determines the starting page number for each chapter by accumulating the page counts for previous chapters, and rounding up to an odd number if necessary.

<chapter-start-page>
   <xsl:stream href="book.xml">
      <xsl:iterate select="book/chapter">
         <xsl:param name="start-page" select="1"/>
         <chapter title="{title}" start-page="{$start-page}"/>
         <xsl:next-iteration>
            <xsl:with-param name="start-page" 
                            select="$start-page + @number-of-pages + 
                                      (@number-of-pages mod 2)"/>
         </xsl:next-iteration>
      </xsl:iterate>
   </xsl:stream>
</chapter-start-page>

Output:

<chapter-start-page>
  <chapter title="The first chapter of book A" start-page="1"/>
  <chapter title="The second chapter of book A" start-page="19"/>
  <chapter title="The third chapter of book A" start-page="35"/>
  ...
</chapter-start-page>

Example: Using xsl:stream with xsl:for-each-group

This example assumes that the input is a book with multiple chapters, and that each chapter belongs to a part, which is present as an attribute of the chapter (for example, chapters 1-4 might constitute Part 1, the next three chapters forming Part 2, and so on):

<book>
  <chapter part="1">
    <title>The first chapter of book A</title>
    ...
  </chapter>
  <chapter part="1">
    <title>The second chapter of book A</title>
    ...
  </chapter>
  ...
  <chapter part="2">
    <title>The fifth chapter of book A</title>
    ...
  </chapter>
</book>

The transformation copies the full text of the chapters, creating an extra level of hierarchy for the parts.

<book>
   <xsl:stream href="book.xml">
      <xsl:for-each-group select="book/chapter" group-adjacent="@part">
         <part number="{current-grouping-key()}">
            <xsl:copy-of select="current-group()"/>
         </part>
      </xsl:for-each-group>
   </xsl:stream>
</book>

Output:

<book>
  <part number="1">
    <chapter title="The first chapter of book A" part="1">
      ...
    </chapter>
    <chapter title="The second chapter of book A" part="1">
      ...
    </chapter>
    ...
  </part>
  <part number="2">
    <chapter title="The fifth chapter of book A" part="2">
    ...
    </chapter>
    ...
  </part>
</book>

Example: Using xsl:stream with xsl:apply-templates

This example copies an XML document while deleting all the ednote elements at any level of the tree, together with their descendants. This example is a complete stylesheet, which is intended to be evaluated by nominating main as the initial template. The use of on-no-match="copy" in the xsl:mode declaration means that the built-in template rule copies nodes unchanged, except where overridden by a user-defined template rule.

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

<xsl:mode name="delete-ednotes" streaming="yes" on-no-match="copy"/>

<xsl:template name="main">
   <xsl:stream href="book.xml">
      <xsl:apply-templates mode="delete-ednotes"/>
   </xsl:stream>
</xsl:template>

<xsl:template match="ednote" mode="delete-ednotes"/>

</xsl:transform>

Additional template rules could be added to process other elements and attributes in the same pass through the data: for example, to modify the value of a last-updated attribute (wherever it appears) to the current date and time, the following rule suffices:

<xsl:template match="@last-updated">
  <xsl:attribute name="last-updated" select="current-dateTime()"/>
</xsl:template>

Example: Using xsl:stream with xsl:merge

This example builds a file representing the index of a book from files containing the index for each chapter. The chapter-level index files contain entries of the form <entry term="XML" page="27"/> sorted first alphabetically by term and then numerically by page number; the sort order for the combined index is the same.

<index>
   <xsl:merge>
     <xsl:merge-source select="uri-collection('chapter-indexes')">
       <xsl:merge-input>
         <xsl:stream href="{.}">
           <xsl:copy-of select="index/entry"/>
         </xsl:stream>
         <xsl:merge-key select="string(@term)"/>
         <xsl:merge-key select="xs:integer(@page)"/>
      </xsl:merge-input>
    </xsl:merge-source>
    <xsl:merge-action>
       <xsl:copy-of select="current-group()[1]"/>
    </xsl:merge-action>
  </xsl:merge>
</index>

In cases where two chapter indexes contain entries for the same term, they will normally have different page numbers, and will therefore go in separate groups. Their order in the output is based on the ordering of the merge keys, which means entries with the same term appear in page number order. In the unlikely case that two files contain entries where both the term and the page number are the same (or, perhaps more plausibly, where such duplicates occur within a single input file), the xsl:merge-action ensures that only the first of the duplicates will be copied.

18.2 Streamable Templates

[Definition: If any of the modes to which a template rule is applicable is a streamable mode, then the template rule must satisfy certain rules to ensure that it can be evaluated using streaming. A template that satisfies these rules is referred to as a streamable template.] Specifically:

The pattern defined in the match attribute of the xsl:template element must be a streamable pattern as defined in 18.3 Streamable patterns.
The sequence constructor contained in the body of the xsl:template element must be a guaranteed streamable sequence constructor, as defined in 18.4 Streamability Analysis.

Issue 19 (streamable-template-terminology):

It might be more consistent to use "guaranteed-streamable template" rather than "streamable template".

18.3 Streamable patterns

Patterns appear in XSLT in a number of contexts: most notably as match patterns in template rules, but also in key definitions and in attributes of the xsl:number and xsl:for-each-group instructions.

In general, it is difficult to predict how often a pattern will be evaluated, or which nodes it will be evaluated against. The rules for matching nodes against a pattern are therefore designed to make it possible to test the pattern against a node in a streamed input document without changing the current position of the stream. In particular, if the node is an element, the rules make it possible to test whether the node matches the pattern while the stream is positioned at the element's start tag.

[Definition: A pattern is a streamable pattern if it can be tested against a node in a streamed document without access to the descendants of the node.] Specifically, a pattern is streamable if it satisfies all the following conditions:

It must not contain any of the constructs VarRefRoot, IdCall, ElementWithIdCall, or KeyCall

Issue 20 (prohibit-doc-in-patterns):

Given that xsl:stream might not yield stable results, it might make sense to prohibit DocCall here as well - it's highly implementation dependent whether the same node from the streamed document would occur in the document returned by the doc function call.
In any PatternStep within the pattern, the PredicateList^XP21 must contain at most one Predicate^XP21.
In any Predicate^XP21 within the pattern, the expression within the predicate must be motionless with respect to its context item, as defined in 18.4.5 Streamability Conditions.

Note:

Informally, the expression in a predicate is motionless if it can be evaluated without reading the children or descendants of the context node. The term "motionless" is chosen to convey the idea that the pattern can be evaluated without repositioning the input stream.

The effect of these rules is that it is always possible to determine whether an element matches the pattern while processing the start tag of the element, and without advancing the stream beyond the start tag of the element.

The use of VarRefRoot is prohibited because the test would never be satisfied: a variable reference outside a predicate would necessarily be a reference to a global variable, and no global variable can ever be bound to a node in a streamed input document.

The use of IdCall and ElementWithIdCall is prohibited because (in the case of an ID-valued element, as distinct from an ID-valued attribute) the ID value is not known until the element content has been read.

The use of KeyCall is prohibited because keys, in general, cannot be evaluated without access to the content of an element, and the use case is not important enough to justify isolating those cases where streaming evaluation would actually be feasible.

The reason for the restriction to a single predicate is to disallow pattern steps such as match="p[@a=2 and @b=3][5]", where the first predicate applies some complex boolean filter, and the second is positional. This would potentially require maintaining a complex set of counting variables. In principle one could allow multiple predicates provided that only the first one depends on the context position; but it is not always possible to identify positional predicates by static analysis, and in any case such analysis is outside the scope of this specification. Patterns such as match="p[1]" are permitted, however: to evaluate such a pattern, a streaming processor must typically maintain a count of how many nodes of each unique combination of (node-kind, node-name, type-annotation) have been encountered at each level of the XML hierarchy.

The analysis depends on the fact that in both XML Schema 1.0 and XML Schema 1.1, the type of an element is known as soon as its start tag has been processed, before examining its content. This principle has been preserved in the design of new features such conditional type assignment in XML Schema 1.1. Clearly the validity of the element against this type is not established until the content has been read; but if the element is found to be invalid, the XSLT processing will always fail, so assuming the type makes no difference to the outcome.

18.4 Streamability Analysis

The rules for streamable templates, and also the rules for the xsl:stream instruction, require that the contained sequence constructor must be guaranteed-streamable. For generality, we define streamability as a property of any construct, of which a sequence constructor is but one kind. The term construct is defined in 18.4.1 Building an Expression Tree.

The assessment of a construct to determine whether it is a guaranteed-streamable construct is done as described in the following rules:

Optionally, the construct may be rewritten by the processor in an implementation-dependent way, replacing it by an optimized equivalent. This optimization may cause a construct that would otherwise be non-streamable to become streamable, but it must not cause a streamable construct to become non-streamable (for example, the inverse of either of the above).

Note:

For example, the expression A[B or C] might be rewritten as A[*[self::B or self::C]]: the expression as written is not streamable because it makes two downward selections, but the rewritten expression is streamable because it only has one. Similarly, the expression //A/B might be rewritten as //B[parent::A]
An expression tree is constructed representing the structure of the construct, in terms of its contained instructions, XPath expressions, and other constructs.
The expression tree is expanded to make all navigation within the streamed document explicit; for example, a construct that atomizes a node is expanded to include a path expression that makes access to all the text node descendants of that node.
A path map is constructed defining the navigation routes followed by the construct, starting at the context node.
This path map is examined to determine whether it contains any paths, or combinations of paths, that are inconsistent with streaming.

These steps are explained in more detail in the following subsections. The section ends with some worked examples: see 18.4.7 Examples of streamability analysis.

Note:

Streamability analysis is done on the stylesheet as it exists after processing of [xsl:]use-when attributes as described in 3.12 Conditional Element Inclusion. An expression that appears in an [xsl:]use-when attribute itself cannot access any source document, and therefore cannot affect streamability.

18.4.1 Building an Expression Tree

The first stage in analyzing a construct (typically the content of an xsl:stream instruction or a template rule) to determine whether it is streamable is to create a representation of the construct in the form of an expression tree. The expression tree represents the syntactic structure of the construct.

[Definition: To distinguish nodes in an expression tree from other kinds of node in other kinds of tree, we refer to them as e-nodes.]

[Definition: An e-node (a node in the expression tree) represents a construct. A construct is a fragment of a stylesheet that can be evaluated or invoked to produce a value.]. Specifically, it is one of the following:

an instruction
an expression
a pattern
a sequence constructor
an attribute value template
a stylesheet function
a template
an attribute set
an [xsl:]use-attribute-sets attribute
an xsl:when, xsl:otherwise, xsl:matching-substring, xsl:non-matching-substring, xsl:with-param, xsl:catch or xsl:on-completion element (these elements have a structural role within an instruction, but they are not themselves instructions)

Some constructs perform navigation that cannot be statically analyzed and that can potentially visit all parts of the tree containing the context node. An example is an xsl:evaluate instruction. This is fatal to streaming only if the context node is a node in the streamed input document. The expression preceding::* is used as a convenient surrogate for an expression that can navigate anywhere in the tree, and the presence of this expression in the data flow graph will ensure that the streamability analysis produces the correct result.

Note:

Many processors will build some kind of expression tree for purposes unrelated to streamability analysis. In practice the same tree is likely to be used for other operations such as type analysis and optimization.

Because static type inferencing is not prescribed by this specification, the algorithms described in this section do not rely on type inferencing. In practice, where the static type of an expression has already been determined, the processor will be able to recognize that some of the steps described in these rules are not always necessary.

In principle an expression tree can be constructed for each stylesheet function, template, and attribute set: its root e-node represents the function, template, or attribute set. In practice, however, expressions trees are only needed for constructs that are subject to streamability analysis: this includes the content of xsl:stream instructions, template rules that use a streamable mode, and the templates, functions, and attribute sets that these call, to any depth.

The children of an e-node are determined as described in the table below.

Parent e-node	Child e-nodes
Template	The pattern in the `match` attribute if present; the `xsl:param` elements used to bind default values to the template's parameters; and the sequence constructor that forms the body of the template.
Stylesheet function	The sequence constructor that forms the body of the function.
Attribute set	The sequence of `xsl:attribute` elements that forms the body of the attribute set, treated as a sequence constructor; plus the `use-attribute-sets` attribute if present.
Variable binding element (`xsl:variable`, `xsl:param`, `xsl:with-param`)	The expression in the `select` attribute, or the contained sequence constructor.
Sequence constructor	The instructions within the sequence constructor, including any literal result elements. It is not necessary to include literal text nodes on the tree, since they never affect streamability. A sequence constructor comprising a single instruction can safely be elided from the tree (that is, replaced by its children).
Literal result element	The sequence constructor used to construct the content of the new element, plus any attribute value templates and `xsl:use-attribute-sets` attributes used to construct its attributes. An attribute whose value is known statically can be omitted from the tree, since it does not affect the streamability of the construct.
Attribute value template	The XPath expressions contained within curly brackets in the attribute value. Any fixed text outside the curly brackets can be omitted from the tree, since it does not affect the streamability of the construct.
`xsl:if` instruction	An `xsl:if` instruction is rewritten as if it were an XPath `if .. then .. else ()` expression, so that the subsequent analysis can treat all conditionals in the same way. The corresponding e-node will therefore have three children, one representing the `test` condition, one representing the sequence constructor contained within the `xsl:if` instruction, and one representing the empty sequence.
`xsl:choose` instruction	An `xsl:choose` instruction is rewritten as a tree of `if .. then .. else ..` conditional expressions: a second `xsl:when` thus becomes a nested conditional within the `else` branch of the first, and so on. The e-node that results will always have three children, representing the test condition, the `then` branch, and the `else` branch. This rewrite is done because it makes the subsequent analysis easier, in particular, the determination of which subexpressions are mutually exclusive.
`xsl:try` instruction	The e-node corresponding to an `xsl:try` instruction has two children, one for the sequence constructor or `select` expression defining the non-error result of the instruction, and one for the set of `xsl:catch` elements. If there are multiple `xsl:catch` elements, these are rewritten as if there were a single `xsl:catch` containing a conditional expression (or set of nested conditionals) performing tests on the value of the error code.
`xsl:for-each` instruction	The `select` expression, plus the sequence constructor representing the body of the instruction. If there are any `xsl:sort` children, then a `sort` e-node is inserted into the tree to represent the sorting operation. This e-node has the `xsl:for-each` instruction as its parent, and the `select` expression of the `xsl:for-each` instruction as its child; in addition, it has as children the `select` expression of the `xsl:sort` element, plus any expressions that appear in attribute value templates among the attributes of the `xsl:sort` elements (used, for example, to compute the collation URI).
`xsl:apply-templates` instruction	The `select` expression, or an e-node representing the expression `child::node()` if the `select` attribute is omitted; plus variable binding elements representing the `xsl:with-param` children. If there are any `xsl:sort` children, then a `sort` e-node is inserted into the tree to represent the sorting operation: for an illustration of this, see 18.4.4.4 Analyzing sorting constructs. This e-node has the `xsl:apply-templates` instruction as its parent, and the `select` expression of the `xsl:apply-templates` instruction as its child; in addition, it has as children any expressions that appear in attribute value templates among the attributes of the `xsl:sort` elements (used, for example, to compute the collation URI).
`xsl:perform-sort` instruction	The `select` expression or contained sequence constructor, together with any expressions that appear in attribute value templates among the attributes of the `xsl:sort` elements (used, for example, to compute the collation URI).
`xsl:for-each-group` instruction	The contained sequence constructor, plus a `group` e-node whose children are the `select` expression, the expressions appearing in the attributes `group-by`, `group-adjacent`, and any expression appearing in an attribute value template in the `collation` attribute. If the instruction has `xsl:sort` children, then a `sort` e-node is inserted into the tree with the `xsl:for-each-group` instruction as its parent and the `group` e-node as its child; in addition, it has as children any expressions that appear in attribute value templates among the attributes of the `xsl:sort` elements (used, for example, to compute the collation URI). The pattern appearing in the `group-starting-with` or `group-ending-with` attributes (if present) is analyzed to determine whether it is a streamable pattern: if it is, then it does not need to be represented on the expression tree; if it is not, then a child e-node representing the expression `preceding::*` is added to the tree, indicating non-streamable navigation.
`xsl:iterate` instruction	The `select` expression; the contained sequence constructor; the `select` expressions of all contained `xsl:param` elements; the `xsl:on-completion` element if present.
`xsl:analyze-string` instruction	The `select` expression; any expression appearing in an attribute value template in the `regex` or `flags` attributes; the `xsl:matching-substring` and `xsl:non-matching-substring` elements.
`xsl:merge` instruction	See 18.4.2.2 Expanding the xsl:merge instruction.
`xsl:number` instruction	See 18.4.2.1 Expanding the xsl:number instruction.
`xsl:evaluate` instruction	The expressions in the `xpath` and `namespace-context` attributes; any expression appearing in an attribute value template in the `base-uri` attribute; any child `xsl:with-param` elements; plus an e-node representing the expression `preceding::` (because the navigation performed by the dynamic XPath expression is statically unpredictable). Issue 21 (streamable-dynamic-evaluate):* This might be a case where deferring decisions on streamability until execution time might be appropriate. There might be scope to provide an attribute on `xsl:evaluate` that asserts streamability (perhaps motionless streamability), with this assertion being checked at execution time when the actual XPath expression is known.
`xsl:sequence` instruction	The `xsl:sequence` instruction does not need to be represented by an e-node on the expression tree; it can be replaced by the e-node representing its `select` expression.
Other XSLT instructions	An e-node representing each XPath expression appearing in an attribute of the instruction (including attribute value templates), any `use-attribute-sets` attribute, plus the sequence constructor forming the body of the instruction, if any.
`xsl:when`, `xsl:otherwise`, `xsl:matching-substring`, `xsl:non-matching-substring`, `xsl:catch`, `xsl:on-completion` element	The contained sequence constructor.
XPath expressions	Every XPath expression is represented by an e-node whose subtree corresponds to the syntactic structure of the expression when parsed according to the XPath grammar. An expression that matches productions at several levels in the grammar only needs to be represented by a single e-node in the tree: for example `3` will be represented as an `IntegerLiteral`, despite being also a `PrimaryExpr`, a `FilterExpr`, a `StepExpr`, a `PathExpr`, and so on. Grammar productions that are not themselves expressions are not represented by further child e-nodes. For example, the expression `@price + 2` will be represented by an e-node corresponding to the `+` operator, with two children, representing the axis step `attribute::price` and the numeric literal `2` respectively. The expression `@price instance of xs:decimal` is represented by an e-node corresponding to the operator `instance of xs:decimal`, with a single child representing the axis step `attribute::price`. This is because the SequenceType^XP21 `xs:decimal` is not itself an expression and plays no role in the streamability analysis. A parenthesized expression is not represented explicitly as an e-node, since the tree structure directly captures all the information conveyed by the parentheses. For example, the expression `$a($b+2)` is represented by a tree consisting of an e-node representing the `` operator with two children, one representing the variable reference `$a`, the other representing the `+` operator, which in turn has two children representing the operands `$b` and `2` respectively.

Example: An expression tree

Consider the instruction:

<xsl:stream href="books.xml">
  <inventory date="{format-date(current-date(), '[D] [MNn] [Y]')}">
    <xsl:value-of select="count(descendant::book)"/>
  </inventory>
</xsl:stream>

The expression tree for the xsl:stream instruction is shown below:

Note:

Below this paragraph is an SVG diagram. To view it, you need a browser that is capable of displaying SVG graphics.

Note:

This tree has been simplified slightly: as suggested in the rules above, the e-nodes representing sequence constructors comprising a single instruction have been elided.

In practice an implementation can simplify the tree further without affecting the subsequent analysis. For example, leaf e-nodes representing literal values can be stripped, and in many cases intermediate e-nodes representing functions or operators can be elided.

18.4.2 Expanding the Expression Tree

After the expression tree has been built as described in the preceding section, it must be expanded to reflect the implicit navigation carried out by certain instructions and expressions. The general rule here is that wherever an expression appears on the tree whose evaluation might access one or more nodes, the expression is rewritten as a path expression that explicitly accesses all the nodes that will be required to evaluate the containing expression. Since the expression tree is used only to analyze the navigation performed by the stylesheet, and not actually to perform any evaluation, it is not necessary that the replacement expression be semantically equivalent to the original; the only requirement is that it perform equivalent navigation in the source tree. For example, the expression string(x) can be replaced by x/descendant-or-self::text(), since evaluation of the string value of a node involves access to the node itself and to all its descendant text nodes.

The operation of expanding the tree is described here in terms of source-level rewrites to certain constructs. For example, data(x) is said to be rewritten as x/descendant-or-self::text(). This is shorthand for saying that the part of the expression tree representing the first construct is replaced by the expression tree of the second construct.

The most common rewrite operation is atomization. The function data^FO, and many other functions, perform atomization on the nodes supplied to their arguments. Many operators, such as arithmetic and comparison operators, do the same, as also do XSLT instructions like xsl:value-of and xsl:comment, and attribute value templates. Atomization also occurs when a value is bound to a variable declared with an atomic type, and when the result of a function or template declared with an atomic type is computed. To atomize a node it is necessary to access all its descendant text nodes. Any function call, operator, or instruction that atomizes one or more of its operands is first rewritten to add a call on data^FO around each such operand, and this is then processed as described in the table below. For example, the expression item[x = 3] is rewritten item[data(x) = 3], which is then rewritten as item[child::x/descendant-or-self::text() = 3].

In principle any expression X that appears in an atomizing context should be replaced by the fragment X/descendant-or-self::text(). This expansion is clearly unnecessary where X returns an atomic value, or indeed where it returns a node other than an element or document node; and if type inferencing has shown this to be the case then the expansion can be avoided. However, it does not affect the streamability analysis if it is done unconditionally.

The same expansion applies to expressions (such as the string^FO and string-length^FO functions) that compute the string value of the supplied node, and to the xsl:copy-of instruction which accesses all descendant nodes. It also applies to the copy-of and snapshot functions, and to any instruction that invokes the rules in 5.7.1 Constructing Complex Content or 5.7.2 Constructing Simple Content, which both implicitly copy or atomize the results of instructions in a contained sequence constructor.

The following table gives the expansion needed for other constructs that need expanding. Some more complex constructs are discussed in the following sections. Others not explicitly described should be handled by applying the same general principles. Remember that in each case the rewritten expression does not need to deliver the same result; its purpose is to identify the implicit navigation performed by each operation and describe it in terms of axis steps.

The expansion continues recursively until no further expansion is defined: for example string() is expanded first to string(.), and then to ./descendant-or-self::text().

Expression	Rewrite	Notes
`data(X)`	`X/descendant-or-self::text()`
`string(X)`	`X/descendant-or-self::text()`
`base-uri()`, `document-uri()`, `generate-id()`, `local-name()`, `name()`, `namespace-uri()`, `normalize-space()`, `number()`, `root()`, `string()`, `string-length()`	`base-uri(.)`, `document-uri(.)`, `generate-id(.)`, `local-name(.)`, `name(.)`, `namespace-uri(.)`, `normalize-space(.)`, `number(.)`, `root(.)`, `string(.)`, `string-length(.)`	These functions take the context item as an implicit argument when called with zero arguments. The expansion makes the dependency on the context item explicit.
`copy-of(X)`	`X/descendant-or-self::node()`
`snapshot(X)`	`X/descendant-or-self::node()`	The fact that the `snapshot` function also accesses ancestors and their attributes can be ignored, as it does not affect the subsequent analysis.
`/`	`ancestor-or-self::document-node()`	It is useful to rewrite this as `self::node()` if it is known that the context node is a document node.
`/X`	`ancestor-or-self::document-node()/X`	It is useful to rewrite this as `child::X` if it is known that the context node is a document node.
`root(X)`	`X/ancestor-or-self::node()`	While an implementation might not need to visit all the ancestors in order to find the root, the effect on streamability is the same as if it did. Specifically, access to ancestor nodes is permitted in a streamable expression, but access to descendants of the ancestors is not.
`key(K, V)`, `key(K, V, R)`	`(K, V, ancestor::node()/preceding::)`, `(K, V, R/preceding::)`	Although there are some cases where the `key` function could theoretically be evaluated in streaming mode, the analysis is complex and offers few benefits; the function can be viewed as a hint to the processor to perform a search by building indexes or hash tables, and this strategy is inconsistent with streaming. However, use of the function is consistent with streaming if it is used to search a document other than the streamed input document. The two-argument function `key(K, V)` can be expanded to `key(K, V, ancestor::node())`; the third argument `R` can then be expanded to `R/preceding::*`.
`id(V)` and `id(V, R)`	`(V, ancestor::node()/preceding::)`, `(V, R/preceding::)`	Although the `id`^FO function could in many cases be evaluated in streaming mode, doing so is unlikely to be useful in practice. This is because detecting that an element has the required ID value in the case of ID-valued element content (as distinct from attribute content) requires reading the descendants of the element, and this leaves little scope for the application to do anything useful with the element once it has been found. Therefore, the `id`^FO is considered non-streamable if applied to the streamed input document. This is reflected in the expression tree by first expanding the second argument of the function (defaulting it to `ancestor::node()`), and then
`element-with-id(V)` and `element-with-id(V, R)`	`(V, ancestor::node()/preceding::)`, `(V, R/preceding::)`	See `id`^FO function above.
`lang(L)`	`ancestor-or-self::*/@xml:lang = L`	This will generally be streamable, assuming `L` does not navigate within the streamed input document.
`lang(L, N)`	`N/ancestor-or-self::*/@xml:lang = L`
`unparsed-entity-uri(N), unparsed-entity-public-id(N)`	`ancestor-or-self::document-node()`	This will generally be streamable. A streaming processor is expected to retain the unparsed entities declared on the streamed input document. Issue 22 (unparsed-entities-not-at-start): There is an edge-case problem here: comments and processing instructions can precede the `DOCTYPE` declaration, and while processing such comments and processing instructions, the unparsed entities referenced in the DTD are not yet known. A possible solution would be to require buffering of such comments and processing instructions until the DTD has been read. Note that the path analysis can establish that a stylesheet makes reference to unparsed entities in the streamed document, so it might be possible to provide this capability without imposing any costs on users who don't use it. Another problem with similar consequences is that an expression such as `/ instance of document-node(element(A))` cannot be evaluated until the first element start tag has been processed.
`xsl:copy-of select="N"`	`N/descendant-or-self::node()`
`xsl:copy` with no `select` attribute	`<xsl:copy select="."/>`
`xsl:merge-source` with no `select` attribute	`<xsl:merge-source select="."/>`
`xsl:number`	See 18.4.2.1 Expanding the xsl:number instruction
`xsl:evaluate xpath="EXP"`	`EXP, preceding::*`	As well as any navigation needed to evaluate the expression given in the `xpath` attribute, the instruction evaluates the expression, which may perform unpredictable navigation from the context item. This is reflected by adding an e-node representing the non-streamable `preceding::*` step to the expression tree.

18.4.2.1 Expanding the `xsl:number` instruction

In general, the xsl:number instruction is not guaranteed-streamable because it computes a number by navigating backwards through the document to count preceding nodes. However, there are several common cases where streamed evaluation of xsl:number is possible.

When the xsl:number instruction has a value attribute, it can be expanded in the expression tree in the same way as any other construct. Its children in the tree are the value expression, plus any expressions that appear within attribute value templates in other attributes of the instruction.
When xsl:number has no value attribute, streamed evaluation is possible if the node selected by the select expression (or its default, . (dot)) is in a document other than the streamed input document
When the selected node is in the streamed input document and level="single" or level="multiple" is specified, streaming is possible if the following conditions are true:
1. The count attribute is either omitted, or is a NodeTest^XP21.
2. The from attribute is either omitted, or is a streamable pattern
3. The instruction satisfies the general constraints on streamability that apply to every construct: for example, the XPath expressions appearing in the instruction (the select expression and any attribute value templates) do not make multiple downward selections.
The reason that the count pattern is restricted to be a simple NodeTest^XP21 is that it is applied to preceding-siblings of the node that is being numbered. The processing model assumes that the processor will maintain limited information about the number of preceding-siblings of the current node and all its ancestors, specifically, the number of preceding siblings for every combination of node-kind, node-name, and type-annotation. This information is sufficient to establish how many preceding siblings match any given NodeTest^XP21, but it is not sufficient to do the same for an arbitrary pattern, even a streamable pattern.

By contrast, the from pattern is applied only to the node being numbered and its ancestors, and for these nodes there is sufficient information to test any streamable pattern.
When the selected node is in the streamed document and level="any" is specified, streaming can be achieved by tallying the counted nodes as they are encountered in the input stream, so that the count is already available when the selected node comes to be read. This requires analysis of the stylesheet to determine all xsl:number level="any" instructions that could possibly be evaluated on nodes in the streamed document. The relevant instructions are those that appear in the data flow graph (see 18.4.3 Analyzing Navigation) on paths emanating from the construct whose streamability is being analyzed.

These xsl:number instructions must satisfy the following conditions for streaming to be possible:
1. The count attribute is present, and is a streamable pattern. (An implementation might be able to relax this condition by allowing the count attribute to be omitted in cases where the node-kind and node-name of the context node can be determined by static analysis. However, this analysis is outside the scope of this specification, so such instructions are not guaranteed-streamable.)
2. The from attribute is either omitted, or is a streamable pattern.
3. The select attribute takes its default value of . (dot).
4. The instruction satisfies the general constraints on streamability that apply to every construct: for example, the attribute value templates used in the instruction do not make multiple downward selections.
A possible implementation strategy is then for the processor, while reading nodes from the input stream, to test every node against the from and count patterns of each reachable xsl:number level="any" instruction. For each such instruction, a counter is maintained. When a node matches the from pattern, the counter is reset to zero. When it matches the count pattern, the counter is incremented. When the xsl:number instruction is then evaluated against the context node, the relevant counter already contains the required number.

Although xsl:number is specified in terms of XPath expressions that navigate to nodes that precede the context node in document order, this navigation does not need to be represented in the expression tree, because a streaming implementation is expected to maintain counters as the stream is read to make such navigation unnecessary.

So the effect on the expression tree is as follows:

The xsl:number e-node is given children corresponding to the select and value expressions, and to any expressions contained in attribute value templates, in the normal way.
If the instruction is not streamable according to the rules given above, then the xsl:number expression N is expanded to N/preceding::* to indicate non-streamable navigation.

18.4.2.2 Expanding the `xsl:merge` instruction

If xsl:merge instruction takes its input by navigating from the context node, then the streamability rules are the same as for any other instruction. For example, the following construct is not guaranteed-streamable because it makes two downwards selections from the context item (to the elements credits and debits):

<xsl:merge>
  <xsl:merge-source select="credits, debits">
    <xsl:merge-input select="transaction">
      <xsl:merge-key select="timestamp"/>
    </xsl:merge-input
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:copy-of select="current-group()"/>
  </xsl:merge-action>
</xsl:merge

Similarly, the following is not streamable, for the same reason:

<xsl:merge>
  <xsl:merge-source select="credits">
    <xsl:merge-input select="transaction">
      <xsl:merge-key select="timestamp"/>
    </xsl:merge-input>
  </xsl:merge-source>
  <xsl:merge-source select="debits">
    <xsl:merge-input select="transaction"/>
    <xsl:merge-key select="timestamp"/>
  </xsl:merge-source>
  <xsl:merge-action>
    <xsl:copy-of select="current-group()"/>
  </xsl:merge-action>
</xsl:merge

If xsl:merge is to operate on streamed input, this is achieved by using xsl:stream within the xsl:merge-input instruction. The streamability then depends on analysis of the xsl:stream instruction alone.

For the purposes of this analysis, therefore, xsl:merge is not essentially different from any other instruction. The structure in the expression tree matches the syntactic structure:

The e-node representing the xsl:merge element has one child for each xsl:merge-source element, and one for the xsl:merge-action.
The e-node representing the xsl:merge-source element has one child for the select expression and one for the xsl:merge-input element.
The e-node representing the xsl:merge-input element has one child for its select attribute or contained sequence constructor, plus additional children for the expressions contained in any xsl:merge-key children.

In the subsequent analysis, as explained in later sections, it is necessary to take account of the fact that (a) the select expressions of both xsl:merge-source and xsl:merge-input change the focus, and (b) some of the contained expressions are evaluated repeatedly, meaning that xsl:merge is treated as a looping construct (see 18.4.4.3 Analyzing looping constructs) .

18.4.3 Analyzing Navigation

Having built the expression tree, the next step is to analyze where constructs derive their input. The objective here is twofold:

Firstly, it is necessary to determine which constructs operate on data that comes from the streamed document. If a construct is actually operating on other (non-streamed) input documents, then it is able to access that data without constraints.
Secondly, where constructs operate on the streamed document, it is necessary to determine whether they do so in a way that permits streaming. This requires analysis of the navigation paths through the streamed document.

This analysis creates a new graph, known as the data flow graph, showing a different kind of relationship between the e-nodes of the expression tree: the arcs in this graph show where nodes returned by one construct are used as input to another construct. These data flows can arise in a number of ways:

A child construct can return nodes that participate directly in the result of its parent construct. For example, when the union operator is used, the result of the union expression includes the nodes returned by both its operand expressions.
When a variable is bound to a node or nodes, there is a data flow from the construct used to initialize the variable to every variable reference that refers to this variable binding.
When a construct sets the context item, there is a data flow from the child construct that sets the context item to every context-dependent construct that uses this new context.
When a construct calls a stylesheet function or a named template, there is a data flow from the construct that sets the value of a parameter to the function or template to the variable binding in the called function or template.
When parameters are supplied from one iteration of xsl:iterate to the next using xsl:with-param elements within xsl:next-iteration, there is a data flow from the xsl:with-param element that sets the parameter value to the xsl:param element that receives it.

The following sections describe in more detail how these data flows are modeled. In all cases they result in arcs being added to the data flow graph.

18.4.3.1 Marking contributing child constructs

An arc is created in the data flow graph from any e-node to its parent in the expression tree if the child construct returns nodes^DM11 that form part of the result of the parent construct.

The following table lists constructs that return nodes contributed by one of their child constructs, referred to as a contributing construct.

Construct	Contribution
Path expression `A/B`	`B` is a contributing construct.
Filter expression `S[P]`	`S` is a contributing construct.
Union expression `P\|Q`	`P` and `Q` are both contributing constructs.
Difference expression `P except Q`	`P` is a contributing construct.
Intersection expression `P intersect Q`	`P` and `Q` are both contributing constructs. Issue 23 (intersect): It might be safe to treat one of the operands as non-contributing, but the Working Group has not been able to demonstrate this to its satisfaction. Note that if one of the operands selects nodes from the streamed input and the other does not, then the intersection will not contain any nodes from the streamed input.
Comma expression `P, Q`	`P` and `Q` are both contributing constructs.
Sequence constructor	The instructions within the sequence constructor are all contributing constructs.
XSLT variable binding (`xsl:variable`, `xsl:param`, `xsl:with-param`)	The initializer of the variable binding (that is, the `select` expression or the contained sequence constructor) is a contributing construct. However, in the case where there is no `as` attribute, so a new document node is created, the sequence constructor is not a contributing construct. Also, the initializer is not a contributing construct in the case where the variable is declared with an atomic type, as any nodes delivered by the initializer will then be atomized. The implicit navigation required to perform this atomization must be made explicit on the expression tree.
XPath variable binding (`for`, `let`)	In the case of `for` and `let` expressions, the expression in the `return` clause is a contributing expression to the result of the `for` or `let` expression. In the case of `some` and `every` expressions, the result is a boolean, so there is no contributing subexpression.
Conditional `if (C) then T else E`	`T` and `E` are both contributing constructs (`C` is not). This applies whether the conditional originated as an XPath `if` expression, or as an `xsl:if` or `xsl:choose` instruction.
Instructions `xsl:for-each`, `xsl:for-each-group`, `xsl:stream`	The contained sequence constructor is a contributing construct.
Instruction `xsl:iterate`	The contained sequence constructor and the `xsl:on-completion` child are contributing constructs.
Instruction `xsl:perform-sort`	The `select` expression and the contained sequence constructor are contributing constructs.
Instruction `xsl:analyze-string`	The `xsl:matching-substring` and `xsl:non-matching-substring` children are contributing constructs.
Instruction `xsl:merge`	The contained `xsl:merge-action` element is a contributing construct.
Instruction `xsl:try`	The contained sequence constructor and each contained `xsl:catch` element is a contributing construct.
Elements `xsl:when`, `xsl:otherwise`, `xsl:matching-substring`, `xsl:non-matching-substring`, `xsl:catch`, `xsl:on-completion`, `xsl:merge-action`	The contained sequence constructor is a contributing construct.
Functions `remove`^FO, `subsequence`^FO, `reverse`^FO, `trace`^FO, `unordered`^FO, `one-or-more`^FO, `exactly-one`^FO, `zero-or-one`^FO, `innermost`, `outermost`	The first argument is a contributing construct.
Function `insert-before`^FO	The first and third arguments are contributing constructs.
Operation `sort` (the e-node that is added to the tree by operations that perform sorting)	The subexpression representing the `select` expression (the sequence being sorted) is a contributing construct.

18.4.3.2 Analyzing variable references

In the data flow graph, an arc is created from a variable binding construct to every variable reference that refers to that variable.

Example: Data flow with variables

Consider the construct:

<xsl:template name="example">
  <xsl:variable name="doc-A" select="doc('a.xml')"/>
  <xsl:stream href="b.xml">
    <xsl:sequence 
         select="count($doc-A/descendant::*) + count(descendant::*)"/>
  </xsl:stream>
</xsl:template>

The expression tree for this template is as follows (note that sequence constructors containing a single instruction have again been elided):

After adding the links from contributing subexpressions to their parent expression, and from the variable declaration to its reference, the data flow graph is like this:

18.4.3.3 Tracing the Context of an Expression

In the same way as the previous step created arcs in the data flow graph from an e-node representing a variable declaration to an e-node representing a variable reference, this step creates an arc from an e-node representing a construct that sets the context item to an e-node representing a reference to the context item. This creates one arc pointing to each e-node representing any of the following:

The context item expression .
An axis step, for example @status
The expression last() (but not position(), since calls on the position^FO function never affect the streamability analysis).

Note:

Other expressions that might appear to be dependent on the context item have already been rewritten to make the dependency explicit: for example name() has been rewritten as name(.), while / has been rewritten as ancestor-or-self::document-node(), as described in 18.4.2 Expanding the Expression Tree

It would be possible to handle axis steps in the same way, by rewriting @status as ./@status. However, if applied repeatedly, the resulting expression would be expanded again, leading to infinite recursion.

The instructions xsl:apply-templates, xsl:apply-imports, and xsl:next-match are not considered to depend on the context item: they are considered separately: see 18.4.4.5 Analyzing dynamic invocation

The origin of the arc is the construct that sets the context item for this expression. This is found by searching for the nearest ancestor e-node that represents a construct that changes the focus. An example of such an construct is a path expression A/B. This has two subexpressions: A, which sets the focus, and B, which is evaluated with the new focus. Other context-changing constructs similarly have a child construct that acts as focus setter and another (or several) that are evaluated using the new focus. These are shown in the table below:

Construct	Context-setting construct	Construct(s) evaluated with the new focus
Path expression A/B	A	B
Filter expression A[B]	A	B
`xsl:for-each`	`select` expression	the contained sequence constructor, and the `select` attributes of any `xsl:sort` keys
`xsl:for-each-group`	`select` expression	the contained sequence constructor, and the `select` attributes of any `xsl:sort` keys
`xsl:iterate`	`select` expression	the contained sequence constructor and any `xsl:on-completion` child
`xsl:analyze-string`	`select` expression	the sequence constructors within the `xsl:matching-substring` and `xsl:non-matching-substring` children
`xsl:stream`	the `xsl:stream` instruction itself	the contained sequence constructor
`xsl:perform-sort`	`select` expression or the contained sequence constructor	the `select` expressions of the `xsl:sort` keys
`xsl:merge-source`	`select` expression	the `select` expression or the contained sequence constructor of the `xsl:merge-input` children
`xsl:merge-input`	`select` expression or the contained sequence constructor	the `select` expressions of the `xsl:merge-key` children, and the `xsl:merge-action` element. Note that context for the `xsl:merge-action` element is set by each of the `xsl:merge-input` elements, so in general there will be multiple arcs to the `xsl:merge-action` e-node.

Having found an e-node E that represents a context-dependent construct, the relevant context-setting construct can be found by searching the ancestors of the e-node until a context-changing construct C is found, provided that E is within the subexpression that uses the new context. The context-setting construct is then the subexpression of C that sets the context item, shown in the table above.

If the search for ancestor e-nodes finds no context-changing construct, then the context-setting construct is deemed to be the e-node at the root of the tree, for example an e-node representing an xsl:template declaration.

Example: Adding context arcs to the data flow graph

This example builds on the example in the previous section. After adding the links from context-setting constructs to context-using constructs, the data flow graph is like this:

It can now be clearly seen that there are two navigation paths performed by this template, from document a.xml to its descendant elements, and from b.xml to its descendant elements. The streamability analysis will in due course examine the paths in the data flow graph emanating from the e-node representing the xsl:stream instruction to determine whether they conform to the rules for streamable navigation (which they do).

The navigation paths relating to a.xml do not need to be streamable, because this document is being accessed using non-streaming interfaces; however, it is necessary to construct the paths before it can be determined which document is being accessed by which expressions.

There are some special cases:

If E represents a call on the function current, then the search for a context-changing ancestor e-node skips all e-nodes that represent containing XPath expressions (that is, the search only considers XSLT constructs that set the context).
If E represents a call on the function current-group, that appears nested within an xsl:for-each-group instruction that is itself within the expression tree, is treated as if it were the axis step child::node(). Although this bears no relationship to the actual navigation path in the source tree, it has the correct result in the context of streamability analysis. This is because grouping essentially performs two nested iterations over the items in an input sequence (one over the groups, one over the items of each group) and this processing structure is the same as if there were an extra level of nodes in the source tree. If there is no enclosing xsl:for-each-group instruction within the expression tree (which is possible because the current group has dynamic scope) then the call on current-group can be treated as if it were a reference to a global variable; it has no bearing on the path analysis.

Issue 24 (streamability-of-grouping):

The analysis of the streamability of grouping needs a more thorough exposition; although the rules given might well be correct, they are not convincingly explained.

At this stage it is possible to detect some conditions that will render an expression non-streamable, without the need to do further analysis. If we are testing an xsl:stream or xsl:template construct for streamability, then if any of the following e-nodes are present on a path in the data flow graph starting at that construct, the construct is not streamable:

An axis step using any of the axes following-sibling, preceding-sibling, following, or preceding
A call on the last^FO function
A sort node
A call on the reverse^FO function
An xsl:for-each-group instruction with a group-by attribute.

Example: Avoiding the use of last()

Use of the last^FO function can often cause code to become non-streamable. In some cases the problem is easily avoided by rearranging the code. For example, the following template inserts a <br/> element after every line of a poem except the last:

<xsl:for-each select="poem/lines">
  <xsl:value-of select="."/>
  <xsl:if test="position() ne last()"><br/></xsl:if>
</xsl:for-each>

This code is not streamable, but it can easily be rewritten to make it streamable by instead inserting the <br/> element before every line except the first:

<xsl:for-each select="poem/lines">
  <xsl:if test="position() ne 1"><br/></xsl:if>
  <xsl:value-of select="."/>  
</xsl:for-each>

18.4.4 Analyzing choices, repetition, and calls

The previous section established a data flow graph sufficient to identify the navigation routes through a document used within an individual function or template. This is not yet sufficient to establish whether the navigation is guaranteed-streamable:

Conditional branches in the logic can make a construct streamable based on knowledge that two navigation paths are mutually exclusive at run-time (the logic will only follow one of them). Conditional branches arise most obviously from use of an xsl:choose instruction or an XPath if expression; however they also arise with xsl:catch, and the same analysis is used with xsl:fork.
Iteration in the logic, on the other hand, can make a construct non-streamable, because it is in the nature of streaming that descendant nodes can only be visited once.
To get a complete picture of the navigation routes followed, it is necessary to trace paths through function and template calls and invocations of attribute sets.

These factors are considered in the sections that follow.

18.4.4.1 Analyzing conditional constructs

It is necessary to identify constructs that are mutually exclusive, in the sense that when one construct is evaluated the other will not be evaluated. This is because a guaranteed-streamable construct is only allowed to traverse the children of a node once, but performing two traversals in mutually exclusive branches of a conditional does not violate this condition. For example, the expression if (@a) then child::title else child::subtitle is potentially streamable even though it contains two downward selections.

Recall that when building the expression tree, an xsl:if instruction was converted to an (if-then-else) expression, in which the else branch is always an empty sequence, and an xsl:choosestream instruction was decomposed into a set of binary (if-then-else) tests Similarly, it is convenient to consider an xsl:if instruction as having an implicit else branch that always returns an empty sequence. Furthermore, a sequence of xsl:catch clauses was reduced to a single xsl:catch construct containing internal if-then-else constructs to test the error code. Thus all conditional expressions have been reduced to a common form.

[Definition: Two e-nodes in the expression tree are defined to be mutually exclusive if they have a common ancestor if e-node, and if one is a descendant of the then child of that if, while the other is a descendant of the else child. Two e-nodes are also mutually exclusive if they are mutually independent as defined in 18.4.4.2 Analyzing parallel branches.]

Example: Conditional branches

Consider the template

<xsl:template name="t">
  <xsl:choose>
    <xsl:when test="@code=23>
       <xsl:sequence select="firstName"/>
    </xsl:when>
    <xsl:when test="@code=24>
       <xsl:sequence select="lastName"/>
    </xsl:when>
    <xsl:when test="@code=if (@married) then 31 else 32">
       <xsl:sequence select="formerName"/>
    </xsl:when>
    <xsl:otherwise>
       <xsl:sequence select="concat(firstName, lastName)"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

The combined expression tree and data flow graph for this template is shown below. (To avoid complicating the diagram unnecessarily, data flows from the xsl:sequence instructions back via the if/then/else expressions to the root e-node labeled xsl:template are not shown.)

Later, the streamability analysis will test whether there are two paths starting at the xsl:template that both contain downward selections and are not mutually exclusive. In fact there are five paths here that contain a downward selection (all those to e-nodes that use the child axis), and they are all mutually exclusive except those that include the two subexpressions of the concat() node. In consequence, this template is not guaranteed-streamable.

18.4.4.2 Analyzing parallel branches

When the xsl:fork instruction is used, instructions within its sequence constructor can be evaluated in parallel, during a single pass of the streamed input document.

Recall that two instructions directly contained within an xsl:fork instruction are defined to be independent if neither is dependent on the other (that is, in all cases except where one instruction binds a variable that is used by the other). Extending this concept:

[Definition: Two e-nodes are mutually independent if they share an e-node representing an xsl:fork instruction as a common ancestor, and if they occur in separate subtrees rooted at different children of the xsl:fork instruction, such that neither subtree is dependent (directly or indirectly) on the value of a variable bound by the other subtree.]

Note:

From the point of view of streamability analysis, e-nodes that are mutually independent are treated in the same way as those that are mutually exclusive because they occur in different branches of a conditional.

18.4.4.3 Analyzing looping constructs

It is necessary to identify constructs that are evaluated repeatedly, in the sense that when their parent construct is evaluated, the child construct is evaluated more than once. This is because a streamable construct is only allowed to traverse the children of a node once. For example, the expression for $a in 1 to 5 return child::* is not streamable: it performs multiple traversals of the children of the context node even though there is only a single subexpression that does downwards navigation.

A number of constructs are recognized as looping constructs, in that they cause one of their sub-constructs to be evaluated more than once, with differences in the dynamic context (either a different focus, or different variable values). In each case the construct has one child construct whose evaluation returns a sequence, which is evaluated once, and another child construct that is evaluated repeatedly: we will refer to the first subconstruct as the controlling expression and the second as the controlled expression.

To analyze this situation, it is necessary to examine arcs in the data flow graph that start on an e-node S representing a construct that is outside a loop, and end on an e-node E that is inside the loop. This is consistent with streaming only where S is the controlling expression for the loop.

Example: A streamable loop

Consider the construct

<xsl:template match="department">
  <xsl:for-each select="employee">
    <a><xsl:value-of select="salary"/></a>
  </xsl:for-each>
</xsl:template>

The expression tree and data flow graph for this construct are shown below. (Again, the expansion of axis steps such as child::employee to ./child::employee has been omitted.)

This is streamable because the arcs from the xsl:template e-node to the e-node representing the select expression, and that from the select expression into the body of the loop, are both permitted under the rules below.

Example: A non-streamable loop

Consider the construct

<xsl:template match="department">
  <xsl:param name="required" select="()"/>                    
  <a>
    <xsl:value-of select="for $i in $required 
                          return employee[@id=$i]/name"/>
  </a>
</xsl:template>

The expression tree and data flow graph for this construct are shown below.

This is not streamable because the arc from the e-node representing the xsl:template to the e-node representing the step child::employee crosses into the loop in a way that is not allowed.

The looping constructs are listed in the table below.

Looping construct	Controlling expression	Controlled expression
`xsl:for-each`	the `select` expression	the contained sequence constructor; plus the `select` expression of any child `xsl:sort` elements
`xsl:for-each-group`	the `select` expression	the contained sequence constructor; plus the `group-by` and `group-adjacent` expressions, and the `select` expression of any child `xsl:sort` elements
`xsl:iterate`	the `select` expression	the contained sequence constructor
`xsl:analyze-string`	the `select` expression	the sequence constructors contained in the `xsl:matching-substring` and `xsl:non-matching-substring` children
`xsl:merge-source`	the `select` expression of the `xsl:merge-source` element	the `select` expression of its `xsl:merge-input` child
`xsl:merge`	the `select` expressions of the `xsl:merge-input` elements	the sequence constructor contained in the `xsl:merge-action` child; plus the `select` expression of any child `xsl:merge-key` elements
XPath `for` expression	the `in` expression	the `return` expression
XPath `some/every` expression	the `in` expression	the `satisfies` expression
Path expression (`A/B`)	the first operand, `A`	the second operand, `B`
Filter expression (`A[B]`)	the sequence being filtered, `A`	the predicate, `B`

[Definition: An arc in the data flow graph is a repeating arc if it ends at an e-node that is within the subtree rooted at the e-node representing a controlled expression, and starts at an e-node that is outside the tree rooted at the corresponding looping construct.]

When such an arc forms part of a path starting at a construct whose streamability is being tested, it will cause the construct to be deemed non-streamable. However, an arc from outside the looping construct to the controlling expression, and an arc from the controlling expression to the controlled expression, do not cause non-streamability.

Issue 25 (data-flow-into-a-loop):

The rules prohibiting data flows into the body of a loop may be stricter than is necessary: they are designed to prevent repeated evaluation of a downward selection, but as written, they also disallow motionless expressions such as $var/@name or name($var)

18.4.4.4 Analyzing sorting constructs

Where an expression sorts nodes from a streamed input document into some order other than document order, the effect is to make the code non-streamable. An example is an xsl:for-each instruction containing an xsl:sort child element.

In building the expression tree according to the rules in 18.4.1 Building an Expression Tree, a construct of the form:

<xsl:for-each select="IN">
  <xsl:sort select="KEY"/>
  <xsl:sequence select="OUT"/>
</xsl:for-each>

was rewritten to make the expression IN a subexpression of an e-node representing the sorting operation, so the expression tree is:

If the subsequent analysis of the data flow graph reveals that the expression IN contains nodes from the streamed input, the presence of the sort e-node will result in the entire construct being deemed non-streamable, because a sort operation (in the worst case) needs to read all its input into memory before it can produce any output. (If the sort operation is sorting data from another source then this is not incompatible with streaming: it may involve allocating memory, but the requirement to stream the input document has been satisfied.)

Example: Non-streamable sorting

Consider the template rule

<xsl:template match="department">
  <xsl:for-each select="employee">
     <xsl:sort select="@empNr"/>
     <xsl:copy-of select="."/>
  </xsl:for-each>
</xsl:template>

The expression tree and data flow graph for this template are shown below:

This template is not streamable, because the data flow graph contains a sort construct on a path reachable from the xsl:template construct.

[Definition: Sorting is just one example of an operation on a sequence whose output is not streamable with respect to its input. In general we refer to any construct that requires to hold its entire input sequence in memory in order to compute its result as a reordering construct.]

The following is a complete list of constructs that are classified as reordering constructs:

The sort e-node created on the expression tree for any instruction having an xsl:sort element as a child.
The function reverse^FO
The function last^FO (see below)
the xsl:for-each-group instruction when used with a group-by attribute

Example: The last function

This example shows how the analysis is done for the last^FO function. As described in 18.4.3.3 Tracing the Context of an Expression, this expression is considered to depend on the context item, and therefore has an inward arc in the data flow graph from the expression that sets the context item.

Consider the template rule

<xsl:template match="department">
  <xsl:for-each select="employee">
     <xsl:if test="position() = last()">
        <xsl:value-of select="surname"/>
     </xsl:if>
  </xsl:for-each>
</xsl:template>

The expression tree and data flow graph for this template are shown below:

This example is not streamable, because the reordering construct last() is present on a data flow path starting at the xsl:template construct.

Note:

Any expressions appearing in attribute value templates of the xsl:sort element (for example, the collation attribute) must be analyzed in the usual way: the focus for these expressions is the same as the focus for the select expression of the containing instruction (for example, xsl:for-each). Even if the select expression does not force a streamability problem by reordering the nodes in the streamed input, there is potential for these additional attributes to disrupt streamability by making downwards selections from a streamed input node.

18.4.4.5 Analyzing dynamic invocation

A number of constructs cause invocation of a function, template, or expression that cannot be identified statically. These constructs include xsl:apply-templates, xsl:apply-imports, xsl:next-match, xsl:evaluate, and dynamic function invocations in XPath.

The instructions xsl:apply-templates, xsl:apply-imports, and xsl:next-match cause a template to be invoked dynamically. There are two cases to consider:

If the invocation is in a streamable mode, then the called template is guaranteed to be streamable, which means the caller can reliably assume that the called template will only navigate within the subtrees of the selected nodes. The effect of the called template can therefore be simulated by adding the navigation step descendant-or-self::node() to the nodes selected by the select expression (in the case of xsl:apply-templates) or the context item (in the case of xsl:apply-imports and xsl:next-match)
If the invocation is in a non-streamable mode, then the caller cannot make any assumptions about the navigation performed by the called template. This can be simulated by adding the navigation step X/preceding::* to the nodes selected by the select expression (in the case of xsl:apply-templates) or the context item (in the case of xsl:apply-imports and xsl:next-match). If the selected nodes are in the streamed document this will inevitably cause the construct to be deemed non-streamable.

Any xsl:with-param elements used within an xsl:apply-templates, xsl:apply-imports, xsl:next-match, or xsl:evaluate instruction, as well as the arguments to a dynamic function invocation, are handled as follows: the initializing expression X (the expression that evaluates the argument to be passed) is replaced by X/preceding::*, reflecting the ability of the called component to navigate anywhere within a tree that contains nodes passed as parameter values, as well as the atomization that may be performed in the course of parameter passing.

Note:

This expansion isn't needed if the type of the parameter value is always atomic. However, this specification does not assume that the processor is able to perform static type inferencing. If the parameter value is atomic, this expansion will do no harm as it does not affect the path analysis.

The effect of this rule is that nodes within a streamed document cannot be passed as parameters to a called template. This disallows some cases that might be completely innocent, for example passing an attribute node which the called template then atomizes. In effect it is a pessimistic strategy: it disallows things that cannot be determined statically to be safe. An alternative might be to allow a more optimistic approach, in which it is permitted to pass such a parameter, and a dynamic error is then signalled if the called template uses it in an inappropriate way, for example by navigating outside the subtree that is available when streaming.

In the case of xsl:evaluate, the dynamically invoked XPath expression can perform arbitrary navigation not only from any nodes passed using xsl:with-param, but also from the context item. This is represented by adding the expression ./preceding::* as an additional subexpression on the expression tree.

18.4.4.6 Analyzing calls to functions, templates, and attribute sets

Calls on stylesheet functions, named templates, and attribute sets can be resolved at this stage: a data flow graph is constructed that combines the navigation performed by the calling template or function with that performed by its callee.

Parameters in a function call or in xsl:call-template are handled by creating an arc in the data flow graph from the expression that sets the parameter (in the caller) to the variable binding construct in the callee. The return value is represented by an arc from the root e-node of the expression tree representing the callee, to the e-node representing the function or template invocation.

In the case of named templates and attribute sets, the context item is passed implicitly, which is represented by (a) treating the calling construct as one that has an intrinsic dependency on the context item, and (b) creating an arc from the calling construct to the root e-node of the callee. This is illustrated in the examples below.

If an argument or parameter has a declared type that is atomic, then the parameter passing may invoke atomization, which may require navigation to descendant nodes. In this case an e-node representing the step descendant::text() must be inserted into the arc connecting the caller to the callee. It is not necessary to represent atomization of the returned result in the same way, because this operation will already be reflected in the expression tree of the callee.

Example: Analyzing a function call

Consider a calling template and a called function as follows:

<xsl:template match="employee">
  <e><xsl:value-of select="f:salary(.)"/></e>
</xsl:template>
<xsl:function name="f:salary" as="xs:decimal">
  <xsl:param name="emp" as="element(employee)"/>
  <xsl:choose>
    <xsl:when test="$emp/hourly-pay">
       <xsl:sequence select="$emp/hourly-pay * 1924"/>
    </xsl:when>
    <xsl:otherwise>
       <xsl:sequence select="$emp/annual-salary"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>

The two expression trees (one for the template, one for the called function) are linked in the data flow graph as shown below.

Analysis of the data flow graph will show that the template is not streamable. There are three paths originating at the xsl:template e-node that make downward selections and are not mutually exclusive (two select $emp/hourly-pay, one selects $emp/annual-salary). Two of these are mutually exclusive, but the third is not. If the properties of the employee were held in attributes rather than child elements, however, the template would be streamable.

Note that a data flow graph needs to be constructed independently for each supposedly streamable template. Constructing a global data flow graph could create spurious paths that affect the analysis.

Where there are several calls to the same function, the paths in the data flow graph from the root xsl:template e-node will no longer form a tree (paths may converge); and where a function or template is recursive, the graph may contain cycles. This is not necessarily incompatible with the template being streamable.

Example: A streamable recursive template

This example shows a recursive function that counts how many immediate ancestor div elements a given element has, and a streamable template that calls this function.

<xsl:template match="p" mode="streamable">
  <out>Nesting depth: <xsl:value-of select="f:div-depth(.)"/></out>
</xsl:template>

<xsl:function name="f:nesting-depth" as="xs:integer">
  <xsl:param name="this" as="element()"/>
  <xsl:sequence select="if ($this/parent::div) 
                        then 1 + f:nesting-depth($this/parent::div) 
                        else 0"/>
</xsl:function>

The two expression trees (for the template and the function) are shown in the diagram below, together with the data flow graph.

Note the cycle from the xsl:param element to the variable reference $this used in the recursive function call, to the parent::div step and then the containing path expression. This cycle is not inconsistent with streamability, because streamable code can make an indefinite number of upwards steps (the ancestors of a node are always available). The fact that there is only one axis step on this cycle reflects the fact that each recursive invocation of the function moves one step up the ancestor axis.

18.4.4.7 Analyzing the streamability of `xsl:iterate`

The xsl:iterate instruction is a looping construct, and as such its analysis is described in 18.4.4.3 Analyzing looping constructs.

In addition, in xsl:iterate there is a data flow from an xsl:with-param element within the xsl:next-iteration element, to the corresponding xsl:param element. As with a recursive function call, this causes cycles in the data flow graph, but such cycles are not necessarily fatal to streamability.

18.4.5 Streamability Conditions

The streamability of a construct C can be determined by examining the paths in the data flow graph that emanate from the e-node representing C in the expression tree. A path here is any sequence of arcs in the data flow graph. Note that because the data flow graph may have cycles, a path can be infinite (and there can also be an infinite number of paths). Paths that do not start from C can be ignored.

A construct C is guaranteed-streamable with respect to its context item if the set of paths starting at C in the data flow graph satisfies all the following conditions:

No path contains an e-node representing a sideways axis step (following, preceding, following-sibling, or preceding-sibling).

Note:

Although there might be streaming techniques that allow such axes to be used, perhaps with the help of buffering, such techniques are out of scope for this specification and code that uses them is therefore not guaranteed-streamable.
No path contains an e-node representing an upwards axis step (parent, ancestor, or ancestor-or-self) followed immediately or otherwise by an e-node representing a downward step (child, descendant, or descendant-or-self).

Note:

The processing model for streaming used in this specification assumes that while passing through a streamed document, the processor will retain information about the ancestors of the node at the current position of the stream, together with their attributes. However, retaining information about the descendants of these ancestors would be inconsistent with streaming. Therefore, it is possible to navigate upwards to ancestors, but not downwards from the ancestors to other parts of the document.
No path contains an e-node representing a descendant or descendant-or-self axis step followed immediately or otherwise by an e-node representing a downward step (child, descendant, or descendant-or-self).

Note:

For discussion of the reasons for this restriction and the possible ways in which it might be relaxed, see 18.4.6 Notes on the streamability of paths using the descendant axis.
Given any pair of paths P and Q, excluding their common prefix if any, every e-node in P that represents a downward step (child, descendant, or descendant-or-self) is mutually exclusive with every e-node representing a downward step in Q.

[Definition: The common prefix of two paths in the data flow graph contains the arcs that are present in both paths before the paths diverge.]

Note:

This rule is trivially satisfied if P and Q are the same path, or if one is a prefix of the other, or if either P or Q contains no downward selections.

So in practice it is only necessary to examine distinct paths that contain one or more downward selections from the point at which the paths diverge, and to check whether any downward selections in one arm are mutually exclusive with the downward selections in the other arm (that is, that they occur in different branches of a conditional such as xsl:choose, or in independent instructions within an xsl:fork instruction).

The rule reflects the fact that in streaming mode, the descendants of a node can only be visited once. This rule therefore imposes a static constraint on streamable constructs that they must not make more than one downward selection, unless those downward selections are in mutually exclusive branches of a conditional, so that only one of them will ever be evaluated, or in independent branches of an xsl:fork instruction, so that they are evaluated during a single pass of the input document.
No path contains a repeating arc. (See 18.4.4.3 Analyzing looping constructs.)

Note:

This complements the previous rule, by stating that if there is a downward selection to access descendants of a node, it must not occur in a loop where it can be executed more than once.
No path contains an e-node representing a reordering construct. (See 18.4.4.4 Analyzing sorting constructs.)

Note:

Examples of reordering constructs are the sort node added to the expression tree in response to an xsl:sort child of xsl:for-each or xsl:apply-templates, or a call on the functions reverse^FO or last^FO. These constructs have the characteristic that they need to read their full input sequence before producing any output, which is clearly incompatible with streaming.
No non-empty path returns to the e-node representing the starting construct C.

Note:

Such a path would indicate that the supposedly streamable construct is capable of returning (as all or part of its result) a node from the streamed input document. In general this is not allowed, because there is no way of analyzing what the caller attempts to do with the returned node, and in particular, no way of determining that what it does is compatible with streaming. This restriction is particularly necessary when the construct being analyzed is a template rule, because each template rule in a streamable mode is analyzed independently of the others.

It might be possible to relax the rule in the case of the xsl:stream instruction, where there is more scope to pursue the analysis beyond the instruction itself.

The above rules establish that a construct can be evaluated using streaming with respect to a given context node; in the case of an element node this will typically involve reading the input stream from the start tag of the element until the end tag of the same element. For some situations, notably evaluation of patterns, a stronger test is required: the construct must be evaluated while the stream is positioned at the start tag, and without changing the position of the input stream. This is achieved by the definition that follows.

[Definition: A construct C is motionless with respect to its context item if (a) it is guaranteed-streamable with respect to its context item (as defined above), and (b) in the set of paths starting at C in the data flow graph, no path contains a downward step (child, descendant, or descendant-or-self).]

18.4.6 Notes on the streamability of paths using the descendant axis

This section is a commentary describing future work; it will not form part of the final specification.

Issue 26 (descendant-then-child):

The restriction that a path such as .//section/head is non-streamable is too severe; it needs to be relaxed.

In the analysis given in the previous section, a path containing a descendant step followed by a child step is deemed non-streamable. For example, this applies to the path expression .//section/head. In fact, it even applies to the path expression .//employee, because this is merely an abbreviation for ./descendant-or-self::node()/child::employee

This restriction is probably unacceptable. This section discusses how it can be relaxed.

The reason for the restriction is that a nested-loop evaluation of the expression is not guaranteed to return results in document order. Consider for example the perverse case of a document where the head element of a section appears at the end:

<section nr="1">
  <section nr="1.1">
    <head>section 1.1</head>
  </section>
  <section nr="1.2">
    <head>section 1.2</head>
  </section>
  <head>section 1</head>
</section>

While the instruction <xsl:value-of select="//section/head"/> will output the headings in document order as "section 1.1 section 1.2 section 1", the xsl:for-each instruction

<xsl:for-each select="//section">
  <xsl:value-of select="head"/>
</xsl:for-each>

will output them in "logical order" as "section 1 section 1.1 section 1.2" (ignoring whitespace). Here the output is not in the same order as the input, so by definition the construct is not fully streamable -- some kind of buffering is needed, either of the input or the output.

There are several possible ways one could relax the rules to make such expressions streamable.

One could make a distinction between path expressions (which return results in document order) and nested loops such as xsl:for-each (which do not).

Currently the data flow graph makes no distinction between the two cases: the data flow graph for the two cases is exactly the same. We could modify the analysis so that the path .//section/head is treated effectively as ./descendant::head[parent::section], which is guaranteed-streamable under the current rules.
One could go further and make all downwards paths guaranteed-streamable, even if they use nested-loop constructs such as xsl:for-each. This has the advantage that it would license the use of instructions such as this:
```
<xsl:for-each select=".//employee">
  <xsl:value-of select="emp-nr"/>
</xsl:for-each>                     
                  
```
which most users would expect to be streamable, and which in practice are streamable in nearly all commonly encountered cases. There are then two ways one could deal with the unusual cases that are not actually streamable (that is, the cases where the order of the output is not the same as the order of the input):
- One could require the processor to perform buffering in this situation, to achieve the necessary reordering of the output (note that no buffering is needed unless the structure is actually recursive, that is, the descendant axis actually selects a node that is a descendant of another selected node)
  
  An existing implementation has shown that this is a feasible approach; but it does have the disadvantage that the worst-case memory requirement is unpredictable.
- One could require the processor to signal a dynamic error in this case.
One could in principle make the rules schema-aware, so that the expression .//employee becomes guaranteed-streamable if the schema indicates that an employee element cannot contain another employee element. However, doing this in an interoperable way would require a complete definition of the static type inferencing rules, which is a major undertaking; it would also require users to write schema-aware stylesheets, which for many would be a major change from current practice.
One could make the for expression streamable only in the case where the unordered^FO function has been used to relax the ordering rules, by writing for $s in unordered(//section) return $s/last-changed

In the meantime, note that the outermost function is provided to enable paths that are potentially recursive to be declared, in effect, as selecting non-nested nodes, which guarantees the streamability of an expression that uses this function (though this has not yet been factored into the streamability rules).

18.4.7 Examples of streamability analysis

Example: Analysis of an xsl:stream instruction using xsl:iterate

Consider the following instruction:

 <xsl:stream href="transactions.xml">
   <xsl:iterate select="account/transaction">
      <xsl:param name="balance" select="0.00" as="xs:decimal"/>
      <xsl:variable name="newBalance" select="$balance + xs:decimal(@value)"/>
      <balance date="{@date}" value="{$newBalance}"/>
      <xsl:next-iteration>
        <xsl:with-param name="balance" select="$newBalance"/>
      </xsl:next-iteration>
    </xsl:iterate>
  </xsl:stream>

The expression tree for this and data flow graph for this construct are shown below.

Some simplifying assumptions have been made in creating this graph. No data flow arcs are shown for values that are known to be atomic, such as the variables $balance and $newBalance, because these can never affect the streamability analysis. Equally, no descendant-or-self steps have been added to reflect atomization of nodes that are known to be attributes.

The data flow graph can be seen more clearly by showing only the data flow paths starting from the xsl:stream instruction and the e-nodes they connect (these arcs are shown in red on the previous diagram):

There are thus two navigation paths emanating from the xsl:stream instruction, both of the form child/child/attribute. All the conditions for streamability are satisfied, so the xsl:stream construct is guaranteed-streamable.

Example: Analysis of a template rule including a choice

In this example we assume that mode M has been declared to be a streamable mode, so we need to check that the template rule is streamable.

<xsl:template match="para" mode="M">
  <xsl:choose>
    <xsl:when test="ancestor::para">
      <span>
        <xsl:apply-templates mode="M"/>
      </span>
    </xsl:when>   
    <xsl:otherwise>
      <p>
        <xsl:apply-templates mode="M"/>
      </p>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

The resulting expression tree and data flow graph are shown below.

The expression tree has been extended with descendant-or-self steps in four places:

Both calls of xsl:apply-templates appear in the content of literal result elements. This means that in constructing the parent element, the value returned by the xsl:apply-templates instruction will be copied. Copying navigates to all the descendant nodes, so a descendant-or-self step is added to reflect this.
Both calls of xsl:apply-templates are invoking a template in a streamable mode, and can therefore assume that the template being invoked follows the rules for streamable templates. Such templates must be assumed to process the subtree under the selected nodes, which is reflected by adding a descendant-or-self step to the select expression. (The child::node() step that represents the default value of the select attribute has also been made explicit.)

The data flow paths emanating from the xsl:template construct can be seen more clearly if everything else is removed:

At first sight, this violates the rule that there must be only one path that makes a downward selection. However, closer examination shows that the two paths are mutually exclusive because they occur in different branches of a conditional instruction. The template is therefore guaranteed-streamable.

Example: A non-streamable example using local variables

This example attempts to select all the transactions in a banking file where the amount exceeds $1000 and the bank branch is Skipton.

<xsl:stream href="transactions.xml">
  <xsl:for-each select="account/transaction">
    <xsl:variable name="branch" 
         select="doc('branches.xml')/descendant::branch
                           [code = current()/branchCode]"/>
    <xsl:copy-of 
         select=".[amount gt 1000.00 and $branch/name eq 'Skipton']"/>
  </xsl:for-each>
</xsl:stream>

The raw expression tree for the xsl:stream instruction is like this:

This tree must first be expanded to include the effects of atomization. The result of child::code is atomized, because it is an argument to a comparison operator. The same applies to child::branch, child::amount, and child::name. All these expressions therefore have an implicit descendant-or-self::node() added to them. In addition, the xsl:copy-of instruction also accesses all the descendant nodes of the node being copied, so this results in another implicit descendant-or-self::node() bing added to the tree.

After adding these nodes, and tracing the use of variables and context, the expression tree and its data flow graph look like this. For space reasons, the descendant-or-self::node() e-nodes are labelled "//"

The paths emanating from the root e-node (the xsl:stream instruction) can be seen on the simplified diagram:

In this tree there are three paths in which child::transaction is followed by a downward selection. The construct is therefore not streamable, and the processor must report a static error.

The code can be made streamable by including a call to the copy-of function, thus:

<xsl:stream href="transactions.xml"> 
  <xsl:for-each select="account/transaction/copy-of()">
    <xsl:variable name="branch" 
       select="doc('branches.xml')//branch[code = current()/branchCode]"/>
    <xsl:copy-of select=".[amount gt 1000.00 and $branch/name eq 'Skipton']"/>
  </xsl:for-each>
</xsl:stream>

The effect of this on the path analysis is that all the three selections that previously depended on child::transaction now depend on the result of the copy-of() call. This always returns newly constructed nodes, so these dependencies no longer lead back to the xsl:stream instruction, and can therefore be excluded from the path map.

18.4.8 Notes on the streamability algorithm

The algorithm for creating a path map representing the axes of navigation through a source document is inspired by the algorithms used for document projection in [Marian & Siméon].

There are a number of differences, however:

The algorithm published by Marian and Siméon is for XQuery rather than XSLT. Moreover, it is for a core subset of XQuery, since the authors were able to build on previous work showing that XQuery, already a smaller language than XSLT, could be reduced to an even smaller core. The analysis for XSLT is inevitably more complex because of the need to handle dynamic template invocation. However, a practical implementation could simplify the expression tree very substantially before analysis starts, since much of the information on the tree makes no contribution to the analysis.
Marian and Siméon analyze the paths followed by a query in order to determine which parts of the input tree are reachable. This means, for example, that duplicate paths can be eliminated, and that it makes no difference whether two paths are mutually exclusive. For streamability analysis, multiple instances of navigation to the same place are significant, and it is also necessary to consider the paths as a tree, not simply as a set of independent paths from the root to the leaves.

18.5 The copy-of function

copy-of() as node()

copy-of($node as node()?) as node()?

The zero-argument form of this function has the same effect as calling copy-of(.), that is, supplying the context item as an implicit argument.

The function returns a deep copy of the node supplied as the argument $node. If the argument is an empty sequence, the function returns an empty sequence. The effect is the same as that of the xsl:copy-of instruction with copy-namespaces set to yes and validation set to preserve.

If the function is called more than once with the same argument, it is implementation-dependent whether each call returns the same node, or whether multiple calls return different nodes. That is, the result of the expression copy-of($X) is copy-of($X) is implementation-dependent.

The copy-of function is available for use (and is primarily intended for use) when a source document is processed using streaming. It can also be used when not streaming. The effect is to take a copy of the subtree rooted at the current node, and to make this available as a normal tree, that can be processed without any of the restrictions that apply while streaming, for example only being able to process children once. The copy, of course, does not include siblings or ancestors of the context node, so any attempt to navigate to siblings or ancestors will result in an empty sequence being returned.

Example: Using copy-of() while streaming

This example copies from the source document all employees who work in marketing and are based in Dubai. Because there are two accesses using the child axis, it is not possible to do this without buffering each employee in memory, which can be achieved using the copy-of function.

<xsl:stream href="employees.xml">
  <xsl:sequence select="employees/employee/copy-of()
                          [department='Marketing' and location='Dubai']"/>
</xsl:stream>

18.6 The snapshot function

snapshot() as node()

snapshot($node as node()?) as node()?

The zero-argument form of this function has the same effect as calling snapshot(.), that is, supplying the context item as an implicit argument.

The function returns a snapshot of the node supplied as the argument $node. If the argument is an empty sequence, the function returns an empty sequence.

If the function is called more than once with the same argument, it is implementation-dependent whether each call returns the same node, or whether multiple calls return different nodes. That is, the result of the expression snapshot($X) is snapshot($X) is implementation-dependent.

[Definition: A snapshot of a node N is a deep copy of N, as produced by the xsl:copy-of instruction with copy-namespaces set to yes and validation set to preserve, with the additional property that for every ancestor of N, the copy also has a corresponding ancestor whose name, node-kind, and base URI are the same as the corresponding ancestor of N, and that has copies of the attributes and namespaces of the corresponding ancestor of N. But the ancestor has a type annotation of xs:anyType, has the properties nilled, is-ID, and is-IDREF set to false, and has no children other than the child that is a copy of N or one of its ancestors.]

More formally, a snapshot of a node is the result of the following function.

<xsl:function name="fn:snapshot" as="node()?">
  <xsl:param name="node" as="node()?"/>
  <xsl:sequence select="f:parent-copy($node, $node/ancestor::node(), 1)"/>
</xsl:function>
 
<xsl:function name="f:parent-copy" as="node()?">
  <xsl:param name="node" as="node()?"/>
  <xsl:param name="ancestors" as="node()*"/>
  <xsl:param name="level" as="xs:integer"/>    
  <xsl:choose>
    <xsl:when test="empty($node)">
      <xsl:sequence select="()"/>
    </xsl:when>
    <xsl:when test="empty($ancestors)">
      <xsl:sequence select="$node/descendant-or-self::node()[$level]"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:variable name="p" as="node()?">
        <xsl:for-each select="$ancestors[last()]">
          <xsl:copy validation="strip">
            <xsl:copy-of select="@*" validation="preserve"/>
            <xsl:copy-of select="$node" validation="preserve"/>
          </xsl:copy>
        </xsl:for-each>
      </xsl:variable>
      <xsl:sequence select="f:parent-copy($p, 
                      $ancestors[position() lt last()], $level+1)"/>
    </xsl:otherwise>
  </xsl:choose>
  </xsl:function>

Note:

The <xsl:when test="empty($ancestors)"> branch of this code is a little obscure. At this stage $node represents the root of a constructed tree that includes copies of all the ancestors of the original node supplied to the snapshot function, together with that node and all its descendants. The result of the snapshot function is not $node (the root of this constructed tree), but rather the node within the constructed tree that corresponds to the original node. This can be found by searching the descendants of $node. In fact it is the node that is found $level nodes below $node, which can be selected as $node/descendant-or-self::node()[$level] because each relevant node has exactly one child.

Issue 27 (snapshot-on-root-node):

The code given here is incorrect in the case where snapshot is applied to a parentless node: it should return a copy of the node, but actually returns the original.

The snapshot function is available for use (and is primarily intended for use) when a source document is processed using streaming. It can also be used when not streaming. The effect is to take a copy of the subtree rooted at the current node, along with copies of the ancestors and their attributes, and to make this available as a normal tree, that can be processed without any of the restrictions that apply while streaming, for example only being able to process children once. The copy, of course, does not include siblings of the context node or of its ancestors, so any attempt to navigate to these siblings will result in an empty sequence being returned.

Example: Using snapshot() while streaming

This example copies from the source document all employees who work in marketing and are based in Dubai. It assumes that employees are grouped by location. Because there are two accesses using the child axis (referencing department and salary), it is not possible to do this without buffering each employee in memory. The snapshot function is used in preference to the simpler copy-of so that access to attributes of the parent location element remains possible.

<xsl:stream href="employees.xml">
  <xsl:for-each select="locations/location[@name='Dubai']
                          /employee/snapshot()[department='Marketing']">
    <employee>
      <location code="{../@code}"/>
      <salary value="{salary}"/>
    </employee>
  </xsl:for-each>
</xsl:stream>

18.7 The outermost function

outermost($nodes as node()*) as node()*

The outermost takes as input a sequence of nodes, and returns those nodes within the sequence that have no ancestor that is itself a member of the sequence; the nodes are returned in document order with duplicates eliminated.

That is, the effect of the function is equivalent to the expression:

$nodes[not(ancestor::node() intersect $nodes)]

For example, the expression outermost(//table) selects every table element that is not nested within another table element.

Note:

As noted in 18.4.6 Notes on the streamability of paths using the descendant axis, path expressions such as .//section/head cause a problem in streamability analysis because there is no guarantee that a nested-loop evaluation of the expression will deliver nodes in document order. This is caused by the fact that section elements can potentially contain further section elements.

This is not the case for the expression outermost(.//section)/head: for this expression, a nested-loop evaluation strategy will return the nodes in document order.

There are two situations in which the outermost function can potentially be useful. Firstly, if it is known that section elements will never be nested, the expression outermost(.//section) is equivalent to .//section, but is more tractable in terms of its streamability. Secondly, if the section elements are nested, there may well be cases where only the outermost sections are to be processed.

Issue 28 (streamability-of-outermost):

Note however that the streamability analysis as currently written does not take calls on the outermost function into account.

18.8 The innermost function

innermost($nodes as node()*) as node()*

The innermost takes as input a sequence of nodes, and returns every node within the sequence that is not an ancestor of another node within the sequence; the nodes are returned in document order with duplicates eliminated.

That is, the effect of the function is equivalent to the expression:

$nodes except $nodes/ancestor::node()

For example, the expression innermost(//table) selects every table element that does not contain a nested table element.

Note:

Unlike the outermost function, this function does not help in making expressions streamable. It is provided purely for symmetry.

18.9 The has-children function

has-children() as xs:boolean

To be specified.

Issue 29 (has-children):

The Working Group is considering defining a function has-children which returns true if the context item has one or more child nodes. This function would be defined as motionless, allowing it to be used for example in the predicate of a pattern. Implementation requires a one-parser-event lookahead. The primary use case is for creating lists or tables in streaming mode, where the wrapper element (for example ul or table) is to be generated only if the list is non-empty. Most current solutions to this problem require two downward selections, one to test if the list is empty and one to iterate over its contents. There is a solution using xsl:for-each-group to generate a singleton group, but it involves rather artificial coding.

19 Additional Functions

This section describes XSLT-specific additions to the core function library. Some of these additional functions also make use of information specified by declarations in the stylesheet; this section also describes these declarations.

19.1 Multiple Source Documents

19.1.1 The `document` function

document($uri-sequence as item()*) as node()*

document($uri-sequence as item()*, $base-node as node()) as node()*

The document function allows access to XML documents identified by a URI.

The first argument contains a sequence of URI references. The second argument, if present, is a node whose base URI is used to resolve any relative URI references contained in the first argument.

A sequence of absolute URI references is obtained as follows.

For an item in $uri-sequence that is an instance of xs:string, xs:anyURI, or xs:untypedAtomic, the value is cast to xs:anyURI. If the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved against the base URI of $base-node if supplied, or against the base URI from the static context otherwise (this will usually be the base URI of the stylesheet module). A relative URI reference is resolved against a base URI using the rules defined in [RFC3986].
For an item in $uri-sequence that is a node, the node is atomized. The result must be a sequence whose items are all instances of xs:string, xs:anyURI, or xs:untypedAtomic. Each of these values is cast to xs:anyURI, and if the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved against the base URI of $base-node if supplied, or against the base URI of the node that contained it otherwise.

Note:

The XPath rules for function calling ensure that it is a type error if the supplied value of the second argument is anything other than a single node. If XPath 1.0 compatibility mode is enabled, then a sequence of nodes may be supplied, and the first node in the sequence will be used.

Each of these absolute URI references is then processed as follows. Any fragment identifier that is present in the URI reference is removed, and the resulting absolute URI is cast to a string and then passed to the doc^FO function defined in [Functions and Operators]. This returns a document node. If an error occurs during evaluation of the doc^FO function, the processor may either signal this error in the normal way, or may recover by ignoring the failure, in which case the failing URI will not contribute any nodes to the result of the document function.

If the URI reference contained no fragment identifier, then this document node is included in the sequence of nodes returned by the document function.

If the URI reference contained a fragment identifier, then the fragment identifier is interpreted according to the rules for the media type of the resource representation identified by the URI, and is used to select zero or more nodes that are descendant-or-self nodes of the returned document node. As described in 2.3 Initiating a Transformation, the media type is available as part of the evaluation context for a transformation.

[ERR XTRE1160] When a URI reference contains a fragment identifier, it is a recoverable dynamic error if the media type is not one that is recognized by the processor, or if the fragment identifier does not conform to the rules for fragment identifiers for that media type, or if the fragment identifier selects something other than a sequence of nodes (for example, if it selects a range of characters within a text node). The optional recovery action is to ignore the fragment identifier and return the document node. The set of media types recognized by a processor is implementation-defined.

Note:

The recovery action here is different from XSLT 1.0

The sequence of nodes returned by the function is in document order, with no duplicates. This order has no necessary relationship to the order in which URIs were supplied in the $uri-sequence argument.

Note:

One effect of these rules is that unless XML entities or xml:base are used, and provided that the base URI of the stylesheet module is known, document("") refers to the document node of the containing stylesheet module (the definitive rules are in [RFC3986]). The XML resource containing the stylesheet module is processed exactly as if it were any other XML document, for example there is no special recognition of xsl:text elements, and no special treatment of comments and processing instructions.

19.1.2 The `uri-collection` function

uri-collection() as xs:string*

uri-collection($href as xs:string?) as xs:string*

The uri-collection returns the document URIs of the documents in a collection. Unlike the collection^FO function, it does not retrieve the documents themselves.

The zero-argument form of the function returns the URIs of the documents in the default collection. If the value of the default collection is undefined an error is raised ([ERR FODC0002] ^FO).

The single-argument form returns the URIs of the documents in the collection with a given collection URI. If the value of the argument is an empty sequence, the action is as for the zero-argument form of the function. If the argument is a relative URI reference, it is resolved against the base URI property of the static context. If the argument is not a valid xs:anyURI, or if the dynamic context does not include a collection with this URI, then an error is raised ([ERR FODC0004] ^FO).

The function is defined so that the expression for $u in uri-collection(X) return doc($u), if it succeeds, will always return the same result as the expression collection(X).

Note:

There are several reasons it might be appropriate to retrieve the URIs of the documents in a collection without retrieving the documents themselves. For example:

It allows the documents to be processed in streaming mode using xsl:stream
It allows recovery from failures to read, parse, or validate individual documents, by calling the doc^FO function within the scope of an xsl:try instruction
It allows access to non-XML documents within a collection using the unparsed-text function
It allows selection of which documents to read based on their URI, for example they can be filtered to select those whose URIs end in .xml

However, there may be collections that cannot be processed in this way: specifically, those that contain nodes other than document nodes, and those that contain document nodes having no document URI. Conversely, there may be collections (such as those containing non-XML resources) that can be processed using the uri-collection function but not the collection^FO function.

Issue 30 (transfer-uri-collection):

A decision in principle has been reached for uri-collection to become a standard XPath 2.1 function.

19.2 Reading Text Files

19.2.1 The `unparsed-text` function

unparsed-text($href as xs:string?) as xs:string?

unparsed-text($href as xs:string?, $encoding as xs:string) as xs:string?

Issue 31 (transfer-unparsed-text):

A decision in principle has been reached for unparsed-text and unparsed-text-available to become standard XPath 2.1 functions.

The unparsed-text function reads an external resource (for example, a file) and returns its contents as a string.

The $href argument must be a string in the form of a URI reference, which must contain no fragment identifier, and must identify a resource that can be read as text. If the URI is a relative URI reference, then it is resolved relative to the base URI from the static context.

If the value of the $href argument is an empty sequence, the function returns an empty sequence.

Note:

If a different base URI is appropriate (for example, when resolving a relative URI reference read from a source document) then the stylesheet author should resolve the relative URI reference using the resolve-uri^FO function before passing it to the unparsed-text function.

The $encoding argument, if present, is the name of an encoding. The values for this attribute follow the same rules as for the encoding attribute in an XML declaration. The only values which every implementation is required to recognize are utf-8 and utf-16.

The encoding of the external resource is determined as follows:

external encoding information is used if available, otherwise
if the media type of the resource is text/xml or application/xml (see [RFC2376]), or if it matches the conventions text/*+xml or application/*+xml (see [RFC3023] and/or its successors), then the encoding is recognized as specified in [XML 1.0], otherwise
the value of the $encoding argument is used if present, otherwise
the processor may use implementation-defined heuristics to determine the likely encoding, otherwise
UTF-8 is assumed.

Note:

The above rules are chosen for consistency with [XInclude]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

[ERR XTDE1170] It is a non-recoverable dynamic error if a URI contains a fragment identifier, or if it cannot be used to retrieve a resource containing text.

[ERR XTDE1190] It is a non-recoverable dynamic error if a resource contains octets that cannot be decoded into Unicode characters using the specified encoding, or if the resulting characters are not permitted XML characters. This includes the case where the processor does not support the requested encoding.

[ERR XTDE1200] It is a non-recoverable dynamic error if the second argument of the unparsed-text function is omitted and the processor cannot infer the encoding using external information and the encoding is not UTF-8.

The result is a string containing the text of the resource retrieved using the URI.

Note:

If the text file contains characters such as < and &, these will typically be output as < and & when the string is written to a final result tree and serialized as XML or HTML. If these characters actually represent markup (for example, if the text file contains HTML), then the stylesheet can attempt to write them as markup to the output file using the disable-output-escaping attribute of the xsl:value-of instruction (see 23.2 Disabling Output Escaping). Note, however, that implementations are not required to support this feature.

Example: Copying Unparsed HTML Boilerplate

This example attempts to read an HTML file and copy it, as HTML, to the serialized output file:

<xsl:output method="html"/>

<xsl:template match="/">
  <xsl:value-of select="unparsed-text('header.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
  <xsl:apply-templates/>
  <xsl:value-of select="unparsed-text('footer.html', 'iso-8859-1')"
                disable-output-escaping="yes"/>
</xsl:template>

Example: Splitting an Input File into a Sequence of Lines

Often it is necessary to split a text file into a sequence of lines, representing each line as a string. This can be achieved by using the unparsed-text function in conjunction with the XPath tokenize^FO function. For example:

<xsl:for-each select="tokenize(unparsed-text($in), '\r?\n')">
 ...
</xsl:for-each>

Note that the unparsed-text function does not normalize line endings. This example has been written to recognize both Unix and Windows conventions for end-of-line, namely a single newline (#x0A) character or a carriage return / line feed pair (#x0D #x0A). It differs from the unparsed-text-lines function, however, in that it does not recognize a carriage return on its own as a line ending, and it does not give special treatment to a newline appearing at the end of the file.

19.2.2 The `unparsed-text-lines` function

unparsed-text-lines($href as xs:string?) as xs:string?*

unparsed-text-lines($href as xs:string?, $encoding as xs:string) as xs:string?*

The unparsed-text-lines function reads an external resource (for example, a file) and returns its contents as a sequence of strings, separated at newline boundaries.

The result of the single-argument function is the same as the result of the expression tokenize(unparsed-text($href), '\r\n|\r|\n')[not(position()=last() and .='')]. The result of the two-argument function is the same as the result of the expression tokenize(unparsed-text($href, $encoding), '\r\n|\r|\n'))[not(position()=last() and .='')].

The result is a thus a sequence of strings containing the text of the resource retrieved using the URI, each string representing one line of text. Lines are separated by one of the sequences #x0A, #x0D, or #x0D #x0A. The characters representing the newline are not included in the returned strings. If there are two adjacent newline sequences, a zero-length string will be returned to represent the empty line; but if the external resource ends with a newline sequence, no zero-length string will be returned as the last item in the result.

Note:

This function has been added in XSLT 2.1 for three reasons: to do the line splitting in a way consistent with the rules applied during XML parsing; to do it without recourse to regular expressions (which is likely to be more efficient), and to make it easier for processors to read the input file line by line, which is likely to use less memory.

19.2.3 The unparsed-text-available function

Because errors in evaluating the unparsed-text and unparsed-text-lines functions are non-recoverable, two functions are provided to allow a stylesheet to determine whether a call with particular arguments would succeed:

unparsed-text-available($href as xs:string?) as xs:boolean

`unparsed-text-available`(	`$href`	`as` `xs:string?`,
`unparsed-text-available`(	`$encoding`	`as` `xs:string?`) `as` `xs:boolean`

The unparsed-text-available function determines whether a call on the unparsed-text function with identical arguments would return a string.

If the first argument is an empty sequence, the function returns false. If the second argument is an empty sequence, the function behaves as if the second argument were omitted.

In other cases, the function returns true if a call on unparsed-text with the same arguments would succeed, and false if a call on unparsed-text with the same arguments would fail with a non-recoverable dynamic error.

Note:

This requires that the unparsed-text-available function should actually attempt to read the resource identified by the URI, and check that it is correctly encoded and contains no characters that are invalid in XML. Implementations may avoid the cost of repeating these checks for example by caching the validated contents of the resource, to anticipate a subsequent call on the unparsed-text or unparsed-text-lines function. Alternatively, implementations may be able to rewrite an expression such as if (unparsed-text-available(A)) then unparsed-text(A) else ... to generate a single call internally.

The functions unparsed-text, unparsed-text-lines , and unparsed-text-available have the same requirement for stability^FO as the functions doc^FO and doc-available^FO defined in [Functions and Operators]. This means that unless the user has explicitly stated a requirement for a reduced level of stability, either of these functions if called twice with the same arguments during the course of a transformation must return the same results each time; moreover, the results of a call on unparsed-text-available must be consistent with the results of a subsequent call on unparsed-text or unparsed-text-lines with the same arguments.

Issue 32 (function-stability):

The functions in this specification need to be classified more clearly in terms of their stability properties, along the lines being developed in Functions and Operators.

19.3 Keys

Keys provide a way to work with documents that contain an implicit cross-reference structure. They make it easier to locate the nodes within a document that have a given value for a given attribute or child element, and they provide a hint to the implementation that certain access paths in the document need to be efficient.

19.3.1 The `xsl:key` Declaration

 <xsl:key name = qname match = pattern use? = expression collation? = uri >  </xsl:key>

The xsl:key declaration is used to declare keys. The name attribute specifies the name of the key. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. The match attribute is a Pattern; an xsl:key element applies to all nodes that match the pattern specified in the match attribute.

[Definition: A key is defined as a set of xsl:key declarations in the stylesheet that share the same name.]

The value of the key may be specified either using the use attribute or by means of the contained sequence constructor.

[ERR XTSE1205] It is a static error if an xsl:key declaration has a use attribute and has non-empty content, or if it has empty content and no use attribute.

If the use attribute is present, its value is an expression specifying the values of the key. The expression will be evaluated with a singleton focus based on the node that matches the pattern. The result of evaluating the expression is atomized.

Similarly, if a sequence constructor is present, it is used to determine the values of the key. The sequence constructor will be evaluated with the node that matches the pattern as the context node. The result of evaluating the sequence constructor is atomized.

[Definition: The expression in the use attribute and the sequence constructor within an xsl:key declaration are referred to collectively as the key specifier. The key specifier determines the values that may be used to find a node using this key.]

Note:

There is no requirement that all the values of a key should have the same type.

The presence of an xsl:key declaration makes it easy to find a node that matches the match pattern if any of the values of the key specifier (when applied to that node) are known. It also provides a hint to the implementation that access to the nodes by means of these values needs to be efficient (many implementations are likely to construct an index or hash table to achieve this). Note that the key specifier in general returns a sequence of values, and any one of these may be used to locate the node.

Note:

An xsl:key declaration is not bound to a specific source document. The source document to which it applies is determined only when the key function is used to locate nodes using the key. Keys can be used to locate nodes within any source document (including temporary trees), but each use of the key function searches one document only.

The optional collation attribute is used only when deciding whether two strings are equal for the purposes of key matching. Specifically, two values $a and $b are considered equal if the result of the function call compare($a, $b, $collation) is zero. The effective collation for an xsl:key declaration is the collation specified in its collation attribute if present, resolved against the base URI of the xsl:key element, or the default collation that is in scope for the xsl:key declaration otherwise; the effective collation must be the same for all the xsl:key declarations making up a key.

[ERR XTSE1210] It is a static error if the xsl:key declaration has a collation attribute whose value (after resolving against the base URI) is not a URI recognized by the implementation as referring to a collation.

[ERR XTSE1220] It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different effective collations. Two collations are the same if their URIs are equal under the rules for comparing xs:anyURI values, or if the implementation can determine that they are different URIs referring to the same collation.

It is possible to have:

multiple xsl:key declarations with the same name;
a node that matches the match patterns of several different xsl:key declarations, whether these have the same key name or different key names;
a node that returns more than one value from its key specifier;
a key value that identifies more than one node (the key values for different nodes do not need to be unique).

An xsl:key declaration with higher import precedence does not override another of lower import precedence; all the xsl:key declarations in the stylesheet are effective regardless of their import precedence.

19.3.2 The `key` Function

key($key-name as xs:string, $key-value as xs:anyAtomicType*) as node()*

`key`(	`$key-name`	`as` `xs:string`,
	`$key-value`	`as` `xs:anyAtomicType*`,
	`$top`	`as` `node()`) `as` `node()*`

The key function does for keys what the element-with-id^FO function does for IDs.

The $key-name argument specifies the name of the key. The value of the argument must be a lexical QName, which is expanded as described in 5.1 Qualified Names.

[ERR XTDE1260] It is a non-recoverable dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName, or if the name obtained by expanding the QName is not the same as the expanded name of any xsl:key declaration in the stylesheet. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

The $key-value argument to the key function is considered as a sequence. The set of requested key values is formed by atomizing the supplied value of the argument, using the standard function conversion rules. Each of the resulting atomic values is considered as a requested key value. The result of the function is a sequence of nodes, in document order and with duplicates removed, comprising those nodes in the selected subtree (see below) that are matched by an xsl:key declaration whose name is the same as the supplied key name, where the result of evaluating the key specifier contains a value that is equal to one of these requested key values, under the rules appropriate to the XPath eq operator for the two values in question, using the collation attributes of the xsl:key declaration when comparing strings. No error is reported if two values are encountered that are not comparable; they are regarded for the purposes of this function as being not equal.

Note:

Under the rules for the eq operator, untyped atomic values are converted to strings, not to the type of the other operand. This means, for example, that if the expression in the use attribute returns a date, supplying an untyped atomic value in the call to the key function will return an empty sequence.

If the second argument is an empty sequence, the result of the function will be an empty sequence.

Different rules apply when XSLT 1.0 compatible behavior is enabled. Specifically, if any of the xsl:key elements in the definition of the key is processed with XSLT 1.0 behavior, then the value of the key specifier and the value of the second argument of the key function are both converted after atomization to a sequence of strings, by applying a cast to each item in the sequence, before performing the comparison.

The third argument is used to identify the selected subtree. If the argument is present, the selected subtree is the set of nodes that have $top as an ancestor-or-self node. If the argument is omitted, the selected subtree is the document containing the context node. This means that the third argument effectively defaults to /.

[ERR XTDE1270] It is a non-recoverable dynamic error to call the key function with two arguments if there is no context node, or if the root of the tree containing the context node is not a document node; or to call the function with three arguments if the root of the tree containing the node supplied in the third argument is not a document node.

The result of the key function can be described more specifically as follows. The result is a sequence containing every node $N that satisfies the following conditions:

$N/ancestor-or-self::node() intersect $top is non-empty. (If the third argument is omitted, $top defaults to /)
$N matches the pattern specified in the match attribute of an xsl:key declaration whose name attribute matches the name specified in the $key-name argument.
When the key specifier of that xsl:key declaration is evaluated with a singleton focus based on $N, the atomized value of the resulting sequence includes a value that compares equal to at least one item in the atomized value of the sequence supplied as $key-value, under the rules of the eq operator with the collation selected as described above.

The sequence returned by the key function will be in document order, with duplicates (that is, nodes having the same identity) removed.

Example: Using a Key to Follow Cross-References

For example, given a declaration

<xsl:key name="idkey" match="div" use="@id"/>

an expression key("idkey",@ref) will return the same nodes as id(@ref), assuming that the only ID attribute declared in the XML source document is:

<!ATTLIST div id ID #IMPLIED>

and that the ref attribute of the context node contains no whitespace.

Suppose a document describing a function library uses a prototype element to define functions

<prototype name="sqrt" return-type="xs:double">
  <arg type="xs:double"/>
</prototype>

and a function element to refer to function names

<function>sqrt</function>

Then the stylesheet could generate hyperlinks between the references and definitions as follows:

<xsl:key name="func" match="prototype" use="@name"/>

<xsl:template match="function">
<b>
  <a href="#{generate-id(key('func',.))}">
    <xsl:apply-templates/>
  </a>
</b>
</xsl:template>

<xsl:template match="prototype">
  <p>
    <a name="{generate-id()}">
      <b>Function: </b>
      ...
    </a>
  </p>
</xsl:template>

When called with two arguments, the key function always returns nodes that are in the same document as the context node. To retrieve a node from any other document, it is necessary either to change the context node, or to supply a third argument.

Example: Using Keys to Reference other Documents

For example, suppose a document contains bibliographic references in the form <bibref>XSLT</bibref>, and there is a separate XML document bib.xml containing a bibliographic database with entries in the form:

<entry name="XSLT">...</entry>

Then the stylesheet could use the following to transform the bibref elements:

<xsl:key name="bib" match="entry" use="@name"/>

<xsl:template match="bibref">
  <xsl:variable name="name" select="."/>
  <xsl:apply-templates select="document('bib.xml')/key('bib',$name)"/>
</xsl:template>

Note:

This relies on the ability in XPath 2.0 to have a function call on the right-hand side of the / operator in a path expression.

The following code would also work:

<xsl:key name="bib" match="entry" use="@name"/>

<xsl:template match="bibref">
  <xsl:apply-templates select="key('bib', ., document('bib.xml'))"/>
</xsl:template>

19.4 Defining a Decimal Format

format-number($value as numeric?, $picture as xs:string) as xs:string

`format-number`(	`$value`	`as` `numeric?`,
	`$picture`	`as` `xs:string`,
	`$decimal-format-name`	`as` `xs:string`) `as` `xs:string`

The format-number^FO function formats $value as a string using the picture string specified by the $picture argument and the decimal-format named by the $decimal-format-name argument, or the default decimal-format, if there is no $decimal-format-name argument. The syntax of the picture string is described in 19.4.1 Processing the Picture String.

The $value argument may be of any numeric data type (xs:double, xs:float, xs:decimal, or their subtypes including xs:integer). Note that if an xs:decimal is supplied, it is not automatically promoted to an xs:double, as such promotion can involve a loss of precision.

If the supplied value of the $value argument is an empty sequence, the function behaves as if the supplied value were the xs:double value NaN.

The value of $decimal-format-name must be a lexical QName, which is expanded as described in 5.1 Qualified Names. The result of the function is the formatted string representation of the supplied number.

[ERR XTDE1280] It is a non-recoverable dynamic error if the name specified as the $decimal-format-name argument is not a valid QName, or if its prefix has not been declared in an in-scope namespace declaration, or if the stylesheet does not contain a declaration of a decimal-format with a matching expanded-QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

 <xsl:decimal-format name? = qname decimal-separator? = char grouping-separator? = char infinity? = string minus-sign? = char NaN? = string percent? = char per-mille? = char zero-digit? = char digit? = char pattern-separator? = char />

The xsl:decimal-format element controls the interpretation of a picture string used by the format-number^FO function.

[Definition: The picture string is the string supplied as the second argument of the format-number^FO function.]

Note:

The format-number^FO function, previously defined in this specification, is now a core function defined in [Functions and Operators].

A stylesheet may contain multiple xsl:decimal-format declarations and may include or import stylesheet modules that also contain xsl:decimal-format declarations. The name of an xsl:decimal-format declaration is the value of its name attribute, if any.

[Definition: All the xsl:decimal-format declarations in a stylesheet that share the same name are grouped into a named decimal format; those that have no name are grouped into a single unnamed decimal format.]

If a stylesheet does not contain a declaration of the unnamed decimal format, a declaration equivalent to an xsl:decimal-format element with no attributes is implied.

The attributes of the xsl:decimal-format declaration establish values for a number of variables used as input to the algorithm followed by the format-number^FO function. An outline of the purpose of each attribute is given below; however, the definitive explanations are given as part of the specification of format-number^FO.

For any named decimal format, the effective value of each attribute is taken from an xsl:decimal-format declaration that has that name, and that specifies an explicit value for the required attribute. If there is no such declaration, the default value of the attribute is used. If there is more than one such declaration, the one with highest import precedence is used.

For any unnamed decimal format, the effective value of each attribute is taken from an xsl:decimal-format declaration that is unnamed, and that specifies an explicit value for the required attribute. If there is no such declaration, the default value of the attribute is used. If there is more than one such declaration, the one with highest import precedence is used.

[ERR XTSE1290] It is a static error if a named or unnamed decimal format contains two conflicting values for the same attribute in different xsl:decimal-format declarations having the same import precedence, unless there is another definition of the same attribute with higher import precedence.

The following attributes control the interpretation of characters in the picture string supplied to the format-number^FO function, and also specify characters that may appear in the result of formatting the number. In each case the value must be a single character [see ERR XTSE0020].

decimal-separator specifies the character used for the decimal-separator-sign; the default value is the period character (.)
grouping-separator specifies the character used for the grouping-sign, which is typically used as a thousands separator; the default value is the comma character (,)
percent specifies the character used for the percent-sign; the default value is the percent character (%)
per-mille specifies the character used for the per-mille-sign; the default value is the Unicode per-mille character (#x2030)
zero-digit specifies the character used for the digit-zero-sign; the default value is the digit zero (0). This character must be a digit (category Nd in the Unicode property database), and it must have the numeric value zero. This attribute implicitly defines the Unicode character that is used to represent each of the values 0 to 9 in the final result string: Unicode is organized so that each set of decimal digits forms a contiguous block of characters in numerical sequence.

[ERR XTSE1295] It is a static error if the character specified in the zero-digit attribute is not a digit or is a digit that does not have the numeric value zero.

The following attributes control the interpretation of characters in the picture string supplied to the format-number^FO function. In each case the value must be a single character [see ERR XTSE0020].

digit specifies the character used for the digit-sign in the picture string; the default value is the number sign character (#)
pattern-separator specifies the character used for the pattern-separator-sign, which separates positive and negative sub-pictures in a picture string; the default value is the semi-colon character (;)

The following attributes specify characters or strings that may appear in the result of formatting the number:

infinity specifies the string used for the infinity-symbol; the default value is the string Infinity
NaN specifies the string used for the NaN-symbol, which is used to represent the value NaN (not-a-number); the default value is the string NaN
minus-sign specifies the character used for the minus-symbol; the default value is the hyphen-minus character (-, #x2D). The value must be a single character.

[ERR XTSE1300] It is a static error if, for any named or unnamed decimal format, the variables representing characters used in a picture string do not each have distinct values. These variables are decimal-separator-sign, grouping-sign, percent-sign, per-mille-sign, digit-zero-sign, digit-sign, and pattern-separator-sign.

Every (named or unnamed) decimal format defined in the stylesheet is added to the statically known decimal formats^XP21 in the static context^XP21 of every expression in the stylesheet, excluding expressions appearing in [xsl:]use-when attributes.

19.4.1 Processing the Picture String

The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the variables decimal-separator-sign, grouping-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters (including the percent-sign and per-mille-sign) are classified as passive characters.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator-sign if there is one, or the entire sub-picture otherwise. The fractional part of the sub-picture is defined as the part that appears to the right of the decimal-separator-sign if there is one; it is a zero-length string otherwise.

[ERR XTDE1310] The picture string must conform to the following rules. It is a non-recoverable dynamic error if the picture string does not satisfy these rules.

Note that in these rules the words "preceded" and "followed" refer to characters anywhere in the string, they are not to be read as "immediately preceded" and "immediately followed".

A picture-string consists either of a sub-picture, or of two sub-pictures separated by a pattern-separator-sign. A picture-string must not contain more than one pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values.
A sub-picture must not contain more than one decimal-separator-sign.
A sub-picture must not contain more than one percent-sign or per-mille-sign, and it must not contain one of each.
A sub-picture must contain at least one digit-sign or zero-digit-sign.
A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.
A sub-picture must not contain a grouping-separator-sign adjacent to a decimal-separator-sign.
The integer part of a sub-picture must not contain a zero-digit-sign that is followed by a digit-sign. The fractional part of a sub-picture must not contain a digit-sign that is followed by a zero-digit-sign.

The evaluation of the format-number^FO function is described below in two phases, an analysis phase and a formatting phase. The analysis phase takes as its inputs the picture string and the variables derived from the relevant xsl:decimal-format declaration, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

Note:

Numbers will always be formatted with the most significant digit on the left.

19.4.2 Analyzing the Picture String

This phase of the algorithm analyzes the picture string and the attribute settings of the xsl:decimal-format declaration, and has the effect of setting the values of various variables, which are used in the subsequent formatting phase. These variables are listed below. Each is shown with its initial setting and its data type.

Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.

The variables are as follows:

The integer-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-separator-sign that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the integer part of the sub-picture and to the right of the grouping-separator-sign. In addition, if these integer-part-grouping-positions are at regular intervals (that is, if they form a sequence N, 2N, 3N, ... for some integer value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N as far as necessary to accommodate the largest possible number.
The minimum-integer-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator-sign. It is normally set to the number of zero-digit-sign characters found in the integer part of the sub-picture. But if the sub-picture contains no zero-digit-sign and no decimal-separator-sign, it is set to one.

Note:

There is no maximum integer part size. All significant digits in the integer part of the number will be displayed, even if this exceeds the number of digit-sign and zero-digit-sign characters in the subpicture.
The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-sign character and the prefix for the positive sub-picture (if any), in that order.
The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For each grouping-separator-sign that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator-sign.
The minimum-fractional-part-size is set to the number of zero-digit-sign characters found in the fractional part of the sub-picture.
The maximum-fractional-part-size is set to the total number of digit-sign and zero-digit-sign characters found in the fractional part of the sub-picture.
The suffix is set to contain all passive characters to the right of the rightmost active character in the fractional part of the sub-picture.

Note:

If there is only one sub-picture, then all variables for positive numbers and negative numbers will be the same, except for prefix: the prefix for negative numbers will be preceded by the minus-sign character.

19.4.3 Formatting the Number

This section describes the second phase of processing of the format-number^FO function. This phase takes as input a number to be formatted (referred to as the input number), and the variables set up by analyzing the xsl:decimal-format declaration and the picture string, as described above. The result of this phase is a string, which forms the return value of the format-number^FO function.

The algorithm for this second stage of processing is as follows:

If the input number is NaN (not a number), the result is the specified NaN-symbol (with no prefix or suffix).
In the rules below, the positive sub-picture and its associated variables are used if the input number is positive, and the negative sub-picture and its associated variables are used otherwise. Negative zero is taken as negative, positive zero as positive.
If the input number is positive or negative infinity, the result is the concatenation of the appropriate prefix, the infinity-symbol, and the appropriate suffix.
If the sub-picture contains a percent-sign, the number is multiplied by 100. If the sub-picture contains a per-mille-sign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.
The adjusted number is converted (if necessary) to an xs:decimal value, using an implementation of xs:decimal that imposes no limits on the totalDigits or fractionDigits facets. If there are several such values that are numerically equal to the adjusted number (bearing in mind that if the adjusted number is an xs:double or xs:float, the comparison will be done by converting the decimal value back to an xs:double or xs:float), the one that is chosen should be one with the smallest possible number of digits not counting leading or trailing zeroes (whether significant or insignificant). For example, 1.0 is preferred to 0.9999999999, and 100000000 is preferred to 100000001. This value is then rounded so that it uses no more than maximum-fractional-part-size digits in its fractional part. The rounded number is defined to be the result of converting the adjusted number to an xs:decimal value, as described above, and then calling the function round-half-to-even^FO with this converted number as the first argument and the maximum-fractional-part-size as the second argument, again with no limits on the totalDigits or fractionDigits in the result.
The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the characters implied by the choice of zero-digit-sign to represent the ten decimal digits, and the decimal-separator-sign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimal-separator-sign on its own.)
If the number of digits to the left of the decimal-separator-sign is less than minimum-integer-part-size, leading zero-digit-sign characters are added to pad out to that size.
If the number of digits to the right of the decimal-separator-sign is less than minimum-fractional-part-size, trailing zero-digit-sign characters are added to pad out to that size.
For each integer N in the integer-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.
For each integer N in the fractional-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.
If there is no decimal-separator-sign in the sub-picture, or if there are no digits to the right of the decimal-separator-sign character in the string, then the decimal-separator-sign character is removed from the string (it will be the rightmost character in the string).
The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.

19.5 Miscellaneous Additional Functions

19.5.1 current

current() as item()

The current function, used within an XPath expression, returns the item that was the context item at the point where the expression was invoked from the XSLT stylesheet. This is referred to as the current item. For an outermost expression (an expression not occurring within another expression), the current item is always the same as the context item. Thus,

<xsl:value-of select="current()"/>

means the same as

<xsl:value-of select="."/>

However, within square brackets, or on the right-hand side of the / operator, the current item is generally different from the context item.

Example: Using the current Function

For example,

<xsl:apply-templates select="//glossary/entry[@name=current()/@ref]"/>

will process all entry elements that have a glossary parent element and that have a name attribute with value equal to the value of the current item's ref attribute. This is different from

<xsl:apply-templates select="//glossary/entry[@name=./@ref]"/>

which means the same as

<xsl:apply-templates select="//glossary/entry[@name=@ref]"/>

and so would process all entry elements that have a glossary parent element and that have a name attribute and a ref attribute with the same value.

If the current function is used within a pattern, its value is the item that is being matched against the pattern.

[ERR XTDE1360] If the current function is evaluated within an expression that is evaluated when the context item is undefined, a non-recoverable dynamic error occurs.

19.5.2 unparsed-entity-uri

unparsed-entity-uri($entity-name as xs:string) as xs:anyURI

The unparsed-entity-uri function returns the URI of the unparsed entity whose name is given by the value of the $entity-name argument, in the document containing the context node. It returns the zero-length xs:anyURI if there is no such entity. This function maps to the dm:unparsed-entity-system-id accessor defined in [Data Model].

[ERR XTDE1370] It is a non-recoverable dynamic error if the unparsed-entity-uri function is called when there is no context node, or when the root of the tree containing the context node is not a document node.

19.5.3 unparsed-entity-public-id

unparsed-entity-public-id($entity-name as xs:string) as xs:string

The unparsed-entity-public-id function returns the public identifier of the unparsed entity whose name is given by the value of the $entity-name argument, in the document containing the context node. It returns the zero-length string if there is no such entity, or if the entity has no public identifier. This function maps to the dm:unparsed-entity-public-id accessor defined in [Data Model].

[ERR XTDE1380] It is a non-recoverable dynamic error if the unparsed-entity-public-id function is called when there is no context node, or when the root of the tree containing the context node is not a document node.

19.5.4 system-property

system-property($property-name as xs:string) as xs:string

The $property-name argument must evaluate to a lexical QName. The lexical QName is expanded as described in 5.1 Qualified Names.

[ERR XTDE1390] It is a non-recoverable dynamic error if the value is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

The system-property function returns a string representing the value of the system property identified by the name. If there is no such system property, the zero-length string is returned.

Implementations must provide the following system properties, which are all in the XSLT namespace:

xsl:version, a number giving the version of XSLT implemented by the processor; for implementations conforming to the version of XSLT specified by this document, this is the string "2.1". The value will always be a string in the lexical space of the decimal data type defined in XML Schema (see [XML Schema Part 2]). This allows the value to be converted to a number for the purpose of magnitude comparisons.
xsl:vendor, a string identifying the implementer of the processor
xsl:vendor-url, a string containing a URL identifying the implementer of the processor; typically this is the host page (home page) of the implementer's Web site.
xsl:product-name, a string containing the name of the implementation, as defined by the implementer. This should normally remain constant from one release of the product to the next. It should also be constant across platforms in cases where the same source code is used to produce compatible products for multiple execution platforms.
xsl:product-version, a string identifying the version of the implementation, as defined by the implementer. This should normally vary from one release of the product to the next, and at the discretion of the implementer it may also vary across different execution platforms.
xsl:is-schema-aware, returns the string "yes" in the case of a processor that claims conformance as a schema-aware XSLT processor, or "no" in the case of a basic XSLT processor.
xsl:supports-serialization, returns the string "yes" in the case of a processor that offers the serialization feature, or "no" otherwise.
xsl:supports-backwards-compatibility, returns the string "yes" in the case of a processor that offers the XSLT 1.0 compatibility feature, or "no" otherwise.
xsl:supports-1.0-compatibility, returns the string "yes" in the case of a processor that offers the XSLT 1.0 compatibility feature, or "no" otherwise.
xsl:supports-2.0-compatibility, returns the string "yes" in the case of a processor that offers the XSLT 2.0 compatibility feature, or "no" otherwise.
xsl:supports-namespace-axis, returns the string "yes" in the case of a processor that offers the XPath namespace axis even when not in backwards compatible mode, or "no" otherwise. Note that a processor that supports backwards compatible mode must support the namespace axis when in that mode, so this property is not relevant to that case.
xsl:supports-streaming, returns the string "yes" in the case of a processor that offers the streaming feature (see 24.5 Streaming Feature), or "no" otherwise.

Some of these properties relate to the conformance levels and features offered by the processor: these options are described in 24 Conformance.

The actual values returned for the above properties are implementation-defined.

The set of system properties that are supported, in addition to those listed above, is also implementation-defined. Implementations must not define additional system properties in the XSLT namespace.

Note:

An implementation must not return the value 2.1 as the value of the xsl:version system property unless it is conformant to XSLT 2.1.

It is recognized that vendors who are enhancing XSLT 1.0 or 2.0 processors may wish to release interim implementations before all the mandatory features of this specification are implemented. Since such products are not conformant to XSLT 2.1, this specification cannot define their behavior. However, implementers of such products are encouraged to return a value for the xsl:version system property that is intermediate between 1.0 and 2.1, and to provide the element-available and function-available functions to allow users to test which features have been fully implemented.

19.6 Formatting Dates and Times

Note:

These functions have been moved into XPath 2.1

Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar, language, and country. Each has two variants.

`format-dateTime`(	`$value`	`as` `xs:dateTime?`,
	`$picture`	`as` `xs:string`,
	`$language`	`as` `xs:string?`,
	`$calendar`	`as` `xs:string?`,
	`$country`	`as` `xs:string?`) `as` `xs:string?`

format-dateTime($value as xs:dateTime?, $picture as xs:string) as xs:string?

`format-date`(	`$value`	`as` `xs:date?`,
	`$picture`	`as` `xs:string`,
	`$language`	`as` `xs:string?`,
	`$calendar`	`as` `xs:string?`,
	`$country`	`as` `xs:string?`) `as` `xs:string?`

format-date($value as xs:date?, $picture as xs:string) as xs:string?

`format-time`(	`$value`	`as` `xs:time?`,
	`$picture`	`as` `xs:string`,
	`$language`	`as` `xs:string?`,
	`$calendar`	`as` `xs:string?`,
	`$country`	`as` `xs:string?`) `as` `xs:string?`

format-time($value as xs:time?, $picture as xs:string) as xs:string?

The format-dateTime, format-date, and format-time functions format $value as a string using the picture string specified by the $picture argument, the calendar specified by the $calendar argument, the language specified by the $language argument, and the country specified by the $country argument. The result of the function is the formatted string representation of the supplied dateTime, date, or time value.

[Definition: The three functions format-date, format-time, and format-dateTime are referred to collectively as the date formatting functions.]

If $value is the empty sequence, the empty sequence is returned.

Calling the two-argument form of each of the three functions is equivalent to calling the five-argument form with each of the last three arguments set to an empty sequence.

For details of the language, calendar, and country arguments, see 19.6.2 The Language, Calendar, and Country Arguments.

In general, the use of an invalid picture, language, calendar, or country argument is classified as a non-recoverable dynamic error. By contrast, use of an option in any of these arguments that is valid but not supported by the implementation is not an error, and in these cases the implementation is required to output the value in a fallback representation.

19.6.1 The Picture String

The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal substring, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.

A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a width modifier. Whitespace within a variable marker is ignored.

The component specifier indicates the component of the date or time that is required, and takes the following values:

Specifier	Meaning	Default Presentation Modifier
Y	year (absolute value)	1
M	month in year	1
D	day in month	1
d	day in year	1
F	day of week	n
W	week in year	1
w	week in month	1
H	hour in day (24 hours)	1
h	hour in half-day (12 hours)	1
P	am/pm marker	n
m	minute in hour	01
s	second in minute	01
f	fractional seconds	1
Z	timezone as a time offset from UTC, or if an alphabetic modifier is present the conventional name of a timezone (such as PST)	1
z	timezone as a time offset using GMT, for example GMT+1 or GMT-05:00. For this component there is a fixed prefix of `GMT`, or a localized variation thereof for the chosen language, and the presentation modifier controls the representation of the signed time offset that follows.	1
C	calendar: the name or abbreviation of a calendar name	n
E	era: the name of a baseline for the numbering of years, for example the reign of a monarch	n

[ERR XTDE1340] It is a non-recoverable dynamic error if the syntax of the picture is incorrect.

[ERR XTDE1350] It is a non-recoverable dynamic error if a component specifier within the picture refers to components that are not available in the given type of $value, for example if the picture supplied to the format-time refers to the year, month, or day component.

It is not an error to include a timezone component when the supplied value has no timezone. In these circumstances the timezone component will be ignored.

The first presentation modifier indicates the style in which the value of a component is to be represented. Its value may be either:

any format token permitted in the format string of the xsl:number instruction (see 12 Numbering), indicating that the value of the component is to be output numerically using the specified number format (for example, 1, 01, i, I, w, W, or Ww) or
the format token n, N, or Nn, indicating that the value of the component is to be output by name, in lower-case, upper-case, or title-case respectively. Components that can be output by name include (but are not limited to) months, days of the week, timezones, and eras. If the processor cannot output these components by name for the chosen calendar and language then it must use an implementation-defined fallback representation.

If the implementation does not support the use of the requested format token, it must use the default presentation modifier for that component.

If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:

Modifier	Meaning
t	traditional numbering. This has the same meaning as `letter-value="traditional"` in `xsl:number`.
o	ordinal form of a number, for example `8th` or `8º`. The actual representation of the ordinal form of a number may depend not only on the language, but also on the grammatical context (for example, in some languages it must agree in gender).

Note:

Although the formatting rules are expressed in terms of the rules for format tokens in xsl:number, the formats actually used may be specialized to the numbering of date components where appropriate. For example, in Italian, it is conventional to use an ordinal number (primo) for the first day of the month, and cardinal numbers (due, tre, quattro ...) for the remaining days. A processor may therefore use this convention to number days of the month, ignoring the presence or absence of the ordinal presentation modifier.

Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters or digits to be included in the representation of the value.

The width modifier, if present, is introduced by a comma. It takes the form:

, min-width ("-" max-width)?

where min-width is either an unsigned integer indicating the minimum number of characters to be output, or * indicating that there is no explicit minimum, and max-width is either an unsigned integer indicating the maximum number of characters to be output, or * indicating that there is no explicit maximum; if max-width is omitted then * is assumed. Both integers, if present, must be greater than zero.

A format token containing leading zeroes, such as 001, sets the minimum and maximum width to the number of digits appearing in the format token; if a width modifier is also present, then the width modifier takes precedence.

Note:

A format token consisting of a one-digit on its own, such as 1, does not constrain the number of digits in the output. In the case of fractional seconds in particular, [f001] requests three decimal digits, [f01] requests two digits, but [f1] will produce an implementation-defined number of digits. If exactly one digit is required, this can be achieved using the component specifier [f1,1-1].

If the minimum and maximum width are unspecified, then the output uses as many characters as are required to represent the value of the component without truncation and without padding: this is referred to below as the full representation of the value. For a timezone offset (component specifier z), the full representation consists of a sign for the offset, the number of hours of the offset, and if the offset is not an integral number of hours, a colon (:) followed by the two digits of the minutes of the offset..

If the full representation of the value exceeds the specified maximum width, then the processor should attempt to use an alternative shorter representation that fits within the maximum width. Where the presentation modifier is N, n, or Nn, this is done by abbreviating the name, using either conventional abbreviations if available, or crude right-truncation if not. For example, setting max-width to 4 indicates that four-letter abbreviations should be used, though it would be acceptable to use a three-letter abbreviation if this is in conventional use. (For example, "Tuesday" might be abbreviated to "Tues", and "Friday" to "Fri".) In the case of the year component, setting max-width requests omission of high-order digits from the year, for example, if max-width is set to 2 then the year 2003 will be output as 03. In the case of the fractional seconds component, the value is rounded to the specified size as if by applying the function round-half-to-even(fractional-seconds, max-width). If no mechanism is available for fitting the value within the specified maximum width (for example, when roman numerals are used), then the value should be output in its full representation.

If the full representation of the value is shorter than the specified minimum width, then the processor should pad the value to the specified width.

For decimal representations of numbers, this should be done by prepending zero digits from the appropriate set of digit characters, or appending zero digits in the case of the fractional seconds component.
For timezone offsets this should be done by first appending a colon (:) followed by two zero digits from the appropriate set of digit characters if the full representation does not already include a minutes component and if the specified minimum width permits adding three characters, and then if necessary prepending zero digits from the appropriate set of digit characters to the hour component.
In other cases, it should be done by appending spaces.

19.6.2 The Language, Calendar, and Country Arguments

The set of languages, calendars, and countries that are supported in the date formatting functions is implementation-defined. When any of these arguments is omitted or is an empty sequence, an implementation-defined default value is used.

If the fallback representation uses a different calendar from that requested, the output string must identify the calendar actually used, for example by prefixing the string with [Calendar: X] (where X is the calendar actually used), localized as appropriate to the requested language. If the fallback representation uses a different language from that requested, the output string must identify the language actually used, for example by prefixing the string with [Language: Y] (where Y is the language actually used) localized in an implementation-dependent way. If a particular component of the value cannot be output in the requested format, it should be output in the default format for that component.

The language argument specifies the language to be used for the result string of the function. The value of the argument must be either the empty sequence or a value that would be valid for the xml:lang attribute (see [XML]). Note that this permits the identification of sublanguages based on country codes (from [ISO 3166-1]) as well as identification of dialects and of regions within a country.

If the language argument is omitted or is set to an empty sequence, or if it is set to an invalid value or a value that the implementation does not recognize, then the processor uses an implementation-defined language.

The language is used to select the appropriate language-dependent forms of:

names (for example, of months)
numbers expressed as words or as ordinals (twenty, 20th, twentieth)
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year

Where appropriate this choice may also take into account the value of the country argument, though this should not be used to override the language or any sublanguage that is specified as part of the language argument.

The choice of the names and abbreviations used in any given language is implementation-defined. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices.

Where ordinal numbers are used, the selection of the correct representation of the ordinal (for example, the linguistic gender) may depend on the component being formatted and on its textual context in the picture string.

The calendar attribute specifies that the dateTime, date, or time supplied in the $value argument must be converted to a value in the specified calendar and then converted to a string using the conventions of that calendar.

A calendar value must be a valid QName. If the QName does not have a prefix, then it identifies a calendar with the designator specified below. If the QName has a prefix, then the QName is expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the calendar; the behavior in this case is implementation-defined.

If the calendar attribute is omitted an implementation-defined value is used.

Note:

The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past.

This specification does not define any of these calendars, nor the way that they map to the value space of the xs:date data type in [XML Schema Part 2]. There may be ambiguities when dates are recorded using different calendars. For example, the start of a new day is not simultaneous in different calendars, and may also vary geographically (for example, based on the time of sunrise or sunset). Translation of dates is therefore more reliable when the time of day is also known, and when the geographic location is known. When translating dates between one calendar and another, the processor may take account of the values of the country and/or language arguments, with the country argument taking precedence.

Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].

Designator	Calendar
AD	Anno Domini (Christian Era)
AH	Anno Hegirae (Muhammedan Era)
AME	Mauludi Era (solar years since Mohammed's birth)
AM	Anno Mundi (Jewish Calendar)
AP	Anno Persici
AS	Aji Saka Era (Java)
BE	Buddhist Era
CB	Cooch Behar Era
CE	Common Era
CL	Chinese Lunar Era
CS	Chula Sakarat Era
EE	Ethiopian Era
FE	Fasli Era
ISO	ISO 8601 calendar
JE	Japanese Calendar
KE	Khalsa Era (Sikh calendar)
KY	Kali Yuga
ME	Malabar Era
MS	Monarchic Solar Era
NS	Nepal Samwat Era
OS	Old Style (Julian Calendar)
RS	Rattanakosin (Bangkok) Era
SE	Saka Era
SH	Mohammedan Solar Era (Iran)
SS	Saka Samvat
TE	Tripurabda Era
VE	Vikrama Era
VS	Vikrama Samvat Era

At least one of the above calendars must be supported. It is implementation-defined which calendars are supported.

The ISO 8601 calendar ([ISO 8601]), which is included in the above list and designated ISO, is very similar to the Gregorian calendar designated AD, but it differs in several ways. The ISO calendar is intended to ensure that date and time formats can be read easily by other software, as well as being legible for human users. The ISO calendar prescribes the use of particular numbering conventions as defined in ISO 8601, rather than allowing these to be localized on a per-language basis. In particular it provides a numeric 'week date' format which identifies dates by year, week of the year, and day in the week; in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday of that year. The numeric values of the components year, month, day, hour, minute, and second are the same in the ISO calendar as the values used in the lexical representation of the date and time as defined in [XML Schema Part 2]. The era ("E" component) with this calendar is either a minus sign (for negative years) or a zero-length string (for positive years). For dates before 1 January, AD 1, year numbers in the ISO and AD calendars are off by one from each other: ISO year 0000 is 1 BC, -0001 is 2 BC, etc.

Note:

The value space of the date and time data types, as defined in XML Schema, is based on absolute points in time. The lexical space of these data types defines a representation of these absolute points in time using the proleptic Gregorian calendar, that is, the modern Western calendar extrapolated into the past and the future; but the value space is calendar-neutral. The date formatting functions produce a representation of this absolute point in time, but denoted in a possibly different calendar. So, for example, the date whose lexical representation in XML Schema is 1502-01-11 (the day on which Pope Gregory XIII was born) might be formatted using the Old Style (Julian) calendar as 1 January 1502. This reflects the fact that there was at that time a ten-day difference between the two calendars. It would be incorrect, and would produce incorrect results, to represent this date in an element or attribute of type xs:date as 1502-01-01, even though this might reflect the way the date was recorded in contemporary documents.

When referring to years occurring in antiquity, modern historians generally use a numbering system in which there is no year zero (the year before 1 CE is thus 1 BCE). This is the convention that should be used when the requested calendar is OS (Julian) or AD (Gregorian). When the requested calendar is ISO, however, the conventions of ISO 8601 should be followed: here the year before +0001 is numbered zero. In [XML Schema Part 2] (version 1.0), the value space for xs:date and xs:dateTime does not include a year zero: however, a future edition is expected to endorse the ISO 8601 convention. This means that the date on which Julius Caesar was assassinated has the ISO 8601 lexical representation -0043-03-13, but will be formatted as 15 March 44 BCE in the Julian calendar or 13 March 44 BCE in the Gregorian calendar (dependant on the chosen localization of the names of months and eras).

The intended use of the country argument is to identify the place where an event represented by the dateTime, date, or time supplied in the $value argument took place or will take place. If the value is supplied, and is not the empty sequence, then it should be a country code defined in [ISO 3166-1]. Implementations may also allow the use of codes representing subdivisions of a country from ISO 3166-2, or codes representing formerly used names of countries from ISO 3166-3. This argument is not intended to identify the location of the user for whom the date or time is being formatted; that should be done by means of the language attribute. This information may be used to provide additional information when converting dates between calendars or when deciding how individual components of the date and time are to be formatted. For example, different countries using the Old Style (Julian) calendar started the new year on different days, and some countries used variants of the calendar that were out of synchronization as a result of differences in calculating leap years. The geographical area identified by a country code is defined by the boundaries as they existed at the time of the date to be formatted, or the present-day boundaries for dates in the future.

19.6.3 Examples of Date and Time Formatting

Example: Gregorian Calendar

The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar as the default calendar.

Required Output	Expression
`2002-12-31`	`format-date($d, "[Y0001]-[M01]-[D01]")`
`12-31-2002`	`format-date($d, "[M]-[D]-[Y]")`
`31-12-2002`	`format-date($d, "[D]-[M]-[Y]")`
`31 XII 2002`	`format-date($d, "[D1] [MI] [Y]")`
`31st December, 2002`	`format-date($d, "[D1o] [MNn], [Y]", "en", (), ())`
`31 DEC 2002`	`format-date($d, "[D01] [MN,*-3] [Y0001]", "en", (), ())`
`December 31, 2002`	`format-date($d, "[MNn] [D], [Y]", "en", (), ())`
`31 Dezember, 2002`	`format-date($d, "[D] [MNn], [Y]", "de", (), ())`
`Tisdag 31 December 2002`	`format-date($d, "[FNn] [D] [MNn] [Y]", "sv", (), ())`
`[2002-12-31]`	`format-date($d, "[[[Y0001]-[M01]-[D01]]]")`
`Two Thousand and Three`	`format-date($d, "[YWw]", "en", (), ())`
`einunddreißigste Dezember`	`format-date($d, "[Dwo] [MNn]", "de", (), ())`
`3:58 PM`	`format-time($t, "[h]:[m01] [PN]", "en", (), ())`
`3:58:45 pm`	`format-time($t, "[h]:[m01]:[s01] [Pn]", "en", (), ())`
`3:58:45 PM PDT`	`format-time($t, "[h]:[m01]:[s01] [PN] [ZN,*-3]", "en", (), ())`
`3:58:45 o'clock PM PDT`	`format-time($t, "[h]:[m01]:[s01] o'clock [PN] [ZN,*-3]", "en", (), ())`
`15:58`	`format-time($t,"[H01]:[m01]")`
`15:58:45.762`	`format-time($t,"[H01]:[m01]:[s01].[f001]")`
`15:58:45 GMT+02:00`	`format-time($t,"[H01]:[m01]:[s01] [z,6-6]", "en", (), ())`
`15.58 Uhr GMT+2`	`format-time($t,"[H01]:[m01] Uhr [z]", "de", (), ())`
`3.58pm on Tuesday, 31st December`	`format-dateTime($dt, "[h].[m01][Pn] on [FNn], [D1o] [MNn]")`
`12/31/2002 at 15:58:45`	`format-dateTime($dt, "[M01]/[D01]/[Y0001] at [H01]:[m01]:[s01]")`

Example: Non-Gregorian Calendars

The following examples use calendars other than the Gregorian calendar.

These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.

Description	Request	Result
Islamic	`format-date($d, "[D١] [Mn] [Y١]", "ar", "AH", ())`	٢٦ ﺸﻭّﺍﻝ ١٤٢٣
Jewish (with Western numbering)	`format-date($d, "[D] [Mn] [Y]", "he", "AM", ())`	‏26 טבת 5763
Jewish (with traditional numbering)	`format-date($d, "[Dאt] [Mn] [Yאt]", "he", "AM", ())`	כ״ו טבת תשס״ג
Julian (Old Style)	`format-date($d, "[D] [MNn] [Y]", "en", "OS", ())`	18 December 2002
Thai	`format-date($d, "[D๑] [Mn] [Y๑]", "th", "BE", ())`	๓๑ ธันวาคม ๒๕๔๕

19.7 Function items and context-dependency

This section describes unfinished work.

The XPath 2.1 specification introduces the ability for functions to be manipulated as values. In the draft of XPath 2.1 that is current at the time of writing, there are no rules describing how context-dependent function items (such as position#0 or static-base-uri#0) are to be handled. The expected resolution is that (a) binding a function item to a function that depends on the static context (for example any function that depends on the default collation) will use the static context at the point where the function item is created, while (b) binding of function items to functions that depend on non-stable parts of the dynamic context (for example position#0 or name#0) will not be allowed.

Similar rules may need to be defined for XSLT-specific functions such as key or current-group that depend on the XSLT-specific parts of the static and dynamic context.

Issue 33 (context-dependent-functions):

The rules for binding of function items to context-dependent functions need to be defined.

20 Messages

 <xsl:message select? = expression terminate? = { "yes" | "no" } error-code? = { QName } >  </xsl:message>

The xsl:message instruction sends a message in an implementation-defined way. The xsl:message instruction causes the creation of a new document, which is typically serialized and output to an implementation-defined destination. The result of the xsl:message instruction is an empty sequence.

The content of the message may be specified by using either or both of the optional select attribute and the sequence constructor that forms the content of the xsl:message instruction.

If the xsl:message instruction contains a sequence constructor, then the sequence obtained by evaluating this sequence constructor is used to construct the content of the new document node, as described in 5.7.1 Constructing Complex Content.

If the xsl:message instruction has a select attribute, then the value of the attribute must be an XPath expression. The effect of the xsl:message instruction is then the same as if a single xsl:copy-of instruction with this select attribute were added to the start of the sequence constructor.

If the xsl:message instruction has no content and no select attribute, then an empty message is produced.

The tree produced by the xsl:message instruction is not technically a final result tree. The tree has no URI and processors are not required to make the tree accessible to applications.

Note:

In many cases, the XML document produced using xsl:message will consist of a document node owning a single text node. However, it may contain a more complex structure.

Note:

An implementation might implement xsl:message by popping up an alert box or by writing to a log file. Because the order of execution of instructions is implementation-defined, the order in which such messages appear is not predictable.

The terminate attribute is interpreted as an attribute value template.

If the effective value of the terminate attribute is yes, then the processor must signal a non-recoverable dynamic error after sending the message. This error may be caught in the same way as any other dynamic error using xsl:catch. The default value is no. Note that because the order of evaluation of instructions is implementation-dependent, this gives no guarantee that any particular instruction will or will not be evaluated before processing terminates.

The optional error-code attribute may be used to indicate the error code associated with the message. This may be used irrespective of the value of terminate. The error code is a QName, supplied as a lexical QName. If no error code is specified, or if the value is not a valid QName, the error code will have local part XTMM9000 and namespace URI http://www.w3.org/2005/xqt-errors. User-defined error codes should be in a namespace other than http://www.w3.org/2005/xqt-errors. When the value of terminate is yes, the error code may be matched in an xsl:catch element to catch the error and cause processing to continue normally.

[ERR XTMM9000] When a transformation is terminated by use of xsl:message terminate="yes", the effect is the same as when a non-recoverable dynamic error occurs during the transformation. The default error code is XTMM9000; this may be overridden using the error-code attribute of the xsl:message instruction.

Example: Localizing Messages

One convenient way to do localization is to put the localized information (message text, etc.) in an XML document, which becomes an additional input file to the stylesheet. For example, suppose messages for a language L are stored in an XML file resources/L.xml in the form:

<messages>
  <message name="problem">A problem was detected.</message>
  <message name="error">An error was detected.</message>
</messages>

Then a stylesheet could use the following approach to localize messages:

<xsl:param name="lang" select="'en'"/>
<xsl:variable name="messages"
  select="document(concat('resources/', $lang, '.xml'))/messages"/>

<xsl:template name="localized-message">
  <xsl:param name="name"/>
  <xsl:message select="string($messages/message[@name=$name])"/>
</xsl:template>

<xsl:template name="problem">
  <xsl:call-template name="localized-message">
    <xsl:with-param name="name">problem</xsl:with-param>
  </xsl:call-template>
</xsl:template>

Any dynamic error that occurs while evaluating the select expression or the contained sequence constructor, and any serialization error that occurs while processing the result, is treated as a recoverable error even if the error would not be recoverable under other circumstances. The optional recovery action is implementation-dependent.

Note:

An example of such an error is the serialization error that occurs when processing the instruction <xsl:message select="@code"/> (on the grounds that free-standing attributes cannot be serialized). Making such errors recoverable means that it is implementation-defined whether or not they are signaled to the user and whether they cause termination of the transformation. If the processor chooses to recover from the error, the content of any resulting message is implementation-dependent.

One possible recovery action is to include a description of the error in the generated message text.

21 Extensibility and Fallback

XSLT allows two kinds of extension, extension instructions and extension functions.

[Definition: An extension instruction is an element within a sequence constructor that is in a namespace (not the XSLT namespace) designated as an extension namespace.]

[Definition: An extension function is a function that is available for use within an XPath expression, other than a core function defined in [Functions and Operators], an additional function defined in this XSLT specification, a constructor function named after an atomic type, or a stylesheet function defined using an xsl:function declaration.].

This specification does not define any mechanism for creating or binding implementations of extension instructions or extension functions, and it is not required that implementations support any such mechanism. Such mechanisms, if they exist, are implementation-defined. Therefore, an XSLT stylesheet that must be portable between XSLT implementations cannot rely on particular extensions being available. XSLT provides mechanisms that allow an XSLT stylesheet to determine whether the implementation makes particular extensions available, and to specify what happens if those extensions are not available. If an XSLT stylesheet is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still retain portability.

21.1 Extension Functions

The set of functions that can be called from a FunctionCall^XP21 within an XPath expression may include one or more extension functions. The expanded-QName of an extension function always has a non-null namespace URI.

21.1.1 Testing Availability of Functions

The function-available function can be used with the [xsl:]use-when attribute (see 3.12 Conditional Element Inclusion) to explicitly control how a stylesheet behaves if a particular extension function is not available.

function-available($function-name as xs:string) as xs:boolean

`function-available`(	`$function-name`	`as` `xs:string`,
`function-available`(	`$arity`	`as` `xs:integer`) `as` `xs:boolean`

A function is said to be available within an XPath expression if it is present in the in-scope functions^XP21 for that expression (see 5.4.1 Initializing the Static Context). Functions in the static context are uniquely identified by the name of the function (a QName) in combination with its arity.

The value of the $function-name argument must be a string containing a lexical QName. The lexical QName is expanded into an expanded-QName using the namespace declarations in scope for the expression. If the lexical QName is unprefixed, then the standard function namespace is used in the expanded QName.

The two-argument version of the function-available function returns true if and only if there is an available function whose name matches the value of the $function-name argument and whose arity matches the value of the $arity argument.

The single-argument version of the function-available function returns true if and only if there is at least one available function (with some arity) whose name matches the value of the $function-name argument.

[ERR XTDE1400] It is a non-recoverable dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

When the containing expression is evaluated with XPath 1.0 compatibility mode set to true, the function-available function returns false in respect of a function name and arity for which no implementation is available (other than the fallback error function that raises a dynamic error whenever it is called). This means that it is possible (as in XSLT 1.0) to use logic such as the following to test whether a function is available before calling it:

Example: Calling an extension function with backwards compatibility enabled

<summary xsl:version="1.0">
  <xsl:choose>
    <xsl:when test="function-available('my:summary')">
      <xsl:value-of select="my:summary()"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:text>Summary not available</xsl:text>
    </xsl:otherwise>
  </xsl:choose>
</summary>

Note:

The fact that a function with a given name is available gives no guarantee that any particular call on the function will be successful. For example, it is not possible to determine the types of the arguments expected.

Note:

In XSLT 2.0 (without backwards compatibility enabled) a static error occurs when an XPath expression references a function that is not available. This is true even in a part of the stylesheet that uses forwards compatible behavior. Therefore, the conditional logic to test whether a function is available before calling it should normally be written in a use-when attribute (see 3.12 Conditional Element Inclusion).

Example: Stylesheet portable between XSLT 1.0, XSLT 2.0, and XSLT 2.1

A stylesheet that is designed to use XSLT 2.0 facilities when running under an XSLT 2.0 or XSLT 2.1 processor, but to fall back to XSLT 1.0 capabilities when not, might be written using the code:

<out xsl:version="2.0">
  <xsl:choose>
    <xsl:when test="function-available('matches')">
      <xsl:value-of select="matches($input, '[a-z]*')"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="string-length(
                          translate($in, 'abcdefghijklmnopqrstuvwxyz', '')) = 0"/>
    </xsl:otherwise>
  </xsl:choose>
</out>

Here an XSLT 2.0 or XSLT 2.1 processor will always take the xsl:when branch, while a 1.0 processor will follow the xsl:otherwise branch. The single-argument version of the function-available function is used here, because that is the only version available in XSLT 1.0. Under the rules of XSLT 1.0, the call on the matches function is not an error, because it is never evaluated.

Example: Stylesheet portable between XSLT 2.1 and a future version of XSLT

A stylesheet that is designed to use facilities in some future XSLT version when they are available, but to fall back to XSLT 2.0 or XSLT 2.1 capabilities when not, might be written using code such as the following. This hypothesizes the availability in some future version of a function pad which pads a string to a fixed length with spaces:

 <xsl:value-of select="pad($input, 10)" 
               use-when="function-available('pad', 2)"/>
 <xsl:value-of select="concat($input, string-join(
                          for $i in 1 to 10 - string-length($input) 
                                                  return ' ', ''))"
               use-when="not(function-available('pad', 2))"/>

In this case the two-argument version of function-available is used, because there is no requirement for this code to run under XSLT 1.0.

21.1.2 Calling Extension Functions

If the function name used in a FunctionCall^XP21 within an XPath expression identifies an extension function, then to evaluate the FunctionCall^XP21, the processor will first evaluate each of the arguments in the FunctionCall^XP21. If the processor has information about the data types expected by the extension function, then it may perform any necessary type conversions between the XPath data types and those defined by the implementation language. If multiple extension functions are available with the same name, the processor may decide which one to invoke based on the number of arguments, the types of the arguments, or any other criteria. The result returned by the implementation is returned as the result of the function call, again after any necessary conversions between the data types of the implementation language and those of XPath. The details of such type conversions are outside the scope of this specification.

[ERR XTDE1420] It is a non-recoverable dynamic error if the arguments supplied to a call on an extension function do not satisfy the rules defined for that particular extension function, or if the extension function reports an error, or if the result of the extension function cannot be converted to an XPath value.

Note:

Implementations may also provide mechanisms allowing extension functions to report recoverable dynamic errors, or to execute within an environment that treats some or all of the errors listed above as recoverable.

[ERR XTDE1425] When the containing element is processed with XSLT 1.0 behavior, it is a non-recoverable dynamic error to evaluate an extension function call if no implementation of the extension function is available.

Note:

When XSLT 1.0 behavior is not enabled, this is a static error [XPST0017].

Note:

There is no prohibition on calling extension functions that have side-effects (for example, an extension function that writes data to a file). However, the order of execution of XSLT instructions is not defined in this specification, so the effects of such functions are unpredictable.

Implementations are not required to perform full validation of values returned by extension functions. It is an error for an extension function to return a string containing characters that are not permitted in XML, but the consequences of this error are implementation-defined. The implementation may raise an error, may convert the string to a string containing valid characters only, or may treat the invalid characters as if they were permitted characters.

Note:

The ability to execute extension functions represents a potential security weakness, since untrusted stylesheets may invoke code that has privileged access to resources on the machine where the processor executes. Implementations may therefore provide mechanisms that restrict the use of extension functions by untrusted stylesheets.

All observations in this section regarding the errors that can occur when invoking extension functions apply equally when invoking extension instructions.

21.1.3 External Objects

An implementation may allow an extension function to return an object that does not have any natural representation in the XDM data model, whether as an atomic value, a node, or a function item. For example, an extension function sql:connect might return an object that represents a connection to a relational database; the resulting connection object might be passed as an argument to calls on other extension functions such as sql:insert and sql:select.

The way in which such objects are represented in the type system is implementation-defined. They might be represented by a completely new data type, or they might be mapped to existing data types such as integer, string, or anyURI.

21.1.4 Testing Availability of Types

The type-available function can be used to control how a stylesheet behaves if a particular schema type is not available in the static context.

type-available($type-name as xs:string) as xs:boolean

A schema type (that is, a simple type or a complex type) is said to be available within an XPath expression if it is a type definition that is present in the in-scope schema types^XP21 for that expression (see 5.4.1 Initializing the Static Context). This includes built-in types, types imported using xsl:import-schema, and extension types defined by the implementation.

The value of the $type-name argument must be a string containing a lexical QName. The lexical QName is expanded into an expanded-QName using the namespace declarations in scope for the expression. If the lexical QName is unprefixed, then the default namespace is used in the expanded QName.

The function returns true if and only if there is an available type whose name matches the value of the $type-name argument.

[ERR XTDE1428] It is a non-recoverable dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

Note:

The type-available function is of limited use within an [xsl:]use-when expression, because the static context for the expression does not include any user-defined types.

21.2 Extension Instructions

[Definition: The extension instruction mechanism allows namespaces to be designated as extension namespaces. When a namespace is designated as an extension namespace and an element with a name from that namespace occurs in a sequence constructor, then the element is treated as an instruction rather than as a literal result element.] The namespace determines the semantics of the instruction.

Note:

Since an element that is a child of an xsl:stylesheet element is not occurring in a sequence constructor , user-defined data elements (see 3.6.3 User-defined Data Elements) are not extension elements as defined here, and nothing in this section applies to them.

21.2.1 Designating an Extension Namespace

A namespace is designated as an extension namespace by using an [xsl:]extension-element-prefixes attribute on an element in the stylesheet (see 3.5 Standard Attributes). The attribute must be in the XSLT namespace only if its parent element is not in the XSLT namespace. The value of the attribute is a whitespace-separated list of namespace prefixes. The namespace bound to each of the prefixes is designated as an extension namespace.

The default namespace (as declared by xmlns) may be designated as an extension namespace by including #default in the list of namespace prefixes.

[ERR XTSE1430] It is a static error if there is no namespace bound to the prefix on the element bearing the [xsl:]extension-element-prefixes attribute or, when #default is specified, if there is no default namespace.

The designation of a namespace as an extension namespace is effective for the element bearing the [xsl:]extension-element-prefixes attribute and for all descendants of that element within the same stylesheet module.

21.2.2 Testing Availability of Instructions

The element-available function can be used with the xsl:choose and xsl:if instructions, or with the [xsl:]use-when attribute (see 3.12 Conditional Element Inclusion) to explicitly control how a stylesheet behaves when a particular XSLT instruction or extension instruction is (or is not) available.

element-available($element-name as xs:string) as xs:boolean

The value of the $element-name argument must be a string containing a QName. The QName is expanded into an expanded-QName using the namespace declarations in scope for the expression. If there is a default namespace in scope, then it is used to expand an unprefixed QName. The element-available function returns true if and only if the expanded-QName is the name of an instruction. If the expanded-QName has a namespace URI equal to the XSLT namespace URI, then it refers to an element defined by XSLT. Otherwise, it refers to an extension instruction. If the expanded-QName has a null namespace URI, the element-available function will return false.

[ERR XTDE1440] It is a non-recoverable dynamic error if the argument does not evaluate to a string that is a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

If the expanded-QName is in the XSLT namespace, the function returns true if and only if the expanded QName is the name of an XSLT instruction, that is, an XSLT element whose syntax summary in this specification classifies it as an instruction.

Note:

Although the result of applying this function to a name in the XSLT namespace when using a conformant XSLT 2.1 processor is entirely predictable, the function is useful in cases where the stylesheet might be executing under a processor that implements some other version of XSLT with different rules.

If the expanded-QName is not in the XSLT namespace, the function returns true if and only if the processor has an implementation available of an extension instruction with the given expanded QName. This applies whether or not the namespace has been designated as an extension namespace.

If the processor does not have an implementation of a particular extension instruction available, and such an extension instruction is evaluated, then the processor must perform fallback for the element as specified in 21.2.3 Fallback. An implementation must not signal an error merely because the stylesheet contains an extension instruction for which no implementation is available.

21.2.3 Fallback

 <xsl:fallback>  </xsl:fallback>

The content of an xsl:fallback element is a sequence constructor, and when performing fallback, the value returned by the xsl:fallback element is the result of evaluating this sequence constructor.

When not performing fallback, evaluating an xsl:fallback element returns an empty sequence: the content of the xsl:fallback element is ignored.

There are two situations where a processor performs fallback: when an extension instruction that is not available is evaluated, and when an instruction in the XSLT namespace, that is not defined in XSLT 2.1, is evaluated within a region of the stylesheet for which forwards compatible behavior is enabled.

Note:

Fallback processing is not invoked in other situations, for example it is not invoked when an XPath expression uses unrecognized syntax or contains a call to an unknown function. To handle such situations dynamically, the stylesheet should call functions such as system-property and function-available to decide what capabilities are available.

[ERR XTDE1450] When a processor performs fallback for an extension instruction that is not recognized, if the instruction element has one or more xsl:fallback children, then the content of each of the xsl:fallback children must be evaluated; it is a non-recoverable dynamic error if it has no xsl:fallback children.

Note:

This is different from the situation with unrecognized XSLT elements. As explained in 3.9 Forwards Compatible Processing, an unrecognized XSLT element appearing within a sequence constructor is a static error unless (a) forwards compatible behavior is enabled, and (b) the instruction has an xsl:fallback child.

22 Final Result Trees

The output of a transformation is a set of one or more final result trees.

A final result tree can be created explicitly, by evaluating an xsl:result-document instruction. As explained in 2.4 Executing a Transformation, a final result tree is also created implicitly if no xsl:result-document instruction is evaluated, or if the result of evaluating the initial template is a non-empty sequence.

The way in which a final result tree is delivered to an application is implementation-defined.

Serialization of final result trees is described further in 23 Serialization

22.1 Creating Final Result Trees

<xsl:result-document format? = { qname } href? = { uri-reference } validation? = "strict" | "lax" | "preserve" | "strip" type? = qname method? = { "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname } byte-order-mark? = { "yes" | "no" } cdata-section-elements? = { qnames } doctype-public? = { string } doctype-system? = { string } encoding? = { string } escape-uri-attributes? = { "yes" | "no" } include-content-type? = { "yes" | "no" } indent? = { "yes" | "no" } media-type? = { string } normalization-form? = { "NFC" | "NFD" | "NFKC" | "NFKD" | "fully-normalized" | "none" | nmtoken } omit-xml-declaration? = { "yes" | "no" } standalone? = { "yes" | "no" | "omit" } suppress-indentation? = { qnames } undeclare-prefixes? = { "yes" | "no" } use-character-maps? = qnames output-version? = { nmtoken } >  </xsl:result-document>

The xsl:result-document instruction is used to create a final result tree. The content of the xsl:result-document element is a sequence constructor for the children of the document node of the tree. 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.7.1 Constructing Complex Content. The tree rooted at this document node forms the final result tree.

The xsl:result-document instruction defines the URI of the result tree, and may optionally specify the output format to be used for serializing this tree.

The effective value of the format attribute, if specified, must be a lexical QName. The QName is expanded using the namespace declarations in scope for the xsl:result-document element. The expanded-QName must match the expanded QName of a named output definition in the stylesheet. This identifies the xsl:output declaration that will control the serialization of the final result tree (see 23 Serialization), if the result tree is serialized. If the format attribute is omitted, the unnamed output definition is used to control serialization of the result tree.

[ERR XTDE1460] It is a non-recoverable dynamic error if the effective value of the format attribute is not a valid lexical QName, or if it does not match the expanded-QName of an output definition in the stylesheet. If the processor is able to detect the error statically (for example, when the format attribute contains no curly brackets), then the processor may optionally signal this as a static error.

Note:

The only way to select the unnamed output definition is to omit the format attribute.

The attributes method, byte-order-mark cdata-section-elements, doctype-public, doctype-system, encoding, escape-uri-attributes, indent, media-type, normalization-form, omit-xml-declaration, standalone, suppress-indentation, undeclare-prefixes, use-character-maps, and output-version may be used to override attributes defined in the selected output definition.

With the exception of use-character-maps, these attributes are all defined as attribute value templates, so their values may be set dynamically. For any of these attributes that is present on the xsl:result-document instruction, the effective value of the attribute overrides or supplements the corresponding value from the output definition. This works in the same way as when one xsl:output declaration overrides another:

In the case of cdata-section-elements and suppress-indentation, the value of the serialization parameter is the union of the expanded names of the elements named in this instruction and the elements named in the selected output definition;
In the case of use-character-maps, the character maps referenced in this instruction supplement and take precedence over those defined in the selected output definition;
In all other cases, the effective value of an attribute actually present on this instruction takes precedence over the value defined in the selected output definition.

Note:

In the case of the attributes method, cdata-section-elements, suppress-indentation, and use-character-maps, the effective value of the attribute contains one or more lexical QNames. The prefix in such a QName is expanded using the in-scope namespaces for the xsl:result-document element. In the case of cdata-section-elements and suppress-indentation, an unprefixed element name is expanded using the default namespace.

The output-version attribute on the xsl:result-document instruction overrides the version attribute on xsl:output (it has been renamed because version is available with a different meaning as a standard attribute: see 3.5 Standard Attributes). In all other cases, attributes correspond if they have the same name.

There are some serialization parameters that apply to some output methods but not to others. For example, the indent attribute has no effect on the text output method. If a value is supplied for an attribute that is inapplicable to the output method, its value is not passed to the serializer. The processor may validate the value of such an attribute, but is not required to do so.

The href attribute is optional. The default value is the zero-length string. The effective value of the attribute must be a URI Reference, which may be absolute or relative. There may be implementation-defined restrictions on the form of absolute URI that may be used, but the implementation is not required to enforce any restrictions. Any legal relative URI reference must be accepted. Note that the zero-length string is a legal relative URI reference.

The base URI of the document node at the root of the final result tree is based on the effective value of the href attribute. If the effective value is a relative URI reference, then it is resolved relative to the base output URI. If the implementation provides an API to access final result trees, then it must allow a final result tree to be identified by means of this base URI.

Note:

The base URI of the final result tree is not necessarily the same thing as the URI of its serialized representation on disk, if any. For example, a server (or browser client) might store final result trees only in memory, or in an internal disk cache. As long as the processor satisfies requests for those URIs, it is irrelevant where they are actually written on disk, if at all.

Note:

It will often be the case that one final result tree contains links to another final result tree produced during the same transformation, in the form of a relative URI reference. The mechanism of associating a URI with a final result tree has been chosen to allow the integrity of such links to be preserved when the trees are serialized.

As well as being potentially significant in any API that provides access to final result trees, the base URI of the new document node is relevant if the final result tree, rather than being serialized, is supplied as input to a further transformation.

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

A processor may allow a final result tree to be serialized. Serialization is described in 23 Serialization. However, an implementation (for example, a processor running in an environment with no access to writable filestore) is not required to support the serialization of final result trees. An implementation that does not support the serialization of final result trees may ignore the format attribute and the serialization attributes. Such an implementation must provide the application with some means of access to the (un-serialized) result tree, using its URI to identify it.

Implementations may provide additional mechanisms, outside the scope of this specification, for defining the way in which final result trees are processed. Such mechanisms may make use of the XSLT-defined attributes on the xsl:result-document and/or xsl:output elements, or they may use additional elements or attributes in an implementation-defined namespace.

Example: Multiple Result Documents

The following example takes an XHTML document as input, and breaks it up so that the text following each <h1> element is included in a separate document. A new document toc.html is constructed to act as an index:

<xsl:stylesheet
        version="2.1"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
        
<xsl:output name="toc-format" method="xhtml" indent="yes"
     doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
     doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"/>
            
<xsl:output name="section-format" method="xhtml" indent="no"
     doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
     doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/>       
         
<xsl:template match="/">
  <xsl:result-document href="toc.html" 
                       format="toc-format" 
                       validation="strict">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head><title>Table of Contents</title></head>
      <body>
        <h1>Table of Contents</h1>
        <xsl:for-each select="/*/xhtml:body/(*[1] | xhtml:h1)">
          <p>
            <a href="section{position()}.html">
              <xsl:value-of select="."/>
            </a>
          </p>
        </xsl:for-each>
      </body>
    </html>
  </xsl:result-document>
  <xsl:for-each-group select="/*/xhtml:body/*" group-starting-with="xhtml:h1">
    <xsl:result-document href="section{position()}.html" 
                         format="section-format" validation="strip">         
      <html xmlns="http://www.w3.org/1999/xhtml">
        <head><title><xsl:value-of select="."/></title></head>
        <body>
          <xsl:copy-of select="current-group()"/>
        </body>
      </html>
    </xsl:result-document>
  </xsl:for-each-group>
</xsl:template>

</xsl:stylesheet>

There are restrictions on the use of the xsl:result-document instruction, designed to ensure that the results are fully interoperable even when processors optimize the sequence in which instructions are evaluated. Informally, the restriction is that the xsl:result-document instruction can only be used while writing a final result tree, not while writing to a temporary tree or a sequence. This restriction is defined formally as follows.

[Definition: Each instruction in the stylesheet is evaluated in one of two possible output states: final output state or temporary output state ].

[Definition: The first of the two output states is called final output state. This state applies when instructions are writing to a final result tree.]

[Definition: The second of the two output states is called temporary output state. This state applies when instructions are writing to a temporary tree or any other non-final destination.]

The instructions in the initial template are evaluated in final output state. An instruction is evaluated in the same output state as its calling instruction, except that xsl:variable, xsl:param, xsl:with-param, xsl:attribute, xsl:comment, xsl:processing-instruction, xsl:namespace, xsl:value-of, xsl:function, xsl:key, xsl:sort, and xsl:message always evaluate the instructions in their contained sequence constructor in temporary output state.

[ERR XTDE1480] It is a non-recoverable dynamic error to evaluate the xsl:result-document instruction in temporary output state.

[ERR XTDE1490] It is a non-recoverable dynamic error for a transformation to generate two or more final result trees with the same URI.

Note:

Note, this means that it is an error to evaluate more than one xsl:result-document instruction that omits the href attribute, or to evaluate any xsl:result-document instruction that omits the href attribute if an initial final result tree is created implicitly.

Technically, the result of evaluating the xsl:result-document instruction is an empty sequence. This means it does not contribute any nodes to the result of the sequence constructor it is part of.

[ERR XTRE1495] It is a recoverable dynamic error for a transformation to generate two or more final result trees with URIs that identify the same physical resource. The optional recovery action is implementation-dependent, since it may be impossible for the processor to detect the error.

[ERR XTRE1500] It is a recoverable dynamic error for a stylesheet to write to an external resource and read from the same resource during a single transformation, whether or not the same URI is used to access the resource in both cases. The optional recovery action is implementation-dependent: implementations are not required to detect the error condition. Note that if the error is not detected, it is undefined whether the document that is read from the resource reflects its state before or after the result tree is written.

22.2 Validation

It is possible to control the type annotation applied to 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, xsl:copy-of, xsl:document, and xsl:result-document instructions, or the xsl:type and xsl:validation attributes of a literal result element.

The [xsl:]type attribute is used to request validation of an element or attribute against a specific simple or complex type defined in a schema. The [xsl:]validation attribute is used to request validation against the global element or attribute declaration whose name matches the name of the element or attribute being validated.

The [xsl:]type and [xsl:]validation attributes are mutually exclusive. Both are optional, but if one is present then the other must be omitted. If both attributes are omitted, the effect is the same as specifying the validation attribute with the value specified in the default-validation attribute of the containing xsl:stylesheet element; if this is not specified, the effect is the same as specifying validation="strip".

[ERR XTSE1505] It is a static error if both the [xsl:]type and [xsl:]validation attributes are present on the xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, xsl:document, or xsl:result-document instructions, or on a literal result element.

The detailed rules for validation vary depending on the kind of node being validated. The rules for element and attribute nodes are given in 22.2.1 Validating Constructed Elements and Attributes, while those for document nodes are given in 22.2.2 Validating Document Nodes.

22.2.1 Validating Constructed Elements and Attributes

22.2.1.1 Validation using the `[xsl:]validation` Attribute

The [xsl:]validation attribute defines the validation action to be taken. It determines not only the type annotation of the node that is constructed by the relevant instruction itself, but also the type annotations of all element and attribute nodes that have the constructed node as an ancestor. Conceptually, the validation requested for a child element or attribute node is applied before the validation requested for its parent element. For example, if the instruction that constructs a child element specifies validation="strict", this will cause the child element to be checked against an element declaration, but if the instruction that constructs its parent element specifies validation="strip", then the final effect will be that the child node is annotated as xs:untyped.

In the paragraphs below, the term contained nodes means the elements and attributes that have the newly constructed node as an ancestor.

The value strip indicates that the new node and each of the contained nodes will have the type annotation xs:untyped if it is an element, or xs:untypedAtomic if it is an attribute. Any previous type annotation present on a contained element or attribute node (for example, a type annotation that is present on an element copied from a source document) is also replaced by xs:untyped or xs:untypedAtomic as appropriate. The typed value of the node is changed to be the same as its string value, as an instance of xs:untypedAtomic. In the case of elements the nilled property is set to false. The values of the is-id and is-idrefs properties are unchanged. Schema validation is not invoked.
The value preserve indicates that nodes that are copied will retain their type annotations, but nodes whose content is newly constructed will be annotated as xs:anyType in the case of elements, or xs:untypedAtomic in the case of attributes. Schema validation is not invoked. The detailed effect depends on the instruction:
- In the case of xsl:element and literal result elements, the new element has a type annotation of xs:anyType, and the type annotations of contained nodes are retained unchanged.
- In the case of xsl:attribute, the effect is exactly the same as specifying validation="strip": that is, the new attribute will have the type annotation xs:untypedAtomic.
- In the case of xsl:copy-of, all the nodes that are copied will retain their type annotations unchanged.
- In the case of xsl:copy, the effect depends on the kind of node being copied.
  1. Where the node being copied is an attribute, the copied attribute will retain its type annotation.
  2. Where the node being copied is an element, the copied element will have a type annotation of xs:anyType (because this instruction does not copy the content of the element, it would be wrong to assume that the type is unchanged); but any contained nodes will have their type annotations retained in the same way as with xsl:element.
The value strict indicates that type annotations are established by performing strict schema validity assessment on the element or attribute node created by this instruction as follows:
- In the case of an element, a top-level element declaration is identified whose local name and namespace (if any) match the name of the element, and schema-validity assessment is carried out according to the rules defined in [XML Schema Part 1] (section 3.3.4 "Element Declaration Validation Rules", validation rule "Schema-Validity Assessment (Element)", clauses 1.1 and 2, using the top-level element declaration as the "declaration stipulated by the processor", which is mentioned in clause 1.1.1.1). The element is considered valid if the result of the schema validity assessment is a PSVI in which the relevant element node has a validity property whose value is valid. If there is no matching element declaration, or if the element is not considered valid, the transformation fails [see ERR XTTE1510], [see ERR XTTE1512]. In effect this means that the element being validated must be declared using a top-level declaration in the schema, and must conform to its declaration. The process of validation applies recursively to contained elements and attributes to the extent required by the schema definition.
  
  Note:
  
  It is not an error if the identified type definition is a simple type, although [XML Schema Part 1] does not define explicitly that this case is permitted.
- In the case of an attribute, a top-level attribute declaration is identified whose local name and namespace (if any) match the name of the attribute, and schema-validity assessment is carried out according to the rules defined in [XML Schema Part 1] (section 3.2.4 "Attribute Declaration Validation Rules", validation rule "Schema-Validity Assessment (Attribute)"). The attribute is considered valid if the result of the schema validity assessment is a PSVI in which the relevant attribute node has a validity property whose value is valid. If the attribute is not considered valid, the transformation fails [see ERR XTTE1510]. In effect this means that the attribute being validated must be declared using a top-level declaration in the schema, and must conform to its declaration.
- The schema components used to validate an element or attribute may be located in any way described by [XML Schema Part 1] (see section 4.3.2, How schema documents are located on the Web). The components in the schema constructed from the synthetic schema document (see 3.14 Importing Schema Components) will always be available for validating constructed nodes; if additional schema components are needed, they may be located in other ways, for example implicitly from knowledge of the namespace in which the elements and attributes appear, or using the xsi:schemaLocation attribute of elements within the tree being validated.
- If no validation is performed for a node, which can happen when the schema specifies lax or skip validation for that node or for a subtree, then the node is annotated as xs:anyType in the case of an element, and xs:untypedAtomic in the case of an attribute.
The value lax has the same effect as the value strict, except that whereas strict validation fails if there is no matching top-level element declaration or if the outcome of validity assessment is a validity property of invalid or notKnown, lax validation fails only if the outcome of validity assessment is a validity property of invalid. That is, lax validation does not cause a type error when the outcome is notKnown.

In practice this means that the element or attribute being validated must conform to its declaration if a top-level declaration is available. If no such declaration is available, then the element or attribute is not validated, but its attributes and children are validated, again with lax validation. Any nodes whose validation outcome is a validity property of notKnown are annotated as xs:anyType in the case of an element, and xs:untypedAtomic in the case of an attribute.

Note:

When the parent element lacks a declaration, the XML Schema specification defines the recursive checking of children and attributes as optional. For this specification, this recursive checking is required.

Note:

If an element that is being validated has an xsi:type attribute, then the value of the xsi:type attribute will be taken into account when performing the validation. However, the presence of an xsi:type attribute will not of itself cause an element to be validated: if validation against a named type is required, as distinct from validation against a top-level element declaration, then it must be requested using the XSLT [xsl:]type attribute on the instruction that invokes the validation, as described in section 22.2.1.2 Validation using the [xsl:]type Attribute

[ERR XTTE1510] If the validation attribute of an xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, or xsl:result-document instruction, or the xsl:validation attribute of a literal result element, has the effective value strict, and schema validity assessment concludes that the validity of the element or attribute is invalid or unknown, a type error occurs. As with other type errors, the error may be signaled statically if it can be detected statically.

[ERR XTTE1512] If the validation attribute of an xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, or xsl:result-document instruction, or the xsl:validation attribute of a literal result element, has the effective value strict, and there is no matching top-level declaration in the schema, then a type error occurs. As with other type errors, the error may be signaled statically if it can be detected statically.

[ERR XTTE1515] If the validation attribute of an xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, or xsl:result-document instruction, or the xsl:validation attribute of a literal result element, has the effective value lax, and schema validity assessment concludes that the element or attribute is invalid, a type error occurs. As with other type errors, the error may be signaled statically if it can be detected statically.

Note:

No mechanism is provided to validate an element or attribute against a local declaration in a schema. Such validation can usually be achieved by applying validation to a containing element for which a top-level element declaration exists.

22.2.1.2 Validation using the `[xsl:]type` Attribute

The [xsl:]type attribute takes as its value a QName. This must be the name of a type definition included in the in-scope schema components for the stylesheet. If the QName has no prefix, it is expanded using the default namespace established using the effective [xsl:]xpath-default-namespace attribute if there is one; otherwise, it is taken as being a name in no namespace.

If the [xsl:]type attribute is present, then the newly constructed element or attribute is validated against the type definition identified by this attribute.

In the case of an element, schema-validity assessment is carried out according to the rules defined in [XML Schema Part 1] (section 3.3.4 "Element Declaration Validation Rules", validation rule "Schema-Validity Assessment (Element)", clauses 1.2 and 2), using this type definition as the "processor-stipulated type definition". The element is considered valid if the result of the schema validity assessment is a PSVI in which the relevant element node has a validity property whose value is valid.
In the case of an attribute, the attribute is considered valid if (in the terminology of XML Schema) the attribute's normalized value is locally valid with respect to that type definition according to the rules for "String Valid" ([XML Schema Part 1], section 3.14.4). (Normalization here refers to the process of normalizing whitespace according to the rules of the whiteSpace facet for the data type).
If the element or attribute is not considered valid, as defined above, the transformation fails [see ERR XTTE1540].

[ERR XTSE1520] It is a static error if the value of the type attribute of an xsl:element, xsl:attribute, xsl:copy, xsl:copy-of, xsl:document, or xsl:result-document instruction, or the xsl:type attribute of a literal result element, is not a valid QName, or if it uses a prefix that is not defined in an in-scope namespace declaration, or if the QName is not the name of a type definition included in the in-scope schema components for the stylesheet.

[ERR XTSE1530] It is a static error if the value of the type attribute of an xsl:attribute instruction refers to a complex type definition.

[ERR XTTE1540] It is a type error if an [xsl:]type attribute is defined for a constructed element or attribute, and the outcome of schema validity assessment against that type is that the validity property of that element or attribute information item is other than valid.

Note:

Like other type errors, this error may be signaled statically if it can be detected statically. For example, the instruction <xsl:attribute name="dob" type="xs:date">1999-02-29</xsl:attribute> may result in a static error being signaled. If the error is not signaled statically, it will be signaled when the instruction is evaluated.

22.2.1.3 The Validation Process

As well as checking for validity against the schema, the validity assessment process causes type annotations to be associated with element and attribute nodes. If default values for elements or attributes are defined in the schema, the validation process will where necessary create new nodes containing these default values.

Validation of an element or attribute node only takes into account constraints on the content of the element or attribute. Validation rules affecting the document as a whole are not applied. Specifically, this means:

The validation rule "Validation Root Valid (ID/IDREF)" is not applied. This means that validation will not fail if there are non-unique ID values or dangling IDREF values in the subtree being validated.
The validation rule "Validation Rule: Identity-constraint Satisfied" should be applied.
There is no check that the document contains unparsed entities whose names match the values of nodes of type xs:ENTITY or xs:ENTITIES. (XSLT 2.1 provides no facility to construct unparsed entities within a tree.)
There is no check that the document contains notations whose names match the values of nodes of type xs:NOTATION. (The XDM data model makes no provision for notations to be represented in the tree.)

With these caveats, validating a newly constructed element, using strict or lax validation, is equivalent to the following steps:

The element is serialized to textual XML form, according to the rules defined in [XSLT and XQuery Serialization] using the XML output method, with all parameters defaulted. Note that this process discards any existing type annotations.
The resulting XML document is parsed to create an XML Information Set (see [XML Information Set].)
The Information Set produced in the previous step is validated according to the rules in [XML Schema Part 1]. The result of this step is a Post-Schema Validation Infoset (PSVI). If the validation process is not successful (as defined above), a type error is raised.
The PSVI produced in the previous step is converted back into the XDM data model by the mapping described in [Data Model] (Section 3.3.1 Mapping PSVI Additions to Node Properties^DM11). This process creates nodes with simple or complex type annotations based on the types established during schema validation.

Validating an attribute using strict or lax validation requires a modified version of this procedure. A copy of the attribute is first added to an element node that is created for the purpose, and namespace fixup (see 5.7.3 Namespace Fixup) is performed on this element node. The name of this element is of no consequence, but it must be the same as the name of a synthesized element declaration of the form:

<xs:element name="E">
  <xs:complexType>
    <xs:sequence/>
    <xs:attribute ref="A"/>
  </xs:complexType>
</xs:element>

where A is the name of the attribute being validated.

This synthetic element is then validated using the procedure given above for validating elements, and if it is found to be valid, a copy of the validated attribute is made, retaining its type annotation, but detaching it from the containing element (and thus, from any namespace nodes).

The XDM data model does not permit an attribute node with no parent to have a typed value that includes a namespace-qualified name, that is, a value whose type is derived from xs:QName or xs:NOTATION. This restriction is imposed because these types rely on the namespace nodes of a containing element to resolve namespace prefixes. Therefore, it is an error to validate a parentless attribute against such a type. This affects the instructions xsl:attribute, xsl:copy, and xsl:copy-of.

[ERR XTTE1545] A type error occurs if a type or validation attribute is defined (explicitly or implicitly) for an instruction that constructs a new attribute node, if the effect of this is to cause the attribute value to be validated against a type that is derived from, or constructed by list or union from, the primitive types xs:QName or xs:NOTATION.

22.2.2 Validating Document Nodes

It is possible to apply validation to a document node. This happens when a new document node is constructed by one of the instructions xsl:document, xsl:result-document, xsl:copy, or xsl:copy-of, and this instruction has a type attribute, or a validation attribute with the value strict or lax.

Document-level validation is not applied to the document node that is created implicitly when a variable-binding element has no select attribute and no as attribute (see 9.4 Creating implicit document nodes). This is equivalent to using validation="preserve" on xsl:document: nodes within such trees retain their type annotation. Similarly, validation is not applied to document nodes created using xsl:message.

The values validation="preserve" and validation="strip" do not request validation. In the first case, all element and attribute nodes within the tree rooted at the new document node retain their type annotations. In the second case, elements within the tree have their type annotation set to xs:untyped, while attributes have their type annotation set to xs:untypedAtomic.

When validation is requested for a document node (that is, when validation is set to strict or lax, or when a type attribute is present), the following processing takes place:

[ERR XTTE1550] A type error occurs unless the children of the document node comprise exactly one element node, no text nodes, and zero or more comment and processing instruction nodes, in any order.
The single element node child is validated, using the supplied values of the validation and type attributes, as described in 22.2.1 Validating Constructed Elements and Attributes.

Note:

The type attribute on xsl:document and xsl:result-document, and on xsl:copy and xsl:copy-of when copying a document node, thus refers to the required type of the element node that is the only element child of the document node. It does not refer to the type of the document node itself.
The validation rule "Validation Root Valid (ID/IDREF)" is applied to the single element node child of the document node. This means that validation will fail if there are non-unique ID values or dangling IDREF values in the document tree.
Identity constraints, as defined in section 3.11 of [XML Schema Part 1], are checked. (This refers to constraints defined using xs:unique, xs:key, and xs:keyref.)
There is no check that the tree contains unparsed entities whose names match the values of nodes of type xs:ENTITY or xs:ENTITIES. This is because there is no facility in XSLT 2.1 to create unparsed entities in a result tree. It is possible to add unparsed entity declarations to the result document by referencing a suitable DOCTYPE during serialization.
There is no check that the document contains notations whose names match the values of nodes of type xs:NOTATION. This is because notations are not part of the XDM data model. It is possible to add notations to the result document by referencing a suitable DOCTYPE during serialization.
All other children of the document node (comments and processing instructions) are copied unchanged.

[ERR XTTE1555] It is a type error if, when validating a document node, document-level constraints are not satisfied. These constraints include identity constraints (xs:unique, xs:key, and xs:keyref) and ID/IDREF constraints.

23 Serialization

A processor may output a final result tree as a sequence of octets, although it is not required to be able to do so (see 24 Conformance). Stylesheet authors can use xsl:output declarations to specify how they wish result trees to be serialized. If a processor serializes a final result tree, it must do so as specified by these declarations.

The rules governing the output of the serializer are defined in [XSLT and XQuery Serialization]. The serialization is controlled using a number of serialization parameters. The values of these serialization parameters may be set within the stylesheet, using the xsl:output, xsl:result-document, and xsl:character-map declarations.

The xsl:output declaration is optional; if used, it must always appear as a top-level element within a stylesheet module.

A stylesheet may contain multiple xsl:output declarations and may include or import stylesheet modules that also contain xsl:output declarations. The name of an xsl:output declaration is the value of its name attribute, if any.

[Definition: All the xsl:output declarations in a stylesheet that share the same name are grouped into a named output definition; those that have no name are grouped into a single unnamed output definition.]

A stylesheet always includes an unnamed output definition; in the absence of an unnamed xsl:output declaration, the unnamed output definition is equivalent to the one that would be used if the stylesheet contained an xsl:output declaration having no attributes.

A named output definition is used when its name matches the format attribute used in an xsl:result-document element. The unnamed output definition is used when an xsl:result-document element omits the format attribute. It is also used when serializing the final result tree that is created implicitly in the absence of an xsl:result-document element.

All the xsl:output elements making up an output definition are effectively merged. For those attributes whose values are namespace-sensitive, the merging is done after lexical QNames have been converted into expanded QNames. For the cdata-section-elements and suppress-indentation attributes, the output definition uses the union of the values from all the constituent xsl:output declarations. For the use-character-maps attribute, the output definition uses the concatenation of the sequences of expanded QNames values from all the constituent xsl:output declarations, taking them in order of increasing import precedence, or where several have the same import precedence, in declaration order. For other attributes, the output definition uses the value of that attribute from the xsl:output declaration with the highest import precedence.

[ERR XTSE1560] It is a static error if two xsl:output declarations within an output definition specify explicit values for the same attribute (other than cdata-section-elements and use-character-maps), with the values of the attributes being not equal, unless there is another xsl:output declaration within the same output definition that has higher import precedence and that specifies an explicit value for the same attribute.

If none of the xsl:output declarations within an output definition specifies a value for a particular attribute, then the corresponding serialization parameter takes a default value. The default value depends on the chosen output method.

An implementation may allow the attributes of the xsl:output declaration to be overridden, or the default values to be changed, using the API that controls the transformation.

The location to which final result trees are serialized (whether in filestore or elsewhere) is implementation-defined (which in practice may mean that it is controlled using an implementation-defined API). However, these locations must satisfy the constraint that when two final result trees are both created (implicitly or explicitly) using relative URI references in the href attribute of the xsl:result-document instruction, then these relative URI references may be used to construct references from one tree to the other, and such references must remain valid when both result trees are serialized.

The method attribute on the xsl:output element identifies the overall method that is to be used for outputting the final result tree.

[ERR XTSE1570] The value must (if present) be a valid QName. If the QName does not have a prefix, then it identifies a method specified in [XSLT and XQuery Serialization] and must be one of xml, html, xhtml, or text. If the QName has a prefix, then the QName is expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the output method; the behavior in this case is not specified by this document.

The default for the method attribute depends on the contents of the tree being serialized, and is chosen as follows. If the document node of the final result tree has an element child, and any text nodes preceding the first element child of the document node of the result tree contain only whitespace characters, then:

If the expanded-QName of this first element child has local part html (in lower case), and namespace URI http://www.w3.org/1999/xhtml, then the default output method is normally xhtml. However, if the version attribute of the xsl:stylesheet element of the principal stylesheet module has the value 1.0, and if the result tree is generated implicitly (rather than by an explicit xsl:result-document instruction), then the default output method in this situation is xml.
If the expanded-QName of this first element child has local part html (in any combination of upper and lower case) and a null namespace URI, then the default output method is html.

In all other cases, the default output method is xml.

The default output method is used if the selected output definition does not include a method attribute.

The other attributes on xsl:output provide parameters for the output method. The following attributes are allowed:

The value of the encoding attribute provides the value of the encoding parameter to the serialization method. The default value is implementation-defined, but in the case of the xml and xhtml methods it must be either UTF-8 or UTF-16.
The byte-order-mark attribute defines whether a byte order mark is written at the start of the file. If the value yes is specified, a byte order mark is written; if no is specified, no byte order mark is written. The default value depends on the encoding used. If the encoding is UTF-16, the default is yes; for UTF-8 it is implementation-defined, and for all other encodings it is no. The value of the byte order mark indicates whether high order bytes are written before or after low order bytes; the actual byte order used is implementation-dependent, unless it is defined by the selected encoding.
The cdata-section-elements attribute is a whitespace-separated list of QNames. The default value is an empty list. After expansion of these names using the in-scope namespace declarations for the xsl:output declaration in which they appear, this list of names provides the value of the cdata-section-elements parameter to the serialization method. In the case of an unprefixed name, the default namespace (that is, the namespace declared using xmlns="uri") is used.

Note:

This differs from the rule for most other QNames used in a stylesheet. The reason is that these names refer to elements in the result document, and therefore follow the same convention as the name of a literal result element or the name attribute of xsl:element.
The value of the doctype-system attribute provides the value of the doctype-system parameter to the serialization method. By default, the parameter is not supplied.
The value of the doctype-public attribute provides the value of the doctype-public parameter to the serialization method. By default, the parameter is not supplied.

The value of doctype-public must conform to the rules for a PubidLiteral^XML (see [XML 1.0]).
The value of the escape-uri-attributes attribute provides the value of the escape-uri-attributes parameter to the serialization method. The default value is yes.
The value of the include-content-type attribute provides the value of the include-content-type parameter to the serialization method. The default value is yes.
The value of the indent attribute provides the value of the indent parameter to the serialization method. The default value is yes in the case of the html and xhtml output methods, no in the case of the xml output method.
The value of the media-type attribute provides the value of the media-type parameter to the serialization method. The default value is text/xml in the case of the xml output method, text/html in the case of the html and xhtml output methods, and text/plain in the case of the text output method.
The value of the normalization-form attribute provides the value of the normalization-form parameter to the serialization method. A value that is an NMTOKEN other than one of those enumerated for the normalization-form attribute specifies an implementation-defined normalization form; the behavior in this case is not specified by this document. The default value is none.
The value of the omit-xml-declaration attribute provides the value of the omit-xml-declaration parameter to the serialization method. The default value is no.
The value of the standalone attribute provides the value of the standalone parameter to the serialization method. The default value is omit; this means that no standalone attribute is to be included in the XML declaration.
The suppress-indentation attribute is a whitespace-separated list of QNames. The default value is an empty list. After expansion of these names using the in-scope namespace declarations for the xsl:output declaration in which they appear, this list of names provides the value of the suppress-indentation parameter to the serialization method. In the case of an unprefixed name, the default namespace (that is, the namespace declared using xmlns="uri") is used.

Note:

This differs from the rule for most other QNames used in a stylesheet. The reason is that these names refer to elements in the result document, and therefore follow the same convention as the name of a literal result element or the name attribute of xsl:element.
The undeclare-prefixes attribute is relevant only when producing output with method="xml" and version="1.1" (or later). It defines whether namespace undeclarations (of the form xmlns:foo="") should be output when a child element has no namespace node with the same name (that is, namespace prefix) as a namespace node of its parent element. The default value is no: this means that namespace undeclarations are not output, which has the effect that when the resulting XML is reparsed, the new tree may contain namespace nodes on the child element that were not there in the original tree before serialization.
The use-character-maps attribute provides a list of named character maps that are used in conjunction with this output definition. The way this attribute is used is described in 23.1 Character Maps. The default value is an empty list.
The value of the version attribute provides the value of the version parameter to the serialization method. The set of permitted values, and the default value, are implementation-defined. A serialization error will be reported if the requested version is not supported by the implementation.

If the processor performs serialization, then it must signal any non-recoverable serialization errors that occur. These have the same effect as non-recoverable dynamic errors: that is, the processor must signal the error and must not finish as if the transformation had been successful.

23.1 Character Maps

[Definition: A character map allows a specific character appearing in a text or attribute node in the final result tree to be substituted by a specified string of characters during serialization.] The effect of character maps is defined in [XSLT and XQuery Serialization].

The character map that is supplied as a parameter to the serializer is determined from the xsl:character-map elements referenced from the xsl:output declaration for the selected output definition.

The xsl:character-map element is a declaration that may appear as a child of the xsl:stylesheet element.

 <xsl:character-map name = qname use-character-maps? = qnames >  </xsl:character-map>

The xsl:character-map declaration declares a character map with a name and a set of character mappings. The character mappings are specified by means of xsl:output-character elements contained either directly within the xsl:character-map element, or in further character maps referenced in the use-character-maps attribute.

The required name attribute provides a name for the character map. When a character map is used by an output definition or another character map, the character map with the highest import precedence is used.

[ERR XTSE1580] It is a static error if the stylesheet contains two or more character maps with the same name and the same import precedence, unless it also contains another character map with the same name and higher import precedence.

The optional use-character-maps attribute lists the names of further character maps that are included into this character map.

[ERR XTSE1590] It is a static error if a name in the use-character-maps attribute of the xsl:output or xsl:character-map elements does not match the name attribute of any xsl:character-map in the stylesheet.

[ERR XTSE1600] It is a static error if a character map references itself, directly or indirectly, via a name in the use-character-maps attribute.

It is not an error if the same character map is referenced more than once, directly or indirectly.

An output definition, after recursive expansion of character maps referenced via its use-character-maps attribute, may contain several mappings for the same character. In this situation, the last character mapping takes precedence. To establish the ordering, the following rules are used:

Within a single xsl:character-map element, the characters defined in character maps referenced in the use-character-maps attribute are considered before the characters defined in the child xsl:output-character elements.
The character maps referenced in a single use-character-maps attribute are considered in the order in which they are listed in that attribute. The expansion is depth-first: each referenced character map is fully expanded before the next one is considered.
Two xsl:output-character elements appearing as children of the same xsl:character-map element are considered in document order.

The xsl:output-character element is defined as follows:

<xsl:output-character character = char string = string />

The character map that is passed as a parameter to the serializer contains a mapping for the character specified in the character attribute to the string specified in the string attribute.

Character mapping is not applied to characters for which output escaping has been disabled as described in 23.2 Disabling Output Escaping.

If a character is mapped, then it is not subjected to XML or HTML escaping.

Example: Using Character Maps to Generate Non-XML Output

Character maps can be useful when producing serialized output in a format that resembles, but is not strictly conformant to, HTML or XML. For example, when the output is a JSP page, there might be a need to generate the output:

<jsp:setProperty name="user" property="id" value='<%= "id" + idValue %>'/>

Although this output is not well-formed XML or HTML, it is valid in Java Server Pages. This can be achieved by allocating three Unicode characters (which are not needed for any other purpose) to represent the strings <%, %>, and ", for example:

<xsl:character-map name="jsp">
  <xsl:output-character character="«" string="&lt;%"/>   
  <xsl:output-character character="»" string="%&gt;"/>
  <xsl:output-character character="§" string='"'/>
</xsl:character-map>

When this character map is referenced in the xsl:output declaration, the required output can be produced by writing the following in the stylesheet:

<jsp:setProperty name="user" property="id" value='«= §id§ + idValue »'/>

This works on the assumption that when an apostrophe or quotation mark is generated as part of an attribute value by the use of character maps, the serializer will (where possible) use the other choice of delimiter around the attribute value.

Example: Constructing a Composite Character Map

The following example illustrates a composite character map constructed in a modular fashion:

<xsl:output name="htmlDoc" use-character-maps="htmlDoc" />

<xsl:character-map name="htmlDoc"
  use-character-maps="html-chars doc-entities windows-format" />
  
<xsl:character-map name="html-chars"
  use-character-maps="latin1 ..." />

<xsl:character-map name="latin1">
  <xsl:output-character character="&#160;" string="&amp;nbsp;" />
  <xsl:output-character character="&#161;" string="&amp;iexcl;" />
  ...
</xsl:character-map>

<xsl:character-map name="doc-entities">
  <xsl:output-character character="&#xE400;" string="&amp;t-and-c;" />
  <xsl:output-character character="&#xE401;" string="&amp;chap1;" />
  <xsl:output-character character="&#xE402;" string="&amp;chap2;" />
  ...
</xsl:character-map>

<xsl:character-map name="windows-format">
  <!-- newlines as CRLF -->
  <xsl:output-character character="&#xA;" string="&#xD;&#xA;" />

  <!-- tabs as three spaces -->
  <xsl:output-character character="&#x9;" string="   " />

  <!-- images for special characters -->
  <xsl:output-character character="&#xF001;"
    string="&lt;img src='special1.gif' /&gt;" />
  <xsl:output-character character="&#xF002;"
    string="&lt;img src='special2.gif' /&gt;" />
  ...
</xsl:character-map>

23.2 Disabling Output Escaping

Normally, when using the XML, HTML, or XHTML output method, the serializer will escape special characters such as & and < when outputting text nodes. This ensures that the output is well-formed. However, it is sometimes convenient to be able to produce output that is almost, but not quite well-formed XML; for example, the output may include ill-formed sections which are intended to be transformed into well-formed XML by a subsequent non-XML-aware process. For this reason, XSLT defines a mechanism for disabling output escaping.

This feature is deprecated.

This is an optional feature: it is not required that a XSLT processor that implements the serialization option should offer the ability to disable output escaping, and there is no conformance level that requires this feature.

This feature requires an extension to the serializer described in [XSLT and XQuery Serialization]. Conceptually, the final result tree provides an additional boolean property disable-escaping associated with every character in a text node. When this property is set, the normal action of the serializer to escape special characters such as & and < is suppressed.

An xsl:value-of or xsl:text element may have a disable-output-escaping attribute; the allowed values are yes or no. The default is no; if the value is yes, then every character in the text node generated by evaluating the xsl:value-of or xsl:text element should have the disable-output property set.

Example: Disable Output Escaping

For example,

<xsl:text disable-output-escaping="yes">&lt;</xsl:text>

should generate the single character <.

If output escaping is disabled for an xsl:value-of or xsl:text instruction evaluated when temporary output state is in effect, the request to disable output escaping is ignored.

If output escaping is disabled for text within an element that would normally be output using a CDATA section, because the element is listed in the cdata-section-elements, then the relevant text will not be included in a CDATA section. In effect, CDATA is treated as an alternative escaping mechanism, which is disabled by the disable-output-escaping option.

Example: Interaction of Output Escaping and CDATA

For example, if <xsl:output cdata-section-elements="title"/> is specified, then the following instructions:

<title>
  <xsl:text disable-output-escaping="yes">This is not &lt;hr/&gt; 
                                          good coding practice</xsl:text>
</title>

should generate the output:

<title><![CDATA[This is not ]]><hr/><![CDATA[ good coding practice]]></title>

The disable-output-escaping attribute may be used with the html output method as well as with the xml output method. The text output method ignores the disable-output-escaping attribute, since it does not perform any output escaping.

A processor will only be able to disable output escaping if it controls how the final result tree is output. This might not always be the case. For example, the result tree might be used as a source tree for another XSLT transformation instead of being output. It is implementation-defined whether (and under what circumstances) disabling output escaping is supported.

[ERR XTRE1620] It is a recoverable dynamic error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled and the implementation does not support this. The optional recovery action is to ignore the disable-output-escaping attribute.

[ERR XTRE1630] It is a recoverable dynamic error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled when writing to a final result tree that is not being serialized. The optional recovery action is to ignore the disable-output-escaping attribute.

If output escaping is disabled for a character that is not representable in the encoding that the processor is using for output, the request to disable output escaping is ignored in respect of that character.

Since disabling output escaping might not work with all implementations and can result in XML that is not well-formed, it should be used only when there is no alternative.

Note:

The facility to define character maps for use during serialization, as described in 23.1 Character Maps, has been produced as an alternative mechanism that can be used in many situations where disabling of output escaping was previously necessary, without the same difficulties.

24 Conformance

A processor that claims conformance with this specification must claim conformance either as a basic XSLT processor or as a schema-aware XSLT processor. The rules for these two conformance levels are defined in the following sections.

A processor that claims conformance at either of these two levels may additionally claim conformance with either or both of the following optional features: the serialization feature, defined in 24.3 Serialization Feature, and the backwards compatibility feature, defined in 24.4 Compatibility Features.

Note:

There is no conformance level or feature defined in this specification that requires implementation of the static typing features described in [XPath 2.1]. An XSLT processor may provide a user option to invoke static typing, but to be conformant with this specification it must allow a stylesheet to be processed with static typing disabled. The interaction of XSLT stylesheets with the static typing feature of XPath 2.1 has not been specified, so the results of using static typing, if available, are implementation-defined.

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

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

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

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

When a dynamic error occurs during the course of a transformation, the action depends on whether the error is classified as a recoverable error. If a non-recoverable error occurs, the processor must signal it and must eventually terminate abnormally. If a recoverable error occurs, the processor must either signal it and terminate abnormally, or it must take the defined recovery action and continue processing.

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

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

24.1 Basic XSLT Processor

[Definition: A basic XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification with the exception of certain explicitly identified constructs related to schema processing.] These constructs are listed below.

The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.1, as described in [XPath 2.1]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

A basic XSLT processor must enforce the following restrictions. It must signal a static or dynamic error when the restriction is violated, as described below.

[ERR XTSE1650] A basic XSLT processor must signal a static error if the stylesheet includes an xsl:import-schema declaration.

Note:

A processor that rejects an xsl:import-schema declaration will also reject any reference to a user-defined type defined in a schema, or to a user-defined element or attribute declaration; it will not, however, reject references to the built-in types listed in 3.13 Built-in Types.

A basic XSLT processor is not able to validate input documents, and is not able to handle input documents containing type annotations other than xs:untyped or xs:untypedAtomic. Therefore, such a processor must treat any [xsl:]validation or default-validation attribute with a value of preserve or lax as if the value were strip.

Note:

The values lax and preserve indicate that the validation to be applied depends on the calling application, so it is appropriate for the request to be treated differently by different kinds of processor. By contrast, requesting strict validation, either through the [xsl:]validation attribute or the type attribute, indicates that the stylesheet is expecting to deal with typed data, and therefore cannot be processed without performing the validation.

[ERR XTSE1660] A basic XSLT processor must signal a static error if the stylesheet includes an [xsl:]type attribute, or an [xsl:]validation or default-validation attribute with a value other than strip, preserve, or lax.

A basic XSLT processor constrains the data model as follows:

Atomic values must belong to one of the atomic types listed in 3.13 Built-in Types (except as noted below).

An atomic value may also belong to an implementation-defined type that has been added to the context for use with extension functions or extension instructions.

The set of constructor functions available are limited to those that construct values of the above atomic types.

The static context, which defines the full set of type names recognized by an XSLT processor and also by the XPath processor, includes these atomic types, plus xs:anyType, xs:anySimpleType, xs:untyped, and xs:anyAtomicType.
Element nodes must be annotated with the type annotation xs:untyped, and attribute nodes with the type annotation xs:untypedAtomic.

[ERR XTDE1665] A basic XSLT processor must raise a non-recoverable dynamic error if the input to the processor includes a node with a type annotation other than xs:untyped or xs:untypedAtomic, or an atomic value of a type other than those which a basic XSLT processor supports. This error will not arise if the input-type-annotations attribute is set to strip.

Note:

Although this is expressed in terms of a requirement to detect invalid input, an alternative approach is for a basic XSLT processor to prevent this error condition occurring, by not providing any interfaces that would allow the situation to arise. A processor might, for example, implement a mapping from the PSVI to the data model that loses all non-trivial type annotations; or it might not accept input from a PSVI at all.

The phrase input to the processor is deliberately wide: it includes the tree containing the initial context item, trees passed as stylesheet parameters, trees accessed using the document, doc^FO, and collection^FO functions, and trees returned by extension functions and extension instructions.

24.2 Schema-Aware XSLT Processor

[Definition: A schema-aware XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification, including those features that a basic XSLT processor signals as an error. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.1, as described in [XPath 2.1]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.]

24.3 Serialization Feature

[Definition: A processor that claims conformance with the serialization feature must support the conversion of a final result tree to a sequence of octets following the rules defined in 23 Serialization.] It must respect all the attributes of the xsl:output and xsl:character-map declarations, and must provide all four output methods, xml, xhtml, html, and text. Where the specification uses words such as must and required, then it must serialize the result tree in precisely the way described; in other cases it may use an alternative, equivalent representation.

A processor may claim conformance with the serialization feature whether or not it supports the setting disable-output-escaping="yes" on xsl:text, or xsl:value-of.

A processor that does not claim conformance with the serialization feature must not signal an error merely because the stylesheet contains xsl:output or xsl:character-map declarations, or serialization attributes on the xsl:result-document instruction. Such a processor may check that these declarations and attributes have valid values, but is not required to do so. Apart from optional validation, these declarations should be ignored.

24.4 Compatibility Features

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

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

Note that a processor that does not claim conformance with the XSLT 1.0 compatibility feature must raise a non-recoverable dynamic error if an instruction is evaluated whose effective version is 1.0; and similarly, a processor that does not claim conformance with the XSLT 2.0 compatibility feature must raise a non-recoverable dynamic error if an instruction is evaluated whose effective version is 2.0. [see ERR XTDE0160].

Note:

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

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

Note:

Currently, there are no incompatibilities between 2.1 and 2.0 that justify this machinery. This will be reviewed at a later stage of development of the specification.

24.5 Streaming Feature

[Definition: A processor that claims conformance with the streaming feature must ....]

Issue 34 (streaming-conformance):

We need to define the conformance rules for streaming processors.

XSL Transformations (XSLT) Version 2.1

W3C Working Draft 11 May 2010

Abstract

Status of this Document

Table of Contents

Appendices

1 Introduction

1.1 What is XSLT?

1.2 What's New in XSLT 2.1?

2 Concepts

2.1 Terminology

2.2 Notation

2.3 Initiating a Transformation

2.4 Executing a Transformation

2.5 The Evaluation Context

2.6 Parsing and Serialization

2.7 Extensibility

2.8 Stylesheets and XML Schemas

2.9 Streaming

2.10 Error Handling

3 Stylesheet Structure

3.1 XSLT Namespace

3.2 Reserved Namespaces

3.3 Extension Attributes

3.4 XSLT Media Type

3.5 Standard Attributes

3.6 Stylesheet Element

3.6.1 The default-collation attribute

3.6.2 The default-mode attribute

3.6.3 User-defined Data Elements

3.7 Simplified Stylesheet Modules

3.8 Backwards Compatible Processing

3.8.1 XSLT 1.0 compatibility mode

3.8.2 XSLT 2.0 compatibility mode

3.9 Forwards Compatible Processing

3.10 Combining Stylesheet Modules

3.10.1 Locating Stylesheet Modules

3.10.2 Stylesheet Inclusion

3.10.3 Stylesheet Import

3.11 Embedded Stylesheet Modules

3.12 Conditional Element Inclusion

3.13 Built-in Types

3.14 Importing Schema Components

4 Data Model

4.1 XML Versions

4.2 Stripping Whitespace from the Stylesheet

4.3 Stripping Type Annotations from a Source Tree

4.4 Stripping Whitespace from a Source Tree

4.5 Attribute Types and DTD Validation

4.6 Data Model for Streaming

4.7 Limits

4.8 Disable Output Escaping

5 Features of the XSLT Language

5.1 Qualified Names

5.2 Unprefixed QNames in Expressions and Patterns

5.3 Expressions

5.4 The Static and Dynamic Context

5.4.1 Initializing the Static Context

5.4.2 Additional Static Context Components used by XSLT

5.4.3 Initializing the Dynamic Context

5.4.3.1 Maintaining Position: the Focus

5.4.3.2 Other components of the XPath Dynamic Context

5.4.4 Additional Dynamic Context Components used by XSLT

5.5 Patterns

5.5.1 Examples of Patterns

5.5.2 Syntax of Patterns

Patterns

5.5.3 The Meaning of a Pattern

5.5.4 Errors in Patterns

5.6 Attribute Value Templates

5.7 Sequence Constructors

5.7.1 Constructing Complex Content

5.7.2 Constructing Simple Content

5.7.3 Namespace Fixup

5.8 URI References

6 Template Rules

6.1 Defining Templates

6.2 Defining Template Rules

6.3 Applying Template Rules

6.4 Conflict Resolution for Template Rules

3.6.1 The `default-collation` attribute

3.6.2 The `default-mode` attribute

7.1 The `xsl:for-each` instruction

7.2 The `xsl:iterate` instruction

8.1 Conditional Processing with `xsl:if`

8.2 Conditional Processing with `xsl:choose`

11.2 Creating Element Nodes Using `xsl:element`

11.3 Creating Attribute Nodes Using `xsl:attribute`

11.4.2 Creating Text Nodes Using `xsl:text`

11.4.3 Generating Text with `xsl:value-of`

13.1 The `xsl:sort` Element