AbstractThis 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. The changes made in this document are
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.
A summary of the changes since XSLT 1.0
is included in J Changes from XSLT 1.0. 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 is a Candidate
Recommendation as described in the
W3C Process Document.
This document is intended for review by W3C members and other interested
parties. The publication of this document constitutes a
call for
implementations of this specification. This specification will remain
a Candidate Recommendation until at least 28 February 2006. This document has been produced by the
XSL Working Group, which is part of the
XML Activity. Publication
as a Candidate Recommendation does not imply endorsement by the W3C
Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress. This draft includes corrections and changes based on public comments on
the Last Call
Working Draft dated 4 April 2005, reflecting decisions made by the
working groups through 29 September 2005 (plus some later editorial corrections). These decisions
are recorded in the W3C public Bugzilla repository
(http://www.w3.org/Bugs/Public/)
used for Last Call issues tracking. A full list of changes since the Last
Call Working Draft of 4 April 2005 is included (see
J.2.4 Changes in the 15 September 2005 Draft and J.2.5 Changes in the Candidate Recommendation).
In addition, this document is published in two versions:
one that highlights changes
since the Last Call Working Draft of 4 April 2005, and
one without change highlighting.
Comments on this document should be made 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 mailing list,
public-qt-comments@w3.org (archived at
http://lists.w3.org/Archives/Public/public-qt-comments/).
It will be very helpful if you 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/. The agreed exit criteria for this Candidate Recommendation (that is, the criteria for its becoming
a Proposed Recommendation)
are as follows: - Sufficient reports of implementation experience have been
gathered to demonstrate that XSLT processors based on the
specification are implementable and have compatible behavior.
The WG expects to have at least two implementations of each
required feature.
- An implementation report has been produced indicating the results of testing each
distinct feature in the test plan. The WG believes that these
features cover the specification.
The patent policy for this document is the
5 February 2004 W3C Patent Policy.
Patent disclosures relevant to this specification may
be found on the
XSL Working Group's patent
disclosure page. An individual who has actual knowledge of a patent
which the individual believes contains Essential Claim(s) with respect to
this specification should disclose the information in accordance with
section 6
of the W3C Patent Policy.
1 Introduction
1.1 What is XSLT?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.
1.2 What's New in XSLT 2.0?
XSLT 1.0 was published in November 1999, and version 2.0 represents a significant increase
in the capability of the language. A detailed list of changes is included in 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.
2 Concepts
2.1 TerminologyFor 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,
and collection, 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.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 . 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 .
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 .
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 . 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·.
2.2 Notation
In this document the specification of each XSLT-defined element type is preceded by
a summary of its syntax in the form of a model for elements of that
element type. A full list of all these specifications can be found in
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: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. XSLT defines a set of standard functions which are additional to those defined
in [Functions and Operators]. The signatures of these functions are described using the
same notation as used in [Functions and Operators].
The names of these functions are all in the
·standard function namespace·.
2.3 Initiating a Transformation
This document does not specify any application programming interfaces or other
interfaces for initiating a transformation. This section, however, describes the information that is
supplied when a transformation is initiated. Except where otherwise indicated, the information
is required. Implementations may allow a transformation to run as two or more phases, for example parsing, compilation and
execution. Such a distinction is outside the scope of this specification, which treats transformation as a single
process controlled using a set of ·stylesheet modules·, supplied
in the form of XML documents. The following information is supplied to execute a transformation: - The ·stylesheet module· that is
to act as the ·principal stylesheet module· for the transformation.
The complete ·stylesheet· is assembled by recursively
expanding the
xsl:import and
xsl:include
declarations in the principal stylesheet module, as described in 3.10.2 Stylesheet Inclusion and 3.10.3 Stylesheet Import.
- A set (possibly empty) of values for ·stylesheet parameters·
(see 9.5 Global Variables and Parameters). These
values are available for use within ·expressions· in the
·stylesheet·.
-
[Definition:] 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 5.4.3.1 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·. 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 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 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 or collection (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).
2.4 Executing a Transformation
[Definition:] A stylesheet contains a
set of template rules (see 6 Template Rules). A template rule has two parts: a
·pattern· that is matched against nodes, 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
[ err:XPDE1490].
, since it is not possible to create two final result
trees with the same URI. [Definition:] The elements appearing within a sequence constructor are
referred to as instructions. The main categories of instruction elements 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·.
2.5 The Evaluation Context
The results of some expressions and instructions in a stylesheet may depend on information
provided contextually. This context information is divided into two categories: the static
context, which is known during static analysis of the stylesheet, and the dynamic context, which
is not known until the stylesheet is evaluated. Although information in the static context is
known at analysis time, it is sometimes used during stylesheet evaluation. Some context information can be set by means of declarations within the stylesheet itself.
For example, the namespace bindings used for any XPath expression are determined by the namespace
declarations present in containing elements in the stylesheet. Other information may
be supplied externally or implicitly: an example is the current date and time. The context information used in processing an XSLT stylesheet includes as a subset all the context
information required when evaluating XPath expressions. The XPath 2.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.
2.6 Parsing and Serialization
An XSLT ·stylesheet· describes a process that
constructs a set of ·final result trees· from a set of
·source trees·. The ·stylesheet· does not describe how a
·source tree· is constructed.
Some possible ways of constructing source trees
are described in [Data Model].
Frequently
an ·implementation· will operate in conjunction
with an XML parser (or more strictly, in the
terminology of [XML 1.0], an XML processor), to build a source
tree from an input XML document. An implementation may also provide an application programming
interface allowing the tree to be constructed directly, or allowing it to be supplied in the form of a
DOM Document object (see [DOM Level 2]). This is outside the scope of this specification.
Users should be aware, however, that since the input to the transformation is a tree conforming
to the XDM data model as described in [Data Model], constructs that might exist in the
original XML document, or in the DOM, but which are not within the scope of the data model,
cannot be processed by the ·stylesheet· and cannot be guaranteed to
remain unchanged in the transformation output. Such constructs include CDATA section boundaries,
the use of entity references, and the DOCTYPE declaration and internal DTD subset.
[Definition:] A frequent requirement is to
output a ·final result tree· as an XML document (or in other formats such as HTML).
This process is referred to as serialization. Like parsing, serialization is not part of the transformation
process, and it is not required that an XSLT processor must be able to perform
serialization. However, for pragmatic reasons, this specification describes declarations
(the
xsl:output element and the
xsl:character-map declarations,
see 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.
2.7 Extensibility
XSLT defines a number of features that allow the language to be extended by
implementers, or, if implementers choose to provide the capability, by users. These features
have been designed, so far as possible, so that they can be used without sacrificing interoperability.
Extensions other than those explicitly defined in this specification are not permitted. These features are all based on XML namespaces; namespaces are used to ensure that the
extensions provided by one implementer do not clash with those of a different implementer. The most common way of extending the language is by providing additional functions, which
can be invoked from XPath expressions. These are known as
·extension functions·, and are described in
18.1 Extension Functions. It is also permissible to extend the language by providing new XSLT 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).
2.8 Stylesheets and XML Schemas
An XSLT ·stylesheet·
can make use of information from a schema. An XSLT transformation can take place
in the absence of a
schema (and, indeed, in the absence of a DTD), but where the source document has
undergone schema validity assessment, the XSLT processor has access to the type
information associated with individual nodes, not merely to the untyped text. Information from a schema can be used both statically (when the ·stylesheet· is compiled),
and dynamically (during evaluation of the stylesheet to transform a source document). There are places within a ·stylesheet·,
and within XPath ·expressions· and
·patterns· in
a ·stylesheet·, where it is possible
to refer to named type definitions in a schema, or to element and attribute declarations.
For example, it is
possible to declare the types expected for the parameters of a function.
This is done using the SequenceType 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 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:
Example: Asserting the Required Type of the Source Document <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 xdt:untyped and xdt: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.
2.9 Error Handling
[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 )
that if any expression (at any level) can be evaluated during the analysis phase
(because all its explicit operands are known and it has no dependencies on the dynamic context),
then any error in performing this evaluation may be reported as a static error.
For XPath expressions used in an XSLT stylesheet, however, any
such errors must not be reported as static errors in the stylesheet unless they
would occur in every possible evaluation of that stylesheet; instead, they must be
signaled as dynamic errors, and signaled only if the XPath expression is actually evaluated.
Example: Errors in Constant Subexpressions An XPath processor
may report statically that the expression 1 div 0 fails with a "divide by zero" error.
But suppose this XPath expression occurs in an XSLT construct such as: <xsl:choose>
<xsl:when test="system-property('xsl:version') = '1.0'">
<xsl:value-of select="1 div 0"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="xs:double('INF')"/>
</xsl:otherwise>
</xsl:choose>Then the XSLT processor must not report an error, because the relevant XPath construct
appears in a context where it will never be executed by an XSLT 2.0 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.
As with other aspects of serialization,
the handling of serialization errors is
·implementation-defined·:
see 20 Serialization. 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.
3 Stylesheet Structure
[Definition:] A
·stylesheet·
consists of one or more stylesheet modules, each one forming
all or part of an XML document. Note: A stylesheet module is represented by an XDM element node
(see [Data Model]). Except in the case of a
·simplified stylesheet module·, this will be an
xsl:stylesheet
or
xsl:transform element. 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 a source document that is to be processed
using the stylesheet. [Definition:] A
standalone stylesheet module is a stylesheet module that comprises the whole of an XML document. [Definition:] An
embedded stylesheet module is a stylesheet module that is
embedded within another XML document, typically the source document
that is being transformed. (see 3.11 Embedded Stylesheet Modules). There are thus four kinds of stylesheet module: standalone standard stylesheet modules standalone simplified stylesheet modules embedded standard stylesheet modules embedded simplified stylesheet modules
3.1 XSLT Namespace
[Definition:] The XSLT namespace
has the URI http://www.w3.org/1999/XSL/Transform. It is used to identify
elements, attributes, and other names that have a special meaning defined in
this specification.
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.
3.2 Reserved Namespaces
[Definition:] The
XSLT namespace, together with certain other namespaces
recognized by an XSLT processor, are classified as reserved namespaces
and must be used only as specified in this and related specifications.
The reserved namespaces are those listed below. - The ·XSLT namespace·, described in
3.1 XSLT Namespace, is reserved.
- [Definition:] The standard function namespace
http://www.w3.org/2005/xpath-functions
is used for functions in the function library defined in
[Functions and Operators] and 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 XPath
datatypes namespace
http://www.w3.org/2005/xpath-datatypes is used
as defined in [Functions and Operators]. In a ·stylesheet· this namespace may be used to refer
to the types
xdt:untypedAtomic, xdt:yearMonthDuration, xdt:dayTimeDuration,
xdt:anyAtomicType, and to the constructor functions associated with
the first three of these types.
-
[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 instructions:
but other processors may impose restrictions or attach special meaning to them. Reserved namespaces must not
be used, however, in the names of stylesheet-defined objects such as
·variables· and ·stylesheet functions·. Note: With the exception of the XML namespace, any of the above namespaces that
are used in a stylesheet must be explicitly declared with a namespace declaration. Although conventional
prefixes are used for these namespaces in this specification, any prefix may be used in a user stylesheet.
[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
|