Please refer to the errata for this document, which may include some normative corrections.
See also translations.
Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines the syntax and semantics of XSLT 2.0, a language for transforming XML documents into other XML documents.
XSLT 2.0 is a revised version of the XSLT 1.0 Recommendation [XSLT 1.0] published on 16 November 1999.
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].
This document contains hyperlinks to specific sections or definitions within other documents in this family of specifications. These links are indicated visually by a superscript identifying the target specification: for example XP for XPath, DM for the XDM data model, FO for Functions and Operators.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This Recommendation builds on the success of [XSLT 1.0], which was published on 16 November 1999. Many new features have been added to the language (see J.2 New Functionality) while retaining a high level of backwards compatibility (see J.1 Incompatible Changes). The changes have been designed to meet the requirements for XSLT 2.0 described in [XSLT 2.0 Requirements]. The way in which each requirement has been addressed is outlined in I Checklist of Requirements.
XSLT 2.0 depends on a number of other specifications that have progressed to Recommendation status at the same time: see [XPath 2.0], [Data Model], [Functions and Operators], and [XSLT and XQuery Serialization]. These subsidiary documents are also referenced in the specification of XQuery 1.0.
This document has been produced by the XSL Working Group, which is part of the XML Activity. The document has been reviewed by W3C Members and other interested parties, and is endorsed by the Director. It is a stable document and may be used as reference material or cited as a normative reference from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
A small number of editorial corrections and clarifications have been made to the document since it was published as a Proposed Recommendation on 21 November 2006. These changes are listed at J.2.4 Changes since Proposed Recommendation.
Please record any comments about this document in W3C's public Bugzilla system (instructions can be found at http://www.w3.org/XML/2005/04/qt-bugzilla). If access to that system is not feasible, you may send your comments to the W3C XSLT/XPath/XQuery public comments mailing list<EMAIL_ADDRESS>It is helpful to include the string [XSLT] in the subject line of your comment, whether made in Bugzilla or in email. Each Bugzilla entry and email message should contain only one comment. Archives of the comments and responses are available at http://lists.w3.org/Archives/Public/public-qt-comments/.
General public discussion of XSLT takes place on the XSL-List forum.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
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.5 The Evaluation
Context
2.6 Parsing and
Serialization
2.7 Extensibility
2.8 Stylesheets and XML
Schemas
2.9 Error
Handling
3 Stylesheet
Structure
3.1 XSLT
Namespace
3.2 Reserved Namespaces
3.3 Extension Attributes
3.4 XSLT
Media Type
3.5 Standard Attributes
3.6 Stylesheet Element
3.6.1 The default-collation
attribute
3.6.2 User-defined Data Elements
3.7 Simplified Stylesheet
Modules
3.8 Backwards-Compatible Processing
3.9 Forwards-Compatible Processing
3.10 Combining Stylesheet Modules
3.10.1 Locating Stylesheet Modules
3.10.2 Stylesheet Inclusion
3.10.3 Stylesheet Import
3.11 Embedded
Stylesheet Modules
3.12 Conditional Element
Inclusion
3.13 Built-in
Types
3.14 Importing
Schema Components
4 Data Model
4.1 XML
Versions
4.2 Stripping Whitespace from the
Stylesheet
4.3 Stripping Type Annotations from a
Source Tree
4.4 Stripping
Whitespace from a Source Tree
4.5 Attribute Types and DTD
Validation
4.6 Limits
4.7 Disable Output Escaping
5 Features of the XSLT Language
5.1 Qualified
Names
5.2 Unprefixed QNames in Expressions and
Patterns
5.3 Expressions
5.4 The Static and Dynamic
Context
5.4.1 Initializing the Static Context
5.4.2 Additional Static Context
Components used by XSLT
5.4.3 Initializing the Dynamic
Context
<IP_ADDRESS>
Maintaining Position: the Focus
<IP_ADDRESS>
Other components of the XPath
Dynamic Context
5.4.4 Additional Dynamic Context
Components used by XSLT
5.5 Patterns
5.5.1 Examples of Patterns
5.5.2 Syntax of Patterns
5.5.3 The Meaning of a Pattern
5.5.4 Errors in Patterns
5.6 Attribute Value
Templates
5.7 Sequence Constructors
5.7.1 Constructing Complex
Content
5.7.2 Constructing Simple
Content
5.7.3 Namespace Fixup
5.8 URI
References
6 Template Rules
6.1 Defining Templates
6.2 Defining Template Rules
6.3 Applying Template Rules
6.4 Conflict
Resolution for Template Rules
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 Creating
implicit document nodes
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.1.2 Tunnel Parameters
10.2 Named
Attribute Sets
10.3 Stylesheet Functions
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 Document Nodes
11.6 Creating Processing
Instructions
11.7 Creating Namespace Nodes
11.8 Creating Comments
11.9 Copying
Nodes
11.9.1 Shallow Copy
11.9.2 Deep Copy
11.10 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 The xsl:sort
Element
13.1.1 The Sorting Process
13.1.2 Comparing Sort Key Values
13.1.3 Sorting Using Collations
13.2 Creating a Sorted
Sequence
13.3 Processing a Sequence in Sorted
Order
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 The
xsl:analyze-string instruction
15.2 Captured
Substrings
15.3 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 Picture String
16.5.2 The Language, Calendar, and Country
Arguments
16.5.3 Examples of Date and Time
Formatting
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.1.4 Testing Availability of
Types
18.2 Extension Instructions
18.2.1 Designating an Extension
Namespace
18.2.2 Testing Availability of
Instructions
18.2.3 Fallback
19 Final Result Trees
19.1 Creating Final Result Trees
19.2 Validation
19.2.1 Validating Constructed Elements
and Attributes
<IP_ADDRESS>
Validation
using the [xsl:]validation Attribute
<IP_ADDRESS>
Validation using the [xsl:]type
Attribute
<IP_ADDRESS>
The Validation Process
19.2.2 Validating Document
Nodes
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
A References
A.1 Normative References
A.2 Other
References
B The XSLT Media Type
B.1 Registration of MIME Media Type
application/xslt+xml
B.2 Fragment Identifiers
C Glossary (Non-Normative)
D Element Syntax Summary
(Non-Normative)
E Summary of Error Conditions
(Non-Normative)
F Checklist of
Implementation-Defined Features (Non-Normative)
G Schema for XSLT Stylesheets
(Non-Normative)
H Acknowledgements
(Non-Normative)
I Checklist of
Requirements (Non-Normative)
J Changes from XSLT 1.0
(Non-Normative)
J.1 Incompatible Changes
J.1.1 Tree construction: whitespace
stripping
J.1.2 Changes in Serialization
Behavior
J.1.3 Backwards Compatibility
Behavior
J.1.4 Incompatibility in the
Absence of a Schema
J.1.5 Compatibility in the Presence of a
Schema
J.1.6 XPath 2.0 Backwards
Compatibility
J.2 New
Functionality
J.2.1 Pervasive changes
J.2.2 Major Features
J.2.3 Minor Changes
J.2.4 Changes since Proposed
Recommendation
This specification defines the syntax and semantics of the XSLT 2.0 language.
[Definition: A transformation in the XSLT language is expressed in the form of a stylesheet, whose syntax is well-formed XML [XML 1.0] conforming to the Namespaces in XML Recommendation [Namespaces in XML 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 [Extensible Stylesheet Language (XSL)]), or into another presentation-oriented format such as HTML, XHTML, or SVG. However, XSLT is used for a wide range of transformation tasks, not exclusively for formatting and presentation applications.
A transformation expressed in XSLT describes rules for transforming zero or more source trees into one or more result trees. The structure of these trees is described in [Data Model]. The transformation is achieved by a set of template rules. A template rule associates a pattern, which matches nodes in the source document, with a sequence constructor. In many cases, evaluating the sequence constructor will cause new nodes to be constructed, which can be used to produce part of a result tree. The structure of the result trees can be completely different from the structure of the source trees. In constructing a result tree, nodes from the source trees can be filtered and reordered, and arbitrary structure can be added. This mechanism allows a stylesheet to be applicable to a wide class of documents that have similar source tree structures.
[Definition: A stylesheet may consist of several
stylesheet modules, contained
in different XML documents. For a given transformation, one
of these functions as the principal stylesheet
module. The complete stylesheet is assembled by finding the
stylesheet modules referenced
directly or indirectly from the principal stylesheet module
using xsl:include
and
xsl:import
elements: see 3.10.2 Stylesheet
Inclusion and 3.10.3
Stylesheet Import.]
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 J 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.
For a full glossary of terms, see C Glossary.
[Definition: The software responsible for transforming source trees into result trees using an XSLT stylesheet is referred to as the processor. This is sometimes expanded to XSLT processor to avoid any confusion with other processors, for example an XML processor.]
[Definition: A specific product that performs the functions of an XSLT processor is referred to as an implementation ].
[Definition: The term result tree is used to refer to any tree constructed by instructions in the stylesheet. A result tree is either a final result tree or a temporary tree.]
[Definition: A final result tree is a
result
tree that forms part of the final output of a
transformation. Once created, the contents of a final
result tree are not accessible within the stylesheet
itself.] The xsl:result-document
instruction always creates a final result tree, and a final
result tree may also be created implicitly by the initial
template. The conditions under which this happens are
described in 2.4
Executing a Transformation. A final result tree
may be serialized as described in
20 Serialization.
[Definition: The term source tree means any
tree provided as input to the transformation. This includes
the document containing the initial context node if
any, documents containing nodes supplied as the values of
stylesheet parameters,
documents obtained from the results of functions such as
document
,
doc
FO, and
collection
FO, and
documents returned by extension functions or extension
instructions. In the context of a particular XSLT
instruction, the term source tree means any tree
provided as input to that instruction; this may be a source
tree of the transformation as a whole, or it may be a
temporary tree produced during the
course of the transformation.]
[Definition: The term temporary tree means any tree that is neither a source tree nor a final result tree.] Temporary trees are used to hold intermediate results during the execution of the transformation.
In this specification the phrases must, must not, should, should not, may, required, and recommended are to be interpreted as described in [RFC2119].
Where the phrase must, must not, or required relates to the behavior of the XSLT processor, then an implementation is not conformant unless it behaves as specified, subject to the more detailed rules in 21 Conformance.
Where the phrase must, must not, or required relates to a stylesheet, then the processor must enforce this constraint on stylesheets by reporting an error if the constraint is not satisfied.
Where the phrase should, should not, or recommended relates to a stylesheet, then a processor may produce warning messages if the constraint is not satisfied, but must not treat this as an error.
[Definition: In this specification, the term implementation-defined refers to a feature where the implementation is allowed some flexibility, and where the choices made by the implementation must be described in documentation that accompanies any conformance claim.]
[Definition: The term implementation-dependent refers to a feature where the behavior may vary from one implementation to another, and where the vendor is not expected to provide a full specification of the behavior.] (This might apply, for example, to limits on the size of source documents that can be transformed.)
In all cases where this specification leaves the behavior implementation-defined or implementation-dependent, the implementation has the option of providing mechanisms that allow the user to influence the behavior.
A paragraph labeled as a Note or described as an example is non-normative.
Many terms used in this document are defined in the XPath specification [XPath 2.0] or the XDM specification [Data Model]. Particular attention is drawn to the following:
[Definition: The term atomization is defined in Section 2.4.2 AtomizationXP. 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-only content), atomization generates a dynamic error.
[Definition: The term typed value is
defined in Section
5.15 typed-value
AccessorDM. Every node
except an element defined in the schema with
element-only content has a typed value. For example,
the typed
value of an attribute of type
xs:IDREFS
is a sequence of zero or more
xs:IDREF
values.]
[Definition: The term string value is defined in Section 5.13 string-value AccessorDM. Every node has a string value. For example, the string value of an element is the concatenation of the string values of all its descendant text nodes.]
[Definition: The term
XPath 1.0 compatibility mode is defined in
Section
2.1.1 Static ContextXP.
This is a setting in the static context of an XPath
expression; it has two values, true
and
false
. When the value is set to true, the
semantics of function calls and certain other
operations are adjusted to give a greater degree of
backwards compatibility between XPath 2.0 and XPath
1.0.]
[Definition: The term core function means a function that is specified in [Functions and Operators] and that is in the standard function namespace.]
[Definition: An XSLT element is an element in the XSLT namespace whose syntax and semantics are defined in this specification.] For a non-normative list of XSLT elements, see D Element Syntax Summary.
In this document the specification of each XSLT element is preceded by a summary of its syntax in the form of a model for elements of that element type. A full list of all these specifications can be found in D Element Syntax Summary. The meaning of syntax summary notation is as follows:
An attribute that is required is shown with its name in bold. An attribute that may be omitted is shown with a question mark following its name.
An attribute that is deprecated is shown in a grayed font within square brackets.
The string that occurs in the place of an attribute
value specifies the allowed values of the attribute. If
this is surrounded by curly brackets
({...}
), then the attribute value is
treated as an attribute value
template, and the string occurring within curly
brackets specifies the allowed values of the result of
evaluating the attribute value template. Alternative
allowed values are separated by |
. A
quoted string indicates a value equal to that specific
string. An unquoted, italicized name specifies a
particular type of value.
In all cases where this specification states that the value of an attribute must be one of a limited set of values, 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.
This example illustrates the notation used to describe XSLT elements.
<!-- Category:
instruction -->
<xsl:example-element
select = 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 brackets indicate that the
value can be defined as an attribute value
template, allowing a value such as
debug="{$debug}"
, where the variable
debug
is evaluated to yield
"yes"
or "no"
at run-time.
The content of an xsl:example-element
instruction is defined to be a sequence of zero or more
xsl:variable
and xsl:param
elements, followed by an xsl:sequence
element.
[ERR XTSE0010] A static error is signaled if an XSLT-defined element is used in a context where it is not permitted, if a required attribute is omitted, or if the content of the element does not correspond to the content that is allowed for the element.
Attributes are validated as follows. These rules apply to the value of the attribute after removing leading and trailing whitespace.
[ERR XTSE0020] It is a static error if an attribute (other than an attribute written using curly brackets in a position where an attribute value template is permitted) contains a value that is not one of the permitted values for that attribute.
[ERR XTDE0030] It is a non-recoverable dynamic error if the effective value of an attribute written using curly brackets, in a position where an attribute value template is permitted, is a value that is not one of the permitted values for that attribute. If the processor is able to detect the error statically (for example, when any XPath expressions within the curly brackets can be evaluated statically), then the processor may optionally signal this as a static error.
Special rules apply if the construct appears in part of the stylesheet that is processed with forwards-compatible behavior: see 3.9 Forwards-Compatible Processing.
[Definition: Some constructs defined in this specification are described as being deprecated. The use of this term implies that stylesheet authors should not use the construct, and that the construct may be removed in a later version of this specification.] All constructs that are deprecated in this specification are also (as it happens) optional features that implementations are not required to provide.
Note:
This working draft includes a non-normative XML Schema for XSLT stylesheet modules (see G Schema for XSLT Stylesheets). The syntax summaries described in this section are normative.
XSLT defines a set of standard functions which are additional to those defined in [Functions and Operators]. The signatures of these functions are described using the same notation as used in [Functions and Operators]. The names of these functions are all in the standard function namespace.
This document does not specify any application programming interfaces or other interfaces for initiating a transformation. This section, however, describes the information that is supplied when a transformation is initiated. Except where otherwise indicated, the information is required.
Implementations may allow a transformation to run as two or more phases, for example parsing, compilation and execution. Such a distinction is outside the scope of this specification, which treats transformation as a single process controlled using a set of stylesheet modules, supplied in the form of XML documents.
The following information is supplied to execute a transformation:
The stylesheet module that is
to act as the principal
stylesheet module for the transformation. The
complete stylesheet is assembled by
recursively expanding the xsl:import
and
xsl:include
declarations in the principal stylesheet module, as
described in 3.10.2 Stylesheet
Inclusion and 3.10.3
Stylesheet Import.
A set (possibly empty) of values for stylesheet parameters (see 9.5 Global Variables and Parameters). These values are available for use within expressions in the stylesheet.
[Definition: 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 .
(dot) and self::node()
, as described in
<IP_ADDRESS> Maintaining Position: the
Focus].
If no initial context node is supplied, then the context item, context position, and context size will initially be undefined, and the evaluation of any expression that references these values will result in a dynamic error. (Note that the initial context size and context position will always be 1 (one) when an initial context node is supplied, and will be undefined if no initial context node is supplied).
Optionally, the name of a named template which is to be executed as the entry point to the transformation. This template must exist within the stylesheet. If no named template is supplied, then the transformation starts with the template rule that best matches the initial context 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. This must either be the default mode, or a
mode that is explicitly named in the mode
attribute of an xsl:template
declaration within the stylesheet. If an initial
mode is supplied, then in searching for the template
rule that best matches the initial context 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. [Definition: The base output URI is a URI to be used as the base URI when resolving a relative URI allocated to a final result tree. If the transformation generates more than one final result tree, then typically each one will be allocated a URI relative to this base URI. ] The way in which a base output URI is established is implementation-defined.
A mechanism for obtaining a document node and a
media type, given an absolute URI. The total set of
available documents (modeled as a mapping from URIs to
document nodes) forms part of the context for
evaluating XPath expressions, specifically the doc
FO function. The XSLT document
function
additionally requires the media type of the resource
representation, for use in interpreting any fragment
identifier present within a URI Reference.
Note:
The set of documents that are available to the stylesheet is implementation-dependent, as is the processing that is carried out to construct a tree representing the resource retrieved using a given URI. Some possible ways of constructing a document (specifically, rules for constructing a document from an Infoset or from a PSVI) are described in [Data Model].
[ERR XTDE0040] It is a non-recoverable dynamic error if the invocation of the stylesheet specifies a template name that does not match the expanded-QName of a named template defined in the stylesheet.
[ERR XTDE0045] It is a non-recoverable dynamic
error if the invocation of the stylesheet specifies an initial
mode (other than the
default mode) that does not match the expanded-QName in the
mode
attribute of any template defined in the
stylesheet.
[ERR XTDE0047] It is a non-recoverable dynamic error if the invocation of the stylesheet specifies both an initial mode and an initial template.
[ERR XTDE0050] It is a non-recoverable dynamic
error if the stylesheet that is invoked declares a
visible stylesheet parameter with
required="yes"
and no value for this parameter
is supplied during the invocation of the stylesheet. A
stylesheet parameter is visible if it is not masked by
another global variable or parameter with the same name and
higher import precedence.
[Definition: The transformation is performed by
evaluating an initial template. If a named
template is supplied when the transformation is
initiated, then this is the initial template;
otherwise, the initial template is the template rule
selected according to the rules of the xsl:apply-templates
instruction for processing the initial context node in the
initial mode.]
Parameters passed to the transformation by the client application are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters declared within the initial template. All template parameters within the initial template to be executed will take their default values.
[ERR XTDE0060] It is a non-recoverable dynamic
error if the initial template defines a
template parameter that
specifies required="yes"
.
A stylesheet can process further source
documents in addition to those supplied when the
transformation is invoked. These additional documents can
be loaded using the functions document
(see
16.1 Multiple Source
Documents) or doc
FO or
collection
FO (see
[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).
[Definition: A stylesheet contains a set of template rules (see 6 Template Rules). A template rule has three parts: a pattern that is matched against nodes, a (possibly empty) set of template parameters, and a sequence constructor that is evaluated to produce a sequence of items.] In many cases these items are newly constructed nodes, which are then written to a result tree.
A transformation as a whole is executed by evaluating the sequence constructor of the initial template as described in 5.7 Sequence Constructors.
If the initial template has an as
attribute, then the result sequence of the initial template
is checked against the required type in the same way as for
any other template. If this result sequence is non-empty,
then it is used to construct an implicit final
result tree, following the rules described in 5.7.1 Constructing
Complex Content: the effect is as if the initial
template T were called by an implicit template
of the form:
<xsl:template name="IMPLICIT"> <xsl:result-document href=""> <xsl:call-template name="T"/> </xsl:result-document> </xsl:template>
An implicit result tree is also created when the result
sequence is empty, provided that no xsl:result-document
instruction has been evaluated during the course of the
transformation. In this situation the implicit result tree
will consist of a document node with no children.
Note:
This means that there is always at least one result
tree. It also means that if the content of the initial
template is a single xsl:result-document
instruction, as in the example above, then only one
result tree is produced, not two. It is useful to make
the result document explicit as this is the only way of
invoking document-level validation.
If the result of the initial template is non-empty,
and an explicit xsl:result-document
instruction has been evaluated with the empty attribute
href=""
, then an error will occur
[see ERR
XTDE1490], since it is not possible to create
two final result trees with the same URI.
A sequence constructor is a sequence of sibling nodes in the stylesheet, each of which is either an XSLT instruction, a literal result element, a text node, or an extension instruction.
[Definition: An instruction is either an XSLT instruction or an extension instruction.]
[Definition: An XSLT instruction is an
XSLT
element whose syntax summary in this specification
contains the annotation <!-- category: instruction
-->
.]
Extension instructions are described in 18.2 Extension Instructions.
The main categories of XSLT instruction are as follows:
instructions that create new nodes: xsl:document
,
xsl:element
,
xsl:attribute
,
xsl:processing-instruction
,
xsl:comment
,
xsl:value-of
,
xsl:text
,
xsl:namespace
;
an instruction that returns an arbitrary sequence by
evaluating an XPath expression: xsl:sequence
;
instructions that cause conditional or repeated
evaluation of nested instructions: xsl:if
, xsl:choose
, xsl:for-each
,
xsl:for-each-group
;
instructions that invoke templates: xsl:apply-templates
,
xsl:apply-imports
,
xsl:call-template
,
xsl:next-match
;
Instructions that declare variables: xsl:variable
,
xsl:param
;
other specialized instructions: xsl:number
, xsl:analyze-string
,
xsl:message
,
xsl:result-document
.
Often, a sequence constructor will
include an xsl:apply-templates
instruction, which selects a sequence of nodes to be
processed. Each of the selected nodes is processed by
searching the stylesheet for a matching template rule
and evaluating the sequence constructor of that
template rule. The resulting sequences of items are
concatenated, in order, to give the result of the xsl:apply-templates
instruction, as described in 6.3 Applying Template
Rules; this sequence is often added to a result tree. Since
the sequence constructors of the
selected template rules may themselves
contain xsl:apply-templates
instructions, this results in a cycle of selecting nodes,
identifying template rules, constructing
sequences, and constructing result trees, that recurses through a
source
tree.
The results of some expressions and instructions in a stylesheet may depend on information provided contextually. This context information is divided into two categories: the static context, which is known during static analysis of the stylesheet, and the dynamic context, which is not known until the stylesheet is evaluated. Although information in the static context is known at analysis time, it is sometimes used during stylesheet evaluation.
Some context information can be set by means of declarations within the stylesheet itself. For example, the namespace bindings used for any XPath expression are determined by the namespace declarations present in containing elements in the stylesheet. Other information may be supplied externally or implicitly: an example is the current date and time.
The context information used in processing an XSLT
stylesheet includes as a subset all the context information
required when evaluating XPath expressions. The XPath 2.0
specification defines a static and dynamic context that the
host language (in this case, XSLT) may initialize, which
affects the results of XPath expressions used in that
context. XSLT augments the context with additional
information: this additional information is used firstly by
XSLT constructs outside the scope of XPath (for example,
the xsl:sort
element), and secondly, by functions that are defined in
the XSLT specification (such as key
and format-number
)
that are available for use in XPath expressions appearing
within a stylesheet.
The static context for an expression or other construct in a stylesheet is determined by the place in which it appears lexically. The details vary for different components of the static context, but in general, elements within a stylesheet module affect the static context for their descendant elements within the same stylesheet module.
The dynamic context is maintained as a stack. When an instruction or expression is evaluated, it may add dynamic context information to the stack; when evaluation is complete, the dynamic context reverts to its previous state. An expression that accesses information from the dynamic context always uses the value at the top of the stack.
The most commonly used component of the dynamic context
is the context item. This is an implicit
variable whose value is the item (it may be a node or an
atomic value) currently being processed. The value of the
context item can be referenced within an XPath expression
using the expression .
(dot).
Full details of the static and dynamic context are provided in 5.4 The Static and Dynamic Context.
An XSLT stylesheet describes a process that constructs a set of final result trees from a set of source trees.
The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [Data Model]. Frequently an implementation will operate in conjunction with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build a source tree from an input XML document. An implementation may also provide an application programming interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a DOM Document object (see [DOM Level 2]). This is outside the scope of this specification. Users should be aware, however, that since the input to the transformation is a tree conforming to the XDM data model as described in [Data Model], constructs that might exist in the original XML document, or in the DOM, but which are not within the scope of the data model, cannot be processed by the stylesheet and cannot be guaranteed to remain unchanged in the transformation output. Such constructs include CDATA section boundaries, the use of entity references, and the DOCTYPE declaration and internal DTD subset.
[Definition: A frequent requirement is to output a final result tree as an XML document (or in other formats such as HTML). This process is referred to as serialization.]
Like parsing, serialization is not part of the
transformation process, and it is not required that an XSLT processor must be able to perform serialization.
However, for pragmatic reasons, this specification
describes declarations (the xsl:output
element and
the xsl:character-map
declarations, see 20
Serialization), and attributes on the xsl:result-document
instruction, that allow a stylesheet to specify the desired
properties of a serialized output file. When
serialization is not being performed, either because the
implementation does not support the serialization option,
or because the user is executing the transformation in a
way that does not invoke serialization, then the content of
the xsl:output
and xsl:character-map
declarations has no effect. Under these circumstances the
processor may report any errors
in an xsl:output
or xsl:character-map
declaration, or in the serialization attributes of xsl:result-document
,
but is not required to do so.
XSLT defines a number of features that allow the language to be extended by implementers, or, if implementers choose to provide the capability, by users. These features have been designed, so far as possible, so that they can be used without sacrificing interoperability. Extensions other than those explicitly defined in this specification are not permitted.
These features are all based on XML namespaces; namespaces are used to ensure that the extensions provided by one implementer do not clash with those of a different implementer.
The most common way of extending the language is by providing additional functions, which can be invoked from XPath expressions. These are known as extension functions, and are described in 18.1 Extension Functions.
It is also permissible to extend the language by
providing new instructions. These are referred to
as extension instructions, and
are described in 18.2
Extension Instructions. A stylesheet that uses
extension instructions must declare that it is doing so by
using the [xsl:]extension-element-prefixes
attribute.
Extension instructions and extension functions defined according to these rules may be provided by the implementer of the XSLT processor, and the implementer may also provide facilities to allow users to create further extension instructions and extension functions.
This specification defines how extension instructions and extension functions are invoked, but the facilities for creating new extension instructions and extension functions are implementation-defined. For further details, see 18 Extensibility and Fallback.
The XSLT language can also be extended by the use of extension attributes (see 3.3 Extension Attributes), and by means of user-defined data elements (see 3.6.2 User-defined Data Elements).
An XSLT stylesheet can make use of information from a schema. An XSLT transformation can take place in the absence of a schema (and, indeed, in the absence of a DTD), but where the source document has undergone schema validity assessment, the XSLT processor has access to the type information associated with individual nodes, not merely to the untyped text.
Information from a schema can be used both statically (when the stylesheet is compiled), and dynamically (during evaluation of the stylesheet to transform a source document).
There are places within a stylesheet, and within XPath expressions and patterns in a stylesheet, where it is possible to refer to named type definitions in a schema, or to element and attribute declarations. For example, it is possible to declare the types expected for the parameters of a function. This is done using the SequenceType XP syntax defined in [XPath 2.0].
[Definition: Type definitions and element and attribute declarations are referred to collectively as schema components.]
[Definition: The schema components that may be referenced by name in a stylesheet are referred to as the in-scope schema components. This set is the same throughout all the modules of a stylesheet.]
The conformance rules for XSLT 2.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 produce the
same results with a schema-aware XSLT processor
provided that the source documents are untyped (that
is, they are not validated against a schema). However, if
source documents are validated against a schema then the
results may be different from the case where they are not
validated. Some constructs that work on untyped data may
fail with typed data (for example, an attribute of type
xs:date
cannot be used as an argument of the
substring
FO function)
and other constructs may produce different results
depending on the data type (for example, given the element
<product price="10.00"
discount="2.00"/>
, the expression @price gt
@discount
will return true if the attributes have
type xs:decimal
, but will return false if they
are untyped).
There is a standard set of type definitions that are always available as in-scope schema components in every stylesheet. These are defined in 3.13 Built-in Types. The set of built-in types varies between a basic XSLT processor and a schema-aware XSLT processor.
The remainder of this section describes facilities that are available only with a schema-aware XSLT processor.
Additional schema components (type
definitions, element declarations, and attribute
declarations) may be added to the in-scope schema
components by means of the xsl:import-schema
declaration in a stylesheet.
The xsl:import-schema
declaration may reference an external schema document by
means of a URI, or it may contain an inline
xs:schema
element.
It is only necessary to import a schema explicitly if one or more of its schema components are referenced explicitly by name in the stylesheet; it is not necessary to import a schema merely because the stylesheet is used to process a source document that has been assessed against that schema. It is possible to make use of the information resulting from schema assessment (for example, the fact that a particular attribute holds a date) even if no schema has been imported by the stylesheet.
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 a result tree just as much as for nodes in source documents. It is possible to make assertions about the type of an input document by means of tests within the stylesheet. For example:
<xsl:template match="document-node(schema-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 unless the document element of the
source document is valid against the top-level element
declaration my:invoice
, and has been
annotated as such.
It is possible that a source document may contain nodes
whose type
annotation is not one of the types imported by the
stylesheet. This creates a potential problem because in the
case of an expression such as data(.) instance of
xs:integer
the system needs to know whether the type
named in the type annotation of the context node is derived
by restriction from the type xs:integer
. This
information is not explicitly available in an XDM
tree, as defined in [Data
Model]. The implementation may choose one of several
strategies for dealing with this situation:
The processor may signal a non-recoverable dynamic error if a source document is found to contain a type annotation that is not known to the processor.
The processor may maintain additional metadata,
beyond that described in [Data Model], that allows the
source document to be processed as if all the necessary
schema information had been imported using xsl:import-schema
.
Such metadata might be held in the data structure
representing the source document itself, or it might be
held in a system catalog or repository.
The processor may be configured to use a fixed set of schemas, which are automatically used to validate all source documents before they can be supplied as input to a transformation. In this case it is impossible for a source document to have a type annotation that the processor is not aware of.
The processor may be configured to treat the source
document as if no schema processing had been performed,
that is, effectively to strip all type annotations from
elements and attributes on input, marking them instead
as having type xs:untyped
and
xs:untypedAtomic
respectively.
Where a stylesheet author chooses to make assertions about the types of nodes or of variables and parameters, it is possible for an XSLT processor to perform static analysis of the stylesheet (that is, analysis in the absence of any source document). Such analysis may reveal errors that would otherwise not be discovered until the transformation is actually executed. An XSLT processor is not required to perform such static type-checking. Under some circumstances (see 2.9 Error Handling) type errors that are detected early may be reported as static errors. In addition an implementation may report any condition found during static analysis as a warning, provided that this does not prevent the stylesheet being evaluated as described by this specification.
A stylesheet can also control the type annotations of nodes that it constructs in a final result tree, or in temporary trees. This can be done in a number of ways.
It is possible to request explicit validation of a
complete document, that is, a tree rooted at a document
node. This applies both to temporary trees constructed
using the xsl:document
(or
xsl:copy
)
instruction and also to final result trees
constructed using xsl:result-document
.
Validation is either strict or lax, as described in
[XML Schema Part 1]. If
validation of a result tree fails (strictly
speaking, if the outcome of the validity assessment is
invalid
), then the transformation fails,
but in all other cases, the element and attribute nodes
of the tree will be annotated with the names of the
types to which these nodes conform. These type
annotations will be discarded if the result tree is
serialized as an XML document, but they remain
available when the result tree is passed to an
application (perhaps another stylesheet) for further
processing.
It is also possible to validate individual element
and attribute nodes as they are constructed. This is
done using the type
and
validation
attributes of the xsl:element
,
xsl:attribute
,
xsl:copy
, and
xsl:copy-of
instructions, or the xsl:type
and
xsl:validation
attributes of a literal
result element.
When elements, attributes, or document nodes are
copied, either explicitly using the xsl:copy
or xsl:copy-of
instructions, or implicitly when nodes in a sequence
are attached to a new parent node, the options
validation="strip"
and
validation="preserve"
are available, to
control whether existing type annotations are to be
retained or not.
When nodes in a temporary tree are validated, type information is available for use by operations carried out on the temporary tree, in the same way as for a source document that has undergone schema assessment.
For details of how validation of element and attribute nodes works, see 19.2 Validation.
[Definition: 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 final result tree.
There is an exception to this rule when the stylesheet specifies forwards-compatible behavior (see 3.9 Forwards-Compatible Processing).
Generally, errors in the structure of the stylesheet, or in the syntax of XPath expressions contained in the stylesheet, are classified as static errors. Where this specification states that an element in the stylesheet must or must not appear in a certain position, or that it must or must not have a particular attribute, or that an attribute must or must not have a value satisfying specified conditions, then any contravention of this rule is a static error unless otherwise specified.
[Definition: An error that is not detected until a source document is being transformed is referred to as a dynamic error.]
[Definition: Some dynamic errors are classed as recoverable errors. When a recoverable error occurs, this specification allows the processor either to signal the error (by reporting the error condition and terminating execution) or to take a defined recovery action and continue processing.] It is implementation-defined whether the error is signaled or the recovery action is taken.
[Definition: If an implementation chooses to recover from a recoverable dynamic error, it must take the optional recovery action defined for that error condition in this specification.]
When the implementation makes the choice between signaling a dynamic error or recovering, it is not restricted in how it makes the choice; for example, it may provide options that can be set by the user. When an implementation chooses to recover from a dynamic error, it may also take other action, such as logging a warning message.
[Definition: A dynamic error that is not recoverable is referred to as a non-recoverable dynamic error. When a non-recoverable dynamic error occurs, the processor must signal the error, and the transformation fails.]
Because different implementations may optimize execution of the stylesheet in different ways, the detection of dynamic errors is to some degree implementation-dependent. In cases where an implementation is able to produce the final result trees without evaluating a particular construct, the implementation is never required to evaluate that construct solely in order to determine whether doing so causes a dynamic error. For example, if a variable is declared but never referenced, an implementation may choose whether or not to evaluate the variable declaration, which means that if evaluating the variable declaration causes a dynamic error, some implementations will signal this error and others will not.
There are some cases where this specification requires
that a construct must not be
evaluated: for example, the content of an xsl:if
instruction
must not be evaluated if the test
condition is false. This means that an implementation
must not signal any dynamic
errors that would arise if the construct were
evaluated.
An implementation may signal a dynamic error before any source document is available, but only if it can determine that the error would be signaled for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see 9.8 Circular Definitions.
The XPath specification states (see Section 2.3.1 Kinds of ErrorsXP) that if any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be reported as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be reported as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be signaled as dynamic errors, and signaled only if the XPath expression is actually evaluated.
An XPath processor may report statically that the
expression 1 div 0
fails with a "divide by
zero" error. But suppose this XPath expression occurs in
an XSLT construct such as:
<xsl:choose> <xsl:when test="system-property('xsl:version') = '1.0'"> <xsl:value-of select="1 div 0"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="xs:double('INF')"/> </xsl:otherwise> </xsl:choose>
Then the XSLT processor must not report an error, because the relevant XPath construct appears in a context where it will never be executed by an XSLT 2.0 processor. (An XSLT 1.0 processor will execute this code successfully, returning positive infinity, because it uses double arithmetic rather than decimal arithmetic.)
[Definition: Certain errors are classified as type errors. A type error occurs when the value supplied as input to an operation is of the wrong type for that operation, for example when an integer is supplied to an operation that expects a node.] If a type error occurs in an instruction that is actually evaluated, then it must be signaled in the same way as a non-recoverable dynamic error. Alternatively, an implementation may signal a type error during the analysis phase in the same way as a static error, even if it occurs in part of the stylesheet that is never evaluated, provided it can establish that execution of a particular construct would never succeed.
It is implementation-defined whether type errors are signaled statically.
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>
On the other hand, in the following example it is not
possible to determine statically whether the operand of
xsl:apply-templates
will have a suitable dynamic type. An implementation
may produce a warning in such
cases, but it must not treat it
as an error.
<xsl:template match="para"> <xsl:param name="p" as="item()"/> <xsl:apply-templates select="$p"/> </xsl:template>
If more than one error arises, an implementation is not required to signal any errors other than the first one that it detects. It is implementation-dependent which of the several errors is signaled. This applies both to static errors and to dynamic errors. An implementation is allowed to signal more than one error, but if any errors have been signaled, it must not finish as if the transformation were successful.
When a transformation signals one or more dynamic errors, the final state of any persistent resources updated by the transformation is implementation-dependent. Implementations are not required to restore such resources to their initial state. In particular, where a transformation produces multiple result documents, it is possible that one or more serialized result documents may be written successfully before the transformation terminates, but the application cannot rely on this behavior.
Everything said above about error handling applies equally to errors in evaluating XSLT instructions, and errors in evaluating XPath expressions. Static errors and dynamic errors may occur in both cases.
[Definition: If a transformation has successfully produced a final result tree, it is still possible that errors may occur in serializing the result tree. For example, it may be impossible to serialize the result tree using the encoding selected by the user. Such an error is referred to as a serialization error.] If the processor performs serialization, then it must do so as specified in 20 Serialization, and in particular it must signal any serialization errors that occur.
Errors are identified by a QName. For errors defined in
this specification, the namespace of the QName is always
http://www.w3.org/2005/xqt-errors
(and is
therefore not given explicitly), while the local part is an
8-character code in the form PPSSNNNN. Here
PP is always XT
(meaning XSLT), and
SS is one of SE
(static error),
DE
(dynamic error), RE
(recoverable dynamic error), or TE
(type
error). Note that the allocation of an error to one of
these categories is purely for convenience and carries no
normative implications about the way the error is handled.
Many errors, for example, can be reported either
dynamically or statically.
These error codes are used to label error conditions in this specification, and are summarized in E Summary of Error Conditions). They are provided primarily for ease of reference. Implementations may use these codes when signaling errors, but they are not required to do so. An API specification, however, may require the use of error codes based on these QNames. Additional errors defined by an implementation (or by an application) may use QNames in an implementation-defined (or user-defined) namespace without risk of collision.
Errors defined in the [XPath 2.0] and [Functions and Operators] specifications use QNames with a similar structure, in the same namespace. When errors occur in processing XPath expressions, an XSLT processor should use the original error code reported by the XPath processor, unless a more specific XSLT error code is available.
[Definition: A stylesheet consists of one or more stylesheet modules, each one forming all or part of an XML document.]
Note:
A stylesheet module is represented by an XDM
element node (see [Data
Model]). In the case of a standard stylesheet
module, this will be an xsl:stylesheet
or
xsl:transform
element. In the case of a simplified stylesheet module, it
can be any element (not in the XSLT namespace) that has an
xsl:version
attribute.
Although stylesheet modules will commonly be maintained in the form of documents conforming to XML 1.0 or XML 1.1, this specification does not mandate such a representation. As with source trees, the way in which stylesheet modules are constructed, from textual XML or otherwise, is outside the scope of this specification.
A stylesheet module is either a standard stylesheet module or a simplified stylesheet module:
[Definition: A standard stylesheet
module is a tree, or part of a tree, consisting of an
xsl:stylesheet
or
xsl:transform
element (see 3.6
Stylesheet Element) together with its descendant
nodes and associated attributes and
namespaces.]
[Definition: A simplified
stylesheet module is a tree, or part of a tree,
consisting of a literal result element
together with its descendant nodes and associated
attributes and namespaces. This element is not itself in
the XSLT namespace, but it must
have an xsl:version
attribute, which implies
that it must have a namespace
node that declares a binding for the XSLT namespace. For
further details see 3.7 Simplified Stylesheet
Modules. ]
Both forms of stylesheet module (standard and simplified) can exist either as an entire XML document, or embedded as part of another XML document, typically but not necessarily a source document that is to be processed using the stylesheet.
[Definition: A standalone stylesheet module is a stylesheet module that comprises the whole of an XML document.]
[Definition: An embedded stylesheet module is a stylesheet module that is embedded within another XML document, typically the source document that is being transformed.] (see 3.11 Embedded Stylesheet Modules).
There are thus four kinds of stylesheet module:
standalone standard stylesheet modules
standalone simplified stylesheet modules
embedded standard stylesheet modules
embedded simplified stylesheet modules
[Definition: The XSLT namespace has the URI
http://www.w3.org/1999/XSL/Transform
. It is
used to identify elements, attributes, and other names that
have a special meaning defined in this
specification.]
Note:
The 1999
in the URI indicates the year in
which the URI was allocated by the W3C. It does not
indicate the version of XSLT being used, which is
specified by attributes (see 3.6 Stylesheet Element
and 3.7 Simplified
Stylesheet Modules).
XSLT processors must use the XML namespaces mechanism [Namespaces in XML 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 D 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.
Note:
Throughout this specification, an element or attribute that is in no namespace, or an expanded-QName whose namespace part is an empty sequence, is referred to as having a null namespace URI.
Note:
The conventions used for the names of XSLT elements,
attributes and functions are that names are all
lower-case, use hyphens to separate words, and use
abbreviations only if they already appear in the syntax
of a related language such as XML or HTML. Names of types
defined in XML Schema 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
FO.
[Definition: The XSLT namespace, together with certain other namespaces recognized by an XSLT processor, are classified as reserved namespaces and must be used only as specified in this and related specifications.] The reserved namespaces are those listed below.
The XSLT namespace, described in 3.1 XSLT Namespace, is reserved.
[Definition: The standard
function namespace
http://www.w3.org/2005/xpath-functions
is
used for functions in the function library defined in
[Functions and
Operators] and standard functions defined in this
specification.]
[Definition: The XML namespace,
defined in [Namespaces
in XML 1.0] as
http://www.w3.org/XML/1998/namespace
,
is used for attributes such as xml:lang
,
xml:space
, and
xml:id
.]
[Definition: The schema namespace
http://www.w3.org/2001/XMLSchema
is used
as defined in [XML Schema Part
1] ]. In a
stylesheet this namespace may be
used to refer to built-in schema datatypes and to the
constructor functions associated with those
datatypes.
[Definition: The schema instance
namespace
http://www.w3.org/2001/XMLSchema-instance
is used as defined in [XML
Schema Part 1] ].
Attributes in this namespace, if they appear in a
stylesheet, are treated by the
XSLT processor in the same way as any other
attributes.
Reserved namespaces may be used without restriction to refer to the names of elements and attributes in source documents and result documents. As far as the XSLT processor is concerned, reserved namespaces other than the XSLT namespace may be used without restriction in the names of literal result elements and user-defined data elements, and in the names of attributes of literal result elements or of XSLT elements: but other processors may impose restrictions or attach special meaning to them. Reserved namespaces must not be used, however, in the names of stylesheet-defined objects such as variables and stylesheet functions.
Note:
With the exception of the XML namespace, any of the above namespaces that are used in a stylesheet must be explicitly declared with a namespace declaration. Although conventional prefixes are used for these namespaces in this specification, any prefix may be used in a user stylesheet.
[ERR XTSE0080] It is a static error to use a reserved namespace in the name of a named template, a mode, an attribute set, a key, a decimal-format, a variable or parameter, a stylesheet function, a named output definition, or a character map.
[Definition: 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. These attributes are referred to as extension attributes.] The presence of an extension attribute must not cause the final result trees produced by the transformation to be different from the result trees that a conformant XSLT 2.0 processor might produce. They must not cause the processor to fail to signal an error that a conformant processor is required to signal. This means that an extension attribute must not change the effect of any instruction except to the extent that the effect is implementation-defined or implementation-dependent.
Furthermore, if serialization is performed using one of
the serialization methods xml
,
xhtml
, html
, or text
described in 20
Serialization, the presence of an extension
attribute must not cause the serializer to behave in a way
that is inconsistent with the mandatory provisions of that
specification.
Note:
Extension attributes may be used to modify the behavior of extension functions and extension instructions. They may be used to select processing options in cases where the specification leaves the behavior implementation-defined or implementation-dependent. They may also be used for optimization hints, for diagnostics, or for documentation.
Extension attributes
may also be used to influence
the behavior of the serialization methods
xml
, xhtml
, html
,
or text
, to the extent that the behavior of
the serialization method is implementation-defined
or implementation-dependent.
For example, an extension attribute might be used to
define the amount of indentation to be used when
indent="yes"
is specified. If a
serialization method other than one of these four is
requested (using a prefixed QName in the method
parameter) then extension attributes may influence its
behavior in arbitrary ways. Extension attributes
must not be used to cause the
four standard serialization methods to behave in a
non-conformant way, for example by failing to report
serialization errors that a serializer is required to report. An implementation that
wishes to provide such options must create a new
serialization method for the purpose.
An implementation that does not recognize the name of an extension attribute, or that does not recognize its value, must perform the transformation as if the extension attribute were not present. As always, it is permissible to produce warning messages.
The namespace used for an extension attribute will be
copied to the result tree in the normal way if it
is in scope for a literal result element.
This can be prevented using the
[xsl:]exclude-result-prefixes
attribute.
The following code might be used to indicate to a
particular implementation that the xsl:message
instruction is to ask the user for confirmation before
continuing with the transformation:
<xsl:message abc:pause="yes" xmlns:abc="http://vendor.example.com/xslt/extensions">Phase 1 complete</xsl:message>
Implementations that do not recognize the namespace
http://vendor.example.com/xslt/extensions
will simply ignore the extra attribute, and evaluate the
xsl:message
instruction in the normal way.
[ERR XTSE0090] It is a static error for an element from the XSLT namespace to have an attribute whose namespace is either null (that is, an attribute with an unprefixed name) or the XSLT namespace, other than attributes defined for the element in this document.
The media type application/xslt+xml
will be
registered for XSLT stylesheet modules.
The proposed definition of the media type is at B The XSLT Media Type
This media type should be used for an XML document containing a standard stylesheet module at its top level, and it may also be used for a simplified stylesheet module. It should not be used for an XML document containing an embedded stylesheet module.
[Definition: There are a number of standard
attributes that may appear on any XSLT element:
specifically version
,
exclude-result-prefixes
,
extension-element-prefixes
,
xpath-default-namespace
,
default-collation
, and
use-when
.]
These attributes may also appear on a literal result element,
but in this case, to distinguish them from user-defined
attributes, the names of the attributes are in the
XSLT
namespace. They are thus typically written as
xsl:version
,
xsl:exclude-result-prefixes
,
xsl:extension-element-prefixes
,
xsl:xpath-default-namespace
,
xsl:default-collation
, or
xsl:use-when
.
It is recommended that all these attributes should also be permitted on extension instructions, but this is at the discretion of the implementer of each extension instruction. They may also be permitted on user-defined data elements, though they will only have any useful effect in the case of data elements that are designed to behave like XSLT declarations or instructions.
In the following descriptions, these attributes are
referred to generically as [xsl:]version
, and
so on.
These attributes all affect the element they appear on, together with any elements and attributes that have that element as an ancestor. The two forms with and without the XSLT namespace have the same effect; the XSLT namespace is used for the attribute if and only if its parent element is not in the XSLT namespace.
In the case of [xsl:]version
,
[xsl:]xpath-default-namespace
, and
[xsl:]default-collation
, the value can be
overridden by a different value for the same attribute
appearing on a descendant element. The effective value of
the attribute for a particular stylesheet element is
determined by the innermost ancestor-or-self
element on which the attribute appears.
In an embedded stylesheet module, standard attributes appearing on ancestors of the outermost element of the stylesheet module have no effect.
In the case of
[xsl:]exclude-result-prefixes
and
[xsl:]extension-element-prefixes
the values
are cumulative. For these attributes, the value is given as
a whitespace-separated list of namespace prefixes, and the
effective value for an element is the combined set of
namespace URIs designated by the prefixes that appear in
this attribute for that element and any of its ancestor
elements. Again, the two forms with and without the XSLT
namespace are equivalent.
The effect of the [xsl:]use-when
attribute
is described in 3.12
Conditional Element Inclusion.
Because these attributes may appear on any XSLT element,
they are not listed in the syntax summary of each
individual element. Instead they are listed and described
in the entry for the xsl:stylesheet
and
xsl:transform
elements only. This reflects the fact that these attributes
are often used on the xsl:stylesheet
element only, in which case they apply to the entire
stylesheet module.
Note that the effect of these attributes does
not extend to stylesheet modules referenced
by xsl:include
or xsl:import
declarations.
For the detailed effect of each attribute, see the following sections:
[xsl:]version
see 3.8 Backwards-Compatible Processing and 3.9 Forwards-Compatible Processing
[xsl:]xpath-default-namespace
[xsl:]exclude-result-prefixes
[xsl:]extension-element-prefixes
[xsl:]use-when
[xsl:]default-collation
<xsl:stylesheet
id? = id
extension-element-prefixes? =
tokens
exclude-result-prefixes? =
tokens
version = number
xpath-default-namespace? = uri
default-validation? = "preserve" |
"strip"
default-collation? = uri-list
input-type-annotations? = "preserve" | "strip"
| "unspecified">
<!-- 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? = "preserve" |
"strip"
default-collation? = uri-list
input-type-annotations? = "preserve" | "strip"
| "unspecified">
<!-- 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
.
An xsl:stylesheet
element must have a
version
attribute, indicating the version of
XSLT that the stylesheet module requires.
[ERR XTSE0110] The value of the
version
attribute must be a number: specifically, it
must be a a valid instance
of the type xs:decimal
as defined in [XML Schema Part 2]. For this
version of XSLT, the value should
normally be 2.0
. A value of 1.0
indicates that the stylesheet module was written with the
intention that it should be
processed using an XSLT 1.0 processor.
If a stylesheet that specifies
[xsl:]version="1.0"
in the outermost element
of the principal stylesheet
module (that is, version="1.0"
in the case
of a standard stylesheet
module, or xsl:version="1.0"
in the case
of a simplified stylesheet
module) is submitted to an XSLT 2.0 processor, the
processor should output a warning
advising the user of possible incompatibilities, unless the
user has requested otherwise. The processor must then process the stylesheet using the
rules for backwards-compatible
behavior. These rules require that if the processor
does not support backwards-compatible
behavior, it must signal an
error and must not execute the
transformation.
When the value of the version
attribute is
greater than 2.0, forwards-compatible
behavior is enabled (see 3.9
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 module 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 will 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 alternative
stylesheet modules, one
specifying version="1.0"
, and the other
specifying version="2.0"
; these modules can
use xsl:include
or
xsl:import
to
incorporate the common code. When running under an XSLT
1.0 processor, the version="1.0"
module can
be selected as the principal
stylesheet module; when running under an XSLT 2.0
processor, the version="2.0"
module can be
selected as the principal
stylesheet module. Stylesheet modules that are
included or imported should specify
version="2.0"
if they make use of XSLT 2.0
facilities, and version="1.0"
otherwise.
The effect of the input-type-annotations
attribute is described in 4.3 Stripping Type Annotations
from a Source Tree.
The default-validation
attribute defines
the default value of the validation
attribute
of all xsl:document
,
xsl:element
,
xsl:attribute
,
xsl:copy
, xsl:copy-of
, and
xsl:result-document
instructions, and of the xsl:validation
attribute of all literal result elements.
It also determines the validation applied to the implicit
final result tree created in
the absence of an xsl:result-document
instruction. This default applies within the stylesheet
module: it does not extend to included or imported
stylesheet modules. If the attribute is omitted, the
default is strip
. The permitted values
are preserve
and strip
.
For details of the effect of this attribute, see 19.2 Validation.
[ERR XTSE0120] An xsl:stylesheet
element must not have any text
node children. (This rule applies after stripping of
whitespace text nodes as
described in 4.2
Stripping Whitespace from the Stylesheet.)
[Definition: An
element occurring as a child of an xsl:stylesheet
element is called a top-level element.]
[Definition: Top-level elements fall into two categories: declarations, and user-defined data elements. Top-level elements whose names are in the XSLT namespace are declarations. Top-level elements in any other namespace are user-defined data elements (see 3.6.2 User-defined Data Elements)].
The declaration elements permitted in the
xsl:stylesheet
element are:
xsl:import
xsl:include
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:import-schema
xsl:key
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:strip-space
xsl:template
xsl:variable
Note that the xsl:variable
and
xsl:param
elements can act either as declarations or as instructions. A
global variable or parameter is defined using a
declaration; a local variable or parameter using an
instruction.
If there are xsl:import
elements,
these must come before any other
elements. Apart from this, the child elements of the
xsl:stylesheet
element may appear in any order. 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.
default-collation
attributeThe default-collation
attribute is a
standard attribute that may
appear on any element in the XSLT namespace, or (as
xsl:default-collation
) on a literal result
element.
The attribute is used to specify the default collation
used by all XPath expressions appearing in the attributes
of this element, or attributes of descendant elements,
unless overridden by another
default-collation
attribute on an inner
element. It also determines the collation used by certain
XSLT constructs (such as xsl:key
and xsl:for-each-group
)
within its scope.
The value of the attribute is a whitespace-separated list of collation URIs. If any of these URIs is a relative URI, then it is resolved relative to the base URI of the attribute's parent element. If the implementation recognizes one or more of the resulting absolute collation URIs, then it uses the first one that it recognizes as the default collation.
[ERR XTSE0125] It is a static error
if the value of an [xsl:]default-collation
attribute, after resolving against the base
URI, contains no URI that the implementation
recognizes as a collation URI.
Note:
The reason the attribute allows a list of collation URIs is that collation URIs will often be meaningful only to one particular XSLT implementation. Stylesheets designed to run with several different implementations can therefore specify several different collation URIs, one for use with each. To avoid the above error condition, it is possible to specify the Unicode Codepoint Collation as the last collation URI in the list.
The [xsl:]default-collation
attribute
does not affect the collation used by
xsl:sort
.
[Definition: 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.]
[ERR XTSE0130] It is a static error
if the xsl:stylesheet
element has a child element whose name has a null
namespace URI.
An implementation may attach
an implementation-defined
meaning to user-defined data elements that appear in
particular namespaces. The set of namespaces
that are recognized for such data elements is implementation-defined.
The presence of a user-defined data element must not change the behavior of XSLT elements
and functions defined in this document; for example, it
is not permitted for a user-defined data element to
specify that xsl:apply-templates
should use different rules to resolve conflicts.
The constraints on what user-defined data elements
can and cannot do are exactly the same as the constraints
on extension attributes,
described in 3.3
Extension Attributes. Thus, an
implementation is always free to ignore user-defined data
elements, and must ignore such
data elements without giving an error if it does not
recognize the namespace URI.
User-defined data elements can provide, for example,
information used by extension instructions or extension functions (see 18 Extensibility and Fallback),
information about what to do with any final result tree,
information about how to construct source trees,
optimization hints for the processor,
metadata about the stylesheet,
structured documentation for the stylesheet.
A user-defined data element
must not precede an xsl:import
element
within a stylesheet module
[see ERR XTSE0200]
A simplified syntax is allowed for a stylesheet
module that defines only a single template rule for the
document node. The stylesheet module may consist of just a
literal result element
(see 11.1 Literal
Result Elements) together with its contents.
The literal result element must have an
xsl:version
attribute (and it must therefore
also declare the XSLT namespace). Such a stylesheet
module is equivalent to a standard stylesheet
module whose xsl:stylesheet
element contains a template rule containing the
literal result element, minus its
xsl:version
attribute; the template
rule has a match pattern of /
.
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>
Note that it is not possible, using a simplified
stylesheet, to request that the serialized output
contains a DOCTYPE
declaration. This can
only be done by using a standard stylesheet module, and
using the xsl:output
element.
More formally, a simplified stylesheet module is
equivalent to the standard stylesheet module that would be
generated by applying the following transformation to the
simplified stylesheet module, invoking the transformation
by calling the named template
expand
, with the containing literal result
element as the context node:
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template name="expand"> <xsl:element name="xsl:stylesheet"> <xsl:attribute name="version" select="@xsl:version"/> <xsl:element name="xsl:template"> <xsl:attribute name="match">/</xsl:attribute> <xsl:copy-of select="."/> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
[ERR XTSE0150] A literal result element
that is used as the outermost element of a simplified
stylesheet module must have an
xsl:version
attribute. This indicates the
version of XSLT that the stylesheet requires. For this
version of XSLT, the value will normally be
2.0
; the value must
be a valid instance of the type
xs:decimal
as defined in [XML Schema Part 2].
Other literal result elements
may also have an xsl:version
attribute. When
the xsl:version
attribute is numerically less
than 2.0
, backwards-compatible processing
behavior is enabled (see 3.8
Backwards-Compatible Processing). When the
xsl:version
attribute is numerically greater
than 2.0
, forwards-compatible
behavior is enabled (see 3.9
Forwards-Compatible Processing).
The allowed content of a literal result element when
used as a simplified stylesheet is the same as when it
occurs within a sequence constructor. Thus,
a literal result element used as the document element of a
simplified stylesheet cannot contain declarations. Simplified
stylesheets therefore cannot use global variables, stylesheet parameters,
stylesheet functions,
keys, attribute-sets, or output
definitions. In turn this means that the only useful
way to initiate the transformation is to supply a document
node as the initial context node, to be
matched by the implicit match="/"
template
rule using the default mode.
[Definition: An element enables
backwards-compatible behavior for itself, its attributes,
its descendants and their attributes if it has an
[xsl:]version
attribute (see 3.5 Standard Attributes)
whose value is less than 2.0
.]
An element that has an [xsl:]version
attribute whose value is greater than or equal to
2.0
disables backwards-compatible behavior for
itself, its attributes, its descendants and their
attributes. The compatibility behavior established by an
element overrides any compatibility behavior established by
an ancestor element.
If an attribute containing an XPath expression is
processed with backwards-compatible behavior, then the
expression is evaluated with XPath 1.0 compatibility mode
set to true
. For details of this mode, see
Section
2.1.1 Static ContextXP.
Furthermore, in such an expression any function call
for which no implementation is available (unless it uses
the standard function
namespace) is bound to a fallback error function whose
effect when evaluated is to raise a dynamic error
[see ERR
XTDE1425] . The effect is that with
backwards-compatible behavior enabled, calls on extension functions that are
not available in a particular implementation do not cause
an error unless the function call is actually evaluated.
For further details, see 18.1 Extension
Functions.
Note:
This might appear to contradict the specification of XPath 2.0, which states that a static error [XPST0017] is raised when an expression contains a call to a function that is not present (with matching name and arity) in the static context. This apparent contradiction is resolved by specifying that the XSLT processor constructs a static context for the expression in which every possible function name and arity (other than names in the standard function namespace) is present; when no other implementation of the function is available, the function call is bound to a fallback error function whose run-time effect is to raise a dynamic error.
Certain XSLT constructs also produce different results when backwards-compatible behavior is enabled. This is described separately for each such construct.
These rules do not apply to the xsl:output
element,
whose version
attribute has an entirely
different purpose: it is used to define the version of the
output method to be used for serialization.
Note:
By making use of backwards-compatible behavior, it is possible to write the stylesheet in a way that ensures that its results when processed with an XSLT 2.0 processor are identical to the effects of processing the same stylesheet using an XSLT 1.0 processor. The differences are described (non-normatively) in J.1 Incompatible Changes. To assist with transition, some parts of a stylesheet may be processed with backwards compatible behavior enabled, and other parts with this behavior disabled. All data values manipulated by an XSLT 2.0 processor are defined by the XDM data model, whether or not the relevant expressions use backwards compatible behavior. Because the same data model is used in both cases, expressions are fully composable. The result of evaluating instructions or expressions with backwards compatible behavior is fully defined in the XSLT 2.0 and XPath 2.0 specifications, it is not defined by reference to the XSLT 1.0 and XPath 1.0 specifications.
It is implementation-defined whether a particular XSLT 2.0 implementation supports backwards-compatible behavior.
[ERR XTDE0160] If an implementation does not support backwards-compatible behavior, then it is a non-recoverable dynamic error if any element is evaluated that enables backwards-compatible behavior.
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:import-schema
.
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.
The intent of forwards-compatible behavior is to make it possible to write a stylesheet that takes advantage of features introduced in some version of XSLT subsequent to XSLT 2.0, while retaining the ability to execute the stylesheet with an XSLT 2.0 processor using appropriate fallback behavior.
It is always possible to write conditional code to run
under different XSLT versions by using the
use-when
feature described in 3.12 Conditional Element
Inclusion. The rules for forwards-compatible
behavior supplement this mechanism in two ways:
certain constructs in the stylesheet that mean nothing to an XSLT 2.0 processor are ignored, rather than being treated as errors.
explicit fallback behavior can be defined for
instructions defined in a future XSLT release, using
the xsl:fallback
instruction.
The detailed rules follow.
[Definition: An element enables
forwards-compatible behavior for itself, its
attributes, its descendants and their attributes if it has
an [xsl:]version
attribute (see 3.5 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: it is used to
define the version of the output method to be used for
serialization.
Within a section of a stylesheet where forwards-compatible behavior is enabled:
if an element in the XSLT namespace appears as a
child of the xsl:stylesheet
element, and XSLT 2.0 does not allow such elements to
occur as children of the xsl:stylesheet
element, then the element and its content must be ignored.
if an element has an attribute that XSLT 2.0 does not allow the element to have, then the attribute must be ignored.
if an element in the XSLT namespace appears as part of a sequence constructor, and XSLT 2.0 does not allow such elements to appear as part of a sequence constructor, then:
If the element has one or more xsl:fallback
children, then no error is reported either
statically or dynamically, and the result of
evaluating the instruction is the concatenation of
the sequences formed by evaluating the sequence
constructors within its xsl:fallback
children, in document order. Siblings of the
xsl:fallback
elements are ignored, even if they are valid XSLT
2.0 instructions.
If the element has no xsl:fallback
children, then a static error is reported in the
same way as if forwards-compatible behavior were
not enabled.
For example, an XSLT 2.0 processor will process the following stylesheet without error, although the stylesheet includes elements from the XSLT namespace that are not defined in this specification:
<xsl:stylesheet version="17.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:template match="/"> <xsl:exciting-new-17.0-feature> <xsl:fly-to-the-moon/> <xsl:fallback> <html> <head> <title>XSLT 17.0 required</title> </head> <body> <p>Sorry, this stylesheet requires XSLT 17.0.</p> </body> </html> </xsl:fallback> </xsl:exciting-new-17.0-feature> </xsl:template> </xsl:stylesheet>
Note:
If a stylesheet depends crucially on a declaration
introduced by a version of XSLT after 2.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="number(system-property('xsl:version')) lt 17.0"> <xsl:message terminate="yes"> <xsl:text>Sorry, this stylesheet requires XSLT 17.0.</xsl:text> </xsl:message> </xsl:when> <xsl:otherwise> ... </xsl:otherwise> </xsl:choose> </xsl:template> ... </xsl:stylesheet>
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.
The include and import mechanisms use two
declarations, xsl:include
and
xsl:import
,
which are defined in the sections that follow.
These declarations use an href
attribute,
whose value is a URI reference, to identify the
stylesheet module to be
included or imported. If the value of this attribute is a
relative URI, it is resolved as described in
5.8 URI
References.
After resolving against the base URI, the way in which the URI reference is used to locate a representation of a stylesheet module, and the way in which the stylesheet module is constructed from that representation, are implementation-defined. In particular, it is implementation-defined which URI schemes are supported, whether fragment identifiers are supported, and what media types are supported. Conventionally, the URI is a reference to a resource containing the stylesheet module as a source XML document, or it may include a fragment identifier that selects an embedded stylesheet module within a source XML document; but the implementation is free to use other mechanisms to locate the stylesheet module identified by the URI reference.
The referenced stylesheet module may be any of the four kinds of stylesheet module: that is, it may be standalone or embedded, and it may be standard or simplified. If it is a simplified stylesheet module then it is transformed into the equivalent standard stylesheet module by applying the transformation described in 3.7 Simplified Stylesheet Modules.
Implementations may choose to accept URI references containing a fragment identifier defined by reference to the XPointer specification (see [XPointer Framework]). Note that if the implementation does not support the use of fragment identifiers in the URI reference, then it will not be possible to include an embedded stylesheet module.
[ERR XTSE0165] It is a static error if the processor is not able to retrieve the resource identified by the URI reference, or if the resource that is retrieved does not contain a stylesheet module conforming to this specification.
<!-- 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 a required
href
attribute whose value is a URI
reference identifying the stylesheet module to be
included. This attribute is used as described in 3.10.1 Locating Stylesheet
Modules.
[ERR XTSE0170] An xsl:include
element
must be a top-level element.
[Definition: A stylesheet level is a
collection of stylesheet modules connected
using xsl:include
declarations: specifically, two stylesheet modules
A and B are part of the same
stylesheet level if one of them includes the other by
means of an xsl:include
declaration, or if there is a third stylesheet module
C that is in the same stylesheet level as both
A and B.]
[Definition: The declarations within a stylesheet
level have a total ordering known as declaration
order. The order of declarations within a stylesheet
level is the same as the document order that would result
if each stylesheet module were inserted textually in
place of the xsl:include
element
that references it.] In
other respects, however, the effect of xsl:include
is not
equivalent to the effect that would be obtained by
textual inclusion.
[ERR XTSE0180] It is a static error if a stylesheet module directly or indirectly includes itself.
Note:
It is not intrinsically an error for a stylesheet to include the same module more than once. However, doing so can cause errors because of duplicate definitions. Such multiple inclusions are less obvious when they are indirect. For example, if stylesheet B includes stylesheet A, stylesheet C includes stylesheet A, and stylesheet D includes both stylesheet B and stylesheet C, then A will be included indirectly by D twice. If all of B, C and D are used as independent stylesheets, then the error can be avoided by separating everything in B other than the inclusion of A into a separate stylesheet B' and changing B to contain just inclusions of B' and A, similarly for C, and then changing D to include A, B', C'.
<!-- Category: declaration
-->
<xsl:import
href =
uri-reference />
A stylesheet module may import another stylesheet module using an
xsl:import
declaration. Importing a stylesheet
module is the same as including it (see
3.10.2 Stylesheet
Inclusion) except that template rules and other
declarations in the importing
module take precedence over template rules
and declarations in the imported module;
this is described in more detail below.
The xsl:import
declaration
has a required
href
attribute whose value is a URI
reference identifying the stylesheet module to be
included. This attribute is used as described in 3.10.1 Locating Stylesheet
Modules.
[ERR XTSE0190] An xsl:import
element
must be a top-level element.
[ERR XTSE0200] The xsl:import
element
children must precede all other
element children of an xsl:stylesheet
element, including any xsl:include
element
children and any user-defined data
elements.
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>
[Definition: The stylesheet levels making up a
stylesheet are treated as forming an
import tree. In the import tree, each stylesheet
level has one child for each xsl:import
declaration
that it contains.] The
ordering of the children is the declaration order of the
xsl:import
declarations within their stylesheet level.
[Definition: A declaration D in the stylesheet is defined to have lower import precedence than another declaration E if the stylesheet level containing D would be visited before the stylesheet level containing E in a post-order traversal of the import tree (that is, a traversal of the import tree in which a stylesheet level is visited after its children). Two declarations within the same stylesheet level have the same import precedence.]
For example, suppose
stylesheet module A imports stylesheet modules B and C in that order;
stylesheet module B imports stylesheet module D;
stylesheet module C imports stylesheet module E.
Then the import tree has the following structure:
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.
[ERR XTSE0210] It is a static error if a stylesheet module directly or indirectly imports itself.
Note:
The case where a stylesheet module with a particular URI is imported several times is not treated specially. The effect is exactly the same as if several stylesheet modules with different URIs but identical content were imported. This might or might not cause an error, depending on the content of the stylesheet module.
An embedded stylesheet module is a stylesheet module whose containing element is not the outermost element of the containing XML document. Both standard stylesheet modules and simplified stylesheet modules may be embedded in this way.
Two situations where embedded stylesheets may be useful are:
The stylesheet may be embedded in the source document to be transformed.
The stylesheet may be embedded in an XML document that describes a sequence of processing of which the XSLT transformation forms just one part.
The xsl:stylesheet
element may have an
id
attribute to facilitate reference to the
stylesheet module within the containing document.
Note:
In order for such an attribute value to be used as a
fragment identifier in a URI, the XDM attribute
node must generally have the is-id
property: see Section
5.5 is-id AccessorDM. This
property will typically be set if the attribute is
defined in a DTD as being of type ID
, or if
is defined in a schema as being of type
xs:ID
. It is also necessary that the media
type of the containing document should support the use of
ID values as fragment identifiers. Such support is
widespread in existing products, and is expected to be
endorsed in respect of the media type
application/xml
by a future revision of
[RFC3023].
An alternative, if the implementation supports it, is
to use an xml:id
attribute. XSLT allows this
attribute (like other namespaced attributes) to appear on
any XSLT
element.
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 is subject to
confirmation: see 3.4 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 required for conformance with this
Recommendation. Implementations are not constrained
in the mechanisms they use to identify a stylesheet when
a transformation is initiated: see 2.3 Initiating a
Transformation.
Any element in the XSLT namespace may have a
use-when
attribute whose value is an XPath
expression that can be evaluated statically. If the
attribute is present and the effective boolean
valueXP of the expression is
false, then the element, together with all the nodes having
that element as an ancestor, is effectively excluded from
the stylesheet module. When a node
is effectively excluded from a stylesheet module the
stylesheet module has the same effect as if the node were
not there. Among other things this means that no static or
dynamic errors will be reported in respect of the element
and its contents, other than errors in the
use-when
attribute itself.
Note:
This does not apply to XML parsing or validation
errors, which will be reported in the usual way. It
also does not apply to attributes that are necessarily
processed before [xsl:]use-when
, examples
being xml:space
and
[xsl:]xpath-default-namespace
.
A literal result element,
or any other element within a stylesheet
module that is not in the XSLT namespace, may
similarly carry an xsl:use-when
attribute.
If the xsl:stylesheet
or
xsl:transform
element itself is effectively excluded, the effect is to
exclude all the children of the xsl:stylesheet
or
xsl:transform
element, but not the xsl:stylesheet
or
xsl:transform
element or its attributes.
Note:
This allows all the declarations that depend on the
same condition to be included in one stylesheet module,
and for their inclusion or exclusion to be controlled by
a single use-when
attribute at the level of
the module.
Conditional element exclusion happens after stripping of whitespace text nodes from the stylesheet, as described in 4.2 Stripping Whitespace from the Stylesheet.
There are no syntactic constraints on the XPath
expression that can be used as the value of the
use-when
attribute. However, there are severe
constraints on the information provided in its evaluation
context. These constraints are designed to ensure that the
expression can be evaluated at the earliest possible stage
of stylesheet processing, without any dependency on
information contained in the stylesheet itself or in any
source document.
Specifically, the components of the static and dynamic context are defined by the following two tables:
| Component | Value |
|---|---|
| XPath 1.0 compatibility mode | false |
| In scope namespaces | determined by the in-scope namespaces for the containing element in the stylesheet |
| Default element/type namespace | determined by the
xpath-default-namespace attribute if
present (see 5.2
Unprefixed QNames in Expressions and
Patterns); otherwise the null namespace |
| Default function namespace | The standard function namespace |
| In scope type definitions | The type definitions that would be available in
the absence of any xsl:import-schema
declaration |
| In scope element declarations | None |
| In scope attribute declarations | None |
| In scope variables | None |
| In scope functions | The core functions defined in
[Functions and
Operators], together with the functions element-available ,
function-available ,
type-available ,
and system-property
defined in this specification, plus the set of
extension functions that are present in the static
context of every XPath expression (other than a
use-when expression) within the content of the
element that is the parent of the
use-when attribute. Note that
stylesheet functions
are not included in the context, which means
that the function function-available
will return false in respect of such
functions. The effect of this rule is to ensure
that function-available
returns true in respect of functions that can be
called within the scope of the use-when
attribute. It also has the effect that these
extensions functions will be recognized within the
use-when attribute itself; however, the
fact that a function is available in this sense gives
no guarantee that a call on the function will
succeed. |
| In scope collations | Implementation-defined |
| Default collation | The Unicode Codepoint Collation |
| Base URI | The base URI of the containing element in the stylesheet |
| Statically known documents | None |
| Statically known collections | None |
| Component | Value |
|---|---|
| Context item, position, and size | Undefined |
| Dynamic variables | None |
| Current date and time | Implementation-defined |
| Implicit timezone | Implementation-defined |
| Available documents | None |
| Available collections | None |
Within a stylesheet module, all
expressions contained in [xsl:]use-when
attributes are evaluated in a single execution
scopeFO. This need not be the
same execution scope as that used for
[xsl]:use-when
expressions in other stylesheet
modules, or as that used when evaluating XPath expressions
appearing elsewhere in the stylesheet module. This means
that a function such as
current-date
FO will
return the same result when called in different
[xsl:]use-when
expressions within the same
stylesheet module, but will not necessarily return the same
result as the same call in an [xsl:]use-when
expression within a different stylesheet module, or as a
call on the same function executed during the
transformation proper.
The use of [xsl:]use-when
is illustrated in
the following examples.
This example demonstrates the use of the
use-when
attribute to achieve portability of
a stylesheet across schema-aware and non-schema-aware
processors.
<xsl:import-schema schema-location="http://example.com/schema" use-when="system-property('xsl:is-schema-aware')='yes'"/> <xsl:template match="/" use-when="system-property('xsl:is-schema-aware')='yes'" priority="2"> <xsl:result-document validation="strict"> <xsl:apply-templates/> </xsl:result-document> </xsl:template> <xsl:template match="/"> <xsl:apply-templates/> </xsl:template>
The effect of these declarations is that a
non-schema-aware processor ignores the xsl:import-schema
declaration and the first template rule, and therefore
generates no errors in respect of the schema-related
constructs in these declarations.
This example includes different stylesheet modules depending on which XSLT processor is in use.
<xsl:include href="module-A.xsl" use-when="system-property('xsl:vendor')='vendor-A'"/> <xsl:include href="module-B.xsl" use-when="system-property('xsl:vendor')='vendor-B'"/>
Every XSLT 2.0 processor includes the following named type definitions in the in-scope schema components:
All the primitive atomic types defined in [XML Schema Part 2], with the
exception of xs:NOTATION
. That is:
xs:string
, xs:boolean
,
xs:decimal
, xs:double
,
xs:float
, xs:date
,
xs:time
, xs:dateTime
,
xs:duration
, xs:QName
,
xs:anyURI
, xs:gDay
,
xs:gMonthDay
, xs:gMonth
,
xs:gYearMonth
, xs:gYear
,
xs:base64Binary
, and
xs:hexBinary
.
The derived atomic type xs:integer
defined in [XML Schema Part
2].
The types xs:anyType
and
xs:anySimpleType
.
The following types defined in [XPath 2.0]:
xs:yearMonthDuration
,
xs:dayTimeDuration
,
xs:anyAtomicType
,
xs:untyped
, and
xs:untypedAtomic
.
A schema-aware XSLT processor additionally supports:
All other built-in types defined in [XML Schema Part 2]
User-defined types, and element and attribute
declarations, that are imported using an xsl:import-schema
declaration as described in 3.14 Importing Schema
Components. These may include both simple and
complex types.
Note:
The names that are imported from the XML Schema
namespace do not include all the names of top-level types
defined in either the Schema for Schemas or the Schema
for Datatypes. The Schema for Datatypes, as well as
defining built-in types such as xs:integer
and xs:double
, also defines types that are
intended for use only within the Schema for DataTypes,
such as xs:derivationControl
. A stylesheet that is
designed to process XML Schema documents as its input or
output may import the Schema for Schemas.
An implementation may define mechanisms that allow additional schema components to be added to the in-scope schema components for the stylesheet. For example, the mechanisms used to define extension functions (see 18.1 Extension Functions) may also be used to import the types used in the interface to such functions.
These schema components are the only
ones that may be referenced in XPath expressions within the
stylesheet, or in the [xsl:]type
and
as
attributes of those elements that permit
these attributes.
For a Basic XSLT Processor, schema built-in types that
are not included in the static context (for example,
xs:NCName
) are "unknown types" in the sense of
Section
2.5.4 SequenceType
MatchingXP. In the language
of that section, a Basic XSLT Processor must be able to determine whether these
unknown types are derived from known schema types such as
xs:string
. The purpose of this rule is to
ensure that system functions such as
local-name-from-QName
FO,
which is defined to return an xs:NCName
,
behave correctly. A stylesheet that uses a Basic XSLT
Processor will not be able to test whether the returned
value is an xs:NCName
, but it will be able to
use it as if it were an xs:string
.
Note:
The facilities described in this section are not available with a basic XSLT processor. They require a schema-aware XSLT processor, as described in 21 Conformance.
<!-- Category:
declaration -->
<xsl:import-schema
namespace? = uri-reference
schema-location? =
uri-reference>
<!-- Content: xs:schema? -->
</xsl:import-schema>
The xsl:import-schema
declaration is used to identify schema components (that is,
top-level type definitions and top-level element and
attribute declarations) that need to be available
statically, that is, before any source document is
available. Names of such components used statically within
the stylesheet must refer to an in-scope schema
component, which means they must either be built-in
types as defined in 3.13
Built-in Types, or they must be imported using an
xsl:import-schema
declaration.
The xsl:import-schema
declaration identifies a namespace containing the names of
the components to be imported (or indicates that components
whose names are in no namespace are to be imported). The
effect is that the names of top-level element and attribute
declarations and type definitions from this namespace (or
non-namespace) become available for use within XPath
expressions in the stylesheet, and within other
stylesheet constructs such as the type
and
as
attributes of various XSLT
elements.
The same schema components are available in all stylesheet modules; importing components in one stylesheet module makes them available throughout the stylesheet.
The namespace
and
schema-location
attributes are both
optional.
If the xsl:import-schema
element contains an xs:schema
element, then
the schema-location
attribute must be absent,
and the namespace
attribute must either have
the same value as the targetNamespace
attribute of the xs:schema
element (if
present), or must be absent, in which case its effective
value is that of the targetNamespace
attribute
of the xs:schema
element if present or the
zero-length string otherwise.
[ERR XTSE0215] It is a static error if
an xsl:import-schema
element that contains an xs:schema
element has
a schema-location
attribute, or if it has a
namespace
attribute that conflicts with the
target namespace of the contained schema.
If two xsl:import-schema
declarations specify the same namespace, or if both specify
no namespace, then only the one with highest import
precedence is used. If this leaves more than one, then
all the declarations at the highest import precedence are
used (which may cause conflicts, as described below).
After discarding any xsl:import-schema
declarations under the above rule, the effect of the
remaining xsl:import-schema
declarations is defined in terms of a hypothetical document
called the synthetic schema document, which is constructed
as follows. The synthetic schema document defines an
arbitrary target namespace that is different from any
namespace actually used by the application, and it contains
xs:import
elements corresponding one-for-one
with the xsl:import-schema
declarations in the stylesheet, with the following
correspondence:
The namespace
attribute of the
xs:import
element is copied from the
namespace
attribute of the xsl:import-schema
declaration if it is explicitly present, or is
implied by the targetNamespace
attribute
of a contained xs:schema
element,
and is absent if it is absent.
The schemaLocation
attribute of the
xs:import
element is copied from the
schema-location
attribute of the xsl:import-schema
declaration if present, and is absent if it is absent.
If there is a contained xs:schema
element, the effective value of the
schemaLocation
attribute is a URI
referencing a document containing a copy of the
xs:schema
element.
The base URI of the xs:import
element
is the same as the base URI of the xsl:import-schema
declaration.
The schema components included in the in-scope schema components (that is, the components whose names are available for use within the stylesheet) are the top-level element and attribute declarations and type definitions that are available for reference within the synthetic schema document. See [XML Schema Part 1] (section 4.2.3, References to schema components across namespaces).
[ERR XTSE0220] It is a static error if the synthetic schema document does not satisfy the constraints described in [XML Schema Part 1] (section 5.1, Errors in Schema Construction and Structure). This includes, without loss of generality, conflicts such as multiple definitions of the same name.
Note:
The synthetic schema document does not need to be
constructed by a real implementation. It is purely a
mechanism for defining the semantics of xsl:import-schema
in terms of rules that already exist within the XML
Schema specification. In particular, it implicitly
defines the rules that determine whether the set of
xsl:import-schema
declarations are mutually consistent.
These rules do not cause names to be imported transitively. The fact that a name is available for reference within a schema document A does not of itself make the name available for reference in a stylesheet that imports the target namespace of schema document A. (See [XML Schema Part 1] section 3.15.3, Constraints on XML Representations of Schemas.) The stylesheet must import all the namespaces containing names that it actually references.
The namespace
attribute indicates that a
schema for the given namespace is required by the
stylesheet. This information may be
enough on its own to enable an implementation to locate
the required schema components. The
namespace
attribute may be omitted to
indicate that a schema for names in no namespace is being
imported. The zero-length string is not a valid namespace
URI, and is therefore not a valid value for the
namespace
attribute.
The schema-location
attribute is a
URI
Reference that gives a hint indicating where a schema
document or other resource containing the required
definitions may be found. It is likely that a schema-aware XSLT
processor will be able to process a schema document
found at this location.
The XML Schema specification gives implementations flexibility in how to handle multiple imports for the same namespace. Multiple imports do not cause errors if the definitions do not conflict.
A consequence of these rules is that it is not
intrinsically an error if no schema document can be
located for a namespace identified in an xsl:import-schema
declaration. This will cause an error only if it results
in the stylesheet containing references to names that
have not been imported.
An inline schema document (using an
xs:schema
element as a child of the
xsl:import-schema
element) has the same
status as an external schema document, in the sense that
it acts as a hint for a source of schema components in
the relevant namespace. To ensure that the inline schema
document is always used, it is advisable to use a target
namespace that is unique to this schema document.
The use of a namespace in an xsl:import-schema
declaration does not by itself associate any namespace
prefix with the namespace. If names from the namespace are
used within the stylesheet module then a namespace
declaration must be included in the stylesheet module, in
the usual way.
The following example shows an inline schema document.
This declares a simple type local:yes-no
,
which the stylesheet then uses in the declaration of a
variable.
The example assumes the namespace declaration
xmlns:local="http://localhost/ns/yes-no"
<xsl:import-schema> <xs:schema targetNamespace="http://localhost/ns/yes-no" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="local:yes-no"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> </xs:schema> </xsl:import-schema> <xs:variable name="condition" select="'yes'" as="local:yes-no"/>
The data model used by XSLT is the XPath 2.0 and XQuery 1.0 data model (XDM), as defined in [Data Model]. XSLT operates on source, result and stylesheet documents using the same data model.
This section elaborates on some particular features of XDM as it is used by XSLT:
The rules in 4.2 Stripping Whitespace from the Stylesheet and 4.4 Stripping Whitespace from a Source Tree make use of the concept of a whitespace text node.
[Definition: A whitespace text node is a text node whose content consists entirely of whitespace characters (that is, #x09, #x0A, #x0D, or #x20).]
Note:
Features of a source XML document that are not represented in the XDM tree will have no effect on the operation of an XSLT stylesheet. Examples of such features are entity references, CDATA sections, character references, whitespace within element tags, and the choice of single or double quotes around attribute values.
The XDM data model defined in [Data Model] is capable of representing either an XML 1.0 document (conforming to [XML 1.0] and [Namespaces in XML 1.0]) or an XML 1.1 document (conforming to [XML 1.1] and [Namespaces in XML 1.1]), and it makes no distinction between the two. In principle, therefore, XSLT 2.0 can be used with either of these XML versions.
Construction of the XDM tree is outside the scope of this specification, so XSLT 2.0 places no formal requirements on an XSLT processor to accept input from either XML 1.0 documents or XML 1.1 documents or both. This specification does define a serialization capability (see 20 Serialization), though from a conformance point of view it is an optional feature. Although facilities are described for serializing the XDM tree as either XML 1.0 or XML 1.1 (and controlling the choice), there is again no formal requirement on an XSLT processor to support either or both of these XML versions as serialization targets.
Because the XDM tree is the same whether the original document was XML 1.0 or XML 1.1, the semantics of XSLT processing do not depend on the version of XML used by the original document. There is no reason in principle why all the input and output documents used in a single transformation must conform to the same version of XML.
Some of the syntactic constructs in XSLT 2.0 and XPath 2.0, for example the productions Char XML and NCName Names, are defined by reference to the XML and XML Namespaces specifications. There are slight variations between the XML 1.0 and XML 1.1 versions of these productions. Implementations may support either version; it is recommended that an XSLT 2.0 processor that implements the 1.1 versions should also provide a mode that supports the 1.0 versions. It is thus implementation-defined whether the XSLT processor supports XML 1.0 with XML Namespaces 1.0, or XML 1.1 with XML Namespaces 1.1, or supports both versions at user option.
Note:
The specification referenced as [Namespaces in XML 1.0] was actually published without a version number.
At the time of writing there is no published version of
[XML Schema Part 2] that
references the XML 1.1 specifications. This means that data
types such as xs:NCName
and xs:ID
are constrained by the XML 1.0 rules, and do not allow the
full range of values permitted by XML 1.1. This situation
will not be resolved until a new version of [XML Schema Part 2] becomes available;
in the meantime, it is recommended that implementers wishing to
support XML 1.1 should consult [XML Schema 1.0 and XML 1.1] for
guidance. An XSLT 2.0 processor that supports XML 1.1
should implement the rules in
later versions of [XML Schema Part
2] as they become available.
The tree representing the stylesheet is preprocessed as follows:
All comments and processing instructions are removed.
Any text nodes that are now adjacent to each other are merged.
Any whitespace text node that satisfies both the following conditions is removed from the tree:
The parent of the text node is not an xsl:text
element
The text node does not have an ancestor element
that has an xml:space
attribute with a
value of preserve
, unless there is a
closer ancestor element having an
xml:space
attribute with a value of
default
.
Any whitespace text node
whose parent is one of the following elements is
removed from the tree, regardless of any
xml:space
attributes:
xsl:analyze-string
xsl:apply-imports
xsl:apply-templates
xsl:attribute-set
xsl:call-template
xsl:character-map
xsl:choose
xsl:next-match
xsl:stylesheet
xsl:transform
Any whitespace text node
whose following-sibling node is an xsl:param
or xsl:sort
element is
removed from the tree, regardless of any
xml:space
attributes.
[ERR XTSE0260] Within an XSLT element
that is required to be empty, any
content other than comments or processing instructions,
including any whitespace text node
preserved using the xml:space="preserve"
attribute, is a static error.
Note:
Using xml:space="preserve"
in parts of
the stylesheet that contain sequence constructors will
cause all text nodes in that part of the stylesheet,