W3C

XSL Transformations (XSLT)
Version 2.0

W3C Working Draft 30 April 2002

This version:
http://www.w3.org/TR/2002/WD-xslt20-20020430/
Latest version:
http://www.w3.org/TR/xslt20
Previous version:
http://www.w3.org/TR/2001/WD-xslt20-20011220/
Editor:
Michael Kay (Software AG) <Michael.Kay@softwareag.com>

Abstract

This specification defines the syntax and semantics of XSLT, which is a language for transforming XML documents into other XML documents.

XSLT is designed for use as part of XSL, which is a stylesheet language for XML. In addition to XSLT, XSL includes an XML vocabulary for specifying formatting (see [XSL Formatting Objects]). XSL Formatting Objects are frequently used as the output of an XSLT transformation.

XSLT is also designed to be used independently of XSL Formatting Objects. It is often used to produce HTML and XHTML documents, as well as for transformation of application-specific message formats.

Status of this document

This document is the second published Working Draft of XSLT 2.0. It is published in order to provide the XSLT user community with a progress report on the evolving language specification and the outstanding issues that remain to be decided. Changes since the first Working Draft (published on 20 December 2001) are indicated by background highlighting (green for modified text, yellow for new text), or in the case of deleted text, by strikethrough. A summary of the changes is included at [K.3.4 Changes in this draft]; the most significant changes are to clarify the interaction of XSLT with XML Schema. However, further work remains to be done in this area, particularly with regard to creating and validating typed information in the result tree.

This remains a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". While prototype implementations are encouraged, users and vendors are advised that this working draft cannot be regarded as a stable specification.

XSLT 2.0 is intended as a revised version of the XSLT 1.0 Recommendation [XSLT 1.0] published on 16 November 1999. The changes made in this document are intended to meet the requirements for XSLT 1.1 and XSLT 2.0 described in [XSLT 1.1 Requirements] and [XSLT 2.0 Requirements] and to incorporate fixes for errors that have been detected in XSLT 1.0. A summary of the changes since XSLT 1.0 is included in [K Changes from XSLT 1.0].

XSLT 2.0 is designed to be used together with XPath 2.0, which has been developed by the W3C XSL Working Group in collaboration with the XML Query Working Group. The current specification of XPath 2.0 can be found in [XPath 2.0].

NOTE: This specification supersedes XSLT 1.1 (see [XSLT 1.1 WD]), which was never developed beyond the Working Draft stage.

Comments on this specification may be sent to public-qt-comments@w3.org; archives of the comments are available, and it is possible to subscribe to the list. Archives of comments on earlier versions of the specification can be found at http://lists.w3.org/Archives/Public/xsl-editors/. Public discussion of XSL, including XSL Transformations, takes place on the XSL-List mailing list.

The English version of this specification is the only normative version. However, for translations of this document, see http://www.w3.org/Style/XSL/translations.html.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.

This specification has been produced as part of the W3C Style activity.

Table of contents

1 Introduction
    1.1 Stylesheets and Transformation
    1.2 Initiating a Transformation
    1.3 Stylesheets and Schemas
    1.4 Executing a Transformation
    1.5 Maintaining Position: the Focus
    1.6 Parsing and Serialization
    1.7 Extensibility
    1.8 Error Handling
2 Stylesheet Structure
    2.1 XSLT Namespace
    2.2 XSLT Media Type
    2.3 Standard Attributes
    2.4 Stylesheet Element
        2.4.1 User-defined Data Elements
    2.5 Simplified Stylesheet Modules
    2.6 Backwards-Compatible Processing
    2.7 Forwards-Compatible Processing
    2.8 Combining Stylesheet Modules
        2.8.1 Stylesheet Inclusion
        2.8.2 Stylesheet Import
    2.9 Embedded Stylesheet Modules
    2.10 Importing Schema Components
3 Data Model
    3.1 Parentless Nodes
    3.2 Document Node Children
    3.3 Unparsed Entities
    3.4 Whitespace Stripping
    3.5 Namespace Fixup
    3.6 Disable Output Escaping
    3.7 External Objects
4 Syntactic Constructs
    4.1 Qualified Names
    4.2 Expressions
    4.3 Patterns
    4.4 Unprefixed Names in Expressions and Patterns
    4.5 Attribute Value Templates
    4.6 Content Constructors
5 Template Rules
    5.1 Processing Model
    5.2 Defining Template Rules
    5.3 Applying Template Rules
    5.4 Conflict Resolution for Template Rules
    5.5 Overriding Template Rules
    5.6 Modes
    5.7 Built-in Template Rules
6 Variables and Parameters
    6.1 Values of Variables and Parameters
    6.2 Global Variables and Parameters
    6.3 Circular Definitions
    6.4 Local Variables and Parameters
    6.5 Range Variables
7 Callable Components
    7.1 Named Templates
        7.1.1 Passing Parameters to Templates
    7.2 Named Attribute Sets
    7.3 Stylesheet Functions
        7.3.1 Defining a Stylesheet Function
        7.3.2 Returning the Result
8 Creating New Nodes
    8.1 Literal Result Elements
        8.1.1 Attribute Nodes for Literal Result Elements
        8.1.2 Namespace Nodes for Literal Result Elements
        8.1.3 Namespace Aliasing
    8.2 Creating Element Nodes using xsl:element
    8.3 Creating Attribute Nodes using xsl:attribute
    8.4 Creating Text Nodes
        8.4.1 Literal Text Nodes
        8.4.2 Creating Text Nodes using xsl:text
    8.5 Creating Processing Instructions
    8.6 Creating Namespace Nodes
    8.7 Creating Comments
    8.8 Copying Nodes from the Source Tree to the Result Tree
        8.8.1 Shallow Copy
        8.8.2 Deep Copy
    8.9 Generating Text with xsl:value-of
9 Numbering
    9.1 Formatting a Supplied Number
    9.2 Numbering based on Position in the Source Tree
    9.3 Number to String Conversion Attributes
10 Repetition
11 Conditional Processing
    11.1 Conditional Processing with xsl:if
    11.2 Conditional Processing with xsl:choose
12 Sorting
    12.1 Collating Sequences
    12.2 The xsl:sort Element
    12.3 Using Unnamed Sort Specifications
    12.4 Using Named Sort Specifications
13 Grouping
    13.1 The Current Group
    13.2 The xsl:for-each-group Element
    13.3 Examples of Grouping
14 Additional Functions
    14.1 Multiple Source Documents
    14.2 Reading Text Files
    14.3 Keys
        14.3.1 The xsl:key Declaration
        14.3.2 The key Function
    14.4 Number Formatting
        14.4.1 Defining a Decimal Format
        14.4.2 Processing the Picture String
        14.4.3 Analysing the Picture String
        14.4.4 Formatting the Number
    14.5 Dynamic XPath Expressions
    14.6 Miscellaneous Additional Functions
        14.6.1 current()
        14.6.2 unparsed-entity-uri()
        14.6.3 generate-id()
        14.6.4 system-property()
15 Messages
16 Extensibility and Fallback
    16.1 Extension Functions
        16.1.1 Testing Availability of Functions
        16.1.2 Calling Extension Functions
        16.1.3 External Objects
    16.2 Extension Instructions
        16.2.1 Designating an Extension Namespace
        16.2.2 Testing Availability of Instructions
        16.2.3 Fallback
17 Result Trees
    17.1 The Principal Result Tree
    17.2 Secondary Result Trees
18 Serialization
    18.1 XML Output Method
    18.2 XHTML Output Method
    18.3 HTML Output Method
    18.4 Text Output Method
    18.5 Disabling Output Escaping
19 Conformance
20 Notation

Appendices

A References
    A.1 Normative References
    A.2 Other References
B Glossary (Non-Normative)
C Element Syntax Summary
D Summary of Error Conditions (Non-Normative)
E Checklist of Implementation-Defined Features (Non-Normative)
F DTD Fragment for XSLT Stylesheets (Non-Normative)
G Representation of Lexical XML Constructs (Non-Normative)
H Acknowledgements (Non-Normative)
I Checklist of Requirements (Non-Normative)
J Summary of Issues (Non-Normative)
    J.1 Open Issues
    J.2 Decided Issues
    J.3 Closed Issues
K Changes from XSLT 1.0 (Non-Normative)
    K.1 Incompatible Changes
        K.1.1 XSLT 2.0 Backwards Compatibility
        K.1.2 XPath 2.0 Backwards Compatibility
        K.1.3 Compatibility in the Presence of a Schema
    K.2 Changes from XSLT 1.0 to XSLT 1.1
    K.3 Changes from XSLT 1.1 to XSLT 2.0
        K.3.1 Pervasive changes
        K.3.2 Major Features
        K.3.3 Minor Changes
        K.3.4 Changes in this draft

1 Introduction

1.1 Stylesheets and Transformation

This specification defines the syntax and semantics of the XSLT language. A transformation in the XSLT language is expressed in the form of a stylesheet, whose syntax is well-formed XML [XML] conforming to the Namespaces in XML Recommendation [XML Names]. A stylesheet generally includes both elements that are defined by XSLT and elements that are not defined by XSLT. XSLT-defined elements are distinguished by belonging to a specific XML namespace (http://www.w3.org/1999/XSL/Transform: see [2.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.

NOTE: 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, or into another presentation-oriented format such as HTML, XHTML, or SVG.

The software responsible for transforming a source document into a result document 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. A specific product that performs the functions of an XSLT processor is referred to as an implementation.

A transformation expressed in XSLT describes rules for transforming a source tree into a result tree. 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 content constructor, which can be evaluated to produce part of the result tree. The structure of the result tree can be completely different from the structure of the source tree. In constructing the result tree, nodes from the source tree 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.

NOTE: More generally, a transformation can process several source trees and produce several result trees.

A stylesheet may consist of several stylesheet modules, contained in different XML documents. 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 [2.8.1 Stylesheet Inclusion] and [2.8.2 Stylesheet Import].

1.2 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 must be supplied when a transformation is initiated.

There are two ways a transformation can be initiated: these are referred to as apply-transformation and call-transformation.

In both cases the transformation requires identification of the principal stylesheet module, and optionally, values for one or more stylesheet parameters (see [6.2 Global Variables and Parameters]).

In the case of apply-transformation, the following additional information is supplied by the client application:

  • A node within a document (often, but not necessarily, a document node) where the transformation is to commence. This node is referred to as the initial input node.

With this method of invocation, the stylesheet starts executing with the template rule that best matches the supplied node, according to the rules defined in [5.4 Conflict Resolution for Template Rules]. The initial input node is available at any point during the processing of the stylesheet as the result of the input function described in [Functions and Operators].

The document containing the initial input node is referred to as the principal source document.

In the case of call-transformation, the following additional information is supplied by the client application:

  • A collection of nodes that forms the initial input sequence. These nodes (which will often be document nodes, but may in principle be any kind of node, from the same or different documents) are available at any time during the transformation as the result of the input function described in [Functions and Operators].
  • The name of a named template (see [7.1 Named Templates]) which is to be invoked. The API may provide a default entry point, conventionally <xsl:template name="main">, but this is not required.

With this method of invocation, the stylesheet starts executing with the named template rule.

[ERR001] It is a dynamic error if the stylesheet is invoked using the call-transformation method, and the invocation specifies an template name that does not match the expanded-QName of a named template defined in the stylesheet.

Issue (global-variables-in-call-mode): It's not obvious what the context should be for evaluating global variables when a transformation is initiated using the "call-transformation" method. The solution adopted here, that the "principal source document" is the document containing the first node of the input sequence, is unsatisfactory, and is included purely to avoid leaving a gaping hole.

When a stylesheet is invoked using the call-transformation method, the principal source document is considered to be the document containing the first node in the initial input.

Note that (with either invocation method) any parameters passed to the transformation by the client application are matched against global stylesheet parameters (see [6.2 Global Variables and Parameters]), not against the local parameters declared within the first template to be executed. All local parameters within the first template to be executed will take their default values.

A stylesheet can process further source documents in addition to the principal source document. These additional documents can be loaded using the functions document or collection described in [Functions and Operators], or they can be supplied as stylesheet parameters (see [6.2 Global Variables and Parameters]), or as the result of an extension function (see [16.1 Extension Functions]

NOTE: Sometimes it is useful to write an XSLT stylesheet that does not require input from a principal source document. However, the semantics of the language require that a principal source document is always present. Implementors may provide a mechanism that supplies a default document, containing just a document node with no children, as the principal source document to be used in the absence of any other source document.

1.3 Stylesheets and Schemas

An XSLT stylesheet can make use of information from XML Schemas, as defined in [XML Schema]. 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 typed information associated with individual nodes, not merely to the raw text.

There are places within a stylesheet, and within XPath expressions and patterns with a stylesheet, where the names of schema-defined elements, attributes, and named types may appear. For example, it is possible to declare the types expected for the parameters of a function. The element, attribute, and type names that appear in such contexts must either be built-in schema types (for example xsd:string or xsd:integer), or they must be user-defined types that are made accessible to the XSLT processor by means of an xsl:import-schema declaration: see [2.10 Importing Schema Components].

It is only necessary to import a schema explicitly if its type definitions are mentioned statically 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.

Further, 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 the result tree just as much as for nodes on the principal source document.

Issue (assert-source-document-type): How should a stylesheet assert the schema type of the source documents that it is designed to process?

A stylesheet can also make assertions about the types of nodes that it constructs in a final result tree, or in temporary trees. In the case of temporary trees, this enables the tree to be processed in the same way as a source document that has undergone schema assessment. In the case of a final result tree, it enables the result tree to be passed to further processes (including further XSLT transformations) with its type information intact.

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, and if it does perform such checking, any errors reported are advisory only: the user must be given the option to use the stylesheet even if static analysis has revealed type errors.

1.4 Executing a Transformation

A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a content constructor which is evaluated to produce a sequence of nodes: these nodes are typically used to form part of the result tree. This allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

A content constructor is evaluated for a particular node in the source tree, to create part of the result tree. A content constructor can contain elements (called literal result elements) and text nodes that specify part of the result structure directly. A content constructor can also contain elements from the XSLT namespace that are instructions for creating parts of the result tree.

When a content constructor is evaluated, each instruction is evaluated to produce a sequence of zero or more nodes; the result of the content constructor as a whole is a sequence of nodes formed by concatenating the results of each of the instructions and literal results nodes that it contains, in the order that they appear in the content constructor. The resulting nodes are typically attached as children to an element or document node constructed by the instruction that contains the content constructor, thus forming a tree. During this process, adjacent text nodes will be merged into a single text node. When a content constructor is evaluated to create new nodes, the tree to which these nodes are added is referred to as the current result tree. When the transformation is initiated, a result tree is created, and becomes the current result tree. This tree is referred to as the principal result tree. Various XSLT instructions, (including xsl:variable and xsl:result-document) establish a new current result tree for the nodes created by the content constructor that they contain.

The elements occurring within a content constructor are classified as being either literal result elements or instructions. If the element is in the XSLT namespace, or in a namespace designated as an extension namespace, then it is an instruction. Otherwise, it is a literal result element.

The element syntax summary notation used to describe the syntax of XSLT-defined elements is described in [20 Notation], and a full list of these elements is provided in [C Element Syntax Summary]

Instructions can select and process other nodes in a source tree. The typical way of processing a source node is to create a sequence of result nodes by finding the applicable template rule and evaluating its content constructor. Note that source nodes are processed only if they are selected by such an instruction.

Instructions that select nodes from the source document, or that derive information from these nodes for inclusion in the result document, always access the source tree by means of an Expression in the XPath language, described in [XPath 2.0]. A stylesheet written to use XSLT 2.0 will contain expressions whose syntax and semantics are defined by XPath 2.0 (but see also [2.6 Backwards-Compatible Processing] and [2.7 Forwards-Compatible Processing]).

Execution of a stylesheet against the principal source document proceeds by creating a document node for the principal result tree, finding the template rule that matches the document node of the source tree, and evaluating the content constructor of this template rule to create the children of the new document node. By the time evaluation of this content constructor is complete, these children will typically each act as the parent of further result nodes, so a complete tree is constructed.

It is also possible for the execution of a stylesheet to start at a node in the source document other than the document node, determined by the implementation-specific mechanism for invoking a stylesheet. In this situation, the complete tree remains available for processing by the stylesheet; the only difference is the choice of the node used when applying the first template rule.

In the process of finding the applicable template rule, more than one template rule may have a pattern that matches a given node. However, only one template rule will be applied. The method for deciding which template rule to apply is described in [5.4 Conflict Resolution for Template Rules].

A single content constructor by itself has considerable power. It can create structures of arbitrary complexity; it can pull string values out of arbitrary locations in the source tree; and it can generate structures that are repeated according to the occurrence of nodes in the source tree.

For simple transformations where the structure of the result tree is independent of the structure of the source tree, a stylesheet can often consist of only a single literal result element, containing a content constructor which functions as a template for building the complete result tree. Transformations on XML documents that represent data with a regular and predictable structure (for example, data extracted from a relational database) are often of this kind. XSLT allows a simplified syntax for such stylesheets (see [2.5 Simplified Stylesheet Modules]).

1.5 Maintaining Position: the Focus

When a content constructor is evaluated, the processor keeps track of which nodes 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 five values:

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

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.

Sometimes the focus is based on a single node rather than a sequence. A singleton focus based on a node N has the context item (and therefore the context node) set to N, the context document set to the document containing N, and the context position and context size both set to 1 (one).

1.6 Parsing and Serialization

As explained in the previous section, an XSLT stylesheet describes a process that constructs a result tree from a source tree.

The stylesheet does not describe how the source tree is constructed. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML], an XML processor), to build the 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 [DOM2]). 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 data model 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.

A frequent requirement is to output the 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 should be able to perform serialization. However, for pragmatic reasons, this specification describes a declaration (the xsl:output element, see [18 Serialization]) which allows a stylesheet to specify the desired properties of a serialized output file. Implementations that do not serialize the result tree are allowed to ignore this declaration.

Because it is a common requirement to perform a transformation on a document while retaining lexical characteristics such as CDATA section boundaries, entity references, and the like, an appendix to this specification (see [G Representation of Lexical XML Constructs]) describes a way in which these constructs can be represented within the data model by means of elements in a special namespace. If such a representation is chosen, the tree is transformed in the same way as any other tree. The process of constructing such a tree is something that happens before XSLT transformation starts, and the process of interpreting such a tree and reconstituting the lexical representation is part of the serialization process. Neither of these processes is properly within the scope of XSLT transformation, and therefore, this specification places no requirement on an XSLT processor to support this representation of lexical properties.

1.7 Extensibility

XSLT provides two "hooks" for extending the language, one hook for extending the set of instruction elements used in content constructors and one hook for extending the set of functions used in XPath expressions. These hooks are both based on XML namespaces: see [16 Extensibility and Fallback] for further details. Extension instructions and extension functions defined according to these rules may be provided by the implementor of the XSLT processor, and the implementor 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.

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 should be described in the vendor's documentation.

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.

1.8 Error Handling

An error that is 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, and it must not use the stylesheet to produce a result tree. A static error must be signaled even if it occurs in a part of the stylesheet that is never evaluated.

There is an exception to this rule when the stylesheet specifies forwards-compatible behavior (see [2.7 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.

An error that is not detected until a source document is being transformed is referred to as a dynamic error. In many cases, this specification allows dynamic errors to be signaled (by reporting the error condition and terminating execution), but also defines a recovery action that can be taken. It is implementation-defined whether the error is signaled or the recovery action is taken. If the implementation does choose to take recovery action, it must take the recovery action defined 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 is also allowed to take other action, such as logging a warning message.

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 result tree 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 can 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 report 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 [6.3 Circular Definitions].

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 reported as a dynamic error. An implementation may also, optionally, report a type error 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. For example, the following construct contains a type error, because 42 is not allowed as an operand of the xsl:apply-templates instruction. An implementation may optionally report this as a static error, even though the offending instruction will never be evaluated, and the type error would therefore never be reported as a dynamic error.

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

<xsl:if test="false()">
  <xsl:apply-templates select="42"/>
</xsl:if>

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 produce a result tree.

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.

If a transformation has successfully produced a 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. As with other aspects of serialization, the handling of serialization errors is implementation-defined: see [18 Serialization].

2 Stylesheet Structure

A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document. There are three kinds of stylesheet module:

2.1 XSLT Namespace

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 [2.4 Stylesheet Element] and [2.5 Simplified Stylesheet Modules]).

XSLT processors must use the XML namespaces mechanism [XML Names] 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 [16.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.

An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded-QName (see [XPath 2.0]) of the attribute has a non-null namespace URI. The presence of such attributes must not change the behavior of XSLT elements and functions defined in this document or in the XPath specification, though they may be used to modify the behavior of extension functions and extension instructions. Thus, an implementation is always free to ignore such attributes, and must ignore such attributes without giving an error if it does not recognize the namespace URI. Such attributes can provide, for example, unique identifiers, optimization hints, or documentation. The set of namespaces that are recognized for such attributes is implementation-defined.

For example, the following code might be used to provide a hint to a particular implementation that a call to an extension function has side effects:

<xsl:value-of select="abc:set-property('someprop', 3)" 
    abc:side-effects="yes"
    xmlns:abc="http://some.vendor.com/xslt/extensions"/>

[ERR002] It is a static error for an element from the XSLT namespace to have an attribute with an expanded-QName that has a null namespace URI (i.e. an attribute with an unprefixed name) other than attributes defined for the element in this document.

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.

2.2 XSLT Media Type

The MIME media types text/xml and application/xml [RFC2376] should be used for XSLT stylesheets. It is possible that a media type will be registered specifically for XSLT stylesheets; if and when it is, that media type may also be used.

2.3 Standard Attributes

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

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

It is recommended that these attributes should also be permitted on extension instructions, but this is at the discretion of the implementor 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, and any descendant elements of the element they appear on, together with attributes of those descendant elements. 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 and [xsl:]default-xpath-namespace the value can be overridden by a different value for the same attribute appearing on a descendant element. The effective value of the attribute for a particular stylesheet element is determined by the innermost containing element on which the attribute appears.

In the case of [xsl:]exclude-result-prefixes and [xsl:]extension-element-prefixes the values are cumulative. For these attributes, the value is a whitespace-separated list of namespace prefixes, and the effective value for an element is the combined set of 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.

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 description of the xsl:stylesheet and xsl:transform elements only. This reflects the fact that these attributes are often used on the xsl:stylesheet element, 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:

2.4 Stylesheet Element

<xsl:stylesheet
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  default-xpath-namespace = uri>
  <!-- Content: (xsl:import*, top-level-elements) -->
</xsl:stylesheet>

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  default-xpath-namespace = uri>
  <!-- Content: (xsl:import*, top-level-elements) -->
</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.

[ERR003] An xsl:stylesheet element must have a version attribute, indicating the version of XSLT that the stylesheet requires. [ERR004] The value of the version attribute must be a number (specifically, it must be a DecimalLiteral as defined in [XPath 2.0].) For this version of XSLT, the value should normally be 2.0. When the value is less than 2.0, backwards-compatible processing behavior is enabled (see [2.6 Backwards-Compatible Processing]). When the value is greater than 2.0, forwards-compatible behavior is enabled (see [2.7 Forwards-Compatible Processing]).

[ERR005] An xsl:stylesheet element must have no text node children, other than text nodes consisting entirely of whitespace.

An element occurring as a child of an xsl:stylesheet element is called a top-level element.

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 [2.4.1 User-defined Data Elements])

The xsl:stylesheet element may contain the following types of declaration:

The order in which the children of the xsl:stylesheet element occur is not significant except for xsl:import elements and for error recovery. Users are free to order the elements as they prefer, and stylesheet creation tools need not provide control over the order in which the elements occur.

2.4.1 User-defined Data Elements

In addition to declarations, the xsl:stylesheet element may contain 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. [ERR006] It is a static error if the xsl:stylesheet element has a child element having a null namespace URI.

An implementation may attach meaning to user-defined data elements that appear in a namespace controlled by the vendor. 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. 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. The set of namespaces that are recognized for such data elements is implementation-defined.

User-defined data elements can provide, for example,

[ERR007] A user-defined data element must not precede an xsl:import element within a stylesheet module.

2.5 Simplified Stylesheet Modules

A simplified syntax is allowed for a stylesheet module that consists of only a single template rule for the document node. The stylesheet module may consist of just a literal result element (see [8.1 Literal Result Elements]). Such a stylesheet is equivalent to a standard stylesheet module whose xsl:stylesheet element contains a template rule containing the literal result element; the template rule has a match pattern of /. For example:

<html xsl:version="2.0"
      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.0"
                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>

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:

<xsl:stylesheet version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/*">
  <xsl:element name="xsl:stylesheet">
    <xsl:attribute name="version">
      <xsl:value-of select="@xsl:version"/>
    </xsl:attribute>
    <xsl:element name="xsl:template">
      <xsl:attribute name="match">/</xsl:attribute>
      <xsl:copy-of select="."/>
    </xsl:element>
  </xsl:element>
</xsl:template>  

</xsl:stylesheet>

If the outermost element of the simplified stylesheet is not the document element, then in the above transformation the attribute match="/*" must be replaced by a pattern than matches this outermost element. Note that if the element has an ID attribute to enable it to be selected (for example in the fragment identifier of a URI reference), then this ID attribute will be copied to the result document in the same way as other attributes of a literal result element.

[ERR008] 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 should normally be 2.0; the value must be a DecimalLiteral as defined in [XPath 2.0].

Other literal result elements may also have an xsl:version attribute. When the xsl:version attribute is numerically less than 2.0, backwards-compatible processing behavior is enabled (see [2.6 Backwards-Compatible Processing]). When the xsl:version attribute is numerically greater than 2.0, forwards-compatible behavior is enabled (see [2.7 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 content constructor. Thus, a literal result element used as the document element of a simplified stylesheet cannot contain declarations.

2.6 Backwards-Compatible Processing

An element enables backwards-compatible behavior for itself, its attributes, its descendants and their attributes if either it has an [xsl:]version attribute (see [2.3 Standard Attributes]) whose value is less than 2.0. 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.

If an attribute containing an XPath expression is processed with backwards-compatible behavior, then:

It is implementation-defined whether a particular XSLT 2.0 implementation supports backwards-compatible behavior. [ERR010] If an implementation does not support backwards-compatible behavior, then it is a dynamic error if any element is evaluated that enables backwards-compatible behavior. The processor must signal the error.

2.7 Forwards-Compatible Processing

An element enables forwards-compatible behavior for itself, its attributes, its descendants and their attributes if it has an [xsl:]version attribute (see [2.3 Standard Attributes]) whose value is greater than 2.0. An element that has an [xsl:]version attribute whose value is less than or equal to 2.0 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.

Within a section of a stylesheet where forwards-compatible behavior is enabled, errors that would normally be static errors are treated instead as dynamic errors. This means that no error is reported unless the construct containing the error is actually evaluated.

This means, for example, that when an element is processed with forwards-compatible behavior:

Thus, any XSLT 2.0 processor must be able to 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:choose>
      <xsl:when test="system-property('xsl:version') >= 17.0">
        <xsl:exciting-new-17.0-feature/>
      </xsl:when>
      <xsl:otherwise>
        <html>
        <head>
          <title>XSLT 17.0 required</title>
        </head>
        <body>
          <p>Sorry, this stylesheet requires XSLT 17.0.</p>
        </body>
        </html>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
</xsl:stylesheet>
NOTE: If a stylesheet depends crucially on a declaration introduced by a version of XSLT after 2.0, then the stylesheet can use an xsl:message element with terminate="yes" (see [15 Messages]) to ensure that implementations that conform to an earlier version of XSLT will not silently ignore the declaration. 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="system-property('xsl:version') < 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>

2.8 Combining Stylesheet Modules

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

2.8.1 Stylesheet Inclusion

<!-- Category: declaration -->
<xsl:include
  href = uri-reference />

A stylesheet module may include another stylesheet module using an xsl:include declaration. The xsl:include declaration has an href attribute whose value is a URI reference identifying the stylesheet module to be included. A relative URI is resolved relative to the base URI of the xsl:include declaration (see [Data Model]).

It is implementation-defined whether the URI reference may include a fragment identifier, and if so, what form of fragment identifier is supported. A future version of XSLT may define rules for the use of fragment identifiers in the URI reference, for example by reference to the XPointer specification (see [XPointer]). 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.

[ERR011] The xsl:include element is allowed only as a top-level element.

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.

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.

The included stylesheet module may be any of the three kinds of stylesheet module: a standard stylesheet module, a simplified stylesheet module, or an embedded stylesheet module.

[ERR012] It is an 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'.

2.8.2 Stylesheet Import

<!-- Category: declaration -->
<xsl:import
  href = uri-reference />

A stylesheet module may import another stylesheet module using an xsl:import declaration. Importing a stylesheet is the same as including it (see [2.8.1 Stylesheet Inclusion]) except that template rules and other declarations in the importing stylesheet take precedence over template rules and declarations in the imported stylesheet; this is described in more detail below. The xsl:import declaration has an href attribute whose value is a URI reference identifying the stylesheet to be imported. A relative URI is resolved relative to the base URI of the xsl:import element (see [Data Model]).

It is implementation-defined whether the URI reference may include a fragment identifier, and if so, what form of fragment identifier is supported. A future version of XSLT may define rules for the use of fragment identifiers in the URI reference, for example by reference to the XPointer specification (see [XPointer]). Note that if the implementation does not support the use of fragment identifiers in the URI reference, then it will not be possible to import an embedded stylesheet module.

[ERR013] The xsl:import declaration is allowed only as a top-level element. [ERR014] 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.

For example,

<xsl:stylesheet version="2.0"
                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>

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

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

NOTE: The case where a stylesheet with a particular URI is imported in multiple places is not treated specially. The resulting stylesheet will contain multiple declarations that are identical in content but that differ in their import precedence.

2.9 Embedded Stylesheet Modules

A standard stylesheet module is a complete XML document with the xsl:stylesheet element as its document element. However, a stylesheet module may also be embedded in another resource. Two forms of embedding are possible:

To facilitate the second form of embedding, the xsl:stylesheet element is allowed to have an ID attribute that specifies a unique identifier.

NOTE: In order for such an attribute to be used with the XPath id function, it must actually be declared in the DTD as being of type ID. The same requirement typically applies if the identifier is to be used as a fragment identifier in a URI reference.

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="text/xml" href="#style1"?>
<!DOCTYPE doc SYSTEM "doc.dtd">
<doc>
<head>
<xsl:stylesheet id="style1"
                version="2.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format">
<xsl:import href="doc.xsl"/>
<xsl:template match="id('foo')">
  <fo:block font-weight="bold"><xsl:apply-templates/></fo:block>
</xsl:template>
<xsl:template match="xsl:stylesheet">
  <!-- ignore -->
</xsl:template>
</xsl:stylesheet>
</head>
<body>
<para id="foo">
...
</para>
</body>
</doc>
NOTE: A stylesheet module that is embedded in the document to which it is to be applied or that may be included or imported into a stylesheet that is so embedded 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="text/xml" in the xml-stylesheet processing instruction to denote an XSLT stylesheet. This usage was defined provisionally in XSLT 1.0, and is subject to change. In the absence of a registered media type for XSLT stylesheets, some vendors' products have adopted different conventions, notably type="text/xsl".
NOTE: Support for the xml-stylesheet processing instruction is not a requirement for conformance with this Recommendation.

2.10 Importing Schema Components

<!-- Category: declaration -->
<xsl:import-schema
  namespace = uri-reference
  schema-location = uri-reference />

The xsl:import-schema declaration is used to identify schema components (that is, definitions of types) which need to be available statically, that is, before any source document is available. Every type name used statically within the stylesheet (including type names used within XPath expressions) must be defined in an imported schema. The declaration imports the element and attribute declarations and type definitions from the schema, and maps them to types in the XPath data model according to rules defined in [].

Ed. Note: Whether or not the locally declared elements and attributes of a schema are imported is an open issue.

The namespace and schema-location attributes are both optional. At least one of them must be present, and it is permissible to supply both.

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 schema-location attribute gives the URI of a location where a schema document or other resource containing the required definitions may be found. An XSLT processor must have the capability to process an XML Schema that exists at this location in the form of a source XML document; implementations may also be able to access equivalent information held in other forms, for example a compiled XML Schema, or type information expressed using some other schema language.

[ERR016] It is a static error if the processor is not able to locate a schema using the namespace and/or schema-location attributes , or if the document that it locates is neither a valid XML Schema nor any other resource that the implementation can process.

[ERR017] It is a static error if two xsl:import-schema declarations yield multiple definitions for the same named type, even if the definitions are consistent with each other.

The use of a namespace in an xsl:import-schema declaration does not by itself make the namespace available for use in the stylesheet. If names from the namespace are used within the stylesheet, a prefix must be associated with the namespace by means of a namespace declaration, in the normal way.

The precise way in which an implementation uses the namespace and/or schema-location attributes to locate schema definitions is implementation-defined.

3 Data Model

The data model used by XSLT is as defined in [Data Model], with the additions described in this section. XSLT operates on source, result and stylesheet documents using the same data model.

Features of a source XML document that are not represented in the tree defined by the data model 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.

Issue (schema-explanation): We need to say something here about schemas and DTDs.

3.1 Parentless Nodes

The data model defined in [Data Model] allows a node to be part of a tree whose root is a node other than a document node.

XSLT does not allow nodes with no parent (other than document nodes) to be created, other than transiently: a node created during the course of XSLT processing is not available for further processing until it has been attached to a tree that is rooted at a document node. However, implementations may allow parentless nodes to be supplied as input to the transformation, for example as parameters to the stylesheet.

3.2 Document Node Children

Ed. Note: This section can be removed when it is confirmed that the data model permits "well-balanced" trees. At the time of writing, this is still an open issue in the data model (Issue 0041).

The normal restrictions on the children of the document node are relaxed for the result tree and for temporary trees constructed during the evaluation of the stylesheet. The document node of such a tree may have any sequence of nodes as children that would be possible for an element node. In particular, it may have text node children, and any number of element node children. When written out using the XML output method (see [18 Serialization]), it is possible that a result tree will not be a well-formed XML document; however, it will always be a well-formed external general parsed entity.

For example, a stylesheet might produce the following output. This is a well-formed external general parsed entity, but it is not a well-formed XML document:

<?xml version="1.0" encoding="iso-8859-1"?>A <i>fine</i> mess!

When a source tree is created by parsing a well-formed XML document, the document node of the source tree will automatically satisfy the normal restrictions of having no text node children and exactly one element child. When a source tree is created in some other way, for example by using the DOM, the usual restrictions are relaxed for the source tree as for the result tree.

3.3 Unparsed Entities

Ed. Note: Unparsed entities don't currently appear in the data model, though we have asked for them to be added. This section can be deleted when the Data Model is updated to support unparsed entities.

The document node has a mapping that gives the URI for each unparsed entity declared in the document's DTD. The URI is generated from the system identifier and public identifier specified in the entity declaration. The processor may use the public identifier to generate a URI for the entity instead of the URI specified in the system identifier. If the processor does not use the public identifier to generate the URI, it must use the system identifier; if the system identifier is a relative URI, it must be resolved into an absolute URI using the URI of the resource containing the entity declaration as the base URI [RFC2396].

Issue (public-identifiers): There is a requirement to add support for the public identifier of unparsed entities. The Working Group intends to add this feature before final publication of XSLT 2.0.

3.4 Whitespace Stripping

Issue (whitespace-and-schema): If an element has element content, as defined in the schema or DTD, the default should be to strip whitespace nodes rather than preserving them.

The source document supplied as input to the transformation process may contain whitespace nodes (that is, text nodes consisting solely of whitespace characters) that are of no interest, and that do not need to be retained by the transformation. Conceptually, such whitespace nodes may be removed from the tree before the transformation commences. This process is referred to as whitespace stripping. The source tree itself must not be modified: the processor may implement whitespace stripping either by creating a copy of the tree from which the whitespace nodes have been removed, or by working on a virtual tree in which the whitespace nodes are treated as if they were absent.

The stripping process takes as input a set of element names whose child whitespace nodes must be preserved. The stripping process is applied to both stylesheets and source documents, but the set of whitespace-preserving element names is determined differently for stylesheets and for source documents.

NOTE: Where multiple transformations are to be applied to the same source document, a useful optimization is to do the whitespace stripping only once. Implementations may therefore allow whitespace stripping to be controlled as a separate operation from the rest of the transformation process.

A text node is preserved if any of the following apply:

Otherwise, the text node is stripped.

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

NOTE: This implies that if an xml:space attribute is specified on a literal result element, it will be included in the result.

For stylesheets, the set of whitespace-preserving element names consists of just xsl:text.

Processing instructions and comments in a stylesheet module are ignored: the stylesheet module is treated as if the processing instructions and comments were not there. This also means that sibling text nodes that are separated by a processing instruction or comment in a stylesheet module are concatenated into a single text node; and a text node is classified as a whitespace text node for the purpose of whitespace stripping only after this concatenation has taken place.

The content model for some XSLT elements (for example xsl:stylesheet and xsl:choose) does not permit text nodes as children of these elements. If the xml:space="preserve" attribute is used to suppress the stripping of whitespace text nodes within such elements, then any whitespace used for the layout of such elements will be retained in the stylesheet tree in the form of whitespace text nodes. Such text nodes must not be reported as an error. [ERR018] Within an XSLT element that is required to be empty, any content other than comments or processing instructions, including any whitespace-only text node preserved using the xml:space="preserve" attribute, is a static error.

<!-- Category: declaration -->
<xsl:strip-space
  elements = tokens />

<!-- Category: declaration -->
<xsl:preserve-space
  elements = tokens />

For source documents, 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 amongst 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; an element name matches an xsl:strip-space or xsl:preserve-space element if it matches one of the NameTests. An element matches a NameTest if and only if the NameTest 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. This is determined in the same way as with template rules:

[ERR019] It is an dynamic error if this leaves more than one match. The processor must either signal the error, of must recover by choosing, from amongst the matches that are left, the one that occurs last in declaration order.

NOTE: A source document is supplied as input to the XSLT processor in the form of a tree. Nothing in this specification states that this tree must be built by parsing an XML document; nor does it state that the application that constructs the tree is required to treat whitespace in any particular way. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the processor. In particular, the processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.

Issue (strip-comments-and-PIs): Should we provide a declaration to control stripping of comments and PIs in the source document? There is a flag in the data model to permit this.

3.5 Namespace Fixup

Ed. Note: The process of namespace fixup would ideally be described along with the node construction functions defined in the XPath 2.0 data model.

Issue (shared-namespace-node-fixup): This section needs to be revised if namespace nodes are to be held at document level.

In a tree constructed by parsing an XML document, the following constraints relating to namespace nodes will be satisfied:

However, when a tree is being constructed as the result of an XSLT transformation, these constraints might not be satisfied unless special action is taken. In particular, since xsl:element and xsl:attribute instructions do not create namespace nodes, they will often cause these constraints not to be satisfied. The process of namespace fixup modifies a tree by adding namespace nodes so that it satisfies all constraints affecting namespace nodes. What namespace nodes are added and where they are added by namespace fixup is implementation-dependent, provided that the resulting tree satisfies the constraints and provided that all namespaces nodes in the resulting tree are allowable, where a namespace node is allowable for an element E if any of the following conditions applies:

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

Namespace fixup is performed in two situations:

There is no requirement to perform namespace fixup for the principal source document, nor for any document loaded using the document function, nor for any document supplied as the value of a global parameter, nor for any document returned by an extension function. [ERR020] It is a dynamic error if such a document does not already satisfy the constraints listed above . The processor may signal the error, or may recover by performing namespace fixup, or may produce implementation-dependent results.

3.6 Disable Output Escaping

If an implementation supports the disable-output-escaping attribute of xsl:text and xsl:value-of (see [18.5 Disabling Output Escaping]), then the data model for trees constructed by the processor is augmented with a boolean value representing the value of this property.

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

This property is preserved when a text node is copied using xsl:copy or xsl:copy-of.

NOTE: There are many ways an implementation can avoid the overhead of actually storing a boolean flag with every character.

Issue (d-o-e-on-attributes): Should we allow disable-output-escaping on xsl:attribute?

Issue (restrict-d-o-e): It is proposed that we should restrict the use of disable-output-escaping so it can only be used on a final result tree. This would avoid distorting the data model.

3.7 External Objects

The type system described in [Data Model] is extended to allow an extension function to return an object whose type is unknown to the XPath or XSLT processor. Such an object is referred to as an external object. For details, see [16.1.3 External Objects].

4 Syntactic Constructs

4.1 Qualified Names

The name of an internal XSLT object, specifically a named template (see [7.1 Named Templates]), a mode (see [5.6 Modes]), an attribute set (see [7.2 Named Attribute Sets]), a key (see [14.3 Keys]), a named sort specification (see [12.4 Using Named Sort Specifications]), a decimal-format (see [14.4 Number Formatting]), a variable or parameter (see [6 Variables and Parameters]), a stylesheet function (see [7.3 Stylesheet Functions]), or a named output definition (see [18 Serialization]), is specified as a QName.

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

An expanded-QName is a pair of values containing a namespace URI and a local name. A QName is expanded by replacing the namespace prefix with the corresponding namespace URI, from the namespace declarations that are in scope at the point where the QName is written. Two expanded-QNames are equal if the namespace URIs are the same and the local names are the same.

QNames always occur either 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.

Issue (leading-colon-in-qname): The current XPath grammar allows a QName to contain a leading colon. This leading colon is not considered part of the QName as far as XSLT is concerned, and is not permitted in contexts other than an XPath expression.

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 (as defined by a namespace declaration of the form xmlns="some.uri") is not used for unprefixed names.

In the case of an unprefixed QName used as a NameTest within an XPath expression (see [4.2 Expressions]) or within a pattern (see [4.3 Patterns]), or in the elements attribute of the xsl:strip-space and xsl:preserve-space instructions, the namespace to be used in expanding the QName may be specified by means of the [xsl:]default-xpath-namespace attribute, as specified in [4.4 Unprefixed Names in Expressions and Patterns].

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

[ERR022] In the case of a QName produced by evaluating an XPath expression, it is a dynamic error if the defining element has no namespace node whose name matches the prefix of the QName. The error is a dynamic error even if the value of the expression is known statically, for example if the QName is written as a string literal. The required action depends on the defining element.

4.2 Expressions

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

An expression must match the XPath production Expr.

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

[ERR023] It is a static error if the value of such an attribute, or the text between curly braces in an attribute value template, does not match the XPath production Expr, 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.

The context within a stylesheet where an XPath expression may appear determines the required type of the expression. The required type indicates the data type of value that the expression is expected to return.

[ERR024] It is a type error if an XPath expression contains a type error, or if the type of the XPath expression is incompatible with the required type. The processor must either signal a type error as a static error, or must attempt to recover by converting the result of the expression to the required type using the standard type conversion rules; if conversion is not possible under these rules, the processor must signal a dynamic error

The context for evaluation of an XPath expression is determined according to the following rules. The context has two parts: the static context, and the dynamic expression evaluation context.

The static context depends on the element in the stylesheet that contains the attribute holding the XPath expression ("the containing element") as follows:

The evaluation context, which includes the focus, is determined as follows:

Where the containing element is an instruction or a literal result element, the focus is established as follows. In other cases, the rules are given for the specific containing element.

4.3 Patterns

A template rule identifies the nodes to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see [9 Numbering]), for grouping (see [13 Grouping]), and for declaring keys (see [14.3 Keys]).

A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions. As explained in detail below, a node matches a pattern if the node can be selected by evaluating this expression with respect to some possible context.

Here are some examples of patterns:

Issue (type-matching-in-patterns): The current syntax for matching elements of a particular type is cumbersome, for example match="*[. instance of element us-address of type address]".

[ERR026] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern. 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 AxisStepExpr that uses only the child or attribute axes. Patterns may also use the // operator, and they may start with an id or key function call provided its arguments are string literals. Predicates in a pattern (the construct enclosed between square brackets) can contain arbitrary XPath expressions in the same way as predicates in a path expression.

If a pattern occurs in part of the stylesheet where backwards compatible behavior is enabled (see [2.6 Backwards-Compatible Processing]), then the pattern is restricted to use the syntax for patterns defined in XSLT 1.0, and will match a node if and only if it would have matched that node under the rules defined in XSLT 1.0.

Patterns
[1]   Pattern   ::=   PathPattern
| Pattern ('|' | 'union') PathPattern
[2]   PathPattern   ::=   RelativePathPattern
| '/' RelativePathPattern?
| '//' RelativePathPattern
| IdKeyPattern (('/' | '//') RelativePathPattern)?
[3]   RelativePathPattern   ::=   PatternStep (('/' | '//') RelativePathPattern)?
[4]   PatternStep   ::=   PatternAxis? NodeTest ( '[' Expr ']' )*
[5]   PatternAxis   ::=   ('child' '::' | 'attribute' '::' | '@')
[6]   IdKeyPattern   ::=   'id' '(' StringLiteral ')'
| 'key' '(' StringLiteral ',' StringLiteral ')'

The constructs NodeTest, StringLiteral, and Expr are part of the XPath expression language, and are defined in [XPath 2.0].

The meaning of a pattern is defined formally as follows. To determine whether a node N matches a pattern PAT, evaluate the expression //(PAT) with a singleton focus based on N. If the result is a sequence of nodes that includes N, then node N matches the pattern; otherwise node N does not match the pattern. This expression is constructed by textually inserting the pattern PAT exactly as written in the stylesheet.

For example, p matches any p element, because a p element will always be present in the result of evaluating the expression //(p). Similarly, / matches a document node, and only a document node, because the result of the expression //(/) when applied using a particular document as context document returns only the document node of that document.

NOTE: Although the semantics of patterns are specified formally in terms of expression evaluation, it is possible to understand pattern matching using a different model. In a pattern, | indicates alternatives; a pattern with one or more | separated alternatives matches if any one of the alternatives matches. A 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 item[1]. This matches any node selected by the expression //(item[1]): that is, any item element that is the first item child of its parent.

The pattern node() matches all nodes selected by the expression //(node()), that is, all element, text, comment, and processing instruction nodes. It does not match attribute or namespace nodes because the expression does not select nodes using the attribute or namespace axes.

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 semantics by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.

4.4 Unprefixed Names in Expressions and Patterns

The attribute [xsl:]default-xpath-namespace (see [2.3 Standard Attributes]) may be used on an element in the stylesheet to define the namespace URI that will be used for an unprefixed name used as a NameTest within a step of an XPath PathExpression or an XSLT Pattern or in the elements attribute of the xsl:strip-space or xsl:preserve-space instructions, where the NameTest occurs in an attribute of that stylesheet element or an attribute of a descendant of that stylesheet element. The value of the attribute is the namespace URI to be used.

This default namespace URI applies only to a NameTest applied to an axis whose principal node type is elements: it does not apply when the step is using the attribute or namespace axis. The default namespace URI for such a name is the value of the [xsl:]default-xpath-namespace attribute on the innermost ancestor element that has such an attribute, considering all ancestor elements of the attribute containing the XPath expression or XSLT pattern. The [xsl:]default-xpath-namespace attribute must be in the XSLT namespace only if its parent element is not in the XSLT namespace.

In the absence of this attribute, an unqualified NameTest (that is, a NameTest that is an NCName) matches an expanded-QName whose namespace URI is null: the default namespace (as defined by an xmlns="some-uri" declaration) is not used.

The default-xpath-namespace only affects unqualified names (names containing no colon) used in a NameTest. It does not affect other names, for example function names, variable names, or names used as arguments to the key or system-property functions.

Issue (runtime-namespace-selection): The default-xpath-namespace facility as proposed here doesn't meet the requirement to match multiple namespaces, or to decide at run-time which namespace to match - as exemplified by the XHTML scenario.

Ed. Note: Do we need to add this attribute to all element proformas and to the DTD?

4.5 Attribute Value Templates

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 braces ({}).

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 braces ({}). A fixed part may contain any characters, except that a left curly brace must be written as {{ and a right curly brace must be written as }}.

NOTE: An expression within a variable part may contain an unescaped curly brace within a StringLiteral.

Issue (comments-in-AVTs): Should XPath comments (which are delimited by curly braces) be prohibited within an attribute value template?

[ERR027] It is a static error if a left curly brace appears in an attribute value template without a matching right curly brace.

[ERR028] It is a static error if the string contained between matching curly braces in an attribute value template does not match the XPath production Expr.

[ERR029] It is a static error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace. A right curly brace inside a StringLiteral in an expression is not recognized as terminating the expression.

The required type of each expression within an attribute value template is xsd:string.

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 braces ({{ or }}) by the corresponding single curly brace. The expansion of a variable part is obtained by evaluating the enclosed XPath expression and converting the resulting value to a string as if by a call to the string function.

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

NOTE: Not all attributes are interpreted as attribute value templates. Attributes whose value is an expression or pattern, attributes of top-level elements and attributes that refer to named XSLT objects are not interpreted as attribute value templates. In addition, xmlns attributes are not interpreted as attribute value templates; it would not be conformant with the XML Namespaces Recommendation to do this. Two exceptions are the xsl:output and xsl:principal-result-document declarations: although these are top-level elements, some of their attributes are interpreted as attribute value templates.

The following example creates an img result element from a photograph element in the source; the value of the src attribute of the img element is computed from the value of the image-dir variable and the string-value of the href child of the photograph element; the value of the width attribute of the img element is computed from the value of the width attribute of the size child of the photograph element:

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

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

Curly braces are not recognized recursively inside expressions. For example:

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

is not allowed. Instead, use simply:

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

4.6 Content Constructors

NOTE: The term content 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 content constructor as something that can be evaluated to return a sequence of nodes; what happens to these nodes depends on the containing instruction.

Many XSLT elements (including literal result elements) are defined to take as their content a content constructor.

A content constructor is a sequence of nodes in the stylesheet that, when evaluated, constructs and returns a sequence of new nodes suitable for adding to the result tree. This sequence is referred to below as the result sequence.

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

The node sequences produced by each node in the content constructor are concatenated to form a single result sequence. This concatenation retains the order of the nodes within the content constructor: if while evaluating a content constructor, node M is constructed by instruction I, and node N is constructed by a different instruction J, then N will appear after M in the result sequence if and only if J follows I in document order. This does not mean that the nodes in a content constructor must be evaluated sequentially: on the contrary, they may be evaluated in any order, or in parallel, provided that their results are assembled in the correct sequence on completion.

If the result sequence contains two or more adjacent text nodes, these adjacent text nodes are concatenated to form a single text node.

The result sequence will never contain a document node. [ERR030] It is an dynamic error if an extension instruction attempts to return a sequence containing a document node. The processor must signal the error.

[ERR031] It is a dynamic error if the result sequence (after concatenating the results of individual instructions) contains a namespace node that is preceded in the sequence by a node that is not a namespace node. The processor must either signal the error, or must recover by ignoring the offending namespace node.

Issue (must-namespaces-precede-attributes): It appears that several implementations currently allow a namespace node to be added after adding attributes (using xsl:copy ). This seems convenient for the user, and the Working Group is inclined to allow it. To achieve this, we will need to define some conflict resolution if the namespace clashes with an existing attribute.

[ERR032] It is a dynamic error if the result sequence (after concatenating the results of individual instructions) contains an attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node. The processor must either signal the error, or must recover by ignoring the offending attribute node.

What actually happens to the nodes in the result sequence depends on the element containing the content constructor. Some elements, such as xsl:if, simply return the sequence of nodes, which are added to the result of the content constructor containing the xsl:if instruction. Other elements, such as xsl:element, xsl:comment, and xsl:variable, construct a new node, and use the value returned by the content constructor to create the children or the text content of the new node.

Specifically:

Issue (use-constructor-semantics): The above text should be rewritten to provide a formal mapping to the constructor functions defined in the data model.

Issue (sequences-in-XSLT): Should we consider extending XSLT to allow construction of arbitrary sequences?

5 Template Rules

5.1 Processing Model

The xsl:apply-templates instruction takes as input a sequence of nodes in the source tree, and produces as output a sequence of nodes which are typically added to the result tree. Each node in the input sequence is processed by finding a template rule whose pattern matches that node. If there is more than one, the best among them is chosen; if there is none, a built-in template rule is used. The content constructor that forms the body of the chosen template rule is evaluated to produce a sequence of nodes. The resulting sequences of nodes (one for each node in the input sequence) are then concatenated, to form a single sequence. They are concatenated retaining the order of the nodes in the original input sequence, unless a different order is requested using xsl:sort. The final concatenated sequence of nodes forms the result of the xsl:apply-templates instruction: what happens to it next depends on the context in which the xsl:apply-templates instruction appeared.

Ed. Note: Given that the above paragraph explains an important concept, it could be more clearly written.

The stylesheet as a whole is evaluated by evaluating an implicit xsl:apply-templates instruction with the document node (that is, the root) of the principal source document as the (singleton) input node sequence.

NOTE: An implementation may also allow processing to start with some different node sequence, using implementation-defined mechanisms.

A content constructor will often contain an xsl:apply-templates instruction selecting the children of the node as the input sequence for processing. This will cause a template rule to be invoked for each of these children. The nodes constructed by the content constructor for a child node can be added as children to the nodes constructed by the content constructor for their parent. Thus it is possible to construct a result tree whose structure corresponds to the structure of the source tree.

Implementations are free to process the source document in any way that produces the same result as if it were processed using this processing model.

5.2 Defining Template Rules

<!-- Category: declaration -->
<xsl:template
  match = pattern
  name = qname
  priority = number
  mode = qname>
  <!-- Content: (xsl:param*, content-constructor) -->
</xsl:template>

A template rule is specified with the xsl:template element. The match attribute is a Pattern that identifies the source node or nodes to which the rule applies. The match attribute is required unless the xsl:template element has a name attribute (see [7.1 Named Templates]). It is an static error for the value of the match attribute to contain a Variable. The result of applying the template rule is the result of evaluating the content constructor contained in the xsl:template element, with the matching node used as the context node

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 formatting object with a font-weight property of bold.

<xsl:template match="emph">
  <fo:wrapper font-weight="bold">
    <xsl:apply-templates/>
  </fo:wrapper>
</xsl:template>
NOTE: Examples in this document use the fo: prefix for the namespace http://www.w3.org/1999/XSL/Format, which is the namespace of the formatting objects defined in [XSL Formatting Objects].

As described next, the xsl:apply-templates element recursively processes the children of the source element.

5.3 Applying Template Rules

<!-- Category: instruction -->
<xsl:apply-templates
  select = node-sequence-expression
  mode = qname>
  <!-- Content: (xsl:sort | xsl:with-param)* -->
</xsl:apply-templates>

This example creates a block for a chapter element and then processes its immediate children.

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

In the absence of a select attribute, the xsl:apply-templates instruction processes all of the children of the context node, including text nodes. [ERR036] It is a dynamic error if the context item is not a node. The processor must either signal the error, or must recover by returning an empty sequence.

Whitespace text nodes that have been stripped as specified in [3.4 Whitespace Stripping] will not be processed. If stripping of whitespace nodes has not been enabled for an element, then all whitespace in the content of the element will be processed as text, and thus whitespace between child elements will count in determining the position of a child element as returned by the position function.

A select attribute can be used to process nodes 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 (which can contain zero, one, or more nodes). The selected nodes are processed in the order of this sequence, unless a sorting specification is present (see [12 Sorting]).

[ERR037] It is a dynamic error if the sequence returned by the select expression contains an item that is not a node. The processor must either signal the error, or must recover by ignoring the offending items.

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.

Issue (terminology-valid): There are various places in the specification where the word "valid" is used in a sense other than XML (or schema) validity.

The following example processes all of the author children of the author-group:

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

The following example processes all of the given-names of the authors that are children of author-group:

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

This example processes all of the heading descendant elements of the book element.

<xsl:template match="book">
  <fo:block>
    <xsl:apply-templates select=".//heading"/>
  </fo:block>
</xsl:template>

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>

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>
NOTE: 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.
NOTE: Typically, xsl:apply-templates is used to process only 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.

5.4 Conflict Resolution for Template Rules

It is possible for a node in a source document to match more than one template rule. The template rule to be used is determined as follows:

  1. First, all matching template rules that have lower import precedence than the matching template rule or rules with the highest import precedence are eliminated from consideration.

  2. Next, all matching template rules that have lower priority than the matching template rule or rules with the highest priority are eliminated from consideration. The priority of a template rule is specified by the priority attribute on the template rule. [ERR038] The value of this must be a real number (positive or negative), matching the production NumericLiteral with an optional leading minus sign (-). [ERR039] If an xsl:template element does not have a match attribute, then it must not have a priority attribute.

    If no priority attribute is specified on the xsl:template element, the default priority is computed as follows:

    • If the pattern contains multiple alternatives separated by |, then it is treated equivalently to a set of template rules, one for each alternative. Note, however, that it is not an error if a node matches more than one of the alternatives.

    • If the pattern has the form of a QName optionally preceded by a PatternAxis or has the form processing-instruction(StringLiteral) optionally preceded by a PatternAxis, then the priority is 0.

    • If the pattern has the form NCName:* or *:NCName, optionally preceded by a PatternAxis, then the priority is -0.25.

    • Otherwise, if the pattern consists of just a NodeTest optionally preceded by a PatternAxis, then the priority is -0.5.

    • Otherwise, 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 with a particular type and a particular expanded-QName) has priority 0. The next less specific kind of pattern (a pattern that tests for a node with a particular type and an expanded-QName with a particular namespace URI) has priority -0.25. Patterns less specific than this (patterns that just tests for nodes with particular types) have priority -0.5. Patterns more specific than the most common kind of pattern have priority 0.5. 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 item. Therefore, to achieve clarity in a stylesheet it is good practice to allocate explicit priorities.

[ERR040] It is a dynamic error if this leaves more than one matching template rule. The processor must either signal the error, or must recover by choosing, from amongst the matching template rules that are left, the one that occurs last in declaration order.

5.5 Overriding Template Rules

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

A template rule that is being used to override a template rule in an imported stylesheet (see [5.4 Conflict Resolution for Template Rules]) can use the xsl:apply-imports element to invoke the overridden template rule.

At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen by matching a pattern, the template rule becomes the current template rule for the evaluation of the rule's content constructor. When an xsl:for-each or xsl:for-each-group instruction is evaluated, the current template rule becomes null for the evaluation of the content of the xsl:for-each or xsl:for-each-group instruction.

The current template rule is not affected by invoking named templates (see [7.1 Named Templates]), named attribute sets (see [7.2 Named Attribute Sets]), nor stylesheet functions (see [7.3 Stylesheet Functions]). While evaluating a global variable or parameter (see [6.2 Global Variables and Parameters]) the current template rule is null.

xsl:apply-imports searches for a template rule that matches the context node, and whose mode is the same as the current template rule's mode (see [5.6 Modes]). In choosing a template rule, it uses the usual criteria such as the priority and import precedence of the template rules, but it 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.

If no matching template rule is found that satisfies these criteria, the built-in template rule for the node type is used (see [5.7 Built-in Template Rules]).

[ERR041] It is an error if the xsl:apply-imports instruction is evaluated when the context item is not a node. The processor must either signal the error, or must recover by returning an empty sequence.

An xsl:apply-imports element may use xsl:with-param child elements to pass parameters to the chosen template rule (see [7.1.1 Passing Parameters to Templates]).

[ERR042] It is a dynamic error if xsl:apply-imports is evaluated when the current template rule is null. The processor must signal the error.

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>

5.6 Modes

Modes allow a node in the 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 [14.1 Multiple Source Documents]) or when processing temporary trees (see [6 Variables and Parameters])

Both xsl:template and xsl:apply-templates have an optional mode attribute. The value of the mode attribute is a QName, which is expanded as described in [4.1 Qualified Names]. If an xsl:apply-templates element has a mode attribute, then it applies only to those template rules from xsl:template elements that have a mode attribute with the same value; if an xsl:apply-templates element does not have a mode attribute, then it applies only to those template rules from xsl:template elements that do not have a mode attribute.

[ERR043] If an xsl:template element does not have a match attribute, then it is a static error if it has a mode attribute.

5.7 Built-in Template Rules

There is a built-in template rule to allow recursive processing to continue in the absence of a successful pattern match by an explicit template rule in the stylesheet. This template rule applies to both element nodes and the document node. The following shows the equivalent of the built-in template rule:

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

There is also a built-in template rule for each mode, which allows recursive processing to continue in the same mode in the absence of a successful pattern match by an explicit template rule in the stylesheet. This template rule applies to both element nodes and the document node. The following shows the equivalent of the built-in template rule for mode m.

<xsl:template match="*|/" mode="m">
  <xsl:apply-templates mode="m"/>
</xsl:template>

The built-in rule for document nodes and element nodes is equivalent to calling xsl:apply-templates with no select attribute. If the built-in rule was invoked in a non-default mode, that mode is used in the implicit xsl:apply-templates instruction. If the built-in rule was invoked with parameters, those parameters are again used in the implicit xsl:apply-templates instruction.

For example, suppose the stylesheet contains the following instruction:

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

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

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

There is also a built-in template rule for text and attribute nodes that copies text through:

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

The built-in template rule for processing instructions and comments is to do nothing.

<xsl:template match="processing-instruction()|comment()"/>

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 the only template rule that is applied for namespace nodes.

The built-in template rules for text, attribute, comment, processing-instruction, and namespace nodes for a specific mode are the same as the rules shown above that apply where no mode is specified.

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.

6 Variables and Parameters

<!-- Category: declaration -->
<!-- Category: instruction -->
<xsl:variable
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:variable>

<!-- Category: declaration -->
<xsl:param
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:param>

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

A variable is a name that may be bound to a value. The value to which a variable is bound (the value of the variable) can be an object of any of the types that can be returned by expressions. There are two elements that can be used to bind variables: xsl:variable and xsl:param. The difference is that the value specified on the xsl:param variable is only a default value for the binding; when the template or stylesheet within which the xsl:param element occurs is invoked, parameters may be passed that are used in place of the default values.

Both xsl:variable and xsl:param have 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 [4.1 Qualified Names].

Both xsl:variable and xsl:param have an optional type attribute, which specifies the required type of the variable. The value of the type attribute is a SequenceType, as defined in [XPath 2.0]. The result of evaluating the expression contained in the select attribute, or in the case of xsl:param, the value supplied by the caller, is referred to as the supplied value of the variable. [ERR044] If the type attribute is specified, then the supplied value of the variable is converted to the required type, using the same rules that apply when converting a supplied value to the required type for an argument in a function call. These rules are specified in [XPath 2.0]. It is a type error if this conversion fails.

If the type attribute is omitted, the supplied value of the variable is used directly, and no conversion takes place. The effect is the same as if the type were specified as item*.

Issue (variable-validation): Is "validate" invoked automatically when xsl:variable is used to create a temporary tree, and a type is specified? How does this work, given that the type will be a document type, not an element type? What happens if validation fails (and what does it mean for validation to fail)? Should it be possible to request lax validation?

For any use of these variable-binding elements, there is a region of the stylesheet tree within which the binding is visible. The set of variable bindings in scope for an expression consists of those bindings that are visible at the point in the stylesheet where the expression occurs.

6.1 Values of Variables and Parameters

A variable-binding element can specify the supplied value of the variable in three alternative ways.

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

NOTE: 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="item[$n]"/>
This will output the value of the first item 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="item[$n]"/>
or
<xsl:variable name="n">2</xsl:variable>
...
<xsl:value-of select="item[position()=$n]"/>
or
<xsl:variable name="n" type="xsd:int">2</xsl:variable>
...
<xsl:value-of select="item[$n]"/>

6.2 Global Variables and Parameters

Both xsl:variable and xsl:param are allowed as top-level elements. A top-level variable-binding element declares a global variable that is visible everywhere (except where it is shadowed by another binding). A top-level xsl:param element declares a global parameter to the stylesheet; XSLT does not define the mechanism by which parameters are passed to the stylesheet.

If a stylesheet contains more than one binding for a global variable or parameter of a particular name, then the binding with the highest import precedence is used. [ERR046] 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.

For a global variable or parameter, the expression or content constructor specifying the variable value is evaluated with a singleton focus based on the document node of the principal source document.

The following example declares a global variable para-font-size, which it references in an attribute value template.

<xsl:variable name="para-font-size" type="xsd:string">12pt</xsl:variable>

<xsl:template match="para">
 <fo:block font-size="{$para-font-size}">
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

6.3 Circular Definitions

If the expression or content 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. If it is impossible to do this for all global variable definitions, then a circularity is said to exist.

For example the following two declarations create a circularity:

<xsl:variable name="x" select="$y+1"/>

<xsl:variable name="y" select="$x+1"/>

The definition of a global variable can be circular even if no other variable is involved. For example the following two declarations (see [7.3 Stylesheet Functions] for an explanation of the xsl:function element) also create a circularity:

<xsl:variable name="x" select="f()"/>

<xsl:function name="f">
  <xsl:result select="$x"/>
</xsl:function>

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>

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:result select="key('k', $arg1)"/>
</xsl:function>

<xsl:key name="k" match="item[@code=$x]" use="@desc"/>

[ERR047] In general, a circularity in a stylesheet is a dynamic error. The processor must signal the 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 default value for a parameter, but it returns a result that does not require the default value to be evaluated. It is implementation-dependent whether the default value is actually evaluated, and it is therefore implementation-dependent whether the circularity is signaled as an error:

<xsl:variable name="x" select="f(1)/>

<xsl:function name="f">
  <xsl:param name="a" select="$x"/>
  <xsl:result select="$a"/>
</xsl:function>

Circularities usually involve global variables or parameters, but they can also exist between key definitions (see [14.3 Keys]), between named attribute sets (see [7.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 a global variable that uses 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 [7.3 Stylesheet Functions]) and named templates (see [7.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.

6.4 Local Variables and Parameters

As well as being allowed as top-level elements, both xsl:variable and xsl:param are also allowed in content constructors and within the xsl:function element (see [7.3 Stylesheet Functions]. Such a variable or parameter is known as a local variable or parameter.

The result of evaluating a local xsl:variable or xsl:param element (that is, the contribution it makes to the result of the content constructor it is part of) is an empty sequence.

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 a static error if a binding established by a local xsl:variable or xsl:param element shadows another binding established by another local xsl:variable or xsl:param. 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. Thus, the following is an error:

<xsl:template name="foo">
  <xsl:param name="x" select="1"/>
  <xsl:variable name="x" select="2"/>
</xsl:template>

However, the following is allowed:

<xsl:param name="x" select="1"/>
<xsl:template name="foo">
  <xsl:variable name="x" select="2"/>
</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.

6.5 Range Variables

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

Examples of range variables occur in expressions such as:

<xsl:value-of select="sum(for $x in //item return $x/price * $x/qty)"/>

or:

<xsl:if test="some $i in authors/author satisfies substring($i, 1, 1) = 'A'"/>

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.

Issue (xpath-variable-shadowing): Can variables declared within an XPath 2.0 expression shadow variables declared at XSLT level?

7 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 [7.1 Named Templates]), named attribute sets (see [7.2 Named Attribute Sets]) and stylesheet functions (see [7.3 Stylesheet Functions]).

7.1 Named Templates

<!-- Category: instruction -->
<xsl:call-template
  name = qname>
  <!-- Content: xsl:with-param* -->
</xsl:call-template>

Templates can be invoked by name. An xsl:template element with a name attribute specifies a named template. The value of the name attribute is a QName, which is expanded as described in [4.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 element 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 do not affect whether the template is invoked by an xsl:call-template element. Similarly, the name attribute on an xsl:template element does not affect whether the template is invoked by an xsl:apply-templates element.

[ERR048] It is a static error if a stylesheet contains more than one template with the same name and same import precedence.

The result of evaluating an xsl:call-template instruction is the node sequence produced by evaluating the content constructor contained in the associated xsl:template element.

7.1.1 Passing Parameters to Templates

<xsl:with-param
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:with-param>

Parameters are passed to templates using the xsl:with-param element. The required name attribute specifies the name of the 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 [4.1 Qualified Names].

xsl:with-param is allowed within xsl:call-template, xsl:apply-templates and xsl:apply-imports. It is a static error if a single xsl:call-template, xsl:apply-templates or xsl:apply-imports element contains more than one xsl:with-param element with the same name.

The value of the parameter is specified in the same way as for xsl:variable and xsl:param. The focus used for computing the value specified by xsl:with-param element is the same as that used for the xsl:apply-templates, xsl:apply-imports, or xsl:call-template element within which it occurs. It is not an error to pass a parameter x to a template that does not have an xsl:param element for x; the parameter is simply ignored.

The type attribute is used in the same way as for the xsl:variable element. The supplied value is converted as necessary to the required type. This then defines the actual value of the parameter that is supplied to the called template. If necessary, this value may be converted once again to the type specified in the corresponding xsl:param element within the named template definition.

This example defines a named template for a numbered-block with an argument 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>
NOTE: Arguments to stylesheet functions are supplied as part of an XPath function call: see [7.3 Stylesheet Functions]

7.2 Named Attribute Sets

<!-- Category: declaration -->
<xsl:attribute-set
  name = qname
  use-attribute-sets = qnames>
  <!-- Content: xsl:attribute* -->
</xsl:attribute-set>

The xsl:attribute-set element defines a named set of attributes. The name attribute specifies the name of the attribute set. The value of the name attribute is a QName, which is expanded as described in [4.1 Qualified Names]. The content of the xsl:attribute-set element consists of zero or more xsl:attribute elements that specify the attributes in the set.

Attribute sets are used by specifying a use-attribute-sets attribute on the xsl:element, xsl:copy (see [8.8 Copying Nodes from the Source Tree to the Result Tree]) or xsl:attribute-set elements. The value of the use-attribute-sets attribute is a whitespace-separated list of names of attribute sets. Each name is specified as a QName, which is expanded as described in [4.1 Qualified Names]. Specifying a use-attribute-sets attribute is equivalent to adding xsl:attribute elements for each of the attributes in each of the named attribute sets to the beginning of the content of the element with the use-attribute-sets attribute, in the same order in which the names of the attribute sets are specified in the use-attribute-sets attribute. [ERR049] It is a dynamic error if use of use-attribute-sets attributes on xsl:attribute-set elements causes an attribute set to use itself, directly or indirectly. The processor must signal the error

Attribute sets can also be used by specifying an xsl:use-attribute-sets attribute on a literal result element. The value of the xsl:use-attribute-sets attribute is a whitespace-separated list of names of attribute sets. The xsl:use-attribute-sets attribute has the same effect as the use-attribute-sets attribute on xsl:element with the additional rule that attributes specified on the literal result element itself are treated as if they were specified by xsl:attribute elements before any actual xsl:attribute elements but after any xsl:attribute elements implied by the xsl:use-attribute-sets attribute. Thus, in the node sequence produced by evaluating the content constructor for a literal result element, attributes from attribute sets named in an xsl:use-attribute-sets attribute will appear first, in the order listed in the attribute; these will be followed by attributes specified on the literal result element will be added; finally, any attributes specified by xsl:attribute elements will appear. Since in a sequence of attribute nodes produced by a content constructor, only the last attribute with a given expanded-QName has any effect (see [4.6 Content Constructors]), this means that attributes specified in attribute sets can be overridden by attributes specified on the literal result element itself.

The content constructor within each xsl:attribute element in an xsl:attribute-set element is evaluated each time the attribute set is used; it is evaluated using the same focus as is used for evaluating the element bearing the use-attribute-sets or xsl:use-attribute-sets attribute. However, it is the position in the stylesheet of the xsl:attribute element rather than of the element bearing the use-attribute-sets or xsl:use-attribute-sets attribute that determines which variable bindings are visible (see [6 Variables and Parameters]); thus, only global variables and parameters are visible.

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>

Multiple definitions of an attribute set with the same expanded-QName are merged. An attribute from a definition that has higher import precedence takes precedence over an attribute from a definition that has lower import precedence. [ERR050] It is a dynamic error if there are two attribute sets that have the same expanded-QName and equal import precedence and that both contain the same attribute, unless there is a definition of the attribute set with higher import precedence that also contains the attribute. The processor must either signal the error, or must recover by choosing from amongst the definitions that specify the attribute that have the highest import precedence the one that was specified last in declaration order.

Where the attributes in an attribute set were specified is relevant only in merging the attributes into the attribute set; it makes no difference when the attribute set is used. For each attribute set name occurring in a use-attribute-sets attribute on an xsl:attribute-set element, all definitions of an attribute set with that name must be merged before the use-attribute-sets attribute is replaced by the equivalent sequence of xsl:attribute child elements. Any use-attribute-sets attribute on an xsl:attribute-set element must be replaced by the equivalent sequence of xsl:attribute child elements before that xsl:attribute-set element is merged with other xsl:attribute-set elements with the same expanded-QName. When xsl:attribute-set elements with the same expanded-QName are merged, any xsl:attribute child elements added to replace a use-attribute-sets attribute are treated exactly as if they had originally been specified in the stylesheet as child elements.

7.3 Stylesheet Functions

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. [ERR051] A stylesheet function must have a prefixed name, to remove any risk of a clash with a system-defined function. 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 [8.1.2 Namespace Nodes for Literal Result Elements].

7.3.1 Defining a Stylesheet Function

<!-- Category: declaration -->
<xsl:function
  name = qname>
  <!-- Content: (xsl:param*, (xsl:variable | xsl:message)*, xsl:result) -->
</xsl:function>

The xsl:function element 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 [4.1 Qualified Names]: it must have a prefix.

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 zero or more xsl:variable elements that can be used to compute intermediate results, followed by a mandatory xsl:result element that defines the value to be returned by the function. It is also possible to include xsl:message elements after the xsl:param elements and before the xsl:result, to provide diagnostic output.

NOTE: There are no special restrictions on what can appear within an xsl:variable element. For example, the xsl:variable element can contain xsl:apply-templates or xsl:call-template instructions.

If a stylesheet contains declarations of two or more stylesheet functions with the same expanded-QName, the one with highest import precedence is used. [ERR052] It is a static error for a stylesheet to contain two or more functions with the same expanded-QName and the same import precedence, unless there is another function with the same expanded-QName and a higher import precedence.

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 QName that expands to this same expanded-QName.

A stylesheet function defined using the xsl:function element is used in preference to any function bound using an implemention-defined mechanism. It therefore takes precedence over any extension function of the same expanded name that is provided by the implementation.

Issue (user-functions-vs-vendor-functions): Should user-defined functions override vendor-defined functions of the same name, as specified here, or should it be the other way around?

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. [ERR053] It is an static error if there are more arguments supplied in the function call than there are xsl:param elements in the function definition. It is not an error if there are fewer arguments supplied: any excess xsl:param elements will take their default values (see [7.1.1 Passing Parameters to Templates]).

The type 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.0]. If the value cannot be converted to the required type, a type exception is reported. If the type attribute is omitted, the effective default is item*, which means that no conversion takes place and any value is accepted.

Issue (optional-arguments): Should functions be allowed to take optional arguments?

Within the body of the function, the focus is the same as the focus at the point in the XPath expression where the function is called. This focus is used to evaluate expressions contained in xsl:param, xsl:variable, and xsl:result elements within the function. The static context for these expressions is determined by the position of the element within the stylesheet. Specifically, this means that 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.

Any xsl:variable elements within the function are evaluated in the normal way: (see [6 Variables and Parameters]).

7.3.2 Returning the Result

<xsl:result
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:result>

The xsl:result element always appears (and only appears) as the last child of an xsl:function element. It defines the result that is returned when the function is evaluated.

The value is established in the same way as for an xsl:variable element: if there is a select attribute, the result is obtained by evaluating the expression contained in the select attribute; if the xsl:result element is not empty, the result is the document node of a temporary tree constructed as described in [6.1 Values of Variables and Parameters] obtained by evaluating the content constructor and adding the resulting sequence of nodes to a newly-constructed document node. If there is no select attribute and no content constructor, the result is an empty string; it is an static error if there is both a select attribute and a non-empty content constructor.

The optional type attribute indicates the required type of the result. The value of the type attribute is a SequenceType, as defined in [XPath 2.0]. [ERR054] If the type attribute is specified, then the calculated result is converted to the required type, using the rules defined in [XPath 2.0] for the conversion of a supplied value to a required type when calling a function.. It is a type error if this conversion fails. If the type attribute is omitted, the calculated result is used as supplied, and no conversion takes place.

Issue (result-type-optional): Should the type attribute of xsl:result be mandatory?

The following example creates a 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:str="http://user.com/namespace"
  version="2.0"
  exclude-result-prefixes="str">

<xsl:function name="str:reverse">
  <xsl:param name="sentence"/>
  <xsl:result 
     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>

The following example illustrates the use of variables 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 [9 Numbering].

<xsl:function name="num:roman">
  <xsl:param name="value" type="xsd:integer"/>
  <xsl:variable name="roman-number" type="xsd:string">
    <xsl:number value="$value" format="i"/>
  </xsl:variable>
  <xsl:result select="string($roman-number)" type="xsd:string"/>             
</xsl:function>

8 Creating New Nodes

This section describes instructions that directly create new nodes. These nodes will typically be assembled to form the result tree.

8.1 Literal Result Elements

In a content constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see [16.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. 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 content constructor, which is evaluated to return a sequence of nodes that define the attributes and children of the created element node. The children of the newly-constructed element node will be the sequence of elements, text nodes, comment nodes, and processing instructions that results from evaluating this content constructor.

Issue (define-lre-element-type): Should we add an xsl:type attribute to literal result elements, to define the type of the newly-constructed element node? Alternatively, should xsi:type be used with this meaning? What are the rules governing its use?

Issue (lre-element-typed-value): Should we provide a way of supplying the typed value of literal result element, as distinct from its string value, perhaps by means of a xsl:select attribute on the literal result element?

8.1.1 Attribute Nodes for Literal Result Elements

The created element node will have an attribute corresponding to each attribute node that is present on the element node in the stylesheet tree, other than attributes with names in the XSLT namespace.

The value of an attribute of a literal result element is interpreted as an attribute value template: it can therefore contain expressions contained in curly braces ({}). The attribute node created in the result tree will have the same name as the attribute in the source tree, and its string-value will be the same as the effective value of the attribute in the source tree.

Additional attributes may be generated by including xsl:attribute instructions in the content constructor, or by specifying the xsl:use-attribute-sets attribute on the literal result element itself. The way in which conflicts among these attributes are resolved is described in [7.2 Named Attribute Sets].

NOTE: The xml:base, xml:lang and xml:space 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 nodes within that element. One consequence of this is that these attributes should not be written as attribute value templates: although an XSLT processor will understand this notation, the XML parser will not. None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly.

8.1.2 Namespace Nodes for Literal Result Elements

The created element node will also 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 the XSLT namespace URI (http://www.w3.org/1999/XSL/Transform), a namespace URI declared as an extension namespace (see [16.2 Extension Instructions]), or a namespace URI designated as an excluded namespace.

NOTE: These exceptions only affect namespace nodes copied from the stylesheet when processing a literal result element. They do not affect namespace nodes written to the result tree using instructions such as xsl:copy and xsl:element, and they do not affect namespace nodes created under the rules for namespace fixup (see [3.5 Namespace Fixup]).

A namespace URI is designated as an excluded namespace by using an [xsl:]exclude-result-prefixes attribute either on the literal result element itself 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 a whitespace-separated list of namespace prefixes. The namespace bound to each of the prefixes is designated as an excluded namespace. It is a static error if there is no namespace bound to the prefix on the element bearing the [xsl:]exclude-result-prefixes attribute. The default namespace (as declared by xmlns) may be designated as an excluded namespace by including #default in the list of namespace prefixes. The designation of a namespace as an excluded namespace is effective within the subtree of the stylesheet 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.

NOTE: When a stylesheet uses a namespace declaration only for the purposes of addressing the source tree, specifying the prefix in the [xsl:]exclude-result-prefixes attribute will avoid superfluous namespace declarations in the result tree. The attribute is also useful to prevent namespaces used solely for the naming of extension functions from appearing in the result tree.

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

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

  • the string-value of a namespace node on a literal result element in the stylesheet.

<!-- Category: declaration -->
<xsl:namespace-alias
  stylesheet-prefix = prefix | "#default"
  result-prefix = prefix | "#default" />

A stylesheet can use the xsl:namespace-alias element to declare that one namespace URI is an alias for another namespace URI. When a literal namespace URI has been declared to be an alias for another namespace URI, then the namespace URI in the result tree will be the namespace URI that the literal namespace URI is an alias for, instead of the literal namespace URI itself. The xsl:namespace-alias element declares that the namespace URI bound to the prefix specified by the stylesheet-prefix attribute is an alias for the namespace URI bound to the prefix specified by the result-prefix attribute. 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 a namespace URI is declared to be an alias for multiple different namespace URIs, then the declaration with the highest import precedence is used. [ERR055] It is a dynamic error if there is more than one such declaration and different values for namespace-uri. The processor must either signal the error, or must recover by choosing, from amongst the declarations with the highest import precedence, the one that occurs last in declaration order.

When literal result elements are being used to create element, attribute, or namespace nodes that use the XSLT namespace URI, the stylesheet should use an alias. For example, the stylesheet

<xsl:stylesheet
  version="2.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:fo="http://www.w3.org/1999/XSL/Format"
  xmlns:axsl="http://www.w3.org/1999/XSL/TransformAlias">

<xsl:namespace-alias stylesheet-prefix="axsl" result-prefix="xsl"/>

<xsl:template match="/">
  <axsl:stylesheet>
    <xsl:apply-templates/>
  </axsl:stylesheet>
</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>

Ed. Note: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0125.html for suggested improvements to this example.

NOTE: It may be necessary also to use aliases for namespaces other than the XSLT namespace URI. For example, 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.

Issue (copy-aliased-namespaces): The rules for copying the namespace nodes of a literal result element say that a namespace node for the XSLT namespace URI is not copied. What happens if the namespace node has some other URI before xsl:namespace-alias is applied, but has the XSLT namespace URI after xsl:namespace-alias is applied? Current products differ.

Issue (prefix-aliased-namespaces): Should we make a recommendation about the preferred prefix to be used when xsl:namespace-alias changes the URI of an element or attribute?

8.2 Creating Element Nodes using xsl:element

<!-- Category: instruction -->
<xsl:element
  name = { qname }
  namespace = { uri-reference }
  use-attribute-sets = qnames>
  <!-- Content: content-constructor -->
</xsl:element>

Issue (define-element-type): Should we add a type attribute to xsl:element , to define the type of the newly-constructed element node? If so, what are the rules governing its use?

Issue (element-typed-value): Should we provide a way of supplying the typed value of a new element node, as distinct from its string value, perhaps by means of a select attribute on the xsl:element instruction?

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 content constructor for the attributes and children of the created element.

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. [ERR056] It is an dynamic error if the effective value is not a QName. The processor must either signal the error, or must recover by making the result of evaluating the xsl:element element be the sequence of nodes created by evaluating the content of the xsl:element element, excluding any initial attribute nodes.

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 should be a URI reference. It is not an error if the string is not a syntactically legal URI reference. If the string is empty, 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 QName specified by the name attribute is used as the local part of the expanded-QName of the element to be created.

Implementations may make use of the prefix of the QName specified in the name attribute when selecting the prefix used for outputting the created element as XML; however, they are not required to do so.

For the effect of the use-attribute-sets attribute, see [7.2 Named Attribute Sets]

8.3 Creating Attribute Nodes using xsl:attribute

<!-- Category: instruction -->
<xsl:attribute
  name = { qname }
  namespace = { uri-reference }>
  <!-- Content: content-constructor -->
</xsl:attribute>

Issue (define-attribute-type): Should we add a type attribute to xsl:attribute , to define the type of the newly-constructed attribute node? If so, what are the rules governing its use?

Issue (attribute-typed-value): Should we provide a way of supplying the typed value of a new attribute node, as distinct from its string value, perhaps by means of a select attribute on the xsl:attribute element?

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. The expanded-QName of the attribute to be created is specified by a required name attribute and an optional namespace attribute. The result of evaluating an xsl:attribute instruction is the newly-constructed attribute node.

The content of the xsl:attribute element is a content constructor for the value of the created attribute.

The name attribute is interpreted as an attribute value template. [ERR057] It is a dynamic error if the effective value is not a QName or is the string xmlns. The processor must either signal the error, or must recover by not adding the attribute to the result tree.

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: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 should be a URI reference. It is not an error if the string is not a syntactically legal URI reference. If the string is empty, 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 QName specified by the name attribute is used as the local part of the expanded-QName of the attribute to be created.

Implementations may make use of the prefix of the QName specified in the name attribute when selecting the prefix used for outputting the created attribute as XML; however, they are not required to do so and, if the prefix is xmlns, they must not do so. Thus, although it is not an error to do:

<xsl:attribute name="xmlns:xsl" namespace="whatever">http://www.w3.org/1999/XSL/Transform</xsl:attribute>

it will not result in a namespace declaration being output.

As described in [4.6 Content Constructors], any attribute nodes must appear in the result of evaluating a content constructor before any element, text, comment, or processing instruction nodes, but after any namespace nodes. Where the result of the content constructor contains two or more attribute nodes with the same expanded-QName, the one that comes last is the only one that takes effect. When evaluating the content of a node other than an element, returning a node sequence that includes attribute nodes is a dynamic error; the recovery action (if any) depends on the instruction that makes use of the constructed node sequence.

NOTE: When an xsl:attribute element contains a text node with a newline, then the XML output must contain a character reference. For example,
<xsl:attribute name="a">x
y</xsl:attribute>
will result in the output
a="x&#xA;y"
(or with any equivalent character reference). The XML output cannot be
a="x
y"
This is because XML 1.0 requires newline characters in attribute values to be normalized into spaces but requires character references to newline characters not to be normalized. The attribute values in the data model represent the attribute value after normalization. If a newline occurring in an attribute value in the tree were output as a newline character rather than as character reference, then the attribute value in the tree created by reparsing the XML would contain a space not a newline, which would mean that the tree had not been output correctly.

Issue (serializing-unnormalized-whitespace): We discuss serialization of &#xa; characters in attributes. But the same applies to &#x9; and &#xd; characters in attributes, and to &#xd; characters in text nodes. In each case, the character must be serialized as a character reference if it is to retain its value after a round-trip through the serializer and parser.

8.4 Creating Text Nodes

8.4.1 Literal Text Nodes

A content constructor can also contain text nodes. Each text node in a content constructor remaining after whitespace has been stripped as specified in [3.4 Whitespace Stripping] will construct a text node with the same string-value. The resulting text node is added to the result of the containing content constructor. When the resulting content is added to a result tree, adjacent text nodes in the result tree are automatically merged.

Note that text is processed at the tree level. Thus, markup of &lt; 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 &lt; (or an equivalent character reference) when the result tree is externalized as an XML document (unless output escaping is disabled as described in [18.5 Disabling Output Escaping]).

8.4.2 Creating Text Nodes using xsl:text

<!-- Category: instruction -->
<xsl:text
  disable-output-escaping = "yes" | "no">
  <!-- Content: content-constructor -->
</xsl:text>

The xsl:text element is evaluated to contruct a new text node. The content of the xsl:text element is a content constructor for the string-value of the text node.

The result of evaluating the xsl:text instruction is a single node, the newly-constructed text node.

Text nodes that are immediate children of the xsl:text instruction will not be stripped from the stylesheet tree, even if they consist entirely of whitespace (see [3.4 Whitespace Stripping]).

For the effect of the disable-output-escaping attribute, see [18.5 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 content 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.

8.5 Creating Processing Instructions

<!-- Category: instruction -->
<xsl:processing-instruction
  name = { ncname }>
  <!-- Content: content-constructor -->
</xsl:processing-instruction>

The xsl:processing-instruction element is evaluated to create a processing instruction node. The content of the xsl:processing-instruction element is a content constructor for the string-value of the 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.

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

For example, this

<xsl:processing-instruction name="xml-stylesheet">href="book.css" type="text/css"</xsl:processing-instruction>

would create the processing instruction

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

[ERR058] It is a dynamic error if the effective value of the name attribute is not both an NCName and a PITarget. The processor must either signal the error, or must recover by returning an empty sequence.

NOTE: This means that xsl:processing-instruction cannot be used to output an XML declaration. The xsl:output declaration should be used to control this instead (see [18 Serialization]).

[ERR059] It is a dynamic error if the result of evaluating the content of the xsl:processing-instruction contains the string ?>. The processor must either signal the error, or must recover by inserting a space after any occurrence of ? that is followed by a >

8.6 Creating Namespace Nodes

<!-- Category: instruction -->
<xsl:namespace
  name = { ncname }>
  <!-- Content: content-constructor -->
</xsl:namespace>

The xsl:namespace element is evaluated to create a namespace node. The content of the xsl:namespace element is a content constructor for the string-value of the namespace node (that is, the namespace URI). 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.

Except in error situations, the result of evaluating the xsl:namespace instruction is a single node, the newly-constructed namespace node. Note the restrictions described in [4.6 Content Constructors] for the position of a namespace node relative to other nodes in the node sequence returned by a content constructor.

For example, this

<xsl:namespace name="xsd">http://www.w3.org/2001/XMLSchema</xsl:namespace>

would typically cause the output document to contain the namespace declaration:

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

[ERR060] It is a dynamic error if the effective value of the name attribute is neither an empty string nor an NCName. The processor must either signal the error, or must recover by returning an empty sequence.

[ERR061] It is an dynamic error if evaluating the content of xsl:namespace results in an empty string. The processor must either signal the error, or must recover by returning an empty sequence.

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.

Ed. Note: We need to add text explaining how the new namespace node is effectively merged with other matching namespace nodes in the same document, once the data model is finalized.

8.7 Creating Comments

<!-- Category: instruction -->
<xsl:comment>
  <!-- Content: content-constructor -->
</xsl:comment>

The xsl:comment element is evaluated to contruct a new comment node. The content of the xsl:comment element is a content constructor for the string-value of the comment node.

The result of evaluating the xsl:comment instruction is a single node, the newly-constructed 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!-->

[ERR062] It is a dynamic error if the result of evaluating the content of the xsl:comment contains the string -- or ends with -. The processor must either signal the error, or must recover by inserting a space after any occurrence of - that is followed by another - or that ends the comment.

8.8 Copying Nodes from the Source Tree to the Result Tree

8.8.1 Shallow Copy

<!-- Category: instruction -->
<xsl:copy
  use-attribute-sets = qnames>
  <!-- Content: content-constructor -->
</xsl:copy>

The xsl:copy instruction provides an easy way of copying the context item. If the context item is a node, and is not a document node, evaluating the xsl:copy instruction constructs a copy of the context node, and the result of the xsl:copy instruction is this newly-constructed node. The namespace nodes of the context node are automatically copied as well, but the attributes and children of the node are not automatically copied. The content of the xsl:copy element is a content constructor for the attributes and children of the created node; the content constructor is evaluated only for nodes of types that can have children (that is, document nodes and element nodes).

The xsl:copy element may have a use-attribute-sets attribute (see [7.2 Named Attribute Sets]). This is used only when copying element nodes.

The document node is treated specially because the document node of a result tree is created implicitly. When the context item is a document node, xsl:copy will not create a document node, but will just evaluate the content constructor, and return the resulting node sequence as the result of the xsl:copy instruction.

For example, the identity transformation can be written using xsl:copy as follows:

<xsl:template match="@*|node()">
  <xsl:copy>
    <xsl:apply-templates select="@*|node()"/>
  </xsl:copy>
</xsl:template>

[ERR063] When the context item is an attribute node, then if it would be a dynamic error to use xsl:attribute to create an attribute with the same name as the context item, then it is also a dynamic error to use xsl:copy (see [8.3 Creating Attribute Nodes using xsl:attribute]). The processor must either signal the error, or must recover by returning an empty sequence.

When the context item is a namespace node, then xsl:copy constructs a new namespace node as a copy of the context node (that is, a namespace node with the same expanded-QName and string-value. As described in detail in [4.6 Content Constructors], it will generally be an error if this namespace node is preceded in the constructed node sequence by any node other than another namespace node, or if the namespace node cannot be added to a containing element without a conflict arising.

When the context item is not a node, the effect of the xsl:copy instruction is the same as evaluating the instruction <xsl:value-of select="."/>.

The following example shows how xml:lang attributes can be easily copied through from source to result. If a stylesheet defines the following named template:

<xsl:template name="apply-templates-copy-lang">
 <xsl:for-each select="@xml:lang">
   <xsl:copy/>
 </xsl:for-each>
 <xsl:apply-templates/>
</xsl:template>

then it can simply do

<xsl:call-template name="apply-templates-copy-lang"/>

instead of

<xsl:apply-templates/>

when it wants to copy the xml:lang attribute.

Ed. Note: This is a poor example because it would be easier to write <xsl:copy-of select="@xml:lang"/>

8.8.2 Deep Copy

<!-- Category: instruction -->
<xsl:copy-of
  select = expression
  separator = { string } />

The xsl:copy-of instruction can be used to construct a copy of a sequence of nodes, with each new node containing copies of all the children, attributes, and namespace of the original node, recursively. The result of evaluating the instruction is a sequence of new nodes corresponding one-to-one with the supplied node sequence, and retaining its order. (This correspondence does not apply when copying a document node: see below).

The xsl:copy-of instruction can also be used to copy simple values.

The mandatory select attribute contains an expression. The required type of this expression is sequence, which means that any sequence can be supplied. 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 copies of the attribute nodes, namespace nodes and children of the element node.

  • If the item is a document node, the instruction copies the children of the document node (each according to the rules for its own node type) and adds the copies, in order, to the result sequence.

  • 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 [8.8 Copying Nodes from the Source Tree to the Result Tree]).

  • If the item is a simple value, the result is converted to a string, a new text node is constructed with this string as its string-value, and the new text node is appended to the result sequence, as with xsl:value-of.

If the separator attribute is present, then its effective value (a string) is inserted as a text node into the result sequence after the result of processing each item in the input sequence, other than the last. If the separator attribute is absent, the effect is the same as supplying an empty string.

For example, the instruction:

<x><xsl:copy-of select="(1,2,3,4)" separator="|"/></x>

produces the output:

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

8.9 Generating Text with xsl:value-of

Within a content constructor, the xsl:value-of instruction can be used to compute generated text, for example by extracting text from the source tree or by inserting the value of a variable. The xsl:value-of instruction computes this text using an expression that is specified as the value of the select attribute.

NOTE: An alternative way of computing a string value, applicable only when the resulting text is to be used within a generated attribute node, is to use an attribute value template, enclosing the expression in curly braces ({}) within an attribute of a literal result element.

<!-- Category: instruction -->
<xsl:value-of
  select = expression
  separator = { string }
  disable-output-escaping = "yes" | "no" />

The xsl:value-of instruction is evaluated to construct a new text node; the result of the instruction is the newly-constructed text node. But if the rules below produce a text node whose string value is the empty string, the result of the instruction is an empty sequence. The required select attribute is an expression. The required type of this expression is sequence, which means that the result of the expression may be any sequence. If the sequence is empty, no text node will be created. If the sequence contains a single item, the resulting text node will have a string-value that is the same as the string-value of this item. If the sequence contains more than one item, the effect depends on whether the separator attribute is present.

If the separator attribute is present, then the string-value of the newly constructed text node will be the concatenation of the string-values of the items in the sequence that results from evaluating the select attribute, with each of these string-values except the last being followed by the string that is the effective value of the separator attribute. If the separator attribute is absent, then (for backwards compatibility with XSLT 1.0) all items in the input sequence other than the first are ignored. If the effective value of the separator attribute is an empty string, then all items in the input sequence are processed and the results are concatenated with no separator.

For example, the instruction:

<x><xsl:value-of select="(1,2,3,4)" separator="|"/></x>

produces the output:

<x>1|2|3|4</x>
NOTE: The separator attribute is used only when the select expression produces a sequence of items. It is not used when the select expression returns a single node whose typed-value is a sequence, for example a node of type IDREFS. The string-value of such a node is obtained in the normal way, as if by calling the string function.
NOTE: The xsl:copy-of element can be used to copy a sequence of nodes to the result tree without converting to a string. See [8.8.2 Deep Copy].

For example, the following creates an HTML paragraph from a person element with given-name and family-name attributes. The paragraph will contain the value of the given-name attribute of the context node followed by a space and the value of the family-name attribute of the context node.

<xsl:template match="person">
  <p>
   <xsl:value-of select="@given-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="@family-name"/>
  </p>
</xsl:template>

For another example, the following creates an HTML paragraph from a person element with given-name and family-name children elements. The paragraph will contain the string-value of the first given-name child element of the context node followed by a space and the string-value of the first family-name child element of the context node.

<xsl:template match="person">
  <p>
   <xsl:value-of select="given-name"/>
   <xsl:text> </xsl:text>
   <xsl:value-of select="family-name"/>
  </p>
</xsl:template>

The following precedes each procedure element with a paragraph containing the security level of the procedure. It assumes that the security level that applies to a procedure is determined by a security attribute on the procedure element or on an ancestor element of the procedure. It also assumes that if more than one such element has a security attribute then the security level is determined by the element that is closest to the procedure.

<xsl:template match="procedure">
  <fo:block>
    <xsl:value-of select="ancestor-or-self::*[@security][1]/@security"/>
  </fo:block>
  <xsl:apply-templates/>
</xsl:template>

For the effect of the disable-output-escaping attribute, see [18.5 Disabling Output Escaping]

9 Numbering

<!-- Category: instruction -->
<xsl:number
  level = "single" | "multiple" | "any"
  count = pattern
  from = pattern
  value = number-expression
  format = { string }
  lang = { nmtoken }
  letter-value = { "alphabetic" | "traditional" }
  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.

The xsl:number instruction performs two tasks: firstly, determining a place marker to be formatted (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 tree. 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 the context node in the source tree.

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 function may be more suitable: see [14.4 Number Formatting].

9.1 Formatting a Supplied Number

The place marker to be formatted may be specified by an expression. The value attribute contains the expression. The required type of the expression is xsd:integer*, that is, a sequence of integers. The expression is evaluated, to produce a sequence, and each item in this sequence is converted to an integer using the rules of the XPath cast construct.

[ERR064] It is a dynamic error if any item in the sequence cannot be converted to an integer, or if the resulting integer is less than 1 (one). The processor must either signal the error, or must recover by converting that member to a string as if by a call to the string function and inserting the resulting string into the formatted result string in its proper position.

Otherwise, the sequence is formatted as a string using the effective values of the attributes specified in [9.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.

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>

9.2 Numbering based on Position in the Source Tree

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 the context node within its tree. Without loss of generality, the tree containing the context node is referred to in this section as the source tree.

[ERR065] It is a dynamic error if the xsl:number instruction is evaluated, with no value attribute, when the context item is not a node. The processor must either signal the error, or must recover by returning an empty sequence.

The following attributes control how the context node is to be numbered:

In addition, the attributes specified in [9.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 the given 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 the given node matches the pattern given in the from attribute (this function is not used if the from attribute is omitted).

When level="single":

When level="multiple":

When level="any":

The sequence of numbers (the place marker) is then converted into a string using the effective values of the attributes specified in [9.3 Number to String Conversion Attributes]; each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is inserted in the result tree.

For example, 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>

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.

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

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

The following example will number H4 elements in HTML with a three-part label:

<xsl:template match="H4">
 <fo:block>
   <xsl:number level="any" from="H1" count="H2"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H2" count="H3"/>
   <xsl:text>.</xsl:text>
   <xsl:number level="any" from="H3" count="H4"/>
   <xsl:text> </xsl:text>
   <xsl:apply-templates/>
 </fo:block>
</xsl:template>

9.3 Number to String Conversion Attributes

The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than 0. 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) specify the format to be used for each number in the sequence. If the first token is a non-alphanumeric token, then the constructed string will start with that token; if the last token is non-alphanumeric token, then the constructed string will end with that token. Non-alphanumeric tokens that occur between two format tokens are separator tokens that are used to join numbers in the sequence. The nth format token will be used to format the nth number in the sequence. If there are more numbers than format tokens, then the last format token will be used to format remaining numbers. If there are no format tokens, then a format token of 1 is used to format all numbers. The format token specifies the string to be used to represent the number 1. Each number after the first will be separated from the preceding number by the separator token preceding the format token used to format that number, or, if there are no separator tokens, then by . (a period character).

Format tokens are a superset of the allowed values for the type attribute for the OL element in HTML 4.0 and are interpreted as follows:

For all format tokens other than the first kind above (one that consists of decimal digits), there may be an implementation-defined upper bound on the range of numbers that can be formatted using this format token. For the numbering sequences described above, this upper bound must not be less than 1000 (one thousand). Numbers that exceed the upper bound must be formatted using the format token 1.

When numbering with an alphabetic sequence, the lang attribute specifies which language's alphabet is to be used; it has the same range of values as xml:lang [XML]; if no lang value is specified, the language should be determined from the system environment. The set of languages for which numbering is supported is implementation-defined.

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: It is possible for two conforming implementations not to convert a number to exactly the same string. Some implementations might not support some languages. Furthermore, there may be variations possible in the way conversions are performed for any particular language that are not specifiable by the attributes on xsl:number. Future versions of XSLT may provide additional attributes to provide control over these variations. Implementations may also use implementation-defined namespaced attributes on xsl:number for this.

The grouping-separator attribute gives the separator used as a grouping (e.g. 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. If only one of the grouping-separator and grouping-size attributes is specified, then it is ignored.

Here are some examples of conversion specifications:

10 Repetition

<!-- Category: instruction -->
<xsl:for-each
  select = sequence-expression>
  <!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each>

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

The select attribute is required, and the expression must evaluate to a sequence, called the input sequence. If there is an xsl:sort element present (see [12 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 content constructor, which is evaluated once for each item in the sorted sequence. The content constructor is evaluated with the focus set as follows:

For each item in the input sequence, evaluating the content constructor produces a sequence of output nodes; these output sequences are concatenated in the same order as the sorted sequence. The result of the xsl:for-each instruction is the concatenated sequence of output nodes.

NOTE: With XSLT 1.0, the selected nodes were processed in document order. With XSLT 2.0, XPath expressions that would have been valid under XPath 1.0 (such as path expressions and union expressions) will return a sequence of nodes that is already in document order, so backwards compatibility is maintained.

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>

11 Conditional Processing

There are two instructions in XSLT that support conditional processing in a template: 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.

11.1 Conditional Processing with xsl:if

<!-- Category: instruction -->
<xsl:if
  test = expression>
  <!-- Content: content-constructor -->
</xsl:if>

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

The required type of the expression in the test attribute is xsd:boolean. Type conversion follows the XPath rules for other boolean contexts, which means that a value of () (the empty sequence) is treated as false.

If the result of evaluating the expression is true, then the content constructor is evaluated, and the resulting node sequence is returned as the result of the xsl:if instruction; otherwise, an empty sequence is returned.

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>

11.2 Conditional Processing with xsl:choose

<!-- Category: instruction -->
<xsl:choose>
  <!-- Content: (xsl:when+, xsl:otherwise?) -->
</xsl:choose>

<xsl:when
  test = expression>
  <!-- Content: content-constructor -->
</xsl:when>

<xsl:otherwise>
  <!-- Content: content-constructor -->
</xsl:otherwise>

The xsl:choose element selects one among a number of possible alternatives. It consists of a sequence of 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 content constructor.

The required type of the expression in the test attribute of the xsl:when element is xsd:boolean. Type conversion follows the XPath rules for a choice context, which means that a value of () (the empty sequence) is treated as false.

When an xsl:choose element is processed, each of the xsl:when elements is tested in turn, until one of the expressions evaluates to true. The content of the first, and only the first, xsl:when element whose test is true is evaluated, and the resulting node sequence is returned as the result of the xsl:choose instruction. If no xsl:when condition is true, the content of the xsl:otherwise element is evaluated, and the resulting node sequence is returned as the result of the xsl:choose instruction. If no xsl:when element is true, and no xsl:otherwise element is present, the result of the xsl:choose instruction is an empty sequence.

The content constructors for xsl:when and xsl:otherwise instructions other than the selected one are not evaluated, and the select expressions for xsl:when instructions after the selected one are not evaluated.

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>

12 Sorting

A sort 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. Within a sort specification, each xsl:sort element provides one sort key definition. The first xsl:sort element specifies the primary part of the sort specification, the second xsl:sort element specifies the secondary part of the sort specification and so on.

A sort specification may occur as the content of an xsl:sort-key declaration at the top level of a stylesheet module, or it may occur immediately within an xsl:apply-templates, xsl:for-each, or xsl:for-each-group element.

[ERR066] When used within xsl:for-each or xsl:for-each-group, xsl:sort elements must occur before any other children.

12.1 Collating Sequences

When sorting or comparing a set of strings, the question arises, what collating sequence should be used? Facilities in XSLT 2.0 and XPath 2.0 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 should 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.

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.

In order to allow portable stylesheets to be written, implementations should provide facilities that allow an arbitrary URI to be bound to a collation offered by that implementation. The URIs that designate collations should not be hard-wired into the implementation. One way of doing this is by means of a top-level element in the stylesheet of the form <vendor:collation name="uri"> where vendor is an implementor-defined namespace and uri is the URI used to identify the collation; the attributes and/or content of this declaration can be used to bind the collation URI to a specific collation available from the implementation. As described in [2.4.1 User-defined Data Elements], such top-level elements will have no effect when the stylesheet is processed by an XSLT processor that does not recognize the namespace URI. A stylesheet that requires portability can therefore use multiple <vendor:collation declarations to bind the collation URI to different collation implementations provided by different vendors.

Ed. Note: Add something here about the default collation.

12.2 The xsl:sort Element

<xsl:sort
  select = expression
  lang = { nmtoken }
  data-type = { "text" | "number" | qname-but-not-ncname }
  order = { "ascending" | "descending" }
  collation = { uri }
  case-order = { "upper-first" | "lower-first" } />

Those attributes of the xsl:sort elements whose values are attribute value templates are evaluated using the outer focus. If the element that contains the xsl:sort elements is an xsl:sort-key declaration, then the outer focus is a singleton focus based on the document node of the principal source document. Otherwise, the outer focus is the focus used to evaluate the select attribute of the containing instruction (for example, xsl:for-each or xsl:apply-templates).

The sequence to be sorted is referred to as the initial sequence. The sequence after sorting as defined by the xsl:sort elements is referred to as the sorted sequence.

For each item in the initial sequence, a value is computed for each sort key definition within the sort specification. The value computed for an item by using the Nth sort key definition is referred to as the Nth sort key of that item. Specifically, the Nth sort key is computed by evaluating the expression contained in the select attribute of the Nth xsl:sort element, if there is such an attribute. If there is no select attribute, the sort key is computed by taking the actual item in the initial sequence if it is a simple value, or the typed-value of this item if it is a node.

The expression in the select attribute of the xsl:sort element is evaluated with the focus set as follows:

If the xsl:sort element has a data-type attribute, then the sort key is converted to the target data type before comparing it with other items. [ERR067] The target data type for each xsl:sort element is determined by the effective value of its data-type attribute. If this has the value text, the target data type is xsd:string. If it has the value number, the target data type is xsd:double. Otherwise, the target data type must be the name of a primitive data type in XML Schema (see [XML Schema]). It is a dynamic error if any other value is supplied. The processor must either signal the error, or must recover by continuing as if the data-type attribute were not specified. Each sort key is converted to the target data type using the rules for the XPath cast expression. [ERR068] It is a dynamic error if any value obtained by evaluating the select attribute of an xsl:sort element cannot be converted to the target data type. The processor must either signal the error, or must recover by treating the value as being less than any value for which conversion succeeds, but equal to any other value for which conversion fails. This means (if this is the first or only sort key) that values that cannot be converted to the target data type will appear together at the start of the sorted sequence if order is ascending, or at the end if order is descending.

If there is no data-type attribute, then the computed sort keys are not converted before comparison, except in the case where the data type of a computed sort key is a complex type, in which case it is converted to a string as if by the XPath string function.

The items in the initial sequence are ordered into a sorted sequence by comparing their sort keys. The relative position of two items A and B in the sorted sequence is determined as follows. The first sort key of A is compared with the first sort key of B, according to the rules of the first sort key definition. 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 definition specifies descending, in which case B will precede A in the sorted sequence. If, however, the relevant sort keys compare equal, then the second sort key of A is compared with the second sort key of B, according to the rules of the second sort key definition. This continues until two sort keys are found that compare unequal. If all the sort keys compare equal, then A will precede B in the sorted sequence if A preceded B in the initial sequence, and vice versa.

In general, comparison of two values is performed according to the rules of the XPath lt operator. However, special rules apply to certain data types, as described below. [ERR069] It is a dynamic error if, for any sort key definition, the set of sort keys evaluated for all the items in the initial sequence, after any type conversion requested, contains a pair of values for which the result of the XPath lt operator is an error or an empty sequence. The processor must either signal the error, or must recover by assigning an arbitrary ordering to any such pair of values.

If the target data type is a list data type, then the two sort keys to be compared are considered as sequences. The two sequences are compared pairwise. The ordering of the first pair of values that are unequal determines the ordering of the two sequences. If all items up to the length of the shorter sequence are equal, then the shorter sequence is considered to be less than the longer. If the sequences have the same length, and all their items are equal, then the two sequences are considered equal.

Issue (sequence-valued-sort-key): What happens if the value of a sort key is a sequence?

[ERR070] It is a dynamic error if the effective value of the data-type attribute of the xsl:sort element is a data type for which no ordering relation is defined, other than the values xsd:string or text, which are synonymous. The processor must signal the error, or must recover by continuing as if the data-type attribute were omitted.

For comparison of string values, special rules apply. 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 xf:compare($a, $b, $collation).

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 identify a suitable collation:

In the absence of any of these attributes, the default collation is used.

NOTE: The exact results of sorting are implementation-dependent. Some implementations might not support some languages. Furthermore, there may be variations possible in the sorting of any particular language that are not specified by the attributes on xsl:sort, for example, whether Hiragana or Katakana is sorted first in Japanese. Future versions of XSLT may provide additional attributes to provide control over these variations. Implementations may also use implementation-defined namespaced attributes on xsl:sort for this.
NOTE: It is recommended that implementors consult [UNICODE TR10] for information on internationalized sorting.

There are also special considerations where the target data type is float or double. For sorting purposes, NaN values are considered equal to each other, and less than any other value, including negative infinity. A value that cannot be converted to the target data type is treated in the same way as a NaN value. Negative zero and positive zero are considered equal, as normal.

12.3 Using Unnamed Sort Specifications

When used within xsl:for-each or xsl:apply-templates, a sort specification indicates that the sequence of items selected by that instruction should be processed in sorted order, not in the order of the supplied sequence.

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 specification indicates the order in which the groups should be processed. For the effect of xsl:for-each-group, see [13 Grouping]

12.4 Using Named Sort Specifications

<!-- Category: declaration -->
<xsl:sort-key
  name = qname>
  <!-- Content: (xsl:sort+) -->
</xsl:sort-key>

Issue (converge-with-sortby): While the facility for named sort keys meets the requirement to be able to sort arbitrary sequences, the XSL Working Group would prefer to find a way of converging this capability with the sortby syntax proposed for use in XQuery.

A named sort specification is defined by an xsl:sort-key declaration. This is a top-level element in the stylesheet. The name attribute is mandatory. The value of the name attribute is a QName, which is expanded as described in [4.1 Qualified Names]: it need not have a prefix.

The content of the xsl:sort-key element consists of one or more xsl:sort elements that define the components of the sort specification, in major to minor order.

If a stylesheet contains declarations of two or more named sort specifications with the same expanded-QName, the one with highest import precedence is used. [ERR071] It is a static error for a stylesheet to contain two or more named sort specifications with the same expanded-QName and the same import precedence, unless there is another named sort specification with the same expanded-QName and a higher import precedence.

Function: sequence sort(string, sequence)

In an XPath expression used within an XSLT stylesheet, an additional function sort is available, which sorts a sequence using a named sort specification.

The first argument is evaluated as a string; its value must be a QName whose expanded-QName is the same as the name of a named sort specification defined in the stylesheet. [ERR072] It is a dynamic error if the first argument of the sort function does not match the name of any named sort specification in the stylesheet. The processor must signal the error.

The second argument is evaluated as a sequence. This sequence forms the initial sequence for the sort. The sequence is sorted according to the rules for the named sort specification, and the result of the function call is the resulting sorted sequence.

13 Grouping

The facilities described in this section are designed to allow users to group nodes in a document based on common string values, common names, or commmon 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.

In addition these facilities allow grouping based on sequential position, e.g. 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 content 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.

13.1 The Current Group

Function: sequence current-group()

The evaluation context for XPath expressions includes an additional value called the current group, which is a sequence. The current group is the collection of related items that are processed collectively in one iteration of the xsl:for-each-group element.

While an xsl:for-each-group instruction is being evaluated, the current group will be non-empty. At other times, it will be an empty sequence.

The function current-group returns the current group.

The function takes no arguments.

[ERR073] The current-group function must not be used within a pattern.

13.2 The xsl:for-each-group Element

<!-- Category: instruction -->
<xsl:for-each-group
  select = expression
  group-by = expression
  group-adjacent = expression
  group-starting-with = pattern
  group-ending-with = pattern>
  <!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each-group>

This element is an instruction that may be used anywhere within a content constructor.

The xsl:for-each-group instruction partitions a sequence into groups of items (that is, it establishes a set of sequences) based either on common values of a grouping key, or on a pattern that the initial node in a group must match. The content constructor that forms the content of the xsl:for-each-group instruction is evaluated once for each of these groups. A group is never empty.

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. The required type of this expression is sequence. The population is treated as a sequence; the order of items in this sequence is referred to as population order. If the population is empty, the number of groups will be zero. Each item in the population is assigned to exactly one group: the assignment of items to groups depends on the group-by, group-adjacent, and group-starting-with attributes. [ERR074] These four attributes are mutually exclusive: exactly one of the four attributes must be present.

For each group, the item within the group that is first in population order is known as the initial item of the group.

There is an 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.

There is another ordering among groups referred to as processing order.

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 [12 Sorting]). They do not affect the order of items within each group. Multiple sort keys are allowed, and are evaluated in major-to-minor order. If two groups have the same values for all their sort keys, they are processed in order of first appearance.

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, and the current group is the group whose sort key is being determined. 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="@category"/>; or you can sort the groups in order of size by writing <xsl:sort select="count(current-group())" data-type="number">

If there are attribute value templates present in the xsl:sort element, the focus for evaluation of the contained expressions is the same as the focus for evaluation of the select attribute of the containing xsl:for-each-group instruction.

The content constructor contained by the xsl:for-each-group element is evaluated once for each of the groups, in processing order. The node sequences that result are concatenated, in processing order, to form the result of the xsl:for-each-group element. Within the content constructor, the context item is the initial item of the relevant group, the context position is the position of this item among the set of initial items (one item for each group) arranged in processing order of the groups, the context size is the number of groups, and the current group is the group being processed. This has the effect that within the the content constructor, a call on position() takes successive values 1, 2, ... last().

On completion of the evaluation of the xsl:for-each-group, the current group reverts to its previous value.

13.3 Examples of Grouping

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="1.0" 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>

The following example uses the same source document, this time grouping the cities according to the initial letter of the city name. The groups are sorted, and the result includes a count of the nodes within the group. The heading contains a count of the number of groups:

Desired output:

    <html>
      <body>
        <h2>L (1)</h2><p>Lyon</p>
        <h2>M (2)</h2><p>Milano</p><p>München</p>
        <h2>P (1)</h2><p>Paris</p>
        <h2>V (1)</h2><p>Venezia</p>
      </body>
    </html>

Solution:

    <html xsl:version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <body>
        <xsl:for-each-group select="cities/city" group-by="substring(@name,1,1)">
          <xsl:sort select="substring(@name,1,1)"/>
          <h2>
            <xsl:value-of select="upper-case(substring(@name,1,1))"/>
            <xsl:text> (</xsl:text>
            <xsl:value-of select="count(current-group())"/>
            <xsl:text>)</xsl:text>
          </h2>
          <xsl:for-each select="current-group()">
            <p><xsl:value-of select="@name"/></p>
          </xsl:for-each>
        </xsl:for-each-group>
      </body>
    </html>

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 an XML document 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.

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="self::ul or self::ol">
                    <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 Additional Functions

This section describes XSLT-specific additions to the core XPath function library. Some of these additional functions also make use of information specified by declarations in the stylesheet; this section also describes these declarations.

14.1 Multiple Source Documents

The document function, which in XSLT 1.0 was an additional function defined in the XSLT specification, is now a core function defined in XPath 2.0: see [Functions and Operators]. Details of the function have therefore been removed from this specification.

Function: node * document(sequence, node?)

The document function allows access to XML documents other than the principal source document.

Call the value supplied as the first argument to the document function arg1 (in general this is a sequence), and call the value supplied as the second argument arg2. [ERR077] It is a dynamic error if arg2 is an empty sequence, or a sequence whose first item is not a node, unless all the URIs in arg1 are absolute URIs; The processor must either signal the error, or must recover by returning an empty sequence. If arg2 is a sequence of more than one node, the effect is as if only the first node in the sequence were supplied.

The result of the document function can be explained in terms of an internal primitive function one-doc which takes a requested URI and a base URI as arguments, and returns a node sequence as its result. The result of the document function is the union of the node sequences obtained by calling one-doc once for each member of the sequence arg1.

The one-doc function retrieves a document a document using a request URI R and a base URI B.

For a member of arg1 that is a node N, the one-doc function is called with the string-value of N as the request URI, and with a base URI that is the base URI of arg2 if arg2 was supplied, or the base URI of N otherwise.

For a member of the arg1 that is a simple value, the one-doc function is called using a request URI obtained by converting that simple value to a string as if by using the string function, and a base URI that is the base URI of arg2 if arg2 was supplied, or the base URI of the stylesheet element containing the call to the document function otherwise.

The internal one-doc function operates as follows.

The resource identified by the URI is retrieved. The data resulting from the retrieval action is parsed as an XML document and a tree is constructed in accordance with the data model (see [3 Data Model]). [ERR078] An error retrieving the resource is classed as a dynamic error. The processor must either signal the error, or must recover by returning an empty sequence. One possible kind of retrieval error is that the implementation does not support the URI scheme used by the URI. An implementation is not required to support any particular URI schemes. The documentation for an implementation should specify which URI schemes the implementation supports.

If the URI reference does not contain a fragment identifier, then the document node of the document is returned. If the URI reference does contain a fragment identifier, the function returns a node-sequence containing the nodes in the tree identified by the fragment identifier of the URI reference. The semantics of the fragment identifier are dependent on the media type of the result of retrieving the URI. [ERR079] An error in processing the fragment identifier is classed as a dynamic error. The processor must either signal the error, or must recover by returning an empty sequence. Possible errors include:

  • The fragment identifier identifies something that cannot be represented by an XSLT node sequence (such as a range of characters within a text node).

  • The implementation does not support fragment identifiers for the media-type of the retrieval result. An implementation is not required to support any particular media types. The documentation for an implementation should specify for which media types the implementation supports fragment identifiers.

The data resulting from the retrieval action is parsed as an XML document regardless of the media type of the retrieval result; if the top-level media type is text, then it is parsed in the same way as if the media type were text/xml; otherwise, it is parsed in the same way as if the media type were application/xml.

NOTE: Since there is no top-level xml media type, data with a media type other than text/xml or application/xml may in fact be XML.

The URI reference may be relative. The base URI (see [Data Model]) of the node in the second argument is used as the base URI for resolving the relative URI into an absolute URI. Note that specifying a zero-length URI reference has the same effect as specifying the base URI of the node containing the URI reference; this means that unless XML entities or xml:base are used, document("") refers to the document node of the stylesheet module; the tree representation of the stylesheet module is exactly the same as if the XML document containing the stylesheet was the principal source document.

NOTE: When a stylesheet module is loaded as a source document, the rules for whitespace stripping (see [3.4 Whitespace Stripping]) are those that apply to source documents, not those that apply to stylesheet documents.

Two documents are treated as the same document if they are identified by the same URI. The URI used for the comparison is the absolute URI into which any relative URI was resolved and does not include any fragment identifier. One document node is treated as the same node as another document node if the two nodes are from the same document. Thus, the following expression (if it does not cause an error) will always be true:

generate-id(document("foo.xml"))=generate-id(document("foo.xml"))

The document function gives rise to the possibility that a node sequence may contain nodes from more than one document. The concept of document order still applies, and is defined in [Data Model].

Issue (no-base-uri): In the XPath 2.0 data model, elements have a base URI but attributes and text nodes don't.

14.2 Reading Text Files

Function: sequence unparsed-text(sequence, string?)

The unparsed-text reads one or more external files and returns the contents of each one as a string.

The first argument is treated as a sequence. Each item in the sequence, when converted to a string, must be a URI. The URI must contain no fragment identifier, and must identify a resource that can be read as text. If the URI is a relative URI, then:

The second argument, if present, is the name of an encoding. This encoding is used to translate the contents of the file into a string. 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 obliged to recognize are utf-8 and utf-16. If the second argument is omitted, the implementation may attempt to infer the encoding of the file by using external information (such as an HTTP header) or by auto-recognition using techniques such as those described in [XML].

[ERR080] It is a dynamic error if a URI cannot be used to retrieve a resource containing text. The processor must either signal the error, or must recover by treating the URI as if it referenced a resource containing a zero-length string.

[ERR081] It is a dynamic error if a resource contains characters that are not valid XML characters. The processor must either signal the error, or must recover in a implementation-defined way; one possible outcome is that the processor will produce an output file that is not well-formed XML.

[ERR082] It is a dynamic error if a resource contains bytes that cannot be decoded into valid XML characters using the specified encoding. This includes the case where the processor does not support the requested encoding. The processor must signal the error.

[ERR083] It is a dynamic error if the second argument of the unparsed-text function is omitted and the processor cannot infer the encoding using external information.The processor must signal the error.

The result is a sequence of strings, containing one string for each URI in the sequence supplied as the first argument; each string holds the text of the resource retrieved using the URI in the corresponding position of the sequence.

NOTE: If the text file contains characters such as < and &, these will typically be output as &lt; and &amp; when the string is written to the 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 [18.5 Disabling Output Escaping]. Note, however, that implementations are not required to support this feature.

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

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

14.3.1 The xsl:key Declaration

<!-- Category: declaration -->
<xsl:key
  name = qname
  match = pattern
  use = expression
  data-type = qname
  collation = uri />

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 [4.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. The use attribute is an expression specifying the values of the key; the expression will be evaluated with the node that matches the pattern as the context node. The required type of the expression is xsd:string*, which means that the result of evaluating the expression is treated as a sequence of strings, by taking the string value of each item in the sequence.

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 use expression (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 use expression in general returns a sequence of values, and any one of these may be used to locate the node.

The data-type attribute defines the required type of the result of the use expression, and it also defines the rules that determine whether two key values are considered equal. The default value is xsd:string, which means that the result of evaluating the expression is treated as a sequence of strings, by taking the string value of each item in the sequence. In general, the result of evaluating the use expression is converted to a sequence of items of the specified data-type, by invoking the rules for the cast as operator defined in [XPath 2.0]. The data-type must be either a built-in type defined in [XML Schema] (Part 2), or an atomic type defined in a schema imported using an xsl:import-schema declaration.

The collation attribute is used only when the data-type is xsd:string, and it identifies a collation that is used to decide 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 xf:compare($a, $b, $collation) is zero.

It is possible to have:

  • multiple key declarations with the same name;
  • a node that matches the match patterns of several different key declarations;
  • a node that returns more than one value from its use expression;
  • 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.

[ERR084] It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different data types, or if the data type is specified in one of these declarations and omitted in another. The key names and data types are the same if their expanded names match.

[ERR085] It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different collation sequences, or if the collation is specified in one of these declarations and omitted in another. The collation names are the same if their URIs consist of the same sequence of Unicode code-points.

[ERR086] It is a static error if the value of the data-type attribute is not an atomic type (optionally followed by an occurrence count).

[ERR087] It is a static error if a value is specified for the collation attribute unless the data-type is defaulted or set to xsd:string.

[ERR088] It is a dynamic error if the result of evaluating the use expression , for any node that matches the pattern specified in the match attribute, cannot be converted to the data type specified by the data-type attribute. The processor may signal the error, or may recover by ignoring the existence of the value that cannot be converted.

[ERR089] It is a static error for the value of either the use attribute or the match attribute to contain a Variable other than a range variable defined within the XPath expression containing the Variable, or a call to the key function.

[ERR090] It is a dynamic error if evaluating either the use attribute or the match attribute results in a call on the key function, with the name of this key definition as the first argument. The processor must signal the error.

14.3.2 The key Function

Function: node * key(string, sequence)

The key function does for keys what the id function does for IDs.

The first argument specifies the name of the key. The value of the argument must be a QName, which is expanded as described in [4.1 Qualified Names]. [ERR091] It is a 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 key declaration in the stylesheet. The processor must signal these errors.

The second argument to the key function is regarded as a sequence. The set of requested key values is formed by converting each member of this sequence to a string as if by a call to the string functioncasting the supplied value of the argument to the data-type defined in the key declaration. In general the result is a sequence of atomic values, each of which 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 context document that are matched by an xsl:key declaration whose name is the same as the supplied key name, and whose value is equal to one of these requested key values, under the rules of the data-type and collation specified in the key declaration.

More formally, if the result of evaluating the second argument of the key function is denoted by $V, the result returned by the key function is the union of the node sequences selected by the expression

//(MATCH)/self::node()
   [some $k in (for $kk in USE return cast as TYPE ($kk)),
         $v in (for $vv in $V return cast as TYPE ($vv))
         satisfies $k eq $v]

applied to all xsl:key declarations whose name matches the name given as the first argument to the key function, where MATCH is the pattern given in the match attribute of the xsl:key declaration, and USE is the expression given in its use attribute , and TYPE is the expression given in its data-type attribute, or xsd:string* if the attribute is omitted. The values of the match and use and data-type attributes are textually substituted into the above expression. Note that the predicate (USE) = $V typically has a sequence on both sides of the equals sign: it returns true if any of the values returned by the USE expression is equal to any of the values in $V.

If the collation attribute is specified in the key declaration, the expression above is modified to read:

//(MATCH)/self::node()
   [some $k in (for $kk in USE return cast as xsd:string($kk)),
         $v in (for $vv in $V return cast as xsd:string($vv))
         satisfies xf:compare($k, $v, 'COLLATION') = 0]
NOTE: The reason that /self::node() appears in the above expressions is to ensure that any calls of position() or last() within the USE expression evaluate to 1 (one). This is necessary to retain compatibility with the XSLT 1.0 specification.

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="key" return-type="node-set">
<arg type="string"/>
<arg type="object"/>
</prototype>

and a function element to refer to function names

<function>key</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>

The key always returns nodes that are in the context document; to retrieve a key from any other document, it is necessary first to change the context document. 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 any function call on the right-hand side of the / operator in a path expression.

Issue (list-of-keys): Would it be useful to provide a function key-values(keyname) that provides a sequence containing all the values for a given key?

14.4 Number Formatting

Function: string format-number(double, string, string?)

The format-number function formats a number as a string using the picture string specified by the second argument and the decimal-format named by the third argument, or the default decimal-format, if there is no third argument. The number is supplied as the value of the first argument. The required type of this argument is xsd:double; if the value is not of the right type, it is converted using the standard conversion rules. The decimal-format name must be a QName, which is expanded as described in [4.1 Qualified Names]. The result of the function is the formatted string representation of the supplied number.

[ERR092] It is a dynamic error if the stylesheet does not contain a declaration of the decimal-format with the expanded-QName specified as the third argument. The processor must either signal the error, or must recover by ignoring the third argument.

NOTE: Stylesheets can use other facilities in XPath to control rounding.

14.4.1 Defining a Decimal Format

<!-- Category: declaration -->
<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 declares a decimal-format, which controls the interpretation of a picture string used by the format-number function. If there is a name attribute, then the element declares a named decimal-format; otherwise, it declares the default decimal-format. The value of the name attribute is a QName, which is expanded as described in [4.1 Qualified Names]. [ERR093] It is a static error to declare either the default decimal-format or a decimal-format with a given name more than once (even with different import precedence), unless it is declared every time with the same value for all attributes (taking into account any default values). If a stylesheet does not contain a declaration of the default 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 function. An outline of the purpose of each attribute is given below; however, the definitive explanations are given later, as part of the description of this algorithm.

The following attributes both control the interpretation of characters in the picture string supplied to the format-number 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.

  • 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 allocates the corresponding set of Unicode digit characters to represent the values 0 to 9.

The following attributes control the interpretation of characters in the picture string supplied to the format-number function. In each case the value must be a single character.

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

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

14.4.2 Processing the Picture String

The behavior of the format-number function is described here by means of an algorithm; an implementation may use any algorithm that delivers the same result.

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, percent-sign, per-mille-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters are classified as passive characters.

Formatting is centered around the decimal-separator-sign, which can have a whole-part before and fractional-part after. The passive characters in the pattern string define a prefix and suffix portion.

The evaluation of the format-number function is described below in two phases, an anaysis 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.

Issue (decimal-format-grouping-uniformity): In format-number() all grouping separators except the last are ignored. Internationalization experts may want to make a case for non-uniform grouping sizes, in which case each occurrence of the grouping-separator must be taken as significant. (Note, this issue replaces issue 66).

14.4.3 Analysing the Picture String

This phase of the algorithm analyses 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. In the third column of this table, the word "single" means the one picture string that formats both positive and negative numbers, as contrasted to the two "positive" and "negative" sub-pictures that occur when the whole pattern has a pattern-separator.

[ERR095] The picture string must conform to the following rules . It is a dynamic error if the picture string does not satisfy these rules. The processor must either signal the error, or must recover by ignoring those characters in the supplied picture string that make the picture string invalid. If a valid picture string cannot be constructed, the processor may recover by returning the string obtained by applying the string function to the supplied number.

Note that in these rules "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 sub-picture must not contain a pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values; if there is only one, then it is taken as the positive sub-picture, and the negative sub-picture will be the same except for a leading minus-symbol.
  • 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 a zero-digit-sign or digit-sign and that is followed by another zero-digit-sign or digit-sign.
  • A picture-string must not contain the character ¤ (Unicode #x00a4)
  • A sub-picture must not contain a grouping-separator-sign adjacent to a decimal-separator-sign.
  • A sub-picture must not contain a percent-sign or per-mille-sign in an illegal position.

    Ed. Note: see issue below: what are the legal positions?

  • A sub-picture must not contain a digit-sign that is preceded by a decimal-separator-sign and followed by a zero-digit-sign, or one that is preceded by a zero-digit-sign and followed by a decimal-separator-sign.

Inconsistent spacing of grouping separators is not an error. The only significant grouping separators are those closest to the decimal separator, on either side of it. Any others are ignored.

Issue (format-currency-sign): Should the prohibition on ¤ in the picture of format-number continue?

Issue (scientific-notation): There is a requirement to allow scientific notation in format-number (it is permitted in the JDK 1.2 version of the original specification). The Working Group intends to add this capability before final publication of XSLT 2.0.

The following variables apply to the picture string as a whole:

  • digit-range-mapping (boolean, initially false): Indicates whether the standard ASCII digits (0-9) have been replaced by another set of digits. This property applies to the picture string as a whole, and is derived from the xsl:decimal-format declaration rather than the pattern string. If zero-digit is not "0", set digit-range-mapping to true and populate a mapping table for digits 0-9 (output characters for digits 1-9 must bear the same relationship to Basic Latin digits 1-9 as the requested zero-digit bears to Basic Latin digit 0).

  • two-sub-pictures (boolean initially false): Indicates whether positive and negative sub-pictures exist. It is true if the picture string includes a pattern-separator-sign. This variable applies to the picture string as a whole.

The following variables each have two instances, one that applies to positive numbers, and one that applies to negative numbers: the picture string as a whole, if two-sub-pictures is false, or to the positive sub-picture alone if two-sub-pictures is true:

  • fractional-part-grouping (boolean, initially false): Indicates whether the fractional-part will be grouped.

  • fractional-part-grouping-size (numeric, initially zero): Indicates the grouping-size for the fractional-part.

  • integer-mode (boolean, initially true): Indicates whether the pattern lacks a decimal-separator and hence forces output as an integer.

  • is-percent (boolean, initially false). Indicates whether the number is to be processed as a percentage.

  • is-per-mille (boolean, initially false). Indicates whether the number is to be processed as a per-mille.

  • maximum-fractional-part-size (numeric, initially zero): Indicates the largest number of digits possible for the fractional-part.

  • maximum-whole-part-size (numeric, initially one). Indicates the largest number of digits possible for the whole-part.

  • minimum-fractional-part-size (numeric, initially zero). Indicates the smallest number of digits possible for the fractional-part.

  • minimum-whole-part-size (numeric, initially one). Indicates the smallest number of digits possible for the whole part.

  • overflow-threshold (numeric, initially 10). The value is always a power of 10; it indicates the smallest number that is too large to fit the whole-part.

  • prefix (string, initially empty). Indicates the string of passive characters to appear before the number.

  • prefix-exists (boolean, initially false). Indicates whether the prefix is non-null.

  • suffix (string, initially empty). Indicates the string of passive characters to appear after the number.

  • suffix-exists (boolean, initially false). Indicates whether the suffix is non-null.

  • whole-part-grouping (boolean, initially false). Indicates whether the whole-part will be grouped.

  • whole-part-grouping-size (numeric, initially zero). Indicates the grouping-size for the whole-part.

The following variables apply to the negative sub-picture, when there are two sub-pictures:

  • neg-fractional-part-grouping (boolean, initially false). Indicates, for negative numbers, whether the fractional-part will be grouped.

  • neg-fractional-part-grouping-size (numeric, initially zero). Indicates, for negative numbers, the grouping size for the fractional-part.

  • neg-integer-mode (boolean, initially true). Indicates, for negative numbers, whether the pattern lacks a decimal-separator and hence forces integer output.

  • neg-maximum-fractional-part-size (numeric, initially zero). Indicates, for negative numbers, the largest number of digits possible for the fractional-part.

  • neg-maximum-whole-part-size (numeric, initially one). Indicates, for negative numbers, the largest number of digits possible for the whole-part.

  • neg-minimum-fractional-part-size (numeric, initially 0). Indicates, for negative numbers, the smallest number of digits possible for the fractional-part.

  • neg-minimum-whole-part-size (numeric, initially one). Indicate, for negative numbers, the smallest number of digits possible for the whole-part.

  • neg-overflow-threshold (numeric, initially 10). Indicates, for negative numbers, the absolute value of the smallest number that is too large to fit the whole-part (always a power of 10).

  • neg-is-percent (boolean, initially false). Indicates, for negative numbers, whether the number is to be processed as a percentage.

  • neg-is-per-mille (boolean, initially false). Indicates, for negative numbers, whether the number is to be processed as a per-mille.

  • neg-prefix (string, initially empty). Indicates, for negative numbers, the string of passive characters to appear before the number.

  • neg-prefix-exists (boolean, initially false). Indicates whether the prefix for negative numbers is non-null.

  • neg-suffix (string, initially empty). Indicates, for negative numbers, the string of passive characters to appear after the number.

  • neg-suffix-exists (boolean, initially false). Indicates, for negative numbers, whether the suffix is non-null.

  • neg-whole-part-grouping (boolean, initially false). Indicates, for negative numbers, whether the whole-part will be grouped.

  • neg-whole-part-grouping-size (numeric, initially zero). Indicates, for negative numbers, the grouping size for the whole-part.

Issue (position-percent): Must the percent or per-mille sign be immediately after the last digit or decimal-separator? Suggestion: keep the set of legal positions down to the minimum set that will satisfy all world cultures.

These variables are set using the following algorithm. If there are two sub-pictures, then the algorithm is 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.

  1. If zero-digit is not "0", set digit-range-mapping to true and populate a mapping table for digits 0-9 (output characters for digits 1-9 must bear the same relationship to Basic Latin digits 1-9 as the requested zero-digit bears to Basic Latin digit 0). If two-sub-pictures is true, perform the remaining steps separately for the positive and negative patterns, otherwise set the properties for negative numbers to the same values as the positive-number properties, except for neg-prefix and neg-prefix-exists, which are always set separately.

  2. Look for a decimal-separator-sign within the sub-picture. If one is found, set integer-mode to false. If none is found, leave integer-mode set to true; add an implicit decimal-separator-sign just after the last (least significant) digit-sign or zero-digit-sign in the sub-picture; and leave the minimum-fractional-part-size and maximum-fractional-part-size set to zero.

  3. From the decimal-separator-sign, step through characters in order of increasing significance (that is, to the left) looking for an occurrence of the grouping-separator-sign. If none is found before the first occurrence of a passive character, leave the whole-part-grouping property set to false. When one is found, set the whole-part-grouping property to true and the whole-part-grouping-size to the number of characters between the decimal-separator-sign and the first grouping-separator-sign. (All other occurrences farther left are ignored.)

  4. If there is a digit-sign immediately to the left of the (actual or implied) decimal-separator-sign, set the minimum-whole-part-size to zero (unless integer-mode is true, in which case leave it at 1) and step through the characters in order of increasing significance (that is, to the left) looking for a passive character. If there is a zero-digit-sign immediately to the left of the decimal-separator, step through the characters in order of increasing significance (that is, to the left) looking for either a digit-sign or passive character. As soon as a character other than a zero-digit-sign or grouping-separator-sign is found, set minimum-whole-part-size to the number of zero-digit-signs found on this side of the decimal-separator. When a passive character is encountered, set the maximum-whole-part-size to the total number of digit-sign and zero-digit-sign characters found on this side of the decimal-separator. Set overflow-threshold to ten raised to the power of maximum-whole-part-size.

  5. Take all characters from the just-encountered passive character to the beginning of the picture string as the prefix. Set prefix-exists to true if there are any. If two-sub-pictures is false, set the prefix for negative numbers by copying the prefix for positive numbers (if any) and then appending the minus-sign character (i.e., making it the character that will be adjacent to the following number), and set neg-prefix-exists to true. If two-sub-pictures is true, then when analyzing the negative pattern, take all characters from the first-encountered (rightmost) passive character to the beginning of the format string as the neg-prefix. Set neg-prefix-exists true if there are any.

  6. From the (actual) decimal-separator-sign, step through characters in order of decreasing significance (that is, to the right) looking for an occurrence of the grouping-separator-sign. If none is found before the first occurrence of a passive character, leave fractional-part-grouping set to false. When one is found, set fractional-part-grouping to true and fractional-part-grouping-size to the number of characters between the decimal-separator-sign and the first grouping-separator-sign. (All other occurrences further to the right are ignored.)

  7. If there is a digit-sign adjacent to the decimal-separator-sign on the fractional side, leave the minimum-fractional-part-size set to zero and step through the characters in order of decreasing significance (that is, to the right) looking for a passive character, percent-sign, or per-mille-sign. If there is a zero-digit-sign adjacent to the decimal-separator-sign, step through the characters in order of decreasing significance (that is, to the right) looking for an either a digit-sign, passive character, percent-sign, or per-mille-sign. As soon as a character other than zero-digit-sign or grouping-separator-sign is found, set minimum-fractional-part-size to the number of zero-digit-signs found on this side of the decimal-separator-sign. When a passive character, percent-sign, or per-mille-sign is encountered, set maximum-fractional-part-size to the total number of digit-sign and zero-digit-sign characters found on this side of the decimal-separator.

  8. If a percent-sign was encountered, set is-percent to true. If a per-mille-sign was encountered, set is-per-mille to true.

  9. Take all characters from the first-encountered passive character on the fractional side, or the percent-sign or per-mille-sign, to the end of the format string as the suffix. Include the percent-sign or per-mille-sign, if any, as the first character of the suffix. Set suffix-exists true if there are any characters.

Reminder: if two-sub-pictures is true, perform all steps except the first one above once for each sub-picture. Otherwise, set all the attributes for the negative pattern except neg-prefix and neg-prefix-exists to be the same as the corresponding values for the positive pattern. Always set neg-prefix and neg-prefix-exists as described in step 5.

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 have the minus-sign character appended.

14.4.4 Formatting the Number

This algorithm describes the second phase of processing of the format-number function. It takes as input a number to be formatted (referred to as the input number), and the variables set up by analysing the xsl:decimal-format declaration and the picture string, as described above. The result of this algorithm is a string, which forms the return value of the format-number function.

The algorithm for this second stage of processing is as follows:

  1. If the input number is NaN (not a number), return the concatenation of the prefix, the specified NaN-symbol, and the suffix, where the prefix and suffix are taken from the positive sub-picture if two-sub-pictures is true.

  2. In the rules below, select the set of variables that apply to positive numbers if the input number is positive, and the set of variables for negative numbers otherwise. Negative zero is taken as negative, positive zero as positive.

  3. If the input number is positive or negative infinity, return the concatenation of the appropriate prefix, the infinity-symbol, and the appropriate suffix.

  4. If the input number is negative infinity, return the concatenation of the neg-prefix, the infinity-symbol, and the neg-suffix.

  5. If the input number is positive (>= 0) and is-percent is true, multiply the number by 100. If the number is positive and is-per-mille is true, multiply the number by 1000. If the number is negative and neg-is-percent is true, multiply the number by 100. If the number is negative and neg-is-per-mille is true, multiply the number by 1000. The resulting number is referred to below as the adjusted number.

  6. [ERR096] It is a dynamic error if the absolute value of the adjusted number is numerically greater than or equal to the overflow-threshold. The processor may signal the error, or may recover by formatting the number as if the formatting picture were extended to the left (after any prefix) with a sufficient number of digit-sign characters to accommodate the adjusted number.

  7. (Integer case) If the adjusted number is positive and integer-mode is true, or if it is negative and neg-integer-mode is true, round the adjusted number to the nearest integer using the rules for the XPath round function. If the adjusted number is negative, use the properties pertaining to the negative sub-pattern. If the number of digits is less than minimum-whole-part-size, prepend zero-digit-sign characters to pad out to that size. Map all digits if the digit-range-mapping property is true. If whole-part-grouping is true, count digits from the decimal-separator-sign in the direction of increasing significance, and when more than whole-part-grouping-size digits are found, insert a grouping-separator-sign to set off whole-part-grouping-size digits on the less significant side, repeating so that there are not more than whole-part-grouping-size digits in any group, and the leading character of the whole-part is a digit rather than grouping-separator-sign. If the adjusted number is positive, Return the concatenation of the prefix, the string conversion of the number, and the suffix. If the adjusted number is negative, return the concatenation of the neg-prefix, the string conversion of the number, and the neg-suffix.

  8. Render the whole-part as a string. If the adjusted number is negative, use the properties pertaining to the negative sub-picture. If the number of digits is less than minimum-whole-part-size, prepend zero-digit characters to pad out to that size. Map all digits if the digit-range-mapping property is true. If whole-part-grouping is true, count digits from the decimal separator in the direction of increasing significance, and when more than whole-part-grouping-size digits are found, insert a grouping-separator to set off whole-part-grouping-size digits on the less significant side, repeating so that there are not more than whole-part-grouping-size digits in any group, and the leading character of the whole-part is a digit rather than grouping-separator-sign. (Note: the result of this step could be a zero-length string.)

  9. Render the fractional-part as a string. If the adjusted number is negative, use the properties pertaining to the negative sub-pattern. If the number of digits is less than minimum-fractional-part-size, append zero-digit-sign characters to pad out to that size. If the number of digits is greater than maximum-fractional-part-size, set the least significant displayed digit by rounding as if it were the whole-part and following digits were the fractional-part in the XPath rounding procedure, but ignoring any sign that may result. Map all digits if the digit-range-mapping property is true. If fractional-part-grouping is true, count digits from the decimal-separator-sign in the direction of decreasing significance, and when more than fractional-part-grouping-size digits are found, insert a grouping-separator to set off fractional-part-grouping-size digits on the more significant side, repeating so that there are not more than fractional-part-grouping-size digits in any group, and the trailing character of the fractional-part is a digit rather than grouping-separator. (Note: the result of this step could be a zero-length string. It could also be a string of zeroes.)

  10. If the adjusted number is positive,Return the concatenation of the prefix, the whole-part as rendered above, the decimal-separator-sign, the fractional-part as rendered above, and the suffix. If the adjusted number is negative, return the concatenation of the neg-prefix, the whole-part as rendered above, the decimal-separator-sign, the fractional-part as rendered above, and the neg-suffix.

14.5 Dynamic XPath Expressions

In certain circumstances, it is useful in a stylesheet to evaluate XPath expressions that are not hard-coded in the stylesheet text. For example, XPath expressions may be read from the source document, or supplied to the stylesheet as parameters, or constructed as a string from run-time information. A common requirement is for an application to allow the user to select the key that should be used for sorting output, and a natural mechanism for implementing this is to allow the sort key to be passed to the stylesheet as a string parameter, with the string containing an XPath expression to be used as the sort key.

14.6 Miscellaneous Additional Functions

Issue (format-date-time): There is a need for an additional function to format dates and times.

Issue (parse-and-serialize-functions): Should we add functions parse() and serialize()? The parse() function would take source XML as a string, and return a document node; the serialize() function would do the reverse.

Issue (regexp-support): Should we add support for regular expression matching at the XSLT level?

14.6.1 current()

Function: item current()

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. For example,

<xsl:apply-templates select="//glossary/item[@name=current()/@ref]"/>

will process all item 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/item[@name=./@ref]"/>

which means the same as

<xsl:apply-templates select="//glossary/item[@name=@ref]"/>

and so would process all item elements that have a glossary parent element and that have a name attribute and a ref attribute with the same value.

[ERR097] It is a static error to use the current function in a pattern.

[ERR098] It is a dynamic error if the current function is called while evaluating a pattern. The processor must signal the error.

If the current function is used within a pattern, its value is the node that is being matched against the pattern.

14.6.2 unparsed-entity-uri()

Function: string unparsed-entity-uri(string)

The unparsed-entity-uri returns the URI of the unparsed entity with the specified name in the context document (see [3.3 Unparsed Entities]). It returns the empty string if there is no such entity.

14.6.3 generate-id()

Function: string generate-id(node?)

The generate-id function returns a string that uniquely identifies a given node. The unique identifier must consist of ASCII alphanumeric characters and must start with an alphabetic character. Thus, the string is syntactically an XML name. An implementation is free to generate an identifier in any convenient way provided that it always generates the same identifier for the same node and that different identifiers are always generated from different nodes. An implementation is under no obligation to generate the same identifiers each time a document is transformed. There is no guarantee that a generated unique identifier will be distinct from any unique IDs specified in the source document. If the argument is an empty sequence, the empty sequence is returned. If the argument is omitted, it defaults to the context node.

[ERR099] It is a dynamic error if value of the argument is a sequence other than an empty sequence or a sequence containing a single node. If the first item in the sequence is not a node, the processor must signal the error. If the first item in the sequence is a node, the processor may signal the error, or may recover by returning the string that identifies the first node in the sequence.

Ed. Note: This should be covered by the standard fallback type conversion rules, but in the current XPath draft, no fallback rules are given for functions that expect a single node.

14.6.4 system-property()

Function: string system-property(string)

The argument must evaluate to a string that is a QName. The QName is expanded into a name using the namespace declarations in scope for the expression. [ERR100] It is a 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. The processor must signal these errors.

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 empty string should be 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.0". The value will always be a string in the lexical space of the decimal data type defined in XML Schema (see [XML Schema]) This allows the value to be converted to a number for the purpose of magnitude comparisons.
  • xsl:vendor, a string identifying the implementor of the processor
  • xsl:vendor-url, a string containing a URL identifying the implementor of the processor; typically this is the host page (home page) of the implementor's Web site.
  • xsl:product-name, a string containing the name of the implementation, as defined by the implementor. 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 implementor. This should normally vary from one release of the product to the next, and at the discretion of the implementor it may also vary across different execution platforms.

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.

NOTE: An implementation must not return the value 2.0 as the value of the xsl:version system property unless it is conformant to XSLT 2.0. It is recognized that vendors who are enhancing XSLT 1.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.0, this specification cannot define their behavior. However, implementors of such products are encouraged to return a value for the xsl:version system property that is intermediate between 1.0 and 2.0, and to provide the element-available and function-available functions to allow users to test which features have been fully implemented.

Implementations must not define additional system properties in the XSLT namespace.

15 Messages

<!-- Category: instruction -->
<xsl:message
  terminate = "yes" | "no">
  <!-- Content: content-constructor -->
</xsl:message>

The xsl:message instruction sends a message in an implementation-defined way. The content of the xsl:message instruction is a content constructor. The content constructor is evaluated, and the resulting sequence of nodes is added to a newly-created document node, to create an XML document. This XML document forms the content of the message. The document is typically serialized and output to an implementation-defined destination. The result of the xsl:message instruction is an empty sequence.

Issue (terminate-as-avt): In xsl:message, should the terminate attribute be changed to be an attribute value template?.

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

If the terminate attribute has the value yes, then the processor must terminate processing after sending the message. The default value is no.

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>
    <xsl:value-of select="$messages/message[@name=$name]"/>
  </xsl:message>
</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>

16 Extensibility and Fallback

XSLT allows two kinds of extension, extension instructions and extension functions. An extension instruction is an element within a content constructor that is in a namespace (not the XSLT namespace) designated as an extension namespace. An extension function is a function that is available for use within an XPath expression, other than a core function defined in the XPath specification, an additional function defined in this XSLT specification, 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 does not require 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 should happen 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.

16.1 Extension Functions

Issue (support-SOAP): Should we define a binding to web services accessible using SOAP?

If the FunctionName used in a FunctionCall within an XPath expression is not an NCName (that is, if it contains a colon), and if the stylesheet contains no stylesheet function with a matching expanded-QName, then it is treated as a call to an extension function. The QName used as the FunctionName is expanded using the namespace declarations in scope at the point in the stylesheet where the expression appears.

16.1.1 Testing Availability of Functions

The function-available function can be used with the xsl:choose and xsl:if instructions to explicitly control how a stylesheet should behave if a particular extension function is not available.

Function: boolean function-available(string)

A function name is said to be available if it matches the name of a core function defined in XPath, or the name of an additional function defined in this XSLT specification, or the name of a stylesheet function, or if the processor is able to locate an implementation of an extension function with a matching name.

The function-available function returns true if the function name supplied as its argument is available; otherwise it returns false.

The value of the first 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. The function-available function returns true if and only if the expanded-QName is the name of a function in the function library. If the expanded-QName has a non-null namespace URI, then it refers to a stylesheet function or extension function; otherwise, it refers to a function defined by XPath or XSLT.

[ERR101] It is a 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. The processor must either signal the error, or must recover by returning the value false.

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 number of arguments expected, nor their types.

[ERR102] It is a dynamic error if a FunctionCall within an XPath expression is evaluated, when the function in question is not available. The processor must signal the error. An implementation must not signal a static error merely because an expression contains a call to an extension function for which no implementation is available.

16.1.2 Calling Extension Functions

If the FunctionName used in a FunctionCall within an XPath expression identifies an extension function, then to evaluate the FunctionCall, the processor will first evaluate each of the arguments in the FunctionCall. 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.

[ERR103] It is a 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.The processor must signal the error.

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.
NOTE: Implementations are not required to perform full validation of values returned by extension functions. For example, the effect of returning a string containing characters that are not legal XML characters is implementation-defined.
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.

16.1.3 External Objects

Issue (external-objects): Do we want to keep the description of external objects (which was introduced in the XSLT 1.1 Working Draft)? What are the data model implications?

Support for extension functions introduces an additional data-type into the expression language. This additional data type is called an external object. A variable may be bound to an object of type external object instead of one of the XPath data-types. An external object represents an object that is not convertible to one of the XPath data types, which is created by an external programming language and returned by an extension function. The external object, as an XPath value, can be regarded as a wrapper for an object created by, and processible using, the programming language in which the extension functions are written. Expressions can only return values of type external object by referencing variables of type external object or by calling extension functions that return an external object.

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 operations that may be performed on an external object are implementation-defined.

[ERR104] An external object may only be passed as an argument to another extension function, provided the other extension function is written to accept objects of this type. The effect of performing any other operations, for example comparing two external objects for equality, or converting the external object to a string or boolean, or using an external object as an item within a sequence, or copying an external object to the result tree, is in general implementation-defined, and will cause a dynamic error if the operation is not supported. The processor must signal the error.

[ERR105] It is a dynamic error to attempt to copy an external object to a result tree, or to convert it (implicitly or explicitly) to any of the XPath data types. The processor must signal the error. So, for example, if the myvar variable is bound an external object, then the following are dynamic errors, which a processor must signal:

  • <xsl:copy-of select="$myvar"/> <!-- Cannot copy to result tree -->

  • <xsl:value-of select="$myvar"/> <!-- Cannot implicitly convert to String -->

  • <xsl:value-of select="string($myvar)"/> <!-- Cannot explicitly convert to String -->

If an external object is passed to an extension function with an expanded-QName whose namespace URI is different from the namespace URI of the expanded-QName of the extension function that returned that external object, the behavior is implementation-defined.

An extension function can be used to convert the argument to a string or return an XML fragment to be copied to the result tree if desired. For example, assuming the myext:print() extension function accepts an argument of a compatible data type and returns a string, the following is allowed:

<!-- Convert to
string with extension function --> <xsl:value-of
select="myext:print($myvar)"/> 

Ed. Note: Define the idea that an external object "wraps" an object created by an external programming language.

16.2 Extension Instructions

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 content 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 content constructor, non-XSLT top-level elements are not extension elements as defined here, and nothing in this section applies to them.

16.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 [2.3 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 attributes is a whitespace-separated list of namespace prefixes. The namespace bound to each of the prefixes is designated as an extension namespace. [ERR106] It is a static error if there is no namespace bound to the prefix on the element bearing the [xsl:]extension-element-prefixes attribute. The default namespace (as declared by xmlns) may be designated as an extension namespace by including #default in the list of namespace prefixes. 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.

16.2.2 Testing Availability of Instructions

The element-available function can be used with the xsl:choose and xsl:if instructions to explicitly control how a stylesheet should behave if a particular extension instruction is not available.

Function: boolean element-available(string)

The value of the first 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.

[ERR107] It is a 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. The processor must either signal the error, or must recover by returning the value false.

If the processor does not have an implementation of a particular extension instruction available, then the element-available function must return false for the name of the element. When such an extension instruction is evaluated, then the processor must perform fallback for the element as specified in [16.2.3 Fallback]. An implementation must not signal an error merely because a template contains an extension instruction for which no implementation is available.

If the processor has an implementation of a particular extension instruction available, then the element-available function must return true for the name of the element.

16.2.3 Fallback

<!-- Category: instruction -->
<xsl:fallback>
  <!-- Content: content-constructor -->
</xsl:fallback>

Normally, evaluating an xsl:fallback element returns an empty sequence: the content of the xsl:fallback element is ignored. However, when a processor performs fallback for an instruction element, if the instruction element has one or more xsl:fallback children, then the content of each of the xsl:fallback children must be evaluated; if it has no xsl:fallback children, a dynamic error must be signaled. The content of an xsl:fallback element is a content constructor, and when performing fallback, the value returned by the xsl:fallback element is the result of evaluating this content constructor.

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.0, is evaluated with region of the stylesheet for which forwards compatible behavior.

17 Result Trees

The output of a transformation is a set of final result trees. One of these is the principal result tree, the others are referred to as secondary result trees. The principal result tree is the current result tree when the transformation is initiated; a secondary result tree is created using an xsl:result-document instruction, and becomes the current result tree while the xsl:result-document instruction is being evaluated.

Ed. Note: The term "final result tree" seems oxymoronic. Perhaps we should just call them "result trees". In this case the term "current result tree" needs to change, perhaps to "current destination", to reflect the fact that the destination might be a temporary tree rather than a [final] result tree.

The way in which a final result tree is delivered to an application is implementation-defined.

A final result tree has a 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 URI.

NOTE: The URI of the result tree is not the same thing as the URI of its serialized representation on disk, if any. For example, a server (or browser client) might store the result trees only in memory, or in an internal disk cache. As long as it satisfies requests for those URIs, it is irrelevant where they are actually written on disk, if at all.

The URI of the principal result tree is specified using the href attribute of an xsl:principal-result-document declaration; the URI of a secondary result tree is specified using the href attribute of an xsl:result-document instruction. If the URI for a secondary result tree is relative, it is resolved relative to the base URI of the principal result tree. If the URI for the principal result tree is relative, it is resolved relative to an implementation-defined base URI.

NOTE: It will often be the case that one result tree contains links to another result tree produced during the same transformation, in the form of a relative URI. 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.
NOTE: The URI of a result tree is unrelated to the base URI of its document node.

Serialization of final result trees is described further in [18 Serialization]

17.1 The Principal Result Tree

<!-- Category: declaration -->
<xsl:principal-result-document
  format = qname
  href = { uri-reference } />

The xsl:principal-result-document element is used to define the URI of the principal result tree, and optionally to specify the output format to be used for serializing this tree.

The value of the format attribute, if specified, must be a QName. The QName is expanded using the namespace declarations in scope for the xsl:principal-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 result tree (see [18 Serialization]), if the result tree is serialized. If the format attribute is omitted, the unnamed output definition is used to control serialization of the principal result tree.

[ERR108] It is a static error if the value of the format attribute is not a valid QName, or if it does not match the expanded-QName of an output definition in the stylesheet.

If there is more than one xsl:principal-result-document element at the top level of the stylesheet, the one with highest import precedence is used. [ERR109] It is a static error if there is more than one xsl:result-document element at the top level of the stylesheet with the same import precedence, unless there is also another xsl:result-document element at the top level of the stylesheet with a higher import precedence.

If there is no xsl:principal-result-document element at the top level of the stylesheet, the effect is the same as specifying a single top-level xsl:result-document element with no attributes.

The href attribute defines the URI of the principal result tree. The attribute value template is expanded using a singleton focus based on the document node of the principal source document. The effective value of the attribute must be a URI. 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 must be accepted.

If the effective value is a relative URI, then it is resolved relative to an implementation-defined base URI.

The href attribute may be omitted, in which case the URI of the principal result tree is implementation-defined.

NOTE: The main reason to specify a URI for the principal result tree is to allow it to be referenced by links from a secondary result tree.

17.2 Secondary Result Trees

<!-- Category: instruction -->
<xsl:result-document
  format = qname
  href = { uri-reference }>
  <!-- Content: content-constructor -->
</xsl:result-document>

The xsl:result-document instruction is used to create a secondary result tree. The content of the xsl:result-document element is a content constructor; this is evaluated to create a sequence of nodes. A document node is created with this sequence of nodes as its children. The tree rooted at this document node forms the secondary result tree.

The xsl:result-document instruction defines the URI of a secondary final result tree, and may optionally specify the output format to be used for serializing this tree.

The value of the format attribute, if specified, must be a 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 result tree (see [18 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.

[ERR110] It is a static error if the value of the format attribute is not a valid QName, or if it does not match the expanded-QName of an output definition in the stylesheet.

The href attribute is mandatory. The effective value of the attribute must be a URI. 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 must be accepted.

If the effective value is a relative URI, then it is resolved relative to the URI of the principal result tree.

A processor may allow a secondary result tree to be serialized, just as it may allow the principal result tree to be serialized. Serialization is described in [18 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 secondary result trees. An implementation that does not support the serialization of secondary result trees must ignore the format attribute. Such an implementation must provide the application with some means of access to the (un-serialized) result tree, using its URI to identify it.

For example, the following would create a principal result document specifying an HTML frameset with two frames, together with two secondary result documents, one for the contents of each frame:

<xsl:template match="/">
  <html>
    <head><title>Frame example</title></head>
    <frameset cols="20%, 80%">
      <frame src="toc.html"/>
      <xsl:result-document href="toc.html">
        <html>
          <head><title>Table of Contents</title></head>
          <body>
             <xsl:apply-templates mode="toc" select="*"/>
          </body>
        </html>
      </xsl:result-document>
      <frame src="body.html"/>
      <xsl:result-document href="body.html">
        <html>
          <head><title>Body</title></head>
          <body>
             <xsl:apply-templates select="*"/>
          </body>
        </html>
      </xsl:result-document>
    </frameset>
  </html>
</xsl:template>

[ERR111] It is a dynamic error to evaluate the xsl:result-document instruction when the current result tree is neither the principal result tree, nor a secondary result tree. The processor must signal the error.. This means, for example, that it is an error to use xsl:result-document when the current result tree is a temporary tree created using xsl:variable, or a tree created using xsl:message, xsl:attribute, etc.

[ERR112] It is a dynamic error for a transformation to generate two or more result trees with the same URI. The processor must signal the error.

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 content constructor it is part of.

Issue (residue-on-termination): We need to make it clear that an implementation is (or is not) allowed to leave serialized secondary output documents in filestore following a dynamic error that causes stylesheet termination.

Issue (reading-output-documents): We need to make it clear that a stylesheet is not allowed to use the document function to access a serialized secondary output document created during the same transformation.

18 Serialization

A processor may output a final result tree as a sequence of bytes, although it is not required to be able to do so (see [19 Conformance]). Stylesheet authors can use the xsl:output declaration to specify how they wish result trees to be serialized. If a processor serializes the result tree, it should do so as specified by these elements; however, it is not required to do so.

<!-- Category: declaration -->
<xsl:output
  name = qname
  method = { "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname }
  version = { nmtoken }
  encoding = { string }
  omit-xml-declaration = { "yes" | "no" }
  standalone = { "yes" | "no" }
  doctype-public = { string }
  doctype-system = { string }
  cdata-section-elements = { qnames }
  indent = { "yes" | "no" }
  media-type = { string }
  include-content-type = { "yes" | "no" }
  escape-uri-attributes = { "yes" | "no" } />

The xsl:output declaration is optional; if used, it must always appear as a top-level element within a stylesheet.

All attributes on xsl:output except the name attribute are interpreted as attribute value templates. Expressions recognized in the attributes of xsl:output are evaluated with a singleton focus based on the document node of the principal source document. [ERR113] It is a dynamic error if the value of an attribute does not conform to the rules listed below. The processor must either signal the error, or must recover by using the default value for that attribute.

Issue (avts-in-xsl-output): Review the decision to allow attribute value templates in xsl:output.

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 effective value of its name attribute, if any. All the xsl:output declarations in a stylsheet that share the same name are grouped into a named output definition; those that have no name are grouped into a a single unnamed output definition.

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.

All the xsl:output elements making up an output definition are effectively merged. For the cdata-section-elements attribute, the output definition uses the union of the effective values from all the constituent xsl:output declarations. For other attributes, the output definition uses the effective value of that attribute from the xsl:output declaration with the highest import precedence. [ERR114] It is a dynamic error if two xsl:output declarations within an output definition specify explicit values for the same attribute (other than cdata-section-elements), with the effective values of the attributes being not equal, and with neither of these declarations being overridden by an xsl:output declaration with higher import precedence that specifies an explicit value for the same attribute. The processor must either signal the error, or must recover by using the value that occurs last in declaration order.

The values of attributes are defaulted after the xsl:output elements have been merged; different output methods may have different default values for an attribute.

An implementation may allow the attributes of the xsl:output declaration to be overridden using the API that controls the transformation.

Before a final result tree is serialized, namespace fixup is performed (see [3.5 Namespace Fixup]).

The location to which 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 any relative URI used to reference one result tree from another remains valid when all the result trees are serialized. So, with the example in [17.2 Secondary Result Trees], the HTML document produced by serializing the principal result tree would contain valid references to the HTML documents produced by serializing the result trees denoted by href="toc.html" and href="body.html" respectively.

The method attribute on the xsl:output element identifies the overall method that should be used for outputting the result tree. [ERR115] The value must be a valid QName. If the QName does not have a prefix, then it identifies a method specified in this document 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 [4.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 is chosen as follows. If the document node of the 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:

In all other cases, the default output method is xml.

The default output method should be used if there are no xsl:output elements or if none of the xsl:output elements specifies a value for the method attribute.

The other attributes on xsl:output provide parameters for the output method. The following attributes are allowed:

The detailed semantics of each attribute will be described separately for each output method for which it is applicable. If the semantics of an attribute are not described for an output method, then it is not applicable to that output method.

Issue (output-newlines): Do we want to say anything about the representation of line endings when using the text output method? Do we want to provide any user control in this area?

Issue (char-representation): Should we provide some control over the way characters are serialized, e.g. as numeric character references or HTML entity references?

18.1 XML Output Method

The xml output method outputs the result tree as an XML entity that should satisfy the rules for either a well-formed XML document entity, or a well-formed XML external general parsed entity, or both. If the document node of the result tree has a single element node child and no text node children, then the serialized output should be a well-formed XML document entity conforming to the XML Namespaces Recommendation [XML Names]. If the result tree does not take this form, then the serialized output should be an entity which, when referenced within a trivial XML document wrapper like this

<!DOCTYPE doc [
<!ENTITY e SYSTEM "entity-URI">
]>
<doc>&e;</doc>

where entity-URI is a URI for the entity, produces a document which should itself be a well-formed XML document conforming to the XML Namespaces Recommendation [XML Names].

In addition, the output should be such that if a new tree was constructed by parsing the XML document as specified in [3 Data Model], then the new tree would be the same as the result tree, with the following possible exceptions:

Issue (result-tree-PSVI): The rules for serialization of the result tree consider it only as an infoset; the rules need to be enhanced to allow for (potential loss of) PSVI information on the tree.

[ERR116] It is a serialization error to request the output of a document type declaration, or of a standalone attribute, if the result tree contains text nodes or multiple element nodes as children of the root node. The processor may signal the error, or may recover by ignoring the request to output a document type declaration or standalone attribute.

The version attribute specifies the version of XML to be used for outputting the result tree. If the processor does not support this version of XML, it should use a version of XML that it does support. The version output in the XML declaration (if an XML declaration is output) should correspond to the version of XML that the processor used for outputting the result tree. The value of the version attribute should match the VersionNum production of the XML Recommendation [XML]. The default value is 1.0.

The encoding attribute specifies the preferred encoding to use for outputting the result tree. Processors are required to respect values of UTF-8 and UTF-16. [ERR117] A serialization error occurs when an output encoding other than UTF-8 or UTF-16 is requested, if the implementation does not support that encoding. The processor may signal the error, or may recover by using UTF-8 or UTF-16 instead. The processor must not use an encoding whose name does not match the EncName production of the XML Recommendation [XML]. If no encoding attribute is specified, then the processor should use either UTF-8 or UTF-16.

It is possible that the result tree will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where XML recognizes character references (i.e. in the value of an attribute node or text node), then the character should be output as a character reference. [ERR118] A serialization error occurs if such a character appears in a context where character references are not allowed (for example if the character occurs in the name of an element). The processor should signal the error.

If the indent attribute has the value yes, then the xml output method may output whitespace in addition to the whitespace in the result tree (possibly based on whitespace stripped from either the source document or the stylesheet) in order to indent the result nicely; if the indent attribute has the value no, it should not output any additional whitespace. The default value is no. The xml output method should use an algorithm to output additional whitespace that ensures that the result if whitespace were to be stripped from the output using the process described in [3.4 Whitespace Stripping] with the set of whitespace-preserving elements consisting of just xsl:text would be the same when additional whitespace is output as when additional whitespace is not output.

NOTE: It is usually not safe to use indent="yes" with document types that include element types with mixed content.

The cdata-section-elements attribute contains a whitespace-separated list of QNames. Each QName is expanded into an expanded-QName using the namespace declarations in effect on the xsl:output element in which the QName occurs; if there is a default namespace, it is used for QNames that do not have a prefix. The expansion is performed before the merging of multiple xsl:output elements into a single effective xsl:output element. If the expanded-QName of the parent of a text node is a member of the list, then the text node should be output as a CDATA section. For example,

<xsl:output cdata-section-elements="example"/>

would cause a literal result element written in the stylesheet as

<example>&lt;foo></example>

or as

<example><![CDATA[<foo>]]></example>

to be output as

<example><![CDATA[<foo>]]></example>

If the text node contains the sequence of characters ]]>, then the currently open CDATA section should be closed following the ]] and a new CDATA section opened before the >. For example, a literal result element written in the stylesheet as

<example>]]&gt;</example>

would be output as

<example><![CDATA[]]]]><![CDATA[>]]></example>

If the text node contains a character that is not representable in the character encoding being used to output the result tree, then the currently open CDATA section should be closed before the character, the character should be output using a character reference or entity reference, and a new CDATA section should be opened for any further characters in the text node.

CDATA sections should not be used except where they have been explicitly requested by the user, either by using the cdata-section-elements attribute, or by using some other implementation-defined mechanism.

NOTE: This is phrased to permit an implementor to provide an option that attempts to preserve CDATA sections present in the source document.

The xml output method should output an XML declaration unless the omit-xml-declaration attribute has the value yes. The XML declaration should include both version information and an encoding declaration. If the standalone attribute is specified, it should include a standalone document declaration with the same value as the value as the value of the standalone attribute. Otherwise, it should not include a standalone document declaration; this ensures that it is both an XML declaration (allowed at the beginning of a document entity) and a text declaration (allowed at the beginning of an external general parsed entity).

The omit-xml-declaration attribute should be ignored if the standalone attribute is present, or if the encoding attribute specifies a value other than UTF-8 or UTF-16.

If the doctype-system attribute is specified, the xml output method should output a document type declaration immediately before the first element. The name following <!DOCTYPE should be the name of the first element. If doctype-public attribute is also specified, then the xml output method should output PUBLIC followed by the public identifier and then the system identifier; otherwise, it should output SYSTEM followed by the system identifier. The internal subset should be empty. The doctype-public attribute should be ignored unless the doctype-system attribute is specified.

The media-type attribute is applicable for the xml output method. The default value for the media-type attribute is text/xml.

18.2 XHTML Output Method

The xhtml output method serializes the result tree as XML, using the HTML compatibility guidelines defined in the XHTML specification.

It is entirely the responsibility of the stylesheet author to ensure that the result tree conforms to the [XHTML 1.0] or [XHTML 1.1] specification. It is not an error if the result tree is invalid XHTML. Equally, it is entirely under the control of the stylesheet author whether the output conforms to XHTML Strict, XHTML Transitional, XHTML Frameset, or XHTML Basic.

The serialization of the result tree follows the same rules as for the xml output method, with the exceptions noted below. These differences are based on the HTML compatibility guidelines published in Appendix C of [XHTML 1.0], which are designed to ensure that as far as possible, XHTML is rendered correctly on user agents designed originally to handle HTML.

18.3 HTML Output Method

The html output method outputs the result tree as HTML; for example,

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

<xsl:output method="html"/>

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

...

</xsl:stylesheet>

The version attribute indicates the version of the HTML. The default value is 4.0, which specifies that the result should be output as HTML conforming to the HTML 4.0 Recommendation [HTML].

The html output method should not output an element differently from the xml output method unless the expanded-QName of the element has a null namespace URI; an element whose expanded-QName has a non-null namespace URI should be output as XML. If the expanded-QName of the element has a null namespace URI, but the local part of the expanded-QName is not recognized as the name of an HTML element, the element should output in the same way as a non-empty, inline element such as span.

The html output method should not output an end-tag for empty elements. For HTML 4.0, the empty elements are area, base, basefont, br, col, frame, hr, img, input, isindex, link, meta and param. For example, an element written as <br/> or <br></br> in the stylesheet should be output as <br>.

The html output method should recognize the names of HTML elements regardless of case. For example, elements named br, BR or Br should all be recognized as the HTML br element and output without an end-tag.

The html output method should not perform escaping for the content of the script and style elements. For example, a literal result element written in the stylesheet as

<script>if (a &lt; b) foo()</script>

or

<script><![CDATA[if (a < b) foo()]]></script>

should be output as

<script>if (a < b) foo()</script>

The html output method should not escape < characters occurring in attribute values.

If the indent attribute has the value yes, then the html output method may add or remove whitespace as it outputs the result tree, so long as it does not change how an HTML user agent would render the output. The default value is yes.

Unless the escape-uri-attributes attribute is present and has the value no, the html output method should escape non-ASCII characters in URI attribute values using the method recommended in [RFC2396] (section 2.4.1).

The html output method may output a character using a character entity reference, if one is defined for it in the version of HTML that the output method is using.

The html output method should terminate processing instructions with > rather than ?>.

The html output method should output boolean attributes (that is attributes with only a single allowed value that is equal to the name of the attribute) in minimized form. For example, a start-tag written in the stylesheet as

<OPTION selected="selected">

should be output as

<OPTION selected>

The html output method should not escape a & character occurring in an attribute value immediately followed by a { character (see Section B.7.1 of the HTML 4.0 Recommendation). For example, a start-tag written in the stylesheet as

<BODY bgcolor='&amp;{{randomrbg}};'>

should be output as

<BODY bgcolor='&{randomrbg};'>

The encoding attribute specifies the preferred encoding to be used. If there is a HEAD element, then unless the include-content-type attribute is present and has the value "no", the html output method should add a META element immediately after the start-tag of the HEAD element specifying the character encoding actually used. For example,

<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=EUC-JP">
...

The content type should be set to the value given for the media-type attribute; the default value is text/html.

[ERR119] It is possible that the result tree will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where HTML recognizes character references, then the character should be output as a character entity reference or decimal numeric character reference; otherwise (for example, in a script or style element or in a comment), the processor should signal a serialization error.

If the doctype-public or doctype-system attributes are specified, then the html output method should output a document type declaration immediately before the first element. The name following <!DOCTYPE should be HTML or html. If the doctype-public attribute is specified, then the output method should output PUBLIC followed by the specified public identifier; if the doctype-system attribute is also specified, it should also output the specified system identifier following the public identifier. If the doctype-system attribute is specified but the doctype-public attribute is not specified, then the output method should output SYSTEM followed by the specified system identifier.

The media-type attribute is applicable for the html output method. The default value is text/html.

18.4 Text Output Method

The text output method outputs the result tree by outputting the string-value of every text node in the result tree in document order without any escaping.

The media-type attribute is applicable for the text output method. The default value for the media-type attribute is text/plain.

The encoding attribute identifies the encoding that the text output method should use to convert sequences of characters to sequences of bytes. The default is system-dependent. [ERR120] If the result tree contains a character that cannot be represented in the encoding that the processor is using for output, the implementation should signal a serialization error.

18.5 Disabling Output Escaping

Normally, the xml output method escapes & and < (and possibly other characters) when outputting text nodes. This ensures that the output is well-formed XML. 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 provides a mechanism for disabling output escaping. 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 a text node generated by evaluating the xsl:value-of or xsl:text element should be output without any escaping. For example,

<xsl:text disable-output-escaping="yes">&lt;</xsl:text>

should generate the single character <.

[ERR121] It is a dynamic error for output escaping to be disabled for a text node that is used for something other than a text node in the result tree. Thus, it is an error to disable output escaping for an xsl:value-of or xsl:text element that is used to generate the string-value of a comment, processing instruction or attribute node; it is also a dynamic error to convert a node to a number or a string if the node is, or contains, a text node for which escaping was disabled. In both cases, the processor must either signal the error, of must recover by ignoring the disable-output-escaping attribute.

When a text node is copied, either by using xsl:copy or by applying xsl:copy-of to that node or one of its ancestors, and when escaping was disabled for some or all of the characters within that text node, then escaping should also be disabled for the resulting copy of those characters. For example

<xsl:variable name="x">
<xsl:text disable-output-escaping="yes">&lt;</xsl:text>
</xsl:variable>
<xsl:copy-of select="$x"/>

should output < not &lt;.

Text nodes for which escaping is disabled are subject to merging with text nodes that are adjacent in the result tree in the same way as text nodes for which is escaping is not disabled. An element or document node in the result tree never has two consecutive text node children. Thus, it is possible for escaping to be disabled for some but not all of the characters in a text node.

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 result tree is output. This might not always be the case. For example, the result tree might be used as the source tree for another XSLT transformation instead of being output. It is implementation-defined whether (and under what circumstances) disabling output escaping is supported. [ERR122] It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping should be disabled and the implementation does not support this. The processor must either signal the error, of must recover by not disabling output escaping.

[ERR123] It is a serialization error if output escaping is disabled for a character that is not representable in the encoding that the processor is using for output. The processor must either signal the error, of must recover by not disabling output escaping.

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.

19 Conformance

A conforming processor must be able to use a stylesheet to transform source trees into result trees as specified in this document. A conforming processor need not be able to serialize the result in XML or in any other form.

NOTE: Implementations are strongly encouraged to provide a way to verify that the processor is behaving conformingly by allowing result trees to be output as XML or by providing access to result trees through a standard API such as the DOM or SAX.

A conforming processor must signal any errors except for those that this document specifically allows a processor not to signal. A conforming processor may continue after signaling an error, but if it does so, it must either take the recovery action defined in this document, or it must eventually terminate without producing a result tree.

However, a processor will not be considered as failing to conform to this specification solely because it implements constructs that are introduced in a later version of this specification.

NOTE: This means that a processor that implements all of version 2.0 and a few features of version 3.0 can claim conformance with XSLT 2.0. This differs from the situation with XSLT 1.0, where implementing selected XSLT 2.0 constructs makes a processor technically non-conformant with XSLT 1.0.

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

Issue (conformance-modules): Should we introduce multiple conformance levels or modules, recognizing that serialization is a separate specification to which processors may or may not conform?

20 Notation

The specification of each XSLT-defined element type is preceded by a summary of its syntax in the form of a model for elements of that element type. The meaning of syntax summary notation is as follows:

[ERR124] 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. [ERR125] It is a static error if an attribute (other than an attribute written using curly braces in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute. [ERR126] It is a dynamic error if the effective value of an attribute written using curly braces, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute.

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


A References

A.1 Normative References

Data Model
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Data Model W3C Working Draft. See http://www.w3.org/TR/query-datamodel/
Functions and Operators
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Functions and Operators. W3C Working Draft. See http://www.w3.org/TR/xquery-operators/
DOM2
World Wide Web Consortium. Document Object Model (DOM) Level 2 Core Specification. W3C Recommendation. See http://www.w3.org/TR/DOM-Level-2-Core/
XHTML 1.0
World Wide Web Consortium. XHTML 1.0: The Extensible HyperText Markup Language. W3C Recommendation. See http://www.w3.org/TR/xhtml1/. Note: a second edition of this specification is in preparation.
XHTML 1.1
World Wide Web Consortium. XHTML 1.1: Module-Based XHTML. W3C Recommendation. See http://www.w3.org/TR/xhtml11/
XML
World Wide Web Consortium. Extensible Markup Language (XML) 1.0 (Second Edition) W3C Recommendation. See http://www.w3.org/TR/2000/REC-xml-20001006
XMLBASE
World Wide Web Consortium. XML Base. W3C Recommendation. See http://www.w3.org/TR/xmlbase/
XML Names
World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See http://www.w3.org/TR/REC-xml-names/
XML Schema
World Wide Web Consortium. XML Schema Part 1: Structures and and XML Schema Part 2: Data Types. W3C Recommendation. See http://www.w3.org/TR/xmlschema-1/ and http://www.w3.org/TR/xmlschema-2/
XPath 2.0
World Wide Web Consortium. XML Path Language Version 2.0 W3C Working Draft. See http://www.w3.org/TR/xpath20
Formal Semantics
World Wide Web Consortium. XQuery 1.0 Formal Semantics W3C Working Draft. See http://www.w3.org/TR/query-semantics/

A.2 Other References

HTML
World Wide Web Consortium. HTML 4.01 specification. W3C Recommendation. See http://www.w3.org/TR/html4/
IANA
Internet Assigned Numbers Authority. Character Sets. See http://www.iana.org/assignments/character-sets.
RFC2278
N. Freed, J. Postel. IANA Charset Registration Procedures. IETF RFC 2278. See http://www.ietf.org/rfc/rfc2278.txt.
RFC2336
M. Baker, P. Stark. The 'application/xhtml+xml' Media Type. IETF RFC 2278. See http://www.ietf.org/rfc/rfc2336.txt.
RFC2376
E. Whitehead, M. Murata. XML Media Types. IETF RFC 2376. See http://www.ietf.org/rfc/rfc2376.txt.
RFC2396
T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource Identifiers (URI): Generic Syntax. IETF RFC 2396. See http://www.ietf.org/rfc/rfc2396.txt.
UNICODE TR10
Unicode Consortium. Unicode Technical Standard #10. Unicode Collation Algorithm. Unicode Technical Report. See http://www.unicode.org/unicode/reports/tr10/.
XML Stylesheet
World Wide Web Consortium. Associating Style Sheets with XML documents. W3C Recommendation. See http://www.w3.org/TR/xml-stylesheet/
XPointer
World Wide Web Consortium. XML Pointer Language (XPointer) Version 1.0 W3C Candidate Recommendation. See http://www.w3.org/TR/xptr
XSL Formatting Objects
World Wide Web Consortium. Extensible Stylesheet Language (XSL). W3C Recommendation. See http://www.w3.org/TR/xsl/
XSLT 1.0
World Wide Web Consortium. XSL Transformations (XSLT) Version 1.0 W3C Recommendation. See http://www.w3.org/TR/xslt
XSLT 1.1 Requirements
World Wide Web Consortium. XSL Transformations Requirements Version 1.1 W3C Working Draft. See http://www.w3.org/TR/xslt11req
XSLT 1.1 WD
World Wide Web Consortium. XSL Transformations (XSLT) Version 1.1 W3C Working Draft. See http://www.w3.org/TR/xslt11/
XSLT 2.0 Requirements
World Wide Web Consortium. XSLT Requirements Version 2.0 W3C Working Draft. See http://www.w3.org/TR/xslt20req

B Glossary (Non-Normative)

alias 

A stylesheet can use the xsl:namespace-alias element to declare that one namespace URI is an alias for another namespace URI.

allowable 

What namespace nodes are added and where they are added by namespace fixup is implementation-dependent, provided that the resulting tree satisfies the constraints and provided that all namespaces nodes in the resulting tree are allowable, where a namespace node is allowable for an element E if any of the following conditions applies:

attribute value template 

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 braces ({})

circularity 

If the expression or content 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. If it is impossible to do this for all global variable definitions, then a circularity is said to exist.

collation 

Facilities in XSLT 2.0 and XPath 2.0 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 should be sorted before the other.

content constructor 

A content constructor is a sequence of nodes in the stylesheet that, when evaluated, constructs and returns a sequence of new nodes suitable for adding to the result tree.

context document 

The context document is the source document currently being processed. This is initially set to the document node of the principal source document. It changes when instructions such as xsl:apply-templates and xsl:for-each are used to process nodes in a document other than the principal source document.

context item 

The context item is the item currently being processed. An item (see [Data Model]) is either a simple value (such as an integer, date, or string), or a node. If the context item is a node, then it will always be a node in the context document. The initial context node is the same as the context document. 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.

context node 

If the context item is a node (as distinct from a simple 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 a simple value, there is no context node: its value is an empty sequence.

context position 

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.

context size 

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

current group 

The evaluation context for XPath expressions includes an additional value called the current group, which is a sequence. The current group is the collection of related items that are processed collectively in one iteration of the xsl:for-each-group element.

current result tree 

When a content constructor is evaluated to create new nodes, the tree to which these nodes are added is referred to as the current result tree

current template rule 

At any point in the processing of a stylesheet, there may be a current template rule. Whenever a template rule is chosen by matching a pattern, the template rule becomes the current template rule for the evaluation of the rule's content constructor. When an xsl:for-each or xsl:for-each-group instruction is evaluated, the current template rule becomes null for the evaluation of the content of the xsl:for-each or xsl:for-each-group instruction.

declaration 

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 [2.4.1 User-defined Data Elements])

declaration order 

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.

default priority 

If no priority attribute is specified on the xsl:template element, the default priority is computed as follows:

dynamic error 

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

effective value 

The result of evaluating an attribute value template is referred to as the effective value of the attribute.

embedded stylesheet module 

an embedded stylesheet module consists of an xsl:stylesheet or xsl:transform element embedded within another XML document, typically the principal source document

expanded-QName 

An expanded-QName is a pair of values containing a namespace URI and a local name. A QName is expanded by replacing the namespace prefix with the corresponding namespace URI, from the namespace declarations that are in scope at the point where the QName is written. Two expanded-QNames are equal if the namespace URIs are the same and the local names are the same.

expression 

An expression must match the XPath production Expr.

extension function 

An extension function is a function that is available for use within an XPath expression, other than a core function defined in the XPath specification, an additional function defined in this XSLT specification, or a stylesheet function defined using an xsl:function declaration.

extension instruction 

An extension instruction is an element within a content constructor that is in a namespace (not the XSLT namespace) designated as an extension namespace

extension namespace 

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 content constructor, then the element is treated as an instruction rather than as a literal result element.

external object 

Support for extension functions introduces an additional data-type into the expression language. This additional data type is called an external object. A variable may be bound to an object of type external object instead of one of the XPath data-types. An external object represents an object that is not convertible to one of the XPath data types, which is created by an external programming language and returned by an extension function. The external object, as an XPath value, can be regarded as a wrapper for an object created by, and processible using, the programming language in which the extension functions are written. Expressions can only return values of type external object by referencing variables of type external object or by calling extension functions that return an external object.

focus 

When a content constructor is evaluated, the processor keeps track of which nodes are being processed by means of a set of implicit variables referred to collectively as the focus.

forwards-compatible behavior 

An element enables forwards-compatible behavior for itself, its attributes, its descendants and their attributes if it has an [xsl:]version attribute (see [2.3 Standard Attributes]) whose value is greater than 2.0.

group 

The xsl:for-each-group instruction partitions a sequence into groups of items (that is, it establishes a set of sequences) based either on common values of a grouping key, or on a pattern that the initial node in a group must match.

grouping key 

The result of evaluating the group-by expression is converted to a string; the resulting string is known as the grouping key for that item. All items that have the same value for the grouping key are assigned to the same group

implementation 

A specific product that performs the functions of an XSLT processor is referred to as an implementation

implementation-defined 

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 should be described in the vendor's documentation.

implementation-dependent 

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.

import precedence 

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.

import tree 

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.

initial sequence 

The sequence to be sorted is referred to as the initial sequence.

instruction 

The elements occurring within a content constructor are classified as being either literal result elements or instructions. If the element is in the XSLT namespace, or in a namespace designated as an extension namespace, then it is an instruction. Otherwise, it is a literal result element.

literal namespace URI 

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.

literal result element 

In a content constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see [16.2 Extension Instructions]) is classified as a literal result element.

mode 

Modes allow a node in the 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 [14.1 Multiple Source Documents]) or when processing temporary trees (see [6 Variables and Parameters])

named sort specification 

A named sort specification is defined by an xsl:sort-key declaration. This is a top-level element in the stylesheet.

named template 

Templates can be invoked by name. An xsl:template element with a name attribute specifies a named template.

namespace fixup 

The process of namespace fixup modifies a tree by adding namespace nodes so that it satisfies all constraints affecting namespace nodes.

order of first appearance 

There is an 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.

output definition 

All the xsl:output declarations in a stylsheet that share the same name are grouped into a named output definition; those that have no name are grouped into a a single unnamed output definition.

pattern 

A pattern specifies a set of conditions on a node. A node that satisfies the conditions matches the pattern; a node that does not satisfy the conditions does not match the pattern. The syntax for patterns is a subset of the syntax for expressions.

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, percent-sign, per-mille-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters are classified as passive characters.

place marker 

The xsl:number instruction performs two tasks: firstly, determining a place marker to be formatted (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 tree.

population 

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.

population order 

The population is treated as a sequence; the order of items in this sequence is referred to as population order

principal result tree 

When the transformation is initiated, a result tree is created, and becomes the current result tree. This tree is referred to as the principal result tree

principal source document 

The document containing the initial input node is referred to as the principal source document

principal stylesheet module 

A stylesheet may consist of several stylesheet modules, contained in different XML documents. 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 [2.8.1 Stylesheet Inclusion] and [2.8.2 Stylesheet Import]

processor 

The software responsible for transforming a source document into a result document 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.

QName 

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

required type 

The context within a stylesheet where an XPath expression may appear determines the required type of the expression. The required type indicates the data type of value that the expression is expected to return.

serialization 

A frequent requirement is to output the result tree as an XML document (or in other formats such as HTML). This process is referred to as serialization.

serialization error 

If a transformation has successfully produced a 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.

shadows 

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.

simplified stylesheet module 

a simplified stylesheet module is represented by an element that is not itself in the XSLT namespace, but that has an xsl:version attribute (which implies that the XSLT namespace must be declared). This element will often be the document element of an XML document, in which case the simplified stylesheet module consists of the entire document, but it can also be an element embedded more deeply within another document. The element containing the xsl:version attribute acts as a literal result element (see [2.5 Simplified Stylesheet Modules]), and may contain embedded XSLT instructions.

singleton focus 

A singleton focus based on a node N has the context item (and therefore the context node) set to N, the context document set to the document containing N, and the context position and context size both set to 1 (one).

sorted sequence 

The sequence after sorting as defined by the xsl:sort elements is referred to as the sorted sequence.

sort key 

For each item in the initial sequence, a value is computed for each sort key definition within the sort specification. The value computed for an item by using the Nth sort key definition is referred to as the Nth sort key of that item.

sort key definition 

Within a sort specification, each xsl:sort element provides one sort key definition.

sort specification 

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

standard attributes 

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

standard stylesheet module 

a standard stylesheet module is an XML document having an xsl:stylesheet or xsl:transform element as its document element (see [2.4 Stylesheet Element]).

static error 

An error that is 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.

stylesheet 

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

stylesheet function 

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.

stylesheet level 

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.

stylesheet module 

A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document.

template rule 

A stylesheet contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in the source tree and a content constructor which is evaluated to produce a sequence of nodes: these nodes are typically used to form part of the result tree.

 

If a variable-binding element has no select attribute and has non-empty content (i.e. the variable-binding element has one or more child nodes), then the content of the variable-binding element specifies the supplied value. The content of the variable-binding element is a content constructor; a new document (referred to as a temporary tree) is constructed with a document node having as its children the sequence of nodes that results from evaluating the content constructor.

top-level 

An element occurring as a child of an xsl:stylesheet element is called a top-level element.

type errors 

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.

user-defined data element 

In addition to declarations, the xsl:stylesheet element may contain 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.

value 

The value to which a variable is bound (the value of the variable) can be an object of any of the types that can be returned by expressions.

variable-binding element 

The two elements xsl:variable and xsl:param are referred to as variable-binding elements

XSLT namespace 

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.

C Element Syntax Summary

The syntax of each XSLT element is summarized below, together with the context in the stylesheet where the element may appear. Some elements (specifically, instructions) are allowed as a child of any element that is allowed to contain a content constructor. These elements are:

xsl:apply-imports

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:apply-templates

 

Category: instruction

Model:

<xsl:apply-templates
  select = node-sequence-expression
  mode = qname>
  <!-- Content: (xsl:sort | xsl:with-param)* -->
</xsl:apply-templates>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:attribute

 

Category: instruction

Model:

<xsl:attribute
  name = { qname }
  namespace = { uri-reference }>
  <!-- Content: content-constructor -->
</xsl:attribute>

Permitted parent elements:

  • xsl:attribute-set
  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:attribute-set

 

Category: declaration

Model:

<xsl:attribute-set
  name = qname
  use-attribute-sets = qnames>
  <!-- Content: xsl:attribute* -->
</xsl:attribute-set>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:call-template

 

Category: instruction

Model:

<xsl:call-template
  name = qname>
  <!-- Content: xsl:with-param* -->
</xsl:call-template>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:choose

 

Category: instruction

Model:

<xsl:choose>
  <!-- Content: (xsl:when+, xsl:otherwise?) -->
</xsl:choose>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:comment

 

Category: instruction

Model:

<xsl:comment>
  <!-- Content: content-constructor -->
</xsl:comment>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:copy

 

Category: instruction

Model:

<xsl:copy
  use-attribute-sets = qnames>
  <!-- Content: content-constructor -->
</xsl:copy>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:copy-of

 

Category: instruction

Model:

<xsl:copy-of
  select = expression
  separator = { string } />

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:decimal-format

 

Category: declaration

Model:

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

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:element

 

Category: instruction

Model:

<xsl:element
  name = { qname }
  namespace = { uri-reference }
  use-attribute-sets = qnames>
  <!-- Content: content-constructor -->
</xsl:element>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:fallback

 

Category: instruction

Model:

<xsl:fallback>
  <!-- Content: content-constructor -->
</xsl:fallback>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:for-each

 

Category: instruction

Model:

<xsl:for-each
  select = sequence-expression>
  <!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:for-each-group

 

Category: instruction

Model:

<xsl:for-each-group
  select = expression
  group-by = expression
  group-adjacent = expression
  group-starting-with = pattern
  group-ending-with = pattern>
  <!-- Content: (xsl:sort*, content-constructor) -->
</xsl:for-each-group>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:function

 

Category: declaration

Model:

<xsl:function
  name = qname>
  <!-- Content: (xsl:param*, (xsl:variable | xsl:message)*, xsl:result) -->
</xsl:function>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:if

 

Category: instruction

Model:

<xsl:if
  test = expression>
  <!-- Content: content-constructor -->
</xsl:if>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:import

 

Category: declaration

Model:

<xsl:import
  href = uri-reference />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:import-schema

 

Category: declaration

Model:

<xsl:import-schema
  namespace = uri-reference
  schema-location = uri-reference />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:include

 

Category: declaration

Model:

<xsl:include
  href = uri-reference />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:key

 

Category: declaration

Model:

<xsl:key
  name = qname
  match = pattern
  use = expression
  data-type = qname
  collation = uri />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:message

 

Category: instruction

Model:

<xsl:message
  terminate = "yes" | "no">
  <!-- Content: content-constructor -->
</xsl:message>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element
  • xsl:function

xsl:namespace

 

Category: instruction

Model:

<xsl:namespace
  name = { ncname }>
  <!-- Content: content-constructor -->
</xsl:namespace>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:namespace-alias

 

Category: declaration

Model:

<xsl:namespace-alias
  stylesheet-prefix = prefix | "#default"
  result-prefix = prefix | "#default" />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:number

 

Category: instruction

Model:

<xsl:number
  level = "single" | "multiple" | "any"
  count = pattern
  from = pattern
  value = number-expression
  format = { string }
  lang = { nmtoken }
  letter-value = { "alphabetic" | "traditional" }
  grouping-separator = { char }
  grouping-size = { number } />

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:otherwise

 

Model:

<xsl:otherwise>
  <!-- Content: content-constructor -->
</xsl:otherwise>

Permitted parent elements:

  • xsl:choose

xsl:output

 

Category: declaration

Model:

<xsl:output
  name = qname
  method = { "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname }
  version = { nmtoken }
  encoding = { string }
  omit-xml-declaration = { "yes" | "no" }
  standalone = { "yes" | "no" }
  doctype-public = { string }
  doctype-system = { string }
  cdata-section-elements = { qnames }
  indent = { "yes" | "no" }
  media-type = { string }
  include-content-type = { "yes" | "no" }
  escape-uri-attributes = { "yes" | "no" } />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:param

 

Category: declaration

Model:

<xsl:param
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:param>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform
  • xsl:function
  • xsl:template

xsl:preserve-space

 

Category: declaration

Model:

<xsl:preserve-space
  elements = tokens />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:principal-result-document

 

Category: declaration

Model:

<xsl:principal-result-document
  format = qname
  href = { uri-reference } />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:processing-instruction

 

Category: instruction

Model:

<xsl:processing-instruction
  name = { ncname }>
  <!-- Content: content-constructor -->
</xsl:processing-instruction>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:result

 

Model:

<xsl:result
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:result>

Permitted parent elements:

  • xsl:function

xsl:result-document

 

Category: instruction

Model:

<xsl:result-document
  format = qname
  href = { uri-reference }>
  <!-- Content: content-constructor -->
</xsl:result-document>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:sort

 

Model:

<xsl:sort
  select = expression
  lang = { nmtoken }
  data-type = { "text" | "number" | qname-but-not-ncname }
  order = { "ascending" | "descending" }
  collation = { uri }
  case-order = { "upper-first" | "lower-first" } />

Permitted parent elements:

  • xsl:sort-key
  • xsl:for-each
  • xsl:apply-templates
  • xsl:for-each-group

xsl:sort-key

 

Category: declaration

Model:

<xsl:sort-key
  name = qname>
  <!-- Content: (xsl:sort+) -->
</xsl:sort-key>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:strip-space

 

Category: declaration

Model:

<xsl:strip-space
  elements = tokens />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:stylesheet

 

Model:

<xsl:stylesheet
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  default-xpath-namespace = uri>
  <!-- Content: (xsl:import*, top-level-elements) -->
</xsl:stylesheet>

Permitted parent elements:

  • None

xsl:template

 

Category: declaration

Model:

<xsl:template
  match = pattern
  name = qname
  priority = number
  mode = qname>
  <!-- Content: (xsl:param*, content-constructor) -->
</xsl:template>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:text

 

Category: instruction

Model:

<xsl:text
  disable-output-escaping = "yes" | "no">
  <!-- Content: content-constructor -->
</xsl:text>

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:transform

 

Model:

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  default-xpath-namespace = uri>
  <!-- Content: (xsl:import*, top-level-elements) -->
</xsl:transform>

Permitted parent elements:

  • None

xsl:value-of

 

Category: instruction

Model:

<xsl:value-of
  select = expression
  separator = { string }
  disable-output-escaping = "yes" | "no" />

Permitted parent elements:

  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:variable

 

Category: declaration

Model:

<xsl:variable
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:variable>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform
  • xsl:function
  • any XSLT element whose content model is content constructor
  • any literal result element

xsl:when

 

Model:

<xsl:when
  test = expression>
  <!-- Content: content-constructor -->
</xsl:when>

Permitted parent elements:

  • xsl:choose

xsl:with-param

 

Model:

<xsl:with-param
  name = qname
  select = expression
  type = sequence-type>
  <!-- Content: content-constructor -->
</xsl:with-param>

Permitted parent elements:

  • xsl:apply-templates
  • xsl:apply-imports
  • xsl:call-template

D Summary of Error Conditions (Non-Normative)

This appendix provides a summary of error conditions that a processor may signal. This list is not exhaustive or definitive. The errors are numbered for ease of reference, but there is no implication that an implementation should report errors using these error codes, or that applications can test for these codes. Moreover, implementations are not required to report errors using the descriptive text used here.

Static errors

ERR002

It is a static error for an element from the XSLT namespace to have an attribute with an expanded-QName that has a null namespace URI (i.e. an attribute with an unprefixed name) other than attributes defined for the element in this document.

ERR003

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

ERR004

The value of the version attribute [of the xsl:stylesheet element] must be a number (specifically, it must be a DecimalLiteral as defined in [XPath 2.0].)

ERR005

An xsl:stylesheet element must have no text node children, other than text nodes consisting entirely of whitespace.

ERR006

It is a static error if the xsl:stylesheet element has a child element having a null namespace URI.

ERR007

A user-defined data element must not precede an xsl:import element within a stylesheet module.

ERR008

A literal result element that is used as the outermost element of a simplified stylesheet module must have an xsl:version attribute.

ERR011

The xsl:include element is allowed only as a top-level element.

ERR012

It is an static error if a stylesheet module directly or indirectly includes itself.

ERR013

The xsl:import declaration is allowed only as a top-level element.

ERR014

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.

ERR015

It is a static error if a stylesheet module directly or indirectly imports itself.

ERR016

It is a static error if the processor is not able to locate a schema using the namespace and/or schema-location attributes [of the xsl:import-schema declaration] , or if the document that it locates is neither a valid XML Schema nor any other resource that the implementation can process.

ERR017

It is a static error if two xsl:import-schema declarations yield multiple definitions for the same named type, even if the definitions are consistent with each other.

ERR018

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

ERR021

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

ERR023

It is a static error if the value of such an attribute, or the text between curly braces in an attribute value template, does not match the XPath production Expr, 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.

ERR026

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

ERR027

It is a static error if a left curly brace appears in an attribute value template without a matching right curly brace.

ERR028

It is a static error if the string contained between matching curly braces in an attribute value template does not match the XPath production Expr.

ERR029

It is a static error if a right curly brace occurs in an attribute value template outside an expression without being followed by a second right curly brace.

ERR038

The value of this [the priority attribute of the xsl:template element] must be a real number (positive or negative), matching the production NumericLiteral with an optional leading minus sign (-).

ERR039

If an xsl:template element does not have a match attribute, then it must not have a priority attribute.

ERR043

If an xsl:template element does not have a match attribute, then it is a static error if it has a mode attribute.

ERR045

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.

ERR046

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.

ERR048

It is a static error if a stylesheet contains more than one template with the same name and same import precedence.

ERR051

A stylesheet function must have a prefixed name, to remove any risk of a clash with a system-defined function. It is a static error if the name has no prefix.

ERR052

It is a static error for a stylesheet to contain two or more functions with the same expanded-QName and the same import precedence, unless there is another function with the same expanded-QName and a higher import precedence.

ERR066

When used within xsl:for-each or xsl:for-each-group, xsl:sort elements must occur before any other children.

ERR071

It is a static error for a stylesheet to contain two or more named sort specifications with the same expanded-QName and the same import precedence, unless there is another named sort specification with the same expanded-QName and a higher import precedence.

ERR073

The current-group function must not be used within a pattern.

ERR074

These four attributes [the group-by, group-adjacent, and group-starting-with, and group-ending-with attributes of xsl:for-each-group] are mutually exclusive: exactly one of the four attributes must be present.

ERR084

It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different data types, or if the data type is specified in one of these declarations and omitted in another.

ERR085

It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different collation sequences, or if the collation is specified in one of these declarations and omitted in another.

ERR086

It is a static error if the value of the data-type attribute [of the xsl:key element] is not an atomic type (optionally followed by an occurrence count).

ERR087

It is a static error if a value is specified for the collation attribute [of the xsl:key element] unless the data-type is defaulted or set to xsd:string.

ERR093

It is a static error to declare either the default decimal-format or a decimal-format with a given name more than once (even with different import precedence), unless it is declared every time with the same value for all attributes (taking into account any default values).

ERR094

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.

ERR106

It is a static error if there is no namespace bound to the prefix on the element bearing the [xsl:]extension-element-prefixes attribute.

ERR108

It is a static error if the value of the format attribute [of an xsl:principal-result-document element] is not a valid QName, or if it does not match the expanded-QName of an output definition in the stylesheet.

ERR109

It is a static error if there is more than one xsl:result-document element at the top level of the stylesheet with the same import precedence, unless there is also another xsl:result-document element at the top level of the stylesheet with a higher import precedence.

ERR110

It is a static error if the value of the format attribute [of an xsl:result-document element] is not a valid QName, or if it does not match the expanded-QName of an output definition in the stylesheet.

ERR124

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.

ERR125

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

Type errors

ERR024

It is a type error if an XPath expression contains a type error, or if the type of the XPath expression is incompatible with the required type.
    Action: The processor must either signal a type error as a static error, or must attempt to recover by converting the result of the expression to the required type using the standard type conversion rules; if conversion is not possible under these rules, the processor must signal a dynamic error

ERR044

If the type attribute [of xsl:variable or xsl:param] is specified, then the supplied value of the variable is converted to the required type, using the same rules that apply when converting a supplied value to the required type for an argument in a function call. These rules are specified in [XPath 2.0]. It is a type error if this conversion fails.

ERR054

If the type attribute [of xsl:result] is specified, then the calculated result is converted to the required type, using the rules defined in [XPath 2.0] for the conversion of a supplied value to a required type when calling a function.. It is a type error if this conversion fails.

Dynamic errors

ERR001

It is a dynamic error if the stylesheet is invoked using the call-transformation method, and the invocation specifies an template name that does not match the expanded-QName of a named template defined in the stylesheet.

ERR009

If the value [returned by an XPath expression with backwards-compatible behavior] is an empty sequence or a sequence that consists entirely of nodes, then it is converted to a node-set; it is a dynamic error if the value is any other sequence of two or more items.
    Action: The processor must signal the error.

ERR010

If an implementation does not support backwards-compatible behavior, then it is a dynamic error if any element is evaluated that enables backwards-compatible behavior.
    Action: The processor must signal the error.

ERR019

It is an dynamic error if this [the process of finding an xsl:strip-space or xsl:preserve-space declaration to match an element in the source document] leaves more than one match.
    Action: The processor must either signal the error, of must recover by choosing, from amongst the matches that are left, the one that occurs last in declaration order.

ERR020

It is a dynamic error if such a document [a source document, a document returned by the document or by an extension function, or supplied as a stylesheet parameter] does not already satisfy the constraints listed above [in summary, that the namespace nodes on the tree are consistent with those produced by parsing a well-formed document conforming to the XML Namespaces Recommendation] .
    Action: The processor may signal the error, or may recover by performing namespace fixup, or may produce implementation-dependent results.

ERR022

In the case of a QName produced by evaluating an XPath expression, it is a dynamic error if the defining element has no namespace node whose name matches the prefix of the QName. The error is a dynamic error even if the value of the expression is known statically, for example if the QName is written as a string literal.

ERR025

It is a dynamic error for an expression to call any function that is not included in the in-scope functions.
    Action: The processor must signal the error, but only if the function call is actually evaluated.

ERR030

It is an dynamic error if an extension instruction attempts to return a sequence containing a document node.
    Action: The processor must signal the error.

ERR031

It is a dynamic error if the result sequence [returned by a content constructor] (after concatenating the results of individual instructions) contains a namespace node that is preceded in the sequence by a node that is not a namespace node.
    Action: The processor must either signal the error, or must recover by ignoring the offending namespace node.

ERR032

It is a dynamic error if the result sequence [returned by a content constructor] (after concatenating the results of individual instructions) contains an attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node.
    Action: The processor must either signal the error, or must recover by ignoring the offending attribute node.

ERR033

Elements such as xsl:variable, xsl:param, xsl:message, and xsl:result-document construct a new document node, and use the result sequence returned by the content constructor to form the children of this document node. In this case it is an dynamic error if the result sequence contains namespace or attribute nodes.
    Action: The processor must either signal the error, or must recover by ignoring the offending nodes.

ERR034

It is a dynamic error to add a namespace node to an element if the element already has a namespace node with the same name, unless both namespace nodes have the same string-value, in which case the duplicate is ignored. It is also a dynamic error to add a namespace node to an element if the namespace node has a null name and the element has a null namespace URI.
    Action: In both cases the processor must either signal the error, or must recover by ignoring the offending namespace node.

ERR035

It is a dynamic error if the result sequence [produced by the xsl:comment, xsl:attribute, xsl:processing-instruction, xsl:text, or xsl:namespace elements] contains nodes other than text nodes.
    Action: The processor must either signal the error, or must recover by ignoring the non-text nodes together with their content.

ERR036

It is a dynamic error if [xsl:apply-templates with no select attribute is evaluated when] the context item is not a node.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR037

It is a dynamic error if the sequence returned by the select expression [of xsl:apply-templates] contains an item that is not a node.
    Action: The processor must either signal the error, or must recover by ignoring the offending items.

ERR040

It is a dynamic error if this [the conflict resolution algorithm for template rules] leaves more than one matching template rule.
    Action: The processor must either signal the error, or must recover by choosing, from amongst the matching template rules that are left, the one that occurs last in declaration order.

ERR041

It is an error if the xsl:apply-imports instruction is evaluated when the context item is not a node.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR042

It is a dynamic error if xsl:apply-imports is evaluated when the current template rule is null.
    Action: The processor must signal the error.

ERR047

In general, a circularity in a stylesheet is a dynamic error.
    Action: The processor must signal the error.

ERR049

It is a dynamic error if use of use-attribute-sets attributes on xsl:attribute-set elements causes an attribute set to use itself, directly or indirectly.
    Action: The processor must signal the error

ERR050

It is a dynamic error if there are two attribute sets that have the same expanded-QName and equal import precedence and that both contain the same attribute, unless there is a definition of the attribute set with higher import precedence that also contains the attribute.
    Action: The processor must either signal the error, or must recover by choosing from amongst the definitions that specify the attribute that have the highest import precedence the one that was specified last in declaration order.

ERR053

It is an static error if there are more arguments supplied in the function call than there are xsl:param elements in the function definition.

ERR055

It is a dynamic error if there is more than one such declaration [more than one xsl:namespace-alias declaration with the same stylesheet-prefix] and different values for namespace-uri.
    Action: The processor must either signal the error, or must recover by choosing, from amongst the declarations with the highest import precedence, the one that occurs last in declaration order.

ERR056

It is an dynamic error if the effective value [of the name attribute of the xsl:element instruction] is not a QName.
    Action: The processor must either signal the error, or must recover by making the result of evaluating the xsl:element element be the sequence of nodes created by evaluating the content of the xsl:element element, excluding any initial attribute nodes.

ERR057

It is a dynamic error if the effective value [of the name attribute of an xsl:attribute instruction] is not a QName or is the string xmlns.
    Action: The processor must either signal the error, or must recover by not adding the attribute to the result tree.

ERR058

It is a dynamic error if the effective value of the name attribute [of the xsl:processing-instruction instruction] is not both an NCName and a PITarget.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR059

It is a dynamic error if the result of evaluating the content of the xsl:processing-instruction contains the string ?>.
    Action: The processor must either signal the error, or must recover by inserting a space after any occurrence of ? that is followed by a >

ERR060

It is a dynamic error if the effective value of the name attribute [of the xsl:namespace instruction] is neither an empty string nor an NCName.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR061

It is an dynamic error if evaluating the content of xsl:namespace results in an empty string.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR062

It is a dynamic error if the result of evaluating the content of the xsl:comment contains the string -- or ends with -.
    Action: The processor must either signal the error, or must recover by inserting a space after any occurrence of - that is followed by another - or that ends the comment.

ERR063

When the context item is an attribute node, then if it would be a dynamic error to use xsl:attribute to create an attribute with the same name as the context item, then it is also a dynamic error to use xsl:copy (see [8.3 Creating Attribute Nodes using xsl:attribute]).

ERR064

It is a dynamic error if any item in the 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 1 (one).
    Action: The processor must either signal the error, or must recover by converting that member to a string as if by a call to the string function and inserting the resulting string into the formatted result string in its proper position.

ERR065

It is a dynamic error if the xsl:number instruction is evaluated, with no value attribute, when the context item is not a node.
    Action: The processor must either signal the error, or must recover by returning an empty sequence.

ERR067

The target data type for each xsl:sort element is determined by the effective value of its data-type attribute. If this has the value text, the target data type is xsd:string. If it has the value number, the target data type is xsd:double. Otherwise, the target data type must be the name of a primitive data type in XML Schema (see [XML Schema]). It is a dynamic error if any other value is supplied.
    Action: The processor must either signal the error, or must recover by continuing as if the data-type attribute were not specified.

ERR068

It is a dynamic error if any value obtained by evaluating the select attribute of an xsl:sort element cannot be converted to the target data type.
    Action: The processor must either signal the error, or must recover by treating the value as being less than any value for which conversion succeeds, but equal to any other value for which conversion fails. This means (if this is the first or only sort key) that values that cannot be converted to the target data type will appear together at the start of the sorted sequence if order is ascending, or at the end if order is descending.

ERR069

It is a dynamic error if, for any sort key definition, the set of sort keys evaluated for all the items in the initial sequence, after any type conversion requested, contains a pair of values for which the result of the XPath lt operator is an error or an empty sequence.
    Action: The processor must either signal the error, or must recover by assigning an arbitrary ordering to any such pair of values.

ERR070

It is a dynamic error if the effective value of the data-type attribute of the xsl:sort element is a data type for which no ordering relation is defined, other than the values xsd:string or text, which are synonymous.

ERR072

It is a dynamic error if the first argument of the sort function does not match the name of any named sort specification in the stylesheet.
    Action: The processor must signal the error.

ERR075

It is a dynamic error if the result of evaluating the select expression [of the xsl:for-each-group instruction, with a group-starting-with attribute,] contains an item that is not a node.
    Action: The processor must signal the error.

ERR076

It is a dynamic error if the result of evaluating the select expression [of the xsl:for-each-group instruction, with a group-ending-with attribute,] contains an item that is not a node.
    Action: The processor must signal the error.

ERR080

It is a dynamic error if a URI [supplied in the first argument to the unparsed-text function] cannot be used to retrieve a resource containing text.
    Action: The processor must either signal the error, or must recover by treating the URI as if it referenced a resource containing a zero-length string.

ERR081

It is a dynamic error if a resource [retrieved using the unparsed-text function] contains characters that are not valid XML characters.
    Action: The processor must either signal the error, or must recover in a implementation-defined way; one possible outcome is that the processor will produce an output file that is not well-formed XML.

ERR082

It is a dynamic error if a resource [retrieved using the unparsed-text function] contains bytes that cannot be decoded into valid XML characters using the specified encoding. This includes the case where the processor does not support the requested encoding.
    Action: The processor must signal the error.

ERR083

It is a dynamic error if the second argument of the unparsed-text function is omitted and the processor cannot infer the encoding using external information.
    Action: The processor must signal the error.

ERR088

It is a dynamic error if the result of evaluating the use expression [of the xsl:key element] , for any node that matches the pattern specified in the match attribute, cannot be converted to the data type specified by the data-type attribute.
    Action: The processor may signal the error, or may recover by ignoring the existence of the value that cannot be converted.

ERR091

It is a dynamic error if the value [of the first argument to the key function] 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 key declaration in the stylesheet.
    Action: The processor must signal these errors.

ERR092

It is a dynamic error if the stylesheet does not contain a declaration of the decimal-format with the expanded-QName specified as the third argument [ to the format-number function] .
    Action: The processor must either signal the error, or must recover by ignoring the third argument.

ERR095

The picture string [supplied to the format-number function] must conform to the following rules [see full specification] . It is a dynamic error if the picture string does not satisfy these rules.
    Action: The processor must either signal the error, or must recover by ignoring those characters in the supplied picture string that make the picture string invalid. If a valid picture string cannot be constructed, the processor may recover by returning the string obtained by applying the string function to the supplied number.

ERR096

It is a dynamic error if [[while processing the format-number function]] the absolute value of the adjusted number is numerically greater than or equal to the overflow-threshold.
    Action: The processor may signal the error, or may recover by formatting the number as if the formatting picture were extended to the left (after any prefix) with a sufficient number of digit-sign characters to accommodate the adjusted number.

ERR099

It is a dynamic error if value of the argument [to the generate-id] is a sequence other than an empty sequence or a sequence containing a single node.
    Action: If the first item in the sequence is not a node, the processor must signal the error. If the first item in the sequence is a node, the processor may signal the error, or may recover by returning the string that identifies the first node in the sequence.

ERR100

It is a dynamic error if the value [supplied as the first argument to the system-property function] is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName.
    Action: The processor must signal these errors.

ERR101

It is a dynamic error if the argument [passed to the function-available function] 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.
    Action: The processor must either signal the error, or must recover by returning the value false.

ERR102

It is a dynamic error if a FunctionCall within an XPath expression is evaluated, when the function in question is not available.
    Action: The processor must signal the error.

ERR103

It is a 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.
    Action: The processor must signal the error.

ERR104

An external object may only be passed as an argument to another extension function, provided the other extension function is written to accept objects of this type. The effect of performing any other operations, for example comparing two external objects for equality, or converting the external object to a string or boolean, or using an external object as an item within a sequence, or copying an external object to the result tree, is in general implementation-defined, and will cause a dynamic error if the operation is not supported.
    Action: The processor must signal the error.

ERR107

It is a dynamic error if the argument [passed to the element-available function] 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.
    Action: The processor must either signal the error, or must recover by returning the value false.

ERR111

It is a dynamic error to evaluate the xsl:result-document instruction when the current result tree is neither the principal result tree, nor a secondary result tree.
    Action: The processor must signal the error.

ERR112

It is a dynamic error for a transformation to generate two or more result trees with the same URI.
    Action: The processor must signal the error.

ERR113

It is a dynamic error if the value of an attribute [of the xsl:output declaration] does not conform to the rules listed below.
    Action: The processor must either signal the error, or must recover by using the default value for that attribute.

ERR114

It is a dynamic error if two xsl:output declarations within an output definition specify explicit values for the same attribute (other than cdata-section-elements), with the effective values of the attributes being not equal, and with neither of these declarations being overridden by an xsl:output declaration with higher import precedence that specifies an explicit value for the same attribute.
    Action: The processor must either signal the error, or must recover by using the value that occurs last in declaration order.

ERR121

It is a dynamic error for output escaping to be disabled for a text node that is used for something other than a text node in the result tree. Thus, it is an error to disable output escaping for an xsl:value-of or xsl:text element that is used to generate the string-value of a comment, processing instruction or attribute node; it is also a dynamic error to convert a node to a number or a string if the node is, or contains, a text node for which escaping was disabled.
    Action: In both cases, the processor must either signal the error, of must recover by ignoring the disable-output-escaping attribute.

ERR126

It is a dynamic error if the effective value of an attribute written using curly braces, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute.

Serialization errors

ERR115

The value [of the method attribute on xsl:output] must be a valid QName. If the QName does not have a prefix, then it identifies a method specified in this document and must be one of xml, html, xhtml, or text.

ERR116

It is a serialization error to request the output of a document type declaration, or of a standalone attribute, if the result tree contains text nodes or multiple element nodes as children of the root node.
    Action: The processor may signal the error, or may recover by ignoring the request to output a document type declaration or standalone attribute.

ERR117

A serialization error occurs when an output encoding other than UTF-8 or UTF-16 is requested, if the implementation does not support that encoding.
    Action: The processor may signal the error, or may recover by using UTF-8 or UTF-16 instead.

ERR118

A serialization error occurs if such a character [a character that cannot be represented in the encoding that the processor is using for output] appears in a context where character references are not allowed (for example if the character occurs in the name of an element).
    Action: The processor should signal the error.

ERR119

It is possible that the result tree will contain a character that cannot be represented in the encoding that the processor is using for output. In this case, if the character occurs in a context where HTML recognizes character references, then the character should be output as a character entity reference or decimal numeric character reference; otherwise (for example, in a script or style element or in a comment), the processor should signal a serialization error.

ERR120

If the result tree contains a character that cannot be represented in the encoding that the processor is using for output, the implementation should signal a serialization error.

ERR122

It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping should be disabled and the implementation does not support this.
    Action: The processor must either signal the error, of must recover by not disabling output escaping.

ERR123

It is a serialization error if output escaping is disabled for a character that is not representable in the encoding that the processor is using for output.
    Action: The processor must either signal the error, of must recover by not disabling output escaping.

E Checklist of Implementation-Defined Features (Non-Normative)

This appendix provides a summary of XSLT language features whose effect is explicitly implementation-defined. Vendors should provide documentation with each implementation that explains how these choices have been exercised.

F DTD Fragment for XSLT Stylesheets (Non-Normative)

Ed. Note: The DTD for XSLT Stylesheets is not included in this draft. The XSL Working Group intends to provide a DTD and/or Schema for XSLT stylesheets in the final version of this Recommendation.

G Representation of Lexical XML Constructs (Non-Normative)

Sometimes it is useful, when performing a transformation, to retain lexical detail from the source document within the result document. Examples of such details include entity references and CDATA section boundaries. Since these details do not form part of the data model, they are normally lost in the course of transformation, which can make subsequent editing of the document more difficult.

This appendix therefore defines a way in which these lexical details can be represented within the data model, by means of elements in a special namespace, specifically http://www.w3.org/2002/04/XSL/Transform/LexicalMapping, with a conventional prefix of lex. The process that builds the source tree for a transformation may use this mapping to represent lexical constructs encountered in the source document, and the serializer may interpret the elements in this namespace as directives to reproduce these lexical constructs on output. There is no requirement that XSLT processors must support this mapping. The transformation itself does not treat these elements specially; they will be visible to the stylesheet in the same way as any other element, and what happens to them is entirely under the control of the stylesheet author. A stylesheet is free to copy these elements, or to ignore them, or to create new elements in this namespace as directives to the serializer.

If an implementation chooses to support these mappings, it is suggested that this should be done by means of a user option that causes the tree construction process to create the relevant elements, and the serializer to interpret them. This option should not be the default mode of processing.

The elements are listed below:

Element NameAttributes Meaning
lex:cdata-section None Defines a CDATA section. The content of the CDATA section is represented in the form of child nodes of the lex:cdata-section element.
lex:entity-reference name Marks the point in the source text where a general entity reference occurred. The name attribute gives the name of the entity. The expanded content of the entity is represented in the form of child nodes of the lex:entity-reference element. Note that entity references within attribute values cannot be represented this way.
lex:doctype name, public-id, system-id Marks the point in the source text where the DOCTYPE declaration occurred. The name attribute gives the name of the document type. The optional system-id attribute gives the system identifier of the external DTD subset. The optional public-id attribute gives the public identifier of the external DTD subset.
lex:element-declaration name, model Represents an element declaration within the internal DTD subset. This element will appear only as a child of lex:doctype. The name attribute gives the name of the element type. The model attribute gives the content model of the element type, as an unparsed string. This may be normalized, for example by expansion of parameter entities, removal of whitespace, at implementor option.
lex:attribute-declaration element-name, attribute-name, attribute-type, optional, default-value Represents an attribute declaration within the internal DTD subset. This element will appear only as a child of lex:doctype. The element-name attribute gives the name of the element. The attribute-name attribute gives the name of the attribute. The attribute-type attribute gives the attribute type, for example CDATA or IDREFS. The optional attribute takes the value FIXED, REQUIRED, or IMPLIED; it is omitted if none of these is applicable. The default-value attribute gives the default value for the attribute if one has been defined; if not, this attribute is omitted.
lex:notation-declaration name, system-id, public-id Represents an notation declaration within the internal DTD subset. This element will appear only as a child of lex:doctype. The name attribute gives the name of the notation. The optional system-id attribute gives the system identifier of the notation. The optional public-id attribute gives the public identifier of the notation.
lex:unparsed-entity-declaration name, system-id, public-id, notation-name Represents an unparsed entity declaration within the internal DTD subset. This element will appear only as a child of lex:doctype. The name attribute gives the name of the unparsed entity. The system-id attribute gives the system identifier of the unparsed entity. The optional public-id attribute gives the public identifier of the unparsed entity. The notation-name attribute gives the name of the associated notation.

Note that even when using this representation of the lexical structure of an XML document, the tree will contain attribute nodes representing attributes whose values were defaulted from the DTD. A stylesheet that wishes to avoid outputting such attributes must include the necessary logic to avoid this; it is not possible from the tree representation to determine whether the attribute was actually present in the original XML instance.

H Acknowledgements (Non-Normative)

This specification was developed and approved for publication by the W3C XSL Working Group (WG). WG approval of this specification does not necessarily imply that all WG members voted for its approval.

The current chair of the XSL WG is Sharon Adler, IBM. The other members of the XSL WG are:

Principal Alternate Affiliation
Amr Yassin - Philips Electronics
Sanjiva Weerawarana Anders Berglund IBM
Henry Thompson - HCRC Language Technology Group, University of Edinburgh
Bob Lojek - Mozquito Technologies
Jeff Caruso Andrew Greene Pageflex, Inc.
Paul Grosso - Arbortext
Michael Kay Juliane Harbarth Software AG Inc
Jeremy Richman - Interleaf
Norm Walsh Tony Graham Sun Microsystems Inc.
Scott Boag - Lotus Development Corporation
Scott Parnell - Xerox
Perin Blanchard Shon Vella Novell, Inc.
Jonathan Marsh Ashok Malhotra Microsoft Corporation
Zarella Rendon - DataChannel
Bill Lindsey - B-Bop
Chris Maden Ray Waldin Lexica
Peter Van der Beken - Netscape/AOL
Evan Lenz - XYZFind Corp.
Dipak Chopra - SAP Labs
Mark Scardina K Karun Oracle
Daniela Florescu - Propel
Alex Milowski - Markup Technology Ltd.
Kristoffer Rose IBM

The W3C representative on the XSL WG is Max Froumentin.

The following individuals made significant contributions to XSLT 2.0 while they were members of the WG:

This specification builds on the success of the XSLT 1.0 Recommendation. For a list of contributors to XSLT 1.0, see [XSLT 1.0].

I Checklist of Requirements (Non-Normative)

This section provides a checklist of progress against the published XSLT 2.0 Requirements document.

Requirement 1

Must Maintain Backwards Compatibility with XSLT 1.1 [Read this as "with XSLT 1.0"]

Any stylesheet whose behavior is fully defined in XSLT 1.0 and which generates no errors will produce the same result tree under XSLT 2.0

Response

See [K.1 Incompatible Changes]

Requirement 2

Must Match Elements with Null Values

A stylesheet should be able to match elements and attributes whose value is explicitly null.

Response

This has been handled as an XPath 2.0 requirement.

Requirement 3

Should Allow Included Documents to "Encapsulate" Local Stylesheets

XSLT 2.0 SHOULD define a mechanism to allow the templates in a stylesheet associated with a secondary source document, to be imported and used to format the included fragment, taking precedence over any applicable templates in the current stylesheet.

Response

No progress has been made against this requirement.

Requirement 4

Could Support Accessing Infoset Items for XML Declaration

A stylesheet COULD be able to access information like the version and encoding from the XML declaration of a document.

Response

This is not easy: this information is not readily available from XML parsers? Apparently some of this information is being added to the DOM.

Requirement 5

Could Provide QName Aware String Functions

Users manipulating documents (e.g. stylesheets, schemas) that have QName-valued element or attribute content need functions that take a string containing a QName as their argument, convert it to an expanded-QName using either the namespace declarations in scope at that point in the stylesheet, or the namespace declarations in scope for a specific source node, and return properties of the expanded-QName such as its namespace URI and local name.

Response

Functions operating on QNames are included in the XPath 2.0 operators and functions document.

Requirement 6

Could Enable Constructing a Namespace with Computed Name

Provide an xsl:namespace analog to xsl:element for constructing a namespace node with a computed prefix and URI.

Response

An xsl:namespace instruction has been added: see [8.6 Creating Namespace Nodes].

Requirement 7

Could Simplify Resolving Prefix Conflicts in QName-Valued Attributes

XSLT 2.0 could simplify the renaming of conflicting namespace prefixes in result tree fragments, particularly for attributes declared in a schema as being QNames. Once the processor knows an attribute value is a QName, an XSLT processor should be able to rename prefixes and generate namespace declarations to preserve the semantics of that attribute value, just as it does for attribute names.

Response

If an attribute is typed as a QName in the schema, the new XPath 2.0 functions can be used to manipulate it as required at application level. This may be sufficient to meet the requirement.

Requirement 8

Could Support XHTML Output Method

Complementing the existing output methods for html, xml, and text, an xhtml output method could be provided to simplify transformations which target XHTML output.

Response

An XHTML output method is now provided.

Requirement 9

Must Allow Matching on Default Namespace Without Explicit Prefix

Many users stumble trying to match an element with a default namespace.

Response

A new [xsl:]default-xpath-namespace attribute is provided for this purpose.

Requirement 10

Must Add Date Formatting Functions

One of the more frequent requests from XSLT 1.0 users is the ability to format date information with similar control to XSLT's format-number(). XML Schema introduces several kinds of date and time datatypes which will further increase the demand for date formatting during transformations. Functionality similar to that provided by java.text.SimpleDateFormat. A date analog of XSLT's named xsl:decimal-format may be required to handle locale-specific date formatting issues.

Response

Date manipulation functions are included in XPath 2.0, but no formatting capability is provided yet. The XSL Working Group intends to provide such a function in the final Recommendation.

Requirement 11

Must Simplify Accessing Id's and Key's in Other Documents

Currently it is cumbersome to lookup nodes by id() or key() in documents other than the source document. Users must first use an xsl:for-each instruction, selecting the desired document() to make it the current node, then relative XPath expressions within the scope of the xsl:for-each can refer to id() or key() as desired.

Response

The requirement is met by the generalization of path syntax in XPath 2.0

Requirement 12

Should Provide Function to Absolutize Relative URIs

There SHOULD be a way in XSLT 2.0 to create an absolute URI. The functionality should allow passing a node-set and return a string value representing the absolute URI resolved with respect to the base URI of the current node.

Response

This requirement has not yet been addressed.

Requirement 13

Should Include Unparsed Text from an External Resource

Frequently stylesheets must import text from external resources. Today users have to resort to extension functions to accomplish this because XSLT 1.0 only provides the document() function which, while useful, can only read external resources that are well-formed XML documents.

Response

A function unparsed-text has been added.

Requirement 14

Should Allow Authoring Extension Functions in XSLT

As part of the XSLT 1.1 work done on extension functions, a proposal to author XSLT extension functions in XSLT itself was deferred for reconsideration in XSLT 2.0. This would allow the functions in an extension namespace to be implemented in "pure" XSLT, without resulting to external programming languages.

Response

A solution to this requirement, the xsl:function element, is included in this specification. See [7.3 Stylesheet Functions].

Requirement 15

Should Output Character Entity References Instead of Numeric Character Entities

Users have frequently requested the ability to have the output of their transformation use (named) character references instead of the numeric character entity. The ability to control this preference as the level of the whole document is sufficient. For example, rather than seeing &#160; in the output, the user could request to see the equivalent &nbsp; instead.

Response

This requirement has not yet been addressed.

Requirement 16

Should Construct Entity Reference by Name

Analogous to the ability to create elements and attributes, users have expressed a desire to construct named entity references.

Response

An appendix has been added (see [G Representation of Lexical XML Constructs]) defining a method of representing the lexical structure of an XML document within the data model. If this representation is used, elements representing entity references can be constructed in the result tree.

Requirement 17

Should Support for Unicode String Normalization

For reliable string comparison of Unicode strings, users need the ability to apply Unicode normalization before comparing the strings.

Response

This requirement has been addressed in XPath 2.0.

Requirement 18

Should Standardize Extension Element Language Bindings

XSLT 1.1 undertook the standarization of language bindings for XSLT extension functions. For XSLT 2.0, analogous bindings should be provided for extension elements [now renamed extension instructions].

Response

The XSL Working Group has decided not to pursue this requirement, and the attempt to standardize language bindings for extension functions that appeared in the XSLT 1.1 Working Draft has now been withdrawn. The Working Group decided that language bindings would be better published separately from the core XSLT specification.

Requirement 19

Could Improve Efficiency of Transformations on Large Documents

Many useful transformations take place on large documents consisting of thousands of repeating "sub-documents". Today transformations over these documents are impractical due to the need to have the entire source tree in memory. Enabling "progressive" transformations, where the processor is able to produce progressively more output as more input is received, is tantamount to avoiding the need for XSLT processors to have random access to the entire source document. This might be accomplished by:

Identifying a core subset of XPath that does not require random access to the source tree, or

Consider a "transform all subtrees" mode where the stylesheet says, "Apply the transformation implied by this stylesheet to each node that matches XXX, considered as the root of a separate tree, and copy all the results of these mini-transformations as separate subtrees on to the final result tree."

Response

This requirement has not been addressed.

Requirement 20

Could Support for Reverse IDREF attributes

Given a particular value of an ID, produce a list of all elements that have an IDREF or IDREFS attribute which refers to this ID.

This functionality can be accomplished using the current <xsl:key> and key() mechanism.

Response

An idref() function is included in XPath 2.0 Functions and Operators

Requirement 21

Could Support for Case-Insensitive Comparisons

XSLT 2.0 could expand its comparison functionality to include support for case-insensitive string comparison.

Response

This is an XPath 2.0 requirement. XPath 2.0 Functions and Operators includes functions to convert strings to uppercase or lowercase, it also includes functions to compare strings using a named collating sequence, which provides the option of using a collating sequence that treats uppercase and lowercase as equal.

Requirement 22

Could Support Lexigraphic String Comparisons

We don't let users compare strings like $x > 'a'.

Response

This requirement has been addressed in XPath 2.0.

Requirement 23

Could Allow Comparing Nodes Based on Document Order

Support the ability to test whether one node comes before another in document order.

Response

This requirement has been addressed in XPath 2.0.

Requirement 24

Could Improve Support for Unparsed Entities

In XSLT 1.0 there is an asymmetry in support for unparsed entities. They can be handled on input but not on output. In particular, there is no way to do an identity transformation that preserves them. At a minimum we need the ability to retrieve the Public ID of an unparsed entity.

Response

An appendix has been added (see [G Representation of Lexical XML Constructs]) defining a method of representing the lexical structure of an XML document within the data model. If this representation is used, additional information about unparsed entities is available from the source tree, and elements representing unparsed entities can be added to the result tree.

Requirement 25

Could Allow Processing a Node with the "Next Best Matching" Template

In the construction of large stylesheets for complex documents, it is often necessary to construct templates that implement special behavior for a particular instance of an element, and then apply the normal styling for that element. Currently this is not possible because xsl:apply-templates specifies that for any given node only a single template will be selected and instantiated.

Currently the processor determines a list of matching templates and then discards all but the one with the highest priority. In order to support this requirement, the processor would retain the list of matching templates sorted in priority order. A new instruction, for example xsl:next-match, in a template would simply trigger the next template in the list of matching templates. This "next best match" recursion naturally bottoms out at the builtin template which can be seen as the lowest priority matching template for every match pattern.

Response

The working group has discussed this requirement but has not yet produced a proposal that is ready for publication.

Requirement 26

Could Make Coercions Symmetric By Allowing Scalar to Nodeset Conversion

Presently, no datatype can be coerced or cast to a node-set. By allowing a string value to convert to a node-set, some user "gotchas" could be avoided.

Response

The availability of sequences of strings or numbers probably meets most of the use-cases envisaged by this requirement.

Requirement 27

Must Simplify Constructing and Copying Typed Content

It MUST be possible to construct XML Schema-typed elements and attributes. In addition, when copying an element or an attribute to the result, it should be possible to preserve the type during the process.

Response

This is work in progress. Facilities for associating type information with constructed elements and attributes are likely to appear in future drafts of XSLT 2.0.

Requirement 28

Must Support Sorting Nodes Based on XML Schema Type

XSLT 1.0 supports sorting based on string-valued and number-valued expressions. XML Schema: Datatypes introduces new scalar types (for example, date) with well-known sort orders. It MUST be possible to sort based on these extended set of scalar data types. Since XML Schema: Datatypes does not define an ordering for complex types, this sorting support should only be considered for simple types.

Should be consistent with whatever we define for the matrix of conversion and comparisons.

Response

Sorting based on any schema-defined primitive data type is included in this specification.

Requirement 29

Could Support Scientific Notation in Number Formatting

Several users have requested the ability to have the existing format-number() function extended to format numbers using Scientific Notation.

Response

The specification for the format-number has been rewritten to remove the dependency on the JDK 1.1 specification. It could be further enhanced to introduce scientific notation (which would represent an upgrade to the JDK 1.2 specification). Simple scientific formatting is now available through support for the schema-defined xsd:float and xsd:double data types.

Requirement 30

Could Provide Ability to Detect Whether "Rich" Schema Information is Available

A stylesheet that requires XML Schema type-related functionality could be able to test whether a "rich" Post-Schema-Validated Infoset is available from the XML Schema processor, so that the stylesheet can provide fallback behavior or choose to exit with xsl:message abort="yes".

Response

XPath 2.0 allows expressions to determine the type of element and attribute nodes, using information from the schema. The details of how these expressions behave when there is no schema are defined in the XPath specifications.

Requirement 31

Must Simplify Grouping

Grouping is complicated in XSLT 1.0. It MUST be possible for users to group nodes in a document based on common string-values, common names, or common values for any other expression

In addition XSLT must allow grouping based on sequential position, e.g. selecting groups of adjacent <P> elements. Ideally it should also make it easier to do fixed-size grouping as well, e.g. groups of three adjacent nodes, for laying out data in multiple columns. For each group of nodes identified, it must be possible to instantiate a template for the group. Grouping must be "nestable" to multiple levels so that groups of distinct nodes can be identified, then from among the distinct groups selected, further sub-grouping of distinct node in the current group can be done.

Response

A new xsl:for-each-group instruction is provided: see [13 Grouping]. In addition, many of the new functions and operators provided in XPath 2.0 make these algorithms easier to write.

J Summary of Issues (Non-Normative)

J.1 Open Issues

Issue 9: schema-explanation

Description: We need to say something here about schemas and DTDs.

Suggested resolution: Add something along the lines of the type strawman, once our ideas are clearer. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Jan/0113.html (members only) and subsequent discussion.

Issue 10: public-identifiers

Description: There is a requirement to add support for the public identifier of unparsed entities. The Working Group intends to add this feature before final publication of XSLT 2.0.

Suggested resolution: Add a new function unparsed-entity-public-identifier() along the lines of unparsed-entity-URI(). (Check: what is the status of unparsed entities in the data model?)

Issue 11: whitespace-and-schema

Description: If an element has element content, as defined in the schema or DTD, the default should be to strip whitespace nodes rather than preserving them.

Suggested resolution: We should discuss this in Boston

Issue 13: shared-namespace-node-fixup

Description: This section needs to be revised if namespace nodes are to be held at document level.

Suggested resolution: Hold pending, waiting for the data model to be updated.

Issue 14: d-o-e-on-attributes

Description: Should we allow disable-output-escaping on xsl:attribute?

Suggested resolution: Allow it. It's at least as useful as d-o-e for text nodes. Legitimate uses occur when generating pseudo-XML formats that allow elements within attributes, or that allow attributes of the form "&{value}"

Issue 15: restrict-d-o-e

Description: It is proposed that we should restrict the use of disable-output-escaping so it can only be used on a final result tree. This would avoid distorting the data model.

Suggested resolution: Make this restriction.

Issue 16: leading-colon-in-qname

Description: The current XPath grammar allows a QName to contain a leading colon. This leading colon is not considered part of the QName as far as XSLT is concerned, and is not permitted in contexts other than an XPath expression.

Suggested resolution: Pursue this with XPath TF. Do we want to allow the leading colon in XPath (as distinct from XQuery)? If so, the production should not be called "QName".

Issue 20: default-collation

Description: Should there be facilities in XSLT to select the default collation? If so, how should this be scoped?

Suggested resolution: We decided in Cambridge (22 Jan 2002) to wait and see what XQuery does.

Issue 29: runtime-namespace-selection

Description: The default-xpath-namespace facility as proposed here doesn't meet the requirement to match multiple namespaces, or to decide at run-time which namespace to match - as exemplified by the XHTML scenario.

Suggested resolution: Not urgent. Leave it open for now, pending a proposal for a solution.

Issue 30: must-namespaces-precede-attributes

Description: It appears that several implementations currently allow a namespace node to be added after adding attributes (using xsl:copy ). This seems convenient for the user, and the Working Group is inclined to allow it. To achieve this, we will need to define some conflict resolution if the namespace clashes with an existing attribute.

Suggested resolution: Do nothing until data model for namespace nodes is fixed. This will clarify what the ordering rules are for namespaces vs. attributes.

Issue 31: use-constructor-semantics

Description: The above text should be rewritten to provide a formal mapping to the constructor functions defined in the data model.

Suggested resolution: Editor to review, once the data model construction rules are updated to handle namespace fixup.

Issue 38: xpath-variable-shadowing

Description: Can variables declared within an XPath 2.0 expression shadow variables declared at XSLT level?

Suggested resolution: This is essentially an XPath issue. Raise an issue with XPath.

Issue 41: user-functions-vs-vendor-functions

Description: Should user-defined functions override vendor-defined functions of the same name, as specified here, or should it be the other way around?

Suggested resolution: There's been lots of discussion of this on xsl-list (see also the thread starting at http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0010.html ), and there are arguments both ways. In Cambridge (22 Jan 2002) we voted 7-3 that vendor functions should win, but agreed to leave the issue open for now.

Issue 43: result-type-optional

Description: Should the type attribute of xsl:result be mandatory?

Resolution: No, it shouldn't (for consistency). A system that wants to know the result type statically can find out by analysing the xsl:result expression.

Issue 44: define-lre-element-type

Description: Should we add an xsl:type attribute to literal result elements, to define the type of the newly-constructed element node? Alternatively, should xsi:type be used with this meaning? What are the rules governing its use?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 45: lre-element-typed-value

Description: Should we provide a way of supplying the typed value of literal result element, as distinct from its string value, perhaps by means of a xsl:select attribute on the literal result element?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 46: define-element-type

Description: Should we add a type attribute to xsl:element , to define the type of the newly-constructed element node? If so, what are the rules governing its use?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 47: element-typed-value

Description: Should we provide a way of supplying the typed value of a new element node, as distinct from its string value, perhaps by means of a select attribute on the xsl:element instruction?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 48: define-attribute-type

Description: Should we add a type attribute to xsl:attribute , to define the type of the newly-constructed attribute node? If so, what are the rules governing its use?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 49: attribute-typed-value

Description: Should we provide a way of supplying the typed value of a new attribute node, as distinct from its string value, perhaps by means of a select attribute on the xsl:attribute element?

Suggested resolution: Needs discussion (locus: constructing typed results)

Issue 53: converge-with-sortby

Description: While the facility for named sort keys meets the requirement to be able to sort arbitrary sequences, the XSL Working Group would prefer to find a way of converging this capability with the sortby syntax proposed for use in XQuery.

Suggested resolution: Keep open for now, until the XQuery syntax becomes clearer. Add to an XPath TF agenda.

Issue 69: format-currency-sign

Description: Should the prohibition on ¤ in the picture of format-number continue?

Suggested resolution: Start allowing it.

Issue 70: scientific-notation

Description: There is a requirement to allow scientific notation in format-number (it is permitted in the JDK 1.2 version of the original specification). The Working Group intends to add this capability before final publication of XSLT 2.0.

Suggested resolution: David Marston has made a proposal on this. Review this and incorporate it into the text.

Issue 71: position-percent

Description: Must the percent or per-mille sign be immediately after the last digit or decimal-separator? Suggestion: keep the set of legal positions down to the minimum set that will satisfy all world cultures.

Suggested resolution: Leave open for now.

Issue 75: format-date-time

Description: There is a need for an additional function to format dates and times.

Suggested resolution: A draft proposal is at http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Feb/0040.html (members only) ; see also subsequent comments.

Issue 78: external-objects

Description: Do we want to keep the description of external objects (which was introduced in the XSLT 1.1 Working Draft)? What are the data model implications?

Suggested resolution: Ideally we should get this into the data model and remove it from here. In fact, much of the material on extension functions could logically be moved into XPath. Raise as an XPath TF agenda item. Note: discussed at XSL WG Telcon on 2002-03-21. Issue raised against XPath, see http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Mar/0206.html.

Issue 83: result-tree-PSVI

Description: The rules for serialization of the result tree consider it only as an infoset; the rules need to be enhanced to allow for (potential loss of) PSVI information on the tree.

Suggested resolution: Need to discuss this (locus: creating type information in result tree).

Issue 86: conformance-modules

Description: Should we introduce multiple conformance levels or modules, recognizing that serialization is a separate specification to which processors may or may not conform?

Suggested resolution: Define serialization as a separate conformance module.

Issue 87: no-base-uri

Description: In the XPath 2.0 data model, elements have a base URI but attributes and text nodes don't.

Suggested resolution: The description of the document() function should be modified to say that we don't use the text or attribute node containing the relative URI as the base URI directly, rather we take its containing element. Since the document() function has been transferred to XPath, this issue needs to be transferred to the Functions & Operators draft.

Issue 88: output-newlines

Description: Do we want to say anything about the representation of line endings when using the text output method? Do we want to provide any user control in this area?

Suggested resolution: Add a line-ending attribute to xsl:output (for all output methods).

Issue 89: support-SOAP

Description: Should we define a binding to web services accessible using SOAP?

Origin: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0090.html and http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0120.html

Suggested resolution: Decide that this is out of scope for version 2.0?

Issue 90: uri-escaping-rules

Description: Should we say that all non-allowed characters in a URI are escaped (not just non-ASCII characters)?

Origin: See the thread http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0082.html and other discussions.

Suggested resolution: Keep the spec as it is, because changes are too fragile. For example, escaping spaces in a javascript URI, or in a fragment identifier, can be fatal. Instead, we have provided an option to switch off escaping; supplement this with a function escape-URI() to do the escaping manually.

Issue 91: list-of-keys

Description: Would it be useful to provide a function key-values(keyname) that provides a sequence containing all the values for a given key?

Suggested resolution: Add such a function. It should eliminate duplicates but the order of keys in the sequence should be undefined.

Issue 92: residue-on-termination

Description: We need to make it clear that an implementation is (or is not) allowed to leave serialized secondary output documents in filestore following a dynamic error that causes stylesheet termination.

Suggested resolution: Make it implementation defined whether such files might be left behind.

Issue 93: reading-output-documents

Description: We need to make it clear that a stylesheet is not allowed to use the document function to access a serialized secondary output document created during the same transformation.

Suggested resolution: Make it an error and leave the detection implementation defined?

Issue 94: char-representation

Description: Should we provide some control over the way characters are serialized, e.g. as numeric character references or HTML entity references?

Origin: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0113.html and also http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0117.html

Suggested resolution: Don't provide any user control over this, but specify that native characters should be used when within the encodable repertoire, and that HTML entity references are preferred to decimal or hex values for characters outside this repertoire; also, require support for encoding="us-ascii".

Issue 95: NEL-char

Description: Should we make provision for XML 1.1 and its introduction of NEL as a whitespace character?

Origin: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0112.html

Suggested resolution: Keep this under review. Meanwhile add a note anticipating this change.

Issue 96: parse-and-serialize-functions

Description: Should we add functions parse() and serialize()? The parse() function would take source XML as a string, and return a document node; the serialize() function would do the reverse.

Origin: For a use case for serialize(), see http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0112.html

Suggested resolution: Needs discussion.

Issue 97: regexp-support

Description: Should we add support for regular expression matching at the XSLT level?

Origin: There is a fairly detailed proposal from David Carlisle at http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0083.html . There is also a paper from Kristoffer Rose [URL to be provided]

Suggested resolution: Needs discussion.

Issue 98: strip-comments-and-PIs

Description: Should we provide a declaration to control stripping of comments and PIs in the source document? There is a flag in the data model to permit this.

Origin: See the thread starting at http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0054.html . This led to the suggestion that while switches to set the flags might be too much trouble, the ability to interrogate these settings (and also, whether ID attributes are recognized, etc) might be useful.

Suggested resolution: Make no change: too much effort for a small benefit.

Issue 99: sequences-in-XSLT

Description: Should we consider extending XSLT to allow construction of arbitrary sequences?

Origin: See Jeni Tennison's proposal at http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0050.html .

Suggested resolution: We reviewed this in Cambridge (Jan 2002) and agreed to review it again after further study.

Issue 101: copy-aliased-namespaces

Description: The rules for copying the namespace nodes of a literal result element say that a namespace node for the XSLT namespace URI is not copied. What happens if the namespace node has some other URI before xsl:namespace-alias is applied, but has the XSLT namespace URI after xsl:namespace-alias is applied? Current products differ.

Origin: Email to MHK from Eric Bratton at Software AG: http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0125.html

Suggested resolution: Needs further study.

Issue 102: terminology-valid

Description: There are various places in the specification where the word "valid" is used in a sense other than XML (or schema) validity.

Origin: Email to xsl-editors from Elliotte Rusty Harold, dated 3 March 2002: see http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0131.html

Suggested resolution: Examine each individual case.

Issue 104: optional-arguments

Description: Should functions be allowed to take optional arguments?

Origin: The formal semantics for the function callling mechanism in XPath will not allow for optional arguments. It will handle the core functions that have multiple arguments by defining multiple signatures for these functions. Allowing optional arguments for XSLT-defined functions will require an extension to the XPath formal semantics. See also public comment from Karsten Bohlmann, SAP: http://lists.w3.org/Archives/Public/xsl-editors/2002AprJun/0011.html

Issue 105: sequence-valued-sort-key

Description: What happens if the value of a sort key is a sequence?

Origin: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0067.html .

Suggested resolution: In XQuery it is an error. An alternative would be to use "lexicographic" sorting, that is, compare the first items in the two sequences, then the second, and so on until an item is found that differs, or one of the sequences is exhausted.

Issue 106: assert-source-document-type

Description: How should a stylesheet assert the schema type of the source documents that it is designed to process?

Issue 107: variable-validation

Description: Is "validate" invoked automatically when xsl:variable is used to create a temporary tree, and a type is specified? How does this work, given that the type will be a document type, not an element type? What happens if validation fails (and what does it mean for validation to fail)? Should it be possible to request lax validation?

Issue 108: decimal-format-grouping-uniformity

Description: In format-number() all grouping separators except the last are ignored. Internationalization experts may want to make a case for non-uniform grouping sizes, in which case each occurrence of the grouping-separator must be taken as significant. (Note, this issue replaces issue 66).

Issue 110: type-matching-in-patterns

Description: The current syntax for matching elements of a particular type is cumbersome, for example match="*[. instance of element us-address of type address]".

Origin: XSL WG meeting, Cannes, Feb 2002

Suggested resolution: A possible integration of the XPath 2.0 SequenceType syntax with the KindTest syntax has been sketched out. This might allow the above to be written along the lines match="element(us-address, address)"

Issue 111: comments-in-AVTs

Description: Should XPath comments (which are delimited by curly braces) be prohibited within an attribute value template?

Issue 112: serializing-unnormalized-whitespace

Description: We discuss serialization of &#xa; characters in attributes. But the same applies to &#x9; and &#xd; characters in attributes, and to &#xd; characters in text nodes. In each case, the character must be serialized as a character reference if it is to retain its value after a round-trip through the serializer and parser.

Issue 113: global-variables-in-call-mode

Description: It's not obvious what the context should be for evaluating global variables when a transformation is initiated using the "call-transformation" method. The solution adopted here, that the "principal source document" is the document containing the first node of the input sequence, is unsatisfactory, and is included purely to avoid leaving a gaping hole.

Origin: See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0036.html (members only)

Issue 114: avts-in-xsl-output

Description: Review the decision to allow attribute value templates in xsl:output.

Origin: XSL WG telcon 2002-04-25

Issue 115: prefix-aliased-namespaces

Description: Should we make a recommendation about the preferred prefix to be used when xsl:namespace-alias changes the URI of an element or attribute?

Origin: Email to MHK from Eric Bratton at Software AG: http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0125.html

Suggested resolution: Needs further study.

J.2 Decided Issues

These are issues where the working group has made a decision, but the decision is not yet reflected in this draft.

Issue 54: grouping-with-collation

Description: Should we add a collation attribute to xsl:for-each-group, to specify the collation under which strings are compared for equality?

Resolution: Yes. Text reflecting this decision will be included in the next draft.

Issue 55: grouping-with-other-datatypes

Description: Should we allow grouping based on key values whose data type is other than string?

Resolution: Yes. Text reflecting this decision will be included in the next draft.

Issue 109: terminate-as-avt

Description: In xsl:message, should the terminate attribute be changed to be an attribute value template?.

Origin: Message to xsl-editors from Jeni Tennison, dated 9 April 2002

Resolution: Yes, this change should be made. It will be made in a future draft.

J.3 Closed Issues

Issue 1: binding-to-schema

Description: Do we need to say anything, or add any capabilities, for binding a stylesheet to a schema? Presumably the names of types used in variable declarations must be known statically, which implies that a schema is available statically.

Resolution: Add an xsl:import-schema declaration, similar to the "import schema" statement in XQuery. This serves merely to establish a vocabulary of types whose names may appear in the stylesheet, it doesn't imply that the source or result documents must conform to this schema. Multiple declarations should be allowed and conflicts resolved using import precedence.

Issue 2: document-collection

Description: There are suggestions that it should be possible to supply a collection of source documents as input. In this case, it is unclear whether any one of these would be specially identified as the principal source document, or whether the transformation would be applied to each of them independently.

Resolution: We decided in principle to allow a stylesheet to be called with a named template as the entry point, with the ability to access a collection of documents via the input() function. Some details are still to be worked out. See proposal at http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0008.html (members only) and comments on the proposal at http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0036.html (members only)

Issue 3: type-errors

Description: Do we want all type-checking errors to be dynamic errors, as described above? In XSLT 1.0, it's unclear whether implementations are required to report the above as an error, or even whether they are permitted to do so.

Resolution: Type errors may be reported statically as an implementation option.

Issue 4: embedded-simplified-stylesheets

Description: This classification would imply that embedded stylesheet modules cannot be simplified stylesheets. The Working Group does not intend to disallow use of embedded simplified stylesheet modules, and will re-work the text before final publication to permit this combination.

Resolution: Editor to updated the document to make it clear that embedded simplified stylesheets are permitted.

Issue 5: import-first

Description: Is there still any value in the rule that xsl:import elements must come first, given that promotion is needed in the case where a module is imported into an included module?

Resolution: Keep the rule, it's not broken so don't fix it.

Issue 6: import-before-user-defined

Description: Can a user-defined top-level element come before an xsl:import element?

Resolution: No, it can't.

Issue 7: compatibility-static-error

Description: Should it be a static error to invoke backwards compatible behavior with a processor that doesn't support it?

Resolution: No, it should be a dynamic error. This allows the user to test system properties at run-time and take an alternative path.

Issue 8: include-fragment

Description: Is it permitted for the URI reference used in xsl:include and xsl:import to include a fragment identifier, to reference an embedded stylesheet module? And if so, what is the form of the fragment identifier? This isn't clear at 1.0.

Resolution: We decided to leave the semantics of a fragment identifier implementation-defined for the time being, until XPointer is finished; at that time we can define it in terms of XPointer.

Issue 12: stripping-optional

Description: Should we relax the rules on whitespace stripping? When the processor is supplied with an immutable tree as input, it imposes a very significant performance overhead, which may be quite unjustified. Really, whitespace stripping should be part of the tree construction process, not part of the transformation proper. Perhaps we should say something like "there may be operational circumstances in which whitespace stripping is infeasible. In such circumstances, a processor may reject an xsl:strip-space declaration as an error."

Resolution: Leave the specification unchanged.

Issue 17: type-compatibility

Description: We need to provide a more rigorous definition of what it means for the supplied value to be compatible with the required type.

Resolution: It is now defined in terms of the XPath rules: in particular, it is consistent with the handling of arguments to a function call in XPath.

Issue 18: statically-known-types

Description: Are any types, other than those defined in XML Schema (such as xsd:integer) known statically?

Resolution: Same as issue 1. The types that may be used are those defined in the imported schemas.

Issue 19: stylesheet-defined-collations

Description: Should the stylesheet define names of collations? If so, how are they to be described? Should we encourage portability by providing some indirection between the collation name and the underlying collation? But if this is to aid portability, there needs to be a way of selecting different mappings based on the XSLT implementation.

Resolution: We decided that definitions of collations, if included in the stylesheet at all, should be implementation-defined. Text will be added to the specification to explain this.

Issue 21: pattern-compatibility

Description: We need to define the backwards compatibility rules, if patterns contain XPath expressions that are not 100% backwards compatible.

Resolution: The rules are now defined.

Issue 22: allow-intersect-in-patterns

Description: Should we allow the intersect and except operators in patterns? If so, what are the implications on priority of template rules?

Resolution: Don't allow intersect and except in patterns.

Issue 23: id-in-patterns

Description: In patterns, id() and key() with literal arguments are virtually useless in practice. Should we generalize them to allow the argument to be a global parameter?

Resolution: No change needed from XSLT 1.0. The existing facility might not be very useful, but it's not broken.

Issue 24: xsl-default-namespace-lre

Description: Should an xsl:default-xpath-namespace attribute be allowed on literal result elements?

Resolution: Yes, it is now allowed.

Issue 25: default-prefix-or-uri

Description: Should the value of the attribute be a namespace prefix or a namespace URI? We usually use a prefix, but in this case I can see no merit in requiring the namespace to be declared in the stylesheet.

Resolution: The value is a namespace URI.

Issue 26: xsl-default-namespace-everywhere

Description: Should the new attribute be allowed on elements where it has no effect, e.g. xsl:decimal-format?.

Resolution: It is now allowed everywhere, for simplicity

Issue 27: other-general-attributes

Description: Should we allow other "inheritable" attributes, e.g. version, extension-element-prefixes, to be used on any XSLT element? At present they are only allowed on the xsl:stylesheet element or on literal result elements, which can be very restrictive.

Resolution: The rules have been generalized so all these attributes can appear anywhere.

Issue 28: xsl-default-namespace-in-xpath

Description: We need to ensure that XPath 2.0 allows the default namespace to be specified as part of the context.

Resolution: It is defined in the current XPath draft.

Issue 32: variables-in-match-patterns

Description: Is the rule excluding a Variable useful? Its main purpose is to prevent circularity, where a global variable issues xsl:apply-templates and the variable needs to be evaluated to determine the match. But the rule is not sufficient to prevent circularity, because the template rule, once selected, can contain instructions that reference the global variable. However, it might be useful to retain the rule because it helps processors optimize matching of template rules. Also note, the rule needs to be phrased so that range variables declared locally within a sub-expression are permitted.

Resolution: We decided to remove the restriction on having variable references within the match pattern of xsl:template; the editor was actioned to write a proposal. This has been done (possibly twice): see http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Feb/0012.html (members only) and http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0034.html (members only)

Issue 33: apply-templates-on-non-nodes

Description: What happens when the value of the expression in the select attribute is a simple value, or a sequence that contains a simple value? If heterogeneous sequences are disallowed, we can make this an error, as in XSLT 1.0. If they are permitted, the best approach may be to say that there is a built-in rule for simple values that converts the value to a string and outputs it. This isn't likely to be very useful, but it's simple enough to implement and to explain.

Resolution: Treated as a recoverable dynamic error.

Issue 34: parameters-with-built-in-templates

Description: Would it be useful to define that parameters to a built in template are passed through unchanged? This is a frequent source of user bewilderment. The change would be technically backwards incompatible, but very unlikely to have adverse effects.

Resolution: We decided to change the rules so the built-in templates pass parameters through unchanged. This removes a common usability trap, and is very unlikely to affect any existing stylesheets adversely.

Issue 35: variable-type-semantics

Description: We need to say more about the permitted values of the type attribute, and their meaning, once the XPath rules are clearer. For example, are all the permitted names of types known statically, and if so, where do these names come from?

Resolution: The valid values for the type attribute are the same as the valid values for the SequenceType production in XPath; the names of types must be types that are statically known as a result of xsl:import-schema (or built-in types). Note that although this issue is closed, there remain open issues about the typing of temporary trees: see issue 107.

Issue 36: variable-type-conversion

Description: Should the type attribute on xsl:variable cause the supplied value to be converted to the required type, or should it cause a dynamic error to be signaled if the supplied value does not conform to the required type: perhaps with conversion as a recovery action?

Resolution: There should be a conversion of the supplied value to the required type, using the rules for conversion of arguments to a function call as defined in XPath 2.0.

Issue 37: variable-type-mandatory

Description: Should we make the type attribute on xsl:variable mandatory (but with provision for backwards compatibility), or allow a mode of execution in which the attribute is mandatory?

Resolution: The Working Group decided that this attribute should not be mandatory.

Issue 39: add-type-to-with-param

Description: Should we add a type attribute to xsl:with-param, for symmetry with xsl:variable and xsl:param?

Resolution: Yes, it has has now been added.

Issue 40: with-param-verbosity

Description: Should we introduce an alternative and less verbose syntax for passing parameters when invoking a template?

Resolution: We decided to close this issue making no change to the specification. Users will make increasing use of functions rather than named templates, and function calls already have a concise syntax.

Issue 42: too-many-params-error

Description: Should it be a static or a dynamic error if too many parameters are supplied? It's described here as a static error, because it can be detected statically, even though this seems inconsistent with the fact that it's a dynamic error if the function doesn't exist, which is done so that function-available() works.

Suggested resolution: We decided to close this issue and make no change to the specification. Leave it as a static error.

Issue 50: xsl-value-of-first-node-semantics

Description: Do we want xsl:value-of to retain first-node semantics as in XPath 1.0? If the value is a sequence, should it be the first in document order or the first in sequence order? What if the value is a sequence of simple values?

Resolution: Retain XSLT 1.0 behavior in the absence of the new separator attribute.

Issue 51: for-each-and-sequences

Description: We need to decide how xsl:for-each should handle sequences of simple values, or heterogeneous sequences.

Resolution: Any kind of sequence can be processed; the generalization of context node to context item makes this possible.

Issue 52: descending-duplicates

Description: We are saying here that with order="descending", duplicates are delivered in reverse document order. XSLT 1.0 implied that they were delivered in forwards document order.

Resolution: They are now in forwards order (again). It has to be this way, because there might be multiple sort keys.

Issue 56: group-ending-with

Description: A use case has also been identified for a group-ending-with attribute. This arises when all but the last item in a sequence carries a continuation marker of some kind.

Suggested resolution: Add this attribute. The specification is very similar to group-starting-with.

Issue 57: namespace-for-additional-functions

Description: Should functions defined in XSLT (additional to those defined in XPath) use a different namespace, perhaps the XSLT namespace, to avoid any future conflicts with functions defined in the core?

Resolution: We decided (Cambridge 22 Jan 2002) to close this issue with no change to the specification.

Issue 58: document-function-in-core

Description: The Functions and Operators specification describes an xf:document function which should supersede the one described here, allowing this section to be removed. However, at present the specification here is rather more complete.

Resolution: The next issue of F&O is expected to adopt our spec; we can then remove it from XSLT.

Issue 59: document-fragment-id

Description: Should we be more prescriptive about the form of fragment identifier supported by the document function? Should we perhaps (following XInclude) mandate that it should be treated as an XPointer? Should we drop the notion that the form of fragment identifier depends on the media type, given that we are going to treat the actual media type as text/xml regardless?

Resolution: We decided (Cambridge 22 Jan 2002) to wait and see what happened to the XPointer specification.

Issue 60: collation-in-keys

Description: Should xsl:key specify a collation to be used for matching strings?

Resolution: Yes, it should. Add a collation attribute to xsl:key. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0035.html (members only)

Issue 61: datatype-in-keys

Description: Should xsl:key allow comparison of values using data types other than string?

Resolution: Yes, it should. Add a type (or data-type?) attribute to xsl:key. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0035.html (members only)

Issue 62: sequence-valued-keys

Description: What if the second argument to key() is an attribute of type IDREFS? We should consider the typed-value of the nodes in the sequence, not just the string value.

Resolution: We decided in principle that the key function should take the typed values of the second argument into account. The editor was actioned to prepare text to implement this. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0035.html (members only)

Issue 63: format-number-and-jdk

Description: The JDK 1.1 specification is insufficiently rigorous. Is there anything better available?

Resolution: A new specification, independent of the JDK, has been written.

Issue 64: invalid-format-pattern

Description: Need to specify what happens if the format pattern is invalid. Is there a recovery action?

Resolution: The number should be output using standard conversion to a string.

Issue 65: format-number-left-to-right

Description: This version of the format-number specification makes the presumption that numbers will be formatted with the most significant digit on the left. Do we want to make this assumption?

Origin: See also http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0032.html

Resolution: We decided to close the issue and make no change to the specification. Apparently all known languages use this convention (at least when using decimal numbers!).

Issue 66: decimal-format-grouping-size

Description: The xsl:number instruction uses an explicit option to set grouping-size, while in format-number() it is derived by inspection of the pattern. Should the two work the same way, which would mean adding a grouping-size to xsl:decimal-format?

Suggested resolution: Replaced by issue 108.

Issue 67: allow-grouping-in-fractional-part

Description: Should it be possible to use grouping-separators in the fractional part?

Resolution: Yes, the current algorithm allows it. This is because (a) it's functionally beneficial, and (b) there may be a culture in the world that wants them.

Issue 68: error-multiple-clusters-active-characters

Description: Should it be an error to have more than one cluster of digit and/or zero-digit characters, or should all clusters after the first just be assumed to be part of the suffix?

Resolution: Make it an error, because it almost always would be, and the stylesheet writer should use concat() for all but the simplest prefixes and suffixes anyway.

Issue 72: overflow-filler

Description: Should overflows be represented by a filler pattern? What is the overflow filler pattern?

Resolution: We decided (Cambridge 22 Jan 2002) to define this as a dynamic error, with an optional recovery action that displays all significant digits to the left of the decimal point even if the result is too large for the space available; that is, it respects the value but not the format.

Issue 73: evaluate-function

Description: Should an evaluate() function be provided? It is useful, but has significant implications on the run-time architecture of the processor, as well as the ability to do static optimization.

Resolution: We decided not to pursue this requirement. The remaining references to dynamic evaluation will therefore be removed from the specification.

Issue 74: variables-in-evaluate

Description: Do we want to allow dyamically constructed expressions to contain variable references and/or calls on non-core functions? The current text is a compromise, it effectively makes it an implementor option.

Resolution: This issue disappears with the resolution of issue 73.

Issue 76: current-in-pattern

Description: The rule banning use of current() in a pattern could be relaxed. For example, it would be simpler to say that current() refers to the node being tested against the pattern.

Resolution: In a pattern, current() should refer to the node being tested. There are not many cases where this is needed, but it is easier for implementations to allow it than to enforce the restriction. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Mar/0034.html (members only)

Issue 77: message-destination

Description: Should we provide attributes to control the formatting and/or destination of messages? Indeed, is there any real difference between a message and a secondary result document?

Resolution: We decided to close the issue, making no change to the specification.

Issue 79: null-external-object

Description: Should the spec have the concept that an external object may be null, and provide a way for testing this, for example, by conversion to boolean ?

Suggested resolution: No, it shouldn't. External objects should be manipulated entirely by extension functions. Drop this issue.

Issue 80: destination-element-name

Description: Is it possible to find a better name for the xsl:destination element? The name xsl:principal-result has been suggested.

Resolution: We decided to change the name to xsl:principal-result-document

Issue 81: message-document

Description: What should happen if xsl:result-document occurs inside xsl:message ?

Resolution: It's an error.

Issue 82: more-than-one-output-value

Description: Is it an error if an attribute of xsl:output is specified more than once, but they all have the same value? An analogy with xsl:decimal-format would suggest not. This would also seem to be the only excuse for making this a dynamic error rather than a static one.

Resolution: It should not be an error to specify the same attribute more than once, unless the values conflict.

Issue 84: XHTML-URI-escaping

Description: Should the XHTML output method perform URI escaping of attributes that are known to be URI values, in the same way as the HTML output method?

Resolution: Yes, but under the control of a new escape-uri-attributes attribute on xsl:output.

Issue 85: XHTML-v11

Description: We currently reference XHTML 1.0. We need to examine the possible impact of XHTML 1.1.

Resolution: No technical changes are needed to support XHTML 1.1. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Jan/0108.html (members only) . However, we need to update the references.

Issue 100: messages-in-functions

Description: Should we allow xsl:message to be used from within xsl:function?

Origin: See http://lists.w3.org/Archives/Public/xsl-editors/2002JanMar/0034.html .

Resolution: We decided to allow this.

Issue 103: apos-in-XHTML

Description: The entity reference &apos; should probably be avoided when producing output using the XHTML output method.

Origin: Correspondence on xml-dev (Mar 2002, thread "Is "apos" still valid as per XML specs?") suggests that &apos; is not supported in all HTML browsers and should therefore be avoided in XHTML.

Resolution: Recommend that in XHTML output, a character reference be used instead.

K Changes from XSLT 1.0 (Non-Normative)

K.1 Incompatible Changes

This section lists all known cases where a stylesheet that was valid (produced no errors) under XSLT 1.0, and whose behavior was fully specified by XSLT 1.0, will produce different results under XSLT 2.0.

Most of the discussion is concerned with compatibility in the absence of a schema: that is, it is assumed that the source document being transformed has no schema when processed using XSLT 1.0, and that no schema is added when moving to XSLT 2.0. Some additional factors that come into play when a schema is added are noted at the end of the section.

K.1.1 XSLT 2.0 Backwards Compatibility

If the source documents supplied as input to a transformation contain no type information generated from a schema (or by generating a PSVI from information in the DTD), then the known areas of incompatibility are as follows:

  • A stylesheet that specifies a version number other than 1.0 was defined in XSLT 1.0 to execute in forwards-compatible mode; if such a stylesheet used features that are not defined in XSLT 2.0 then errors may be reported by an XSLT 2.0 processor that would not be reported by an XSLT 1.0 processor.

  • If the xsl:number element was called with a value attribute whose value was a node-set containing more than one node, then an XSLT 1.0 processor would output the numeric value of the first node in the node-set. An XSLT 2.0 processor will output the numeric value of every node in the equivalent node sequence. If the node-set was empty, an XSLT 1.0 processor would output "NaN"; an XSLT 2.0 processor will output nothing.

  • At XSLT 1.0 the system-property function, when called with a first argument of "xsl:version", returned 1.0 as a number. At XSLT 2.0 it returns "2.0" as a string.

  • When the data-type attribute of xsl:sort has the value number, an XSLT 1.0 processor would evaluate the sort key as a string, and convert the result to a number. An XSLT 2.0 processor evaluates the sort key as a number directly. This only affects the outcome in cases where conversion of a number to a string and then back to a number does not produce the original number, as is the case for example with the number Positive Infinity.

  • XSLT 1.0 allowed the data-type attribute of xsl:sort to be a QName with a prefix. The semantics of this were left implementation-defined. XSLT 2.0 defines a meaning for data-types of this form; these semantics may be incompatible with the semantics offered by some XSLT 1.0 implementations.

  • The specification of the format-number function has been rewritten to remove the normative dependency on the Java JDK 1.1 specification. The JDK 1.1 specification left aspects of the behavior undefined; it is therefore possible that some cases will give different results. The ability to include literal text in the format picture (enclosed in single quotes) has been removed; any stylesheet that uses this feature will need to be modified, for example to display the literal text using the concat function instead.

  • If no output method is explicitly requested, and the first element node output appears to be an XHTML document element, the output method now defaults to XHTML; previously the XML output method would have been used.

  • At XSLT 1.0, if a built-in template rule was invoked with parameters, the parameters were not passed on to any templates invoked by the built-in rule. At XSLT 2.0, these parameters are passed through the built-in template rule unchanged.

K.1.2 XPath 2.0 Backwards Compatibility

Information about incompatibilities between XPath 2.0 and XPath 1.0 is included in [XPath 2.0]

This section provides a summary of the main areas of incompatibility between XPath 2.0 and XPath 1.0. Many of these are areas where the specification still has open issues outstanding, so this list should not be taken as final. It is the intention of the working group to review all known incompatibilities before final publication.

The list given here assumes (a) that the source document is processed in the absence of a schema, and (b) that the policy for handling type exceptions is flexible: that is, that the software attempts wherever possible to perform conversions from the supplied type of a value to the type required by the operation or function where it is used.

In the description below, the terms node-set and number are used with their XPath 1.0 meanings, that is, to describe expressions which according to the rules of XPath 1.0 would have generated a node-set or a number respecively.

  • The rules for comparing a node-set to a boolean have changed. In XPath 1.0, an expression such as $nodeset=true() was evaluated by converting the node-set to a boolean and comparing the result: so this expression would return true if $nodeset was non-empty. In XPath 2.0, this expression is handled in the same way as other comparisons between a sequence and a singleton: it is true if $nodeset contains at least one node whose typed value is true.

  • The rules for converting a string to a boolean have changed, so they are now aligned with XML Schema. The rules depend on the context of the expression. For arguments of functions where a boolean is expected, and for the operands of and and or in XPath 2.0, the strings "0" and "false" are treated as false, while in XPath 1.0, they were treated as true. All other strings are converted in the same way as XPath 1.0. In predicates, however, a string is an error in XPath 2.0, no string to boolean conversion is currently defined.

  • Additional numeric types have been introduced, with the effect that arithmetic may now be done as an integer, decimal, or single-precision floating point calculation where previously it was always performed as double-precision floating point. This may affect the precision of the results, and may cause errors if division by zero is attempted.

  • The rules for converting numbers to strings have changed. These will affect the way numbers are displayed in the output of a stylesheet. The output format depends on the data type of the result: floating point values, for example, will be displayed using scientific notation. The result of a decimal calculation such as 1.5 + 3.5 will be displayed as 5.0, not 5 as previously. The general rule is that the resulting string uses the canonical lexical representation for the data type as defined in XML Schema.

  • The rules for converting strings to numbers have changed. A string that cannot be interpreted as a number now (subject to resolution of an open issue) produces an error, whereas in XPath 1.0 it produced the value NaN (not a number). The representation of special values such as Infinity has been aligned with XML Schema. Strings containing a leading plus sign, or numbers in scientific notation, may now be converted to ordinary numeric values, whereas in XPath 1.0 they were converted to NaN.

  • Many operations in XPath 2.0 produce an empty sequence as their result when one of the arguments or operands is an empty sequence. With XPath 1.0, the result of such an operation was typically an empty string or the numeric value NaN. Examples include the arithmetic operators, and functions such as substring and name. Functions also produce an empty sequence when applied to an argument for which no other value is defined. However, for core functions such as name, the XPath 1.0 behavior has been retained, so that (for example) the name function when applied to a text node returns an empty string.

  • In XPath 1.0, the sum of an empty node-set was zero. At XPath 2.0, it is an empty sequence.

  • In XPath 1.0, an equality comparison involving an element node was performed by comparing its string value, that is, the string obtained by concatenating all its text node descendants. In XPath 2.0, it is an error to use an element node in such a comparison unless it has simple content. However, because the = operator tests whether any pair of items from the two operands are equal, this error will generally be masked, so a comparison such as PERSON='abc', where PERSON is an element with one or more child elements, will now always return false.

  • In XPath 1.0, the < and > operators, when applied to two strings, attempted to convert both the strings to numbers and then made a numeric comparison between the results. In XPath 2.0, subject to resolution of an open issue, it is proposed that these operators should perform a lexicographic comparison using the default collation.

  • In XPath 1.0, functions and operators that compared strings (for example, the = operator and the contains function) worked on the basis of character-by-character equality of Unicode codepoints, allowing Unicode normalization at the discretion of the implementor. In XPath 2.0 (subject to resolution of open issues), these comparisons are done using the default collation. The working group may define mechanisms allowing codepoint comparison to be selected as the default collating sequence, but there is no such mechanism in the current draft.

  • If an arithmetic operator is applied to an operand that is a sequence of two or more nodes, at XPath 1.0 the numeric value of the first node in the sequence was used. At XPath 2.0, this is an error. (The current XPath 2.0 specification does not invoke fallback conversion in this case).

  • In the XPath 1.0 data model, an element node had a namespace node for each in-scope namespace. The parent of the namespace node was the element node, and the namespace nodes for one element were distinct from those of any other element (as revealed, for example, using the union operator |). In XPath 2.0 (subject to resolution of open issues) element nodes will still have namespace nodes for all the in-scope namespaces, but these namespace nodes will be shared by different elements in the same document: that is, there will be a many-to-many relationship between element nodes and namespace nodes. This will affect any code that attempts to find the parent or ancestors of a namespace node, or that tries to count namespace nodes or to form a union between two sets of namespace nodes.

K.1.3 Compatibility in the Presence of a Schema

An XSLT 1.0 processor ignored all information about data types that might be obtained from a schema or DTD associated with a source document. An XSLT 2.0 processor will take account of such information. This may lead to a number of differences in behavior. An implementation may provide facilities to handle the document as if the schema information were not available. This section attempts only to give some examples of the kind of differences that might be expected when schema information is made available:

  • Operations such as sorting will be sensitive to the data type of the items being sorted. For example, if the data type of the sort key is defined in the schema as a date, then in the absence of a data-type attribute on the xsl:sort element, the sequence will be sorted in date order. With XSLT 1.0, the dates would be compared and sorted as strings.

K.2 Changes from XSLT 1.0 to XSLT 1.1

XSLT 1.1 was published as a working draft (see [XSLT 1.1 WD]) on 10 December 2000. Subsequently, the XSL Working Group decided not to take XSLT 1.1 forwards to Recommendation status, but rather to use the document as a baseline for the development of XSLT 2.0.

The following were the principal changes between XSLT 1.0 and XSLT 1.1. These changes are retained in this XSLT 2.0 working draft, except where noted.

Reported errors in XSLT 1.0 were also fixed.

K.3 Changes from XSLT 1.1 to XSLT 2.0

This section summarizes the changes that have been made in this draft. These are arranged in three groups. Firstly, the changes that pervade the entire text. Secondly, the major new features introduced. And thirdly, a catalog of minor technical changes.

K.3.1 Pervasive changes

  • There has been significant re-arrangement of the text. More terminology definitions have been hyperlinked, and a glossary (see [B Glossary]) has been added.

  • The specifications of some features (notably keys, xsl:number, the format-number function, and the xsl:import mechanism) have been rewritten to make them clearer and more precise.

  • A number of changes have been made to support the XPath 2.0 data model, notably the support for sequences as a replacement for the node-sets of XPath 1.0. This has affected the specification of elements such as xsl:for-each, xsl:value-of, and xsl:sort.

  • The processing model is described differently: instead of instructions "writing to the result tree", they now return nodes or node-sequences. This change is largely one of terminology: it paves the way to a more formal definition of the language, sharing a common semantic model with the draft XML Query specifications, and mapping directly to the constructor functions defined in the data model.

  • The description of the evaluation context has been changed. The concept of current node and current node list have been replaced by the XPath concepts of context item, context position, and context size.

  • With the introduction of support for XML Schema within XPath 2.0, XSLT has moved in the direction of supporting stronger data typing, while retaining backwards compatibility. In particular, the types of variables and parameters can now be specified explicitly.

  • The description of error handling has been improved (see [1.8 Error Handling]). This formalizes the difference between static and dynamic errors, and tightens the rules that define which errors must be reported under which conditions.

K.3.2 Major Features

  • Facilities are introduced for grouping of nodes (the xsl:for-each-group instruction, and the current-group() function). See [13 Grouping]

  • It is now possible to create user-defined functions within the stylesheet, that can be called from XPath expressions. See [7.3 Stylesheet Functions].

  • The facility for multiple output documents, already introduced in the XSLT 1.1 Working Draft, is significantly revised. It now separates the production of multiple result trees from their serialization, and defines more carefully the rules that apply to the creation of links between the different result trees by means of relative URIs. See [17.2 Secondary Result Trees].

  • An XHTML output method has been added. See [18.2 XHTML Output Method].

  • A new xsl:sort-key declaration is available to define named sort specifications, supporting an additional sort to allow a sequence to be sorted from within an XPath expression. A collation attribute has been added to the xsl:sort element to allow sorting using a user-defined collation.

K.3.3 Minor Changes

  • The text for [4.3 Patterns] has been revised to align it with the new XPath grammar. The formal semantics of patterns has been simplified: this became possible because of the extra compositionality now available in the expression grammar. The syntax and semantics of patterns remains essentially unchanged, except that XPath 2.0 expressions can be used within predicates.

  • A backwards-compatible processing mode is introduced. See [2.6 Backwards-Compatible Processing]

  • The system-property function now always returns a string. Two new system properties product-name and product-version have been defined. See [14.6.4 system-property()].

  • Namespace fixup is no longer required for documents supplied as source documents or returned by extension functions. See [3.5 Namespace Fixup].

  • With <xsl:message terminate="yes">, the processor now must terminate processing. Previously the word should was used. See [15 Messages].

  • It is now specified that the omit-xml-declaration attribute is ignored if standalone or encoding needs to be included in the XML declaration. See [18.1 XML Output Method].

  • A new include-content-type attribute has been added to xsl:output to suppress the generation of a meta element in HTML and XHTML output.

  • A new instruction xsl:namespace is available, for creating namespace nodes: see [8.6 Creating Namespace Nodes].

  • A new [xsl:]default-xpath-namespace attribute is available to define the default namespace for unqualified names in an XPath expression or XSLT pattern.

  • The attributes [xsl:]version, [xsl:]exclude-result-prefixes, and [xsl:]extension-element-prefixes, as well as the new [xsl:]default-xpath-namespace, can be used on any XSLT element, not only on xsl:stylesheet and on literal result elements as before. In particular, they can now be used on the xsl:template element.

  • The xsl:text instruction has been brought into line with xsl:attribute, xsl:comment, and the like. It is now possible to use instructions such as xsl:value-of and xsl:if within an xsl:text element.

  • A new unparsed-text function is introduced. It allows the contents of an external text file to be read as a string.

K.3.4 Changes in this draft

Changes since the December 2001 working draft are highlighted in the text. They fall into the following main categories:

  • Addition of the xsl:import-schema declaration, together with additional detail on the way types are handled, statically and dynamically.

  • A transformation may now be invoked by calling a named template, supplying input by means of the new input function defined in [Functions and Operators].

  • Addition of the group-ending-with attribute to the xsl:for-each-group instruction

  • Adding the capability for typed comparisons to xsl:key and xsl:sort. Similar changes are likely to be made to xsl:for-each-group in a future draft.

  • Removal of specific restrictions on the use of variables within patterns and key definitions; in their place a more general statement of the restrictions preventing circularity has been formulated. The current function may also now be used within patterns.

  • The built-in templates for element and document nodes now pass any supplied parameter values on to the templates that they call.

  • The description of the algorithm for use in the format-number function has been simplified, without changing its effect.

  • The definition of the document function has been transferred to [Functions and Operators].

  • Resolution of numerous issues, and addition of some new issues, many of these in response to public comments.

  • The terms implementation-defined and implementation-dependent are now defined and used consistently, and a checklist of implementation-defined features is provided (see [E Checklist of Implementation-Defined Features]).