The presentation of this document has been augmented to identify changes from a previous version. Three kinds of changes are highlighted: new, added text, changed text, and deleted text.


W3C

XSL Transformations (XSLT) Version 2.0

W3C Working Draft 2 May 2003

This version:
http://www.w3.org/TR/2003/WD-xslt20-20030502/
Latest version:
http://www.w3.org/TR/xslt20/
Previous versions:
http://www.w3.org/TR/2002/WD-xslt20-20021115/
http://www.w3.org/TR/2002/WD-xslt20-20020816/
http://www.w3.org/TR/2002/WD-xslt20-20020430/
http://www.w3.org/TR/2001/WD-xslt20-20011220/
Editor:
Michael Kay, Software AG <Michael.Kay@softwareag.com>

This document is also available in these non-normative formats: HTML without revision markings and HTML with revision markings.


Abstract

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

XSLT 2.0 is designed to be used in conjunction with XPath 2.0, which is defined in [XPath 2.0]. XSLT shares the same data model as XPath 2.0, which is defined in [Data Model], and it uses the library of functions and operators defined in [Functions and Operators].

XSLT 2.0 also includes optional facilities to serialize the results of a transformation, by means of an interface to the serialization component described in [XSLT and XQuery Serialization].

Status of this Document

This document is a 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. The document is published in two versions: one that highlights changes since the previous published Working Draft, and one without change highlighting.

With this draft, there are no outstanding open issues. All mandatory requirements, and most of the requirements in the "should" and "could" categories, have been satisfied. The Working Group therefore considers it unlikely that future drafts will introduce major changes to the functionality of the language. However, there will still be some tidying up to improve syntactic and semantic consistency, and the Working Group will address any significant concerns that arise from public comments. At this stage, comments on the detail are particularly welcome, whereas comments that question the overall requirements are less likely to be productive.

The amount of change since the November 2002 draft is substantial. A detailed summary of the changes is included at K.2.4 Changes since the November 2002 draft. The most significant changes are:

The specifications for XSLT serialization have been moved to a separate Working Draft, [XSLT and XQuery Serialization], to make it easier for other W3C specifications such as XQuery to reference them.

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 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 2.0 described in [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].

Comments on this specification may be sent to public-qt-comments@w3.org; archives of the comments are available. 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/.

The development of XSLT is undertaken by the XSL Working Group which is now part of the W3C XML Activity.

Patent disclosures relevant to this specification may be found on the XSL Working Group's patent disclosure page at http://www.w3.org/Style/XSL/Disclosures.html.

Table of Contents

1 Introduction
    1.1 What is XSLT?
    1.2 What's new in XSLT 2.0?
2 Concepts
    2.1 Terminology
    2.2 Notation
    2.3 Initiating a Transformation
    2.4 Executing a Transformation
        2.4.1 Push Processing Instructions
        2.4.2 Pull Processing Instructions
        2.4.3 Constructing Sequences
        2.4.4 Constructing Result Trees
    2.5 Maintaining Position: the Focus
    2.6 Parsing and Serialization
    2.7 Extensibility
    2.8 Stylesheets and Schemas
    2.9 Error Handling
3 Stylesheet Structure
    3.1 XSLT Namespace
    3.2 XSLT Media Type
    3.3 Standard Attributes
    3.4 Stylesheet Element
        3.4.1 User-defined Data Elements
    3.5 Simplified Stylesheet Modules
    3.6 Backwards-Compatible Processing
    3.7 Forwards-Compatible Processing
    3.8 Combining Stylesheet Modules
        3.8.1 Stylesheet Inclusion
        3.8.2 Stylesheet Import
    3.9 Embedded Stylesheet Modules
    3.10 Importing Schema Components
4 Data Model
    4.1 Whitespace Stripping
    4.2 Disable Output Escaping
5 Syntactic Constructs
    5.1 Qualified Names
    5.2 Expressions
    5.3 Patterns
    5.4 Unprefixed Names in Expressions and Patterns
    5.5 Attribute Value Templates
    5.6 Sequence Constructors
        5.6.1 Constructing Complex Content
        5.6.2 Constructing Simple Content
        5.6.3 Namespace Fixup
6 Template Rules
    6.1 Defining Templates
    6.2 Defining Template Rules
    6.3 Applying Template Rules
    6.4 Conflict Resolution for Template Rules
    6.5 Modes
    6.6 Built-in Template Rules
    6.7 Overriding Template Rules
7 Repetition
8 Conditional Processing
    8.1 Conditional Processing with xsl:if
    8.2 Conditional Processing with xsl:choose
9 Variables and Parameters
    9.1 Variables
    9.2 Parameters
    9.3 Values of Variables and Parameters
    9.4 Temporary Trees
    9.5 Global Variables and Parameters
    9.6 Local Variables and Parameters
    9.7 Scope of Variables
    9.8 Circular Definitions
10 Callable Components
    10.1 Named Templates
        10.1.1 Passing Parameters to Templates
    10.2 Named Attribute Sets
    10.3 Stylesheet Functions
        10.3.1 Defining a Stylesheet Function
11 Creating Nodes and Sequences
    11.1 Literal Result Elements
        11.1.1 Setting the Type Annotation for Literal Result Elements
        11.1.2 Attribute Nodes for Literal Result Elements
        11.1.3 Namespace Nodes for Literal Result Elements
        11.1.4 Namespace Aliasing
    11.2 Creating Element Nodes using xsl:element
        11.2.1 Setting the Type Annotation for a Constructed Element Node
    11.3 Creating Attribute Nodes using xsl:attribute
        11.3.1 Setting the Type Annotation for a Constructed Attribute Node
    11.4 Creating Text Nodes
        11.4.1 Literal Text Nodes
        11.4.2 Creating Text Nodes using xsl:text
        11.4.3 Generating Text with xsl:value-of
    11.5 Creating Processing Instructions
    11.6 Creating Namespace Nodes
    11.7 Creating Comments
    11.8 Copying Nodes from a Source Tree to a Result Tree
        11.8.1 Shallow Copy
        11.8.2 Deep Copy
    11.9 Constructing Sequences
12 Numbering
    12.1 Formatting a Supplied Number
    12.2 Numbering based on Position in a Document
    12.3 Number to String Conversion Attributes
13 Sorting
    13.1 Collating Sequences
    13.2 The xsl:sort Element
    13.3 Using Unnamed Sort Specifications
    13.4 Using Named Sort Specifications
        13.4.1 Declaring a Named Sort Specification
        13.4.2 Sorting Using a Named Sort Specification
14 Grouping
    14.1 The Current Group
    14.2 The Current Grouping Key
    14.3 The xsl:for-each-group Element
    14.4 Examples of Grouping
15 Regular Expressions
    15.1 Examples of Regular Expression Matching
16 Additional Functions
    16.1 Multiple Source Documents
    16.2 Reading Text Files
    16.3 Keys
        16.3.1 The xsl:key Declaration
        16.3.2 The key Function
    16.4 Number Formatting
        16.4.1 Defining a Decimal Format
        16.4.2 Processing the Picture String
        16.4.3 Analysing the Picture String
        16.4.4 Formatting the Number
    16.5 Formatting Dates and Times
        16.5.1 The date-format declaration
        16.5.2 The Picture String
    16.6 Miscellaneous Additional Functions
        16.6.1 current
        16.6.2 unparsed-entity-uri
        16.6.3 unparsed-entity-public-id
        16.6.4 generate-id
        16.6.5 system-property
17 Messages
18 Extensibility and Fallback
    18.1 Extension Functions
        18.1.1 Testing Availability of Functions
        18.1.2 Calling Extension Functions
        18.1.3 External Objects
    18.2 Extension Instructions
        18.2.1 Designating an Extension Namespace
        18.2.2 Testing Availability of Instructions
        18.2.3 Fallback
19 Result Trees
    19.1 Creating Result Trees
    19.2 Validation
        19.2.1 Validating Constructed Nodes
        19.2.2 Validating Result Trees
20 Serialization
    20.1 Character Maps
    20.2 Disabling Output Escaping
21 Conformance
    21.1 Basic XSLT Processor
    21.2 Schema-Aware XSLT Processor
    21.3 Serialization Feature
    21.4 Backwards Compatibility Feature

Appendices

A References
    A.1 Normative References
    A.2 Other References
B Glossary (Non-Normative)
C Element Syntax Summary (Non-Normative)
D Summary of Error Conditions (Non-Normative)
E Checklist of Implementation-Defined Features (Non-Normative)
F Schema for XSLT Stylesheets (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 Backwards Compatibility Behavior
        K.1.2 Incompatibility in the Absence of a Schema
        K.1.3 Compatibility in the Presence of a Schema
        K.1.4 XPath 2.0 Backwards Compatibility
    K.2 Changes since XSLT 1.0
        K.2.1 Pervasive changes
        K.2.2 Major Features
        K.2.3 Minor Changes
        K.2.4 Changes since the November 2002 draft


1 Introduction

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 1.0] conforming to the Namespaces in XML Recommendation [XML Namespaces 1.0]. 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 sequence 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 Concepts

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 document, doc or 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]. Where the word must relates to the behavior of the XSLT processor, then an implementation is not conformant unless it behaves as specified, subject to the more detailed rules in 21 Conformance. Where the word must relates to a stylesheet, then the processor must enforce this constraint on stylesheets.

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 labeled as Notes or described as examples are non-normative.

Many terms used in this document are defined in the XPath specification [XPath 2.0] or the Data Model specification [Data Model]. Particular attention is drawn to the following:

  • The term atomization is defined in [XPath 2.0]. It is a process that takes as input a sequence of nodes and atomic values, and returns a sequence of atomic values, in which the nodes are replaced by their typed values as defined in [Data Model]. For some nodes (for example, elements with element content), atomization generates a dynamic error.

  • The term string value is defined in [Data Model]. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.

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.

    In all cases where this specification limits the set of values that an attribute may take, leading and trailing whitespace in the attribute value is ignored. In the case of an attribute value template, this applies to the effective value obtained when the attribute value template is expanded.

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

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

 

The following example illustrates the notation.

<!-- Category: instruction -->
<xsl:example-element
  select = sequence-expression
  debug = { "yes" | "no" }>
  <!-- Content: ((xsl:variable | xsl:param)*, xsl:sequence) -->
</xsl:example-element>

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

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

 

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

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

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.

Note:

This working draft includes a non-normative 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 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, then the context item, context position, and context size will initially be unset, and the evaluation of any expression that references these values will result in a dynamic error. 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.4 Conflict Resolution for Template Rules. Either a named template, or an initial context node, or both, must be supplied.

  • Optionally, an initial mode. If an initial mode is supplied, then in searching for the template rule that best matches the initial context node, the processor considers only those rules that apply to the initial mode. If no initial mode is supplied, the default mode is used.

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

The transformation is performed by evaluating an initial template; if a named template is supplied when the transformation is initiated, then this is the initial template; otherwise, the initial template is the template rule selected for processing the initial context node in the initial mode, selected according to the rules used by the xsl:apply-templates instruction. If the result of evaluating the initial template is a non-empty sequence, then this sequence is used to construct an implicit result tree, following the rules described in 5.6.1 Constructing Complex Content: the effect is as if the sequence constructor contained in the initial template were contained in an xsl:result-document element with no attributes.

Parameters passed to the transformation by the client application are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the initial template. All template parameters within the initial template to be executed will take their default values. [ERR005] It is a dynamic error if the initial template defines a 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 document, doc or 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.

2.4.1 Push Processing Instructions

A stylesheet generally contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in a source tree and a sequence constructor which is evaluated to produce a sequence of items. In most cases these items are nodes, which are then written to a result tree.

A template rule that is selected to process a particular node in the source tree will commonly write one or more nodes to the result tree, and will frequently use the xsl:apply-templates instruction to select other nodes in the source tree (often, but not invariably, the original node's children) for processing. Each of these selected nodes is processed by searching the stylesheet for a matching template rule. Sometimes all the selected nodes will be processed by the same template rule, but in general different nodes will be processed by different template rules. Either way, the chosen template rules are evaluated and the process repeats itself, typically resulting in a recursive traversal of the source tree.

Because the template rule that is written to process one node in the tree has no knowledge of which rules will be chosen to process the nodes that it selects, push processing allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.

Frequently, the first action of the stylesheet is to find the template rule that matches the document node of a source tree. This initial template may create the document node of a new result tree explicitly by using the xsl:result-document instruction; if it does not do so, the system implicitly creates the document node of a new result tree. The sequence constructor of this template rule then creates the children of the new document node. By the time evaluation of this sequence constructor is complete, these children will typically each act as the parent of further result nodes, so a complete tree is constructed.

In the process of finding a template rule to process a particular node, more than one template rule may have a pattern that matches the node. However, only one template rule will be applied. The method for deciding which template rule to apply is described in 6.4 Conflict Resolution for Template Rules. If there is no template rule that matches the node, a built-in template rule is used (see 6.6 Built-in Template Rules).

 

For example, suppose the source tree contains the structure below:

<doc>
  <val>1</val>
  <val>2</val>
  <val>3</val>
</doc>

If the context node is the doc element, and the xsl:apply-templates instruction is evaluated with the attribute select="*", then the input sequence will contain the three val elements. Suppose the template rule that matches a val element has the following form:

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

This template rule will be evaluated once for each val element in the input sequence, and in each case it will return a new li element, which in turn will contain a single text node. The result of the xsl:apply-templates instruction will therefore be a sequence of three li elements. The following XML fragment will be generated:

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

This fragment will be added to the result tree at the point where the doc element was being processed.

 

Very often, the template rule that matches one element in the source tree will contain an xsl:apply-templates instruction selecting the children of that element as the input sequence for processing. In this situation, each child node will be processed to create a subtree, and these subtrees will be added as children of the element produced by the parent template rule. The structure of the result tree will then correspond directly to the structure of the source tree.

 

For example, suppose that the doc element in the previous example is processed using the template rule below:

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

Then the result of processing the doc element will be the following result tree:

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

2.4.2 Pull Processing Instructions

A single template rule 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.

A stylesheet that uses the pull processing technique is written to navigate explicitly around the source tree, accessing data from wherever it appears in order to construct nodes in the result tree. A number of XSLT instructions are provided to assist pull processing: notably xsl:for-each, xsl:choose, xsl:if, and xsl:call-template.

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 sequence 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 3.5 Simplified Stylesheet Modules).

2.4.3 Constructing Sequences

Whether the stylesheet is written to use push processing or pull processing, nodes in the result tree are always generated using sequence constructors. Each level of the tree is constructed in a two-stage process. First, a sequence constructor is evaluated to produce a sequence of items. Second, this sequence of items is used to form the children (and attributes and namespaces) of a new element or document node.

A sequence constructor is a sequence of instructions, which appear as sibling nodes in the stylesheet, and which are evaluated to create a sequence of items.

A sequence constructor can contain elements (called literal result elements) and text nodes that are copied directly into the result sequence. A sequence constructor can also contain elements from the XSLT namespace that are instructions for creating parts of the result sequence.

The sequence produced by evaluating a sequence constructor is most commonly used to form the child nodes (and attributes and namespaces) of a new element or document node, as described in 2.4.4 Constructing Result Trees. But it is also possible to manipulate the value returned by a sequence constructor directly. This is generally done by binding a variable to the value, as described in 9.1 Variables. It is possible for such a sequence to contain elements, attributes, or other nodes that have no parent.

An instruction is defined as an element that can appear in a sequence constructor and that is either in the XSLT namespace, or in a namespace designated as an extension namespace.

Instructions that select nodes from a 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 3.6 Backwards-Compatible Processing and 3.7 Forwards-Compatible Processing).

2.4.4 Constructing Result Trees

The result of evaluating a sequence constructor is an arbitrary sequence of items, which may include both nodes and atomic values. When a sequence constructor appears as the content of an instruction that creates an element or document node, then the sequence of items created by the sequence constructor is used to form the children, attributes and namespaces of the new element or document node. During this process, any sequence of consecutive atomic values is first converted to a text node by casting each atomic value to a string, and inserting a single space between successive strings to form the string value of the text node. Any adjacent text nodes in the sequence are then merged.

Technically, each node appearing in the value returned by a sequence constructor is copied, together with all its children, attributes, and namespaces, when it is attached to a parent element or document node. In practice, it is only necessary to make a physical copy when the original node is accessible independently of its new parent, for example when it is part of a sequence that has been bound to a variable.

The order of the child nodes in the result tree corresponds to their order in the sequence, which itself depends on the stylesheet order of the instructions that created them. In the case of attribute or namespace nodes, the new nodes become attributes or namespaces of the element under construction.

The process of constructing a result tree is described in more detail in 5.6.1 Constructing Complex Content.

2.5 Maintaining Position: the Focus

When a sequence 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 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 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.6.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. The focus is also undefined on initial entry to the stylesheet if no initial context node supplied. [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:

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 1.0], 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 must 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 sequence 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.

Information from a schema can be used both statically (when the stylesheet is compiled), and dynamically (during evaluation of the stylesheet to transform a source document).

The conformance rules for XSLT 2.0, defined in 21 Conformance, distinguish between a basic XSLT processor and a schema-aware XSLT processor. As the names suggest, a basic XSLT processor does not support the features of XSLT that require access to schema information, either statically or dynamically. A stylesheet that works with a basic XSLT processor will usually work unchanged with a schema-aware XSLT processor; however, the fact that a source document has been processed using a schema processor and has been annotated with type information affects the outcome of certain operations such as sorting.

The remainder of this section describes facilities that are available only with a schema-aware XSLT processor.

There are places within a stylesheet, and within XPath expressions and patterns in a stylesheet, where the names of schema-defined elements, attributes, and named types 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="document-node(element(my:invoice))" priority="2">
. . .
</xsl:template>

<xsl:template match="document-node()" priority="1">
  <xsl:message terminate="yes">Source document is not an invoice</xsl:message>
</xsl:template>

This example will cause the transformation to fail with an error message if the source document has not been successfully validated and annotated with type my:invoice.

 

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

  • It is possible to request explicit validation of a complete result tree. Validation is either strict or lax, and is performed according to the rules defined in [XML Schema]. If validation of a result tree fails (strictly speaking, if the outcome of the validity assessment is invalid), then 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. These annotations will be discarded if the result tree is serialized as an XML document, but they remain available when the result tree is passed to an application (perhaps another stylesheet) for further processing.

  • It is also possible to validate individual element and attribute nodes as they are constructed. This is done using the type and validation attributes of the xsl:element, xsl:attribute, xsl:copy, and xsl:copy-of instructions, or the xsl:type and xsl:validation attributes of a literal result element.

  • When elements or attributes are copied, either explicitly using the xsl:copy or xsl:copy-of, or implicitly when nodes in a sequence are attached to a new parent node, the options validation="strip" and validation="preserve" are available, to control whether existing type annotations are to be retained or not.

For details of how validation of element and attribute nodes works, see 19.2 Validation.

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. A static error must be signaled even if it occurs in a part of the stylesheet that is never evaluated. Static errors are never recoverable. After signaling a static error, a processor may continue for the purpose of signaling additional errors, but it must eventually terminate abnormally without producing any result tree.

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. Some dynamic errors are classed as recoverable errors. When a recoverable error occurs, this specification allows the processor either to signal the error (by reporting the error condition and terminating execution) or to take a defined recovery action and continue processing. It is implementation-defined whether the error is signaled or the recovery action is taken. If the 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 signal any dynamic errors that would arise if the construct were evaluated.

An implementation may signal a dynamic error before any source document is available, but only if it can determine that the error would be signaled for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see 9.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 signaled as a dynamic error. An implementation may also, optionally, signal 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 signaled statically.

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 signal this as a static error, even though the offending instruction will never be evaluated, and the type error would therefore never be signaled as a dynamic error.

<xsl:if test="false()">
  <xsl: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 Stylesheet Structure

A stylesheet consists of one or more stylesheet modules, each one forming all or part of a well-formed XML document.

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

Both forms of stylesheet module (standard and simplified) can exist either as an entire XML document, or embedded as part of another XML document, typically a source document that is to be processed using the stylesheet. An embedded stylesheet module is a stylesheet module that is embedded within another XML document, typically the source document that is being transformed. (see 3.9 Embedded Stylesheet Modules).

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

 

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

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

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

 

[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 current-dateTime.

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

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

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

  • 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 Namespaces 1.0] 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 XPath datatypes namespace http://www.w3.org/2003/05/xpath-datatypes is used as defined in [Functions and Operators] . In a stylesheet this namespace may be used to refer to the types xdt:untypedAtomic, xdt:yearMonthDuration, xdt:dayTimeDuration, xdt:anyAtomicType, and to the constructor functions associated with the first three of these types.

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

Note:

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

[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 date-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.

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

A media type will be registered for XSLT stylesheet modules.

Note:

It is expected that this media type will be application/xslt+xml as forecast in section 8.17 of [RFC3023].

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

3.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 xpath-default-namespace.

These attributes may also appear on a literal result element, but in this case, to distinguish them from user-defined attributes, the names of the attributes are in the XSLT namespace. They are thus typically written as xsl:version, xsl:exclude-result-prefixes, xsl:extension-element-prefixes, or xsl:xpath-default-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:]xpath-default-namespace the value can be overridden by a different value for the same attribute appearing on a descendant element. The effective value of the attribute for a particular stylesheet element is determined by the innermost containing element on which the attribute appears. Note however that the version attribute on the xsl:output element serves an entirely different purpose.

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

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:

3.4 Stylesheet Element

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

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  xpath-default-namespace = uri
  default-validation = "strict" | "lax" | "preserve" | "strip">
  <!-- 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. A value of 1.0 indicates that the stylesheet was written with the intention that it should be processed using an XSLT 1.0 processor. [ERR011] It is a static error to submit to an XSLT 2.0 processor a stylesheet that specifies version="1.0" in the xsl:stylesheet element of the principal stylesheet module, or in the xsl:version attribute of the outermost element in the case of a simplified stylesheet module. This is a recoverable error. The processor may signal the error, or may recover by processing the stylesheet with backwards-compatible processing behavior enabled (see 3.6 Backwards-Compatible Processing).

When the value of the version attribute is greater than 2.0, forwards-compatible behavior is enabled (see 3.7 Forwards-Compatible Processing).

Note:

XSLT 1.0 allowed the [xsl:]version attribute to take any numeric value, and specified that if the value was not equal to 1.0, the stylesheet would be executed in forwards compatible mode. XSLT 2.0 continues to allow the attribute to take any unsigned decimal value. A software product that includes both an XSLT 1.0 processor and an XSLT 2.0 processor (or that can execute as either) may use the [xsl:]version attribute to decide which processor to invoke; such behavior is outside the scope of this specification. When the stylesheet is executed with an XSLT 2.0 processor, the value 1.0 is taken to indicate that the stylesheet was written with XSLT 1.0 in mind: if this value appears on the outermost element of the principal stylesheet module then an XSLT 2.0 processor must either reject the stylesheet or execute it in backwards compatible mode, as described above. Setting version="2.0" indicates that the stylesheet is to be executed with neither backwards nor forwards compatible behavior enabled. Any other value less than 2.0 enables backwards compatible behavior, while any value greater than 2.0 enables forwards compatible behavior.

When developing a stylesheet that is designed to execute under either XSLT 1.0 or XSLT 2.0, the recommended practice is to create two separate entry modules, one specifying version="1.0", and the other specifying version="2.0"; these entry modules can use xsl:include or xsl:import to incorporate the common code. Subsidiary stylesheet modules should specify version="2.0" if they make use of XSLT 2.0 facilities, and version="1.0" otherwise.

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

[ERR012] 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:

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.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. [ERR013] 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,

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

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

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

[ERR015] 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 sequence 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.

These rules do not apply to the version attribute of the xsl:output element, which has an entirely different purpose.

If an attribute containing an XPath expression is processed with backwards-compatible behavior, then the expression is evaluated with the XPath 1.0 backwards compatibility flag set to true.

Certain XSLT constructs also produce different results when backwards-compatible behavior is enabled. This is described separately for each such construct.

Note:

The result of processing a stylesheet using backwards compatible behavior is likely in most cases to be identical or very similar to the effects of processing the same stylesheet using an XSLT 1.0 processor. The differences are described (non-normatively) in K.1 Incompatible Changes. To assist with transition, some parts of an stylesheet may be processed with backwards compatible behavior enabled, and other parts with this behavior disabled. All data values manipulated by an XSLT 2.0 processor are defined by the XPath 2.0 data model, whether or not the relevant expressions use backwards compatible behavior. Because the same data model is used in both cases, expressions are fully composable. The result of evaluating instructions or expressions with backwards compatible behavior is fully defined in the XSLT 2.0 and XPath 2.0 specifications, it is not defined by reference to the XSLT 1.0 and XPath 1.0 specifications.

  • 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. [ERR016] 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. [ERR017] 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.

These rules do not apply to the version attribute of the xsl:output element, which has an entirely different purpose.

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 signaled 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 sequence constructor and XSLT 2.0 does not allow such elements to occur in sequence 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.

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

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.

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

The included stylesheet module must be either a standard stylesheet module or a a simplified stylesheet module. It may be a complete XML document, or (if referenced using a suitable fragment identifier) it may be an embedded stylesheet module .

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

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

Note:

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

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

The imported stylesheet module must be either a standard stylesheet module or a simplified stylesheet module. It may be a complete XML document, or (if referenced using a suitable fragment identifier) it may be an embedded stylesheet module.

[ERR020] The xsl:import declaration is allowed only as a top-level element. [ERR021] 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 import tree has the following structure:

         A
         |
     +---+---+
     |       |
     B       C
     |       |
     D       E

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.

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

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

  • the XSLT stylesheet may be textually embedded in a non-XML resource, or

  • the xsl:stylesheet element may occur in an XML document other than as the document element.

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 or schema 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="application/xslt+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 typically needs to contain a template rule that specifies that xsl:stylesheet elements are to be ignored.

Note:

The above example uses the pseudo-attribute type="application/xslt+xml" in the xml-stylesheet processing instruction to denote an XSLT stylesheet. This usage was defined provisionally in XSLT 1.0, and is subject to change: see 3.2 XSLT Media Type. 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.

3.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, the names of type definitions and element and attribute declarations) which need to be available statically, that is, before any source document is available. Every such name used statically within the stylesheet other than the built-in type names defined in XML Schema and the four built-in types defined in XPath 2.0 (xdt:dayTimeDuration, xdt:yearMonthDuration, xdt:anyAtomicType, xdt:untypedAtomic) must be defined in an imported schema.

The xsl:import-schema declaration imports the top-level element and attribute declarations and type definitions from the schema, and makes them available for use within XPath expressions in the stylesheet, and within other stylesheet contexts such as the type and as attributes of various XSLT elements.

The same schema definitions are available in all stylesheet modules; importing the definitions in one stylesheet module makes them available throughout the stylesheet.

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

If two xsl:import-schema declarations specify the same namespace, or if both specify no namespace, then only the one with highest import precedence is used. [ERR023] It is a static error if two xsl:import-schema declarations for the same namespace have the same import precedence, unless there is another xsl:import-schema declaration for this namespace that has higher import precedence.

After discarding any xsl:import-schema declarations under the above rule, the effect of the remaining xsl:import-schema declarations is the same as the effect of importing a single hypothetical schema that consists entirely of xs:import elements corresponding one-for-one with the xsl:import-schema declarations in the stylesheet, with the following correspondence:

  • The order of xs:import elements is in increasing order of the import precedence of the corresponding xsl:import-schema declarations, and in declaration order where two declarations have the same import precedence.

  • The namespace attribute of the xs:import element is copied from the namespace attribute of the xsl:import-schema declaration if present, and is absent if it is absent.

  • The schemaLocation attribute of the xs:import element is copied from the schema-location attribute of the xsl:import-schema declaration if present, and is absent if it is absent.

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

Conflicts (multiple definitions of the same name) are handled as defined in [XML Schema], assuming that all the imported definitions are assembled into one schema using the process described above.

Note:

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

The schema-location attribute gives the URI of a location where a schema document or other resource containing the required definitions may be found. A schema-aware 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.

Any xs:import (or xs:include and xs:redefine elements in an imported schema are processed recursively.

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

[ERR025] It is a static error if both the namespace and the schema-location attributes are specified, and the schema that is located is not a schema for the specified namespace.

[ERR026] It is a static error if the schema-location attribute is omitted, and the namespace attribute identifies a namespace whose schema is not known to the XSLT processor.

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

Additional types may be imported into a stylesheet using implementation-defined mechanisms. For example, the mechanisms used to define extension functions (see 18.1 Extension Functions) may also be used to import the types used in the interface to such functions.

4 Data Model

The data model used by XSLT is the XPath 2.0 and XQuery 1.0 data model, 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.

Some of the sections below describe restrictions to the data model: that is, features of the data model that are never used by XSLT. Some sections describe additions to the data model: that is, information that is required to support XSLT processing, but that is not described in the data model. Other sections describe refinements to the data model, that is, additional rules about the way in which trees in the data model are constructed. Each section is therefore marked as a restriction, and addition, or a refinement.

Note:

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.

Ed. Note:We need to say something here about schemas and DTDs. See http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Jan/0113.html (members only) and subsequent discussion.

4.1 Whitespace Stripping

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:

  • The element name of the parent of the text node is in the set of whitespace-preserving element names.

  • The text node contains at least one non-whitespace character. As in XML, a whitespace character is #x20, #x9, #xD or #xA.

  • An ancestor element of the text node has an xml:space attribute with a value of preserve, and no closer ancestor element has xml:space with a value of default.

Otherwise, the 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 signaled as an error. [ERR027] 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:

[ERR028] It is a dynamic error if this leaves more than one match. This is a recoverable error. 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.

4.2 Disable Output Escaping

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

Conceptually, each character in a text node on such a result tree, and each attribute node, 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 or attribute node.

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

Note:

In practice, the nodes in a final result tree will often be streamed directly from the XSLT processor to the serializer. In such an implementation, disable-output-escaping is not so much a property stored with nodes in the tree, but an out-of-band signal passed across the interface between the XSLT processor and the serializer.

4.3 Parentless Nodes

Restriction

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

5 Syntactic Constructs

5.1 Qualified Names

The name of a stylesheet-defined object, specifically a named template, a mode, an attribute set, a key, a named sort specification, a decimal-format, a date-format, a variable or parameter, a stylesheet function, a named output definition, or a character map is specified as a QName.

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

An expanded-QName is a pair of values containing a local name and an optional namespace URI. 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 (or both absent) and the local names are the same.

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

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 5.2 Expressions) , and in certain other contexts, the namespace to be used in expanding the QName may be specified by means of the [xsl:]xpath-default-namespace attribute, as specified in 5.4 Unprefixed Names in Expressions and Patterns.

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

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

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

  • selecting nodes for processing;

  • specifying conditions for different ways of processing a node;

  • generating text to be inserted in the result tree.

Within this specification, the term XPath expression, or simply expression, means a string that matches the production Expr defined in [XPath 2.0].

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

[ERR031] Except where otherwise stated, 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.

[ERR032] The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error. The processor must signal the error.

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

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

[ERR033] It is a type error if an XPath expression raises a type error, or if the type of the XPath expression is incompatible with the required type. The processor must signal the 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.

  • The initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing instruction or literal result element. (Note that these values may change for evaluation of sub-expressions within the XPath expression, according to the XPath rules.)

5.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 12 Numbering), for grouping (see 14 Grouping), and for declaring keys (see 16.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 deriving an equivalent expression, and evaluating this expression with respect to some possible context.

Here are some examples of patterns:

  • para matches any para element

  • * matches any element

  • chapter|appendix matches any chapter element and any appendix element

  • olist/entry matches any entry element with an olist parent

  • appendix//para matches any para element with an appendix ancestor element

  • element(us:address) matches any element that is an instance of the schema-defined element declaration us:address, or another element in its substitution group.

  • attribute(*, xs:date) matches any attribute of type xs:date, as established by schema validation.

  • / matches a document node, or any other node that is the root of a tree (for example, a parentless element or attribute node)

  • document-node() matches a document node

  • document-node(element(my:invoice)) matches the document node of a document whose document element is validated against the schema type my:invoice

  • text() matches any text node

  • node() matches any node other than an attribute node, namespace node, or document node

  • id("W33") matches the element with unique ID W33

  • para[1] matches any para element that is the first para child element of its parent. It also matches a parentless para element.

  • //para matches any para element that has a parent node

  • bullet[position() mod 2 = 0] matches any bullet element that is an even-numbered bullet child of its parent.

  • div[@class="appendix"]//p matches any p element with a div ancestor element that has a class attribute with value appendix

  • @class matches any class attribute (not any element that has a class attribute)

  • @* matches any attribute node

[ERR035] 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 AxisStep that uses only the child or attribute axes. Patterns may also use the // operator. 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.

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

If a pattern occurs in part of the stylesheet where backwards compatible behavior is enabled (see 3.6 Backwards-Compatible Processing), then the semantics of the pattern are defined on the basis that the equivalent XPath expression is evaluated with the XPath 1.0 backwards compatibility flag set to true.

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' '(' IdKeyValue ')'
| 'key' '(' StringLiteral ',' IdKeyValue ')'
[7]   IdKeyValue   ::=    Literal | Variable

The constructs NodeTest, Literal, 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.

First we define the concept of an equivalent expression. In general, the equivalent expression is the XPath expression that takes the same lexical form as the pattern as written. However, if the pattern contains a PathPattern that is a RelativePathPattern, then the first PatternStep of this RelativePathPattern is adjusted to allow it to match a parentless element or attribute node. If this first PatternStep uses the child axis (explicitly or implicitly), and if the NodeTest in this PatternStep is not node(), then the axis in this step is replaced by child-or-top::. If this PatternStep uses the attribute axis, then the axis is replaced by attribute-or-top::.

The axes child-or-top and attribute-or-top are introduced only for definitional purposes, they cannot be used explicitly in a user-written pattern or expression. They are defined as follows:

  • If the context node is a parentless element, comment, processing-instruction, text, or document node then the child-or-top axis selects the context node; otherwise it selects the children of the context node. It is a forwards axis whose principal node kind is element.

  • If the context node is a parentless attribute node then the attribute-or-top axis selects the context node; otherwise it selects the attributes of the context node. It is a forwards axis whose principal node kind is attribute.

Note:

The purpose of this adjustment is to ensure that a pattern such as person matches any element named person, even if it has no parent; and similarly, that the pattern @width matches any attribute named width, even a parentless attribute. The rule also ensures that a pattern using a NodeTest of the form document-node(...) matches a document node, though for backwards compatibility reasons, it remains true that the pattern node() will not match a document node (or any other parentless node).

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. In this expression, PAT is the equivalent expression as defined above.

For example, p matches any p element, because a p element will always be present in the result of evaluating the expression //(child-or-top::p). Similarly, / matches the root of a tree, and only the root of a tree, because the result of the expression //(/) returns the root node of the tree containing the context node.

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 para[1]. This matches any node selected by the expression //(child-or-top::para[1]): that is, any para element that is the first para child of its parent , or a para element that has no parent.

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. It does not match document nodes, or other parentless nodes, because for backwards compatibility reasons the child axis is not replaced by child-or-top in this case.

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.

5.4 Unprefixed Names in Expressions and Patterns

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

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

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

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

The effective value of this attribute similarly applies to:

  • any unprefixed element name or type name used in a pattern within its scope

  • any unprefixed element name used in the elements attribute of the xsl:strip-space or xsl:preserve-space instructions within its scope

  • any unprefixed element name or type name used in the as attribute of any XSLT instructions within its scope.

  • any unprefixed type name used in the type attribute of any XSLT instructions within its scope.

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

If the effective value of the attribute is a zero-length string, which will be the case if it is explicitly set to a zero-length string or if it is not specified at all, then an unprefixed element name or type name refers to a name that is in no namespace. The default namespace (as defined by an xmlns="some-uri" declaration) is not used.

The attribute does not affect other names, for example function names, variable names, or names used as arguments to the key or system-property functions.

5.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. It may also contain a construct, such as a comment, that is delimited by paired opening and closing braces.

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

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

[ERR038] 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 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. This conversion is done by atomizing the result of the expression using the procedure defined in [XPath 2.0], and then converting each of the atomic values in the atomized sequence to a string, adding a single space after each value other than the last. If the atomized sequence is empty, the result is a zero-length string.

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

Note:

This may give a different result from XSLT 1.0. In XSLT 1.0, if the expression returned a node-set, all nodes other than the first were ignored.

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 declaration 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: this is because they must be interpreted in the same way by the XML parser and the XSLT processor.

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

 

The following source:

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

produces the result:

<temperature readings="10.32 5.5 8.31"/>

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

5.6 Sequence Constructors

Note:

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

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

A sequence constructor is a sequence of sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes and atomic values. The way that the resulting sequence is used depends on the containing instruction.

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

  • Text nodes appearing in the stylesheet (if they have not been removed in the process of whitespace stripping: see 4.1 Whitespace Stripping) are copied to create a new parentless text node in the result sequence.

  • Literal result elements are evaluated to create a new parentless element node, having the same name as the literal result element, which is added to the result sequence: see 11.1 Literal Result Elements

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

  • Extension instructions also produce a sequence of items as their result. The items in this sequence are added to the result sequence.

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

  • The sequence may be bound to a variable or returned from a stylesheet function, in which case it becomes available as a value to be manipulated in arbitrary ways by XPath expressions. The sequence is bound to a variable when the sequence constructor appears within one of the elements xsl:variable, xsl:param, or xsl:with-param, when this instruction has an as attribute that indicates that the constructed sequence is required as the value. For details, see 9.3 Values of Variables and Parameters. The sequence is returned from a stylesheet function when the sequence constructor appears within the xsl:function element.

    Note:

    This will typically expose to the stylesheet elements, attributes, and other nodes that have not yet been attached to a parent node in a result tree. The semantics of XPath expressions when applied to parentless nodes are well-defined; however, such expressions should be used with care. For example, the expression / selects the root node of the tree containing the context node, which will not necessarily be a document node. The expression /E selects an E element child of the root node of the tree: if the root node is itself an E element, this expression will not select it.

    Parentless attribute nodes require particular care because they have no namespace nodes associated with them. This means, for example, that the name function will not be able to determine a prefix to use when reporting the name of the attribute. When a parentless attribute node has content containing namespace prefixes (for example, a QName or an XPath expression) then there is no information allowing the prefix to be resolved to a namespace URI. Parentless attributes can be useful in an application (for example, they provide an alternative to the use of attribute sets: see 10.2 Named Attribute Sets) but they need to be handled with care.

  • The sequence may be returned as the result of the containing element. It will then typically be concatenated with other sequences before eventually being returned to an instruction that processes it. This happens when the instruction containing the sequence constructor is xsl:if, xsl:choose, xsl:when, xsl:otherwise, xsl:sequence, xsl:call-template, xsl:apply-templates, xsl:apply-imports, xsl:next-match, xsl:for-each, xsl:for-each-group, xsl:analyze-string, xsl:matching-substring, xsl:non-matching-substring, or xsl:fallback.

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

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

5.6.1 Constructing Complex Content

This section describes how the sequence obtained by evaluating a sequence constructor may be used to construct the children of a newly constructed document node, or the children, attributes and namespaces of a newly constructed element node.

The sequence is processed as follows:

  1. Any atomic value in the sequence is cast to a string. Special considerations apply to two atomic types:

    • [ERR039] A dynamic error occurs if the sequence contains an atomic value of type xs:NOTATION, because such values cannot be cast to a string. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending xs:NOTATION value.

    • If the sequence contains an atomic value of type xs:QName, the conversion to a string uses the in-scope namespaces of the element node whose content is being constructed. [ERR040] A dynamic error occurs if the node whose content is being constructed is a document node. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending xs:QName value. [ERR041] A dynamic error occurs if the node whose content is being constructed is an element that has no in-scope namespace that declares the namespace URI of the xs:QName value.This is a recoverable error. The processor must either signal the error, or must recover by adding a namespace node to the element under construction, and converting the xs:QName value to a string using the namespace prefix declared by this namespace node. The choice of namespace prefix is implementation-defined

  2. Any consecutive sequence of strings within the result sequence is converted to a single text node, whose string value contains the content of each of the strings in turn, with a single space (#x20) used as a separator between successive strings.

  3. Any document node within the result sequence is replaced by a sequence containing each of its children, in document order.

  4. [ERR042] It is a dynamic error if the result sequence used to construct the content of an element node contains a namespace node or attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace or attribute node.

  5. [ERR043] It is a dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace or attribute node.

  6. If the result sequence contains two or more namespace nodes with the same name (or no name) and the same string value (that is, two namespace nodes mapping the same prefix to the same namespace URI), then all but one of the duplicate nodes are discarded.

    Note:

    Since the order of namespace nodes is undefined, it is not significant which of the duplicates is retained.

  7. [ERR044] It is a dynamic error if the result sequence contains two or more namespace nodes having the same name but different string values (that is, namespace nodes that map the same prefix to different namespace URIs). This is a recoverable error. The processor must either signal the error, or must recover by discarding all conflicting namespace nodes other than the one that appears last in the result sequence.

  8. [ERR045] It is a dynamic error if the result sequence contains a namespace node with no name and the element node being constructed has a null namespace URI (that is, it is an error to define a default namespace when the element is in no namespace). This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace node.

  9. If an attribute A in the result sequence has the same name as another attribute B that appears later in the result sequence, then attribute A is discarded from the result sequence.

  10. Each node in the resulting sequence is attached as a namespace, attribute, or child of the newly constructed element or document node. Conceptually this involves making a deep copy of the node; in practice, however, copying the node will only be necessary if the existing node can be referenced independently of the parent to which it is being attached. When copying an element node, its base URI property is changed to be the same as that of its new parent, unless it has an xml:base attribute that overrides this.

  11. If the newly constructed node is an element node, then namespace fixup is applied to this node, as described in 5.6.3 Namespace Fixup

 

For example, consider the following stylesheet fragment:

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

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

 

5.6.2 Constructing Simple Content

The xsl:attribute, xsl:comment, xsl:processing-instruction, and xsl:namespace elements create nodes that cannot have children. These instructions take a sequence constructor as their content. The sequence constructor is evaluated to produce a result sequence in the usual way, and the string value of the new node is derived from this result sequence in the following way:

  1. Any atomic value in the sequence is cast to a string. Special considerations apply to atomic values of type xs:NOTATION or xs:QName:

    • [ERR046] A dynamic error occurs if the sequence contains a value of type xs:NOTATION, because such values cannot be cast to a string. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the xs:NOTATION value.

    • [ERR047] A dynamic error occurs if the sequence being used to construct the content of a namespace, comment, or processing-instruction node contains an atomic value of type xs:QName, because such values cannot be cast to a string without knowledge of the namespace context. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the xs:QName value.

    • [ERR048] A dynamic error occurs if the sequence being used to construct the content of an attribute node contains an atomic value of type xs:QName, because such values cannot be cast to a string without knowledge of the namespace context. This is a recoverable error. The processor must either signal the error, or must recover by converting the xs:QName value to a string using the namespace declarations that are in scope for the element to which the constructed attribute is eventually attached; if necessary, an additional namespace node may be attached to such an element to declare the required namespace; the namespace prefix used in any such namespace node is implementation-defined.

  2. Any consecutive sequence of strings within the result sequence is converted to a single text node, whose string value contains the content of each of the strings in turn, with a single space (#x20) used as a separator between successive strings.

  3. [ERR049] It is a dynamic error if the result sequence contains nodes other than text nodes. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the non-text nodes together with their content.

  4. The string value of the new attribute, namespace, comment, or processing-instruction node is the concatenation of the string values of the text nodes in the result sequence.

5.6.3 Namespace Fixup

In a tree supplied to or constructed by an XSLT processor, the following constraints relating to namespace nodes must be satisfied in addition to those specified in [Data Model]:

  • If an element node has an expanded-QName with a non-null namespace URI, then that element node must have at least one namespace node whose string value is the same as that namespace URI.

  • If an element node has an attribute node whose expanded-QName has a non-null namespace URI, then the element must have at least one namespace node whose string value is the same as that namespace URI and whose name is non-empty.

  • If an element node has a namespace node whose name is non-empty, then every child element of that element must also have a namespace node with that expanded-QName (possibly with a different string value).

  • Every element must have a namespace node whose expanded-QName has local-part xml and whose string value is http://www.w3.org/XML/1998/namespace.

  • If an element is annotated with the type xs:QName, or a type derived from xs:QName, or if it has an attribute with such a type annotation, then that element must have a namespace node whose string value is the same as the namespace URI of that QName value, and whose name is the same as the prefix used in the lexical representation of the QName (if the lexical representation is unprefixed, the namespace node must be unnamed).

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

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

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

Namespace fixup is applied to every element that is constructed using a literal result element, or one of the instructions xsl:element, xsl:copy, or xsl:copy-of.

There is no requirement to perform namespace fixup for any source document, that is, for a document in the initial input sequence, a document loaded using the document, doc or collection function, a document supplied as the value of a stylesheet parameter, or a document returned by an extension function. [ERR050] It is a dynamic error if such a document does not already satisfy the constraints listed above . This is a recoverable error. The processor may signal the error, or may recover by performing namespace fixup, or may produce implementation-dependent results.

In an InfoSet created from a document conforming to [XML Namespaces 1.0], it will always be true that if a parent element has an in-scope namespace with a non-empty namespace prefix, then its child elements will also have an in-scope namespace with the same namespace prefix, though possibly with a different namespace URI. This constraint is removed in [XML Namespaces 1.1]. XSLT 2.0 supports the creation of result trees that do not satisfy this constraint: the namespace fixup process does not add a namespace node to an element merely because its parent node in the result tree has such a namespace node. This means that it is possible to create result trees that cannot be faithfully serialized as XML 1.0 documents. When such a result tree is serialized as XML 1.0, namespace declarations written for the parent element will be inherited by its child elements as if the corresponding namespace nodes were present on the child element. When the same result tree is serialized as XML 1.1, however, it is possible to add namespace undeclarations to the child element (for example, xmlms:foo="") to prevent this inheritance taking place.

6 Template Rules

Template rules implement the push processing model described in 2.4.1 Push Processing Instructions.

6.1 Defining Templates

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

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

An xsl:template element must have either a match attribute or a name attribute, or both. If it has a match attribute, then it is a template rule. If it has a name attribute, then it is a named template. An xsl:template element that has no match attribute must have no mode attribute and no priority attribute.

A template may be invoked in a number of ways, depending on whether it is a template rule, a named template, or both. The result of invoking the template is the result of evaluating the sequence constructor contained in the xsl:template element. If an as attribute is present, the as attribute defines the required type of the result. [ERR051] The result of evaluating the sequence constructor is converted to the required type using the argument conversion rules. A type error occurs if this conversion is unsuccessful. Like other type errors, this error may be signaled statically if it can be detected statically.

If no as attribute is specified, the default value is item()*, which permits any value. No conversion then takes place.

6.2 Defining Template Rules

This section describes template rules. The use of named templates is described in 10.1 Named Templates.

A template rule is specified using the xsl:template element with a match attribute. The match attribute is a Pattern that identifies the source node or nodes to which the rule applies. The result of applying the template rule is the result of evaluating the sequence constructor contained in the xsl:template element, with the matching 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 in the next section, the xsl:apply-templates element can be used to process the children of a source element, and their children, recursively.

6.3 Applying Template Rules

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

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

If the instruction has one or more xsl:sort children, then then input sequence is sorted as described in 13 Sorting.

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, using rules described below; if there is none, a built-in template rule is used. The chosen template rule is evaluated. The rule that matches the Nth node in the sequence (after sorting) is evaluated with that node as the context item, with N as the context position, and with the length of the sequence as the context size. Each template rule that is evaluated produces a sequence of items as its result. 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 input sequence after sorting. The final concatenated sequence of nodes forms the result of the xsl:apply-templates instruction, and is passed to its parent instruction which will normally add the nodes to the result tree.

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. [ERR052] It is a dynamic error if the context item is not a node. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

Note:

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. This effect can be prevented by stripping whitespace text nodes as specified in 4.1 Whitespace Stripping.

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 of nodes (it can contain zero, one, or more nodes). The order of the result sequence will be the same as the order of this sequence, unless a sorting specification is present (see 13 Sorting).

[ERR053] It is a type error if the sequence returned by the select expression contains an item that is not a node. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the items that are not nodes. As with other type errors, the error may be signaled statically if it can be detected statically.

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.

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>
 

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

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

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

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

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

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

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

 

 

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.

6.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. [ERR054] The value of this must be a decimal number (positive or negative), matching the production NumericLiteral with an optional leading minus sign (-).

    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 the template rule is treated equivalently to a set of template rules, one for each alternative. However, it is not an error if a node matches more than one of the alternatives.

    • If the pattern has the form /, then the priority is -0.5.

    • 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 of an ElementTest or AttributeTest, optionally preceded by a PatternAxis, then the priority is as shown in the table below. In this table, the symbols E, A, and T represent an arbitrary element name, attribute name, and type name respectively, while the symbols * and @* represent themselves. A SchemaContextPath and LocalName may be specified instead of an element or attribute name; this does not affect the priority. The presence or absence of the keyword nillable does not affect the priority.

      FormatPriorityNotes
      element()-0.5(equivalent to *)
      element(*,*)-0.5(equivalent to *)
      attribute()-0.5(equivalent to @*)
      attribute(@*,*)-0.5(equivalent to @*)
      element(E,*)0(matches by substitution group)
      element(*,T)0(matches by type only)
      attribute(*,T)0(matches by type only)
      attribute(@A,*)0(equivalent to @A)
      element(E,T)0.25(matches by substitution group and type)
      element(E)0.25(matches by substitution group and type)
      attribute(@A,T)0.25(matches by name and type)
      attribute(@A)0.25(matches by name and type)
    • If the pattern has the form of a DocumentTest, then if it includes no ElementTest the priority is -0.5. If if does include an ElementTest, then the priority is the same as the priority of that ElementTest, computed according to the table above.

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

    • If the pattern is any other 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 of a particular kind, with a particular expanded-QName or a particular type) has priority 0. The next less specific kind of pattern (a pattern that tests for a node of a particular kind and an expanded-QName with a particular namespace URI) has priority -0.25. Patterns less specific than this (patterns that just test for nodes of a given kind) have priority -0.5. Patterns that specify both the name and the required type have a priority of +0.25, putting them above patterns that only specify the name or the type. Patterns more specific than this, for example patterns that include predicates or that specify the ancestry of the required node, have priority 0.5.

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

[ERR055] It is a dynamic error if this leaves more than one matching template rule. This is a recoverable error. 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.

6.5 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 16.1 Multiple Source Documents) or when processing temporary trees (see 9.4 Temporary Trees)

Modes are identified by a QName, except for the default mode, which is unnamed.

A template rule is applicable to one or more modes. The modes to which it is applicable are defined by the mode attribute of the xsl:template element. If the attribute is omitted, then the template rule is applicable to the default mode. If the attribute is present, then its value must be a space-separated list of tokens, each of which defines a mode to which the template rule is applicable. Each token must either be a QName, which is expanded as described in 5.1 Qualified Names to define the name of the mode, or it must be the token #default, to indicate that the template rule is applicable to the default mode, or it must be the token #all, to indicate that the template rule is applicable to all modes.

[ERR056] It is a static error if the same token is included more than once in the list or if the token #all appears together with any other value.

The xsl:apply-templates element also has an optional mode attribute. The value of this attribute must either be a QName, which is expanded as described in 5.1 Qualified Names to define the name of a mode, or the token #default, to indicate that the default mode is to be used, or the token #current, to indicate that the current mode is to be used. If the attribute is omitted, the default mode is used.

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

At any point in the processing of a stylesheet, there is a current mode. When the transformation is initiated, the current mode is the default mode, unless a different initial mode has been supplied, as described in 2.3 Initiating a Transformation. Whenever an xsl:apply-templates instruction is evaluated, the current mode becomes the mode selected by this instruction. When a stylesheet function is called, the current mode becomes the default mode. No other instruction changes the current mode. On completion of the xsl:apply-templates instruction, or on return from a stylesheet function call, the current mode reverts to its previous value. The current mode is used when an xsl:apply-templates instruction uses the syntax mode="#current"; it is also used by the xsl:apply-imports and xsl:next-match instructions (see 6.7 Overriding Template Rules).

6.6 Built-in Template Rules

When a node is selected by xsl:apply-templates and there is no template rule in the stylesheet that can be used to process that node, a built-in template rule is evaluated instead. The built-in template rule for document nodes and elements nodes causes the children of the node to be processed; the built in rule for text nodes and attribute nodes causes the text to be copied to the result tree.

The built-in template rules apply to all modes. It is not possible for a user-written template rule to apply to all modes, but for the sake of illustration, the syntax mode="#all" is used in the examples below as shorthand for a list of all modes (including the default mode) that are used in the stylesheet.

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

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="#all">
  <xsl:with-param name="init"/>
  <xsl:apply-templates mode="#current">
    <xsl:with-param name="init" select="$init"/>
  </xsl:apply-templates>
</xsl:template>

The built-in template rule for text and attribute nodes returns a text node containing the string value of the context node, unless the string value is zero-length, in which case it returns an empty sequence. It is effectively:

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

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

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

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 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.7 Overriding Template Rules

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

<!-- Category: instruction -->
<xsl:next-match>
  <!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:next-match>

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

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 sequence constructor. When an xsl:for-each or xsl:for-each-group instruction is evaluated, or when a stylesheet function is called (see 10.3 Stylesheet Functions), the current template rule becomes null for the evaluation of that instruction or function.

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

Note:

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

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

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

    Note:

    This is not the same as saying that the search considers all template rules whose import precedence is lower than that of the current template rule.

  • The xsl:next-match instruction considers as candidates all those template rules that come after the current template rule in the ordering of template rules implied by the conflict resolution rules given in 6.4 Conflict Resolution for Template Rules. That is, it considers all template rules with lower import precedence than the current template rule, plus the template rules that are at the same import precedence that have lower priority than the current template rule. If the processor has recovered from the error that occurs when two matching template rules have the same import precedence and priority, then it also considers all matching template rules with the same import precedence and priority that occur before the current template rule in declaration order.

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

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

An xsl:apply-imports or xsl:next-match element may use xsl:with-param child elements to pass parameters to the chosen template rule (see 10.1.1 Passing Parameters to Templates).

[ERR058] It is a dynamic error if xsl:apply-imports or xsl:next-match 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>

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

7 Repetition

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

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

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

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

For each item in the input sequence, evaluating the sequence constructor produces a sequence of items; 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 items.

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>

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

8.1 Conditional Processing with xsl:if

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

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

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

If the effective boolean value of the expression is true, then the sequence constructor is evaluated, 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>

8.2 Conditional Processing with xsl:choose

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

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

<xsl:otherwise>
  <!-- Content: sequence-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 sequence constructor.

When an xsl:choose element is processed, each of the xsl:when elements is tested in turn (that is, in document order as the elements appear in the stylesheet), until one of the xsl:when elements is satisfied. An xsl:when element is satisfied if the effective boolean value of the expression in its test attribute is true. The rules for determining the effective boolean value of an expression are given in [XPath 2.0]: they are the same as the rules used for XPath conditional expressions.

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

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

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>

9 Variables and Parameters

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

The xsl:variable element declares a variable, which may be a global variable or a local variable. The xsl:param element declares a parameter, which may be a stylesheet parameter, a template parameter, or a function parameter. A parameter is a variable with the additional property that its value can be set by the caller of the stylesheet, the template, or the function.

A variable is a binding between a name and a value. The value to which a variable is bound (the value of the variable) is any sequence (of nodes and/or atomic values), as defined in [Data Model].

9.1 Variables

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

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

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

The value of the variable is computed using the expression given in the select attribute and/or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters. This value is referred to as the supplied value of the variable.

[ERR059] If the as attribute is specified, then the supplied value of the variable is converted to the required type, using the argument conversion rules. It is a type error if this conversion fails. The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

If the as 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()*.

The type-information attribute is used to determine what type annotations are to be present in a newly constructed tree. [ERR060] It is an error to specify the type-information attribute on a variable binding element that has empty content. For details of the meaning of this attribute, see 9.4 Temporary Trees.

9.2 Parameters

<!-- Category: declaration -->
<xsl:param
  name = qname
  select = expression
  as = sequence-type
  required = "yes" | "no">
  <!-- Content: sequence-constructor -->
</xsl:param>

The xsl:param element may be used as a child of xsl:stylesheet, to define a parameter to the transformation; or as a child of xsl:template to define a parameter to a template, which may be supplied when the template is invoked using xsl:call-template, xsl:apply-templates, xsl:apply-imports or xsl:next-match; or as a child of xsl:function to define a parameter to a stylesheet function, which may be supplied when the function is called from an XPath expression.

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

The supplied value of the parameter is the value supplied by the caller. If no value was supplied by the caller, and if the parameter is not mandatory, then the supplied value is computed using the expression given in the select attribute and/or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters.

The xsl:param element has an optional as attribute, which specifies the required type of the parameter. The value of the as attribute is a SequenceType, as defined in [XPath 2.0]. [ERR061] If the as attribute is specified, then the supplied value of the parameter is converted to the required type, using argument conversion rules. It is a type error if this conversion fails.

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

The type-information attribute is used to determine what type annotations are to be present in a newly constructed tree. The type-information attribute is relevant only to the default value of the parameter; it does not affect the treatment of a value supplied as an actual parameter by the caller. [ERR062] It is an error to specify the type-information attribute on an xsl:param element that has empty content. For details of the meaning of this attribute, see 19.2 Validation.

The required attribute may be used to indicate that a parameter is mandatory. This attribute may be specified for stylesheet parameters and for template parameters; it must not be specified for function parameters, which are always mandatory. The default value is no, indicating that the parameter is optional. If the value of the required attribute is yes, the xsl:param element must be empty, and must have no select attribute.

[ERR063] If the value of the required attribute is no, and the caller supplies no value for the parameter, then it is a type error if the default value of the parameter cannot be converted to the required type, using the argument conversion rules. If the default value is supplied implicitly, that is, if the xsl:param element has no select attribute and has empty content, then the default value is a zero-length string; if the zero-length string cannot be converted to the required type, then an error must be signaled only as a dynamic error, if the caller supplies no value for the parameter. In all other cases the type error may be signaled either as a static error or as a dynamic error.

9.3 Values of Variables and Parameters

A variable-binding element may specify the supplied value of the variable or parameter in four different ways.

  • If the variable-binding element has a select attribute, then the value of the attribute must be an expression and the supplied value of the variable is the value that results from evaluating the expression. In this case, the content of the variable-binding element must be empty.

  • If the variable-binding element has empty content and has neither a select attribute nor an as attribute, then the supplied value of the variable is a zero-length string. Thus

    <xsl:variable name="x"/>

    is equivalent to

    <xsl:variable name="x" select="''"/>
  • If a variable-binding element has no select attribute and has non-empty content (i.e. the variable-binding element has one or more child nodes), and has no as attribute, then the content of the variable-binding element specifies the supplied value. The content of the variable-binding element is a sequence constructor; a new document (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 sequence constructor. Temporary trees are described in more detail in 9.4 Temporary Trees.

  • If a variable-binding element has an as attribute but no select attribute, then the supplied value is the sequence that results from evaluating the (possibly empty) sequence constructor contained within the variable-binding element.

These combinations are summarized in the table below.

select attributeas attributecontentEffect
presentabsentemptyValue is obtained by evaluating the select attribute
presentpresentemptyValue is obtained by evaluating the select attribute, adjusted to the type required by the as attribute
presentabsentpresentStatic error
presentpresentpresentStatic error
absentabsentemptyValue is a zero-length string
absentpresentemptyValue is an empty sequence, provided the as attribute permits an empty sequence
absentabsentpresentValue is a temporary tree
absentpresentpresentValue is obtained by evaluating the sequence constructor, adjusted to the type required by the as attribute

[ERR064] It is a static error if a variable-binding element has a select attribute and has non-empty content.

 

The value of the following variable is the sequence of integers (1, 2, 3):

<xsl:variable name="i" as="xs:integer*" select="1 to 3"/>

The value of the following variable is an integer, assuming that the attribute @size exists, and is annotated either as an integer, or as xdt:untypedAtomic:

<xsl:variable name="i" as="xs:integer" select="@size"/>

The value of the following variable is a zero-length string:

<xsl:variable name="z"/>

The value of the following variable is document node containing an empty element as a child (that is, a temporary tree):

<xsl:variable name="doc"><c/></xsl:variable>

The value of the following variable is sequence of integers (2, 4, 6):

<xsl:variable name="seq" as="xs:integer*">
  <xsl:for-each select="1 to 3">
    <xsl:sequence select=".*2"/>
  </xsl:for-each>
</xsl:variable>

The value of the following variable is sequence of parentless attribute nodes:

<xsl:variable name="attset" as="attribute()+">
  <xsl:attribute name="x">2</xsl:attribute>
  <xsl:attribute name="y">3</xsl:attribute>
  <xsl:attribute name="z">4</xsl:attribute>    
</xsl:variable>

The value of the following variable is an empty sequence:

<xsl:variable name="empty" as="empty()"/>
 

The actual value of the variable depends on the supplied value, as described above, and the required type, which is determined by the value of the as attribute.

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="td[$n]"/>

This will output the value of the first td element, because the variable n will be bound to a node, not a number. Instead, do one of the following:

<xsl:variable name="n" select="2"/>
...
<xsl:value-of select="td[$n]"/>

or

<xsl:variable name="n">2</xsl:variable>
...
<xsl:value-of select="td[position()=$n]"/>

or

<xsl:variable name="n" as="xs:integer">2</xsl:variable>
...
<xsl:value-of select="td[$n]"/>

9.4 Temporary Trees

A temporary tree is constructed by evaluating an xsl:variable, xsl:param, or xsl:with-param, or xsl:result element that has non-empty content and that has no as attribute. This element is referred to as the variable-binding element. The value of the variable is a single node, the document node of the temporary tree. This document node is created implicitly, and its content is formed from the result of evaluating the sequence constructor owned by the variable-binding element, as described in 5.6.1 Constructing Complex Content.

The actual value of the variable depends on the supplied value, as described above, and the required type, which is determined by the value of the as attribute.

Namespace fixup is performed on the temporary tree (see 5.6.3 Namespace Fixup).

The base URI of a node in the temporary tree is determined as if all the nodes in the temporary tree came from a single entity whose URI was the base URI of the variable-binding element (see [Data Model]). Thus, the base URI of the document node will be equal to the base URI of the variable-binding element; an xml:base attribute within the temporary tree will change the base URI for its parent element and that element's descendants, just as it would within a document constructed by parsing.

A temporary tree is available for processing in exactly the same way as any source document. For example, its nodes are accessible using path expressions, and they can be processed using instructions such as xsl:apply-templates and xsl:for-each. Also, the key and id functions can be used to find nodes within a temporary tree, provided that at the time the function is called, the context item is a node within the temporary tree.

The type-information attribute determines what type annotations will be present on the element and attribute nodes of the constructed tree. The default value is none. The effect of this attribute is described in 19.2 Validation.

For example, the following stylesheet uses a temporary tree as the intermediate result of a two-phase transformation, using different modes for the two phases (see 6.5 Modes):

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

<xsl:import href="phase1.xsl"/>
<xsl:import href="phase2.xsl"/>

<xsl:variable name="intermediate">
  <xsl:apply-templates select="/" mode="phase1"/>
</xsl:variable>

<xsl:template match="/">
  <xsl:apply-templates select="$intermediate" mode="phase2"/>
</xsl:template>

</xsl:stylesheet>
Note:

The algorithm for matching nodes against template rules is exactly the same regardless which tree the nodes come from; if nodes from different trees cannot be distinguished by means of patterns, it is therefore a good idea to use modes to ensure that each tree is processed using the appropriate set of template rules.

9.5 Global Variables and Parameters

Both xsl:variable and xsl:param are allowed as declaration elements: that is, they may appear as children of the xsl:stylesheet element. 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 stylesheet parameter. A stylesheet parameter is a global variable with the additional property that its value can be supplied by the caller when a transformation is initiated. XSLT does not define the mechanism by which parameter values are passed to the stylesheet.

If a stylesheet contains more than one binding for a global variable of a particular name, then the binding with the highest import precedence is used. [ERR065] 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 the default value of a stylesheet parameter, the expression or sequence constructor specifying the variable value is evaluated with a singleton focus based on the document node of the document containing the initial context node. It is therefore an error for the evaluation of a global variable or parameter to reference the context item, context position, or context size when no initial context node is supplied.

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

<xsl:param name="para-font-size" as="xs:string">12pt</xsl:param>

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

The implementation is expected to provide a mechanism allowing the user to supply a value for the parameter para-font-size when invoking the stylesheet; the value 12pt acts as a default.

9.6 Local Variables and Parameters

As well as being allowed as declaration elements, the xsl:variable element is also allowed in sequence constructors and within the xsl:function element (see 10.3 Stylesheet Functions) after any xsl:param elements and before the xsl:result element. Such a variable is known as a local variable.

An xsl:param element may appear as a child of an xsl:template element, before any non-xsl:param children of that element. Such a parameter is known as a template parameter. A template parameter is a local variable with the additional property that its value can be set when the template is called, using any of the instructions xsl:call-template, xsl:apply-templates, xsl:apply-imports, or xsl:next-match.

An xsl:param element may appear as a child of an xsl:function element, before any non-xsl:param children of that element. Such a parameter is known as a function parameter. A function parameter is a local variable with the additional property that its value can be set when the function is called, using a function call in an XPath expression.

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

9.7 Scope of Variables

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

A global variable binding element is visible everywhere in the stylesheet (including other stylesheet modules) except within the xsl:variable or xsl:param element itself and any region where it is shadowed by another variable binding.

A local variable binding element is visible for all following siblings and their descendants. The binding is not visible for the xsl:variable or xsl:param element itself.

A binding shadows another binding if the binding occurs at a point where the other binding is visible, and the bindings have the same name. It is not an error if a binding established by a local xsl:variable or xsl:param shadows a global binding. In this case, the global binding will not be visible in the region of the stylesheet where it is shadowed by the other binding.

Thus, the following is allowed:

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

It is also not an error if a binding established by a local xsl:variable or xsl:param element shadows another binding established by another local xsl:variable or xsl:param. However, such shadowing is discouraged and implementations may output a warning when it occurs.

 

Thus, the following is not an error, but is discouraged, because the effect is probably not what was intended. The template outputs <x value="1"/>, because the declaration of the inner variable named $x has no effect on the value of the outer variable named $x.

<xsl:template name="foo">
  <xsl:variable name="x" select="1"/>
  <xsl:for-each select="1 to 5">
    <xsl:variable name="x" select="$x+1"/>
  <xsl:for-each>
  <x value="{$x}"/>
</xsl:template>
 
Note:

Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages.

This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.

As well as global variables and local variables, an XPath expression may also declare range variables for use locally within an expression. For details, see [XPath 2.0].

Where a reference to a variable occurs in an XPath expression, it is resolved first by reference to range variables that are in scope, then by reference to local variables and parameters, and finally by reference to global variables and parameters. A range variable may shadow a local variable or a global variable. XPath also allows a range variable to shadow another range variable.

9.8 Circular Definitions

If the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. 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 10.3 Stylesheet Functions for an explanation of the xsl:function element) also create a circularity:

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

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

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

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

[ERR066] 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 local variable $b, but it returns a result that does not require the variable to be evaluated. It is implementation-dependent whether the value is actually evaluated, and it is therefore implementation-dependent whether the circularity is signaled as an error:

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

<xsl:function name="my:f">
  <xsl:param name="a"/>
  <xsl:variable name="b" select="$x"/>  
  <xsl:sequence select="$a + 2"/>
</xsl:function>

Circularities usually involve global variables or parameters, but they can also exist between key definitions (see 16.3 Keys), between named attribute sets (see 10.2 Named Attribute Sets), or between any combination of these constructs. For example, a circularity exists if a key definition invokes a function that references an attribute set that calls the key function, supplying the name of the original key definition as an argument.

Circularity is not the same as recursion. Stylesheet functions (see 10.3 Stylesheet Functions) and named templates (see 10.1 Named Templates) may call other functions and named templates without restriction. With careless coding, recursion may be non-terminating. Implementations are required to signal circularity as a dynamic error, but they are not required to detect non-terminating recursion.

10 Callable Components

This section describes three constructs that can be used to provide subroutine-like functionality that can be invoked from anywhere in the stylesheet: named templates (see 10.1 Named Templates), named attribute sets (see 10.2 Named Attribute Sets) and stylesheet functions (see 10.3 Stylesheet Functions).

10.1 Named Templates

<!-- 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 defines a named template. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. If an xsl:template element has a name attribute, it may, but need not, also have a match attribute. An xsl:call-template 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 instruction. Similarly, the name attribute on an xsl:template element does not affect whether the template is invoked by an xsl:apply-templates instruction.

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

The result of evaluating an xsl:call-template instruction is the node sequence produced by evaluating the sequence constructor contained in the associated xsl:template element. The associated xsl:template element is the one whose name attribute matches the name attribute of the xsl:call-template instruction and that has higher import precedence than any other template with this name.

[ERR068] It is a static error if a stylesheet contains an xsl:call-template instruction whose name attribute does not match the name attribute of any xsl:template in the stylesheet.

10.1.1 Passing Parameters to Templates

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

Parameters are passed to templates using the xsl:with-param element. The required name attribute specifies the name of the template parameter (the variable the value of whose binding is to be replaced). The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names.

xsl:with-param is allowed within xsl:call-template, xsl:apply-templates, xsl:apply-imports, and xsl:next-match. [ERR069] It is a static error if a single xsl:call-template, xsl:apply-templates, xsl:apply-imports, or xsl:next-match 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 (see 9.3 Values of Variables and Parameters. 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, xsl:next-match, 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 template parameter named x; the parameter is simply ignored.

[ERR070] In the case of xsl:call-template, it is a static error to pass a parameter x to a template that does not have a template parameter named x. This is not an error in the case of xsl:apply-templates, xsl:apply-imports, and xsl:next-match; in these cases the parameter is simply ignored.

[ERR071] In the case of xsl:apply-templates, xsl:apply-imports, and xsl:next-match it is a dynamic error if the template that is invoked declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction. The processor must signal the error.

[ERR072] In the case of xsl:call-template, it is a static error if the template that is invoked declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction.

The type-information attribute determines what type annotations will be present on the element and attribute nodes of the constructed tree. This attribute must be omitted if the content of the xsl:with-param element is empty. The default value is none. For details, see 19.2 Validation.

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 10.3 Stylesheet Functions

10.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 attribute set: that is, a collection of attribute values that can be used repeatedly on different elements in the result tree. 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 5.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 11.8 Copying Nodes from a Source Tree to a 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 5.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. [ERR073] 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 sequence 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 sequence constructor, only the last attribute with a given expanded-QName has any effect (see 5.6 Sequence Constructors), this means that attributes specified in attribute sets can be overridden by attributes specified on the literal result element itself.

The sequence 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 9 Variables and Parameters); thus, only global variables and parameters and local variables declared within an xsl:attribute instruction 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. [ERR074] 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. This is a recoverable error. 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.

10.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. [ERR075] 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 11.1.3 Namespace Nodes for Literal Result Elements.

10.3.1 Defining a Stylesheet Function

<!-- Category: declaration -->
<xsl:function
  name = qname
  as = sequence-type
  override = "yes" | "no">
  <!-- Content: (xsl:param*, sequence-constructor) -->
</xsl:function>

The xsl:function declaration defines a stylesheet function that can be called from any XPath expression used in the stylesheet (including an XPath expression used within a predicate in a pattern). The name attribute specifies the name of the function. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names [ERR076] The name attribute must be in a non-null namespace: that is, it must be written with a prefix.

An xsl:function declaration can only appear as a top-level element in the stylesheet.

The content of the xsl:function element consists of zero or more xsl:param elements that specify the formal arguments of the function, followed by a sequence constructor that defines the value to be returned by the function.

The arity of a stylesheet function is the number of xsl:param elements in the function definition. Optional arguments are not allowed. [ERR077] Because arguments to a stylesheet function call must all be specified, the xsl:param elements within an xsl:function element must not specify a default value: this means they must be empty, and must have no select attribute.

A stylesheet function is included in the in-scope functions of the static context for all XPath expressions used in the stylesheet, unless

  • there is another stylesheet function with the same name and arity, and higher import precedence, or

  • the override attribute has the value no and there is already a function with the same name and arity in the in-scope functions.

The optional override attribute defines what happens if this function has the same name and arity as a function provided by the implementor or made available in the static context using an implementation-defined mechanism. If the override attribute has the value yes, then this function is used in preference; if it has the value no, then the other function is used in preference. The default value is yes.

Note:

Specifying override="yes" ensures interoperable behavior: the same code will execute with all processors. Specifying override="no" is useful when writing a fallback implementation of a function that is available with some processors but not others: it allows the vendor's implementation of the function to be used in preference to the stylesheet implementation, which is useful when the vendor's implementation is more efficient.

[ERR078] It is a static error for a stylesheet to contain two or more functions with the same expanded-QName, the same arity, and the same import precedence, unless there is another function with the same expanded-QName and arity, and a higher import precedence.

As defined in XPath, the function that is executed as the result of a function call is identified by looking in the in-scope functions of the static context for a function whose name and arity matches the name and number of arguments in the function call. In an XSLT context, the error that occurs when there is no matching function is a dynamic error: this is to allow the stylesheet to execute conditional logic depending on whether or not a function is available, which can be tested using the function-available function.

When a stylesheet function is called, the number of arguments in the function call must match the arity of the function definition.

Note:

Functions are not polymorphic. Although the XPath function call mechanism allows two functions to have the same name and different arity (number of arguments), it does not allow them to be distinguished by the types of their arguments.

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

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

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. [ERR080] It is a static error if the number of arguments supplied in the function call is different from the number of xsl:param elements in the function definition.

The as attribute of the xsl:param element defines the required type of the parameter. The rules for converting the values of the actual arguments supplied in the function call to the types required by each xsl:param element are defined in [XPath 2.0]. The rules that apply are those for the case where the "XPath 1.0 backwards compatibility flag" is not set. If the value cannot be converted to the required type, a type exception is signaled. If the as attribute is omitted, the effective default is item()*, which means that no conversion takes place and any value is accepted.

[ERR081] Within the body of a stylesheet function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a dynamic error. The processor must signal the error. 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 9.1 Variables).

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://example.com/namespace"
  version="2.0"
  exclude-result-prefixes="str">

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs:string"/>
  <xsl:sequence  
     select="if (contains($sentence, ' '))
             then concat(str:reverse(substring-after($sentence, ' ')),
                         ' ',
                         substring-before($sentence, ' '))
             else $sentence"/>
</xsl:function>

<xsl:template match="/">
<output>
  <xsl:value-of select="str:reverse('DOG BITES MAN')"/>
</output>
</xsl:template>

</xsl:transform>

An alternative way of writing the same function is to implement the conditional logic at the XSLT level, thus:

<xsl:function name="str:reverse" as="xs:string">
  <xsl:param name="sentence" as="xs:string"/>
  <xsl:choose>
    <xsl:when test="contains($sentence, ' ')">  
      <xsl:sequence select="concat(str:reverse(substring-after($sentence, ' ')),
                                ' ',
                                substring-before($sentence, ' '))"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:sequence select="$sentence"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>

 

The following example illustrates the use of the as attribute in a function definition. It returns a string containing the representation of its integer argument, expressed as a roman numeral. For example, the function call num:roman(7) will return the string "vii". This example uses the xsl:number instruction, described in 12 Numbering. The xsl:number instruction returns a text node, and the argument conversion rules are invoked to convert this text node to the type declared in the xsl:function element, namely xs:string. So the text node is atomized to a string.

<xsl:function name="num:roman" as="xs:string">
  <xsl:param name="value" as="xs:integer"/>
  <xsl:number value="$value" format="i"/>
</xsl:function>

10.3.2 Returning the Result

<xsl:result
  select = expression>
  <!-- Content: sequence-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 9.3 Values of Variables and Parameters. If there is no select attribute and no sequence constructor, the result is a zero-length string; it is a static error if there is both a select attribute and a non-empty sequence constructor.

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

The type-information attribute determines what type annotations will be present on the element and attribute nodes of the constructed tree. This attribute must be omitted if the content of the xsl:result element is empty. The default value is none. For details, see 19.2 Validation.

11 Creating Nodes and Sequences

This section describes instructions that directly create new nodes, or sequences of nodes and atomic values.

11.1 Literal Result Elements

In a sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 18.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 sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the element, as described in 5.6.1 Constructing Complex Content

11.1.1 Setting the Type Annotation for Literal Result Elements

The attributes xsl:type and xsl:validation may be used on a literal result element to check the contents of the element against a schema definition, and to determine the type annotation that the new element node will carry. These attributes also affect the type annotation carried by any elements and attributes that have the new element node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their meanings are described in 19.2 Validation.

11.1.2 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 stylesheet tree, and its string value will be the same as the effective value of the attribute in the stylesheet tree.

The type annotation on the attribute node depends on the xsl:validation and xsl:type attributes of the parent literal result element. If the xsl:validation attribute is set to preserve or strip, the type annotation will be xdt:untypedAtomic, and the typed value of the attribute node will be the same as its string value. If the xsl:validation attribute is set to strict or lax, of if the xsl:type attribute is used, the type annotation on the attribute will be set as a result of the schema validation process applied to the parent element. If neither attribute is present, the type annotation on the attribute will be xdt:untypedAtomic.

Additional attributes may be generated by including xsl:attribute instructions in the sequence 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 10.2 Named Attribute Sets. The type annotation on the additional attributes will be preserved, erased, or set by the validation process depending on the value of the xsl:validation attribute of the literal result element.

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.

Note:

The same is true of the schema-defined attributes xsi:type, xsi:nil, and xsi:schemaLocation. If the stylesheet is processed by a schema processor, these attributes will be recognized and interpreted by the schema processor, but they have no special meaning to the XSLT processor. The attributes are copied to the result tree in the same way as any other attribute. If the result tree is validated, the copied attributes will again be recognized and interpreted by the schema processor.

None of these attributes will be generated in the result tree unless the stylesheet writes them to the result tree explicitly.

11.1.3 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 (before the application of any namespace aliases: see 11.1.4 Namespace Aliasing) is designated as an excluded namespace.

The following namespaces are designated as excluded namespaces:

  • The XSLT namespace URI (http://www.w3.org/1999/XSL/Transform)

  • A namespace URI declared as an extension namespace (see 18.2 Extension Instructions)

  • A namespace URI designated by using an [xsl:]exclude-result-prefixes attribute either on the literal result element itself or on an ancestor element. The attribute must be in the XSLT namespace only if its parent element is not in the XSLT namespace.

    The value of the attribute is a whitespace-separated list of tokens, each of which is either a namespace prefix, or #default, or #all . 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 value #all indicates that all namespaces are designated as excluded namespaces. In this case, any other prefixes are ignored.

    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.

The excluded namespaces, as described above, only affect namespace nodes copied from the stylesheet when processing a literal result element. There is no guarantee that an excluded namespace will not appear on the result tree for some other reason. Namespace nodes are also written to the result tree as part of the process of namespace fixup (see 5.6.3 Namespace Fixup), or as the result of instructions such as xsl:copy and xsl:element.

Note:

When a stylesheet uses a namespace declaration only for the purposes of addressing 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 stylesheet functions or extension functions from appearing in the result tree.

11.1.4 Namespace Aliasing

When a stylesheet is used to define a transformation whose output is itself a stylesheet module, or in certain other cases where the result document uses namespaces that it would be inconvenient to use in the stylesheet, namespace aliasing can be used to declare a mapping between a namespace URI used in the stylesheet and the corresponding namespace URI to be used in the result document.

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 namespace prefix that will be used in the serialized output document is implementation-dependent.

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. [ERR083] It is a static error if there is more than one such declaration with the same stylesheet-prefix and the same import precedence and different values for namespace-uri.

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="file://namespace.alias">

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

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

The output of the transformation will be a stylesheet such as the following. Whitespace has been added for clarity. Note that an implementation may output different namespace prefixes from those appearing in this example.

<xsl:stylesheet
  version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:fo="http://www.w3.org/1999/XSL/Format">
  
<xsl:template match="p">
  <fo:block><xsl:apply-templates/></fo:block>
</xsl:template>

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

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

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

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

</xsl:stylesheet>
Note:

It may be necessary also to use aliases for namespaces other than the XSLT namespace URI. For example, it can be useful to define an alias for the namespace http://www.w3.org/2001/XMLSchema-instance, so that the stylesheet can use the attributes xsi:type, xsi:nil, and xsl:schemaLocation on a literal result element, without running the risk that a schema processor will interpret these as applying to the stylesheet itself. Equally, literal result elements belonging to a namespace dealing with digital signatures might cause XSLT stylesheets to be mishandled by general-purpose security software; using an alias for the namespace would avoid the possibility of such mishandling.

11.2 Creating Element Nodes using xsl:element

<!-- Category: instruction -->
<xsl:element
  name = { qname }
  namespace = { uri-reference }
  use-attribute-sets = qnames
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname>
  <!-- Content: sequence-constructor -->
</xsl:element>

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

The content of the xsl:element instruction is a sequence constructor for the children, attributes, and namespaces of the created element. The sequence obtained by evaluating this sequence constructor is used to construct the content of the element, as described in 5.6.1 Constructing Complex Content

The result of evaluating the xsl:element instruction, except in error cases, is the newly constructed element node.

The name attribute is interpreted as an attribute value template.

[ERR084] It is a dynamic error if the effective value is not a QName. This is a recoverable error. 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 and namespace nodes.

[ERR085] In the case of an xsl:element instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:element instruction. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

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 zero-length, then the expanded-QName of the element has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded-QName of the element to be created. The local part of the 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 10.2 Named Attribute Sets

11.2.1 Setting the Type Annotation for a Constructed Element Node

The attributes type and validation may be used on the xsl:element instruction to check the contents of the element against a schema definition, and to determine the type annotation that the new element node will carry. These attributes also affect the type annotation carried by any elements and attributes that have the new element node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their meanings are described in 19.2 Validation.

11.3 Creating Attribute Nodes using xsl:attribute

<!-- Category: instruction -->
<xsl:attribute
  name = { qname }
  namespace = { uri-reference }
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname
  disable-output-escaping = "yes" | "no">
  <!-- Content: sequence-constructor -->
</xsl:attribute>

The xsl:attribute element can be used to add attributes to result elements whether created by literal result elements in the stylesheet or by instructions such as xsl:element or xsl:copy. The expanded-QName of the attribute to be created is specified by a 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 sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the attribute, as described in 5.6.2 Constructing Simple Content.

The name attribute is interpreted as an attribute value template.

[ERR086] It is a dynamic error if the effective value is not a QName or is the string xmlns. This is a recoverable error. The processor must either signal the error, or must recover by not adding the attribute to the result tree.

[ERR087] In the case of an xsl:attribute instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:attribute instruction. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

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 zero-length, then the expanded-QName of the attribute has a null namespace URI. Otherwise, the string is used as the namespace URI of the expanded-QName of the attribute to be created. The local part of the 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 write:

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

it will not result in the namespace declaration xmlns:xsl="http://www.w3.org/1999/XSL/Transform" being output. Instead, it will produce an attribute node with local name xsl, and with a system-allocated namespace prefix mapped to the namespace URI file://some.namespace.

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

For the effect of the disable-output-escaping attribute, see 20.2 Disabling Output Escaping

11.3.1 Setting the Type Annotation for a Constructed Attribute Node

The attributes type and validation may be used on the xsl:attribute instruction to check the contents of the attribute against a schema definition, and to determine the type annotation that the new attribute node will carry. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their meanings are described in 19.2 Validation.

11.4 Creating Text Nodes

11.4.1 Literal Text Nodes

A sequence constructor can also contain text nodes. Each text node in a sequence constructor remaining after whitespace has been stripped as specified in 4.1 Whitespace Stripping will construct a text node with the same string value. The resulting text node is added to the result of the containing sequence 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 serialized as an XML document (unless output escaping is disabled as described in 20.2 Disabling Output Escaping).

11.4.2 Creating Text Nodes using xsl:text

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

The xsl:text element is evaluated to contruct a new text node. The content of the xsl:text element is a single text node whose value forms the string value of the text node. An xsl:text element may also be empty, in which case the result of evaluating the instruction is an empty sequence.

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

A text node that is an immediate child of an xsl:text instruction will not be stripped from the stylesheet tree, even if it consists entirely of whitespace (see 4.1 Whitespace Stripping).

For the effect of the disable-output-escaping attribute, see 20.2 Disabling Output Escaping

[ERR088] It is a static error to specify disable-output-escaping="yes" on an xsl:text instruction that has element node children.

Note:

It is not always necessary to use the xsl:text instruction to write text nodes to the result tree. Literal text can be written to the result tree by including it anywhere in a sequence constructor, while computed text can be output using the xsl:value-of instruction. The principal reason for using xsl:text is that it offers improved control over whitespace handling.

11.4.3 Generating Text with xsl:value-of

Within a sequence constructor, the xsl:value-of instruction can be used to 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 zero-length string, the result of the instruction is an empty sequence. The required select attribute is an expression whose value may be any sequence of nodes or atomic values.

If the sequence is empty, no text node will be created.

Otherwise, the sequence is first atomized, as defined in [XPath 2.0]. The result of atomization is a sequence of atomic values.

If the atomized 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 atomized 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 atomized sequence, 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 effective value of the separator attribute is a zero-length string, then all items in the atomized sequence are processed and the results are concatenated with no separator.

If the separator attribute is absent, then the result depends on whether backwards compatible behavior is enabled for the instruction. If backwards compatible behavior is not enabled, then the instruction is processed as if the separator attribute were present, with its value being a single space character. If backwards compatibility behavior is enabled, then all items in the atomized sequence other than the first are ignored.

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 xsl:copy-of element can be used to copy a sequence of nodes to the result tree without converting to a string. See 11.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 20.2 Disabling Output Escaping

11.5 Creating Processing Instructions

<!-- Category: instruction -->
<xsl:processing-instruction
  name = { ncname }>
  <!-- Content: sequence-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 sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the processing instruction, as described in 5.6.2 Constructing Simple Content.

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">
  <xsl:text>href="book.css" type="text/css"</xsl:text>
</xsl:processing-instruction>

would create the processing instruction

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

[ERR089] It is a dynamic error if the effective value of the name attribute is not both an NCName and a PITarget. This is a recoverable error. 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 20 Serialization).

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

11.6 Creating Namespace Nodes

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

The xsl:namespace element is evaluated to create a namespace node. The content of the xsl:namespace element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the string value of the namespace node (that is, the namespace URI), as described in 5.6.2 Constructing Simple Content.

The xsl:namespace element has a required name attribute that specifies the name of the namespace node (that is, the namespace prefix). The value of the name attribute is interpreted as an attribute value template. If the value of the name attribute is a zero-length string, a namespace node is added for the default namespace.

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 5.6.1 Constructing Complex Content for the position of a namespace node relative to other nodes in the node sequence returned by a sequence constructor.

For example, this

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

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

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

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

[ERR092] It is a dynamic error if evaluating the content of xsl:namespace results in a zero-length string. This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

For details of other error conditions that may arise, see 5.6 Sequence Constructors.

Note:

It is rarely necessary to use xsl:namespace to create a namespace node in the result tree; in most circumstances, the required namespace nodes will be created automatically, as a side-effect of writing elements or attributes that use the namespace. An example where xsl:namespace is needed is a situation where the required namespace is used only within attribute values in the result document, not in element or attribute names; especially where the required namespace prefix or namespace URI is computed at run-time and is not present in either the source document or the stylesheet.

Adding a namespace node to the result tree will never change the expanded-QName of any element or attribute node in the result tree: that is, it will never change the namespace URI of an element or attribute. It may, however, constrain the choice of prefixes when namespace fixup is performed.

Namespace prefixes for element and attribute names are effectively established by the namespace fixup process described in 5.6.3 Namespace Fixup. The fixup process ensures that an element has in-scope namespace nodes for the namespace URIs used in the element name and in its attribute names, and the serializer will typically use these namespace nodes to determine the prefix to use in the serialized output. The fixup process does not take place until the construction of the tree is complete, and it cannot generate namespace nodes that are inconsistent with those already present in the tree. This means that it is not possible for the processor to decide the prefix to use for an element or for any of its attributes until all the namespace nodes for the element have been added. If a namespace prefix is mapped to a particular namespace URI using the xsl:namespace instruction, or by using xsl:copy or xsl:copy-of to copy a namespace node, this prevents the namespace fixup process (and hence the serializer) from using the same prefix for a different namespace URI on the same element.

Note:

The xsl:namespace instruction cannot be used to generate a namespace undeclaration of the form xmlns="" (nor the new forms of namespace undeclaration permitted by XML Namespaces 1.1: see [XML Namespaces 1.1]). Namespace undeclarations are generated automatically by the serializer when a parent element has a namespace node for the default namespace prefix, and a child element has no namespace node for that prefix.

 

The following example shows how to construct the attribute xsi:type="xs:decimal".

<xsl:namespace name="xs">http://www.w3.org/2001/XMLSchema</xsl:namespace>
<xsl:attribute name="xsi:type" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">  
  <xsl:text>xs:decimal</xsl:text>
</xsl:attribute>

The xsl:namespace instruction is needed here to ensure that the xs namespace is declared in the output document. This is not necessary for the xsi namespace, because the namespace fixup mechanism ensures that the namespaces used in element and attribute names are declared automatically.

When the containing element is constructed using a literal result element, an alternative approach would be simply to declare the namespace in the stylesheet as xmlns:xs="http://www.w3.org/2001/XMLSchema". This approach does not work, however, if the containing element is constructed using xsl:element or xsl:copy, or if the required namespace URI is not known statically.

 

11.7 Creating Comments

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

The xsl:comment element is evaluated to contruct a new comment node. The content of the xsl:comment element is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the comment, as described in 5.6.2 Constructing Simple Content.

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

[ERR093] It is a dynamic error if the result of evaluating the content of the xsl:comment contains the string -- or ends with -. This is a recoverable error. 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.

11.8 Copying Nodes from a Source Tree to a Result Tree

11.8.1 Shallow Copy

<!-- Category: instruction -->
<xsl:copy
  copy-namespaces = "yes" | "no"
  use-attribute-sets = qnames
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname>
  <!-- Content: sequence-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. By default, the namespace nodes of the context node are automatically copied as well, but the attributes and children of the node are not automatically copied.

If the context item is an atomic value, the xsl:copy instruction returns this value.

The content of the xsl:copy element is a sequence constructor for the children, attributes, and namespaces of the created node; the sequence constructor is evaluated only for nodes of types that can have children (that is, document nodes and element nodes). The sequence obtained by evaluating this sequence constructor is used to construct the content of the document or element node, as described in 5.6.1 Constructing Complex Content

The xsl:copy element may have a copy-namespaces attribute, with the value yes or no. The default value is yes. The attribute is used only when copying element nodes. If the value is set to yes, or is omitted, then all the namespace nodes of the source element are copied as namespace nodes for the result element. If the value is set to no, then the namespace nodes are not copied. However, namespace nodes will still be added to the result element as required by the namespace fixup process: see 5.6.3 Namespace Fixup.

The xsl:copy element may have a use-attribute-sets attribute (see 10.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 sequence constructor, and return the resulting node sequence as the result of the xsl:copy instruction.

The attributes type and validation may be used on the xsl:copy instruction to check the contents of an element or attribute against a schema definition, and to determine the type annotation that the new copy of an element or attribute node will carry. These attributes are ignored when copying an item that is not an element or attribute node. These attributes also affect the type annotation carried by any elements and attributes that have the copied element or attribute node as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their meanings are described in 19.2 Validation.

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>

[ERR094] 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 11.3 Creating Attribute Nodes using xsl:attribute ). This is a recoverable error. 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 5.6 Sequence 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 or attribute 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="."/>.

Note:

The xsl:copy instruction is most useful when copying element nodes. In other cases, the xsl:copy-of instruction is more flexible, because it has a select attribute allowing selection of the nodes or values to be copied.

Note:

Note that when attribute nodes are copied, whether with xsl:copy or with xsl:copy-of, the processor does not automatically copy any associated namespace information. The namespace used in the attribute name itself will be declared by virtue of the namespace fixup process (see 5.6.3 Namespace Fixup) when the attribute is added to an element in the result tree, but if namespaces are used in the content of the attribute (for example, if the value of the attribute is an XPath expression) then it is the responsibility of the stylesheet author to ensure that suitable namespace declarations are added to the result tree. This can be achieved by copying the namespace nodes using xsl:copy, or by generating them using xsl:namespace.

11.8.2 Deep Copy

<!-- Category: instruction -->
<xsl:copy-of
  select = expression
  copy-namespaces = "yes" | "no"
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname />

The xsl:copy-of instruction can be used to construct a copy of a sequence of nodes and/or atomic values, with each new node containing copies of all the children, attributes, and (by default) namespaces of the original node, recursively. The result of evaluating the instruction is a sequence of items corresponding one-to-one with the supplied 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 atomic values.

The mandatory select attribute contains an expression, whose value may be any sequence of nodes and atomic values. 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 and children of the element node.

    The new element will also have namespace nodes copied from the original element node, unless they are excluded by specifying copy-namespaces="no". If this attribute is omitted, or takes the value yes, then all the namespace nodes of the original element are copied to the new element. If it takes the value no, then none of the namespace nodes are copied: however, namespace nodes will still be created in the result tree as required by the namespace fixup process: see 5.6.3 Namespace Fixup. This attribute affects all elements copied by this instruction: both elements selected directly by the select expression, and elements that are descendants of nodes selected by the select expression.

  • If the item is a document node, the instruction adds a new document node to the result sequence; the children of this document node will be one-to-one copies of the children of the original document node (each copied according to the rules for its own node kind).

  • If the item is an attribute or namespace node, or a text node, a comment, or a processing instruction, the same rules apply as with xsl:copy (see 11.8.1 Shallow Copy).

  • If the item is an atomic value, the value is appended to the result sequence, as with xsl:sequence.

The attributes type and validation may be used on the xsl:copy-of instruction to check the contents of an element or attribute against a schema definition, and to determine the type annotation that the new copy of an element or attribute node will carry. These attributes are applied individually to each element or attribute node that is copied by the instruction; they are ignored when copying an item that is not an element or attribute node. These attributes also affect the type annotation carried by any elements and attributes that have a copied element or attribute node as an ancestor. The specified type, however, applies only to elements and attributes created as copies of nodes actually selected by the select expression, it does not apply to nodes that are implicitly copied because they have such nodes as an ancestor. These two attributes are both optional, and if one is specified then the other must be omitted. The permitted values of these attributes and their meanings are described in 19.2 Validation.

The base URI of a node is copied. However, if the copied node is subsequently attached as a child to a new element, the final copy of the node inherits its base URI from its parent node, unless this is overridden using an xml:base attribute.

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 a zero-length string.

11.9 Constructing Sequences

<!-- Category: instruction -->
<xsl:sequence
  select = expression
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:sequence>

The xsl:sequence instruction may be used within a sequence constructor to construct a sequence of nodes and/or atomic values. This sequence is returned as the result of the instruction. This is the only instruction that can add existing nodes to a sequence, rather than constructing new nodes. When xsl:sequence is used to add atomic values to a sequence, the effect is very similar to the xsl:copy-of instruction.

The items comprising the result sequence may be selected using the select attribute, or constructed using the contained sequence constructor. Any items selected by the select attribute are added to the result sequence before any items constructed using the sequence constructor. If the select attribute is omitted and the sequence constructor is empty, the instruction returns an empty sequence.

The as attribute, if present, defines the required type of the result sequence. The computed value of the result sequence will be converted to this type using the argument conversion rules. [ERR095] If the computed value cannot be converted to the required type, a type error occurs. The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

Note:

The as attribute may be used to restrict the sequence to contain only atomic values, or only nodes, or it may allow a sequence containing both atomic values and nodes.

If no as attribute is specified, the default value is item()*, which permits any value. No conversion then takes place.

For example, the following code:

<xsl:variable name="values" as="xs:integer*">
    <xsl:sequence select="(1,2,3,4)"/>
    <xsl:sequence select="(8,9,10)"/>
</xsl:variable>
<xsl:value-of select="sum($values)"/>

produces the output: 37

 

The following code constructs a sequence containing the value of the @price attribute for selected elements (which we assume to be typed as xs:decimal), or a computed price for those elements that have no @price attribute. It then returns the average price:

<xsl:variable name="prices" as="xs:decimal*">
  <xsl:for-each select="//product">
    <xsl:choose>
      <xsl:when test="@price">
        <xsl:sequence select="@price"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:sequence select="@cost * 1.5"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:for-each>
</xsl:variable>
<xsl:value-of select="avg($prices)"/>

Note that the existing @price attributes could equally have been added to the $prices sequence using xsl:copy-of or xsl:value-of. However, xsl:copy-of would create a copy of the attribute node, which is not needed in this situation, while xsl:value-of would create a new text node, which then has to be converted to an xs:decimal. Using xsl:sequence, which in this case atomizes the existing attribute node and adds an xs:decimal atomic value to the result sequence, is a more direct way of achieving the same result.

This example could alternatively be solved at the XPath level:

<xsl:value-of select="avg(for $p in //product return
             if ($p/@price) then $p/@price else ($p/@cost * 1.5))"/>

12 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. But if the formatted number is a zero-length string, the result of the instruction is an empty sequence.

The xsl:number instruction performs two tasks: firstly, determining a place marker (this is a sequence of integers, to allow for hierarchic numbering schemes such as 1.12.2 or 3(c)ii), and secondly, formatting the place marker for output as a text node in the result sequence. The place marker to be formatted can either be supplied directly, in the value attribute, or it can be computed based on the position of the context node within the tree that contains it.

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 16.4 Number Formatting.

12.1 Formatting a Supplied Number

The place marker to be formatted may be specified by an expression. The value attribute contains the expression. The value of this expression is atomized using the procedure defined in [XPath 2.0], and each value in the atomized sequence is then converted to an integer by first applying the XPath number and round functions, and then casting the result to an integer. The resulting sequence of integers is used as the place marker to be formatted.

If backwards compatible behavior is enabled for the instruction, then all items in the atomized sequence after the first are discarded.

[ERR096] It is a dynamic error if any undiscarded item in the sequence cannot be converted to an integer, or if the resulting integer is less than 1 (one). This is a recoverable error. The processor must either signal the error, or must recover by converting that item 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.

The resulting sequence is formatted as a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the xsl:number element constructs a new text node containing the resulting string, and returns this node.

The following example numbers a sorted list:

<xsl:template match="items">
  <xsl:for-each select="item">
    <xsl:sort select="."/>
    <p>
      <xsl:number value="position()" format="1. "/>
      <xsl:value-of select="."/>
    </p>
  </xsl:for-each>
</xsl:template>

12.2 Numbering based on Position in a Document

If no value attribute is specified, then the xsl:number instruction returns a new text node containing a formatted place marker that is based on the position of the context node within its containing document.

[ERR097] It is a dynamic error if the xsl:number instruction is evaluated, with no value attribute, when the context item is not a node. This is a recoverable error. 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:

  • The level attribute specifies rules for selecting the nodes that are taken into account in allocating a number; it has the values single, multiple or any. The default is single.

  • The count attribute is a pattern that specifies which nodes are to be counted at those levels. If count attribute is not specified, then it defaults to the pattern that matches any node with the same node kind as the context node and, if the context node has an expanded-QName, with the same expanded-QName as the context node.

  • The from attribute is a pattern that specifies where counting starts.

In addition, the attributes specified in 12.3 Number to String Conversion Attributes are used for number to string conversion, as in the case when the value attribute is specified.

The xsl:number element first constructs a sequence of positive integers using the level, count and from attributes. Where level is single or any, this sequence will either be empty or contain a single number; where level is multiple, the sequence may be of any length. The sequence is constructed as follows:

Let matches-count($node) be a function that returns true if the given node $node matches the pattern given in the count attribute, or the implied pattern (according to the rules given above) if the count attribute is omitted.

Let matches-from($node) be a function that returns true if the given node $node matches the pattern given in the from attribute, or if $node is the root node of a tree. If the from attribute is omitted, then the function returns true if and only if $node is the root node of a tree.

When level="single":

  • Let $A be the node sequence selected by the following expression (this selects the innermost ancestor-or-self node that matches the count pattern):

       ancestor-or-self::node()[matches-count(.)][1]

  • Let $F be the node sequence selected by the expression

       ancestor-or-self::node()[matches-from(.)][1]

  • Let $AF be the value of

       $A intersect ($F/descendant-or-self::node())

  • If $AF is empty, return the empty sequence, ()

  • Otherwise return the value of

       1 + count($AF/preceding-sibling::node()[matches-count(.)])

When level="multiple":

  • Let $A be the node sequence selected by the expression

       ancestor-or-self::node()[matches-count(.)]

  • Let $F be the node sequence selected by the expression

       ancestor-or-self::node()[matches-from(.)][1]

  • Let $AF be the value of

       $A intersect ($F/descendant-or-self::node())

  • Return the result of the expression

       for $af in $AF return 1+count($af/preceding-sibling::node()[matches-count(.)])

When level="any":

  • If the context node is a document node, return the empty sequence, ()

  • Let $A be the node sequence selected by the expression

       (preceding::node()|ancestor-or-self::node())[matches-count(.)]

  • Let $F be the node sequence selected by the expression

       (preceding::node()|ancestor-or-self::node())[matches-from(.)][last()]

  • Let $AF be the node sequence $A[. is $F or . >> $F].

  • If $AF is empty, return the empty sequence, ()

  • Otherwise return the value of the expression count($AF)

The sequence of numbers (the place marker) is then converted into a string using the effective values of the attributes specified in 12.3 Number to String Conversion Attributes; each of these attributes is interpreted as an attribute value template. After conversion, the resulting string is 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>

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

  • Any token where the last character has a decimal digit value of 1 (as specified in the Unicode character property database), and the Unicode value of preceding characters is one less than the Unicode value of the last character generates a decimal representation of the number where each number is at least as long as the format token. Thus, a format token 1 generates the sequence 1 2 ... 10 11 12 ..., and a format token 01 generates the sequence 01 02 ... 09 10 11 12 ... 99 100 101.

  • A format token A generates the sequence A B C ... Z AA AB AC....

  • A format token a generates the sequence a b c ... z aa ab ac....

  • A format token i generates the sequence i ii iii iv v vi vii viii ix x ....

  • A format token I generates the sequence I II III IV V VI VII VIII IX X ....

  • Any other format token indicates a numbering sequence that starts with that token. It is implementation-defined which numbering sequences, additional to those listed above, are supported. If an implementation does not support a numbering sequence that starts with the given token, it must use a format token of 1.

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; indeed, for some numbering sequences there may be an intrinsic limit. For the numbering sequences described above, the 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 1.0]; 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, variations are possible in the way conversions are performed for any particular language. Implementations may use implementation-defined namespaced attributes on xsl:number to provide additional control.

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:

  • format="&#x30A2;" specifies Katakana numbering

  • format="&#x30A4;" specifies Katakana numbering in the "iroha" order

  • format="&#x0E51;" specifies numbering with Thai digits

  • format="&#x05D0;" letter-value="traditional" specifies "traditional" Hebrew numbering

  • format="&#x10D0;" letter-value="traditional" specifies Georgian numbering

  • format="&#x03B1;" letter-value="traditional" specifies "classical" Greek numbering

  • format="&#x0430;" letter-value="traditional" specifies Old Slavic numbering

The following examples show some non-Western numbering sequences.

Example: Katakana Numbering:

format="&#x30A2;"

ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ, ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ, ワ, ヰ, ヱ, ヲ, ン

 

Example: Katakana Numbering in "iroha" order:

format="&#x30A4;"

イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ, ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ, ヒ, モ, セ, ス

 

Example: Thai Numbering:

format="&#x0E51;"

๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘, ๑๙, ๒๐

 

Example: Hebrew numbering, "traditional":

format="&#x05D0;" letter-value="traditional"

א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח, יט, כ

 

Example: Georgian numbering, "traditional":

format="&#x10D0" letter-value="traditional"

ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ, ით, კ

 

Example: Greek numbering, "classical":

format="&#x03B1" letter-value="traditional"

αʹ, βʹ, γʹ, δʹ, εʹ, ϛʹ, ζʹ, ηʹ, θʹ, ιʹ, ιαʹ, ιβʹ, ιγʹ, ιδʹ, ιεʹ, ιϛʹ, ιζʹ, ιηʹ, ιθʹ, κʹ

 

Example: Old Slavic numbering:

format="&#x0410"

А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ, ѲӀ, К

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

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

13.1 Collating Sequences

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 is to be sorted before the other. A collation is identified by a URI, but the manner in which this URI is associated with an actual rule or algorithm is implementation-defined.

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.

Note:

Useful background information on international sorting is provided in [UNICODE TR10].

13.2 The xsl:sort Element

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

Those attributes of the xsl:sort elements whose values are attribute value templates are evaluated using the outer focus, which is defined as follows:

  • 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 document containing the initial context node; a dynamic error occurs if an expression if such an attribute value template references the context node, context position, or context size when no initial context node is supplied.

  • 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 an atomic 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 an as attribute, then the sort key is converted to the required type before comparing it with other items, using the argument conversion rules.

[ERR099] The target type for each xsl:sort element is determined by the effective value of its as attribute. This must be the name of an atomic data type that is available in the static context: that is, either the name of a built-in atomic type defined in [XML Schema], or the name of a type derived from such a type by restriction, defined in an imported schema. It is a dynamic error if any other value is supplied. This is a recoverable error. The processor must either signal the error, or must recover by continuing as if the as attribute were not specified.

The values of the sort keys are atomized, and are then compared. The way they are compared depends on their data type.

It is possible to force the system to compare sort keys using the rules for a particular data type by including a cast as part of the sort key. For example, <xsl:sort select="xs:date(@dob)"/> will force the attributes to be compared as dates. In the absence of such a cast, the sort keys are compared using the rules appropriate to their data type. For this purpose the empty sequence is considered to be comparable to all other values: it is considered equal to itself, and less than any other value.

For backwards compatibility with XSLT 1.0, the data-type attribute remains available. If this has the effective value text, the sort keys are converted to strings before being compared. If it has the effective value number, the sort keys are converted to doubles before being compared. The conversion is done by using the string or number function as appropriate. If the data-type attribute has any other effective value, then the value must be a prefixed QName, and the effect of the attribute is implementation-defined.

[ERR100] If the value of any sort key, after atomization and any type conversion required by the data-type attribute, is a sequence containing more than one item, then the effect depends on whether the xsl:sort element is evaluated with backwards compatible behavior. With backwards compatible behavior, the effective value of the sort key is the first item in the sequence. In other cases, this is a type error. The processor must signal the error.

If the as and data-type attributes are both present, the data-type attribute is ignored. The implementation may check that its value is valid, but is not required to do so.

Each sort key (unless it is the empty sequence: see below) is converted to the target type using the rules described above. [ERR101] It is a dynamic error if any value (other than the empty sequence) obtained by evaluating the select attribute of an xsl:sort element cannot be converted to the target type. This is a recoverable error. The processor must either signal the error, or must recover by treating the value as an exception value.

The values of the sort keys (after any conversion) are first divided into three categories: empty values, NaN values, and ordinary values. The empty values represent those items where the sort key evaluates to an empty sequence. These values are considered for sorting purposes to be equal to each other, but less than any other value. The exception values represent those items where the sort key cannot be converted to the target data type, together with the xs:double and xs:float value NaN. NaN values are considered for sorting purposes to be equal to each other, greater than any empty value, but less than any ordinary value. The remaining values are classified as ordinary values.

In general, comparison of two ordinary values is performed according to the rules of the XPath lt operator. However, special rules apply to the xs:string type and types derived by restriction from xs:string, as described below.

[ERR102] 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 ordinary values for which the result of the XPath lt operator is an error. This is a recoverable error. The processor must either signal the error, or must recover by assigning an arbitrary ordering to any such pair of values.

If there is no as or data-type attribute, then the computed sort keys are not converted before comparison, except in the case where the 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.

[ERR103] It is a dynamic error if the effective value of the as attribute of the xsl:sort element is a type for which no ordering relation is defined, other than the value xs:string. This is a recoverable error. The processor must signal the error, or must recover by continuing as if the as 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 compare($a, $b, $collation).

Note:

XSLT provides no facilities to declare or define collations: such mechanisms are expected to be provided by implementors. Equally, this specification does not define what happens if the collation name is not recognized: the implementation may signal an error, or it may use the default 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:

  • The lang attribute indicates that a collation suitable for a particular natural language is required. The effective value of the attribute must be a value that would be valid for the xml:lang attribute (see [XML 1.0]).

  • The case-order attribute indicates whether the desired collation should sort upper-case letters before lower-case or vice versa. The effective value of the attribute must be either lower-first (indicating that lower-case letters precede upper-case letters in the collating sequence) or upper-first (indicating that upper-case letters precede lower-case).

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

13.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 is to 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 are to be processed. For the effect of xsl:for-each-group, see 14 Grouping

13.4 Using Named Sort Specifications

13.4.1 Declaring a Named Sort Specification

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

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 5.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. [ERR104] 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.

13.4.2 Sorting Using a Named Sort Specification

sort($input-sequence as item()*, $sort-spec-name as xs:string) as item()*
Ed. Note:Note that the order of the arguments is reversed since the previous working draft

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 $sort-spec-name 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. [ERR105] It is a dynamic error if the $sort-spec-name argument of the sort function is not a valid QName, or if its prefix is not declared in an in-scope namespace declaration, or if it does not match the name of any named sort specification in the stylesheet. The processor must signal the error. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

The value of the $input-sequence argument 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.

 

The following example uses the sort function to output the book that has the lowest price:

<xsl:sort-key name="book-price">
   <xsl:sort select="xs:decimal(price)"/>
</xsl:sort-key>
   ...
   <xsl:copy-of select="sort(//book, 'book-price')[1]"/>

 
 

14 Grouping

The facilities described in this section are designed to allow nodes in a document to be grouped 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 sequence constructor for the group. Grouping is nestable to multiple levels so that groups of distinct items can be identified, then from among the distinct groups selected, further sub-grouping of distinct items in the current group can be done.

It is also possible for one item to participate in more than one group.

14.1 The Current Group

current-group() as item()*

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.

[ERR106] It is a static error if the current-group function is used within a pattern.

14.2 The Current Grouping Key

current-grouping-key() as xdt:anyAtomicType

The evaluation context for XPath expressions includes an additional value called the current grouping key, which is an atomic value. The current grouping key is a value shared in common by all the items within the current group.

While an xsl:for-each-group instruction with a group-by or group-adjacent attribute is being evaluated, the current grouping key will be non-empty. At other times, it will be an empty sequence.

The function current-grouping-key returns the current grouping key.

The function takes no arguments.

[ERR107] It is a static error if the current-grouping-key function is used within a pattern.

14.3 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
  collation = { uri }>
  <!-- Content: (xsl:sort*, sequence-constructor) -->
</xsl:for-each-group>

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

The xsl:for-each-group instruction allocates the items in an input sequence into groups of items (that is, it establishes a collection of sequences) based either on common values of a grouping key, or on a pattern that the initial node in a group must match. The sequence constructor that forms the content of the xsl:for-each-group instruction is evaluated once for each of these groups. 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 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, group-starting-with, and group-ending-with attributes. [ERR108] These four attributes are mutually exclusive: it is a static error if none of these four attributes is present, or if more than one of them is present.

[ERR109] The as attribute, if specified, must be the name of an atomic type (either a built-in type, or a type defined in an imported schema).

[ERR110] It is an error to specify the as attribute or the collation attribute if neither the group-by attribute nor group-adjacent attribute is specified.

If either of the group-by attribute or group-adjacent attributes is present, then grouping keys are calculated for each item in the population. The expression contained in the group-by or group-adjacent attribute is evaluated with that item as the context item, with its position in population order as the context position, and with the size of the population as the context size. The resulting sequence is atomized, and each atomic value in the atomized sequence acts as a grouping key for that item in the population.

If the group-by attribute is present, then an item in the population may have multiple grouping keys: that is, the group-by expression evaluates to a sequence. The item is included in as many groups as there are distinct grouping keys (which may be zero). If the group-adjacent attribute is used, then each item in the population must have exactly one grouping key value.

[ERR111] It is a type error if the result of the group-adjacent attribute is an empty sequence, or a sequence containing more than one item. The processor must signal the error.

[ERR112] It is a type error if the set of grouping keys obtained by evaluating the group-by or group-adjacent attributes for all items in the population contains two items that are not comparable using the eq operator. The processor must signal the error.

If the as attribute is present, the result of evaluating the group-by expression is converted to the specified type using the argument conversion rules; otherwise, it is converted as if the as attribute were xs:string. The resulting value is known as the grouping key for that item.

[ERR113] It is a type error if the result of evaluating the group-by or group-adjacent attribute, for any item in the population, cannot be converted to the required type using the argument conversion rules. This includes the case where the result is an empty sequence, or a sequence containing more than one item. The processor must signal the error.

Grouping keys are compared using the rules for the eq operator appropriate to their dynamic type. If the values are strings, or untyped atomic values, they are compared using the collation specified in the collation attribute if present, or the default collation otherwise. For the purposes of grouping, the value NaN is considered equal to itself.

  • If the group-by attribute is present, then all items that have the same grouping key are assigned to the same group, and the number of groups is the same as the number of distinct grouping key values present in the population. An item in the population may thus be assigned to zero, one, or many groups. An item will never by assigned more than once to the same group; if two or more grouping keys for the same item are equal, then the duplicates are ignored.

  • If the group-adjacent attribute is present, the items in the population are examined, in population order. If an item has the same value for the grouping key as its preceding item within the population (in population order), then it is assigned to the same group as its preceding item; otherwise a new group is created and the item becomes its first member.

  • If the group-starting-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes. [ERR114] It is a dynamic error if the result of evaluating the select expression contains an item that is not a node. The processor must signal the error.

    The nodes in the population are examined in population order. If a node matches the pattern, or is the first node in the population, then a new group is created and the node becomes its first member. Otherwise, the node is assigned to the same group as its preceding node within the population.

  • If the group-ending-with attribute is present, then its value must be a pattern. In this case, the items in the population must all be nodes. [ERR115] It is a dynamic error if the result of evaluating the select expression contains an item that is not a node. The processor must signal the error.

    The nodes in the population are examined in population order. If a node is the first node in the population, or if the previous node in the population matches the pattern, then a new group is created and the node becomes its first member. Otherwise, the node is assigned to the same group as its preceding node within the population.

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. If two groups G and H have the same initial item (because the item is in both groups) then G precedes H if the grouping key of G precedes the grouping key of H in the sequence that results from evaluating the group-by expression of this initial item.

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 13 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, the current group is the group whose sort key is being determined, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence.

This means that if the grouping key is "@category", you can sort the groups in order of their grouping key by writing <xsl:sort select="current-grouping-key()"/>; or you can sort the groups in order of size by writing <xsl:sort select="count(current-group())" as="xs:integer"/>

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 sequence constructor contained in 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 sequence 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, the current group is the group being processed, and the current grouping key is the grouping key for that group. If the xsl:for-each-group instruction uses the group-starting-with or group-ending-with attributes, then the current grouping key is the empty sequence. This has the effect that within the the sequence 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 and current grouping key revert to their previous value.

14.4 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="current-grouping-key()"/>
      <h2>
        <xsl:value-of select="upper-case(current-grouping-key())"/>
        <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>
 

Sometimes it is necessary to use a composite grouping key: for example, suppose the source document is similar to the one used in the previous examples, but allows multiple entries for the same country and city, such as:

<cities>
  <city name="Milano"  country="Italia"  year="1950"   pop="5.23"/>
  <city name="Milano"  country="Italia"  year="1960"   pop="5.29"/>  
  <city name="Paris"   country="France"  year="1951"   pop="7.2"/>
  <city name="Paris"   country="France"  year="1961"   pop="7.6"/>
</cities>

Now suppose we want to list the average value of @pop for each (country, name) combination. One way to handle this is to concatenate the parts of the key, for example <xsl:for-each-group select="concat(@country, '/', @name)">. A more flexible solution is to nest one xsl:for-each-group element directly inside another:

<xsl:for-each-group select="cities/city" group-by="@country">
  <xsl:for-each-group select="current-group()" group-by="@name">
    <p><xsl:value-of select="@name"/>, <xsl:value-of select="@country"/>:
        <xsl:value-of select="avg(current-group()/@pop)"/></p>
  </xsl:for-each-group>
</xsl:for-each-group>
 

 

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

 

The next example illustrates how a group of related elements can be identified by the last element in the group, rather than the first. Here the absence of the attribute continued="yes" indicates the end of the group.

Source XML document:

<doc>
  <page continued="yes">Some text</page>
  <page continued="yes">More text</page>    
  <page>Yet more text</page>
  <page continued="yes">Some words</page>
  <page continued="yes">More words</page>    
  <page>Yet more words</page>        
</doc>

Desired output:

<doc>
  <pageset>
    <page>Some text</page>
    <page>More text</page>    
    <page>Yet more text</page>
  </pageset>
  <pageset>
    <page>Some words</page>
    <page>More words</page>    
    <page>Yet more words</page>
  </pageset>
</doc>

Solution:

<xsl:template match="doc">
<doc>
  <xsl:for-each-group select="*" 
                      group-ending-with="page[not(@continued='yes')]">
    <pageset>
      <xsl:for-each select="current-group()">
        <page><xsl:value-of select="."/></page>
      </xsl:for-each> 
    </pageset>
  </xsl:for-each-group>
</doc>
</xsl:template>
 

The next example shows how an item can be added to multiple groups. Book titles will be added to one group for each indexing term marked up within the title.

Source XML document:

<titles>
    <title>A Beginner's Guide to <ix>Java</ix></title>
    <title>Learning <ix>XML</ix></title>
    <title>Using <ix>XML</ix> with <ix>Java</ix></title>
</titles>

Desired output:

<h2>Java</h2>
    <p>A Beginner's Guide to Java</p>
    <p>Using XML with Java</p>
<h2>XML</h2>
    <p>Learning XML</p>
    <p>Using XML with Java</p>

Solution:

<xsl:template match="p">
    <xsl:for-each-group select="title" group-by="ix">
      <h2><xsl:value-of select="current-grouping-key()"/></h2>
      <xsl:for-each select="current-group()">
        <xsl:value-of select="."/>
      </xsl:for-each>
    </xsl:for-each-group>
</xsl:template>
 

 

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>

15 Regular Expressions

The core function library for XPath 2.0 defines three functions that make use of regular expressions:

These functions are described in [Functions and Operators].

For more complex string processing than is possible using these functions, XSLT provides an instruction xsl:analyze-string, which is defined in this section.

The regular expressions used by this instruction, and the flags that control the interpretation of these regular expressions, must conform to the syntax defined in [Functions and Operators], which is itself based on the syntax defined in [XML Schema].

<!-- Category: instruction -->
<xsl:analyze-string
  select = expression
  regex = { string }
  flags = { string }>
  <!-- Content: (xsl:matching-substring?, xsl:non-matching-substring?, xsl:fallback*) -->
</xsl:analyze-string>

<xsl:matching-substring>
  <!-- Content: sequence-constructor -->
</xsl:matching-substring>

<xsl:non-matching-substring>
  <!-- Content: sequence-constructor -->
</xsl:non-matching-substring>

The xsl:analyze-string instruction takes as input a string (the value of the select attribute) and a regular expression (the effective value of the regex attribute).

The flags attribute may be used to control the interpretation of the regular expression. If the attribute is omitted, the effect is the same as supplying a zero-length string . This is interpreted in the same way as the $flags attribute of the functions matches, replace, and tokenize. Specifically, if it contains the letter m, the match operates in multiline mode, otherwise it operates in string mode. If it contains the letter i, it operates in case-insensitive mode, otherwise it operates in case-sensitive mode. For more detailed specifications of these modes, see [Functions and Operators].

Note:

Because the regex attribute is an attribute value template, curly braces within the regular expression must be doubled. For example, to match a sequence of one to five characters followed by whitespace, write regex=".{{1,5}}\s".

The xsl:analyze-string instruction may have two child elements: xsl:matching-substring and xsl:non-matching-substring. Both elements are optional, and neither may appear more than once.

The xsl:analyze-string instruction may also have zero or more xsl:fallback child elements. These are ignored by an XSLT 2.0 processor, but allow fallback behavior to be defined when the stylesheet is used with an XSLT 1.0 processor operating in forwards-compatible mode.

This instruction is designed to process all the non-overlapping substrings of the input string that match the regular expression supplied.

[ERR116] It is a dynamic error if the effective value of the regex attribute does not conform to the required syntax for regular expressions, as specified in [Functions and Operators], or if the effective value of the flags attribute has a value other than the values defined in [Functions and Operators]. The processor must signal the error. If the regular expression and/or flags are known statically (for example, if the attributes do not contain any expressions enclosed in curly braces) then the processor may signal the error as a static error.

[ERR117] It is a dynamic error if the effective value of the regex attribute is a regular expression that matches a zero-length string . The processor must signal the error. If the regular expression is known statically (for example, if the attribute does not contain any expressions enclosed in curly braces) then the processor may signal the error as a static error.

The xsl:analyze-string instruction starts at the beginning of the input string and attempts to find the first substring that matches the regular expression. If there are several matches, the first match is defined to be the one whose starting position comes first in the string. Having found the first match, the instruction proceeds to find the second and subsequent matches by repeating the search, starting at the first character that was not included in the previous match.

The input string is thus partitioned into a sequence of substrings, some of which match the regular expression, others which do not match it. Each substring will contain at least one character. This sequence of substrings is processed using the xsl:matching-substring and xsl:non-matching-substring child instructions. A matching substring is processed using the xsl:matching-substring element, a non-matching substring using the xsl:non-matching-substring element. Each of these elements takes a sequence constructor as its content. If the element is absent, the effect is the same as if it were present with empty content. In processing each substring, the contents of the substring will be the context item (as a value of type xs:string); the position of the substring within the sequence of matching and non-matching substrings will be the context position; and the number of matching and non-matching substrings will be the context size.

If the input is a zero-length string, the number of substrings will be zero, so neither the xsl:matching-substring nor xsl:non-matching-substring elements will be evaluated.

regex-group($group-number as integer) as string

While the xsl:matching-substring instruction is active, a set of captured substrings is available, corresponding to the parenthized sub-expressions of the regular expression. These captured substrings are accessible using the function regex-group. This function takes an integer argument to identify the group, and returns a string representing the captured substring. In the absence of a captured substring with the relevant number, it returns the zero-length string .

Note:

The function also returns a zero-length string in the case of a group that matched a zero-length string , and in the case of a group that exists in the regular expression but did not match any part of the input string.

While no xsl:matching-substring instruction is active the regex-group returns an empty sequence. The function also returns an empty sequence if an xsl:non-matching-substring instruction has been activated more recently than an xsl:matching-substring instruction.

15.1 Examples of Regular Expression Matching

Problem: replace all newline characters in the <abstract> by <br/> elements:

Solution:

<xsl:analyze-string select="abstract" regex="\n">
  <xsl:non-matching-substring>
    <xsl:value-of select="."/>
  </xsl:non-matching-substring>
  <xsl:matching-substring>
    <br/>
  </xsl:matching-substring>
</xsl:analyze-string>

 

Problem: replace all occurrences of "[...]" in the <body> by <cite>...</cite> elements:

Solution:

<xsl:analyze-string select="body" regex="\[(.*?)\]">
  <xsl:matching-substring>
    <cite><xsl:value-of select="regex-group(1)"/></cite>
  </xsl:matching-substring>
  <xsl:non-matching-substring>
    <xsl:value-of select="."/>
  </xsl:non-matching-substring>
</xsl:analyze-string>

 

Problem: the input string contains a date such as "23 March 2002". Convert it to the form 2002-03-23.

Solution (with no error handling if the input format is incorrect):

<xsl:variable name="months" select="('January', 'February', 'March', ...)"/>

<xsl:analyze-string select="$input" regex="\s*([0-9]+)\s+([A-Z][a-z]+)\s+([0-9]+)\s*">
    <xsl:matching-substring>
        <xsl:number value="regex-group(3)" format="0001"/>          
        <xsl:text>-</xsl:text>
        <xsl:number value="index-of($months, regex-group(2))" format="01"/>
        <xsl:text>-</xsl:text>
        <xsl:number value="regex-group(1)" format="01"/>
    </xsl:matching-substring>
</xsl:analyze-string>

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

16.1 Multiple Source Documents

Note:

The document function in XSLT 1.0 was an additional function defined in the XSLT specification. In earlier drafts of the XSLT 2.0 specification, this function became a core function defined in the [Functions and Operators], allowing it to be used in contexts other than XSLT. It has now been replaced in the core function library by the much simpler doc function. The original document function therefore moves back into the XSLT specification, to provide backwards compatibility, and also to provide the one feature that is not available through the doc function, namely support for fragment identifiers in a URL.

document($uri-sequence as item()*) as node()*

document($uri-sequence as item()*, $base-node as node()) as node()*

The document function allows access to XML documents identified by a URI.

The first argument contains a sequence of URI references. The second argument, if present, is a node whose base URI is used to resolve any relative URI references contained in the first argument.

A sequence of absolute URI references is obtained as follows.

  • For an item in $uri-sequence that is an instance of xs:string, xs:anyURI, or xs:untypedAtomic, the value is cast to xs:anyURI. If the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved against the base URI of $base-node if supplied, or against the base URI from the static context otherwise (this will usually be the base URI of the stylesheet module).

  • For an item in $uri-sequence that is a node, the node is atomized. The result must be a sequence whose items are all instances of xs:string, xs:anyURI, or xs:untypedAtomic. Each of these values is cast to xs:anyURI, and if the resulting URI reference is an absolute URI reference then it is used as is. If it is a relative URI reference, then it is resolved against the base URI of $base-node if supplied, or against the base URI of the node that contained it otherwise.

Note:

The XPath rules for function calling ensure that it is a type error if the supplied value of the second argument is anything other than a single node. If XPath 1.0 backwards compatibility mode is enabled, then a sequence of nodes may be supplied, and the first node in the sequence will be used.

Each of these absolute URI references is then processed as follows. Any fragment identifier that is present in the URI reference is removed, and the resulting absolute URI is passed to the doc function defined in [Functions and Operators]. This returns a document node. If an error occurs during evaluation of the doc function, the processor may either signal this error in the normal way, or may recover by ignoring the failure, in which case the failing URI will not contribute any nodes to the result of the function.

If the URI reference contained no fragment identifier, then this document node is included in the sequence of nodes returned by the document function.

If the URI reference contained a fragment identifier, then the fragment identifier is interpreted according to the rules for the media type of the resource identified by the URI, and is used to select zero or more nodes that are descendant-or-self nodes of the returned document node. [ERR118] When a URI reference contains a fragment identifier, it is a dynamic error if the media type is not one that is recognized by the processor, or if the fragment identifier does not conform to the rules for fragment identifiers for that media type, or if the fragment identifier selects something other than a sequence of nodes (for example, if it selects a range of characters within a text node). This is a recoverable error. The processor may signal the error, or may recover by ignoring the fragment identifier and returning the document node. The set of media types recognized by a processor is implementation-defined.

Note:

The recovery action here is different from XSLT 1.0

The sequence of nodes returned by the function is in document order, with no duplicates. This order has no necessary relationship to the order in which URIs were supplied in the $uri-sequence argument.

Note:

The effect of these rules is that unless XML entities or xml:base are used, document("") refers to the document node of the containing stylesheet module. The XML resource containing the stylesheet module is processed exactly as if it were any other XML document, for example there is no special recognition of xsl:text elements, and no special treatment of comments and processing instructions.

16.2 Reading Text Files

unparsed-text($href as string?) as string

unparsed-text($href as string?, $encoding as xs:string) as string

The unparsed-text function reads an external resource (for example, a file) and returns its contents as a string.

The $href argumentis treated as a sequence. Each item in the sequence, must be a string in the form of 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 it is resolved relative the the base URI from the static context.

Note:

If a different base URI is appropriate (for example, when resolving a relative URI read from a source document) then the relative URI should be resolved using the resolve-uri function before passing it to the unparsed-text function.

The $encoding 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.

The encoding of the external resource is determined as follows:

  1. external encoding information, if available, otherwise

  2. if the media type of the resource is text/xml, application/xml, or matches the conventions text/*+xml or application/*+xml as described in [RFC3023], the encoding is recognized as specified in [XML 1.0], otherwise

  3. the value of the $encoding argument if present, otherwise

  4. UTF-8.

Note:

The above rules are chosen for consistency with [XInclude]. Files with an XML media type are treated specially because there are use cases for this function where the retrieved text is to be included as unparsed XML within a CDATA section of a containing document, and because processors are likely to be able to reuse the code that performs encoding detection for XML external entities.

[ERR119] It is a dynamic error if a URI cannot be used to retrieve a resource containing text. This is a recoverable error. 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.

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

[ERR121] It is a dynamic error if a resource contains octets that cannot be decoded into permitted 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.

[ERR122] 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 20.2 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>

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

16.3.1 The xsl:key Declaration

<!-- Category: declaration -->
<xsl:key
  name = qname
  match = pattern
  use = expression
  as = 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 5.1 Qualified Names. The match attribute is a Pattern; an xsl:key element applies to all nodes that match the pattern specified in the match attribute. 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 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 as attribute defines the required type of each item within the sequence that forms 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 xs:string, which means that the result of evaluating the expression is treated as a sequence of strings, by invoking the atomization procedure defined in [XPath 2.0]. In general, the result of evaluating the use expression is converted to the required type, by invoking the argument conversion rules. The 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. with an optional occurrence indicator.

The collation attribute is used only when the item type of the required type is xs:string or a type derived by restriction from xs:string, and it identifies a collation, which 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 compare($a, $b, $collation) is zero. In the absence of a collation attribute, the default collation is used.

It is possible to have:

  • multiple xsl:key declarations with the same name;

  • a node that matches the match patterns of several different xsl:key declarations, whether these have the same key name or different key names;

  • a node that returns more than one value from its use expression;

  • a key value that identifies more than one node (the key values for different nodes do not need to be unique).

A key is defined as a set of xsl:key declarations in the stylesheet that share the same name.

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.

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

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

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

[ERR126] It is a static error if a value is specified for the collation attribute unless the as attribute is defaulted or set to xs:string.

[ERR127] 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 type specified by the as attribute. This is a recoverable error. The processor may signal the error, or may recover by ignoring the existence of the value that cannot be converted.

16.3.2 The key Function

key($key-name as xs:string, $key-value as xdt:anyAtomicType*) as node*

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

The $key-name argument specifies the name of the key. The value of the argument must be a QName, which is expanded as described in 5.1 Qualified Names. [ERR128] 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 xsl:key declaration in the stylesheet. The processor must signal these errors. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

The $key-value argument to the key function is considered as a sequence. The set of requested key values is formed by atomizing the supplied value of the argument, using the standard function calling rules. Each of the resulting atomic values is considered as a requested key value. The result of the function is a sequence of nodes, in document order and with duplicates removed, comprising those nodes in the same document as the context node 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 appropriate to the as and collation attributes of the key declaration.

If the second argument is an empty sequence, the result of the function will be an empty sequence.

More formally, if the result of evaluating the $key-value 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 key-equal($k, $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, USE is the expression given in its use attribute, and TYPE is the expression given in its as attribute, or xs:string if the attribute is omitted. The values of the match and use and as attributes are textually substituted into the above expression.

In the above expression, the internal function key-equal is defined as follows:

  • If TYPE is xs:string or a type derived from xs:string by restriction, then key-equal($k, $v) is true if and only if compare($k, $v, 'COLLATION') eq 0, where COLLATION is the collation specified in the collation attribute of the key declaration if present, or the default collation otherwise.

  • If TYPE is xs:float or xs:double, or a type derived from xs:float or xs:double by restriction, then key-equal($k, $v) is true if $k eq $v or if xf:string($k) eq 'NaN' and xf:string($v) eq 'NaN'; otherwise if is false. That is, the values match if they are equal, or if both are NaN.

  • Otherwise key-equal($k, $v) is true if and only if $k eq $v.

Note:

The reason that /self::node() appears in the above expression 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.

More specifically, the result of the key function is a sequence containing every node N that satisfies the following conditions:

  • N must be in the same document as the context node.

  • N must match the pattern specified in the match attribute of a key definition whose name is the same as the name specified in the $key-name argument.

  • When the expression specified in the use attribute of that key definition is evaluated with a singleton focus based on N, the atomized value of the resulting sequence must include a value that compares equal to at least one item in the atomized value of the sequence supplied as $key-value.

Before comparing two values, both values are converted to the type specified in the as attribute of the xsl:key declaration, using the argument conversion rules. If the attribute is omitted, they are converted to xs:string using the rules of the string function. It is a dynamic error if either conversion fails.

Two items compare equal if they are equal under the rules of the eq operator. If a collation is specified in the collation attribute of the xsl:key declaration, this collation is used for comparing strings; otherwise the default collation is used.

Two items also compare equal, for the purposes of this function, if they are both NaN (not-a-number).

If the current function is used in either the match pattern or the use expression of the key declaration, its value is the node N that is being considered for inclusion in the result.

The sequence returned by the key function will be in document order, with duplicates removed.

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 same document as the context node; to retrieve a node from any other document, it is necessary first to change the context node.

For example, suppose a document contains bibliographic references in the form <bibref>XSLT</bibref>, and there is a separate XML document bib.xml containing a bibliographic database with entries in the form:

<entry name="XSLT">...</entry>

Then the stylesheet could use the following to transform the bibref elements:

<xsl:key name="bib" match="entry" use="@name"/>

<xsl:template match="bibref">
  <xsl:variable name="name" select="."/>
  <xsl:apply-templates select="document('bib.xml')/key('bib',$name)"/>
</xsl:template>
Note:

This relies on the ability in XPath 2.0 to have a function call on the right-hand side of the / operator in a path expression.

[ERR129] It is a dynamic error to call the key function if there is no context node, or if the root of the tree containing the context node is not a document node. The processor must signal the error.

16.4 Number Formatting

format-number($value as xs:double, $picture as xs:string) as xs:string

format-number($value as xs:double,
$picture as xs:string,
$decimal-format-name as xs:string) as xs:string

The format-number function formats $value as a string using the picture string specified by the $picture argument and the decimal-format named by the $decimal-format-name argument, or the default decimal-format, if there is no $decimal-format-name argument. The value of $decimal-format-name must be a QName, which is expanded as described in 5.1 Qualified Names. The result of the function is the formatted string representation of the supplied number.

[ERR130] It is a dynamic error if the name specified as the $decimal-format-name argument is not a valid QName, or if its prefix has not been declared in an in-scope namespace declaration, or if the stylesheet does not contain a declaration of a decimal-format with a matching expanded-QName . This is a recoverable error. The processor must either signal the error, or must recover by ignoring the $decimal-format-name argument. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

16.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 5.1 Qualified Names. [ERR131] 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 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 defines the Unicode character that is used to represent each of the values 0 to 9 in the final result string: Unicode is organized so that each set of decimal digits forms a contiguous block of characters in numerical sequence. 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.

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

16.4.2 Processing the Picture String

The formatting of a number is controlled by a picture string. The picture string is a sequence of characters, in which the characters assigned to the variables decimal-separator-sign, grouping-sign, zero-digit-sign, digit-sign and pattern-separator-sign are classified as active characters, and all other characters (including the percent-sign and per-mille-sign) are classified as passive characters.

The integer part of the sub-picture is defined as the part that appears to the left of the decimal-separator-sign if there is one, or the entire sub-picture otherwise. The fractional part of the sub-picture is defined as the part that appears to the right of the decimal-separator-sign if there is one; it is a zero-length string otherwise.

[ERR133] The picture string must conform to the following rules. It is a dynamic error if the picture string does not satisfy these rules. This is a recoverable error. The processor must either signal the error, or may recover by ignoring those characters in the supplied picture string that make the picture string invalid. If a valid picture string cannot be constructed in this way, 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 picture-string must not contain more than one pattern-separator-sign. If the picture-string contains two sub-pictures, the first is used for positive values and the second for negative values.

  • A sub-picture must not contain more than one decimal-separator-sign.

  • A sub-picture must not contain more than one percent-sign or per-mille-sign, and it must not contain one of each.

  • A sub-picture must contain at least one digit-sign or zero-digit-sign.

  • A sub-picture must not contain a passive character that is preceded by an active character and that is followed by another active character.

  • A sub-picture must not contain a grouping-separator-sign adjacent to a decimal-separator-sign.

  • The integer part of a sub-picture must not contain a zero-digit-sign that is followed by a digit-sign. The fractional part of a sub-picture must not contain a digit-sign that is followed by a zero-digit-sign.

The evaluation of the format-number function is described below in two phases, an analysis phase and a formatting phase. The analysis phase takes as its inputs the picture string and the variables derived from the relevant xsl:decimal-format declaration, and produces as its output a number of variables with defined values. The formatting phase takes as its inputs the number to be formatted and the variables produced by the analysis phase, and produces as its output a string containing a formatted representation of the number.

Note:

Numbers will always be formatted with the most significant digit on the left.

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

Several variables are associated with each sub-picture. If there are two sub-pictures, then these rules are applied to one sub-picture to obtain the values that apply to positive numbers, and to the other to obtain the values that apply to negative numbers. If there is only one sub-picture, then the values for both cases are derived from this sub-picture.

The variables are as follows:

  • The whole-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the integer part of the sub-picture. For each grouping-separator-sign that appears within the integer part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the integer part of the sub-picture and to the right of the grouping-separator-sign. In addition, if these whole-part-grouping-positions are at regular intervals (that is, if they are all consecutive integer multiples of some value N, including the case where there is only one number in the list), then the sequence contains all integer multiples of N as far as necessary to accommodate the largest possible number.

  • The minimum-whole-part-size is an integer indicating the minimum number of digits that will appear to the left of the decimal-separator-sign. It is normally set to the number of zero-digit-sign characters found in the integer part of the sub-picture. But if the sub-picture contains no zero-digit-sign and no decimal-separator-sign, it is set to one.

  • The overflow-threshold indicates the smallest number that is too large to fit in the space available. If any digit-sign is found in the integer part of the sub-picture, the overflow-threshold is set to infinity. Otherwise, it is set to ten raised to the power of the number of zero-digit-sign characters found in the integer part of the sub-picture.

  • The prefix is set to contain all passive characters in the sub-picture to the left of the leftmost active character. If the picture string contains only one sub-picture, the prefix for the negative sub-picture is set by concatenating the minus-sign character and the prefix for the positive sub-picture (if any), in that order.

  • The fractional-part-grouping-positions is a sequence of integers representing the positions of grouping separators within the fractional part of the sub-picture. For each grouping-separator-sign that appears within the fractional part of the sub-picture, this sequence contains an integer that is equal to the total number of digit-sign and zero-digit-sign characters that appear within the fractional part of the sub-picture and to the left of the grouping-separator-sign.

  • The minimum-fractional-part-size is set to the number of zero-digit-sign characters found in the fractional part of the sub-picture.

  • The maximum-fractional-part-size is set to the total number of digit-sign and zero-digit-sign characters found in the fractional part of the sub-picture.

  • The suffix is set to contain all passive characters to the right of the rightmost active character in the fractional part of the sub-picture.

Note:

If there is only one sub-picture, then all variables for positive numbers and negative numbers will be the same, except for prefix: the prefix for negative numbers will be preceded by the minus-sign character.

16.4.4 Formatting the Number

This section describes the second phase of processing of the format-number function. This phase 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 phase 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), the result is the concatenation of the prefix, the specified NaN-symbol, and the suffix, where the prefix and suffix are taken from the sub-picture that applies to positive numbers.

  2. In the rules below, the positive sub-picture and its associated variables are used if the input number is positive, and the negative sub-picture and its associated variables are used otherwise. Negative zero is taken as negative, positive zero as positive.

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

  4. If the sub-picture contains a percent-sign, the number is multiplied by 100. If the sub-picture contains a per-mille-sign, the number is multiplied by 1000. The resulting number is referred to below as the adjusted number.

  5. [ERR134] It is a dynamic error if the absolute value of the adjusted number is numerically greater than or equal to the overflow-threshold. This is a recoverable error. The processor may signal the error, or may recover by formatting the number as if each zero-digit-sign character in the integer part of the sub-picture were a digit-sign.

  6. The adjusted number is rounded so that it uses no more than maximum-fractional-part-size digits in its fractional part. The rounded number is defined as the result of calling the function round-half-to-even with the adjusted number as the first argument, and the maximum-fractional-part-size as the second argument.

  7. The absolute value of the rounded number is converted to a string in decimal notation, with no insignificant leading or trailing zeroes, using the characters implied by the choice of zero-digit-sign to represent the ten decimal digits, and the decimal-separator-sign to separate the integer part and the fractional part. (The value zero will at this stage be represented by a decimal-separator-sign on its own.)

  8. If the number of digits to the left of the decimal-separator-sign is less than minimum-whole-part-size, leading zero-digit-sign characters are added to pad out to that size.

  9. If the number of digits to the right of the decimal-separator-sign is less than minimum-fractional-part-size, trailing zero-digit-sign characters are added to pad out to that size.

  10. For each integer N in the whole-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately after that digit that appears in the integer part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.

  11. For each integer N in the fractional-part-grouping-positions list, a grouping-separator-sign character is inserted into the string immediately before that digit that appears in the fractional part of the number and has N digits between it and the decimal-separator-sign, if there is such a digit.

  12. If there is no decimal-separator-sign in the sub-picture, the decimal-separator-sign character is removed from the string (it will be the rightmost character in the string).

  13. The result of the function is the concatenation of the appropriate prefix, the string conversion of the number as obtained above, and the appropriate suffix.

16.5 Formatting Dates and Times

Three functions are provided to represent dates and times as a string, using the conventions of a selected calendar and locale. Each has two variants.

format-dateTime($value as xs:dateTime?,
$picture as xs:string,
$date-format-name as xs:string) as xs:string?

format-dateTime($value as xs:dateTime?, $picture as xs:string) as xs:string?

format-date($value as xs:date?,
$picture as xs:string,
$date-format-name as xs:string) as xs:string?

format-date($value as xs:date?, $picture as xs:string) as xs:string?

format-time($value as xs:time?,
$picture as xs:string,
$date-format-name as xs:string) as xs:string?

format-time($value as xs:time?, $picture as xs:string) as xs:string?

The format-dateTime, format-date, and format-time functions format $value as a string using the picture string specified by the $picture argument and the date-format named by the $date-format-name argument, or the default date-format, if there is no $date-format-name argument. The result of the function is the formatted string representation of the supplied dateTime, date, or time value.

The three functions format-date, format-time, and format-dateTime are referred to collectively as the date formatting functions.

[ERR135] It is a dynamic error if the name specified as the $date-format-name argument is not a valid QName, or if its prefix has not been declared in an in-scope namespace declaration, or if the stylesheet does not contain a declaration of a date-format with a matching expanded-QName. The processor must either signal the error, or must recover by ignoring the $date-format-name argument. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

If $value is the empty sequence, the empty sequence is returned.

16.5.1 The date-format declaration

<!-- Category: declaration -->
<xsl:date-format
  name = qname
  language = nmtoken
  calendar = qname />

The xsl:date-format element declares a date-format, which provides information used by the date formatting functions. If there is a name attribute, then the element declares a named date format; otherwise, it declares the default date format. The value of the name attribute is a QName, which is expanded as described in 5.1 Qualified Names. [ERR136] It is a static error to declare either the default date-format or a date-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 date-format, a declaration equivalent to an xsl:date-format element with no attributes is implied.

The language attribute specifies the language to be used for the result string of the format-date, function. The effective value of the attribute must be a value that would be valid for the xml:lang attribure (see [XML]). If the language attribute is omitted then the default is implementation-defined.

The language is used to select the appropriate language-dependent forms of:

names (for example, of months)
ordinal form of numbers
hour convention (0-23 vs 1-24, 0-11 vs 1-12)
first day of week, first week of year

The set of languages that are supported is implementation-defined.

The calendar attribute specifies that the dateTime, date, or time supplied in the $value argument must be converted to a value in that calendar and then converted to a string using the conventions of that calendar.

A calendar value must be a valid QName. If the QName does not have a prefix, then it identifies a calendar with the designator specified below. If the QName has a prefix, then the QName is expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the calendar; the behavior in this case is not specified by this document.

If the calendar attribute is omitted a locale-specific value is used.

[ERR137] It is a static error if an implementation does not support the language specified in the language attribute, or the calendar specified in the calendar attribute, or the combination of the two. The processor must either signal the error, or must recover by using a locale-specific value of the two attributes instead of the values specified. If a different calendar is used from that requested, the name of this calendar must be included in the result string.

Note:

The calendars listed below were known to be in use during the last hundred years. Many other calendars have been used in the past, and in many cases these cannot be fully supported without additional parameters. Such parameters may be defined using additional namespace-prefixed attributes on the xsl:date-format element; the semantics of such attributes are not defined by this specification.

This specification does not define any of these calendars, nor the way that they map to the value space of the xs:date data type in [XML Schema]. There is only an approximate equivalence between dates recorded using different calendars. For example, the start of a new day is not simultaneous in different calendars, and may also vary geographically. Implementations supporting calendars other than the Gregorian calendar may therefore produce different results.

Information about some of these calendars, and algorithms for converting between them, may be found in [Calendrical Calculations].

DesignatorCalendar
ADAnno Domini (Christian Era)
AHAnno Hegirae (Muhammedan Era)
AMEMauludi Era (solar years since Mohammed's birth)
AMAnno Mundi (Jewish Calendar)
APAnno Persici
ASAji Saka Era (Java)
BEBuddhist Era
CBCooch Behar Era
CECommon Era
CLChinese Lunar Era
CSChula Sakarat Era
EEEthiopian Era
FEFasli Era
ISOISO 8601 calendar
JEJapanese Calendar
KEKhalsa Era (Sikh calendar)
KYKali Yuga
MEMalabar Era
MSMonarchic Solar Era
NSNepal Samwat Era
OSOld Style (Julian Calendar)
RSRattanakosin (Bangkok) Era
SESaka Era
SHMohammedan Solar Era (Iran)
SSSaka Samvat
TETripurabda Era
VEVikrama Era
VSVikrama Samvat Era

At least one of the above calendars must be supported. It is implementation-defined which calendars are supported.

The ISO 8601 calendar, which is included in the above list and designated ISO, is essentially the same as the Gregorian calendar designated AD, but it prescribes the use of particular numbering conventions as defined in ISO 8601, rather than allowing these to be localized on a per-language basis. Specifically, in the ISO calendar the days of the week are numbered from 1 (Monday) to 7 (Sunday), and week 1 in any calendar year is the week (from Monday to Sunday) that includes the first Thursday of that year. The numeric values of the components year, month, day, hour, minutes, and seconds are the same in this calendar as the values used in the lexical representation of the date and time as defined in [XML Schema]. The ISO calendar is intended primarily for applications that need to produce dates and times in formats to be read by other software, rather than by human users.

Ed. Note:The above text needs to be reviewed by the Working Group
Note:

The value space of the date and time data types, as defined in XML Schema, is based on absolute points in time. The lexical space of these data types defines a representation of these absolute points in time using the proleptic Gregorian calendar, that is, the modern Western calendar extrapolated into the past and the future; but the value space is calendar-neutral. The date formatting functions produce a representation of the same absolute point in time as denoted in a possibly different calendar. So, for example, the date whose lexical representation in XML Schema is 1502-01-11 (the day on which Pope Gregory XIII was born) might be formatted using the Old Style (Julian) calendar as 1 January 1502. This reflects the fact that there was at that time a ten-day difference between the two calendars. It would be incorrect, and would produce incorrect results, to represent this date in an element or attribute of type xs:date as 1502-01-01, even though this might reflect the way the date was recorded in contemporary documents.

16.5.2 The Picture String

The picture consists of a sequence of variable markers and literal substrings. A substring enclosed in square brackets is interpreted as a variable marker; substrings not enclosed in square brackets are taken as literal substrings. The literal substrings are optional and if present are rendered unchanged, including any whitespace. If an opening or closing square bracket is required within a literal sub-string, it must be doubled. The variable markers are replaced in the result by strings representing aspects of the date and/or time to be formatted. These are described in detail below.

A variable marker consists of a component specifier followed optionally by one or two presentation modifiers and/or optionally by a length modifier. Whitespace within a variable marker is ignored.

The component specifier indicates the component of the date or time that is required, and takes the following values:

SpecifierMeaningDefault Presentation Modifier
Yyear1
Mmonth in year1
Dday in month1
dday in year1
Fday of weekn
Wweek in year1
wweek in month1
Hhour in day (24 hours)1
hhour in half-day (12 hours)1
Pam/pm markern
mminute in hour1
ssecond in minute1
ffractional seconds1
Ztimezone as a time offset from UTC, or if an alphabetic modifier is present the conventional name of a timezone (such as PST)1
ztimezone as a time offset using GMT, for example GMT+11
Ccalendar: the name or abbreviation of a calendar namen
Eera: the name of a baseline for the numbering of years, for example the reign of a monarchn

[ERR138] It is a dynamic error if a component specifier within the picture refers to components that are not available in the given $value, or which are not supported in the chosen calendar. This is a recoverable error. The processor may signal the error, or may recover by ignoring the offending component specifiers.

The first presentation modifier indicates the style in which the value of a component is to be represented, and takes the following values:

ModifierMeaning
Aalphabetic, upper case
aalphabetic, lower case (may start with initial upper case if so used in language)
Nname, upper case
nname, lower case (may start with initial upper case if so used in language)
digit 1decimal representation
ilower-case Roman numeral
Iupper-case Roman numeral

Any character that has a decimal digit value of 1 (as specified in the Unicode character property database) generates a decimal representation of the number using the appropriate set of Unicode digits.

Any other character may be used to indicate a numbering sequence that starts with that character, if the implementation supports such a numbering sequence.

If the implementation does not support the use of the requested presentation modifier, it must use the default presentation modifier for that component.

If the first presentation modifier is present, then it may optionally be followed by a second presentation modifier as follows:

ModifierMeaning
ttraditional numbering. This has the same meaning as letter-value="traditional" in xsl:number.
oordinal form of a number, for example 3rd or 8º

Whether or not a presentation modifier is included, a width modifier may be supplied. This indicates the number of characters or digits to be included in the representation of the value.

The width modifier takes the form:

     min-width ("-" max-width)?

where min-width is either an unsigned integer indicating the minimum number of characters to be output, or * indicating that there is no explicit minumum, and max-width is either an unsigned integer indicating the maximum number of characters to be output, or * indicating that there is no explicit maximum; if max-width is omitted then * is assumed. Both integers, if present, must be greater than zero.

If there is no width modifier, then the output uses as many characters as are required to represent the value of the component without truncation and without padding: this is referred to below as the full representation of the value.

If the full representation of the value exceeds the specified maximum width, then the processor should attempt to use an alternative shorter representation that fits within the maximum width. Where the presentation modifier is n or N, this is done by abbreviating the name, using either conventional abbreviations if available, or crude right-truncation if not. For example, setting max-width to 4 indicates that four-letter abbreviations should be used, though it would be acceptable to use a three-letter abbreviation if this is in conventional use. (For example, "Tuesday" might be abbreviated to "Tues", and "Friday" to "Fri".) In the case of the year component, setting max-width requests omission of high-order digits from the year, for example, if max-width is set to 2 then the year 2003 will be output as 03. If no mechanism is available for fitting the value within the specified maximum width (for example, when roman numerals are used), then the value should be output in its full representation.

If the full representation of the value is shorter than the specified minimum width, then the processor should pad the value to the specified width. For decimal representations of numbers, this should be done by prepending zero digits from the appropriate set of digit characters. In other cases, it should be done by prepending spaces.

The choice of the names and abbreviations used in any given language is implementation-defined. For example, one implementation might abbreviate July as Jul while another uses Jly. In German, one implementation might represent Saturday as Samstag while another uses Sonnabend. Implementations may provide mechanisms allowing users to control such choices.

The following examples show a selection of dates and times and the way they might be formatted. These examples assume the use of the Gregorian calendar, and assume that the name of xsl:date-format declarations in the stylesheet is the same as the value of their language attribute. (For example, <date-format name="sv" language="sv"/>.)

Required OutputExpression
2002-12-31format-date($d,"[Y]-[M]-[D]")
12-31-2002format-date($d,"[M]-[D]-[Y]")
31-12-2002format-date($d,"[D]-[M]-[Y]")
31 XII 2002format-date($d,"[D1] [MI] [Y]")
31st December, 2002format-date($d,"[Do] [Mn], [Y]", "en")
31 DEC 2002format-date($d,"[D] [MN,*-3] [Y]", "en")
December 31, 2002format-date($d,"[Mn] [D], [Y]", "en")
31 Dezember, 2002format-date($d,"[D] [Mn], [Y]", "de")
Tisdag 31 December 2002format-date($d,"[Fn] [D] [Mn] [Y]", "sv")
[2003-04-07]format-date($t,"[[[Y]-[M]-[D]]]")
3:58 PMformat-time($t,"[h]:[m] [PN]", "en")
3:58:45 pmformat-time($t,"[h]:[m]:[s] [Pn]", "en")
3:58:45 PM PDTformat-time($t,"[h]:[m]:[s] [PN] [ZN,*-3]", "en")
3:58:45 o'clock PM PDTformat-time($t,"[h]:[m]:[s] o'clock [PN] [ZN,*-3]", "en")
15:58format-time($t,"[H]:[m]")
15:58:45format-time($t,"[H]:[m]:[s]")
15:58:45 GMT+02:00format-time($t,"[H]:[m]:[s] [z]", "en")
15.58 Uhr GMT+02:00format-time($t,"[H]:[m]:[s] Uhr [z]", "de")

The following examples use calendars other than the Gregorian calendar.

Example: Thai

<xsl:date-format name="modern_Thai" language="th" calendar="BE"/>

format-date($d, "[D&#x0E51;] [Mn] [Y&#x0E51;]", "modern_Thai")

Result: ๓๑ ธันวาคม ๒๕๔๕

 

Example: Islamic

<xsl:date-format name="Islamic" language="ar" calendar="AH"/>

format-date($d, "[D&#x0661;] [Mn] [Y&#x0661;]", "Islamic")

Result: ٢٦ ﺸﻭّﺍﻝ ١٤٢٣

 

Example: Jewish

<xsl:date-format name="Jewish" language="he" calendar="AM"/>

format-date($d, "[D] [Mn] [Y]", "Jewish")

Result: ‏26 טבת 5763

 

Example: Julian (Old Style)

<xsl:date-format name="Julian" language="en" calendar="OS"/>

format-date($d, "[D] [Mn] [Y]", "Julian")

Result: 18 December 2002

16.6 Miscellaneous Additional Functions

16.6.1 current

current() as item()

The current function, used within an XPath expression, returns the item that was the context item at the point where the expression was invoked from the XSLT stylesheet. This is referred to as the current item. For an outermost expression (an expression not occurring within another expression), the current item is always the same as the context item. Thus,

<xsl:value-of select="current()"/>

means the same as

<xsl:value-of select="."/>

However, within square brackets, or on the right-hand side of the / operator, the current item is generally different from the context item.

For example,

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

will process all entry elements that have a glossary parent element and that have a name attribute with value equal to the value of the current item's ref attribute. This is different from

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

which means the same as

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

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

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

[ERR139] If the current function is evaluated within an expression that is evaluated when the context item is undefined, a dynamic error occurs. The processor must signal the error.

16.6.2 unparsed-entity-uri

unparsed-entity-uri($entity-name as xs:string) as xs:string

The unparsed-entity-uri function returns the URI of the unparsed entity whose name is given by the value of the $entity-name argument, in the document containing the context node. It returns the zero-length string if there is no such entity. This function maps to the dm:unparsed-entity-system-id accessor defined in [Data Model].

[ERR140] It is a dynamic error if the unparsed-entity-uri is called when there is no context node, or when the root of the tree containing the context node is not a document node. The processor must signal the error.

16.6.3 unparsed-entity-public-id

unparsed-entity-public-id($entity-name as xs:string) as xs:string

The unparsed-entity-public-id function returns the public identifier of the unparsed entity whose name is given by the value of the $entity-name argument, in the document containing the context node. It returns the zero-length string if there is no such entity, or if the entity has no public identifier. This function maps to the dm:unparsed-entity-public-id accessor defined in [Data Model].

[ERR141] It is a dynamic error if the unparsed-entity-public-id is called when there is no context node, or when the root of the tree containing the context node is not a document node. The processor must signal the error.

16.6.4 generate-id

generate-id() as xs:string

generate-id($node as node()?) as xs:string

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 the empty sequence, the result is the zero-length string. If the argument is omitted, it defaults to the context node.

16.6.5 system-property

system-property($property-name as xs:string) as xs:string

The $property-name 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. [ERR142] 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. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

The system-property function returns a string representing the value of the system property identified by the name. If there is no such system property, the zero-length string is returned.

Implementations must provide the following system properties, which are all in the XSLT namespace:

  • xsl:version, a number giving the version of XSLT implemented by the processor; for implementations conforming to the version of XSLT specified by this document, this is the string "2.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.

  • xsl:is-schema-aware, returns the string "yes" in the case of a processor that claims conformance as a Schema Aware processor, or "no" in the case of a Basic XSLT Processor.

  • xsl:supports-serialization, returns the string "yes" in the case of a processor that offers the serialization feature, or "no" otherwise.

  • xsl:supports-backwards-compatibility, returns the string "yes" in the case of a processor that offers the backwards compatibility feature, or "no" otherwise.

Some of these properties relate to the conformance levels and features offered by the processor: these options are described in 21 Conformance.

The actual values returned for the above properties are implementation-defined.

The set of system properties that are supported, in addition to those listed above, is also implementation-defined.

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.

17 Messages

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

The xsl:message instruction sends a message in an implementation-defined way. The xsl:message instruction causes the creation of a new document node. The content of the xsl:message instruction is a sequence constructor. The sequence obtained by evaluating this sequence constructor is used to construct the content of the new document node, as described in 5.6.1 Constructing Complex Content. 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.

The tree produced by the xsl:message is not technically a result tree. It has no URI and there is no requirement that processors should make the tree accessible to applications.

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. Because the order of execution of instructions is implementation-defined, the order in which such messages appear is not predictable.

The terminate attribute is interpreted as an attribute value template.

If the effective value of the terminate attribute is yes, then the processor must terminate processing after sending the message. The default value is no. Note that because the order of evaluation of instructions is implementation-dependent, this gives no guarantee that any particular instruction will or will not be evaluated.

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>

18 Extensibility and Fallback

XSLT allows two kinds of extension, extension instructions and extension functions. An extension instruction is an element within a sequence 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 happens if those extensions are not available. If an XSLT stylesheet is careful to make use of these mechanisms, it is possible for it to take advantage of extensions and still retain portability.

18.1 Extension Functions

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.

18.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 behaves if a particular extension function is not available.

function-available($function-name as xs:string) as xs:boolean

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 $function-name argument is available; otherwise it returns false.

The value of the $function-name argument must be a string containing a QName. The QName is expanded into an expanded-QName using the namespace declarations in scope for the expression. 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.

[ERR143] 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. This is a recoverable error. The processor must either signal the error, or must recover by returning the value false. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

Note:

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

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

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

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

Implementations are not required to perform full validation of values returned by extension functions. It is an error for an extension function to return a string containing characters that are not permitted in XML, but the consequences of this error are implementation-defined. The implementation may raise an error, may convert the string to a string containing valid characters only, or may treat the invalid characters as if they were permitted characters.

Note:

The ability to execute extension functions represents a potential security weakness, since untrusted stylesheets may invoke code that has privileged access to resources on the machine where the processor executes. Implementations may therefore provide mechanisms that restrict the use of extension functions by untrusted stylesheets.

18.1.3 External Objects

An implementation may allow an extension function to return an object that does not have any natural representation in the XPath data model, either as an atomic value or as a node. For example, an extension function sql:connect might return an object that represents a connection to a relational database; the resulting connection object might be passed as an argument to calls on other extension functions such as sql:insert and sql:select.

The way in which such objects are represented in the type system is implementation-defined. They might be represented by a completely new data type, or they might be mapped to existing data types such as integer, string, or anyURI.

18.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 sequence constructor, then the element is treated as an instruction rather than as a literal result element. The namespace determines the semantics of the instruction.

Note:

Since an element that is a child of an xsl:stylesheet element is not occurring in a sequence constructor, user-defined data elements (see 3.4.1 User-defined Data Elements) are not extension elements as defined here, and nothing in this section applies to them.

18.2.1 Designating an Extension Namespace

A namespace is designated as an extension namespace by using an [xsl:]extension-element-prefixes attribute on an element in the stylesheet (see 3.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. [ERR146] 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.

18.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 behaves if a particular extension instruction is not available.

element-available($element-name as xs:string) as xs:boolean

The value of the $element-name argument must be a string containing a QName. The QName is expanded into an expanded-QName using the namespace declarations in scope for the expression. If there is a default namespace in scope, then it is used to expand an unprefixed QName. The element-available function returns true if and only if the expanded-QName is the name of an instruction. If the expanded-QName has a namespace URI equal to the XSLT namespace URI, then it refers to an element defined by XSLT. Otherwise, it refers to an extension instruction. If the expanded-QName has a null namespace URI, the element-available function will return false.

[ERR147] 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. This is a recoverable error. The processor must either signal the error, or must recover by returning the value false. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

If the 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 18.2.3 Fallback. An implementation must not signal an error merely because the stylesheet 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.

18.2.3 Fallback

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

[ERR148] 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; it is a dynamic error if it has no xsl:fallback children. This error must be signaled.

The content of an xsl:fallback element is a sequence constructor, and when performing fallback, the value returned by the xsl:fallback element is the result of evaluating this sequence constructor.

When not performing fallback, evaluating an xsl:fallback element returns an empty sequence: the content of the xsl:fallback element is ignored.

There are two situations where a processor performs fallback: when an extension instruction that is not available is evaluated, and when an instruction in the XSLT namespace, that is not defined in XSLT 2.0, is evaluated within a region of the stylesheet for which forwards compatible behavior is enabled.

Note:

Fallback processing is not invoked in other situations, for example it is not invoked when an XPath expression uses unrecognized syntax or contains a call to an unknown function. To handle such situations dynamically, the stylesheet should call functions such as system-property and function-available to decide what capabilities are available.

19 Result Trees

The output of a transformation is a set of zero or more result trees.

A result tree may be created explicitly, by evaluating an xsl:result-document instruction. A result tree is also created implicitly if the result of evaluating the initial template is a non-empty sequence. This implicit result tree is created as if the sequence constructor contained in the initial template were contained in an xsl:result-document instruction with no attributes.

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

A result tree has a URI. If the implementation provides an API to access 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.

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

19.1 Creating Result Trees

<!-- Category: instruction -->
<xsl:result-document
  format = qname
  href = { uri-reference }
  validation = "strict" | "lax" | "preserve" | "strip"
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:result-document>

The xsl:result-document instruction is used to create a result tree. The content of the xsl:result-document element is a sequence constructor for the children of the document node of the tree. A document node is created, and the sequence obtained by evaluating the sequence constructor is used to construct the content of the document, as described in 5.6.1 Constructing Complex Content. The tree rooted at this document node forms the result tree.

The xsl:result-document instruction defines the URI of the result tree, and may optionally specify the output format to be used for serializing this tree.

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

[ERR149] 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 optional. The default value is the zero-length string. The effective value of the attribute must be a URI, which may be absolute or relative. There may be implementation-defined restrictions on the form of absolute URI that may be used, but the implementation is not required to enforce any restrictions. Any legal relative URI must be accepted. Note that the zero-length string is a legal relative URI.

If the effective value is a relative URI, then it is resolved relative to the base output URI.

The validation attribute may be used to to check the contents of the result tree against a schema definition, and to determine the type annotation that elements and attributes within the result tree will carry. The permitted values and their meanings are described in 19.2 Validation.

The as attribute may be used to make an assertion about the type of the document node of the result tree, after any validation has been carried out. The as attribute does not influence the way in which validation is carried out. [ERR150] A type error occurs if the document node at the root of the result tree, after validation, does not match the SequenceType contained in the as attribute .

Note:

Since the item being validated will always be a document node, the only useful values for the as attribute are of the form document-node(element(X,Y)). The value thus serves as an assertion about the type of the document element of the result tree.

Unlike other instructions that take an as attribute, no attempt is made to convert the supplied value to the specified SequenceType. The only possible conversion would be to atomize the value, and this would make no sense as the output of the transformation would then no longer be a tree.

A processor may allow a result tree to be serialized. Serialization is described in 20 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 result trees. An implementation that does not support the serialization of result trees may ignore the format attribute. Such an implementation must provide the application with some means of access to the (un-serialized) result tree, optionally using its URI to identify it.

Implementations may provide additional mechanisms, outside the scope of this specification, for defining the way in which result trees are processed. Such mechanisms may make use of the XSLT-defined attributes on the xsl:result-document and/or xsl:output elements, or they may use additional elements or attributes in an implementation-defined namespace.

 

The following example takes an XHTML document as input, and breaks it up so that the text following each <h1> element is included in a separate document. A new document toc.html is constructed to act as an index:

<xsl:stylesheet
	version="2.0"
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:xhtml="http://www.w3.org/1999/xhtml">
	
<xsl:output name="toc-format" method="xhtml" indent="yes"
            doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"
            doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN"/>
            
<xsl:output name="section-format" method="xhtml" indent="no"
            doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
            doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"/>	
	 
<xsl:template match="/">
  <xsl:result-document href="toc.html" format="toc-format" validation="strict">
    <html xmlns="http://www.w3.org/1999/xhtml">
      <head><title>Table of Contents</title></head>
      <body>
        <h1>Table of Contents</h1>
        <xsl:for-each select="/*/xhtml:body/(*[1] | xhtml:h1)">
          <p><a href="section{position()}.html"><xsl:value-of select="."/></a></p>
        </xsl:for-each>
      </body>
    </html>
  </xsl:result-document>
  <xsl:for-each-group select="/*/xhtml:body/*" group-starting-with="xhtml:h1">
    <xsl:result-document href="section{position()}.html" 
                         format="section-format" validation="strip">  	
      <html xmlns="http://www.w3.org/1999/xhtml">
        <head><title><xsl:value-of select="."/></title></head>
        <body>
          <xsl:copy-of select="current-group()"/>
        </body>
      </html>
    </xsl:result-document>
  </xsl:for-each-group>
</xsl:template>

</xsl:stylesheet>
 

There are restrictions on the use of the xsl:result-document instruction, designed to ensure that the results are fully interoperable even when processors optimize the sequence in which instructions are evaluated. Informally, the restriction is that the xsl:result-document instruction can only be used while writing a final result tree, not while writing to a temporary tree or a sequence. This restriction is defined formally as follows. Each instruction in the stylesheet is evaluated in one of two possible output states, called final output and temporary output. The instructions in the initial template are evaluated in final output state. An instruction is evaluated in the same output state as its calling instruction, except that xsl:variable, xsl:param, xsl:with-param, xsl:attribute, xsl:comment, xsl:processing-instruction, xsl:namespace, xsl:function, and xsl:message always evaluate the instructions in their contained sequence constructor in temporary output state. [ERR151] It is a dynamic error to evaluate the xsl:result-document instruction in temporary output state. The processor must signal the error..

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

Note:

Note, this means that it is an error to evaluate more than one xsl:result-document instruction that omits the href attribute, or to evaluate any xsl:result-document instruction that omits the href attribute if the initial result tree is created implicitly.

Technically, the result of evaluating the xsl:result-document instruction is an empty sequence. This means it does not contribute any nodes to the result of the sequence constructor it is part of.

[ERR153] It is a dynamic error for a stylesheet to write to an external resource and read from the same resource during a single transformation, whether or not the same URI is used to access the resource in both cases. The effect of this error is implementation-dependent: implementations are not obliged to detect it.

19.2 Validation

19.2.1 Validating Constructed Nodes

It is possible to control the type annotation applied to individual element and attribute nodes as they are constructed. This is done using the type and validation attributes of the xsl:element, xsl:attribute, xsl:copy, and xsl:copy-of instructions, or the xsl:type and xsl:validation attributes of a literal result element.

The [xsl:]type and [xsl:]validation attributes are mutually exclusive. Both are optional, but if one is present then the other must be omitted. If both attributes are omitted, the effect is the same as specifying the validation attribute with the value specified in the default-validation attribute of the containing xsl:stylesheet element; if this is not specified, the effect is the same as specifying validation="strip".

The [xsl:]validation attribute defines the action to be taken. It determines the type annotation not only of the node that is constructed by the relevant instruction itself, but also the type annotations of all element and attribute nodes that have the constructed node as an ancestor. Conceptually, the validation requested for a child element or attribute node is applied before the validation requested for its parent element. For example, if the instruction that constructs a child element specifies validation="strict", this will cause the content of that child element to be checked against a schema definition, but if the instruction that constructs its parent element specifies validation="strip", then the final effect will be that the child node is annotated as xs:anyType.

In the paragraphs below, the term contained nodes means the elements and attributes that have the newly constructed node as an ancestor.

  • The value strip indicates that the new node and each of the contained nodes will have the type annotation xs:anyType if it is an element, or xdt:untypedAtomic if it is an attribute. Any type annotation that is present on a contained element or attribute node (for example, a type annotation that is present on an element copied from a source document) is discarded. Schema validation is not invoked.

  • The value preserve indicates that nodes that are copied will retain their type annotations, but nodes whose content is newly constructed will be annotated as xs:anyType in the case of elements, or xdt:untypedAtomic in the case of attributes. Schema validation is not invoked. The detailed effect depends on the instruction:

    • In the case of xsl:element and literal result elements, the new element has a type annotation of xs:anyType, and the type annotations of contained nodes are retained unchanged.

    • In the case of xsl:attribute, the effect is exactly the same as specifying validation="strip": that is, the new attribute will have the type annotation xdt:untypedAtomic.

    • In the case of xsl:copy-of, all the nodes that are copied will retain their type annotations unchanged.

    • In the case of xsl:copy, the effect depends on the kind of node being copied. Where this is an attribute, the copied attribute will retain its type annotation. Where it is an element, the copied element will have a type annotation of xs:anyType (because this instruction does not copy the content of the element, it would be wrong to assume that the type is unchanged); but any contained nodes that are copied will have their type annotations retained in the same way as with xsl:element.

  • The value strict indicates that type annotations are established by performing strict schema validity assessment on the element or attribute created by this instruction, according to the rules defined in [XML Schema] (Part 1, section 5.2 "Assessing Schema-Validity", validation method 3). The element or attribute is considered valid if the result of the schema validity assessment is a PSVI in which the relevant element or attribute has a validity property whose value is valid. If the element or attribute is not considered valid, the transformation fails. In effect this means that the element or attribute being validated must be declared using a top-level declaration in the relevant schema, and must conform to its declaration. The process of validation applies recursively to contained elements and attributes to the extent required by the schema definition.

    Note:

    Technically, XML Schema only defines validity assessment starting at an element, not at an attribute. However, it is straightforward to extrapolate the definition for attributes, simply by substituting "attribute" for "element" where appropriate in the cited section of [XML Schema].

    The relevant schema is found by firstly searching the schemas that have been imported using xsl:import-schema declarations in the stylesheet, and any schemas that have been implicitly imported using implementation-defined mechanisms. If this does not locate a schema containing a top-level definition of the element or attribute being validated, then the validation process may also locate schema components using any of the mechanisms described in [XML Schema] (Part 1, section 4.3.2 "How schema definitions are located on the Web"). For example, a schema component may be located implicitly from knowledge of the namespace in which the elements and attributes appear; or it may be located using the xsi:schemaLocation attribute of elements within the tree.

    If no validation is performed for a node, which can happen when the schema specifies lax or skip validation for that node or for a subtree, then the node is annotated as xs:anyType in the case of an element, and xdt:untypedAtomic in the case of an attribute.

  • The value lax indicates that type annotations are established by performing lax schema validation on the element or attribute created by this instruction, according to the rules defined in [XML Schema] (Part 1, section 5.2 "Assessing Schema-Validity", validation method 3). This means that the element or attribute being validated must conform to its declaration if a top-level declaration is available in a relevant schema. If no such declaration can be located, then the element or attribute is not validated, but its attributes and children are validated, again with lax validation. Any nodes that are not validated are annotated as xs:anyType in the case of an element, and xdt:untypedAtomic in the case of an attribute. In other respects, validation follows the same rules as defined in the previous paragraph.

[ERR154] If the validation attribute of an xsl:element, xsl:attribute, xsl:copy, or xsl:copy-of instruction, or the xsl:validation attribute of a literal result element, has the effective value strict or lax, and schema validity assessment concludes that the element or attribute is invalid, a type error occurs. The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

Note:

No mechanism is provided to validate an element or attribute against a local declaration in a schema. Such validation can usually be achieved by applying validation to a containing element for which a top-level element declaration does exist.

The [xsl:]type attribute takes as its value a QName. This must either be a built-in type defined in [XML Schema], or a built-in type defined in [XPath 2.0], or a type defined in an explicitly imported schema, or a type that has been implicitly imported as described in 3.10 Importing Schema Components. If the QName has no prefix, it is expanded using the default namespace established using the effective [xsl:]xpath-default-namespace attribute if there is one; otherwise, it is taken as being a name in no namespace.

If the [xsl:]type attribute is present, then the newly constructed element or attribute is validated against the top-level type definition identified by this attribute, according to the rules defined in [XML Schema] (Part 1, section 5.2 "Assessing Schema-Validity", validation method 1). The element or attribute is considered valid if the result of the schema validity assessment is a PSVI in which the relevant element or attribute has a validity property whose value is valid. If the element or attribute is not considered valid, the transformation fails.

[ERR155] It is a static error if the value of the type attribute of an xsl:element, xsl:attribute, xsl:copy, or xsl:copy-of instruction, or the xsl:type attribute of a literal result element, is not a valid QName, or if it uses a prefix that is not defined in an in-scope namespace declaration, or if the QName is not the name of a built-in type or of a top-level type definition present in an imported schema.

[ERR156] It is a static error if the value of the type attribute of an xsl:attribute instruction refers to a complex type definition.

[ERR157] It is a type error if an [xsl:]type attribute is defined for a constructed element or attribute, and the outcome of schema validity assessment against that type is that the validity property of that element or attribute information item is other than valid.

Note:

Like other type errors, this error may be signaled statically if it can be detected statically. For example, the instruction <xsl:attribute name="dob" type="xs:date">1999-02-29</xsl:attribute> may result in a static error being signaled. If the error is not signaled statically, it will be signaled when the instruction is evaluated.

The newly constructed nodes are assigned types by performing the schema validation process described in [XML Schema]. The full schema validation process is invoked, except that identity constraints, as defined in section 3.11 of [XML Schema] Part 1, are ignored. All facets of simple types are checked. If default values for elements or attributes are defined in the schema, the validation process may create new nodes containing these default values.

Validating a newly constructed element, using strict or lax validation, is equivalent to the following steps:

  1. The value of the element is converted from the XPath data model (see [Data Model]) to an XML Information Set (see [XML Information Set].) This step is equivalent to serializing the node or tree in XML form and then parsing it to produce an Information Set. Note that this process discards any existing type annotations.

  2. The Information Set produced in the previous step is validated according to the rules in [XML Schema], using the in-scope schema definitions. The result of this step is a Post-Schema Validation Infoset (PSVI). If the validation process is not successful (as defined above), a type error is raised.

  3. The PSVI produced in the previous step is converted back into the XPath data model by the mapping described in [Data Model] (Section 3.6, "Mapping PSV Infoset Additions to Types"). This process creates nodes with simple or complex type annotations based on the types established during schema validation.

19.2.2 Validating Result Trees

It is possible to apply validation to a final result tree. This applies both to a result tree constructed using an xsl:result-document instruction, and to the result tree constructed implicitly in the absence of the an xsl:result-document instruction. In the case where the xsl:result-document instruction is used, validation is controlled using the validation attribute of that instruction, or the default-validation attribute of the containing xsl:stylesheet element if the validation attribute is omitted. In the case where the result tree is constructed in the absence of an xsl:result-document instruction, validation is controlled using the default-validation attribute of the xsl:stylesheet element of the principal stylesheet module.

The permitted values of the validation attribute are the same as the values for the same attribute on instructions such as xsl:element.

[ERR158] A type error occurs if strict or lax validation is requested for a final result tree unless the children of the document node comprise exactly one element node, no text nodes, and zero or more comment and processing instruction nodes, in any order.The processor must signal the error. Like other type errors, the error may be signaled statically if it can be detected statically.

A result tree is validated by applying the validation process (with the same value of the validation attribute) to the element child of the document node of the result tree, as described in 19.2.1 Validating Constructed Nodes, and copying any other children of the document node unchanged.

When validation is requested for a result tree, identity constraints, as defined in section 3.11 of [XML Schema] Part 1, are taken into account. If the result tree does not satisfy the identity constraints, a type error is signaled as for other validation failures.

20 Serialization

A processor may output a result tree as a sequence of octets, although it is not required to be able to do so (see 21 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.

The rules governing the output of the serializer are defined in [XSLT and XQuery Serialization]. The serialization is controlled using a number of serialization parameters. The values of these serialization parameters may be set within the stylesheet, using the xsl:output and xsl:character-map declarations.

<!-- Category: declaration -->
<xsl:output
  name = qname
  method = "xml" | "html" | "xhtml" | "text" | qname-but-not-ncname
  cdata-section-elements = qnames
  doctype-public = string
  doctype-system = string
  encoding = string
  escape-uri-attributes = "yes" | "no"
  include-content-type = "yes" | "no"
  indent = "yes" | "no"
  media-type = string
  normalize-unicode = "yes" | "no"
  omit-xml-declaration = "yes" | "no"
  standalone = "yes" | "no"
  undeclare-namespaces = "yes" | "no"
  use-character-maps = qnames
  version = nmtoken />

The xsl:output declaration is optional; if used, it must always appear as a top-level element within a stylesheet.

A stylesheet may contain multiple xsl:output declarations and may include or import stylesheet modules that also contain xsl:output declarations. The name of an xsl:output declaration is the value of its name attribute, if any. 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 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. It is also used when serializing the result tree that is created implicitly in the absence of an xsl:result-document element.

All the xsl:output elements making up an output definition are effectively merged. For the cdata-section-elements and use-character-maps attributes, the output definition uses the union of the values from all the constituent xsl:output declarations. For other attributes, the output definition uses the value of that attribute from the xsl:output declaration with the highest import precedence. [ERR159] 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 and use-character-maps), with the 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. This is a recoverable error. 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, or the default values to be changed, using the API that controls the transformation.

Before a final result tree is serialized, namespace fixup is performed (see 5.6.3 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 when two result trees are both created (implicitly or explicitly) using relative URIs in the href attribute of the xsl:result-document instruction, then these relative URIs may be used to construct references from one tree to the other, and such references must remain valid when both result trees are serialized.

The method attribute on the xsl:output element identifies the overall method that is to be used for outputting the result tree. [ERR160] The value must be a valid QName. If the QName does not have a prefix, then it identifies a method specified in [XSLT and XQuery Serialization] and must be one of xml, html, xhtml, or text. If the QName has a prefix, then the QName is expanded into an expanded-QName as described in 5.1 Qualified Names; the expanded-QName identifies the output method; the behavior in this case is not specified by this document.

The default for the method attribute 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:

  • If the expanded-QName of this first element child has local part html (in lower case), and namespace URI http://www.w3.org/1999/xhtml, then the default output method is xhtml.

  • If the expanded-QName of this first element child has local part html (in any combination of upper and lower case) and a null namespace URI, then the default output method is html.

In all other cases, the default output method is xml.

The default output method is used if 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 value of the encoding attribute provides the value of the encoding parameter to the serialization method. The default value is implementation-defined, but in the case of the xml and xhtml methods it must be either UTF-8 or UTF-16.

  • The cdata-section-elements attribute is a space-separated list of QNames. After expansion of these names using the in-scope namespace declarations for the xsl:output declaration in which they appear, this list of names provides the value of the cdata-section-elements parameter to the serialization method. The default value is an empty list.

  • The value of the doctype-system attribute provides the value of the doctype-system parameter to the serialization method. By default, the parameter is not supplied.

  • The value of the doctype-public attribute provides the value of the doctype-public parameter to the serialization method. By default, the parameter is not supplied.

  • The value of the escape-uri-attributes attribute provides the value of the escape-uri-attributes parameter to the serialization method. The default value is yes.

  • The value of the include-content-type attribute provides the value of the include-content-type parameter to the serialization method. The default value is yes.

  • The value of the indent attribute provides the value of the indent parameter to the serialization method. The default value is yes in the case of the html and xhtml output methods, no in the case of the xml output method.

  • The value of the media-type attribute provides the value of the media-type parameter to the serialization method. The default value is text/xml in the case of the xml output method, text/html in the case of the html and xhtml output methods, and text/plain in the case of the text output method.

  • The value of the normalize-unicode attribute provides the value of the normalize-unicode parameter to the serialization method. The default value is no.

  • The value of the omit-xml-declaration attribute provides the value of the omit-xml-declaration parameter to the serialization method. The default value is no.

  • The value of the standalone attribute provides the value of the standalone parameter to the serialization method. By default, the parameter is not supplied; this means that no standalone attribute is included in the XML declaration.

  • The undeclare-namespaces attribute is relevant only when producing output with method="xml" and version="1.1". It defines whether namespace undeclarations (of the form xmlns:foo="") should be output when a child element has no namespace node with the same name (that is, namespace prefix) as a namespace node of its parent element. The default value is no: this means that namespace undeclarations are not output, which has the effect that when the resulting XML is reparsed, the new tree will contain namespace nodes on the child element that were not there in the original tree before serialization.

  • The use-character-maps attribute provides a list of named character maps that are used in conjunction with this output definition. The way this attribute is used is described in 20.1 Character Maps.

  • The value of the version attribute provides the value of the version parameter to the serialization method. The default value depends on the output method: it is 1.0 for xml, 4.01 for html, and 1.0 for xhtml. The parameter is not used by the text output method.

20.1 Character Maps

A character map allows a specific character appearing in a text or attribute node in the result tree to be substituted by a specified string of characters during serialization. The effect of character maps is defined in [XSLT and XQuery Serialization].

The character map that is supplied as a parameter to the serializer is determined from the xsl:character-map elements referenced from the xsl:output declaration for the selected output definition.

The xsl:character-map element is a declaration that may appear as a child of the xsl:stylesheet element.

<!-- Category: declaration -->
<xsl:character-map
  name = qname
  use-character-maps = qnames>
  <!-- Content: (xsl:output-character*) -->
</xsl:character-map>

The xsl:character-map declaration declares a character map with a name and a set of character mappings. The character mappings are specified by means of xsl:output-character elements contained either directly within the xsl:character-map element, or in further character maps referenced in the use-character-maps attribute.

The required name attribute provides a name for the character map. When a character map is used by an output definition or another character map, the character map with the highest import precedence is used. [ERR161] It is a static error if the stylesheet contains two or more character maps with the same name and the same import precedence.

The optional use-character-maps attribute lists the names of further character maps that are included into this character map.

[ERR162] It is a static error if a name in the use-character-maps attribute does not match the name attribute of any xsl:character-map in the stylesheet.

[ERR163] It is a static error if a character map references itself, directly or indirectly, via a name in the use-character-maps attribute.

It is not an error if the same character map is referenced more than once, directly or indirectly.

An output definition, after recursive expansion of character maps referenced via its use-character-maps attribute, may contain several mappings for the same character. In this situation, the last character mapping takes precedence. To establish the ordering, the following rules are used:

  • Within a single xsl:character-map element, the characters defined in character maps referenced in the use-character-maps attribute are considered before the characters defined in the child xsl:output-character elements.

  • The character maps referenced in a single use-character-maps attribute are considered in the order in which they are listed in that attribute. The expansion is depth-first: each referenced character map is fully expanded before the next one is considered.

  • Two xsl:output-character elements appearing as children of the same xsl:character-map element are considered in document order.

The xsl:output-character element is defined as follows:

<xsl:output-character
  character = char
  string = string />

The character map that is passed as a parameter to the serializer contains a mapping for the character specified in the character attribute to the string specified in the string attribute.

Character mapping is not applied to characters for which output escaping has been disabled as described in 20.2 Disabling Output Escaping.

If a character is mapped, then it is not subjected to XML or HTML escaping.

The following example illustrates a composite character map constructed in a modular fashion:

<xsl:output name="htmlDoc" character-map="htmlDoc" />

<xsl:character-map name="htmlDoc"
  use-character-maps="html-chars doc-entities windows-format" />
  
<xsl:character-map name="html-chars"
  use-character-maps="latin1 ..." />

<xsl:character-map name="latin1">
  <xsl:output-character character="&#160;" string="&amp;nbsp;" />
  <xsl:output-character character="&#161;" string="&amp;iexcl;" />
  ...
</xsl:character-map>

<xsl:character-map name="doc-entities">
  <xsl:output-character character="&#xE400;" string="&amp;t-and-c;" />
  <xsl:output-character character="&#xE401;" string="&amp;chap1;" />
  <xsl:output-character character="&#xE402;" string="&amp;chap2;" />
  ...
</xsl:character-map>

<xsl:character-map name="windows-format">
  <!-- newlines as CRLF -->
  <xsl:output-character character="&#xA;" string="&#xD;&#xA;" />

  <!-- tabs as three spaces -->
  <xsl:output-character character="&#x9;" string="   " />

  <!-- images for special characters -->
  <xsl:output-character character="&#xF001;"
    string="&lt;img src='special1.gif' /&gt;" />
  <xsl:output-character character="&#xF002;"
    string="&lt;img src='special2.gif' /&gt;" />
  ...
</xsl:character-map>

20.2 Disabling Output Escaping

Normally, when using the XML, HTML, or XHTML output method, the serializer will escape special characters such as & and < when outputting text and attribute nodes. This ensures that the output is well-formed. However, it is sometimes convenient to be able to produce output that is almost, but not quite well-formed XML; for example, the output may include ill-formed sections which are intended to be transformed into well-formed XML by a subsequent non-XML-aware process. For this reason, XSLT defines a mechanism for disabling output escaping.

This is an optional feature: it is not required that a XSLT processor that implements the serialization option should offer the ability to disable output escaping, and there is no conformance level that requires this feature.

This feature requires an extension to the serializer described in [XSLT and XQuery Serialization]. Conceptually, the result tree provides an additional boolean property disable-escaping associated with every character in a text node, and with every attribute node. When this property is set, the normal action of the serializer to escape special characters such as & and < is suppressed.

An xsl:value-of or xsl:text element may have a disable-output-escaping attribute; the allowed values are yes or no. The default is no; if the value is yes, then every character in the text node generated by evaluating the xsl:value-of or xsl:text element should have the disable-output property set.

For example,

<xsl:text disable-output-escaping="yes">&lt;</xsl:text>

should generate the single character <.

[ERR164] It is a dynamic error for output escaping to be disabled for an xsl:value-of or xsl:text instruction that is used to generate 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. This is a recoverable error. The processor must either signal the error, or must recover by ignoring the disable-output-escaping attribute.

If output escaping is disabled for text within an element that would normally be output using a CDATA section, because the element is listed in the cdata-section-elements, then the relevant text will not be included in a CDATA section. In effect, CDATA is treated as an alternative escaping mechanism, which is disabled by the disable-output-escaping option.

 

For example, if <xsl:output cdata-section-elements="title"/> is specified, then the following instructions:

<title>
  <xsl:text disable-output-escaping="yes">This is not &lt;hr/&gt; good coding practice</xsl:text>
</title>

should generate the output:

<title><![CDATA[This is not ]]><hr/><![CDATA[ good coding practice]]></title>
 

Output escaping can be disabled for an attribute node by specifying disable-output-escaping="yes" on the xsl:attribute instruction. It is not possible to disable escaping of some characters in the attribute value while allowing escaping of others.

When output escaping is disabled for an attribute node, the serializer should use quotation marks to delimit the attribute value if it contains an apostrophe, and should use apostrophes to delimit the value if it contains a quotation mark. If it contains both quotations marks and apostrophes, or if it contains neither, then the serializer may use either character as the delimiter.

When output escaping is disabled for an attribute, the escaping of special characters in URI values that is normally performed by the HTML and XHTML output methods will also be disabled.

 

For example,

<jsp:setProperty name="user" property="id">
  <xsl:attribute name="value" disable-output-escaping="yes">
    <xsl:text>&lt;%= "id" + idValue %&gt;</xsl:text>
  </xsl:attribute>
</jsp:setProperty>

should generate the output:

<jsp:setProperty name="user" property="id" value='<%= "id" + idValue %>'/>

Although this output is not well-formed XML or HTML, it is valid in Java Server Pages.

 

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.

[ERR165] It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled and the implementation does not support this. This is a recoverable error. The processor must either signal the error, or must recover by not disabling output escaping.

[ERR166] It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled when when writing to a result tree that is not being serialized. This is a recoverable error. The processor must either signal the error, of must recover by not disabling output escaping.

In particular, it is implementation-defined what happens when output escaping is disabled for a text or attribute node that is written to a temporary tree rather than a final result tree. The implementation may retain the information that output escaping was disabled, and use it when the relevant node is subsequently copied to a final result tree, but it is not required to do so. The fact that output escaping was disabled is not represented explicitly in the data model, and must not affect the result of any expressions that access the temporary tree.

[ERR167] 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. This is a recoverable error. 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.

Note:

The facility to define character maps for use during serialization, as described in 20.1 Character Maps, has been produced as an alternative mechanism that can be used in many situations where disabling of output escaping was previously necessary, without the same difficulties.

21 Conformance

A processor that claims conformance with this specification must claim conformance either as a basic XSLT processor or as a schema-aware XSLT processor. The rules for these two conformance levels are defined in the following sections.

A processor that claims conformance at either of these two levels may additionally claim conformance with either or both of the following optional features: the serialization feature, defined in 21.3 Serialization Feature, and the backwards compatibility feature, define in 21.4 Backwards Compatibility Feature.

Note:

There is no conformance level or feature defined in this specification that requires implementation of the static typing features described in [XPath 2.0]. An XSLT processor may provide a user option to invoke static typing, but to be conformant with this specification it must allow a stylesheet to be processed with static typing disabled. The interaction of XSLT stylesheets with the static typing feature of XPath 2.0 has not been specified, so the results of using static typing, if available, are implementation-defined.

An XSLT processor takes as its inputs a stylesheet and one or more trees supplied as instances of the data model defined in [Data Model]. This specification does not require that the processor supports any particular method of constructing input data models, but conformance can only be tested if it provides a mechanism that enables data model instances representing the stylesheet and primary source document data model to be constructed and supplied as input to the processor.

The output of the XSLT processor consists of one or more trees. This specification does not require that the processor supports any particular method of accessing a result tree, but if it does not support the serialization module, conformance can only be tested if it provides some alternative mechanism that enables access to the results of the transformation.

Certain facilities in this specification are described as producing implementation-defined results. A claim that asserts conformance with this specification must be accompanied by documentation stating the effect of each implementation-defined feature. For convenience, a non-normative checklist of implementation-defined features is provided at E Checklist of Implementation-Defined Features.

A conforming processor must signal any static error occurring in the stylesheet, or in any XPath expression, except where specified otherwise either for individual error conditions or under the general provisions for forwards compatible behavior (see 3.7 Forwards-Compatible Processing). After signaling such an error, the processor may continue for the purpose of signaling additional errors, but must terminate abnormally without performing any transformation.

When a dynamic error occurs during the course of a transformation, the action depends on whether the error is classified as a recoverable error. If a non-recoverable error occurs, the processor must signal it and must eventually terminate abnormally. If a recoverable error occurs, the processor must either signal it and terminate abnormally, or it must take the defined recovery action and continue processing.

Some errors, notable type errors, may be treated as static errors or dynamic errors at the discretion of the processor.

A conforming processor may impose limits on the processing resources consumed by the processing of a stylesheet.

21.1 Basic XSLT Processor

A basic XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification with the exception of those explicitly listed below. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

A basic XSLT processor must enforce the following restrictions. It must signal a static or dynamic error when the restriction is violated, as described below.

  • [ERR168] A basic XSLT processor must signal a static error if the stylesheet includes an xsl:import-schema declaration. Note that a processor that rejects an xsl:import-schema declaration will also reject any reference to a user-defined type defined in a schema, or to a user-defined element or attribute declaration; it will not, however, reject references to the built-in types defined in XML Schema, or to the predefined types xdt:untypedAtomic, xdt:anyAtomicType, xdt:yearMonthDuration, and xdt:dayTimeDuration defined in [Data Model] and [XPath 2.0]. A basic XSLT processor may allow additional types to be defined, in an implementation-defined way, for the purpose of supporting extension functions.

  • [ERR169] A basic XSLT processor must signal a static error if the stylesheet includes an [xsl:]type attribute, or an [xsl:]validation or default-validation attribute with a value other than strip.

  • [ERR170] A basic XSLT processor must signal a static error if the stylesheet includes an XPath expression containing a validate expression.

  • [ERR171] A basic XSLT processor constrains the data model as follows. Atomic values must belong to one of the atomic types available in the static context (that is, they may only use built-in types, or types defined for use by extension functions, but not derived types defined in a schema). Element nodes must be annotated with the type annotation xs:anyType, and attribute nodes with the type annotation xdt:untypedAtomic. This rule means that a basic XSLT processor must not accept as input, or generate as intermediate or final results, any value that exceeds these constraints. If any instruction or expression in the stylesheet would cause these constraints to be violated, the processor must signal a dynamic error.

    Note:

    This places a requirement on software external to the XSLT processor, for example an XML parser, to generate a data model that satisfies these constraints. This specification does not define how this is done. A processor might, for example, implement a mapping from the PSVI to the data model that loses all non-trivial type annotations; or it might not accept input from a PSVI at all.

    Note:

    This description of a basic XSLT processor does not rely normatively on the definition of a Basic XPath Processor contained in [XPath 2.0].

21.2 Schema-Aware XSLT Processor

A schema-aware XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification. including those features that a basic XSLT processor signals as an error. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

21.3 Serialization Feature

A processor that claims conformance with the serialization feature must support the conversion of a result tree to a sequence of octets following the rules defined in 20 Serialization. It must respect all the attributes of the xsl:output and xsl:character-map declarations, and must provide all four output methods, xml, xhtml, html, and text. Where the specification uses words such as must and required, then it must serialize the result tree in precisely the way described; in other cases it may use an alternative, equivalent representation.

A processor may claim conformance with the serialization feature whether or not it supports the setting disable-output-escaping="yes" on xsl:text, xsl:value-of, or xsl:attribute. A processor that does not support the use of disable-output-escaping should ignore the disable-output-escaping attribute, preferably with a warning.

A processor that does not claim conformance with the serialization feature must not signal an error merely because the stylesheet contains xsl:output or xsl:character-map declarations; these declarations should be ignored.

21.4 Backwards Compatibility Feature

A processor that claims conformance with the backwards compatibility feature must support the processing of stylesheet instructions and XPath expressions with backwards compatible behavior, as defined in 3.6 Backwards-Compatible Processing.

[ERR172] A processor that does not claim conformance with the backwards compatibility feature must raise a dynamic error if an instruction is evaluated containing an [xsl:]version attribute that invokes backwards compatible behavior.

Note:

The reason this is a dynamic error rather than a static error is to allow stylesheets to contain conditional logic, following different paths depending on whether the XSLT processor implements XSLT 1.0 or XSLT 2.0. The selection of which path to use can be controlled by using the system-property function to test the xsl:version system property.

A processor that claims conformance with the backwards compatibility feature must permit the use of the namespace axis in XPath expressions when backwards compatible behavior is enabled. In all other circumstances, support for the namespace axis is optional.

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/xpath-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/xpath-functions/
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/
XML Information Set
World Wide Web Consortium. XML Information Set. W3C Recommendation. See http://www.w3.org/TR/xml-infoset/
XSLT and XQuery Serialization
World Wide Web Consortium. XSLT 2.0 and XQuery 1.0 Data Model Serialization. W3C Recommendation. See http://www.w3.org/TR/xslt-xquery-serialization/
Unicode Normalization
Unicode Consortium. Unicode Normalization Forms. Unicode Standard Annex #15. See http://www.unicode.org/unicode/reports/tr15/
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 1.0
World Wide Web Consortium. Extensible Markup Language (XML) 1.0 (Second Edition) W3C Recommendation. See http://www.w3.org/TR/2000/REC-xml-20001006
XML 1.1
World Wide Web Consortium. Extensible Markup Language (XML) 1.1 W3C Candidate Recommendation. See http://www.w3.org/TR/xml11/
XMLBASE
World Wide Web Consortium. XML Base. W3C Recommendation. See http://www.w3.org/TR/xmlbase/
XML Namespaces 1.0
World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See http://www.w3.org/TR/REC-xml-names/
XML Namespaces 1.1
World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See http://www.w3.org/TR/xml-names11/
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/

A.2 Other References

Calendrical Calculations
Edward M. Reingold and Nachum Dershowitz. Calendrical Calculations Millennium edition (2nd Edition). Cambridge University Press, ISBN 0 521 77752 6
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.
RFC2119
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF RFC 2119. See http://www.ietf.org/rfc/rfc2119.txt.
RFC2278
N. Freed, J. Postel. IANA Charset Registration Procedures. IETF RFC 2278. See http://www.ietf.org/rfc/rfc2278.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.
RFC3023
M. Murata, S. St.Laurent, and D. Cohn. XML Media Types. IETF RFC 3023. See http://www.ietf.org/rfc/rfc3023.txt.
RFC3236
M. Baker, P. Stark. The 'application/xhtml+xml' Media Type. IETF RFC 3236. See http://www.ietf.org/rfc/rfc3236.txt.
UNICODE TR10
Unicode Consortium. Unicode Technical Standard #10. Unicode Collation Algorithm. Unicode Technical Report. See http://www.unicode.org/unicode/reports/tr10/.
XInclude
World Wide Web Consortium. XML Inclusions (XInclude) W3C Recommendation. See http://www.w3.org/TR/xinclude/
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 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.

argument conversion rules

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

arity

The arity of a stylesheet function is the number of xsl:param elements in the function definition.

atomize

The term atomization is defined in [XPath 2.0]. It is a process that takes as input a sequence of nodes and atomic values, and returns a sequence of atomic values, in which the nodes are replaced by their typed values as defined in [Data Model].

attribute set

The xsl:attribute-set element defines a named attribute set: that is, a collection of attribute values that can be used repeatedly on different elements in the result tree.

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

backwards compatibility feature

A processor that claims conformance with the backwards compatibility feature must support the processing of stylesheet instructions and XPath expressions with backwards compatible behavior, as defined in 3.6 Backwards-Compatible Processing.

backwards compatible behavior

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.

base output URI

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.

basic XSLT processor

A basic XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification with the exception of those explicitly listed below. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

character map

A character map allows a specific character appearing in a text or attribute node in the result tree to be substituted by a specified string of characters during serialization.

circularity

If the expression or sequence constructor specifying the value of a global variable X references a global variable Y, then the value for Y must be computed before the value of X. 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 is to be sorted before the other.

context item

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.

context node

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.

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

The evaluation context for XPath expressions includes an additional value called the current grouping key, which is an atomic value. The current grouping key is a value shared in common by all the items within the current group.

current mode

At any point in the processing of a stylesheet, there is a current mode. When the transformation is initiated, the current mode is the default mode, unless a different initial mode has been supplied, as described in 2.3 Initiating a Transformation. Whenever an xsl:apply-templates instruction is evaluated, the current mode becomes the mode selected by this instruction.

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 sequence constructor. When an xsl:for-each or xsl:for-each-group instruction is evaluated, or when a stylesheet function is called (see 10.3 Stylesheet Functions), the current template rule becomes null for the evaluation of that instruction or function.

date-format

The xsl:date-format element declares a date-format, which provides information used by the date formatting functions.

date formatting function

The three functions format-date, format-time, and format-dateTime are referred to collectively as the date formatting functions.

decimal-format

The xsl:decimal-format element declares a decimal-format, which controls the interpretation of a picture string used by the format-number function.

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 3.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 is a stylesheet module that is embedded within another XML document, typically the source document that is being transformed.

expanded-QName

An expanded-QName is a pair of values containing a local name and an optional namespace URI. 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 (or both absent) and the local names are the same.

expression

Within this specification, the term XPath expression, or simply expression, means a string that matches the production Expr defined in [XPath 2.0].

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 sequence 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 sequence constructor, then the element is treated as an instruction rather than as a literal result element.

focus

When a sequence 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 3.3 Standard Attributes) whose value is greater than 2.0.

function parameter

An xsl:param element may appear as a child of an xsl:function element, before any non-xsl:param children of that element. Such a parameter is known as a function parameter. A function parameter is a local variable with the additional property that its value can be set when the function is called, using a function call in an XPath expression.

global variable

A top-level variable-binding element declares a global variable that is visible everywhere (except where it is shadowed by another binding).

group

The xsl:for-each-group instruction allocates the items in an input sequence into groups of items (that is, it establishes a collection of sequences) based either on common values of a grouping key, or on a pattern that the initial node in a group must match.

grouping key

If either of the group-by attribute or group-adjacent attributes is present, then grouping keys are calculated for each item in the population.

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

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

initial input sequence

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 input function described in [Functions and Operators].

initial sequence

The sequence to be sorted is referred to as the initial sequence.

initial template

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

instruction

An instruction is defined as an element that can appear in a sequence constructor and that is either in the XSLT namespace, or in a namespace designated as an extension namespace.

key

A key is defined as a set of xsl:key declarations in the stylesheet that share the same name.

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 sequence constructor, an element in the stylesheet that does not belong to the XSLT namespace and that is not an extension instruction (see 18.2 Extension Instructions) is classified as a literal result element.

local variable

As well as being allowed as declaration elements, the xsl:variable element is also allowed in sequence constructors and within the xsl:function element (see 10.3 Stylesheet Functions) after any xsl:param elements and before the xsl:result element. Such a variable is known as a local variable.

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 16.1 Multiple Source Documents) or when processing temporary trees (see 9.4 Temporary Trees)

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 defines a named template.

namespace fixup

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

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. If two groups G and H have the same initial item (because the item is in both groups) then G precedes H if the grouping key of G precedes the grouping key of H in the sequence that results from evaluating the group-by expression of this initial item.

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 single unnamed output definition.

parameter

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

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

place marker

The xsl:number instruction performs two tasks: firstly, determining a place marker (this is a sequence of integers, to allow for hierarchic numbering schemes such as 1.12.2 or 3(c)ii), and secondly, formatting the place marker for output as a text node in the result sequence.

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

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

processor

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.

QName

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

recoverable error

Some dynamic errors are classed as recoverable errors. When a recoverable error occurs, this specification allows the processor either to signal the error (by reporting the error condition and terminating execution) or to take a defined recovery action and continue processing.

required type

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

reserved namespace

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

schema-aware XSLT processor

A schema-aware XSLT processor is an XSLT processor that implements all the mandatory requirements of this specification. including those features that a basic XSLT processor signals as an error. The mandatory requirements of this specification are taken to include the mandatory requirements of XPath 2.0, as described in [XPath 2.0]. A requirement is mandatory unless the specification includes wording (such as the use of the words should or may) that clearly indicates that it is optional.

schema datatypes namespace

The schema datatypes namespace http://www.w3.org/2001/XMLSchema-datatypes is used as defined in [XML Schema]

schema instance namespace

The schema instance namespace http://www.w3.org/2001/XMLSchema-instance is used as defined in [XML Schema]

schema namespace

The schema namespace http://www.w3.org/2001/XMLSchema is used as defined in [XML Schema]

sequence constructor

A sequence constructor is a sequence of sibling nodes in the stylesheet that can be evaluated to return a sequence of nodes and atomic values. The way that the resulting sequence is used depends on the containing instruction.

serialization

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.

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.

serialization feature

A processor that claims conformance with the serialization feature must support the conversion of a result tree to a sequence of octets following the rules defined in 20 Serialization.

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 an XML document, or part of an XML document, whose outermost element is a literal result element to be copied to the result tree. This element is not itself in the XSLT namespace, but it must have an xsl:version attribute, which implies that the XSLT namespace must be declared. For further details see 3.5 Simplified Stylesheet Modules.

singleton focus

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

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 xpath-default-namespace.

standard function namespace

The standard function namespace http://www.w3.org/2003/05/xpath-functions is used for functions in the core function library, defined in [Functions and Operators].

standard stylesheet module

A standard stylesheet module is an XML document, or part of an XML document, having an xsl:stylesheet or xsl:transform element as its outermost element (see 3.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.

string value

The term string value is defined in [Data Model]. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.

stylesheet

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

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.

stylesheet parameter

A top-level xsl:param element declares a stylesheet parameter. A stylesheet parameter is a global variable with the additional property that its value can be supplied by the caller when a transformation is initiated. XSLT does not define the mechanism by which parameter values are passed to the stylesheet.

supplied value

The value of the variable is computed using the expression given in the select attribute and/or the contained sequence constructor, as described in 9.3 Values of Variables and Parameters. This value is referred to as the supplied value of the variable.

template

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

template parameter

An xsl:param element may appear as a child of an xsl:template element, before any non-xsl:param children of that element. Such a parameter is known as a template parameter. A template parameter is a local variable with the additional property that its value can be set when the template is called, using any of the instructions xsl:call-template, xsl:apply-templates, xsl:apply-imports, or xsl:next-match.

template rule

A stylesheet generally contains a set of template rules. A template rule has two parts: a pattern which is matched against nodes in a source tree and a sequence constructor which is evaluated to produce a sequence of items. In most cases these items are nodes, which are then written to a result tree.

temporary 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), and has no as attribute, then the content of the variable-binding element specifies the supplied value. The content of the variable-binding element is a sequence constructor; a new document (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 sequence 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) is any sequence (of nodes and/or atomic values), as defined in [Data Model].

variable

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

variable-binding element

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

XML namespace

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

xpath datatypes namespace

The XPath datatypes namespace http://www.w3.org/2003/05/xpath-datatypes is used as defined in [Functions and Operators]

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 (Non-Normative)

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 sequence constructor. These elements are:

xsl:analyze-string

 

Category: instruction

Model:

<xsl:analyze-string
  select = expression
  regex = { string }
  flags = { string }>
  <!-- Content: (xsl:matching-substring?, xsl:non-matching-substring?, xsl:fallback*) -->
</xsl:analyze-string>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

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 sequence constructor
  • any literal result element

xsl:apply-templates

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:attribute

 

Category: instruction

Model:

<xsl:attribute
  name = { qname }
  namespace = { uri-reference }
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname
  disable-output-escaping = "yes" | "no">
  <!-- Content: sequence-constructor -->
</xsl:attribute>

Permitted parent elements:

  • xsl:attribute-set
  • any XSLT element whose content model is sequence 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 sequence constructor
  • any literal result element

xsl:character-map

 

Category: declaration

Model:

<xsl:character-map
  name = qname
  use-character-maps = qnames>
  <!-- Content: (xsl:output-character*) -->
</xsl:character-map>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:choose

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:comment

 

Category: instruction

Model:

<xsl:comment>
  <!-- Content: sequence-constructor -->
</xsl:comment>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:copy

 

Category: instruction

Model:

<xsl:copy
  copy-namespaces = "yes" | "no"
  use-attribute-sets = qnames
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname>
  <!-- Content: sequence-constructor -->
</xsl:copy>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:copy-of

 

Category: instruction

Model:

<xsl:copy-of
  select = expression
  copy-namespaces = "yes" | "no"
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname />

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:date-format

 

Category: declaration

Model:

<xsl:date-format
  name = qname
  language = nmtoken
  calendar = qname />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

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
  validation = "strict" | "lax" | "preserve" | "strip"
  type = qname>
  <!-- Content: sequence-constructor -->
</xsl:element>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:fallback

 

Category: instruction

Model:

<xsl:fallback>
  <!-- Content: sequence-constructor -->
</xsl:fallback>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:for-each

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is sequence 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
  collation = { uri }>
  <!-- Content: (xsl:sort*, sequence-constructor) -->
</xsl:for-each-group>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:function

 

Category: declaration

Model:

<xsl:function
  name = qname
  as = sequence-type
  override = "yes" | "no">
  <!-- Content: (xsl:param*, sequence-constructor) -->
</xsl:function>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:if

 

Category: instruction

Model:

<xsl:if
  test = expression>
  <!-- Content: sequence-constructor -->
</xsl:if>

Permitted parent elements:

  • any XSLT element whose content model is sequence 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
  as = qname
  collation = uri />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:matching-substring

 

Model:

<xsl:matching-substring>
  <!-- Content: sequence-constructor -->
</xsl:matching-substring>

Permitted parent elements:

  • xsl:analyze-string

xsl:message

 

Category: instruction

Model:

<xsl:message
  terminate = { "yes" | "no" }>
  <!-- Content: sequence-constructor -->
</xsl:message>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element
  • xsl:function

xsl:namespace

 

Category: instruction

Model:

<xsl:namespace
  name = { ncname }>
  <!-- Content: sequence-constructor -->
</xsl:namespace>

Permitted parent elements:

  • any XSLT element whose content model is sequence 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:next-match

 

Category: instruction

Model:

<xsl:next-match>
  <!-- Content: (xsl:with-param | xsl:fallback)* -->
</xsl:next-match>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:non-matching-substring

 

Model:

<xsl:non-matching-substring>
  <!-- Content: sequence-constructor -->
</xsl:non-matching-substring>

Permitted parent elements:

  • xsl:analyze-string

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 sequence constructor
  • any literal result element

xsl:otherwise

 

Model:

<xsl:otherwise>
  <!-- Content: sequence-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
  cdata-section-elements = qnames
  doctype-public = string
  doctype-system = string
  encoding = string
  escape-uri-attributes = "yes" | "no"
  include-content-type = "yes" | "no"
  indent = "yes" | "no"
  media-type = string
  normalize-unicode = "yes" | "no"
  omit-xml-declaration = "yes" | "no"
  standalone = "yes" | "no"
  undeclare-namespaces = "yes" | "no"
  use-character-maps = qnames
  version = nmtoken />

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:output-character

 

Model:

<xsl:output-character
  character = char
  string = string />

Permitted parent elements:

  • xsl:character-map

xsl:param

 

Category: declaration

Model:

<xsl:param
  name = qname
  select = expression
  as = sequence-type
  required = "yes" | "no">
  <!-- Content: sequence-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:processing-instruction

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:result-document

 

Category: instruction

Model:

<xsl:result-document
  format = qname
  href = { uri-reference }
  validation = "strict" | "lax" | "preserve" | "strip"
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:result-document>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:sequence

 

Category: instruction

Model:

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

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:sort

 

Model:

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

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
  xpath-default-namespace = uri
  default-validation = "strict" | "lax" | "preserve" | "strip">
  <!-- Content: (xsl:import*, other-declarations) -->
</xsl:stylesheet>

Permitted parent elements:

  • None

xsl:template

 

Category: declaration

Model:

<xsl:template
  match = pattern
  name = qname
  priority = number
  mode = tokens
  as = sequence-type>
  <!-- Content: (xsl:param*, sequence-constructor) -->
</xsl:template>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform

xsl:text

 

Category: instruction

Model:

<xsl:text
  disable-output-escaping = "yes" | "no">
  <!-- Content: #PCDATA -->
</xsl:text>

Permitted parent elements:

  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:transform

 

Model:

<xsl:transform
  id = id
  extension-element-prefixes = tokens
  exclude-result-prefixes = tokens
  version = number
  xpath-default-namespace = uri
  default-validation = "strict" | "lax" | "preserve" | "strip">
  <!-- Content: (xsl:import*, other-declarations) -->
</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 sequence constructor
  • any literal result element

xsl:variable

 

Category: declaration

Model:

<xsl:variable
  name = qname
  select = expression
  as = sequence-type>
  <!-- Content: sequence-constructor -->
</xsl:variable>

Permitted parent elements:

  • xsl:stylesheet
  • xsl:transform
  • xsl:function
  • any XSLT element whose content model is sequence constructor
  • any literal result element

xsl:when

 

Model:

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

Permitted parent elements:

  • xsl:choose

xsl:with-param

 

Model:

<xsl:with-param
  name = qname
  select = expression>
  <!-- Content: sequence-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 signal errors using these error codes, or that applications can test for these codes. Moreover, implementations are not required to signal errors using the descriptive text used here.

Static errors

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.

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.

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 date-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.

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 [of the xsl:stylesheet element] must be a number (specifically, it must be a DecimalLiteral as defined in [XPath 2.0].)

ERR011

It is a static error to submit to an XSLT 2.0 processor a stylesheet that specifies version="1.0" in the xsl:stylesheet element of the principal stylesheet module, or in the xsl:version attribute of the outermost element in the case of a simplified stylesheet module. This is a recoverable error. The processor may signal the error, or may recover by processing the stylesheet with backwards-compatible processing behavior enabled (see 3.6 Backwards-Compatible Processing).

ERR012

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

ERR013

It is a static error if the xsl:stylesheet element has a child element having a null namespace URI.

ERR014

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

ERR015

A literal result element that is used as the outermost element of a simplified stylesheet module must have an xsl:version attribute.

ERR018

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

ERR019

It is a static error if a stylesheet module directly or indirectly includes itself.

ERR020

The xsl:import declaration is allowed only as a top-level element.

ERR021

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.

ERR022

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

ERR023

It is a static error if two xsl:import-schema declarations for the same namespace have the same import precedence, unless there is another xsl:import-schema declaration for this namespace that has higher import precedence.

ERR024

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.

ERR025

It is a static error if both the namespace and the schema-location attributes [of the xsl:import-schema declaration] are specified, and the schema that is located is not a schema for the specified namespace.

ERR026

It is a static error if the schema-location attribute [of the xsl:import-schema declaration] is omitted, and the namespace attribute identifies a namespace whose schema is not known to the XSLT processor.

ERR027

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.

ERR029

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.

ERR031

Except where otherwise stated, it is a static error if the value of such an attribute [an attribute defined as containing an XPath expression] , 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.

ERR035

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

ERR036

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

ERR037

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.

ERR038

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.

ERR054

The value of this [the priority attribute of the xsl:template element] must be a decimal number (positive or negative), matching the production NumericLiteral with an optional leading minus sign (-).

ERR056

It is a static error if the same token is included more than once in the list [of modes in the mode attribute of xsl:template] or if the token #all appears together with any other value.

ERR064

It is a static error if a variable-binding element has a select attribute and has non-empty content.

ERR065

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.

ERR067

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

ERR068

It is a static error if a stylesheet contains an xsl:call-template instruction whose name attribute does not match the name attribute of any xsl:template in the stylesheet.

ERR069

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

ERR070

In the case of xsl:call-template, it is a static error to pass a parameter x to a template that does not have a template parameter named x.

ERR072

In the case of xsl:call-template, it is a static error if the template that is invoked declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction.

ERR075

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.

ERR076

The name attribute [of the xsl:function element] must be in a non-null namespace: that is, it must be written with a prefix.

ERR077

Because arguments to a stylesheet function call must all be specified, the xsl:param elements within an xsl:function element must not specify a default value: this means they must be empty, and must have no select attribute.

ERR078

It is a static error for a stylesheet to contain two or more functions with the same expanded-QName, the same arity, and the same import precedence, unless there is another function with the same expanded-QName and arity, and a higher import precedence.

ERR083

It is a static error if there is more than one such declaration [more than one xsl:namespace-alias declaration] with the same stylesheet-prefix and the same import precedence and different values for namespace-uri.

ERR098

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

ERR104

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.

ERR106

It is a static error if the current-group function is used within a pattern.

ERR107

It is a static error if the current-grouping-key function is used within a pattern.

ERR108

These four attributes [the group-by, group-adjacent, group-starting-with, and group-ending-with attributes of xsl:for-each-group ] are mutually exclusive: it is a static error if none of these four attributes is present, or if more than one of them is present.

ERR110

It is an error to specify the as attribute or the collation attribute if neither the group-by attribute nor group-adjacent attribute is specified.

ERR123

It is a static error if there are several xsl:key declarations in the stylesheet with the same key name and different types, or if the type is specified in one of these declarations and omitted in another.

ERR124

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.

ERR125

It is a static error if the value of the as attribute [of the xsl:key element] is not an atomic type (optionally followed by an occurrence count).

ERR126

It is a static error if a value is specified for the collation attribute [of the xsl:key element] unless the as attribute is defaulted or set to xs:string.

ERR131

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

ERR132

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.

ERR136

It is a static error to declare either the default date-format or a date-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 date-format, a declaration equivalent to an xsl:date-format element with no attributes is implied.

ERR137

It is a static error if an implementation does not support the language specified in the language attribute [of xsl:date-format] , or the calendar specified in the calendar attribute, or the combination of the two. The processor must either signal the error, or must recover by using a locale-specific value of the two attributes instead of the values specified. If a different calendar is used from that requested, the name of this calendar must be included in the result string.

ERR146

It is a static error if there is no namespace bound to the prefix on the element bearing the [xsl:]extension-element-prefixes attribute.

ERR149

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.

ERR155

It is a static error if the value of the type attribute of an xsl:element, xsl:attribute, xsl:copy, or xsl:copy-of instruction, or the xsl:type attribute of a literal result element, is not a valid QName, or if it uses a prefix that is not defined in an in-scope namespace declaration, or if the QName is not the name of a built-in type or of a top-level type definition present in an imported schema.

ERR156

It is a static error if the value of the type attribute of an xsl:attribute instruction refers to a complex type definition

ERR161

It is a static error if the stylesheet contains two or more character maps with the same name and the same import precedence.

ERR162

It is a static error if a name in the use-character-maps attribute does not match the name attribute of any xsl:character-map in the stylesheet.

ERR163

It is a static error if a character map references itself, directly or indirectly, via a name in the use-character-maps attribute.

ERR168

A basic XSLT processor must signal a static error if the stylesheet includes an xsl:import-schema declaration.

ERR169

A basic XSLT processor must signal a static error if the stylesheet includes an [xsl:]type attribute, or an [xsl:]validation or default-validation attribute with a value other than strip.

Type errors

ERR033

It is a type error if an XPath expression raises a type error, or if the type of the XPath expression is incompatible with the required type.
    Action: The processor must signal the error.

ERR051

The result of evaluating the sequence constructor [contained in an xsl:template declaration] is converted to the required type using the argument conversion rules. A type error occurs if this conversion is unsuccessful.
    Action: Like other type errors, this error may be signaled statically if it can be detected statically.

ERR053

It is a type error if the sequence returned by the select expression [of xsl:apply-templates] contains an item that is not a node.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the items that are not nodes. As with other type errors, the error may be signaled statically if it can be detected statically.

ERR059

If the as attribute [of xsl:variable] is specified, then the supplied value of the variable is converted to the required type, using the argument conversion rules. It is a type error if this conversion fails.
    Action: The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

ERR061

If the as attribute [of xsl:param] is specified, then the supplied value of the parameter is converted to the required type, using argument conversion rules. It is a type error if this conversion fails.

ERR063

If the value of the required attribute is no, and the caller supplies no value for the parameter, then it is a type error if the default value of the parameter cannot be converted to the required type, using the argument conversion rules.

ERR079

If the as attribute [of xsl:function ] is specified, then the result evaluated by the sequence constructor is converted to the required type, using the argument conversion rules. It is a type error if this conversion fails.

ERR095

If the computed value [of the sequence returned by xsl:sequence] cannot be converted to the required type, a type error occurs.
    Action: The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

ERR100

If the value of any sort key, after atomization and any type conversion required by the data-type attribute, is a sequence containing more than one item, then the effect depends on whether the xsl:sort element is evaluated with backwards compatible behavior. With backwards compatible behavior, the effective value of the sort key is the first item in the sequence. In other cases, this is a type error.
    Action: The processor must signal the error.

ERR150

A type error occurs if the document node at the root of the result tree, after validation, does not match the SequenceType contained in the as attribute [of the xsl:result-document element] .

ERR154

If the validation attribute of an xsl:element, xsl:attribute, xsl:copy, or xsl:copy-of instruction, or the xsl:validation attribute of a literal result element, has the effective value strict or lax, and schema validity assessment concludes that the element or attribute is invalid, a type error occurs.
    Action: The processor must signal the error. As with other type errors, the error may be signaled statically if it can be detected statically.

ERR157

It is a type error if an [xsl:]type attribute is defined for a constructed element or attribute, and the outcome of schema validity assessment against that type is that the validity property of that element or attribute information item is other than valid.

ERR158

A type error occurs if strict or lax validation is requested for a final result tree unless the children of the document node comprise exactly one element node, no text nodes, and zero or more comment and processing instruction nodes, in any order.
    Action: The processor must signal the error. Like other type errors, the error may be signaled statically if it can be detected statically.

Dynamic errors

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.

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.

ERR005

It is a dynamic error if the initial template defines a template parameter that specifies required="yes".
    Action: The processor must signal the error.

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.
    Action: The processor must signal the error.

ERR017

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.

ERR028

It is a 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: This is a recoverable error. 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.

ERR030

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.
    Action: The required action depends on the defining element.

ERR032

The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error.
    Action: The processor must signal the error.

ERR034

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.

ERR039

A dynamic error occurs if the sequence [being used to construct the content of an element or document node] contains an atomic value of type xs:NOTATION, because such values cannot be cast to a string.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending xs:NOTATION value.

ERR040

A dynamic error occurs [when the result sequence contains an atomic value of type xs:QName] if the node whose content is being constructed is a document node.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending xs:QName value.

ERR041

A dynamic error occurs [when the result sequence contains an atomic value of type xs:QName] if the node whose content is being constructed is an element that has no in-scope namespace that declares the namespace URI of the xs:QName value.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by adding a namespace node to the element under construction, and converting the xs:QName value to a string using the namespace prefix declared by this namespace node. The choice of namespace prefix is implementation-defined

ERR042

It is a dynamic error if the result sequence used to construct the content of an element node contains a namespace node or attribute node that is preceded in the sequence by a node that is neither a namespace node nor an attribute node.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace or attribute node.

ERR043

It is a dynamic error if the result sequence used to construct the content of a document node contains a namespace node or attribute node.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace or attribute node.

ERR044

It is a dynamic error if the result sequence contains two or more namespace nodes having the same name but different string values (that is, namespace nodes that map the same prefix to different namespace URIs).
    Action: This is a recoverable error. The processor must either signal the error, or must recover by discarding all conflicting namespace nodes other than the one that appears last in the result sequence.

ERR045

It is a dynamic error if the result sequence contains a namespace node with no name and the element node being constructed has a null namespace URI (that is, it is an error to define a default namespace when the element is in no namespace).
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the offending namespace node.

ERR046

A dynamic error occurs if the sequence [being used to construct the content of an attribute, namespace, comment, or processing-instruction node] contains a value of type xs:NOTATION, because such values cannot be cast to a string.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the xs:NOTATION value.

ERR047

A dynamic error occurs if the sequence being used to construct the content of a namespace, comment, or processing-instruction node contains an atomic value of type xs:QName, because such values cannot be cast to a string without knowledge of the namespace context.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the xs:QName value.

ERR048

A dynamic error occurs if the sequence being used to construct the content of an attribute node contains an atomic value of type xs:QName, because such values cannot be cast to a string without knowledge of the namespace context.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by converting the xs:QName value to a string using the namespace declarations that are in scope for the element to which the constructed attribute is eventually attached; if necessary, an additional namespace node may be attached to such an element to declare the required namespace; the namespace prefix used in any such namespace node is implementation-defined.

ERR049

It is a dynamic error if the result sequence [produced by the xsl:comment, xsl:attribute, xsl:processing-instruction, or xsl:namespace elements] contains nodes other than text nodes.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the non-text nodes together with their content.

ERR050

It is a dynamic error if such a document [a source document, a document returned by the document, doc or collection function 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: This is a recoverable error. The processor may signal the error, or may recover by performing namespace fixup, or may produce implementation-dependent results.

ERR052

It is a dynamic error if [xsl:apply-templates with no select attribute is evaluated when] the context item is not a node.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

ERR055

It is a dynamic error if this [the conflict resolution algorithm for template rules] leaves more than one matching template rule.
    Action: This is a recoverable error. 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.

ERR058

It is a dynamic error if xsl:apply-imports or xsl:next-match is evaluated when the current template rule is null.
    Action: The processor must signal the error.

ERR066

In general, a circularity in a stylesheet is a dynamic error.
    Action: The processor must signal the error.

ERR071

In the case of xsl:apply-templates, xsl:apply-imports, and xsl:next-match it is a dynamic error if the template that is invoked declares a template parameter with required="yes" and no value for this parameter is supplied by the calling instruction.
    Action: The processor must signal the error.

ERR073

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

ERR074

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: This is a recoverable error. 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.

ERR080

It is a static error if the number of arguments supplied in the function call is different from the number of xsl:param elements in the function definition.

ERR081

Within the body of a stylesheet function, the focus is initially undefined; this means that any attempt to reference the context item, context position, or context size is a dynamic error.
    Action: The processor must signal the error.

ERR084

It is a dynamic error if the effective value [of the name attribute of the xsl:element instruction] is not a QName.
    Action: This is a recoverable error. 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 and namespace nodes.

ERR085

In the case of an xsl:element instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:element instruction.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

ERR086

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: This is a recoverable error. The processor must either signal the error, or must recover by not adding the attribute to the result tree.

ERR087

In the case of an xsl:attribute instruction with no namespace attribute, it is a dynamic error if the effective value of the name attribute is a QName whose prefix is not declared in an in-scope namespace declaration for the xsl:attribute instruction.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the prefix part of the QName.

ERR089

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: This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

ERR090

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

ERR091

It is a dynamic error if the effective value of the name attribute [of the xsl:namespace instruction] is neither a zero-length string nor an NCName.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

ERR092

It is a dynamic error if evaluating the content of xsl:namespace results in a zero-length string.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

ERR093

It is a dynamic error if the result of evaluating the content of the xsl:comment contains the string -- or ends with -.
    Action: This is a recoverable error. 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.

ERR096

It is a dynamic error if any undiscarded 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: This is a recoverable error. The processor must either signal the error, or must recover by converting that item 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.

ERR097

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: This is a recoverable error. The processor must either signal the error, or must recover by returning an empty sequence.

ERR102

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 ordinary values for which the result of the XPath lt operator is an error.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by assigning an arbitrary ordering to any such pair of values.

ERR105

It is a dynamic error if the $sort-spec-name argument of the sort function is not a valid QName, or if its prefix is not declared in an in-scope namespace declaration, or if it does not match the name of any named sort specification in the stylesheet.
    Action: The processor must signal the error. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

ERR111

It is a type error if the result of the group-adjacent attribute is an empty sequence, or a sequence containing more than one item.
    Action: The processor must signal the error.

ERR112

It is a type error if the set of grouping keys obtained by evaluating the group-by or group-adjacent attributes for all items in the population contains two items that are not comparable using the eq operator.
    Action: The processor must signal the error.

ERR114

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.

ERR115

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.

ERR116

It is a dynamic error if the effective value of the regex attribute [of the xsl:analyze-string instruction] does not conform to the required syntax for regular expressions, as specified in [Functions and Operators], or if the effective value of the flags attribute has a value other than the values defined in [Functions and Operators].
    Action: The processor must signal the error. If the regular expression and/or flags are known statically (for example, if the attributes do not contain any expressions enclosed in curly braces) then the processor may signal the error as a static error.

ERR117

It is a dynamic error if the effective value of the regex attribute [of the xsl:analyze-string instruction] is a regular expression that matches a zero-length string .
    Action: The processor must signal the error. If the regular expression is known statically (for example, if the attribute does not contain any expressions enclosed in curly braces) then the processor may signal the error as a static error.

ERR118

When a URI reference [supplied to the document function] contains a fragment identifier, it is a dynamic error if the media type is not one that is recognized by the processor, or if the fragment identifier does not conform to the rules for fragment identifiers for that media type, or if the fragment identifier selects something other than a sequence of nodes (for example, if it selects a range of characters within a text node).
    Action: This is a recoverable error. The processor may signal the error, or may recover by ignoring the fragment identifier and returning the document node.

ERR119

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: This is a recoverable error. 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.

ERR120

It is a dynamic error if a resource [retrieved using the unparsed-text function] contains characters that are not permitted XML characters.
    Action: This is a recoverable error. The processor must either signal the error, or must recover in an implementation-defined way; one possible outcome is that the processor will produce an output file that is not well-formed XML.

ERR121

It is a dynamic error if a resource [retrieved using the unparsed-text function] contains octets that cannot be decoded into permitted 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.

ERR122

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.

ERR127

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 type specified by the as attribute.
    Action: This is a recoverable error. The processor may signal the error, or may recover by ignoring the existence of the value that cannot be converted.

ERR128

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 xsl:key declaration in the stylesheet.
    Action: The processor must signal these errors. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

ERR129

It is a dynamic error to call the key function if there is no context node, or if the root of the tree containing the context node is not a document node.
    Action: The processor must signal the error.

ERR130

It is a dynamic error if the name specified as the $decimal-format-name argument [ to the format-number function] is not a valid QName, or if its prefix has not been declared in an in-scope namespace declaration, or if the stylesheet does not contain a declaration of a decimal-format with a matching expanded-QName . If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the $decimal-format-name argument.

ERR133

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: This is a recoverable error. The processor must either signal the error, or may recover by ignoring those characters in the supplied picture string that make the picture string invalid. If a valid picture string cannot be constructed in this way, the processor may recover by returning the string obtained by applying the string function to the supplied number.

ERR134

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: This is a recoverable error. The processor may signal the error, or may recover by formatting the number as if each zero-digit-sign character in the integer part of the sub-picture were a digit-sign.

ERR135

It is a dynamic error if the name specified as the $date-format-name argument is not a valid QName, or if its prefix has not been declared in an in-scope namespace declaration, or if the stylesheet does not contain a declaration of a date-format with a matching expanded-QName.
    Action: The processor must either signal the error, or must recover by ignoring the $date-format-name argument. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

ERR138

It is a dynamic error if a component specifier within the picture [used for date/time formatting] refers to components that are not available in the given $value, or which are not supported in the chosen calendar.
    Action: This is a recoverable error. The processor may signal the error, or may recover by ignoring the offending component specifiers.

ERR139

If the current function is evaluated within an expression that is evaluated when the context item is undefined, a dynamic error occurs.
    Action: The processor must signal the error.

ERR140

It is a dynamic error if the unparsed-entity-uri is called when there is no context node, or when the root of the tree containing the context node is not a document node.
    Action: The processor must signal the error.

ERR141

It is a dynamic error if the unparsed-entity-public-id is called when there is no context node, or when the root of the tree containing the context node is not a document node.
    Action: The processor must signal the error.

ERR142

It is a dynamic error if the value [supplied as the $property-name 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. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
    Action: The processor must signal these errors.

ERR143

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. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by returning the value false.

ERR144

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.

ERR145

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.

ERR147

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: This is a recoverable error. The processor must either signal the error, or must recover by returning the value false. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

ERR148

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; it is a dynamic error if it has no xsl:fallback children.
    Action: This error must be signaled.

ERR151

It is a dynamic error to evaluate the xsl:result-document instruction in temporary output state.
    Action: The processor must signal the error.

ERR152

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.

ERR153

It is a dynamic error for a stylesheet to write to an external resource and read from the same resource during a single transformation, whether or not the same URI is used to access the resource in both cases.
    Action: The effect of this error is implementation-dependent: implementations are not obliged to detect it.

ERR159

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 and use-character-maps), with the 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: This is a recoverable error. The processor must either signal the error, or must recover by using the value that occurs last in declaration order.

ERR164

It is a dynamic error for output escaping to be disabled for an xsl:value-of or xsl:text instruction that is used to generate 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.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by ignoring the disable-output-escaping attribute.

ERR171

A basic XSLT processor constrains the data model as follows. Atomic values must belong to one of the atomic types available in the static context (that is, they may only use built-in types, or types defined for use by extension functions, but not derived types defined in a schema). Element nodes must be annotated with the type annotation xs:anyType, and attribute nodes with the type annotation xdt:untypedAtomic. This rule means that a basic XSLT processor must not accept as input, or generate as intermediate or final results, any value that exceeds these constraints. If any instruction or expression in the stylesheet would cause these constraints to be violated, the processor must signal a dynamic error

ERR172

A processor that does not claim conformance with the backwards compatibility feature must raise a dynamic error if an instruction is evaluated containing an [xsl:]version attribute that invokes backwards compatible behavior.

Serialization errors

ERR160

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 [XSLT and XQuery Serialization] and must be one of xml, html, xhtml, or text.

ERR165

It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled and the implementation does not support this.
    Action: This is a recoverable error. The processor must either signal the error, or must recover by not disabling output escaping.

ERR166

It is a serialization error if an xsl:value-of or xsl:text instruction specifies that output escaping is to be disabled when when writing to a result tree that is not being serialized.
    Action: This is a recoverable error. The processor must either signal the error, of must recover by not disabling output escaping.

ERR167

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: This is a recoverable error. 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. The conformance rules (see 21 Conformance) require vendors to provide documentation that explains how these choices have been exercised.

  1. The way in which an XSLT processor is invoked, and the specification of the source document, starting node, and values for stylesheet parameters, are implementation-defined. (See 2 Concepts)

  2. The mechanisms for creating new extension instructions and extension functions are implementation-defined. (See 2 Concepts)

  3. Where the specification provides a choice between signaling a dynamic error or recovering, the decision that is made (but not the recovery action itself) is implementation-defined. (See 2 Concepts)

  4. It is implementation-defined whether type errors are signaled statically. (See 2 Concepts)

  5. The handling of serialization errors is implementation-defined. (See 2 Concepts)

  6. The set of namespaces that are recognized for additional attributes on XSLT instructions is implementation-defined. (See 3 Stylesheet Structure)

  7. An implementation may reserve one or more namespaces for use by the implementation, provided these follow accepted practice to avoid naming collisions. (See 3 Stylesheet Structure)

  8. The set of namespaces that are specially recognized for user-defined data elements (other than the XSLT namespace) is implementation-defined. (See 3 Stylesheet Structure)

  9. It is implementation-defined whether an XSLT 2.0 processor supports backwards-compatible behavior. (See 3 Stylesheet Structure)

  10. The forms of fragment identifier permitted on the URI reference passed to the xsl:include and xsl:import elements, as well as the document function, are implementation-defined. (See 3 Stylesheet Structure)

  11. The precise way in which an implementation uses the namespace and/or schema-location attributes of the xsl:import-schema declaration to locate schema definitions is implementation-defined. (See 3 Stylesheet Structure)

  12. The set of URI references that may be used to identify collations, and the choice of default collation, are implementation-defined. (See 5 Syntactic Constructs)

  13. The numbering sequences supported by the xsl:number instructions, beyond those defined in this specification, is implementation-defined. (See 12 Numbering)

  14. There may be implementation-defined upper bounds on the numbers that can be formatted by xsl:number using any particular numbering sequence. (See 12 Numbering)

  15. The set of languages for which numbering is supported by xsl:number is implementation-defined. (See 12 Numbering)

  16. The facilities for defining collations and allocating URIs to identify them, including facilities for defining the default collation, are implementation-defined. (See 13 Sorting)

  17. If the data-type attribute of the xsl:sort element has a value other than text or number, the effect is implementation-defined. (See 13 Sorting)

  18. The mechanisms used to define collations are implementation-defined. (See 13 Sorting)

  19. The algorithm used by xsl:sort to select a collation, given the values of the lang and case-order attributes, is implementation-defined. (See 13 Sorting)

  20. The set of media types recognized by the processor, for the purpose of interpreting fragment identifiers in URI references passed to the document function, is implementation-defined. (See 16 Additional Functions)

  21. The recovery action when the resource identified by the unparsed-text function contains characters not permitted by the XML Recommendation is implementation-defined. (See 16 Additional Functions)

  22. If no language attribute is specified in an xsl:date-format declaration, the default is implementation-defined. (See 16 Additional Functions)

  23. The set of languages that are supported in the xsl:date-format declaration is implementation-defined. (See 16 Additional Functions)

  24. It is implementation-defined which calendars are supported by the date formatting functions. (See 16 Additional Functions)

  25. The choice of the names and abbreviations used in any given language for calendar units such as days of the week and months of the year is implementation-defined. (See 16 Additional Functions)

  26. The values returned by the system-property function, and the names of the additional properties that are recognized, are implementation-defined. (See 16 Additional Functions)

  27. The destination and formatting of messages written using the xsl:message instruction are implementation-defined. (See 17 Messages)

  28. The effect of an extension function returning a string containing characters that are not legal in XML is implementation-defined. (See 18 Extensibility and Fallback)

  29. The way in which external objects are represented in the type system is implementation-defined. (See 18 Extensibility and Fallback)

  30. The way in which a result tree is delivered to an application is implementation-defined. (See 19 Result Trees)

  31. Implementations may provide additional mechanisms allowing users to define the way in which result trees are processed. (See 19 Result Trees)

  32. If serialization is supported, then the location to which a result tree is serialized is implementation-defined, subject to the constraint that relative URIs used to reference one tree from another remain valid. (See 20 Serialization)

  33. The default value of the encoding attribute of the xsl:output element is implementation-defined. (See 20 Serialization)

  34. It is implementation-defined whether, and under what circumstances, disabling output escaping is supported. (See 20 Serialization)

F Schema for XSLT Stylesheets (Non-Normative)

The following schema describes the structure of an XSLT stylesheet module. It does not define all the constraints that apply to a stylesheet (for example, it does not attempt to define a data type that precisely represents attributes containing XPath expressions), but every valid stylesheet module conforms to this schema.

<?xml version="1.0" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="http://www.w3.org/1999/XSL/Transform"
           elementFormDefault="qualified"
           xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<xs:annotation>
  <xs:documentation>
  
    This is a schema for XSLT 2.0 stylesheets.
    
    It defines all the elements that appear in the XSLT namespace; it also
    provides hooks that allow the inclusion of user-defined literal result elements,
    extension instructions, and top-level data elements.
    
    The schema is derived (with kind permission) from a schema for XSLT 1.0 stylesheets
    produced by Asir S Vedamuthu of WebMethods Inc.
    
    This schema is available for use under the conditions of the W3C Software License
    published at http://www.w3.org/Consortium/Legal/copyright-software-19980720
    
    The schema is organized as follows:
    
    PART A: definitions of complex types and model groups used as the basis 
            for element definitions
    PART B: definitions of individual XSLT elements
    PART C: definitions for literal result elements
    PART D: definitions of simple types used in attribute definitions
    
    This schema does not attempt to define all the constraints that apply to a valid
    XSLT 2.0 stylesheet. It is the intention that all valid stylesheets should conform
    to this schema; however, the schema is non-normative and in the event of any
    conflict, the text of the Recommendation takes precedence.
    
    This version is dated 2003-04-22
    Authors: Michael H Kay, Software AG
             Jeni Tennison, Jeni Tennison Consulting Ltd.
    
  </xs:documentation>
</xs:annotation>   
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<!-- 

The declaration of xml:space and xml:lang has been commented out because
of problems processing the schema using various tools
      
<xs:import namespace="http://www.w3.org/XML/1998/namespace" 
  schemaLocation="http://www.w3.org/2001/xml.xsd"/>
  
-->
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<xs:annotation>
  <xs:documentation>
    PART A: definitions of complex types and model groups used as the basis 
            for element definitions
  </xs:documentation>
</xs:annotation>   
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<xs:complexType name="generic-element-type">
  <xs:attribute name="extension-element-prefixes" type="xsl:prefixes"/>
  <xs:attribute name="exclude-result-prefixes" type="xsl:prefixes"/>
  <xs:attribute name="xpath-default-namespace" type="xs:anyURI"/>
  <!--attribute ref="xml:space"/-->      
  <!--attribute ref="xml:lang"/-->    
  <xs:anyAttribute namespace="##other" processContents="skip"/>
</xs:complexType>

<xs:complexType name="versioned-element-type">
  <xs:complexContent>
    <xs:extension base="xsl:generic-element-type">    
      <xs:attribute name="version" type="xs:decimal" use="optional"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

<xs:complexType name="sequence-constructor">
  <xs:complexContent mixed="true">
    <xs:extension base="xsl:versioned-element-type">    
      <xs:group ref="xsl:sequence-constructor-group" minOccurs="0" maxOccurs="unbounded"/>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

<xs:group name="sequence-constructor-group">
  <xs:choice>
    <xs:element ref="xsl:variable"/>
    <xs:element ref="xsl:instruction"/>
    <xs:group ref="xsl:result-elements"/>
  </xs:choice>
</xs:group>

<xs:element name="declaration" type="xsl:generic-element-type" abstract="true"/>

<xs:element name="instruction" type="xsl:versioned-element-type" abstract="true"/>

<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<xs:annotation>
  <xs:documentation>
    PART B: definitions of individual XSLT elements    
    Elements are listed in alphabetical order.    
  </xs:documentation>
</xs:annotation>   
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<xs:element name="analyze-string" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:matching-substring" minOccurs="0"/>
          <xs:element ref="xsl:non-matching-substring" minOccurs="0"/>
          <xs:element ref="xsl:fallback" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="select" type="xsl:expression" use="required" />
        <xs:attribute name="regex" type="xsl:avt" use="required" />
        <xs:attribute name="flags" type="xsl:avt" default="" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="apply-imports" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:with-param" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="apply-templates" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element ref="xsl:sort"/>
          <xs:element ref="xsl:with-param"/>
        </xs:choice>
        <xs:attribute name="select" type="xsl:expression" default="child::node()"/>
        <xs:attribute name="mode" type="xsl:mode"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="attribute" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xsl:avt" use="required"/>
        <xs:attribute name="namespace" type="xsl:avt"/>
        <xs:attribute name="type" type="xs:QName"/>
        <xs:attribute name="validation" type="xsl:validation-type"/>
        <xs:attribute name="disable-output-escaping" type="xsl:yes-or-no" default="no"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>        

<xs:element name="attribute-set" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence minOccurs="0" maxOccurs="unbounded">
          <xs:element ref="xsl:attribute"/>
        </xs:sequence>
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="use-attribute-sets" type="xsl:QNames" default=""/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="call-template" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:with-param" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="name" type="xs:QName" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="character-map" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:output-character" minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="name" type="xs:QName" use="required" />
        <xs:attribute name="use-character-maps" type="xsl:QNames" default="" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="choose" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:when" maxOccurs="unbounded"/>
          <xs:element ref="xsl:otherwise" minOccurs="0" />
        </xs:sequence>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="comment" substitutionGroup="xsl:instruction" 
            type="xsl:sequence-constructor"/>

<xs:element name="copy" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="copy-namespaces" type="xsl:yes-or-no" default="yes" />
        <xs:attribute name="use-attribute-sets" type="xsl:QNames" default="" />
        <xs:attribute name="type" type="xs:QName" />
        <xs:attribute name="validation" type="xsl:validation-type" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="copy-of" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="select" type="xsl:expression" use="required"/>
        <xs:attribute name="copy-namespaces" type="xsl:yes-or-no" default="yes" />
        <xs:attribute name="type" type="xs:QName" />
        <xs:attribute name="validation" type="xsl:validation-type" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="date-format" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="name" type="xs:QName"/>
        <xs:attribute name="language" type="xs:language"/>
        <xs:attribute name="calendar" type="xs:QName"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="decimal-format" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="name" type="xs:QName"/>
        <xs:attribute name="decimal-separator" type="xsl:char" default="."/>
        <xs:attribute name="grouping-separator" type="xsl:char" default=","/>
        <xs:attribute name="infinity" type="xs:string" default="Infinity"/>
        <xs:attribute name="minus-sign" type="xsl:char" default="-"/>
        <xs:attribute name="NaN" type="xs:string" default="NaN"/>
        <xs:attribute name="percent" type="xsl:char" default="%"/>
        <xs:attribute name="per-mille" type="xsl:char" default="&#x2030;"/>
        <xs:attribute name="zero-digit" type="xsl:char" default="0"/>
        <xs:attribute name="digit" type="xsl:char" default="#"/>
        <xs:attribute name="pattern-separator" type="xsl:char" default=";"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="element" substitutionGroup="xsl:instruction">
  <xs:complexType mixed="true">
    <xs:complexContent>
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xsl:avt" use="required"/>
        <xs:attribute name="namespace" type="xsl:avt" />
        <xs:attribute name="use-attribute-sets" type="xsl:QNames" default="" />
        <xs:attribute name="type" type="xs:QName" />
        <xs:attribute name="validation" type="xsl:validation-type" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="fallback" substitutionGroup="xsl:instruction" 
            type="xsl:sequence-constructor"/>

<xs:element name="for-each" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:sort" minOccurs="0" maxOccurs="unbounded"/>
          <xs:group ref="xsl:sequence-constructor-group" 
                    minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="select" type="xsl:expression" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="for-each-group" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:sort" minOccurs="0" maxOccurs="unbounded"/>
          <xs:group ref="xsl:sequence-constructor-group"
                    minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="select" type="xsl:expression" use="required"/>
        <xs:attribute name="group-by" type="xsl:expression"/>
        <xs:attribute name="group-adjacent" type="xsl:expression"/>            
        <xs:attribute name="group-starting-with" type="xsl:pattern"/>            
        <xs:attribute name="group-ending-with" type="xsl:pattern"/>            
        <xs:attribute name="collation" type="xs:anyURI"/>            
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="function" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:param" minOccurs="0" maxOccurs="unbounded"/>
          <xs:group ref="xsl:sequence-constructor-group"
                    minOccurs="0" maxOccurs="unbounded" />
        </xs:sequence>
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="override" type="xsl:yes-or-no" default="yes"/>
        <xs:attribute name="as" type="xsl:sequence-type" default="item()*"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="if" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="test" type="xsl:expression" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="import">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="href" type="xs:anyURI" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="import-schema" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="namespace" type="xs:anyURI"/>
        <xs:attribute name="schema-location" type="xs:anyURI"/>                  
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="include" substitutionGroup="xsl:declaration">
    <xs:complexType>
      <xs:complexContent>
        <xs:extension base="xsl:versioned-element-type">
          <xs:attribute name="href" type="xs:anyURI" use="required"/>
        </xs:extension>
      </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="key" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="match" type="xsl:pattern" use="required"/>
        <xs:attribute name="use" type="xsl:expression" use="required"/>
        <xs:attribute name="collation" type="xs:anyURI"/>            
        <xs:attribute name="as" type="xs:QName" default="xs:string"/>    
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="matching-substring" type="xsl:sequence-constructor"/>

<xs:element name="message" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="terminate" type="xsl:avt" default="no"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="namespace" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xsl:avt" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="namespace-alias" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="stylesheet-prefix" type="xsl:prefix-or-default" use="required"/>
        <xs:attribute name="result-prefix" type="xsl:prefix-or-default" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="next-match" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:element ref="xsl:with-param" />
          <xs:element ref="xsl:fallback" />
        </xs:choice>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="non-matching-substring" type="xsl:sequence-constructor"/>

<xs:element name="number" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="level" type="xsl:level" default="single"/>
        <xs:attribute name="count" type="xsl:pattern"/>
        <xs:attribute name="from" type="xsl:pattern"/>
        <xs:attribute name="value" type="xsl:expression"/>
        <xs:attribute name="format" type="xsl:avt" default="1"/>
        <xs:attribute name="lang" type="xsl:avt"/>
        <xs:attribute name="letter-value" type="xsl:avt"/>
        <xs:attribute name="grouping-separator" type="xsl:avt"/>
        <xs:attribute name="grouping-size" type="xsl:avt"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="otherwise" type="xsl:sequence-constructor"/>

<xs:element name="output" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:generic-element-type">
        <xs:attribute name="name" type="xs:QName" />
        <xs:attribute name="method" type="xsl:method"/>
        <xs:attribute name="cdata-section-elements" type="xsl:QNames"/>
        <xs:attribute name="doctype-public" type="xs:string"/>
        <xs:attribute name="doctype-system" type="xs:string"/>
        <xs:attribute name="encoding" type="xs:string"/>
        <xs:attribute name="escape-uri-attributes" type="xsl:yes-or-no"/>
        <xs:attribute name="include-content-type" type="xsl:yes-or-no"/>
        <xs:attribute name="indent" type="xsl:yes-or-no"/>
        <xs:attribute name="media-type" type="xs:string"/>
        <xs:attribute name="normalize-unicode" type="xsl:yes-or-no"/>
        <xs:attribute name="omit-xml-declaration" type="xsl:yes-or-no"/>
        <xs:attribute name="standalone" type="xsl:yes-or-no"/>
        <xs:attribute name="undeclare-namespaces" type="xsl:yes-or-no" />
        <xs:attribute name="use-character-maps" type="xsl:QNames" />
        <xs:attribute name="version" type="xs:NMTOKEN"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="output-character">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="character" type="xsl:char" use="required" />
        <xs:attribute name="string" type="xs:string" use="required" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="param">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="select" type="xsl:expression"/>
        <xs:attribute name="as" type="xsl:sequence-type"/>
        <xs:attribute name="required" type="xsl:yes-or-no"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="preserve-space" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="elements" type="xsl:nametests" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="processing-instruction" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xsl:avt" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="result-document" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="format" type="xs:QName"/>
        <xs:attribute name="href" type="xsl:avt"/>
        <xs:attribute name="validation" type="xsl:validation-type"/>
        <xs:attribute name="as" type="xsl:sequence-type"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="sequence" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="select" type="xsl:expression"/>
        <xs:attribute name="as" type="xsl:sequence-type"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="sort">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="select" type="xsl:expression" default="."/>  
        <xs:attribute name="lang" type="xsl:avt"/>        
        <xs:attribute name="data-type" type="xsl:avt" default="text"/>        
        <xs:attribute name="order" type="xsl:avt" default="ascending"/>        
        <xs:attribute name="case-order" type="xsl:avt"/>
        <xs:attribute name="collation" type="xsl:avt"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="sort-key" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:sort" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="name" type="xs:QName" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="strip-space" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="elements" type="xsl:nametests" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="stylesheet" substitutionGroup="xsl:transform"/>

<xs:element name="template" substitutionGroup="xsl:declaration">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:versioned-element-type">
        <xs:sequence>
          <xs:element ref="xsl:param" minOccurs="0" maxOccurs="unbounded"/>
          <xs:group ref="xsl:sequence-constructor-group"
                    minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="match" type="xsl:pattern"/>
        <xs:attribute name="priority" type="xs:decimal"/>
        <xs:attribute name="mode" type="xsl:modes"/>
        <xs:attribute name="name" type="xs:QName"/>
        <xs:attribute name="as" type="xsl:sequence-type" default="item()*"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="text" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="disable-output-escaping" type="xsl:yes-or-no" default="no"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="transform">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:generic-element-type">
        <xs:sequence>
          <xs:element ref="xsl:import" minOccurs="0" maxOccurs="unbounded"/>
          <xs:choice minOccurs="0" maxOccurs="unbounded">
            <xs:element ref="xsl:declaration"/>
            <xs:element ref="xsl:variable"/>
            <xs:element ref="xsl:param"/>              
            <xs:any namespace="##other" processContents="lax"/> <!-- weaker than XSLT 1.0 -->
          </xs:choice>
        </xs:sequence>
        <xs:attribute name="id" type="xs:ID"/>
        <xs:attribute name="version" type="xs:decimal" use="required"/>
        <xs:attribute name="default-validation" type="xsl:validation-type" default="strip"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="value-of" substitutionGroup="xsl:instruction">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="xsl:versioned-element-type">
        <xs:attribute name="select" type="xsl:expression" use="required"/>
        <xs:attribute name="separator" type="xsl:avt"/>            
        <xs:attribute name="disable-output-escaping" type="xsl:yes-or-no" default="no"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="variable">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="select" type="xsl:expression" use="optional"/>
        <xs:attribute name="as" type="xsl:sequence-type" use="optional"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="when">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="test" type="xsl:expression" use="required"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<xs:element name="with-param">
  <xs:complexType>
    <xs:complexContent mixed="true">
      <xs:extension base="xsl:sequence-constructor">
        <xs:attribute name="name" type="xs:QName" use="required"/>
        <xs:attribute name="select" type="xsl:expression"/>
        <xs:attribute name="as" type="xsl:sequence-type"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<xs:annotation>
  <xs:documentation>
    PART C: definition of literal result elements
    
    There are three ways to define the literal result elements
    permissible in a stylesheet.
    
    (a) do nothing. This allows any element to be used as a literal
        result element, provided it is not in the XSLT namespace
    
    (b) declare all permitted literal result elements as members
        of the xsl:literal-result-element substitution group
        
    (c) redefine the model group xsl:result-elements to accommodate
        all permitted literal result elements.
        
    Literal result elements are allowed to take certain attributes
    in the XSLT namespace. These are defined in the attribute group
    literal-result-element-attributes, which can be included in the
    definition of any literal result element.
    
  </xs:documentation>
</xs:annotation>   
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<xs:element name="literal-result-element" abstract="true" type="xs:anyType"/>

<xs:attributeGroup name="literal-result-element-attributes">
  <xs:attribute name="extension-element-prefixes" form="qualified" type="xsl:prefixes"/>
  <xs:attribute name="exclude-result-prefixes" form="qualified" type="xsl:prefixes"/>
  <xs:attribute name="xpath-default-namespace" form="qualified" type="xs:anyURI"/>    
  <xs:attribute name="use-attribute-sets" form="qualified" type="xsl:QNames" default=""/>
  <xs:attribute name="version" form="qualified" type="xs:decimal"/>
  <xs:attribute name="type" form="qualified" type="xs:QName"/>
  <xs:attribute name="validation" form="qualified" type="xsl:validation-type"/>
</xs:attributeGroup>

<xs:group name="result-elements">
  <xs:choice>
    <xs:element ref="xsl:literal-result-element"/>
    <xs:any namespace="##other" processContents="lax"/>
    <xs:any namespace="##local" processContents="lax"/>
  </xs:choice>
</xs:group>


<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
<xs:annotation>
  <xs:documentation>
    PART D: definitions of simple types used in stylesheet attributes 
  </xs:documentation>
</xs:annotation>   
<!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->

<xs:simpleType name="avt">
  <xs:annotation>
    <xs:documentation>
      This type is used for all attributes that allow an attribute value template.
      The general rules for the syntax of attribute value templates, and the specific
      rules for each such attribute, are described in the XSLT 2.0 Recommendation.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string"/>
</xs:simpleType>

<xs:simpleType name="char">
  <xs:annotation>
    <xs:documentation>
      A string containing exactly one character.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:string">
    <xs:length value="1"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="expression">
  <xs:annotation>
    <xs:documentation>
      An XPath 2.0 expression.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:token">
    <xs:pattern value=".+"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="level">
  <xs:annotation>
    <xs:documentation>
      The level attribute of xsl:number: 
      one of single, multiple, or any.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:NCName">
    <xs:enumeration value="single"/>
    <xs:enumeration value="multiple"/>
    <xs:enumeration value="any"/>
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="mode">
  <xs:annotation>
    <xs:documentation>
      The mode attribute of xsl:apply-templates: 
      either a QName, or #current, or #default.
    </xs:documentation>
  </xs:annotation>
  <xs:union memberTypes="xs:QName">
    <xs:simpleType>
      <xs:restriction base="xs:token">
        <xs:enumeration value="#default"/>
        <xs:enumeration value="#current"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

<xs:simpleType name="modes">
  <xs:annotation>
    <xs:documentation>
      The mode attribute of xsl:template: 
      either a list, each member being either a QName or #default;
      or the value #all
    </xs:documentation>
  </xs:annotation>
  <xs:union>
    <xs:simpleType>
      <xs:list>
        <xs:simpleType>
          <xs:union memberTypes="xs:QName">
            <xs:simpleType>
              <xs:restriction base="xs:token">
                <xs:enumeration value="#default"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:union>
        </xs:simpleType>
      </xs:list>
    </xs:simpleType>
    <xs:simpleType>
      <xs:restriction base="xs:token">
        <xs:enumeration value="#all" />
      </xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

<xs:simpleType name="nametests">
  <xs:annotation>
    <xs:documentation>
      A list of NameTests, as defined in the XPath 2.0 Recommendation.
      Each NameTest is either a QName, or "*", or "prefix:*", or "*:localname"
    </xs:documentation>
  </xs:annotation>
  <xs:list>
    <xs:simpleType>
      <xs:union memberTypes="xs:QName">
        <xs:simpleType>
          <xs:restriction base="xs:token">
            <xs:enumeration value="*" />
          </xs:restriction>
        </xs:simpleType>
        <xs:simpleType>
          <xs:restriction base="xs:token">
            <xs:pattern value="\i\c*:\*"/>
            <xs:pattern value="\*:\i\c*"/>            
          </xs:restriction>
        </xs:simpleType>
      </xs:union>
    </xs:simpleType>
  </xs:list>
</xs:simpleType>

<xs:simpleType name="prefixes">
  <xs:list itemType="xs:NCName" />
</xs:simpleType>

<xs:simpleType name="method">
  <xs:annotation>
    <xs:documentation>
      The method attribute of xsl:output:
      Either one of the recognized names "xml", "xhtml", "html", "text",
      or a QName that must include a prefix.
    </xs:documentation>
  </xs:annotation>
  <xs:union>
    <xs:simpleType>
      <xs:restriction base="xs:NCName">
        <xs:enumeration value="xml"/>
        <xs:enumeration value="xhtml"/>
        <xs:enumeration value="html"/>
        <xs:enumeration value="text"/>
      </xs:restriction>
    </xs:simpleType>
    <xs:simpleType>
      <xs:restriction base="xs:QName">
        <xs:pattern value="\c*:\c*"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

<xs:simpleType name="pattern">
  <xs:annotation>
    <xs:documentation>
      A match pattern as defined in the XSLT 2.0 Recommendation.
      The syntax for patterns is a restricted form of the syntax for
      XPath 2.0 expressions.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xsl:expression"/>
</xs:simpleType>

<xs:simpleType name="prefix-or-default">
  <xs:annotation>
    <xs:documentation>
      Either a namespace prefix, or #default.
      Used in the xsl:namespace-alias element.
    </xs:documentation>
  </xs:annotation>
  <xs:union memberTypes="xs:NCName">
    <xs:simpleType>
      <xs:restriction base="xs:token">
        <xs:enumeration value="#default"/>
      </xs:restriction>
    </xs:simpleType>
  </xs:union>
</xs:simpleType>

<xs:simpleType name="QNames">
  <xs:annotation>
    <xs:documentation>
      A list of QNames.
      Used in the [xsl:]use-attribute-sets attribute of various elements,
      and in the cdata-section-elements attribute of xsl:output
    </xs:documentation>
  </xs:annotation>
  <xs:list itemType="xs:QName"/>          
</xs:simpleType>

<xs:simpleType name="sequence-type">
  <xs:annotation>
    <xs:documentation>
      The description of a data type, conforming to the
      SequenceType production defined in the XPath 2.0 Recommendation
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:token">
    <xs:pattern value=".+"/>      
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="validation-type">
  <xs:annotation>
    <xs:documentation>
      Describes different ways of type-annotating an element or attribute.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:token">
    <xs:enumeration value="strict"/>
    <xs:enumeration value="lax"/>
    <xs:enumeration value="preserve"/>
    <xs:enumeration value="strip"/>    
  </xs:restriction>
</xs:simpleType>

<xs:simpleType name="yes-or-no">
  <xs:annotation>
    <xs:documentation>
      One of the values "yes" or "no".
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:token">
    <xs:enumeration value="yes"/>
    <xs:enumeration value="no"/>
  </xs:restriction>
</xs:simpleType>

</xs:schema>

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 a 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 NameAttributesMeaning
lex:cdata-section NoneDefines 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 nameMarks 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-idMarks 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, modelRepresents 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-valueRepresents 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-idRepresents 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-nameRepresents 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:

PrincipalAlternateAffiliation
Scott BoagAnders Berglund* / Kristoffer Rose*IBM
Bob Lojek-Invited Expert
Jeff CarusoAndrew GreenePageflex, Inc.
Paul Grosso-Arbortext
Michael KayJuliane HarbarthSoftware AG
Norm WalshTony GrahamSun Microsystems Inc.
Jonathan MarshAshok MalhotraMicrosoft Corporation
Zarella Rendon-Invited Expert
Peter Van der Beken-Netscape/AOL
Mark ScardinaK Karun*Oracle
Alex Milowski-Markup Technology Ltd.
Jeni Tennison-Invited Expert
W. Eliot Kimber-ISOGEN International

Asterisked names indicate those alternates who regularly participate in discussions alongside their company's principal representative.

The W3C representative on the XSL Working Group is Henry Thompson.

The following individuals made significant contributions to XSLT 2.0 while they were members of the Working Group:

James Clark, Invited Expert
Steve Muench, Oracle
Steve Zilles, Adobe
Evan Lenz, XYZFind

The working group wishes to acknowledge the contribution made by David Marston of IBM to the new specification of the format-number function.

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

The facility to define modes has been generalized, making it easier to define a distinct set of template rules for processing a particular document.

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

No new facilities have been provided in this area, because this information is not available in the Data Model.

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 Functions and Operators document: see [Functions and Operators].

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 11.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: see [XSLT and XQuery Serialization]

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:]xpath-default-namespace attribute is provided for this purpose: see 5.4 Unprefixed Names in Expressions and Patterns

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

A set of date formatting functions has been specified: see 16.5 Formatting Dates and Times

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. It is now possible to use a path expression such as document('a.xml')/id('A001').

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

A function resolve-uri is now defined in [Functions and Operators].

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: see 16.2 Reading Text Files

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

The serialization specification gives the implementation discretion on how special characters are output. A user who wishes to force the use of named character references can achieve this using the new xsl:character-map declaration.

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

No solution has been provided to this requirement; it is difficult, because entity references are not defined in the data model.

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 by the provision of the normalize-unicode function described in [Functions and Operators]. In addition, a serialization option normalize-unicode="yes"|"no" has been added.

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

The idref function defined in [Functions and Operators] has been introduced in response to this requirement.

Requirement 21

Could Support 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 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, using the operators << and >>.

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

A function to retrieve the public identifier of an unparsed entity has been added. However, no facilities have been provided to include unparsed entities in a result document.

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

An xsl:next-match instruction has been added.

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

Facilities to associate type annotations with constructed and copied element and attribute nodes are defined in this specification.

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. The working group has decided not to enhance it further to introduce scientific notation. Simple scientific formatting is now available through support for the schema-defined xs:float and xs:double data types; casting these values to a string produces a representation of the value in scientific notation.

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

There are no issues in this category.

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.

There are no issues in this category.

J.3 Closed Issues

The only issues listed in this section are those whose status has changed since the date of the previous working draft, 15 November 2002.

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.

Resolution: This issue was re-opened at the Chapel Hill meeting. Allowing disable-output-escaping on a temporary tree causes considerable complications for the implementation, and the rules for how it behaves have never been fully defined. The Working Group is considering replacing this feature with a facility to control how particular characters are represented in the final serialized output. This would allow special characters (perhaps Unicode private-use characters) to be written to the temporary tree to drive subsequent serialization. See also issue 124.

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: Having initially decided to retain 1.0 behavior, the WG subsequently modified this decision so that the result depends on whether backwards compatibility mode is enabled. This makes xsl:value-of consistent with attribute value templates.

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.

Resolution: A set of functions for formatting dates and times is now included in the XSLT Working Draft.

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)