XSL Transformations (XSLT) Version 2.0

1.1 What is XSLT?

This specification defines the syntax and semantics of the XSLT 2.0 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 elements that are defined by XSLT as well as elements that are not defined by XSLT. XSLT-defined elements are distinguished by use of the namespace http://www.w3.org/1999/XSL/Transform (see 3.1 XSLT Namespace), which is referred to in this specification as the XSLT namespace. Thus this specification is a definition of the syntax and semantics of the XSLT namespace.

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

A transformation expressed in XSLT describes rules for transforming one or more source trees into one or more result trees. 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 a result tree. The structure of the result trees can be completely different from the structure of the source trees. In constructing a result tree, nodes from the source trees can be filtered and reordered, and arbitrary structure can be added. This mechanism allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

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

1.2 What's new in XSLT 2.0?

XSLT 1.0 was published in November 1999, and version 2.0 represents a significant increase in the capability of the language. A detailed list of changes is included in K Changes from XSLT 1.0. XSLT 2.0 has been developed in parallel with XPath 2.0 (see [XPath 2.0]), so the changes to XPath must be considered alongside the changes to XSLT.

2.1 Terminology

For a full glossary of terms, see B Glossary.

The software responsible for transforming source trees into a result trees 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 .

Note:

The precise meanings of the terms source tree and result tree, as used in this specification, depend on the context. In the context of the stylesheet as a whole, the source trees are the trees provided as the initial input to the transformation, together with any trees supplied as stylesheet parameters and any trees accessed using the fn:document or fn:collection functions; while the result trees are the trees created by an explicit xsl:result-document instruction as well as the implicit result tree created in the absence of an xsl:result-document instruction. In the context of an individual instruction in the stylesheet, the term source tree also includes any temporary tree that the instruction is using for input, and the term result tree includes any temporary tree that the instruction is using for output.

In this specification the words must, must not, should, should not, may, required, and recommended are to be interpreted as described in [RFC2119].

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.

Paragraphs labelled as Notes or described as examples are non-normative.

2.2 Notation

In this document 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. A full list of all these specifications can be found in C Element Syntax Summary. The meaning of syntax summary notation is as follows:

• An attribute is required if and only if its name is in bold.

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

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

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

[ERR001] 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. [ERR002] 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. [ERR003] 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 3.7 Forwards-Compatible Processing.

Ed. Note:

This working draft includes an XML Schema for XSLT stylesheet modules: see F Schema for XSLT Stylesheets. However, it has been decided to retain the syntax summaries in their present form as these are thought to be easier to read.

XSLT defines a set of standard functions which are additional to those defined in [Functions and Operators]. The signatures of these functions are described using the same notation as used in [Functions and Operators].

2.3 Initiating a Transformation

This document does not specify any application programming interfaces or other interfaces for initiating a transformation. This section, however, describes the information that must be supplied when a transformation is initiated.

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

The following information is supplied to execute a transformation:

• An identification of the stylesheet module that is to act as the principal stylesheet module for the transformation. The complete stylesheet is assembled by expanding the xsl:import and xsl:include declarations in the principal stylesheet module, as described in 3.8.1 Stylesheet Inclusion and 3.8.2 Stylesheet Import

• A set (possibly empty) of values for stylesheet parameters (see 9.5 Global Variables and Parameters). These values are available for use within expressions in the stylesheet.

• A set of nodes (possibly empty) 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 fn:input function described in [Functions and Operators].

• A node that acts as the initial context node for the transformation. This node is accessible within the stylesheet as the initial value of the XPath expressions . and self::node(), as described in 2.5 Maintaining Position: the Focus . If no initial context node is supplied explicitly, then the stylesheet is invoked with an initial context node in the form of a document node with no children.

  Note:

  It is not necessary for the initial context node to be a member of the initial input sequence, but in a simple transformation of a single document, it is convenient to set both the initial input sequence and the initial context node to the document node of the source document to be transformed.

• Optionally, the name of a named template which is to be executed as the entry point to the transformation. This template must exist within the stylesheet. If no named template is supplied, then the transformation starts with the template rule that best matches the initial context node, according to the rules defined in 6.3 Conflict Resolution for Template Rules.

  Issue 146 (named-template-entry-points): The current specification says that any named template can be used as an entry point to the transformation. This requires the compiled form of a stylesheet to retain the names and the body of all templates, including those that are never referenced. This is bad news when a stylesheet imports a large library of general-purpose templates.

• A base output URI, that is, a URI to be used as the base URI when resolving a relative URI allocated to a result tree. If the transformation generates multiple result trees, then typically each one will be allocated a URI relative to this base URI.

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

Parameters passed to the transformation by the client application are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the first template to be executed. All template parameters within the first template to be executed will take their default values. [ERR005] It is a dynamic error if the first template executed by the transformation defines template parameter that specifies required="yes". The processor must signal the error.

A stylesheet can process further source documents in addition to those supplied when the transformation is invoked. These additional documents can be loaded using the functions fn:document or fn:collection described in [Functions and Operators], or they can be supplied as stylesheet parameters (see 9.5 Global Variables and Parameters), or as the result of an extension function (see 18.1 Extension Functions

2.4 Executing a Transformation

The XSLT instructions used to control a transformation can be divided into two groups: push processing instructions, which use template rules to define the processing associated with different nodes in a source tree, and pull processing instructions, which allow the selection and processing of source tree nodes to be described together. These two groups of instructions are described in the following sections.

<doc>
  <item>1</item>
  <item>2</item>
  <item>3</item>
</doc>

<xsl:template match="item">
<li><xsl:value-of select="."/></li>
</xsl:template>

  <li>1</li>
  <li>2</li>
  <li>3</li>

<xsl:template match="doc">
<ol><xsl:apply-templates select="*"/></ol>
</xsl:template>

<ol>
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ol>

2.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 three values:

• The context item is the item currently being processed. An item (see [Data Model]) is either an atomic value (such as an integer, date, or string), or a node. The context item is initially set to the initial context node supplied when the transformation is invoked (see 2.3 Initiating a Transformation). It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; each item in such a sequence becomes the context item while that item is being processed. The context item is returned by the XPath expression . (dot).

• The context position is the position of the context item within the sequence of items currently being processed. It changes whenever the context item changes. When an instruction such as xsl:apply-templates or xsl:for-each is used to process a sequence of items, the first item in the sequence is processed with a context position of 1, the second item with a context position of 2, and so on. The context position is returned by the XPath expression fn:position().

• The context size is the number of items in the sequence of items currently being processed. It changes whenever instructions such as xsl:apply-templates and xsl:for-each are used to process a sequence of items; during the processing of each one of those items, the context size is set to the count of the number of items in the sequence (or equivalently, the position of the last item in the sequence). The context size is returned by the XPath expression fn:last().

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

The current function can be used within any XPath expression to select the item that was supplied as the context item to the XPath expression by the XSLT processor; unlike . this is unaffected by changes to the context item that occur within the XPath expression. The current function is described in 16.5.1 current.

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.

When a stylesheet function is called, the focus within the body of the function is initially undefined. [ERR006] When the focus is undefined, evaluation of any expression that references the context item, context position, or context size results in a dynamic error. The processor must signal the error.

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. A singleton focus based on a node N has the context item (and therefore the context node) set to N, and the context position and context size both set to 1 (one).

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

• The current destination node, which is the document or element node to which newly constructed nodes will be added as child nodes, attribute nodes, or namespace nodes: see 2.4.3 Result Tree Construction

• The current template, which is the template rule most recently invoked by an xsl:apply-templates or xsl:apply-imports instruction: see 6.6 Overriding Template Rules

• The current mode, which is the mode in which the current template rule was invoked: see 6.4 Modes

• The current group, which is the set of nodes currently being processed by an xsl:for-each-group instruction: see 14.1 The Current Group

• The current set of captured substrings, which is maintained when a string is matched against a regular expression using the xsl:analyze-string instruction, and which is accessible using the regex-group function: see 15 Regular Expressions

As with the focus, these variables are not accessible within a stylesheet function unless they have been initialized within that function.

2.6 Parsing and Serialization

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

The stylesheet does not describe how a 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 XPath data model as described in [Data Model], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.

A frequent requirement is to output a 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 20 Serialization) which allows a stylesheet to specify the desired properties of a serialized output file. Implementations that do not serialize result trees 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, a non-normative 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.

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

2.8 Stylesheets and Schemas

An XSLT stylesheet can make use of information from XML Schemas, as defined in [XML Schema]. An XSLT transformation can take place in the absence of a schema (and, indeed, in the absence of a DTD), but where the source document has undergone schema validity assessment, the XSLT processor has access to the type information associated with individual nodes, not merely to the raw text.

Ed. Note:

The XSL Working Group intends to define a conformance level for XSLT processors in which schema processing, and handling of user-defined types, is not a requirement. The precise rules for such a processor (for example, the question of whether it should ignore type-related constructs in the stylesheet or should signal them as an error) have yet to be defined.

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 xs:string or xs: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 3.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 in source documents. It is possible to make assertions about the types of input document by means of tests within the stylesheet. For example:

<xsl:template match="/">
<xsl:if test="not(* instance of my:invoice)">
  <xsl:message terminate="yes">Source document is not an invoice</xsl:message>
</xsl:if>
. . .
</xsl:template>

A stylesheet can also control 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.

Type annotations can be created in nodes of a result tree, or of a temporary tree, in a number of ways. Firstly, it is possible to request validation of the complete tree. Validation may be either strict or lax, and is performed according to the rules defined in [XML Schema]: if validation fails, the transformation fails, but if it succeeds, the element and attribute nodes of the tree will be annotated with the names of the schema-defined types to which these nodes conform, and the typed value of the nodes will be accessible using the fn:data function. Secondly, it is possible to add annotations to individual element and attribute nodes as they are constructed. This is done using the type-annotation attribute of the xsl:element and xsl:attribute instructions, or the xsl:type-annotation attribute of a literal result element. This is permitted only for elements that have simple content. In addition, type annotations may be copied from a source tree to a result tree when using the xsl:copy-of instruction. Type annotations attached to individual nodes in this way will only be retained in the completed tree if the tree construction element (for example, xsl:variable or xsl:result-document) specifies type-information="preserve".

2.9 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 3.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 9.8 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.

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

<xsl:if test="fn: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 finish as if the transformation were successful.

When a transformation signals one or more dynamic errors, the final state of any persistent resources updated by the transformation is implementation-dependent. Implementations are not required to restore such resources to their initial state. In particular, where a transformation produces multiple result documents, it is possible that one or more result documents may be written successfully before the transformation terminates, but the application cannot rely on this behavior.

Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.

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

3.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 3.4 Stylesheet Element and 3.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 18.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.

Note:

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

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

[ERR007] It is a static error for an element from the XSLT namespace to have an attribute whose namespace is either null (i.e. an attribute with an unprefixed name) or the XSLT namespace, 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. Names of types defined in XML Schema however, are regarded as single words and are capitalized exactly as in XML Schema. This sometimes leads to composite function names such as fn:current-dateTime.

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

• The XSLT namespace, described in this section, is reserved.

• The standard function namespace http://www.w3.org/2002/08/xquery-functions is used for functions in the core function library, defined in [Functions and Operators]

  Issue 155 (fn-namespace): We need to review how function namespaces are handled in XSLT. Should users be able to declare the default namespace for functions? Should user-defined functions be allowed to be in no namespace? What namespace should be used for functions such as generate-id defined in this specification?

• The standard operator namespace http://www.w3.org/2002/08/xquery-operators is used for functions that underpin XPath operators, defined in [Functions and Operators]

• The XML namespace, defined in [XML Names] as http://www.w3.org/XML/1998/namespace, is used for attributes such as xml:lang and xml:space

• The schema namespace http://www.w3.org/2001/XMLSchema is used as defined in [XML Schema] . In a stylesheet this namespace may be used to refer to built-in schema datatypes and to the constructor functions associated with those datatypes.

• The schema datatypes namespace http://www.w3.org/2001/XMLSchema-datatypes is used as defined in [XML Schema] . In a stylesheet this namespace may be used to refer to built-in schema datatypes and to the constructor functions associated with those datatypes: in these respects it is equivalent to the schema namespace

• The schema instance namespace http://www.w3.org/2001/XMLSchema-instance is used as defined in [XML Schema] . Attributes in this namespace, if they appear in a stylesheet, are treated by the XSLT processor in the same way as any other attributes.

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

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

Implementations may reserve additional namespaces for use by the implementation, provided they follow accepted practice to avoid naming collisions. The set of such namespaces is implementation-defined.

Future versions of this specification may reserve additional namespaces starting with http://www.w3.org/.

3.2 XSLT Media Type

3.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 may be given as a whitespace-separated list of namespace prefixes, and the effective value for an element is the combined set of namespace URIs designated by the prefixes that appear in this attribute for that element and any of its ancestor elements. Again, the two forms with and without the XSLT namespace are equivalent.

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:

• [xsl:]version: see 3.6 Backwards-Compatible Processing and 3.7 Forwards-Compatible Processing

• [xsl:]default-xpath-namespace: see 5.4 Unprefixed Names in Expressions and Patterns.

• [xsl:]exclude-result-prefixes : see 11.1.3 Namespace Nodes for Literal Result Elements.

• [xsl:]extension-element-prefixes: see 18.2 Extension Instructions.

Ed. Note:

The XSL Working Group has decided in principle to impose restrictions in the ability to mix different version attributes on different elements in a stylesheet. The form of these restrictions has yet to be decided.

3.4 Stylesheet Element

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

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  default-xpath-namespace = uri>
  <!-- Content: (xsl:import*, other-declarations) -->
</xsl:transform>

A stylesheet module is represented by an xsl:stylesheet element in an XML document. xsl:transform is allowed as a synonym for xsl:stylesheet; everything this specification says about the xsl:stylesheet element applies equally to xsl:transform.

[ERR009] An xsl:stylesheet element must have a version attribute, indicating the version of XSLT that the stylesheet requires. [ERR010] 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 3.6 Backwards-Compatible Processing). When the value is greater than 2.0, forwards-compatible behavior is enabled (see 3.7 Forwards-Compatible Processing).

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

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

• xsl:import

• xsl:include

• xsl:attribute-set

• xsl:decimal-format

• xsl:function

• xsl:import-schema

• xsl:key

• xsl:namespace-alias

• xsl:output

• xsl:param

• xsl:preserve-space

• xsl:sort-key

• xsl:strip-space

• xsl:template

• xsl:variable

If there are xsl:import elements, these must come before any other elements. Apart from this, the child elements of the xsl:stylesheet element may appear in any order. The ordering of these elements does not affect the results of the transformation unless there are conflicting declarations (for example, two template rules with the same priority that match the same node). In general, it is an error for a stylesheet to contain such conflicting declarations, but in some cases the processor is allowed to recover from the error by choosing the declaration that appears last in the stylesheet.

3.5 Simplified Stylesheet Modules

A simplified syntax is allowed for a stylesheet module that defines only a single template rule for the document node. The stylesheet module may consist of just a literal result element (see 11.1 Literal Result Elements) together with its contents. 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 /.

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

<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, invoking the transformation by calling the named template expand, with the containing literal result element as the context node:

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

<xsl:template name="expand">
  <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>

[ERR014] 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 3.6 Backwards-Compatible Processing). When the xsl:version attribute is numerically greater than 2.0, forwards-compatible behavior is enabled (see 3.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.

3.6 Backwards-Compatible Processing

An element enables backwards-compatible behavior for itself, its attributes, its descendants and their attributes if it has an [xsl:]version attribute (see 3.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 constrained to use syntax permitted by XPath 1.0

• It is guaranteed to return the same result as would be returned by XPath 1.0, after conversion of any variables that it references to the equivalent XPath 1.0 data type. This conversion is done as follows. Any numeric value is converted to the nearest XPath 1.0 number. Boolean values remain as booleans; any other atomic value is converted to a string. [ERR015] If the value 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. The processor must signal the error. The result of the expression is converted to an XPath 2.0 value by representing any node-set as a sequence of nodes in document order.

It is implementation-defined whether a particular XSLT 2.0 implementation supports backwards-compatible behavior. [ERR016] 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.

Note:

To write a stylesheet that works with both XSLT 1.0 and 2.0 processors, while making selective use of XSLT 2.0 facilities, it is necessary to understand both the rules for backwards-compatible behavior in XSLT 2.0, and the rules for forwards-compatible behavior in XSLT 1.0. If the xsl:stylesheet element specifies version="2.0", then an XSLT 1.0 processor will ignore XSLT 2.0 declarations that were not defined in XSLT 1.0, for example xsl:function and xsl:sort-key. If any new XSLT 2.0 instructions are used (for example xsl:analyze-string or xsl:namespace), or if new XPath 2.0 features are used (for example, new functions, or syntax such as conditional expressions, or calls to a function defined using xsl:function), then the stylesheet must provide fallback behavior that relies on XSLT 1.0 and XPath 1.0 facilities only. The fallback behavior can be invoked by using the xsl:fallback instruction, or by testing the results of the function-available or element-available functions, or by testing the value of the xsl:version property returned by the system-property function.

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

• if it is a declaration element and XSLT 2.0 does not allow such elements as declarations, then the element must be ignored along with its content;

• if it is an element in a content constructor and XSLT 2.0 does not allow such elements to occur in content constructors, then if the element is not evaluated, no error must be signaled, and if the element is evaluated, the processor must perform fallback for the element as specified in 18.2.3 Fallback;

• if the element has an attribute that XSLT 2.0 does not allow the element to have or if the element has an optional attribute with a value that XSLT 2.0 does not allow the attribute to have, then the attribute must be ignored.

• if an attribute of the element contains an XPath expression that does not match the allowed syntax of an XPath 2.0 expression, or one that calls a function whose name is in the standard function namespace (see [Functions and Operators]) but that is not defined in XPath 2.0 or XSLT 2.0, or that calls such a function with the wrong number or type of arguments, the error must not be signaled unless the expression is actually evaluated.

<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 17 Messages) to ensure that implementations that conform to an earlier version of XSLT will not silently ignore the declaration.

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

3.8 Combining Stylesheet Modules

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

• an inclusion mechanism that allows stylesheet modules to be combined without changing the semantics of the modules being combined, and

• an import mechanism that allows stylesheet modules to override each other.