The following associated resources are available:
Copyright © 2024 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
This specification defines the syntax and semantics of XSLT 4.0, a language designed primarily for transforming XML documents into other XML documents.
XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation [XSLT 3.0] published on 8 June 2017. Changes are presented in 1.2 What’s New in XSLT 4.0?.
XSLT 4.0 is designed to be used in conjunction with XPath 4.0, which is defined in [XPath 4.0]. XSLT shares the same data model as XPath 4.0, which is defined in [XDM 4.0], and it uses the library of functions and operators defined in [Functions and Operators 4.0]. XPath 4.0 and the underlying function library introduce a number of enhancements, for example the availability of union and record types.
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 XP40 for XPath 4.0, DM40 for the XDM data model version 4.0, FO40 for Functions and Operators version 4.0.
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 https://www.w3.org/TR/.
This document has no official standing. It is produced by the editor as a proposal for community review. Insofar as it copies large amounts of text from the W3C XSLT 3.0 Recommendation, W3C copyright and similar provisions apply.
XSLT is a programming language designed principally to transform data.
A transformation in the XSLT language is expressed in the form of a stylesheet. A stylesheet is made up of one or more well-formed XML [XML 1.0] documents conforming to the Namespaces in XML Recommendation [Namespaces in XML].
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.1 XSLT Namespace), which is referred to in this specification as the
XSLT namespace. Thus this specification
is a definition of the syntax and semantics of the XSLT namespace.
The term stylesheet reflects the fact that one of the important roles of XSLT is to add styling information to an XML source document, by transforming it into a document consisting of XSL formatting objects (see [XSL-FO]), 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 input data into output data. The inputs and outputs will all be instances of the XDM data model, described in [XDM 4.0]. In the simplest and most common case, the input is an XML document referred to as the source document or source tree, and the output is an XML document referred to as the result tree. It is also possible to process multiple source documents, to generate multiple result documents, and to handle formats other than XML.
The transformation is achieved by a set of template rules. A template rule associates a pattern, which typically 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. Because patterns can point to nodes according to typological features, a stylesheet can be applicable to a wide class of source documents that have similar tree structures.
Stylesheets are modular; they may contain several packages developed independently of each other, and each package may consist of several stylesheet modules.
[Definition: A stylesheet consists of one or more packages: specifically, one top-level package and zero or more library packages.]
[Definition: For a given transformation, one package functions as the top-level package. The
complete stylesheet is assembled by finding
the packages referenced directly or indirectly from the top-level package using
xsl:use-package
declarations: see 3.5.2 Dependencies between Packages.]
[Definition: Every package within a stylesheet, other than the top-level package, is referred to as a library package.]
[Definition: Within a package, one stylesheet module functions as the
principal stylesheet module. The complete package 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.11.2 Stylesheet Inclusion and 3.11.3 Stylesheet Import.]
Changes in 4.0 ⬇
Use the arrows to browse significant changes since the 3.0 version of this specification.
Sections with significant changes are marked Δ in the table of contents.
XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation [XSLT 3.0] published on 8 June 2017.
The changes in this version of the language are relatively minor usability enhancements. There are no changes to the data model or processing model. Instead, the specification attempts to fill a number of gaps in functionality resulting from feedback from XSLT 3.0 users. The main areas covered are:
Enhancements to the type system to allow more expressive constraints, especially for maps and atomic values.
Additional functionality for processing arrays.
Exploitation of the power afforded by first-class function items.
XSLT 4.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 4.0].
XSLT 4.0 requires support for XPath 4.0.
A full list of changes is at I Changes since XSLT 3.0.
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 tree is used (as in [XDM 4.0]) to refer to the aggregate consisting of a parentless node together with all its descendant nodes, plus all their attributes and namespaces.]
Note:
The use of the term tree in this document in phrases such as source tree, result tree, and temporary tree does not imply the use of a data structure in memory that holds the entire contents of the document at one time. It implies rather a logical view of the XML input and output in which elements have a hierarchic relationship to each other. When a source document is being processed in a streaming manner, access to the nodes in this tree is constrained, but it is still viewed and described as a tree.
The output of a transformation consists of the following:
[Definition: A principal result: this can be any sequence of items (as defined in [XDM 4.0]).] The principal result is the value returned by the function or template in the stylesheet that is nominated as the entry point, as described in 2.3 Initiating a Transformation.
[Definition: Zero or more
secondary results: each secondary result can be any sequence
of items (as defined in [XDM 4.0]).] A
secondary result is the value returned by evaluating the body of an
xsl:result-document
instruction.
Zero or more messages. Messages are generated by the
xsl:message
and xsl:assert
instructions, and are described in 24.1 Messages and 24.2 Assertions.
Static or dynamic errors: see 2.14 Error Handling.
The principal result and the secondary results may be post-processed as described in 2.3.6 Post-processing the Raw Result.
[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 output of a transformation: specifically, a tree built by post-processing the items in the principal result or in a secondary result. Once created, the contents of a final result tree are not accessible within the stylesheet itself.] Any final result tree may be serialized as described in 27 Serialization.
[Definition: The term source tree
means any tree provided as input to the transformation. This includes the document
containing the global context item if any, documents containing
nodes present in the initial match selection,
documents containing nodes supplied as the values of stylesheet parameters, documents
obtained from the results of functions such as document
,
doc
FO40, and collection
FO40, documents read using the xsl:source-document
instruction, 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.
Unless otherwise stated, the term “tree” refers to a tree rooted at a parentless node: that is, the term does not include subtrees of larger trees. Every node therefore belongs to exactly one tree.
In this specification the phrases must, must not, should, should not, may, required, and recommended, when used in normative text and rendered in small capitals, 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 28 Conformance.
Where the phrase must, must not, or required relates to a stylesheet then the processor must enforce this constraint on stylesheets by raising 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 4.0] or the XDM specification [XDM 4.0]. Particular attention is drawn to the following:
[Definition: The term atomization is defined in Section 2.5.3 AtomizationXP40. It is a process that takes as input a sequence of items, and returns a sequence of atomic items, in which the nodes are replaced by their typed values as defined in [XDM 4.0]. Arrays (see 22 Arrays) are atomized by atomizing their members, recursively.] For some items (for example, elements with element-only content, function items, and maps, atomization raises a dynamic error.
[Definition: The term typed
value is defined in Section
5.15 typed-value Accessor
DM30.
Every node, other than an element whose type
annotation identifies it as having 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 Accessor DM30. 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.2.1 Static ContextXP40. 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
4.0 and XPath 1.0.]
[Definition: The term function definition is defined in Section 2.2.1 Static ContextXP40. It is the definition of a function that can be called statically from within an XPath expression: in the case of XSLT it typically means either a stylesheet function, or a built-in function such as those defined in [Functions and Operators 4.0]]
[Definition: A function definition has an arity range, which defines the minimum and maximum number of arguments that must be supplied in a call to the function. The static context can contain multiple function definitions with the same name, provided that their arity ranges do not overlap.]
[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 the 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.
The types used, and their meanings, are as follows:
boolean
One of the strings "yes"
,
"true"
, or "1"
to indicate the value
true
, or one of the strings "no"
,
"false"
, or "0"
to indicate the value
false
. Note: the values are synonyms; where this
specification uses a phrase such as “If required='yes'
is
specified ...” this is to be interpreted as meaning “If the attribute
named required
is present, and has the value
yes
, true
, or 1
(after
stripping leading and trailing whitespace) ...”.
string
Any string.
expression
An XPath expression.
pattern
A pattern as described in 5.4 Patterns.
item-type
An ItemTypeXP40 as defined in the XPath 4.0 specification.
sequence-type
A SequenceTypeXP40 as defined in the XPath 4.0 specification.
uri; uris
A URI, for example a namespace URI or a collation URI; a whitespace-separated list of URIs.
qname
A lexical QName as defined in 5.1.1 Qualified Names.
eqname; eqnames
An EQName as defined in 5.1.1 Qualified Names; a whitespace-separated list of EQNames.
token; tokens
A string containing no significant whitespace; a whitespace-separated list of such strings.
nmtoken; nmtokens
A string conforming to the XML schema rules for the type
xs:NMTOKEN
; a whitespace-separated list of such
strings.
char
A string comprising a single Unicode character.
language
A string in the value space of xs:language
, or a zero-length string.
integer
An integer, that is, a string that is castable to the schema type
xs:integer
.
decimal
A decimal value, that is, a string that is castable to the schema
type xs:decimal
.
ncname
; ncnames
An unprefixed name: a string that is castable to the schema type
xs:NCName
; a whitespace-separated list of such strings.
prefix
; prefixes
An xs:NCName
representing a namespace prefix, which must
be in scope for the element on which it appears;
a whitespace-separated list of such strings.
id
An xs:NCName
used as a unique identifier for an element
in the containing XML document.
Except where the set of allowed values of an attribute is specified using the italicized name string or char, 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.
XPath comments (delimited by (: ... :)
)
are permitted anywhere that inter-token whitespace is permitted in attributes whose
type is given as expression, pattern, item-type,
or sequence-type, and are not permitted in attributes of other types
(other than within expressions enclosed by curly braces within an attribute value template).
If an attribute has a simple default value, this is shown between tortoise-shell
brackets (for example 〔'no'〕
). Where no default is shown,
the consequence of omitting the attribute is explained in the prose narrative.
Default values shown in the summary apply only where the attribute itself
is applicable; if an attribute is not permitted to appear in the particular context,
then its default value should be ignored. (For example, the stable
attribute of xsl:sort
is shown as having a default value
of 'yes'
, but the attribute is allowed only on the
first of a sequence of adjacent xsl:sort
elements.)
The quotation marks around a default value are not part of the value.
Unless the element is required to be empty, the model element contains a comment specifying the allowed content. The allowed content is specified in a way similar 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 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 affects only 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? = boolean
validation? = { "strict" | "lax" }〔strict〕 >
<!-- 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 the following
attributes:
A mandatory select
attribute, whose value is an XPath expression
An optional debug
attribute, whose
value must be yes
, true
, or
1
to indicate true
, or no
,
false
, or 0
to indicate false
.
An optional validation
attribute, whose value must be
strict
or lax
; the curly brackets indicate that
the value can be defined as an attribute value template, allowing a value such as
validation="{ $val }"
, where the variable
val
is evaluated to yield "strict"
or
"lax"
at run-time. The value strict
in tortoise-shell
brackets indicates the default value, if the attribute is not present.
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] It is a static error 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.
The rules in the element syntax summary (both for the element structure and for its attributes) apply to the stylesheet content after preprocessing as described in 3.13 Stylesheet Preprocessing.
[Definition: The effective value of an attribute or text node in the stylesheet is the value after any required expansion or normalization.]
More specifically, the effective value is the value after:
Expanding shadow attributes as described in 3.13.4 Shadow Attributes;
Expanding defaults (for example, if an xsl:message
instruction has
no terminate
attribute, then the effective value of the terminate
attribute
is no
);
Stripping ignored whitespace (for example, the effective value of a boolean attribute written as
terminate=" no "
is no
);
Replacing synonyms (for example in boolean attributes, 1
and true
are synonyms of yes
);
Expanding attribute value templates and text value templates.
Applying rules from the static context: for example, the effective value of a collation
attribute is the value after expanding a relative URI against the static base URI.
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 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 raise 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.10 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.]
Note:
This specification includes a non-normative XML Schema for XSLT stylesheet modules (see H Schemas for XSLT 4.0 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 4.0]. A list of these functions appears in G.2 List of XSLT-defined functions. The signatures of these functions are described using the same notation as used in [Functions and Operators 4.0]. The names of many of these functions are 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.
The execution of a stylesheet necessarily involves two activities: static analysis
and dynamic evaluation. Static analysis consists of those tasks that can be performed
by inspection of the stylesheet alone, including the
binding of static variables,
the evaluation of [xsl:]use-when
expressions (see 3.13.3 Conditional Element Inclusion) and shadow attributes
(see 3.13.4 Shadow Attributes), and the detection of static errors. Dynamic evaluation consists of
tasks which in general cannot be carried out until a source document is
available.
Dynamic evaluation is further divided into two activities: priming the stylesheet, and invoking a selected component.
Priming the stylesheet provides the dynamic context for evaluation, and supplies all the information needed to establish the values of global variables.
Invoking a component (such as a template or function) causes evaluation of that template or function to produce a result, which is an arbitrary XDM value.
[Definition: The result of invoking the selected component, after any required conversion to the declared result type of the component, is referred to as the raw result.]
The raw result of the invocation
is the immediate result of evaluating the sequence constructor
contained in the target template or function, modified by applying the coercion rules
to convert the immediate result to the type declared in the as
attribute of the xsl:template
or xsl:function
declaration, if present.
This raw result may optionally be post-processed to construct a result tree, to serialize the result, or both, as described in 2.3.6 Post-processing the Raw Result.
Implementations may allow static analysis and dynamic evaluation to be initiated independently, so that the cost of static analysis can be amortized over multiple transformations using the same stylesheet. Implementations may also allow priming of a stylesheet and invocation of components to be initiated independently, in which case a single act of priming the stylesheet may be followed by a series of independent component invocations. Although this specification does not require such a separation, this section distinguishes information that is needed before static analysis can proceed, information that is needed to prime the stylesheet, and information that is needed when invoking components.
The language is designed to allow the static analysis of each package to be performed independently of other packages, with only basic knowledge of the properties of components made available by used packages. Beyond this, the specification leaves it to implementations to decide how to organize this process. When packages are not used explicitly, the entire stylesheet is treated as a single package.
The following information is needed prior to static analysis of a package:
The location of the package manifest,
or in the absence of a package manifest, the stylesheet module that is to act as
the principal stylesheet
module
of the package. The complete package is
assembled by recursively expanding the xsl:import
and
xsl:include
declarations in the principal stylesheet
module, as described in 3.11.2 Stylesheet Inclusion and 3.11.3 Stylesheet Import.
Information about the packages referenced from this
package using xsl:use-package
declarations. The information
needed will include the names and signatures of public components exported
by the referenced package.
A set (possibly empty) of values for static parameters (see 9.5 Global Variables and Parameters). These values are available for use within
static expressions (notably
in [xsl:]use-when
expressions and shadow attributes) as well as
non-static expressions in the stylesheet. As a minimum, values must be
supplied for any static parameters declared with the attribute
required="yes"
.
Conceptually, the output of the static analysis of a package is an object which might be referred to (without constraining the implementation) as a compiled package. Prior to dynamic evaluation, all the compiled packages needed for execution must be checked for consistency, and component references must be resolved. This process may be referred to, again without constraining the implementation, as linking.
The information needed when priming a stylesheet is as follows:
A set (possibly empty) of values for non-static
stylesheet parameters (see
9.5 Global Variables and Parameters). These values are available for use
within expressions in the stylesheet. As a minimum, values
must be supplied for any parameters declared with the
attribute required="yes"
.
A supplied value is converted if necessary to the declared type of the stylesheet parameter using the coercion rules.
Note:
Non-static stylesheet parameters are implicitly
public
, which ensures that all the parameters in the
stylesheet for which values can be supplied externally have distinct
names. Static parameters, by contrast,
are local to a package.
[Definition: An item that is the global
context item for the transformation acts
as the context item when evaluating
the select
expression or sequence constructor of a
global variable whose declaration is
within the top-level package, as described in 5.3.3.1 Maintaining Position: the Focus. The global context item may also be available in a named template
when the stylesheet is invoked as described in 2.3.4 Call-Template Invocation].
[XSLT 3.0 Erratum E7, bug 30179].
Note:
In previous releases of this specification, a single node was typically
supplied to represent the source document for the transformation. This
node was used as the target node for the implicit call on
xsl:apply-templates
used to start the transformation
process (now called the initial match selection), and
the root node of the containing tree was used as the context item for
evaluation of global variables (now called the global context item). This relationship between the
initial match selection and the global context item is likely to be found for compatibility
reasons in a transformation API designed to work with earlier versions of
this specification, but it is no longer a necessary relationship; the two
values can in principle be completely independent of each other.
Stylesheet authors wanting to write code that can be invoked using legacy APIs should not rely on the caller being able to supply different values for the initial match selection and the global context item.
In XPath 4.0, the concept of context item has been generalized and is now referred to as the context valueXP40. For XSLT 4.0, however, the global context item is still constrained to be either a single item, or absent.
The value given to the global context item (and the values given to stylesheet parameters) cannot be nodes in a streamed document. This rule ensures that all global variables can freely navigate within the relevant tree, with no constraints imposed by the streamability rules.
The global context item is potentially
used when initializing global variables and parameters. If the
initialization of any global
variables or parameter depends on the context item, a dynamic error can
occur if the context item is absent. It is implementation-defined whether this error occurs during
priming of the stylesheet or subsequently when the variable is referenced;
and it is implementation-defined whether the error
occurs at all if the variable or parameter is never referenced. The error
can be suppressed by use of xsl:try
and
xsl:catch
within the sequence constructor used to initialize the variable or parameter. It
cannot be suppressed by use of xsl:try
around a
reference to the global variable.
In a library package, the context item, context position, and context size used for evaluation of global variables will be absent, and the evaluation of any expression that references these values will result in a dynamic error. This will also be the case in the top-level package if no global context item is supplied.
Note:
If a context item is available within a global variable declaration, then the context position and context size will always be 1 (one).
Note:
For maximum reusability of code, it is best to avoid use of the context item when initializing global variables and parameters. Instead, all external information should be supplied using named stylesheet parameters, ideally with namespaces, to avoid confusion and conflicts in the information supplied externally to different packages.
When a stylesheet parameter is defined in a library package, it is
possible for a using package to supply a value for the parameter by
overriding the parameter declaration within an
xsl:override
element. If the using package is the
top-level package then the overriding declaration
can refer to the global context item.
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
FO40 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 [XDM 3.0].
Once a stylesheet is primed, the values of global variables
remain stable through all component invocations. In addition, priming a stylesheet
creates an execution scopeFO40
during which the dynamic context and all calls
on deterministicFO40
functions remain stable; for example two calls on the
current-dateTime
FO40 function within an execution scope are
defined to return the same result.
Parameters passed to the transformation by the client application when a stylesheet is primed are matched against stylesheet parameters (see 9.5 Global Variables and Parameters), not against the template parameters of any template executed during the course of the transformation.
[ERR XTDE0050] It is a dynamic error if a stylesheet declares a visible stylesheet parameter that is explicitly or implicitly mandatory, and no value for this parameter is supplied when the stylesheet is primed. A stylesheet parameter is visible if it is not masked by another global variable or parameter with the same name and higher import precedence. If the parameter is a static parameter then the value must be supplied prior to the static analysis phase.
[Definition: A stylesheet may be evaluated by supplying a
value to be processed, together with an initial mode. The
value (which can be any sequence of items) is referred to as the initial
match selection. The processing then corresponds to the effect of the
xsl:apply-templates
instruction.]
The initial match selection will often be a single document node, traditionally called the source document of the transformation; but in general, it can be any sequence. If the initial match selection is an empty sequence, the result of the transformation will be empty, since no template rules are evaluated.
Processing proceeds by finding the template rules that match the items in the initial match selection, and evaluating these template rules with a focus based on the initial match selection. The template rules are evaluated in final output state.
The following information is needed when dynamic evaluation is to start with a template rule:
The initial match selection. An API that chooses to maintain compatibility with previous versions of this specification should allow a method of invocation in which a singleton node is provided, which is then used in two ways: the node itself acts as the initial match selection, and the root node of the containing tree acts as the global context item.
Optionally, an initial mode.
[Definition: The initial mode is the mode used to select template rules for processing items in the initial match selection when apply-templates invocation is used to initiate a transformation.]
In searching for the template rule that best matches the items in the initial match selection, the processor considers only those rules that apply to the initial mode.
If no initial mode is supplied explicitly, then the initial mode is that named in the
default-mode
attribute of the (explicit or implicit) xsl:package
element of the top-level package or in
the absence of such an attribute, the unnamed mode.
[ERR XTDE0044] It is a dynamic error if the invocation of the stylesheet specifies an initial mode when no initial match selection is supplied (either explicitly, or defaulted to the global context item).
A (named or unnamed) mode M is eligible as an initial mode if one of the following conditions applies, where P is the top-level package of the stylesheet:
M is explicitly declared in an xsl:mode
declaration
within P, and has public
or final
visibility (either by virtue
of its visibility
attribute, or by virtue of an xsl:expose
declaration).
M is the unnamed mode.
M is named in the default-mode
attribute of the (explicit or implicit)
xsl:package
element of P.
M is declared in a package used by P, and is given public
or final
visibility in P by means of an xsl:accept
declaration.
The effective value of the declared-modes
attribute of the explicit or implicit
xsl:package
element of P is no
, and M appears as
a mode-name in the mode
attribute of a template rule declared within P.
[ERR XTDE0045] It is a dynamic error if the invocation of the stylesheet specifies an initial mode and the specified mode is not eligible as an initial mode (as defined above).
Parameters, which will be passed to the template rules
used to process items in the input sequence. The parameters consist of two
sets of (QName, value) pairs, one set for tunnel parameters and one for non-tunnel parameters, in which
the QName identifies the name of a parameter and the value provides the
value of the parameter. Either or both sets of parameters may be empty. The
effect is the same as when a template is invoked using
xsl:apply-templates
with an
xsl:with-param
child specifying
tunnel="yes"
or tunnel="no"
as appropriate. If
a parameter is supplied that is not declared or used, the value is simply
ignored. These parameters are not used to set stylesheet parameters.
A supplied value is converted if necessary to the declared type of the template parameter using the coercion rules.
Details of how the result of the initial template is to be returned. For details, see 2.3.6 Post-processing the Raw Result
The raw result of the invocation is the
result of processing the supplied input sequence as if by a call on
xsl:apply-templates
in the specified mode: specifically, each
item in the input sequence is processed by selecting and evaluating the best
matching template rule, and converting the result (if necessary) to the type
declared in the as
attribute of that template using the coercion rules; and the results of processing each item
are then concatenated into a single sequence, respecting the order of items in the
input sequence.
Note:
If the initial mode is declared-streamable, then a streaming processor should allow some or all of the items in the initial match selection to be nodes supplied in streamable form, and any nodes that are supplied in this form must then be processed using streaming.
Since the global context item cannot be a streamed node, in cases where the transformation is to proceed by applying streamable templates to a streamed input document, the global context item must either be absent, or must be something that differs from the initial match selection.
Note:
The design of the API for invoking a transformation should provide some means for users to designate the unnamed mode as the initial mode in cases where it is not the default mode.
It is a dynamic error
[see ERR XTDE0700] if the template rule selected for processing any item in the initial match selection defines a template parameter that specifies required="yes"
and no value is supplied for that
parameter.
Note:
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 20.1 fn:document); or
doc
FO40, unparsed-text
FO40, unparsed-text-lines
FO40, or collection
FO40 (see [Functions and Operators 4.0]); or using the
xsl:source-document
instruction; alternatively, they can
be supplied as stylesheet
parameters (see 9.5 Global Variables and Parameters), or returned as
the result of an extension
function (see 25.1 Extension Functions).
[Definition: A stylesheet may be evaluated by selecting a
named template to be evaluated; this is referred to as the initial named
template.] The effect is analogous to the effect of
executing an xsl:call-template
instruction. The following
information is needed in this case:
Optionally, the name of the initial
named template which is to be executed as the entry point to
the transformation. If no template name is
supplied, the default template name is
xsl:initial-template
. The selected template
must exist within the stylesheet.
Optionally, a context item for evaluation of this named
template, defaulting to the global context item if it
exists. This is constrained by any
xsl:context-item
element appearing within the
selected xsl:template
element. The initial named
template is evaluated with a singleton focus based on
this context item if it exists, or with an absent
focus otherwise.
Note:
The context item for evaluation of the named template must be either a single item or absent; it cannot be an arbitrary value.
Parameters, which will be passed to the selected template
rule. The parameters consist of two sets of (QName, value) pairs, one set
for tunnel parameters and one
for non-tunnel parameters, in which the QName identifies the name of a
parameter and the value provides the value of the parameter. Either or both
sets of parameters may be empty. The effect is the same as when a template
is invoked using xsl:call-template
with an
xsl:with-param
child specifying
tunnel="yes"
or tunnel="no"
as appropriate. If
a parameter is supplied that is not declared or used, the value is simply
ignored. These parameters are not used to set stylesheet parameters.
A supplied value is converted if necessary to the declared type of the template parameter using the coercion rules.
Details of how the result of the initial named template is to be returned. For details, see 2.3.6 Post-processing the Raw Result
The raw result of the invocation is the
result of evaluating the initial named template, after
conversion of the result to the type declared in the as
attribute of
that template using the coercion rules, if such
conversion is necessary.
The initial named template is evaluated in final output state.
[ERR XTDE0040] It is a dynamic error if the invocation of
the stylesheet specifies a template
name that does not match the expanded
QName of a named template defined in the stylesheet, whose
visibility is public
or final
.
Note:
When the top-level package is rooted at an xsl:stylesheet
or
xsl:transform
element, named templates having no explicit
visibility
attribute are automatically exposed as public components.
(This is a consequence of the transformation applied to a package written using
“simplified syntax”, described in 3.5 Packages.) [XSLT 3.0 Erratum E8, bug 30181].
It is a dynamic error
[see ERR XTDE0700] if the initial named template, or any of the template rules invoked to
process items in the initial match selection, defines a
template parameter that
specifies required="yes"
and no value is supplied for that parameter.
[Definition: A stylesheet may be evaluated by calling a named stylesheet function, referred to as the initial function.] The following additional information is needed in this case:
The name and arity of a stylesheet function which is to be executed as the entry point to the transformation.
Note:
In the design of a concrete API, the arity may be inferred from the length of the parameter list.
A list of values to act as parameters to the initial function. The number of values in the list must be the same as the arity of the function.
A supplied value is converted if necessary to the declared type of the function parameter using the coercion rules.
Details of how the result of the initial function is to be returned. For details, see 2.3.6 Post-processing the Raw Result
The raw result of the invocation is the
result of evaluating the initial function, after conversion of
the result to the type declared in the as
attribute of that function
using the coercion rules, if such conversion is
necessary.
Note:
The initial function (like all stylesheet functions) is evaluated with an absent focus.
If the initial function is declared-streamable, a streaming processor should allow the value of the first argument to be supplied in streamable form, and if it is supplied in this form, then it must be processed using streaming.
[ERR XTDE0041] It is a dynamic error if the invocation of the stylesheet specifies a function name and
arity that does not match the expanded
QName and arity of a named stylesheet function defined in the stylesheet, whose visibility is
public
or final
.
When a transformation is invoked by calling an initial function, the entire transformation executes in temporary output state, which means that calls on
xsl:result-document
are not permitted.
[TODO: Generalize the above description to allow for the possibility of keyword-based and optional arguments.]
There are three ways the result of a transformation
may be delivered. (This applies both to the principal result, described here, and
also to secondary results, generated using xsl:result-document
.)
The raw result (a sequence of values) may be returned directly to the calling application.
A result tree may be constructed from the raw result.
By default, a result tree is constructed if the build-tree
attribute of the unnamed output definition
has the effective value yes
. An API for invoking transformations may
allow this setting to be overridden by the calling application. If result tree construction
is requested, it is performed as described in 2.3.6.1 Result Tree Construction.
Alternatively, the raw result may be serialized as described in 2.3.6.2 Serializing the Result. The decision whether or not to serialize the result is determined by the rules of transformation API provided by the processor, and is not influenced by anything in the stylesheet.
Note:
This specification does not constrain the design of application programming interfaces or the choice of defaults. In previous versions of this specification, result tree construction was a mandatory process, while serialization was optional. When invoking stylesheet functions directly, however, result tree construction and serialization may be inappropriate as defaults. These considerations may affect the design of APIs.
In previous versions of XSLT, results were delivered either
in serialized form (as a character or byte stream), or as a tree. In the latter case processors
typically would use either their own tree representation, or a standardized tree
representation such as the W3C Document Object Model (DOM) (see [DOM Level 2]),
adapted to the data structures offered by the programming language in which the API is defined.
To deliver a raw result, processors need to define a representation not only of XDM nodes but
also of sequences, atomic items, maps, arrays, and even functions. As with the return of a simple tree,
this may involve a trade-off between strict fidelity to the XDM data model and usability in the particular
programming language environment. It is not a requirement that an API should return results
in a way that exposes every property of the XDM data model; for example there may be APIs that do not expose
the precise type annotation of a returned node or atomic item, or that fail to expose the base URI
or document URI of a node, or that provide no way of determining whether two nodes in the result
sequence are the same node in the sense of the XPath is
operator.
The way in which maps, arrays, and functions
are returned requires careful design choices. It is recommended that an API should be capable
of returning any XDM value without error, and that there should be minimal loss of information if
the raw results output by one transformation are subsequently used as input to another transformation.
If a result tree is to be constructed from the raw result, then this is done
by applying the rules for the process of sequence normalizationSER30 as defined in
[XSLT and XQuery Serialization]. This process takes as input the serialization parameters defined in the
unnamed output definition of the top-level package; though the only parameter
that is actually used by this process is item-separator
.
[XSLT 3.0 Erratum E14, bug 30208].
The sequence normalization process either returns a document node, or raises a serialization error. The content of the document node is not necessarily well-formed (the document node may have any number of element or text nodes among its children).
Note:
More specifically, the process raises a serialization error if any item in the raw result is an attribute node, a namespace node, or a function (including a map, but not an array: arrays are flattened).
The tree that is constructed is referred to as a final result tree.
If the raw result is an empty sequence, the final result tree will consist of a document node with no children.
The base URI of the document node is set to the base output URI.
Note:
The item-separator
property has no effect if the raw result of the transformation is a sequence
of length zero or one, which in practice will often be the case, especially in a traditional scenario such as
transformation of an XML document to HTML.
If there is no item-separator
, then a single space is inserted between adjacent atomic items;
for example if the raw result is the sequence 1 to 5
, then sequence normalization produces a tree
comprising a document node with a single child, the child being a text node with the string value
1 2 3 4 5
.
If there is an item-separator
, then it is used not only between adjacent atomic items,
but between any pair of items in the raw result. For example if the raw result is a sequence of two
element nodes A
and B
, and the item-separator
is a comma,
then the result of sequence normalization will be a document node with three children: a copy of A
,
a text node whose string value is a single comma, and a copy of B
.
See 2.7 Parsing and Serialization.
The raw result may optionally be serialized as described in 27 Serialization. The serialization is controlled by the serialization parameters defined in the unnamed output definition of the top-level package.
Note:
The first phase of serialization, called sequence normalizationSER30,
takes place for some output methods but not others. For example, if the json
output method
(defined in [XSLT and XQuery Serialization 4.0]) is selected, then the process of constructing
a tree is bypassed.
The effect of serialization is to generate a sequence of octets, representing the serialized result in some character encoding. The processor’s API may define mechanisms enabling this sequence of octets to be written to persistent storage at some location. The default location is the location identified by the base output URI.
In previous versions of this specification it was stated that
when the raw result of the initial template or function is an empty sequence,
a result tree should be produced if and only if the transformation generates no secondary results
(that is, if it does not invoke xsl:result-document
). This provision is most likely
to have a noticeable effect if the transformation produces serialized results, and these results
are written to persistent storage: the effect is then that a transformation producing an empty
principal result will overwrite any existing content at the base output URI location if and only
if the transformation produces no other output. Processor APIs offering backwards compatibility
with earlier versions of XSLT must respect this behavior, but there is no requirement for new
processor APIs to do so.
[Definition: The base output URI is a URI to be used as the base URI when
resolving a relative URI reference 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. Each invocation of the stylesheet may supply
a different base output URI. It is acceptable for the base output URI to be
absent, provided no constructs (such as
xsl:result-document
) are evaluated that depend on the value of
the base output URI.
Note:
It will often be convenient for the base output URI to be the same as the location to which the principal result document is serialized, but this relationship is not a necessary one.
The main executable components of a stylesheet are templates and functions. The body of a template or function is a sequence constructor, which is a sequence of elements and text nodes that can be evaluated to produce a result.
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 25.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
;
instructions that construct maps and arrays: xsl:array
,
xsl:array-member
,
xsl:map
, xsl:map-entry
;
instructions that copy nodes: xsl:copy
,
xsl:copy-of
;
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:switch
, xsl:try
,
xsl:for-each
, xsl:for-each-group
, xsl:fork
,
xsl:iterate
and its subordinate instructions xsl:next-iteration
and
xsl:break
;
instructions that generate output conditionally if elements are or are not
empty: xsl:on-empty
, xsl:on-non-empty
,
xsl:where-populated
;
instructions that invoke templates: xsl:apply-templates
,
xsl:apply-imports
, xsl:call-template
,
xsl:next-match
;
Instructions that declare variables: xsl:variable
;
Instructions to assist debugging: xsl:message
,
xsl:assert
;
other specialized instructions: xsl:number
,
xsl:analyze-string
, xsl:fork
,
xsl:result-document
, xsl:source-document
, xsl:perform-sort
,
xsl:merge
.
The classic method of executing an XSLT transformation is to apply template rules to the root node of an input document (see 2.3.3 Apply-Templates Invocation). The operation of applying templates to a node searches the stylesheet for the best matching template rule for that node. This template rule is then evaluated. A common coding pattern, especially when XSLT is used to convert XML documents into display formats such as HTML, is to have one template rule for each kind of element in the source document, and for that template rule to generate some appropriate markup elements, and to apply templates recursively to its own children. The effect is to perform a recursive traversal of the source tree, in which each node is processed using the best-fit template rule for that node. The final result of the transformation is then the tree produced by this recursive process. This result can then be optionally serialized (see 2.3.6 Post-processing the Raw Result).
This example uses rule-based processing to convert a simple XML input document into an HTML output document.
The input document takes the form:
<PERSONAE PLAY="OTHELLO"> <TITLE>Dramatis Personae</TITLE> <PERSONA>DUKE OF VENICE</PERSONA> <PERSONA>BRABANTIO, a senator.</PERSONA> <PERSONA>Other Senators.</PERSONA> <PERSONA>GRATIANO, brother to Brabantio.</PERSONA> <PERSONA>LODOVICO, kinsman to Brabantio.</PERSONA> <PERSONA>OTHELLO, a noble Moor in the service of the Venetian state.</PERSONA> <PERSONA>CASSIO, his lieutenant.</PERSONA> <PERSONA>IAGO, his ancient.</PERSONA> <PERSONA>RODERIGO, a Venetian gentleman.</PERSONA> <PERSONA>MONTANO, Othello's predecessor in the government of Cyprus.</PERSONA> <PERSONA>Clown, servant to Othello. </PERSONA> <PERSONA>DESDEMONA, daughter to Brabantio and wife to Othello.</PERSONA> <PERSONA>EMILIA, wife to Iago.</PERSONA> <PERSONA>BIANCA, mistress to Cassio.</PERSONA> <PERSONA>Sailor, Messenger, Herald, Officers, Gentlemen, Musicians, and Attendants.</PERSONA> </PERSONAE>
The stylesheet to render this as HTML can be written as a set of template rules:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="3.0" expand-text="yes"> <xsl:strip-space elements="PERSONAE"/> <xsl:template match="PERSONAE"> <html> <head> <title>The Cast of {@PLAY}</title> </head> <body> <xsl:apply-templates/> </body> </html> </xsl:template> <xsl:template match="TITLE"> <h1>{.}</h1> </xsl:template> <xsl:template match="PERSONA[count(tokenize(., ',')) = 2]"> <p><b>{substring-before(., ',')}</b>: {substring-after(., ',')}</p> </xsl:template> <xsl:template match="PERSONA"> <p><b>{.}</b></p> </xsl:template> </xsl:stylesheet>
There are four template rules here:
The first rule matches the outermost element, named PERSONAE
(it could equally
have used match="/"
to match the document node). The effect of this rule is to create
the skeleton of the output HTML page. Technically, the body of the template is a sequence constructor
comprising a single literal result element (the html
element); this
in turn contains a sequence constructor comprising two literal result elements (the head
and body
elements). The head
element is populated with a literal title
element whose content is computed as a mixture of fixed and variable text using a text value template.
The body
element is populated by evaluating an xsl:apply-templates
instruction.
The effect of the xsl:apply-templates
instruction is to process the children of
the PERSONAE
element in the source tree: that is, the TITLE
and
PERSONA
elements. (It would also process any whitespace text node children, but these
have been stripped by virtue of the xsl:strip-space
declaration.) Each of these
child elements is processed by the best matching template rule for that element, which will be one
of the other three rules in the stylesheet.
The template rule for the TITLE
element outputs an h1
element
to the HTML result document, and populates this with the value of .
, the context item. That is,
it copies the text content of the TITLE
element to the output h1
element.
The last two rules match PERSONA
elements. The first rule matches PERSONA
elements whose text content contains exactly one comma; the second rule matches all PERSONA
elements,
but it has lower priority than the first rule (see 6.6 Default Priority for Template Rules), so in practice it
applies only to PERSONA
elements that contain no comma or multiple commas.
For both rules the body of the rule is a sequence constructor containing a single literal result element,
the p
element. These literal result elements contain
further sequence constructors comprising literal result elements and text nodes.
In each of these examples the text nodes are in the form of a text value template:
in general this is a combination of fixed text together with XPath expressions enclosed in curly braces, which
are evaluated to form the content of the containing literal result element.
[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 selected items (often but not necessarily 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.
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 4.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 current-group
) 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 currently being processed (it may be a node, an atomic item,
or a function item). The value of the context
item can be referenced within an XPath expression using the expression .
(dot).
XPath 4.0 generalizes the context item so it can be any value (not necessarily a single item),
and it is now known as the context valueXP40. In certain XPath expressions, the
value of the expression .
can now be an arbitrary value, rather than a single item. However, there
is currently no construct in XSLT 4.0 that takes advantage of this; in the context supplied by XSLT to XPath
(except when using the xsl:evaluate
instruction),
the context value is always either a single item, or absent. The XSLT specification therefore continues to refer
to the context item rather than the context valueXP40.
Full details of the static and dynamic context are provided in 5.3 The Static and Dynamic Context.
An XSLT stylesheet
describes a process that constructs a set of results from a set of inputs. The inputs
are the data provided at stylesheet invocation, as described in 2.3 Initiating a Transformation. The results include the principal result
(an arbitrary sequence), which is the result of the initial component invocation,
together with any secondary results
produced using xsl:result-document
instructions.
The stylesheet does not describe how a source tree is constructed. Some possible ways of constructing source trees are described in [XDM 3.0]. 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 [XDM 3.0], 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 27 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 raise 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.
In XSLT 1.0 and 2.0 it was possible to structure a
stylesheet as a collection of modules, using the xsl:include
and
xsl:import
declarations to express the dependency of one module on
others.
In XSLT 3.0 an additional layer of modularization of stylesheet code was enabled through the introduction of packages. A package is a collection of stylesheet modules with a controlled interface to the packages that use it: for example, it defines which functions and templates defined in the package are visible to callers, which are purely internal, and which are not only public but capable of being overridden by other functions and templates supplied by the using package.
Packages are introduced with several motivations, which broadly divide into two categories:
Software engineering benefits: greater re-use of code, greater robustness through ease of testing, controlled evolution of code in response to new requirements, ability to deliver code that users cannot see or modify.
Efficiency benefits: the ability to avoid compiling libraries repeatedly when they are used in multiple stylesheets, and to avoid holding multiple copies of the same library in memory simultaneously.
Packages are designed to allow separate compilation: that is, a package can be compiled independently of the packages that use it. This specification does not define a process model for compilation, or expand on what it means to compile different packages independently. Nor does it mandate that implementations offer any feature along these lines. It merely defines language features that are designed to make separate compilation of packages possible.
To achieve this, packages (unlike modules):
Must not contain unresolved references to functions, templates, or variables declared in other packages;
Have strict rules governing the ability to override declarations in a library package with declarations in a package that uses the library;
Constrain the visibility of component names and of context declarations such as the declarations of keys and decimal formats;
Can declare a mode (a collection of template rules) as final, which disallows the addition of new overriding template rules in a using package;
Require explicit disambiguation where naming conflicts arise, for example when a package uses two other packages that both export like-named components;
Allow multiple specializations of library components to coexist in the same application.
A package is defined in XSLT
by means of an XML document whose
outermost element is an xsl:package
element. This is referred to as
the package manifest. The xsl:package
element
has optional child elements xsl:use-package
and
xsl:expose
describing properties of the package. The package
manifest may refer to an external top-level stylesheet module using an
xsl:include
or xsl:import
declaration, or it may
contain the body of a stylesheet module inline (the two approaches can also be
mixed).
Although this specification defines packages as constructs written using a defined XSLT syntax, implementations may provide mechanisms that allow packages to be written using other languages (for example, XQuery).
When no packages are explicitly defined, the entire
stylesheet is treated as a single package; the effect is as if the
xsl:stylesheet
or xsl:transform
element of the
principal stylesheet
module were replaced by an xsl:package
element with no
other information in the package manifest.
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 25.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 25.2 Extension Instructions. A stylesheet that uses extension
instructions in a particular namespace 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 25 Extensibility and Fallback.
The XSLT language can also be extended by the use of extension attributes (see 3.2 Extension Attributes), and by means of user-defined data elements (see 3.7.4 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 a SequenceType.
[Definition: A SequenceType constrains the type and number of items in a sequence. The term is used both to denote the concept, and to refer to the syntactic form in which sequence types are expressed in the XPath grammar: specifically SequenceTypeXP40 in [XPath 3.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 package are referred to as the in-scope schema components.]
The set of in-scope schema components may vary between one package and another, but as explained in 3.15 Importing Schema Components, the schema components used in different packages must be consistent with each other.
The conformance rules for XSLT 4.0, defined in
28 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
FO40 function) and other constructs may produce
different results depending on the datatype (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.14 Built-in Types.
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.
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:mode typed="lax"/> <xsl:global-context-item use="required" as="document-node(schema-element(my:invoice))"/>
This example will cause the transformation to fail with an error message, unless
the global context item is valid against the top-level element
declaration my:invoice
, and has been annotated as such.
The setting typed="lax"
further ensures that in any
match pattern for a template rule in this mode, an element name that corresponds
to the name of an element declaration in the schema is taken as referring to
elements validated against that declaration: for example,
match="employee"
will only match a validated employee
element. Selecting this option enables the XSLT processor to do more compile-time
type-checking against the schema, for example it allows the processor to produce
warning or error messages when path expressions contain misspelt element names, or
confuse an element with an attribute.
It is also true that importing a schema does not of itself say
anything about the structure of the result tree. It is possible to request validation
of a result tree against the schema by using the xsl:result-document
instruction, for example:
<xsl:template match="/"> <xsl:result-document validation="strict"> <xhtml:html> <xsl:apply-templates/> </xhtml:html> </xsl:result-document> </xsl:template>
This example will cause the transformation to fail with an error message unless
the document element of the result document is valid against the top-level element
declaration xhtml:html
.
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 [XDM 3.0]. The
implementation may choose one of several strategies for dealing with this
situation:
The processor may raise a 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
[XDM 3.0], 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.14 Error Handling) type errors that are detected early may be raised 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 result tree. This can be done in a number of ways.
It is possible to request explicit validation of a complete document, that is,
a result
tree rooted at a document node. 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 26.4 Validation.
[Definition: The term streaming refers to a manner of processing in which XML documents (such as source and result documents) are not represented by a complete tree of nodes occupying memory proportional to document size, but instead are processed “on the fly” as a sequence of events, similar in concept to the stream of events notified by an XML parser to represent markup in lexical XML.]
[Definition: A streamed document is a source tree that is processed using streaming, that is, without constructing a complete tree of nodes in memory.]
[Definition: A streamed node is a node in a streamed document.]
Many processors implementing earlier versions of this specification adopted an architecture that allowed streaming of the result tree directly to a serializer, without first materializing the complete result tree in memory. Streaming of the source tree, however, has proved to be more difficult without subsetting the language. This has created a situation where documents exceeding the capacity of virtual memory could not be transformed. XSLT 3.0 therefore introduced facilities allowing stylesheets to be written in a way that makes streaming of source documents possible, without excessive reliance on processor-specific optimization techniques.
Streaming achieves two important objectives: it allows large documents to be transformed without requiring correspondingly large amounts of memory; and it allows the processor to start producing output before it has finished receiving its input, thus reducing latency.
This specification does not attempt to legislate precisely which implementation techniques fall under the definition of streaming, and which do not. A number of techniques are available that reduce memory requirements, while still requiring a degree of buffering, or allocation of memory to partial results. A stylesheet that requests streaming of a source document is indicating that the processor should avoid assuming that the entire source document will fit in memory; in return, the stylesheet must be written in a way that makes streaming possible. This specification does not attempt to describe the algorithms that the processor should actually use, or to impose quantitative constraints on the resources that these algorithms should consume.
Nothing in this specification, nor in its predecessors [XSLT 1.0] and [XSLT 2.0], prevents a processor using streaming whenever it sees an opportunity to do so. However, experience has shown that in order to achieve streaming, it is often necessary to write stylesheet code in such a way as to make this possible. Therefore, XSLT provides explicit constructs allowing the stylesheet author to request streaming, and defines explicit static constraints on the structure of the code which are designed to make streaming possible.
A processor that claims conformance with the streaming option offers a guarantee that when streaming is requested for a source document, and when the stylesheet conforms to the rules that make the processing guaranteed-streamable, then an algorithm will be adopted in which memory consumption is either completely independent of document size, or increases only very slowly as document size increases, allowing documents to be processed that are orders-of-magnitude larger than the physical memory available. A processor that does not claim conformance with the streaming option must still process a stylesheet and deliver the correct results, but is not required to use streaming algorithms, and may therefore fail with out-of-memory errors when presented with large source documents.
Apart from the fact that there are constructs to request streaming, and rules that must be followed to guarantee that streaming is possible, the language has been designed so there are as few differences as possible between streaming and non-streaming evaluation. The semantics of the language continue to be expressed in terms of the XDM data model, which is substantively unchanged; but readers must take care to observe that when terms like “node” and “axis” are used, the concepts are completely abstract and may have no direct representation in the run-time execution environment.
Streamed processing of a document can be initiated in one of three ways:
The initial mode can be declared as a
streamable mode. In this case
the initial match selection will generally be a document node (or
sequence of document nodes), supplied by the calling application in
a form that allows streaming (that is, in some form other than a tree in
memory; for example, as a reference to a push or pull XML parser primed to
deliver a stream of events). The type of
these nodes can be constrained by using the attribute
on-no-match="fail"
on the initial mode,
and using this mode only for processing the top-level nodes.
Streamed processing of any document can be initiated using the
xsl:source-document
instruction. This has an attribute
href
whose value is the URI of a document to be processed,
and an attribute streamable
that
indicates whether it is to be processed using
streaming; the actual processing to be applied is defined by the
instructions written as children of the xsl:source-document
instruction.
Streamed merging of a set of input documents can be initiated using the
xsl:merge
instruction.
The rules for streamability, which are defined in detail in 19 Streamability, impose two main constraints:
The only nodes reachable from the node that is currently being processed are its attributes and namespaces, its ancestors and their attributes and namespaces, and its descendants and their attributes and namespaces. The siblings of the node, and the siblings of its ancestors, are not reachable in the tree, and any attempt to use their values is a static error.
When processing a given node in the tree, each descendant node can only be visited once. Essentially this allows two styles of processing: either visit each of the children once, and then process that child with the same restrictions applied; or process all the descendants in a single pass, in which case it is not possible while processing a descendant to make any further downward selection.
The second restriction, that only one visit to the children is
allowed, means that XSLT code that was not designed with streaming in mind will often
need to be rewritten to make it streamable. In many cases it is possible to do this
using a technique sometimes called windowing or burst-mode
streaming (note this is not quite the same meaning as
windowing in XQuery 3.0). Many XML documents consist of a large
number of elements, each of manageable size, representing transactions or business
objects where each such element can be processed independently: in such cases, an
effective design pattern is to write a streaming transformation that takes a snapshot
of each element in turn, processing the snapshot using the full power of the XSLT
language. Each snapshot is a tree built in memory and is therefore fully navigable.
For details see the snapshot
and copy-of
functions.
The new facility of accumulators allows applications complete control over how much information is retained (and by implication, how much memory is required) in the course of a pass over a streamed document. An accumulator computes a value for every node in a streamed document: or more accurately, two values, one for the first visit to a node (before visiting its descendants), and a second value for the second visit to the node (after visiting the descendants). The computation is structured in such a way that the value for a given node can depend only on the value for the previous node in document order together with the data available when positioned at the current node (for example, the attribute values). Based on the well-established fold operation of functional programming languages, accumulators provide the convenience and economy of mutable variables while remaining within the constraints of a purely declarative processing model.
When streaming is initiated, for example using the
xsl:source-document
instruction, it is necessary to declare which
accumulators are applicable to the streamed document.
Streaming applications often fall into one of the following categories:
Aggregation applications, where a single aggregation operation (perhaps
count
FO40, sum
FO40,
exists
FO40, or distinct-values
FO40) is
applied to a set of elements selected from the streamed source document by
means of a path expression.
Record-at-a-time applications, where the source document consists of a long
sequence of elements with similar structure (“records”), and each “record” is
processed using the same logic, independently of any other “records”. This kind
of processing is facilitated using the snapshot
and
copy-of
function mentioned earlier.
Grouping applications, where the output follows the structure of the input, except that an extra layer of hierarchy is added. For example, the input might be a flat series of banking transactions in date/time order, and the output might contain the same transactions grouped by date.
Accumulator applications, which are the same as record-at-a-time applications,
except that the processing of one “record” might depend on data encountered
earlier in the document. A classic example is processing a sequence of banking
transactions in which the input transaction contains a debit or credit amount,
and the output adds a running total (the account balance). The
xsl:iterate
instruction has been introduced to facilitate
this style of processing.
Isomorphic transformations, in which there is an ordered (often largely
one-to-one) relationship between the nodes of the source tree and the nodes of
the result tree: for example, transformations that involve only the renaming or
selective deletion of nodes, or scalar manipulations of the values held in the
leaf nodes. Such transformations are most conveniently expressed using
recursive application of template rules. This is possible with a streamed input
document only if all the template rules adhere to the constraints required for
streamability. To enforce these rules, while still allowing unrestricted
processing of other documents within the same transformation, all streaming
evaluation must be carried out using a specific mode, which is declared to be a streaming mode by means of an
xsl:mode
declaration in the stylesheet.
There are important classes of application in which streaming is possible only if multiple streams can be processed in parallel. This specification therefore provides facilities:
allowing multiple sorted input sequences to be merged into one sorted output
sequence (the xsl:merge
instruction)
allowing multiple output sequences to be generated during a single pass of an
input sequence (the xsl:fork
instruction).
These facilities have been designed in such a way that they can readily be implemented using streaming, that is, without materializing the input or output sequences in memory.
Streaming can be combined with schema-aware processing: that is, the streamed input to a transformation can be subjected to on-the-fly validation, a process which typically accepts an input stream from the XML parser and delivers an output stream (of type-annotated nodes) to the transformation processor. The XSD specification is designed so that validation is, with one or two exceptions, a streamable process. The exceptions include:
There may be a need to allocate memory to hold keys, in order to enforce uniqueness and
referential integrity constraints (xs:unique
, xs:key
, xs:keyref
).
In XSD 1.1, assertions can be defined by means of XPath expressions. These are not constrained to be streamable; in the general case, any subtree of the document that is validated using an assertion may need to be buffered in memory while the assertion is processed.
Applications that need to run in finite memory may therefore need to avoid these XSD features, or to use them with care.
XSD is designed so that the intended type of an element (the “governing type”) can be determined as soon as the start tag of the element is encountered: the process of validation checks whether the content of the element actually conforms to this type, and by the time the end tag is encountered, the process will have established either that the element is valid against the governing type, or that it is invalid.
By default, dynamic errors occurring during streamed processing are fatal: they typically cause the transformation to fail immediately. XSLT 3.0 introduced the ability to catch dynamic errors and recover from them. Schema invalidity, however, is treated as a dynamic error of the instruction that processes the entire input stream, so after a validation failure, no further processing of that input stream is possible.
In consequence, a streamed validator that is running in tandem with a streamed transformation
can present the transformer with element nodes that carry a provisional type annotation representing
the type that the element will have if it turns out to be valid. As soon as a node is encountered that
violates this assumption, the validator should stop the flow of data to the transformer, so that the
transformer never sees invalid data. This allows the stylesheet code to be compiled with the assumption
of type-safety: at run-time, all nodes seen by the transformation will conform to their XSLT-declared types
(for example, a type declared implicitly using match="schema-element(invoice)"
on an
xsl:template
element).
A streamed transformation that only accesses part of the input document (for example, a header at the start of a document) is not required to continue reading once the data it needs has been read. This means that XML well-formedness or validity errors occurring in the unread part of the input stream may go undetected.
The facilities in this specification designed to enable large data sets to be processed in a streaming manner are oriented almost entirely to XML data. This does not mean that there is never a requirement to stream non-XML data, or that the Working Group has ignored this requirement; rather, the Working Group has concluded that for the most part, streaming of non-XML data can be achieved by implementations without the need for specific language features in XSLT.
To make streamed processing of unparsed text files easier, the function unparsed-text-lines
FO40
has been introduced. This is not only more convenient for stylesheet authors than reading the entire input
using the unparsed-text
FO40 function and then tokenizing the result, it is also easier for implementations
to optimize, allowing each line of text to be discarded from memory after it has been processed.
For all functions that access external data, including document
, doc
FO40,
collection
FO40, unparsed-text
FO40, unparsed-text-lines
FO40,
and json-doc
FO40, the requirements on determinism can now
be relaxed using implementation-defined configuration options. This is significant
because it means that when a transformation reads the same external resource more than once, it becomes
legitimate for the contents of the resource to be different on different invocations, and this eliminates
the need for the processor to cache the contents of the resource in memory.
In the XDM data model, every value is a sequence, and (as with most functional programming languages), processing of sequences of items is pervasive throughout the XSLT and XPath languages and their function library. Good performance of a functional programming language often depends on sequence-based operations being pipelined, and being evaluated in a lazy fashion (that is, many operations process items in a sequence one at a time, in order; and many operations can deliver a result without processing the entire sequence). The semantics of XSLT and XPath permit pipelined and lazy evaluation (for example, the error handling semantics are carefully written to ensure this), but they do not require it: the details are left to implementations. Pipelined processing of a sequence is not the same thing as streamed processing of a tree, and where the XSLT specification talks of operations being “guaranteed streamable”, this is always referring to processing of trees, not of sequences.
The facilities for streaming of XML trees include operations such as copy-of
and snapshot
which are able to take a sequence of streamed nodes as input,
and produce a sequence of in-memory (unstreamed) nodes as output. It is also possible to generate
a sequence of strings or other atomic items through the process of atomization.
The actual memory usage of a streamed
XSLT application may depend significantly on whether the processing of the resulting sequence of in-memory
nodes or atomic items is pipelined or not. The specification, however, has nothing to say on this matter:
it is considered an area where implementers can exercise their discretion and ingenuity.
Streaming of JSON input receives little attention in this specification. One can envisage an implementation
of the json-to-xml
function in which the XML delivered by the function consists of
streamed nodes; but the Working Group has not researched the feasibility of such an implementation in any detail.
[Definition: An error that can be 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.]
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.
A processor must provide a mode of operation that takes a (possibly erroneous) stylesheet package as input and enables the user to determine whether or not that package contains any static errors.
Note:
The manner in which static errors are reported, and the behavior when there are multiple static errors, are left as design choices for the implementer. It is recommended that the error codes defined in this specification should be made available in any diagnostics.
A processor may also provide a mode of operation in which static errors in parts of the stylesheet that are not evaluated can go unreported.
Note:
For example, when operating in this mode, a processor might report static errors in a template rule only if the input document contains nodes that match that template rule. Such a mode of operation can provide performance benefits when large and well-tested stylesheets are used to process source documents that might only use a small part of the XML vocabulary that the stylesheet is designed to handle.
[Definition: An error that is not capable of detection until a source document is being transformed is referred to as a dynamic error.]
When a dynamic error occurs, and is not caught
using xsl:catch
, the processor
must raise 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 a principal result or secondary result 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 raise 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 raise any dynamic
errors that would arise if the construct were evaluated.
An implementation may raise a dynamic error before any source document is available, but only if it can determine that the error would be raised for every possible source document and every possible set of parameter values. For example, some circularity errors fall into this category: see 9.11 Circular Definitions.
There are also some dynamic
errors where the specification gives a processor license to raise the
error during the analysis phase even if the construct might never be executed; an
example is the use of an invalid QName as a literal argument to a function such as
key
, or the use of an invalid regular expression in the
regex
attribute of the xsl:analyze-string
instruction.
A dynamic error is also raised during the static analysis phase if the error occurs during evaluation of a static expression.
The XPath specification states (see Section 2.4.1 Kinds of ErrorsXP40) 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 raised as a static error. For XPath expressions used in an XSLT stylesheet, however, any such errors must not be raised as static errors in the stylesheet unless they would occur in every possible evaluation of that stylesheet; instead, they must be raised as dynamic errors, and raised 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 4.0. (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 raised in the same way as a dynamic error. Alternatively, an implementation may raise 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 raised statically.
The following construct contains a type error, because
42
is not allowed as the value of the select
expression of the xsl:number
instruction (it must be a node). An
implementation may optionally raise this as a static error,
even though the offending instruction will never be evaluated, and the type error
would therefore never be raised as a dynamic error.
<xsl:if test="false()"> <xsl:number select="42"/> </xsl:if>
On the other hand, in the following example it is not possible to determine
statically whether the operand of xsl:number
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:number select="$p"/> </xsl:template>
If more than one error arises, an implementation is not required to raise any errors other than the first one that it detects. It is implementation-dependent which of the several errors is raised. This applies both to static errors and to dynamic errors. An implementation is allowed to raise more than one error, but if any errors have been raised, it must not finish as if the transformation were successful.
When a transformation raises 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 principal result or secondary result, it is still possible that errors may occur in serializing that result . For example, it may be impossible to serialize the result 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 27 Serialization, and in particular it must raise 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), 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 raised 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.
Errors defined in related specifications ([XPath 4.0], [Functions and Operators 4.0] [XSLT and XQuery Serialization]) 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.
Implementations must use the codes
defined in these specifications when raising dynamic errors, to ensure that
xsl:catch
behaves in an interoperable way across
implementations. Stylesheet authors should note, however, that there are many
examples of errors where more than one rule in this specification is violated, and
where the processor therefore has discretion in deciding which error code to
associate with the condition: there is therefore no guarantee that different
processors will always use the same error code for the same erroneous
input.
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.
This section describes the overall structure of a stylesheet as a collection of XML documents.
A stylesheet module is typically written as a namespace well-formed XML document: more formally, as described in 3.6 Stylesheet Modules, a stylesheet module takes the form of an XDM tree rooted at an element node.
The names of elements and attributes in source documents and result documents are namespace-qualified names. In addition, as described in 5.1.1 Qualified Names, XSLT uses namespace-qualified names to identify variables, functions, templates, and other components. These names generally use namespace prefixes that are resolved to namespace URIs using a set of prefix-uri namespace bindings.
There are two ways namespace bindings can be established in a stylesheet module:
[Definition: The native namespace bindings for any element in an XSLT stylesheet module are the prefix-uri mappings defined by the namespace nodes of that element, according to the rules in [XDM 3.0].]
For example, a namespace declaration of the form
xmlns:math="http://www.w3.org/2005/xpath-functions/math
establishes a binding
of the prefix math
to the namespace URI http://www.w3.org/2005/xpath-functions/math
,
thereby enabling functions in that namespace to be invoked using an expression such as
math:sin($theta)
[Definition:
The fixed namespace bindings for a stylesheet module are
established using the fixed-namespaces
attribute on the xsl:stylesheet
,
xsl:transform
, or xsl:package
element enclosing the stylesheet
module.]
For example, the attribute fixed-namespaces="math map array"
establishes bindings for the prefixes math
, map
, and array
to the namespace URIs conventionally associated with these prefixes as described
in 5.1.3 Reserved Namespaces.
Prefixes used in element and attribute names in the stylesheet, because these are interpreted
by the XML parser and not only by the XSLT processor, must be bound
using native namespace bindings.
In particular, the XSLT namespace is used in the names of XSLT elements, so it must
be declared in every stylesheet module using a namespace declaration such as
xmlns:xsl="http://www.w3.org/1999/XSL/Transform
. (A different prefix can be used:
some users prefer xslt
, some favor the default namespace.)
But namespace prefixes that are only used within the content of
attribute and text nodes in the stylesheet (for example, select="math:sin($theta)"
)
can be declared in fixed namespace bindings.
[Definition:
The applicable static namespaces for an element in a stylesheet module are the
fixed namespace bindings for the module if the root element
of the module has a fixed-namespaces
attribute, or the native namespace bindings
of the element otherwise.
]
The effect of declaring fixed namespace bindings is described in more detail in 3.7.1 The fixed-namespaces Attribute.
Note:
As a general rule:
Prefixes used in the names of elements and attributes in the stylesheet must be declared using native namespace bindings.
Prefixes used in QNames appearing in the content of attribute nodes
and text nodes in the stylesheet can usually be declared using
fixed namespace bindings. There are a small number
of exceptions, notably the standard attributes [xsl:]exclude-result-prefixes
and [xsl:]extension-element-prefixes
, and the stylesheet-prefix
and result-prefix
attributes of xsl:namespace-alias
.
[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.7 Stylesheet Element and 3.8 Simplified Stylesheet Modules).
XSLT processors must use the XML namespaces mechanism [Namespaces in XML] 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 25.2 Extension Instructions.
Except where the rules for forwards compatible behavior dictate otherwise, it is a static error for any element in the stylesheet to be in the XSLT namespace unless it is an element defined in this specification [see ERR XTSE0010].
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:
By convention, the names of XSLT
elements, attributes and functions are all lower-case;
they use hyphens to separate words, and they use abbreviations only if these already appear
in the syntax of a related language such as XML or HTML. Names of types defined in
XML Schema are regarded as single words and are capitalized exactly as in XML
Schema. This sometimes leads to composite function names such as
current-dateTime
FO40.
[Definition: An element from the XSLT namespace may have any attribute not from the XSLT namespace, provided that the expanded QName (see [XPath 3.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 principal result or any secondary result of the transformation to be different from the results that a conformant XSLT 4.0 processor might produce. They must not cause the processor to fail to raise an error that a conformant processor is required to raise. 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 described in [XSLT and XQuery 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 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
has been registered for XSLT stylesheet
modules.
The definition of the media type is at [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
default-collation
,
default-mode
,
default-validation
,
exclude-result-prefixes
, expand-text
, extension-element-prefixes
,
use-when
, version
, and
xpath-default-namespace
.]
These attributes may also appear on a literal result element, but in this case, to distinguish them from
user-defined attributes, the names of the attributes are in the XSLT namespace. They are thus typically written
as xsl:default-collation
,
xsl:default-mode
,
xsl:default-validation
,
xsl:exclude-result-prefixes
, xsl:expand-text
,
xsl:extension-element-prefixes
, xsl:use-when
,
xsl:version
, or xsl:xpath-default-namespace
.
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:]default-collation
,
[xsl:]expand-text
,
[xsl:]version
, and [xsl:]xpath-default-namespace
, the value
can be overridden by a different value for the same attribute appearing on a
descendant element. The effective value of the attribute for a particular stylesheet
element is determined by the innermost 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.13.3 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
, xsl:transform
, and xsl:package
elements only. This
reflects the fact that these attributes are often used on the outermost element of the stylesheet, in which case they apply to
the entire stylesheet module
or package manifest.
Note that the effect of these attributes does not extend to stylesheet modules referenced by
xsl:include
or xsl:import
declarations, nor to packages referenced using
xsl:use-package
.
For the detailed effect of each attribute, see the following sections:
[xsl:]default-collation
[xsl:]default-mode
[xsl:]default-validation
see 26.4 Validation
[xsl:]exclude-result-prefixes
[xsl:]expand-text
[xsl:]extension-element-prefixes
[xsl:]use-when
[xsl:]version
see 3.9 Backwards Compatible Processing and 3.10 Forwards Compatible Processing
[xsl:]xpath-default-namespace
see 5.1.2 Unprefixed Lexical QNames in Expressions and Patterns
[Definition: An explicit package is
represented by an xsl:package
element, which will generally be
the outermost element of an XML document. When the
xsl:package
element is not used explicitly, the entire
stylesheet comprises a single implicit package.] (This
specification does not preclude the xsl:package
being embedded in
another XML document, but it will never have any other XSLT element as an
ancestor).
<xsl:package
id? = id
name? = uri
package-version? = string〔'1'〕
version = decimal
input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
declared-modes? = boolean〔'yes'〕
default-mode? = eqname | "#unnamed"〔'#unnamed'〕
default-validation? = "preserve" | "strip"〔'strip'〕
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = boolean〔'no'〕
fixed-namespaces? = string
use-when? = expression〔true()〕
xpath-default-namespace? = uri >
<!-- Content: ((xsl:expose | declarations)*) -->
</xsl:package>
[Definition: The content of the
xsl:package
element is referred to as the package
manifest].
The version
attribute indicates the
version of the XSLT language specification to which the package manifest conforms.
The value should normally be
4.0
.
If the value is numerically less than 4.0
, the
content of the xsl:package
element is processed using the rules
for backwards compatible
behavior (see 3.9 Backwards Compatible Processing). If the value is
numerically greater than 4.0
, it is processed using the rules for
forwards compatible behavior (see 3.10 Forwards Compatible Processing).
A package typically has a name, given in its name
attribute, which must be an absolute URI. Unnamed packages are
allowed, but they can only be used as the “top level” of an application; they cannot
be the target of an xsl:use-package
declaration in another
package.
A package may have a version identifier, given in
its package-version
attribute. This is used to distinguish different
versions of a package. The value of the version
attribute, after trimming leading and trailing whitespace, must
conform to the syntax given in 3.5.1 Versions of a Package. If no version
number is specified for a package, version 1
is assumed.
The attributes default-collation
, default-mode
, default-validation
,
exclude-result-prefixes
, expand-text
,
extension-element-prefixes
, use-when
,
version
, and xpath-default-namespace
are standard
attributes that can appear on any XSLT element, and potentially affect all descendant
elements. Their meaning is described in 3.4 Standard Attributes.
The package manifest contains the following elements, arbitrarily ordered:
Zero or more xsl:expose
declarations that define the interface
offered by this package to the outside world. An xsl:expose
declaration may appear only as a child of xsl:package
.
Zero or more additional declarations.
These are the same as the declarations permitted as children of xsl:stylesheet
or xsl:transform
.
Some declarations of particular relevance to packages include:
The xsl:use-package
declaration, which declares the names and
versions of the packages on which this package depends.
The optional xsl:global-context-item
element; if present this
element defines constraints on the existence and type of the global context item.
Zero or more xsl:include
and xsl:import
declarations, which define additional stylesheet modules to be incorporated into this package.
Zero or more ordinary declarations, that is,
elements that are permitted as children of xsl:stylesheet
or
xsl:transform
. One possible coding style is to include in
the package manifest just a single xsl:import
or
xsl:include
declaration as a reference to the effective
top-level stylesheet module; this approach is particularly suitable when
writing code that is required to run under releases of XSLT
earlier than 3.0.
Another approach is to include the substance of the top-level
stylesheet module inline within the package manifest.
The following example shows a package that offers a number of functions for manipulating complex numbers. A complex number is represented as a map with two entries, the keys being 0 for the real part, and 1 for the imaginary part.
<xsl:package name="http://example.org/complex-arithmetic.xsl" package-version="1.0" version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:f="http://example.org/complex-arithmetic.xsl"> <xsl:function name="f:complex-number" as="map(xs:integer, xs:double)" visibility="public"> <xsl:param name="real" as="xs:double"/> <xsl:param name="imaginary" as="xs:double"/> <xsl:sequence select="{ 0: $real, 1: $imaginary }"/> </xsl:function> <xsl:function name="f:real" as="xs:double" visibility="public"> <xsl:param name="complex" as="map(xs:integer, xs:double)"/> <xsl:sequence select="$complex(0)"/> </xsl:function> <xsl:function name="f:imag" as="xs:double" visibility="public"> <xsl:param name="complex" as="map(xs:integer, xs:double)"/> <xsl:sequence select="$complex(1)"/> </xsl:function> <xsl:function name="f:add" as="map(xs:integer, xs:double)" visibility="public"> <xsl:param name="x" as="map(xs:integer, xs:double)"/> <xsl:param name="y" as="map(xs:integer, xs:double)"/> <xsl:sequence select=" f:complex-number( f:real($x) + f:real($y), f:imag($x) + f:imag($y))"/> </xsl:function> <xsl:function name="f:multiply" as="map(xs:integer, xs:double)" visibility="public"> <xsl:param name="x" as="map(xs:integer, xs:double)"/> <xsl:param name="y" as="map(xs:integer, xs:double)"/> <xsl:sequence select=" f:complex-number( f:real($x)*f:real($y) - f:imag($x)*f:imag($y), f:real($x)*f:imag($y) + f:imag($x)*f:real($y))"/> </xsl:function> <!-- etc. --> </xsl:package>
A more complex package might include private or abstract functions as well as
public functions; it might expose components other than functions (for example,
templates or global variables), and it might contain
xsl:use-package
elements to allow it to call on the services
of other packages.
Note:
In this example, the way in which complex numbers are represented is exposed to
users of the package. It would be possible to hide the representation by
declaring the types on public functions simply as item()
; but this
would be at the cost of type safety.
A package that does not itself expose any components may be written
using a simplified syntax: the xsl:package
element is omitted, and
the xsl:stylesheet
or xsl:transform
element is now
the outermost element of the stylesheet module. For compatibility reasons, all the
named templates and modes declared in the package are made public. More formally, the
principal stylesheet module of the top-level
package may be expressed as an xsl:stylesheet
or
xsl:transform
element, which is equivalent to the package represented
by the output of the following transformation, preserving the base URI of the
source:
<xsl:transform version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:t="http://www.w3.org/1999/XSL/TransformAlias"> <xsl:namespace-alias stylesheet-prefix="t" result-prefix="xsl"/> <xsl:template match="xsl:stylesheet|xsl:transform"> <t:package declared-modes="no"> <xsl:copy-of select="@*"/> <t:expose component="mode" names="*" visibility="public"/> <t:expose component="template" names="*" visibility="public"/> <xsl:copy-of select="node()"/> </t:package> </xsl:template> </xsl:transform>
The effect of the input-type-annotations
attribute is defined in 4.3.1 Stripping Type Annotations from a Source Tree.
A more extensive example of a package, illustrating how components in a package can be overridden in a client package, is given in 3.5.7 Worked Example of a Library Package.
If a package has a version number, the version number must conform to the grammar:
PackageVersion ::= NumericPart ( "-" NamePart )? NumericPart ::= IntegerLiteral ( "." IntegerLiteral )* NamePart ::= NCName
Here IntegerLiteralXP40 and NCName
are as defined in
the XPath 4.0 grammar productions of the same name (including rules on
limits). Leading and trailing whitespace is ignored; no other
whitespace is allowed.
Examples of valid version numbers are 2.0.5
or
3.10-alpha
.
[Definition: The integer literals and the optional
NamePart
within the version number are referred to as the
portions of the version number.]
Note:
This means that 1-alpha-2
is a valid version number, with two
portions: 1
and
alpha-2
. The second hyphen is part of the NCName
,
it does not act as a portion separator.
Versions are ordered. When comparing two versions:
Trailing zero portions (that is, any zero-valued integer that is not followed by another integer) are discarded.
Comparison proceeds by comparing portions pairwise from the left.
If both versions have the same number of portions and all portions
compare equal (under the rules of the
XPath eq
operator using the Unicode codepoint
collation), then the versions compare equal.
If the number of portions in the two
versions V1 and V2 is N1 and N2,
with N1<N2, and if all portions in positions 1 to N compare equal, then
V1 is less than V2 if the portion of V2 in position N1 is an integer, and is
greater than V2 if this portion is an
NCName
. For example, 1.2
is less than
1.2.5
, while 2.0
is greater than
2.0-rc1
.
Portions are compared as follows:
If both portions are integers, they are compared using the rules of XPath value comparisons.
If both portions are NCNames, they are compared using the rules of XPath value comparisons, using the Unicode Codepoint Collation.
If one portion is an integer and the other is an
NCName
, the NCName
comes first.
For example, the following shows a possible ordered sequence of version numbers:
0-rc1 < 0-rc2 < 0 < 1 = 1.0 < 1.0.2 < 1.0.3-rc1 < 1.0.3 < 1.0.3.2 < 1.0.10
Note:
The version number format defined here is designed to be general enough to accommodate a variety of conventions in common use, and to allow useful semantics for matching of versions and ranges of versions, without being over-prescriptive. It is influenced by [SemVer], but is not as prescriptive, and it imposes no assumptions about backwards compatibility of packages between successive versions.
Implementations may impose limits on the values used in a version number (or a version range: see below). Such limits are implementation-defined. As a minimum, a processor must accept version numbers including:
A numeric part containing four integers;
Each integer being in the range 0 to 999999;
An NCName
of up to 100 characters
Dependencies between packages may specify a version range (see 3.5.2 Dependencies between Packages). A version range represents a set of accepted versions. The syntax of a version range is shown below. Whitespace is permitted only where indicated, using the terminal symbol S.
PackageVersionRange ::= AnyVersion | VersionRanges AnyVersion ::= "*" VersionRanges ::= VersionRange (S? "," S? VersionRange)* VersionRange ::= PackageVersion | VersionPrefix | VersionFrom | VersionTo | VersionFromTo VersionPrefix ::= PackageVersion ".*" VersionFrom ::= PackageVersion "+" VersionTo ::= "to" S (PackageVersion | VersionPrefix) VersionFromTo ::= PackageVersion S "to" S (PackageVersion | VersionPrefix)
The meanings of the various forms of version range are defined below:
The range AnyVersion
matches any version.
The range VersionRanges
matches a version if any constituent
VersionRange
matches that version.
For example, 9.5.0.8, 9.6.1.2
matches those specific versions only, while 9.5.0.8, 9.6+
matches either version 9.5.0.8 or any version from 9.6 onwards.
A range that is a PackageVersion
matches that version only.
The range VersionPrefix
matches any version whose leading
portions are the same as the portions in the PackageVersion
part of the
VersionPrefix
.
For example, 1.3.*
matches 1.3
,
1.3.5
, 1.3.10.2
, and
1.3-beta
(but not 1
or
1.4
).
Note:
The .*
indicates that additional portions may follow; it does not indicate a substring match
on the final portion. So
1.3.*
does not match 1.35
, and
3.3-beta.*
does not match 3.3-beta12
. Also,
3.3-beta.*
does not match 3.3-beta.5
: this
is because the last dot is not a portion separator, but is part of the
final NCName
. In fact, using .*
after a version
number that includes an NCName
portion is pointless, because
an NCName
portion can never be followed by further
portions.
The range VersionFrom
matches any version that is greater than
or equal to the version supplied.
For example 1.3+
matches
1.3
, 1.3.2
, 1.4
,
and 2.1
(but not 1.3-beta
or 1.2
).
And 1.3-beta+
matches 1.3-beta
,
1.3-gamma
, 1.3.0
, 1.4
,
and 8.0
, but not 1.3-alpha
or
1.2
.
The range VersionTo
matches any version that is less than or
equal to some version that matches the VersionPrefix
.
For example, to 4.0
matches 1.5
,
2.3
, 3.8
, 4.0
,
and 4.0-beta
(but not 4.0.1
), while to
3.3.*
matches 1.5
or 2.0.6
or
3.3.4621
, but not 3.4.0
or
3.4.0-beta
.
The range VersionFromTo
matches any version that is greater
than or equal to the starting PackageVersion
, and less than or
equal to some version that matches the VersionPrefix
.
For example, 1 to 5
matches 1.1
,
2.1
, 3.1
, or 5.0
(but
not 5.1
), while 1 to 5.*
matches all of these,
plus versions such as 5.7.2
(but not 6.0
or
6.0-beta
). Similarly,
1.0-beta to 1.0
matches 1.0-beta
,
1.0-beta.2
, 1.0-gamma
, and 1.0
,
but not 1.0-alpha
or 1.0.1
.
When components in one package reference components in another, the dependency of the first
package on the second must be represented by an xsl:use-package
element. This may appear in the principal stylesheet module
of the first package (which may be a package manifest), or
it may appear in a stylesheet module that is referenced from
the principal stylesheet module via one or more
xsl:include
declarations; however it must not be referenced
via xsl:import
declarations (this is to avoid complications
caused by multiple xsl:use-package
declarations with
different import precedence).
[Definition: If a package Q contains an
xsl:use-package
element that references package
P, then package Q is said to use package
P. In this relationship package Q is referred to as
the using package, package P as the used
package.]
The phrase directly uses is synonymous with uses as defined above, while directly or indirectly uses refers to the transitive closure of this relationship.
<!-- Category: declaration -->
<xsl:use-package
name = uri
package-version? = string〔'*'〕 >
<!-- Content: (xsl:accept | xsl:override)* -->
</xsl:use-package>
A package may be used by more than one other package, but the relationship must not be cyclic. It is possible, but by no means inevitable, that using the same package in more than one place within a stylesheet will cause static errors due to the presence of conflicting components according to the above rules. Where a package is successfully used by more than one other package, its components may be overridden in different ways by different using packages.
The name
and package-version
attributes together
identify the used package. The value of the
package-version
attribute, if present, must conform to the
rules for a PackageVersionRange
given in 3.5.1 Versions of a Package; if omitted the value *
is assumed,
which matches any version. The used package must have a name that is an exact
match for the name in the name
attribute (using codepoint
comparison), and its explicit or implicit package-version
must
match the version range given in the package-version
attribute.
This specification does not define how the implementation locates a package given its name and version. If several matching versions of a package are available, it does not define which of them is chosen. Nor does it define whether this process locates source code or some other representation of the package contents. Such mechanisms are implementation-defined. Use of the package name as a dereferenceable URI is not recommended, because the intent of the packaging feature is to allow a package to be distributed as reusable code and therefore to exist in many different locations.
[ERR XTSE3000] It is a static error if no package matching the package
name and version specified in an xsl:use-package
declaration can be located.
[ERR XTSE3005] It is a static error if a package is dependent on
itself, where package A is defined as being dependent on package
B if A contains an xsl:use-package
declaration that references B, or if A contains an
xsl:use-package
declaration that references a package
C that is itself dependent on B.
[ERR XTSE3008] It is a static error if an xsl:use-package
declaration appears in a stylesheet module that is not in the
same stylesheet level as the principal stylesheet module
of the package.
Note:
Depending on the implementation architecture, there may be a need to locate used packages both during static analysis (for example, to get information about the names and type signatures of the components exposed by the used package), and also at evaluation time (to link to the implementation of these components so they can be invoked). A failure to locate a package may cause an error at either stage.
The xsl:accept
and xsl:override
elements are
used to modify the visibility or behavior of components acquired from the used
package; they are described in 3.5.3.2 Accepting Components below.
Note:
It is not intrinsically an error to have two
xsl:use-package
declarations that identify the same package
(or different versions of the same package). This has the same effect as
having two declarations that identify packages with different names but
identical content. In most cases it will result in an error ([see ERR XTSE3050])
due to the presence of multiple components with the same name; but
no error would occur, for example, if the used package is empty, or if the
two xsl:use-package
declarations use xsl:accept
to accept non-overlapping subsets of the components in the used package.
This section discusses the use of named components in packages.
The components which can be declared in one package and referenced in another are: functions, named templates, attribute sets, modes, global variables and parameters, and named record types
In addition, keys and accumulators are classified as named components because they can contain references to components in another package, even though they cannot themselves be referenced from outside the package.
Named and unnamed modes come within the scope of this section, but there are differences noted in 3.5.4 Overriding Template Rules from a Used Package.
Not all declarations result in components:
Named declarations that can neither be referenced from outside their
containing package, nor can contain references to components in other
packages (examples are xsl:output
,
xsl:character-map
, and
xsl:decimal-format
) are not considered to be components
and are therefore outside the scope of this section.
Some declarations, such as xsl:decimal-format
and
xsl:strip-space
, declare aspects of the processing
context which are not considered to be components as defined here.
Template rules
(xsl:template
with a match
attribute) are
also not considered to be components for the purposes of this section, which
is concerned only with components that are bound by name. However, when an
xsl:template
has both a match
attribute and
a name
attribute, then it establishes both a template rule and
a named template, and in its role
as a named template it comes within the scope of this discussion.
A named declaration, for example a named template, a function, or a global variable, may be overridden within the same package by another like-named declaration having higher import precedence. When a declaration is overridden in this way it cannot be referenced by name either from within its containing package or from outside that package.
In the case of xsl:attribute-set
and xsl:key
declarations, several declarations combine to
form a single component.
The section is largely concerned with details of the rules that affect references from one component to another by name, whether the components are in the same package or in different packages. The rules are designed to meet a number of requirements:
A component defined in one package can be overridden by a component in another package, provided the signatures are type-compatible. This does not apply to named record types, which cannot be overridden.
The author of a package can declare whether the components in the package are public or private (that is, whether or not they can be used from outside the package) and whether they are final, overridable, or abstract (that is whether they can or must be overridden by the using package).
Within an application, two packages can make use of a common library and override its components in different ways.
Visibility of components can be defined either as part of the declaration of the component, or in the package manifest.
An application that wishes to make use of a library package can be selective about which components from the library it acquires, perhaps to avoid name clashes between components acquired from different libraries.
[Definition: The term component is used to refer to any of the following: a stylesheet function, a named template, a mode, an accumulator, an attribute set, a key, a global variable, a , or a mode.]
[Definition: The symbolic identifier of a component is a composite name used to identify the component uniquely within a package. The symbolic identifier comprises the kind of component (stylesheet function, named template, accumulator, attribute set, global variable, key, or mode), the expanded QName of the component (namespace URI plus local name), and in the case of stylesheet functions, the upper bound of the arity range.]
Note:
In the case of the unnamed mode, the expanded QName of the component may be considered to be some system-allocated name different from any user-defined mode name.
[Definition: Two components are said to be homonymous if they have the same symbolic identifier.]
Every component has a declaration in some stylesheet module and therefore within some package. In the case of attribute sets and keys, there may be several declarations. The declaration is an element in an XDM tree representing the stylesheet module. Declarations therefore have identity, based on XDM node identity.
[Definition: The declaring
package of a component is the
package that contains the declaration (or,
in the case of xsl:attribute-set
and
xsl:key
, multiple declarations) of the
component.]
When a component declared in one package is made available in another, the using package will contain a separate component that can be regarded as a modified copy of the original. The new component shares the same symbolic identifier as the original, and it has the same declaration, but it has other properties such as its visibility that may differ from the original.
[Definition: A
component declaration results in multiple components, one in the package in
which the declaration appears, and potentially one in each package that uses
the declaring package, directly or indirectly, subject to the visibility of the
component. Each of these multiple components has the same declaring package, but each has a different containing
package. For the original component, the declaring package and the
containing package are the same; for a copy of a component made as a result of
an xsl:use-package
declaration, the declaring package will be
the original package, and the containing package will be the package in which
the xsl:use-package
declaration appears.]
Note:
Within this specification, we generally use the notation CP for a component named C whose declaring package and containing package are both P; and the notation CPQ for a component whose containing package is P and whose declaring package is Q (that is, a component in P that is derived from a component CQ in the used package Q).
The properties of a component are as follows:
The original declaration of the component.
The package to which the component belongs (called its containing package, not to be confused with the declaring package).
The symbolic identifier of the component.
The visibility of the component,
which determines the way in which the component is seen by other components
within the same package and within using packages. This is one of
public
, private
, abstract
,
final
, or hidden
. The visibility of components
is discussed further in 3.5.3.1 Visibility of Components.
A set of bindings for the symbolic references in the component. The way in which these bindings are established is discussed further in 3.5.3.5 Binding References to Components.
Note:
When a function F defined in a package P is acquired by two using packages Q and R, we may think of P, Q, and R as all providing access to the “same” function. The detailed semantics, however, demand an understanding that there is one function declaration, but three components. The three components representing the function F within packages P, Q, and R have some properties in common (the same symbolic identifier, the same declaration), but other properties (the visibility and the bindings of symbolic references) that may vary from one of these components to another.
[Definition: The declaration of a component includes
constructs that can be interpreted as references to other components by means of their symbolic identifiers. These
constructs are generically referred to as symbolic references.
Examples of constructs that give rise to symbolic references are the
name
attribute of xsl:call-template
; the
[xsl:]use-attribute-sets
attribute of
xsl:copy
, xsl:element
, and literal result elements; the
explicit or implicit
mode
attribute of xsl:apply-templates
; XPath
variable references referring to global variables; XPath static function calls (including partial function
applications) referring to stylesheet functions; and
named function references (example: my:f#1
) referring to
stylesheet functions.
]
Symbolic references exist as properties of the declaration of a component.
The symbolic identifier being
referred to can be determined straightforwardly from the syntactic form and
context of the reference: for example, the instruction <xsl:value-of
select="f:price($o)" xmlns:f="http://f.com/"/>
contains a symbolic
reference to a function with expanded name {http://f.com/}price
and
with arity=1. However, because there may be several (homonymous) function
components with this symbolic identifier, translating this symbolic reference into
a reference to a specific component (a process called “binding”) is less
straightforward, and is described in the text that follows.
The process of assembling a stylesheet from its constituent packages is primarily a process of binding these symbolic references to actual components. Within any component whose declaration is D, there is a set of bindings; each binding is an association between a symbolic reference in D and a component whose symbolic identifier matches the outward reference. Outward references for which a component C contains a binding are said to be bound in C; those for which C contains no binding are said to be unbound.
For example, suppose that in some package Q, function A
calls B, which in turn calls C, and that B is
private
. Now suppose that in some package P which uses
Q, C is overridden. The effect of the binding process is
that P will contain three components corresponding to A,
B, and C, which we might call AP,
BP, and CP. The declarations of AP and BP are in package
Q, but the declaration of CP is in P. The
internal visibility of BP will be hidden
(meaning that it
cannot be referenced from within P), and BP will contain a
binding for the component CP that corresponds to the outward reference
from B to C. The effect is that when A calls
B and B calls C, it is the overriding version
of C that is executed.
In another package R that uses Q without overriding C, there will be three different components AR, BR, and CR. This time the declaration of all three components is in the original package Q. Component BR will contain a binding to CR, so in this package, the original version of C is executed. The fact that one package P overrides C thus has no effect on R, which does not override it.
The binding process outlined above is described in more detail in 3.5.3.5 Binding References to Components.
Template rules are not components in their own right; unlike named templates, they are never referenced by name. Component references within a template rule (for example, references to functions, global variables, or named templates) are treated as occurring within the component that represents the containing mode. This includes component references within the match patterns of template rules. If a template rule lists several modes, it is treated as if there were multiple template rules one in each mode.
An xsl:apply-templates
instruction
with no mode
attribute is treated as a reference to the default mode
defined for that instruction (see 3.7.3 The default-mode Attribute), which in turn defaults to the unnamed mode. An implicit
reference to the unnamed made is treated in the same way as any other symbolic reference. Note that there is an unnamed mode in every
package, and the unnamed mode always has private visibility.
Where an xsl:template
element has both
a name
and a match
attribute, it is treated as if there
were two separate xsl:template
elements, one with a
name
attribute and one with a match
attribute.
Keys
and accumulators behave rather differently from other
components. Their visibility is always private, which means they can only be used
within their declaring package. In addition, the component binding is generally
made dynamically rather than statically, by
virtue of a string passed as an argument to the function
key
, accumulator-before
, or
accumulator-after
. (In the case of accumulators, there
can also be static references: see the use-accumulators
attribute
of xsl:source-document
,
xsl:merge-source
, and xsl:mode
.)
However, outward references from key
definitions and accumulators to other components (such as global
variables and functions) behave in the same way as component references contained
in any other private component, in that they may be re-bound to an overriding
declaration of the target component.
[Definition: The visibility of a
component is one of:
private
, public
, abstract
,
final
, or hidden
.]
The meanings of these visibility values is as follows:
The component can be referenced from other components in this package or in any using package; it can be overridden by a different component in any using package.
The component can be referenced from other components in this package; it cannot be referenced or overridden within a using package.
The component can be referenced from other components in this package or in any using package; in a using package it can either remain abstract or be overridden by a different component.
The component can be referenced from other components in this package or in any using package; it cannot be overridden by a different component in any using package.
The component cannot be referenced from other components in this package; it cannot be referenced or overridden within a using package.
Note:
The visibility of a component in a package P primarily affects
how the component can be used in other packages, specifically, packages that
use P. There is one exception: if the visibility is
hidden
, it also affects how the component can be used within
P.
When a component is declared within a particular
package, its visibility, which affects
how it can be used in other (using) packages, depends on two factors: the value
of the visibility
declaration on the declaration itself (if
present), and the rules given in the xsl:expose
declarations
of the package manifest.
The xsl:function
, xsl:template
,
xsl:attribute-set
, xsl:variable
,
and
xsl:mode
declarations each have an optional
visibility
attribute. The value is one of private
,
public
, abstract
, or final
(never
hidden
). In the case of
an xsl:param
element there is no explicit
visibility
attribute; rather the declaration has the
implicit attribute visibility="public"
.
Any xsl:expose
declarations that
appear as children of xsl:package
define the visibility of
components whose declaration has no explicit visibility
attribute,
and can also be used to reduce the visibility of components where this
attribute is present.
<xsl:expose
component = "template" | "function" | "attribute-set" | "variable" | "mode" | "record-type" | "*"
names = tokens
visibility = "public" | "private" | "final" | "abstract" />
The xsl:expose
element allows the visibility of selected components within a package to be defined.
The components in question are identified using their symbolic identifiers. The
component
attribute defines the kind of component that is
selected.
The value *
means “all component kinds”;
in this case the value of the names
attribute must be a WildcardXP40.
An xsl:expose
declaration has no effect on the
unnamed mode, which is always private to a package.
The names
attribute selects a subset of these components by name
(and in the case of functions, arity); its value is a whitespace-separated
sequence of tokens each of which is either a NameTestXP40 or a NamedFunctionRefXP40. (Examples are
*
, p:*
, *:local
,
p:local
, and p:local#2
.)
The value may be a NamedFunctionRef
only in the case of stylesheet
functions, and distinguishes functions with the same name and different
arity. A NameTestXP40
on its own (that is, with no arity) cannot be used to identify a function. [XSLT 3.0 Erratum E36, bug 30323].
The visibility of a named template, function, variable, attribute set, mode, or named record type declared within a package is the first of the following that applies, subject to consistency constraints which are defined below:
The visibility of a variable declared using
an xsl:param
element is
always public
. No xsl:expose
element
ever matches an xsl:param
component.
Note:
Attempting to match an xsl:param
with
an explicit EQName
will therefore always give an error, while
using a wildcard has no effect.
If the package manifest contains an xsl:expose
element
that matches this component by virtue of an explicit EQName
or NamedFunctionRef
(that is, not by virtue of a wildcard
match), then the value of the visibility
attribute of the
last such xsl:expose
element in document order (call
this the explicit exposed visibility).
If the declaration of the component has a visibility
attribute, then the value of this attribute (call this the declared
visibility).
If the package manifest contains an xsl:expose
element
that matches this component by virtue of a wildcard match that specifies
either the namespace part of the component name or the local part of the
name (for example, prefix:*
or *:local
or
Q{uri}*
), then the value of the visibility
attribute of the last such xsl:expose
element in
document order.
If the package manifest contains an xsl:expose
element
that matches this component by virtue of a wildcard match that matches
all names (that is, *
), then the value of the
visibility
attribute of the last such
xsl:expose
element in document order.
Otherwise, private
.
Note:
In the above rules, no distinction is made between declarations that specify
a specific component kind, and those that specify component="*"
. If both match,
the value of the component
attribute plays no role in deciding which
declaration wins.
If both a declared visibility and an explicit
exposed visibility exist for the same component, then as mentioned above, they
must be consistent. This is determined by reference to the following table,
where the entry N/P means “not permitted”. (In cases where the combination is
permitted, the actual visibility is always the same as the visibility
determined by xsl:expose
.)
Explicit exposed visibility | Declared visibility | |||
---|---|---|---|---|
public | private | final | abstract | |
public | public | N/P | N/P | N/P |
private | private | private | private | N/P |
final | final | N/P | final | N/P |
abstract | N/P | N/P | N/P | abstract |
[ERR XTSE3010] It is a static error if the
explicit exposed visibility of a component is inconsistent with its
declared visibility, as defined in the above table. (This error occurs
only when the component declaration has an explicit
visibility
attribute, and the component is also listed
explicitly by name in an xsl:expose
declaration.)
[ERR XTSE3015] It is a static error if the
explicit exposed visibility of a
component is anything other than private
or final
.
[ERR XTSE3020] It is a static error if a token
in the names
attribute of xsl:expose
, other
than a wildcard, matches no component in the containing package.
[ERR XTSE3022] It is a static error if the
component
attribute of xsl:expose
specifies *
(meaning all component kinds) and the names
attribute is not a wildcard.
Note:
There is no ambiguity, and no error, if several tokens within the same
xsl:expose
element match the same component.
If the visibility of a component as established by the above rules
is abstract
, then the component must have a declared visibility of abstract
.
Note:
In other words, the xsl:expose
declaration cannot be used to make a component
abstract unless it was declared as abstract to start with.
[ERR XTSE3025] It is a static error if the
effect of an xsl:expose
declaration would be to make a component
abstract
, unless the component is already abstract
in the absence of the xsl:expose
declaration.
For a component accepted into a package P
from another package Q, the visibility of the component in P (which primarily
affects how it can be used in a package R that uses P)
depends on the visibility declared in the relevant xsl:accept
or xsl:override
element in P (see 3.5.3.2 Accepting Components); this in turn has a default that depends on
the visibility of the corresponding component in Q. In this case the
visibility is unaffected by any xsl:expose
declaration in
P.
When a package P uses a package Q, by virtue of an
xsl:use-package
element in the package manifest of P, then
P will contain a component
corresponding to every component in Q. The visibility of the component within
P depends on the visibility of the component in Q, optionally modified
by two elements that may appear as children of the
xsl:use-package
element, namely xsl:accept
and xsl:override
.
For every component CQ in package Q that is not matched
by any xsl:override
or xsl:accept
element in
the package manifest of P, there will be a corresponding component
CP in package P that has the same symbolic identifier and declaration as CQ.
If CQ is an xsl:param
component, then the visibility of CP is
public
.
In other cases, the visibility of CP depends on the visibility of CQ, as defined by the following table:
Visibility in used package CQ | Visibility in using package CP |
---|---|
public | private |
final | private |
private | hidden |
hidden | hidden |
abstract | hidden |
Note:
The effect of these rules is as follows:
Components that are public or final in the used package Q become private in the using package P. This means that they can be referenced within P but are not (by default) visible within a package R that uses P.
Components that are private or hidden in the used package Q become hidden in the using package P. This means that they cannot be referenced within P; but if they contain references to components that are overridden in P, the hidden component’s references are bound to the overriding components in P.
Components that are abstract in the used package Q become hidden in the using package P. The hidden component in this case raises a dynamic error if it is invoked. Such an invocation cannot originate within P, because the component is not visible within P; but it can occur if a public component in Q is invoked, which in turn invokes the abstract component.
<xsl:accept
component = "template" | "function" | "attribute-set" | "variable" | "mode" | "record-type" | "*"
names = tokens
visibility = "public" | "private" | "final" | "abstract" | "hidden" />
The xsl:accept
element has very similar syntax and semantics
to xsl:expose
. Whereas xsl:expose
allows a
package to restrict the visibility of its own components to other (using)
packages, xsl:accept
allows a package to restrict the
visibility of components exposed by a package that it uses. This may be
necessary if, for example, it uses two different packages whose component names
conflict. It may also simply be good practice if the package author knows that
only a small subset of the functionality of a used package is required.
The rules for determining whether an xsl:accept
element
matches a particular component, and for which element to use if there are
several matches, are the same as the rules for the xsl:expose
element.
No xsl:accept
element
ever matches a variable declared using xsl:param
.
Note:
Attempting to match an xsl:param
with
an explicit EQName
will therefore always give an error, while
using a wildcard has no effect.
[ERR XTSE3030] It is a static error if a token
in the names
attribute of xsl:accept
, other
than a wildcard, matches no component in the used package.
[ERR XTSE3032] It is a static error if the
component
attribute of xsl:accept
specifies *
(meaning all component kinds) and the names
attribute is not a wildcard.
[ERR XTSE3032] It is a static error if an
xsl:accept
declaration attempts to set the
visibility
of a
to anything other than final
, private
, or hidden
.
In the absence of a matching xsl:override
element (see
3.5.3.3 Overriding Components from a Used Package), the visibility of a component that matches an
xsl:accept
element depends both on the
visibility
attribute of the best-matching
xsl:accept
element and on the visibility of the corresponding component in the used package,
according to the following table. In this table the entry “N/P” means “not
permitted”.
Visibility in xsl:accept element |
Visibility in used package | |||
---|---|---|---|---|
public | private | final | abstract | |
public | public | N/P | N/P | N/P |
private | private | N/P | private | N/P |
final | final | N/P | final | N/P |
abstract | N/P | N/P | N/P | abstract |
hidden | hidden | N/P | hidden | hidden |
[ERR XTSE3040] It is a static error if the
visibility assigned to a component by an xsl:accept
element is incompatible with the visibility of the corresponding
component in the used package, as defined by the above table, unless the
token that matches the component name is a wildcard, in which case the
xsl:accept
element is treated as not matching that
component.
[ERR XTSE3050] It is a static error if the
xsl:use-package
elements in a package manifest cause two or more
homonymous components to be
accepted with a visibility other than hidden
.
Conflicts between the components accepted from used packages and those declared within the package itself are handled as follows:
If the conflict is between two components both declared within the package itself, then it is resolved by the rules relating to import precedence defined for each kind of component.
If the conflict is between two components both accepted from used packages, or between a component declared within the package and an accepted component, then a static error occurs.
If a component is explicitly accepted from a used package (by name, rather
than by a matching wildcard), and if the same component is the subject
of an xsl:override
declaration, then a static error
occurs (see below). There is no conflict, however, if a component declared
within xsl:override
also matches a wildcard in an xsl:accept
element.
[ERR XTSE3051] It is a static error if
a token in the names
attribute of xsl:accept
,
other than a wildcard, matches the symbolic name of a component declared
within an xsl:override
child of the same
xsl:use-package
element.
Where the used package Q contains a component whose
visibility is abstract
, the using package P has three options:
P can accept the component with visibility="abstract"
.
In this case P can contain references to the component, but invocation via
these references will fail unless a non-abstract overriding component has
been supplied in some package R that (directly or indirectly) uses P.
P can accept the component with visibility="hidden"
.
In this case P cannot contain references to the component, and invocation via
references in Q will always fail with a dynamic error. This is the default
if P does not explicitly accept or override the component.
P can provide a concrete implementation of the component
within an xsl:override
element.
Any invocation of the absent component (typically from within its declaring package) causes a dynamic error, as if the component were overridden by a component that unconditionally raises a dynamic error.
[ERR XTDE3052] It is a dynamic error if an invocation of an abstract component is evaluated.
Note:
This can occur when a public component in the used package invokes
an abstract component in the used package, and the using package provides
no concrete implementation for the component in an xsl:override
element.
Note:
To override a component accepted from a used package, the overriding
declaration must appear as a child of the xsl:override
element.
Note:
There is no rule that prevents a function (say) being declared in the using
package with the same name as a private
function in the used
package. This does not create a conflict, since all references in the used
package are bound to one function and all those in the using package are
bound to another.
[Definition: A component in a using package may
override a component in a used package, provided that the
visibility of the component in the
used package is either abstract
or public
. The
overriding declaration is written as a child of the
xsl:override
element, which in turn appears as a child
of xsl:use-package
.]
<xsl:override>
<!-- Content: (xsl:template | xsl:function | xsl:variable | xsl:param | xsl:attribute-set)* -->
</xsl:override>
Note:
This mechanism is distinct from the mechanism for overriding declarations within the same package by relying on import precedence. It imposes stricter rules: the overriding component is required to be type-compatible with the component that it overrides.
If the used package Q contains a component
CQ and the xsl:use-package
element contains an
xsl:override
element which contains a declaration
D whose symbolic
identifier matches the symbolic identifier of CQ, then
the using package P will contain a component CP whose
declaration is D, whose symbolic identifier is that of D, and whose visibility is equal to the value of the visibility
attribute of D, or private
if this is absent,
except in the case
of xsl:param
, which is implicitly
public
.
The using package P will also contain a component CPQ
whose body is the same as the body of CQ and whose visibility is hidden
. This
component is used as the target of a binding for the symbolic reference
xsl:original
described below.
Other than its appearance as a child of xsl:override
, the
overriding declaration is a normal xsl:function
,
xsl:template
,
xsl:variable
, xsl:param
, or
xsl:attribute-set
element. In the case of
xsl:variable
and xsl:param
, the variable
that is declared is a global
variable.
The rules in the remainder of this section apply to
components having a name
attribute (named
components). The only element with no name
attribute that
can appear as a child of xsl:override
is an
xsl:template
declaration having a match
attribute (that is, a template rule). The rules for
overriding of template rules appear in 3.5.4 Overriding Template Rules from a Used Package. If
an xsl:template
element has both a name
attribute
and a match
attribute, then it defines both a named component and
a template rule, and both sections apply.
[ERR XTSE3055] It is a static error if a
component declaration appearing as a child of
xsl:override
is homonymous with any other declaration in the using package,
regardless of import
precedence, including any other overriding declaration in
the package manifest of the using package.
Note:
When an attribute set is overridden, the
overriding attribute set must be defined using a single
xsl:attribute-set
element. Attribute sets defined in
different packages are never merged by virtue of having the same name,
though they may be merged explicitly by using the
use-attribute-sets
attribute.
[ERR XTSE3058] It is a static error if a
component declaration appearing as a child of
xsl:override
does not match (is not homonymous with) some component in the
used package.
[ERR XTSE3060] It is a static error if the
component referenced by an xsl:override
declaration has
visibility other than
public
or abstract
A package is executable if and only if it contains no component whose visibility is abstract
. A package that is not
executable is not a stylesheet, and
therefore cannot be nominated as the stylesheet to be used when initiating a
transformation.
Note:
In other words, if a component is declared as abstract, then some package that uses the declaring package of that component directly or indirectly must override that component with one that is not abstract. It is not necessary for the override to happen in the immediately using package.
[ERR XTSE3070] It is a static error if the signature of an overriding component is not compatible with the signature of the component that it is overriding.
[Definition: The signatures of two components are compatible if they present the same interface to the user of the component. The additional rules depend on the kind of component.]
Compatibility is only relevant when comparing two components that have the same symbolic identifier. The compatibility rules for each kind of component are as follows:
Two attribute sets with the same name are compatible if and only if they satisfy the following rule:
If the overridden attribute set specifies
streamable="yes"
then the overriding attribute set
also specifies streamable="yes"
.
Two functions with the same symbolic identifier are compatible if and only if they satisfy all the following rules:
They have the same arity range (which implies they have the same number of required and optional parameters)
The declared types of the parameters
(defaulting to item()*
) are pairwise identical.
The declared return types
(defaulting to item()*
) are identical.
The effective value of the
new-each-time
attribute on the overriding function is the same as its value on the overridden function.
If the overridden function has a streamability
attribute with a value
other than unspecified
, then the overriding function has a
streamability
attribute with the same value. [XSLT 3.0 Erratum E32, bug 30297]
It is recommended that the parameter names on the overriding function should be the same as on the overridden function. (However, in order to maintain backwards compatibility with XSLT 3.0, this is not required.) If the parameter names are not the same, then the parameter names on the overriding function are effectively replaced with the names declared on the overridden function, so that any static function calls using keyword arguments to set the values of arguments must use the names defined on the overridden function.
Two named templates with the same name are compatible if and only if they satisfy all the following rules:
Their return types are identical.
For every non-tunnel parameter on the overridden template, there is a
non-tunnel parameter on the overriding template that has the same name, an
identical required
type, and the same effective value for the required
attributes.
For every tunnel parameter P on the overridden template, if there is a parameter Q on the overriding template that has the same name as P then Q is also a tunnel parameter, and P and Q have identical required types.
Any parameter on the overriding template for which there is no
corresponding parameter on the overridden template specifies
required="no"
.
The two templates have equivalent
xsl:context-item
children, where equivalence
means that the use
attributes are the same and the
required types are identical; an absent
xsl:context-item
is equivalent to one that
specifies use="optional"
and
as="item()"
.
Two variables (including parameters) with the same name are compatible if and only if they satisfy all the following rules:
Their declared types are identical. For this purpose, the declared type is the first of the following that applies:
If there is an as
attribute, then the type defined by that attribute.
If there is a select
attribute, then item()*
.
If there is a non-empty sequence constructor, then document-node()
.
Otherwise, xs:string
. [XSLT 3.0 Erratum E35, bug 30313].
Note:
A variable may override a parameter or vice-versa, and the initial value may differ.
Because static variables and parameters are
constrained to have visibility private
,
they cannot be overridden in another package. The compatibility rules
therefore do not arise. The reason that such variables cannot be
overridden is that they are typically used during stylesheet
compilation (for example, in [xsl:]use-when
expressions
and shadow attributes) and it is a design goal that packages should be
capable of independent compilation.
[Definition: Types S
and T are considered identical for the purpose of
these rules if and only if subtype(S, T)
and subtype(T,
S)
both hold, where the subtype relation is defined in Section 3.3.1 Subtypes of Sequence TypesXP40.]
Note:
One consequence of this rule is that two plain union types are considered identical if they have the same set of member types, even if the union types have different names or the ordering of the member types is different.
Consider a function that accepts an argument
whose declared type is a union type with member types xs:double
and xs:decimal
, in that order (we might write this as (xs:double | xs:decimal)
).
Using the same notation, this can be overridden by a function that declares the argument
type as (xs:decimal | xs:double)
. This does not affect type checking:
a function call that passes the type checking rules with one signature will also pass the
type checking rules with the other. It does however affect the way that the function
conversion rules work: a call that passes the xs:untypedAtomic
item
"93.7"
(or an untyped node with this as its string value) will be converted to
an xs:decimal
in one case and an xs:double
in the other.
While this rule may appear formal, it is not as straightforward as might be supposed, because the subtype relation in XPath has a dependency on the “Type derivation OK (Simple)” relation in XML Schema, which itself appeals to a judgement as to whether the two type definitions being compared “are the same type definition”. Both XSD 1.0 and XSD 1.1 add the note “The wording of [this rule] appeals to a notion of component identity which is only incompletely defined by this version of this specification.” However, they go on to say that component identity is well defined if the components are named simple type definitions, which will always apply in this case. For named atomic types, the final result of these rules is that two atomic types are identical if and only if they have the same name.
Except where recursive types are involved, a named record type
(declared in an xsl:record-type
declaration) is considered
identical to its expansion. With recursive types, the same type names must
be used. By implication, the named record type must itself be declared or exposed
with visibility="final"
.
Modes are not overridable, so the xsl:mode
declaration cannot
appear as a child of xsl:override
.
Within the declaration of an overriding named component
(that is, a component whose declaration is a child of
xsl:override
, and has a name
attribute), where
the overridden component has public visibility, it is
possible to use the name xsl:original
as a symbolic reference to
the overridden component. More specifically:
Within a named template appearing as a child of
xsl:override
, the name xsl:original
may appear as the value of the name
attribute of
xsl:call-template
: for example,
<xsl:call-template name="xsl:original"/>
.
Within a stylesheet function appearing as a child of
xsl:override
, the static context for contained XPath
expressions (other than static
expressions) is augmented as follows: the statically
known function signatures includes a mapping from the name
xsl:original
to the signature of the overridden
function (which is the same as the signature of the overriding function).
This means that the name xsl:original
can be used in static
function calls, including calls that use partial function application
(where one of the arguments is given as "?"
), and also in named function
references. For example: xsl:original($x)
,
xsl:original($x, ?)
, xsl:original#2
.
Note:
The result of calling function-name(xsl:original#2)
is
the name of the overridden function, not
xsl:original
.
If the function xsl:original
is
called with keyword arguments, the keywords used are those of the overridden
function.
Neither xsl:original
, nor the overridden function, is added
to the dynamically known function definitionsXP40 component of the dynamic context for
XPath expressions within the overriding function. This means that any
attempt to bind the function name xsl:original
dynamically
(for example using function-lookup
FO40, or
function-available
, or
xsl:evaluate
) will fail, and any attempt to bind
the name of the overriding/overridden function dynamically will return
the overriding function.
Within a global variable or parameter appearing as a
child of xsl:override
, the static context for contained
XPath expressions (other than static
expressions) is augmented as follows: the in-scope
variables includes a mapping from the name
xsl:original
to the declared type of the overridden
variable or parameter (which is the same as the type of the overriding
global variable or parameter).
Within an attribute set appearing as a child of
xsl:override
, any
[xsl:]use-attribute-sets
attribute (whether on the
xsl:attribute-set
element itself, or on any
descendant element) may include the name xsl:original
as a
reference to the overridden attribute set.
Within the overriding component CP, the symbolic reference
xsl:original
is bound to the hidden component CPQ
described earlier, whose body is that of the component CQ in the
used package.
[ERR XTSE3075] It is a static error to use the
component reference xsl:original
when the overridden
component has visibility="abstract"
.
Modes are not overridable, so the name
xsl:original
cannot be used to refer to a mode (for example in the mode
attribute of
xsl:apply-templates
).
Note:
In the case of variables, templates, and attribute sets, the invocation of the overridden component can occur only within the lexical scope of the overriding component. With functions, however, there is greater flexibility. The overriding component can obtain a reference to the overridden component in the form of a function item, and can export this value by passing it to other functions or returning it in its result. A dynamic invocation of this function item (and hence, of the overridden function) can thus occur anywhere.
[Definition: The process of identifying the component to which a symbolic reference applies (possibly chosen from several homonymous alternatives) is called reference binding.]
The process of reference binding in the presence of overriding declarations is best illustrated by an example. The formal rules follow later in the section.
Consider a package Q defined as follows:
<xsl:package name="Q" version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:variable name="A" visibility="final" select="$B + 1"/> <xsl:variable name="B" visibility="private" select="$C * 2"/> <xsl:variable name="C" visibility="public" select="22"/> </xsl:package>
(The process is illustrated here using variables as the components, but the logic would be the same if the example used functions, named templates, or attribute sets.)
There are three components in this package, and their properties are illustrated in the following table. (The ID column is an arbitrary component identifier used only for the purposes of this exposition.)
ID | Symbolic Name | Declaring Package | Containing Package | Visibility | Body | Bindings |
---|---|---|---|---|---|---|
AQ | variable A | Q | Q | final | $B + 1 |
$B → BQ |
BQ | variable B | Q | Q | private | $C * 2 |
$C → CQ |
CQ | variable C | Q | Q | public | 22 |
none |
Now consider a package P that uses Q, and that overrides one of the variables declared in Q:
<xsl:package name="P" version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <xsl:use-package name="Q"> <xsl:override> <xsl:variable name="C" visibility="private" select="$xsl:original + 3"/> </xsl:override> </xsl:use-package> <xsl:template name="T" visibility="public"> <xsl:value-of select="$A"/> </xsl:template> </xsl:package>
Package P has five components, whose properties are shown in the following table:
ID | Symbolic Name | Declaring Package | Containing Package | Visibility | Body | Bindings |
---|---|---|---|---|---|---|
APQ | variable A | Q | P | final | $B + 1 |
$B → BPQ |
BPQ | variable B | Q | P | hidden | $C * 2 |
$C → CP |
CPQ | variable C | Q | P | hidden | 22 |
none |
CP | variable C | P | P | private | $xsl:original + 3 |
$xsl:original → CPQ |
TP | template T | P | P | public | value-of select="$A |
$A → APQ |
The effect of these bindings is that when template T is called,
the result is 51
. This is why:
The result of T is the value of APQ.
The value of APQ is the value of BPQ plus 1.
The value of BPQ is the value of CP times 2.
The value of CP is the value of CPQ plus 3.
The value of CPQ is 22.
So the final result is ((22 + 3) * 2) + 1
In this example, the components of P are established in three different ways:
Components APQ, BPQ, and CPQ are modified copies of the corresponding component AQ, BQ, and CQ in the used package Q. The properties of these components are modified as follows:
The symbolic identifier, declaring package, and body are unchanged.
The containing package is changed to P.
The visibility is changed according to the
rules in 3.5.3.2 Accepting Components: in particular,
visibility="private"
changes to
visibility="hidden"
.
The references to other components are rebound as described in this section.
Component CP is the overriding component. Its properties
are exactly as if it were declared as a top-level component in
P (outside the xsl:use-package
element), except that (a) it must adhere to the constraints on
overriding components (see 3.5.3.3 Overriding Components from a Used Package), (b) it is allowed to use
the variable reference $xsl:original
, and (c) the fact
that it overrides CQ affects the way that references from
other components are rebound.
Component TP is a new component declared locally in P.
The general rules for reference binding can now be stated:
If the containing package of a component CP is P, then all symbolic references in CP are bound to components whose containing package is P.
When a package P uses a package Q, then for every component CQ in Q, there is a corresponding component CP in P, as described in 3.5.3.2 Accepting Components.
Given a component CP whose containing package and declaring package are the same package P, then (as a consequence of rules
elsewhere in this specification) for every symbolic reference
D within CP, other than a reference using the name
xsl:original
, there will always be exactly one non-hidden
component DP whose containing package is P and
whose symbolic identifier matches D
(otherwise a static error will have been raised). The reference is then
bound to DP.
In the case of a component reference using the name
xsl:original
, this will in general appear within a
component CP that overrides a component CQ whose
corresponding component in P is CPQ, and the
xsl:original
reference is bound to CPQ.
Given a component CP whose containing package
P is a different package from its declaring package
R (that is, CP is present in P by
virtue of an xsl:use-package
declaration referencing
package Q, which may or may not be the same as R),
then the component bindings in CP are derived from the
component bindings in the corresponding component CQ as
follows: if the component binding within CQ is to a component
DQ, then:
If DQ is overridden within P by a component DP, then the reference is bound to DP;
Otherwise, the reference is bound to the component DPQ in P whose corresponding component in Q is DQ.
When reference resolution is performed on a package that is intended to be used
as a stylesheet (that is, for the
top-level package), there must
be no symbolic references referring to components whose visibility is
abstract
(that is, an implementation must be provided for every
abstract component).
[ERR XTSE3080] It is a static error if a
top-level package (as
distinct from a library
package) contains
components whose visibility is abstract
.
Note:
Abstract components in a used package by default become hidden in the using package, which means that a reference to the component in the top-level package will fail to resolve (resulting in a different static error). This particular error occurs only if the abstract component is declared within the top-level package. [XSLT 3.0 Erratum E4, bug 30142].
Note:
Unresolved references are allowed at the module level but not at the package level. A stylesheet module can contain references to components that are satisfied only when the module is imported into another module that declares the missing component.
Note:
The process of resolving references (or linking) is critical to an implementation that uses separate compilation. One of the aims of these rules is to ensure that when compiling a package, it is always possible to determine the signature of called functions, templates, and other components. A further aim is to establish unambiguously in what circumstances components can be overridden, so that compilers know when it is possible to perform optimizations such as inlining of function and variable references.
Suppose a public template T calls a private function F. When the package containing these two components is referenced by a using package, the template remains public, while the function becomes hidden. Because the function becomes hidden, it can no longer conflict with any other function of the same name, or be overridden by any other function; at this stage the compiler knows exactly which function T will be calling, and can perform optimizations based on this knowledge.
The mechanism for resolving component references described in this section is consistent with the mechanism used for binding function and variable references described in the XPath specification. XPath requires these variable and function names to be present in the static context for an XPath expression. XSLT ensures that all the non-hidden functions, global variables, and global parameters in a package are present in the static context for every XPath expression that appears in that package, along with required information such as the type of a variable and the signature of a function.
Named component references within inline functions follow the standard rules, but the rules need to be interpreted with care. Suppose that in package P we find the declarations:
<xsl:variable name="v" as="xs:integer" visibility="public" select="3"/> <xsl:function name="f:factory" as="fn(*)" visibility="final"> <xsl:sequence select="fn() { $v }"/> </xsl:function>
and that in a using package Q we find:
<xsl:use-package name="P"> <xsl:override> <xsl:variable name="v" as="xs:integer" select="4"/> </xsl:override> </xsl:use-package> <xsl:template name="xsl:initial-template"> <v value="{f:factory()()}"/> </xsl:template>
The correct output here is <v value="4"/>
.
The explanation for this is as follows. Package Q contains a function f:factoryQP
whose declaring package is P and whose containing package is Q. The symbolic reference
$v
within the body of this function is resolved in the normal way; since the containing package
is Q, it is resolved to the global variable vQ: that is, the overriding declaration
of $v
that appears within the xsl:override
element within package Q,
whose value is 4.
In terms of internal implementation, one way of looking at this is that the anonymous function returned
by f:factory
contains within its closure bindings for the global variables and functions that
the anonymous function references; these bindings are inherited from the component bindings of the
component that lexically contains these symbolic references, which in this case is f:factory
,
and more specifically the version of the f:factory
component in package Q.
There are several functions in which a dynamically evaluated QName is used to
identify a component: these include key
,
accumulator-before
,
accumulator-after
,
function-lookup
FO40, and
function-available
. Dynamic references can also occur
in the XPath expression supplied to the xsl:evaluate
instruction.
In all these cases, the set of components that are available to be referenced
are those that are declared in the package where this function call appears,
including components declared within an xsl:override
declaration in that package, but excluding components declared with
visibility="abstract"
. If the relevant component has been
overridden in a different package, the overriding declarations are not
considered.
If one of these functions (for example key
or
accumulator-before
) is invoked via a dynamic function
invocation, then the relevant package is the one in which the function item is
created (using a construct such as key#2
, key('my-key',
?)
, or function-lookup($KEYFN, 2)
). Function items
referring to context-dependent functions bind the context at the point where
the function item is created, not the context at the point where the function
item is invoked.
Note:
This means that if a package wishes to make a key available for use by a
calling package, it can do so by creating a public global variable whose
value is a partial application of the key
function:
<xsl:variable name="get-order" select="key('orders-key', ?, ?)"/>
which the calling code can invoke as $get-order('123-456', /)
.
The rules in the previous section apply to named components including functions, named templates, global variables, and named attribute sets. The rules for modes, and the template rules appearing within a mode, are slightly different.
The unnamed mode is local to a package: in effect, each package has its own
private unnamed mode, and the unnamed mode of one package does not interact with
the unnamed mode of any other package. An
xsl:apply-templates
instruction with no mode
attribute is treated as a symbolic reference to the default
mode defined for that instruction (see 3.7.3 The default-mode Attribute), which in
turn defaults to the unnamed mode. Because the unnamed mode
always has private visibility, it cannot be overridden in another
package.
A named mode may be declared in an xsl:mode
declaration as being
either public
, private
, or final
. The
values of the visibility
attribute are interpreted as follows:
Value | Meaning |
---|---|
public | A using package may use
xsl:apply-templates to invoke templates in this mode;
it may also declare additional template rules in this mode, which are
selected in preference to template rules in the used package. These may
appear only as children of the xsl:override element
within the xsl:use-package element. |
private | A using package may neither reference the mode nor provide additional templates in this mode; the name of the mode is not even visible in the using package, so no such attempt is possible. The using package can use the same name for its own modes without risk of conflict. |
final | A using package may use
xsl:apply-templates to invoke templates in this mode,
but it must not provide additional template rules in this mode. |
As with other named components, an xsl:use-package
declaration
may contain an xsl:accept
element to control the visibility of a
mode acquired from the used package. The allowed values of its
visibility
attribute are public
,
private
, and final
.
The xsl:mode
declaration itself must not be overridden. A using
package must not contain an xsl:mode
declaration whose name
matches that of a public
or final
xsl:mode
component accepted from a used package.
The xsl:expose
and xsl:accept
elements may be
used to reduce the visibility of a mode in a using package; the same rules apply
in general, though some of the rules are not applicable because, for example,
modes cannot be abstract
.
It is not possible for a package to combine the template rules from two other
packages into a single mode. When xsl:apply-templates
is used
without specifying a mode, the chosen template rules will always come from the
same package; when it is used with a named mode, then they will come from the
package where the mode is defined, or any package that uses that package and adds
template rules to the mode. If two template rules defined in different packages
match the same node, then the rule in the using package wins over any rule in the
used package; this decision is made before taking other factors such as import
precedence and priority into account.
A static error occurs if two modes with the same name are visible within a package, either because they are both declared within the package, or because one is declared within the package and the other is acquired from a used package, or because both are accepted from different used packages.
The rules for matching template rules by import precedence and priority operate as
normal, with the addition that template rules declared within an
xsl:use-package
element have higher precedence than any
template rule declared in the used package. More specifically, given an xsl:apply-templates
instruction
in package P, naming a mode M that is declared in a used
package Q and is overridden in P, the search order for
template rules is:
Rules declared within P (specifically,
xsl:template
rules declared as children of an
xsl:override
element within the
xsl:use-package
element that references package
Q). If there are multiple rules declared within P
that match a selected node, they are resolved on the basis of their explicit
or implicit priority, and if the priorities are equal, the last one in declaration order wins.
Rules declared within Q, taking import precedence, priority, and declaration order into account in the usual way (see 6.5 Conflict Resolution for Template Rules).
Built-in template rules (see 6.8 Built-in Template Rules) selected
according to the on-no-match
attribute of the
xsl:mode
declaration (in Q), or its
default.
If the mode is overridden again in a package R that uses P, then this search order is extended by adding R at the start of the search list, and so on recursively.
Note:
If existing XSLT code has been written to use template rules in the unnamed
mode, a convenient way to incorporate this code into a library package is to add a stub module
that defines a new named public
or final
mode, in
which there is a single template rule whose content is the single instruction
<xsl:apply-templates select="."/>
. This in effect redirects
xsl:apply-templates
instructions using the named mode to
the rules defined in the unnamed mode.
In previous versions of XSLT, modes were implicitly declared by simply using a
mode name in the mode
attribute of xsl:template
or xsl:apply-templates
. XSLT 3.0 introduced the ability to
declare a mode explicitly using an xsl:mode
declaration (see
6.7.1 Declaring Modes).
By default, within a package that is defined using an explicit
xsl:package
element, all modes must be explicitly declared.
In an implicit package, however (that is, one rooted at an
xsl:stylesheet
or xsl:transform
element),
modes can be implicitly declared as in previous XSLT versions.
The declared-modes
attribute of xsl:package
determines whether or not modes that
are referenced within the package must be explicitly declared.
If the value is yes
(the default),
then it is an error to use a mode name
unless the package either contains
an explicit xsl:mode
declaration for that mode, or accepts the mode
from a used package. If the value is no
, then this is not an error.
This attribute affects all modules making up the package, it is not confined to
declarations appearing as children of the xsl:package
element.
[ERR XTSE3085] It is a static error,
when the effective value of the declared-modes
attribute of
an xsl:package
element is yes
, if the
package contains an explicit reference to an undeclared mode, or if
it implicitly uses the unnamed mode and the unnamed mode is undeclared.
For the purposes of the above rule:
A mode is declared if either of the following conditions is true:
The package contains an xsl:mode
declaration for that mode.
The mode is a public or final mode accepted from a used package.
The offending reference may be either an explicit mode name, or the token #unnamed
treated as a reference to the unnamed mode, or a defaulted mode attribute, and it may occur in any of the following:
The mode
attribute of an xsl:template
declaration
The mode
attribute of an xsl:apply-templates
instruction
An [xsl:]default-mode
attribute.
A package implicitly uses the unnamed mode if either of the following conditions is true:
There is an xsl:apply-templates
element with no mode
attribute, and with no ancestor-or-self having
an [xsl:]default-mode
attribute.
There is an xsl:template
element with a match
attribute and no mode
attribute, and with no ancestor-or-self having
an [xsl:]default-mode
attribute.
The xsl:import
and
xsl:include
declarations are local to a package.
Declarations of keys, accumulators,
decimal formats, namespace aliases (see
11.1.4 Namespace Aliasing), output definitions, and character
maps within a package have local scope within that package —
they are all effectively private. The elements that declare these constructs do
not have a visibility
attribute. The unnamed decimal format and the
unnamed output format are also local to a package.
If xsl:strip-space
or xsl:preserve-space
declarations appear within a library
package, they only affect calls to the doc
FO40 or
document
functions appearing within that package. Such a declaration within the top-level package additionally affects stripping of whitespace in
the document that contains the global context item.
An xsl:decimal-format
declaration within a package applies only
to calls on format-number
FO40 appearing within that
package.
An xsl:namespace-alias
declaration within a package applies only
to literal result elements within the same package.
An xsl:import-schema
declaration within a package adds the names
of the imported schema components to the static context for that package only;
these names are effectively private, in the sense that they do not become
available for use in any other packages. However, the names of schema components
must be consistent across the stylesheet as a whole: it is not possible for two
different packages within a stylesheet to use a type-name such as part-number
to
refer to different schema-defined simple or complex types.
Type names used in the interface of public components in a package (for example, in the arguments of a function) must be respected by callers of those components, in the sense that the caller must supply values of the correct type. Often this will mean that the using component, if it contains calls on such interfaces, must itself import the necessary schema components. However, the requirement for an explicit schema import applies only where the package contains explicit use of the names of schema components required to call such interfaces.
Note:
For example, suppose a library
package contains a function which requires an argument of type
mfg:part-number
. The caller of this function must supply an
argument of the correct type, but does not need to import the schema unless it
explicitly uses the schema type name mfg:part-number
. If it
obtains an instance of this type from outside the package, for example as the
result of another function call, then it can supply this instance to the
acquired function even though it has not imported a schema that defines this
type.
At execution time, the schema available for validating instance documents contains (at least) the union of the schema components imported into all constituent packages of the stylesheet.
The xsl:global-context-item
element is used to declare whether a
global context item is required, and if so, what its
required type is.
The element is a declaration that
can appear at most once in any stylesheet module; and if more than one
xsl:global-context-item
declaration appears within a package, then the declarations must be consistent. Specifically, all
the attributes must have semantically equivalent values.
Note:
This means that omitting an attribute is equivalent to specifying its default value explicitly; and purely lexical variations, such as the presence of whitespace in an attribute value, are not considered significant.
[ERR XTSE3087] It is a static error if more than
one xsl:global-context-item
declaration appears within a
stylesheet module, or if several modules within a
single package contain inconsistent
xsl:global-context-item
declarations
If there is no xsl:global-context-item
declaration for a package,
this is equivalent to specifying the empty element
<xsl:global-context-item/>
, which imposes no constraints.
<!-- Category: declaration -->
<xsl:global-context-item
as? = item-type
use? = "required" | "optional" | "absent"〔'optional'〕 />
The use
attribute takes the value required
,
optional
, or absent
. The
default is optional
.
If the value required
is specified, then there must be a
global context item.
If the value optional
is specified, or if the attribute is
omitted, or if the xsl:global-context-item
element is
omitted, then there may or may not be a global context item.
If the value absent
is specified, then the global focus
(context item, position, and size) will be absent
Note:
This specification does not define whether supplying a global context item in this situation results in an error or warning, or whether the supplied context item is simply ignored.
If the as
attribute is present then its value must be an ItemTypeXP40. If the attribute is
omitted this is equivalent to specifying as="item()"
.
The as
attribute defines the required type of the global context
item. The default value is as="item()"
. If a global context item is
supplied then it must conform to the required type, after conversion (if
necessary) using the coercion rules.
[ERR XTSE3089] It is a static error if the as
attribute is
present when use="absent"
is specified.
The global context item is available only within the top-level package. If a valid xsl:global-context-item
declaration appears within a library package, then it is
ignored, unless it specifies use="required"
, in which case an error
is raised: [see ERR XTTE0590].
Note:
In earlier releases of this specification, the global context item and
the initial match selection were essentially the same thing, often referred
to as the principal source document. In XSLT 3.0, they were separated:
the global context item is a single item accessible to the initializers of global variables
as the value of the expression .
(dot), while the initial match selection
is a sequence of nodes or other items supplied to an initial implicit xsl:apply-templates
invocation.
APIs that were originally designed for use with earlier versions of XSLT are likely to bundle the two concepts together.
With a streamable processor, the initial match selection can consist of streamed nodes, but the global context item is always grounded, because it is available to all global variables and there is no control over the sequence of processing.
A type error is raised if
the top-level package contains
an xsl:global-context-item
declaration specifying a required type that does not match the supplied global context item. The error code is the same as for
xsl:param
: [see ERR XTTE0590].
[XSLT 3.0 Erratum E7, bug 30179].
Note:
If the ItemType
is one that can only be satisfied by a
schema-validated input document, for example
as="schema-element(invoice)"
, the processor may interpret this as a request to apply schema
validation to the input. Similarly, if the KindTest
indicates that
an element node is required, the processor may interpret this as a request to
supply the document element rather than the document node of a supplied input
document.
[ERR XTDE3086] It is a dynamic error if an
xsl:global-context-item
declaration specifies
use="required"
, and no global context item is supplied. [XSLT 3.0 Erratum E6, bug 30173].
Note:
XSLT 4.0 provides built-in functions for parsing CSV files (for example
the functions parse-csv
FO40 and csv-to-xml
FO40
that should not be confused with the functionality defined by this example. The
example pre-dates the XSLT 4.0 capabilities.
The example in this section illustrates the use of overrides to customize or
extend a (fictional) library package named
http://example.com/csv-parser
, which provides a parsing function
for data formatted as lines containing comma-separated values. For simplicity of
exposition, the example shows a simple, naive implementation; a realistic CSV
parser would be more complicated and make the example harder to follow.
The basic functionality of the package is provided by the function
csv:parse
, which expects a string parameter named
input
. By default, the function parses the input into lines,
and breaks lines on commas, returning as result an element named
csv
containing one row
element per line, each
row
containing a sequence of field
elements.
A simple stylesheet which uses this library and applies it to a string might
look like the following. The initial template applies csv:parse
to
a suitable string and returns a copy of the result:
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:csv="http://example.com/csv" exclude-result-prefixes="xs csv" version="3.0"> <xsl:output indent="yes"/> <xsl:use-package name="http://example.com/csv-parser" package-version="*"/> <!-- example input "file" --> <xsl:variable name="input" as="xs:string"> name,id,postal code "Abel Braaksma",34291,1210 KA "Anders Berglund",473892,9843 ZD </xsl:variable> <!-- entry point --> <xsl:template name="xsl:initial-template"> <xsl:copy-of select="csv:parse($input)"/> </xsl:template> </xsl:stylesheet>
The result returned by this stylesheet would be:
<csv> <row> <field quoted="no">name</field> <field quoted="no">id</field> <field quoted="no">postal code</field> </row> <row> <field quoted="yes">Abel Braaksma</field> <field quoted="no">34291</field> <field quoted="no">1210 KA</field> </row> <row> <field quoted="yes">Anders Berglund</field> <field quoted="no">473892</field> <field quoted="no">9843 ZD</field> </row> </csv>
Variations on this default behavior are achieved by overriding selected declarations in the package, as described below.
The package module itself is version 1.0.0 of a package called
http://example.com/csv-parser
; it has the following
structure:
<?xml version="1.0" encoding="UTF-8"?> <xsl:package name="http://example.com/csv-parser" package-version="1.0.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:csv="http://example.com/csv" exclude-result-prefixes="xs csv" declared-modes="yes" version="3.0"> <!--* Mode declarations ... *--> <!--* Variable declarations ... *--> <!--* Attribute-set declaration ... *--> <!--* Function declarations ... *--> <!--* Templates ... *--> </xsl:package>
The contents of the package (represented here by comments) are described more fully below.
csv:parse
Function and its User-customization HooksThe csv:parse
function is final and cannot be overridden. As can be
seen from the code below, it (1) parses its input
parameter into
lines, (2) calls function csv:preprocess-line
on each line, then
(3) applies the templates of mode csv:parse-line
to the
pre-processed value. The result is then (4) processed again by mode
csv:post-process
.
<xsl:function name="csv:parse" visibility="final"> <xsl:param name="input" as="xs:string"/> <xsl:variable name="result" as="element()"> <csv> <xsl:apply-templates select="(tokenize($input, $csv:line-separator) ! csv:preprocess-line(.))" mode="csv:parse-line"/> </csv> </xsl:variable> <xsl:apply-templates select="$result" mode="csv:post-process"/> </xsl:function>
The default code for this processing is given below. Each part of the processing except the first (the tokenization into lines) can be overridden by the user of the package.
The first user-customization hook is given by the global variable
csv:line-separator
, which specifies the line separator used to
break the input string into lines. It can be overridden by the user if need be.
The default declaration attempts to handle the line-separator sequences used by
most common operating systems in text files:
<xsl:variable name="csv:line-separator" as="xs:string" select="'\r\n?|\n\r?'" visibility="public"/>
The function csv:preprocess-line
calls
normalize-space()
on its argument:
<xsl:function name="csv:preprocess-line" as="xs:string?" visibility="public"> <xsl:param name="line" as="xs:string"/> <xsl:sequence select="normalize-space($line)"/> </xsl:function>
Because the function is declared public
, it can be overridden by a
user. (This might be necessary, for example, if whitespace within quoted
strings needs to be preserved.)
csv:parse-line
By default, the mode csv:parse-line
parses the current item (this
will be one line of the input data) into fields, using mode
csv:parse-field
on the individual fields and (by default)
wrapping the result in a row
element.
The mode is declared with visibility="public"
to allow it to be
called from elsewhere and overridden:
<xsl:mode name="csv:parse-line" visibility="public"/>
<xsl:template match="." mode="csv:parse-line"> <row> <xsl:apply-templates select="tokenize(., $csv:field-separator)" mode="csv:parse-field"/> </row> </xsl:template>
This relies on the variable csv:field-separator
, which is a comma
by default but which can be overridden by the user to parse tab-separated data
or data with other delimiters.
<xsl:variable name="csv:field-separator" as="xs:string" select="','" visibility="public"/>
The default implementation of csv:parse-line
does not handle
occurrences of the field separator occurring within quoted strings. The user
can add templates to the mode to provide that functionality.
csv:parse-field
Mode csv:parse-field
processes the current item as a field; by
default it strips quotation marks from the value, calls the function
csv:preprocess-field()
on it, and wraps the result in a
field
element, which carries the attributes declared in the
attribute set csv:field-attributes
.
<xsl:template match="." mode="csv:parse-field" expand-text="yes"> <xsl:variable name="string-body-pattern" as="xs:string" select="'([^' || $csv:validated-quote || ']*)'"/> <xsl:variable name="quoted-value" as="xs:string" select="$csv:validated-quote || $string-body-pattern || $csv:validated-quote"/> <xsl:variable name="unquoted-value" as="xs:string" select="'(.+)'"/> <field xsl:use-attribute-sets="csv:field-attributes">{ csv:preprocess-field( replace(., $quoted-value || '|' || $unquoted-value, '$1$2')) }</field> </xsl:template>
The attribute set csv:field-attributes
includes, by default, a
quoted
attribute which has the values yes
or
no
to show whether the input value was quoted or not.
<xsl:attribute-set name="csv:field-attributes" visibility="public"> <xsl:attribute name="quoted" select="if (starts-with(., $csv:validated-quote)) then 'yes' else 'no'"/> </xsl:attribute-set>
The mode csv:parse-field
is declared with
visibility="public"
to allow it to be called from elsewhere and
overridden; it specifies on-no-match="shallow-copy"
so that any
string not matching a template will simply be copied:
<xsl:mode name="csv:parse-field" on-no-match="shallow-copy" visibility="public"/>
csv:quote
VariableThe variable csv:quote
can be used to specify the character used
in a particular input stream to quote values.
<xsl:variable name="csv:quote" as="xs:string" select="'"'" visibility="public"/>
The template given above assumes that the variable is one character long. To
ensure that any overriding value of the variable is properly checked, references to the value use a
second variable csv:validated-quote
, which
is declared private
to ensure that the checking cannot be
disabled.
<xsl:variable name="csv:validated-quote" visibility="private" as="xs:string" select=" if (string-length($csv:quote) ne 1) then error(xs:QName('csv:ERR001'), 'Incorrect length for $csv:quote, should be 1') else $csv:quote"/>
When the value of csv:quote
is not
exactly one character long, the reference to
csv:validated-quote
will cause an error (csv:ERR001)
to be raised.
csv:preprocess-field
FunctionThe function csv:preprocess-field
is called on each field after
any quotation marks are stripped and before it is written out as the value of a
field
element:
<xsl:function name="csv:preprocess-field" as="xs:string"> <xsl:param name="field" as="xs:string"/> <xsl:sequence select="$field"/> </xsl:function>
As can be seen, the function does nothing but return its input; its only purpose is to provide the opportunity for the user to supply a suitable function to be invoked at this point in the processing of each field.
csv:post-process
The mode csv:post-process
is intended solely as a hook for user
code. By default, it does nothing.
The package defines no templates for this mode; the mode definition makes it return a copy of its input:
<xsl:mode name="csv:post-process" on-no-match="shallow-copy" visibility="public"/>
As can be seen from the code shown above, the package provides several opportunities for users to override the default behavior:
The global variables csv:line-separator
,
csv:field-separator
, and csv:quote
can be
overridden to specify the character strings used to separate lines and
fields and to quote individual field values.
The function csv:preprocess-line
can be overridden to do
more (or less) than stripping white space; the function
csv:preprocess-field
can be overridden to process
individual field values.
Templates can be added to the modes csv:parse-line
,
csv:parse-field
, and csv:post-process
to
change their behavior.
The attribute set csv:field-attributes
can be overridden to
specify a different set of attributes (or none) for field
elements.
The following using stylesheet illustrates the use of the
xsl:override
element to take advantage of several of these
opportunities:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:csv="http://example.com/csv" exclude-result-prefixes="xs csv" version="3.0"> <xsl:output indent="yes"/> <xsl:use-package name="http://example.com/csv-parser" package-version="*"> <xsl:override> <!-- Change the root element from 'csv' to 'root' --> <xsl:template match="csv" mode="csv:post-process"> <root> <xsl:apply-templates mode="csv:post-process"/> </root> </xsl:template> <!-- add an extra attribute that uses the context item --> <xsl:attribute-set name="csv:field-attributes" use-attribute-sets="xsl:original"> <xsl:attribute name="type" select="if (. castable as xs:decimal) then 'numeric' else 'string'"/> </xsl:attribute-set> <!-- use semicolon not comma between fields --> <xsl:variable name="csv:field-separator" as="xs:string" select="';'" visibility="public"/> <!-- prevent empty rows from appearing with empty lines --> <xsl:function name="csv:preprocess-line" as="xs:string?" visibility="public"> <xsl:param name="line" as="xs:string"/> <xsl:variable name="norm-line" select="normalize-space(xsl:original($line))"/> <xsl:sequence select="if (string-length($norm-line) > 0) then $norm-line else ()"/> </xsl:function> </xsl:override> </xsl:use-package> <!-- example input "file" --> <xsl:variable name="input" as="xs:string"> name;id;postal code "Braaksma Abel";34291;1210 KA "Berglund Anders";473892;9843 ZD </xsl:variable> <!-- entry point --> <xsl:template name="xsl:initial-template"> <xsl:copy-of select="csv:parse($input)"/> </xsl:template> </xsl:stylesheet>
Note:
As it does elsewhere, the visibility of components declared within
xsl:override
defaults to private
; to keep
the component public, it is necessary to specify visibility
explicitly.
The types and optionality of all function parameters must match those of the function being overridden; for function overriding to be feasible, packages must document the function signature thoroughly.
The names, types, and optionality of all named-template parameters must match those of the template being overridden; for overriding to be feasible, packages must document the template signature thoroughly.
The values for the attributes in the attribute set
csv:field-attributes
are calculated once for each
element for which the attribute set is supplied; the
select
attributes which determine the values can thus
refer to the context item. Here, the value specification for the
type
attribute checks to see whether the string value
of the context item is numeric by inquiring whether it can be cast to
decimal, and sets the value for the type
attribute
accordingly.
The result returned by this stylesheet would be:
<root> <row> <field quoted="no" type="string">name</field> <field quoted="no" type="string">id</field> <field quoted="no" type="string">postal code</field> </row> <row> <field quoted="yes" type="string">Braaksma Abel</field> <field quoted="no" type="numeric">34291</field> <field quoted="no" type="string">1210 KA</field> </row> <row> <field quoted="yes" type="string">Berglund Anders</field> <field quoted="no" type="numeric">473892</field> <field quoted="no" type="string">9843 ZD</field> </row> </root>
[Definition: A package 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 [XDM 3.0]). 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.
The principal stylesheet module of a package may take one of three forms:
A package manifest, as described in 3.5 Packages, which is a
subtree rooted at an xsl:package
element
An implicit package, which is a subtree rooted at an
xsl:stylesheet
or xsl:transform
element.
This is transformed automatically to a package as described in 3.5 Packages.
A simplified stylesheet, which is a subtree rooted at a literal result element,
as described in 3.8 Simplified Stylesheet Modules. This is first converted
to an implicit package by wrapping it in an xsl:stylesheet
element using the transformation described in 3.8 Simplified Stylesheet Modules, and then to an explicit package (rooted at an
xsl:package
element) using the transformation described in
3.5 Packages.
A stylesheet module other than the principal stylesheet module of a package may take either of two forms:
[Definition: A
standard stylesheet module, which is a subtree rooted at an
xsl:stylesheet
or xsl:transform
element.]
[Definition: A simplified stylesheet, which is a subtree rooted at a literal result element, as described in 3.8 Simplified Stylesheet Modules. This is first converted to a standard stylesheet module by wrapping it in an xsl:stylesheet element using the transformation described in 3.8 Simplified Stylesheet Modules.]
Whichever of the above forms a module takes, the outermost
element (xsl:package
, xsl:stylesheet
, or a literal result element) may either be the outermost
element of an XML document, or it may be a child of some
(non-XSLT) element in a host document.
[Definition: A stylesheet module whose outermost element is the child of a non-XSLT element in a host document is referred to as an embedded stylesheet module. See 3.12 Embedded Stylesheet Modules.]
A new attribute, main-module
, is added to the xsl:stylesheet
element. The attribute is provided for the benefit of development tools such as syntax-directed
editors to provide information about all the components (variables, functions, etc) visible
within a stylesheet module.
[Issue 87 PR 353 19 April 2023]
<xsl:stylesheet
id? = id
version = decimal
default-mode? = eqname | "#unnamed"〔'#unnamed'〕
default-validation? = "preserve" | "strip"〔'strip'〕
input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = boolean
fixed-namespaces? = string
main-module? = uri
use-when? = expression〔true()〕
xpath-default-namespace? = uri >
<!-- Content: (declarations) -->
</xsl:stylesheet>
<xsl:transform
id? = id
version = decimal
default-mode? = eqname | "#unnamed"〔'#unnamed'〕
default-validation? = "preserve" | "strip"〔'strip'〕
input-type-annotations? = "preserve" | "strip" | "unspecified"〔'unspecified'〕
default-collation? = uris
extension-element-prefixes? = prefixes
exclude-result-prefixes? = prefixes
expand-text? = boolean〔'no'〕
fixed-namespaces? = string
main-module? = uri
use-when? = expression〔true()〕
xpath-default-namespace? = uri >
<!-- Content: (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
.
The version
attribute indicates the version
of XSLT that the stylesheet module requires. The attribute is
required.
[ERR XTSE0110] The value of the version
attribute must be a number:
specifically, it must be a valid instance of the type
xs:decimal
as defined in [XML Schema Part 2].
The version
attribute is intended to indicate the
version of the XSLT specification against which the stylesheet is written. In a
stylesheet written to use XSLT 4.0, the value should normally be
set to 4.0
. If the value is numerically less than 4.0, the
stylesheet is processed using the rules for backwards compatible behavior
(see 3.9 Backwards Compatible Processing). If the value is numerically greater than
4.0, the stylesheet is processed using the rules for
forwards compatible behavior (see 3.10 Forwards Compatible Processing).
The effect of the input-type-annotations
attribute is described in
4.3.1 Stripping Type Annotations from a Source Tree.
The [xsl:]default-validation
attribute defines the default value of the
validation
attribute of all relevant instructions appearing within
its scope. For details of the effect of this attribute, see 26.4 Validation.
The optional main-module
attribute is purely documentary.
By including this attribute in every stylesheet module of a package,
an XSLT editing tool may be enabled to locate the top-level module of the relevant package,
and thus to gather information about all the global variables, templates, and functions available
within the module being edited.
This information can be used (for example) to enable auto-completion and error highlighting of the code as it is
entered. Note that it may be inconvenient or misleading to use this attribute when the stylesheet
module is used as a shared component within multiple stylesheets.
[ERR XTSE0120] An xsl:stylesheet
, xsl:transform
,
or xsl:package
element must not have any
text node children. (This rule applies after stripping of whitespace text nodes as described in 3.13.1 Stripping Whitespace and Commentary from the Stylesheet.)
[Definition: An element occurring as a child of an
xsl:package
,
xsl:stylesheet
,
xsl:transform
, or xsl:override
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.7.4 User-defined Data Elements)].
The declaration elements permitted in the
xsl:stylesheet
element are:
xsl:accumulator
xsl:attribute-set
xsl:character-map
xsl:decimal-format
xsl:function
xsl:global-context-item
xsl:import
xsl:import-schema
xsl:include
xsl:key
xsl:mode
xsl:namespace-alias
xsl:output
xsl:param
xsl:preserve-space
xsl:record-type
xsl:strip-space
xsl:template
xsl:use-package
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.
The child elements of the xsl:stylesheet
element may appear in any order. In most cases, the ordering of these elements does
not affect the results of the transformation; however:
As described in 6.5 Conflict Resolution for Template Rules, when two template rules with the same priority match the same nodes, there are situations where the order of the template rules will affect which is chosen.
Forwards references to static variables are not allowed in static expressions.
fixed-namespaces
Attribute
The xsl:stylesheet
, xsl:transform
, or xsl:package
element may have a fixed-namespaces
attribute making it easier to have the same
namespace declarations in force throughout a stylesheet.
[Issue 369 PR 470 29 November 2023]
The fixed-namespaces
attribute, if present, defines the
fixed namespace bindings
for a stylesheet module. The attribute may appear only on the
outermost element of a stylesheet module (xsl:stylesheet
,
xsl:transform
, or xsl:package
). It is
not available with simplified stylesheet modules.
If the fixed-namespaces
attribute is present, then it defines the entire
set of namespace bindings present in the static context of XPath expressions and
patterns within the stylesheet,
as well as other constructs where namespace prefixes are used in attribute and text nodes,
such as the name
attribute of declarations like xsl:function
and xsl:variable
, and as
and type
attributes
referring to item types and schema types.
The value of the attribute is a whitespace-separated list of tokens, where each token contributes one or more namespace bindings to the fixed namespace bindings of the stylesheet module. Each token must be one of the following. If a token falls into more than one of these categories, then the first one that applies takes precedence.
The string #standard
, which is equivalent to specifying
xsl xml xs xsi fn math map array err
. This has the effect of binding
each of these namespace prefixes to the reserved namespace with which
it is conventionally associated.
An NCName
corresponding to one of the namespace prefixes present
in the in-scope namespaces of the containing element node. This has the effect of adding
the corresponding namespace binding to the fixed namespace bindings.
Any one of the strings xsl
, xml
,
xs
, xsi
, fn
, math
,
map
, array
, err
. This has the effect of binding
that particular namespace prefix to the reserved namespace with which
it is conventionally associated, whether or not the native namespace bindings
contain a binding for this prefix.
Note:
Including xml
in the list has no effect, since the XML namespace
will always be in scope anyway.
If the namespace prefix is explicitly bound to a different namespace, for example
xmlns:math="java:java.util.Math"
, then that binding takes precedence.
A string in the form prefix=uri
, where prefix
is an NCName
and uri
is a (non-empty) namespace URI: for example,
xalan=http://xml.apache.org/xalan
. This has the effect of binding the specified
prefix to the specified URI.
A URI Reference identifying the location of an
XML document whose namespace bindings are to be used. For example, ./package.xsl
.
A token is interpreted as a URI if it does not match any of the other possibilities listed above
(which will be the case if it contains a "/"
as in this example).
The URI Reference is used to locate an XML document, in the same way
as described for xsl:include
and xsl:import
in
3.11.1 Locating Stylesheet Modules. The resource that is retrieved may be any namespace well-formed
XML document. The in-scope namespace bindings of the outermost element of this document are
added to the fixed namespace bindings of the stylesheet module.
Note:
Such URIs cannot contain whitespace.
If different tokens in the fixed-namespaces
attribute result in multiple bindings
for the same namespace prefix, the last one wins.
[ERR XTSE0122] It is a static error if a token
appearing in the fixed-namespaces
attribute takes a form
that is not one of the permitted forms, or if it is interpreted as a URI
but cannot be dereferenced to locate a namespace well-formed XML document.
It is not permitted to bind the prefix xmlns
. It is not permitted to bind the
prefix xml
or the XML namespace URI http://www.w3.org/XML/1998/namespace
, other than
to each other.
The following observations apply when a fixed-namespaces
attribute is present:
All expressions in the stylesheet module will have the same statically known namespacesXP40 in their static context. This means that all prefixes used in XPath expressions, patterns, and similar constructs must be declared at the top level.
Namespace prefixes used in element and attribute names in the stylesheet
cannot be declared using this mechanism. Such prefixes must be bound using
native namespace bindings. This also applies to namespace
prefixes used in the [xsl:]exclude-result-prefixes
and [xsl:]extension-element-prefixes
attributes, and the
stylesheet-prefix
and result-prefix
attributes
of xsl:namespace-alias
.
It is not an error for an element within a stylesheet module
to rebind a prefix listed in the fixed-namespaces
attribute
to a different URI; however this rebinding has no effect on the static
context of XPath expressions and other similar constructs within its scope.
The fixed-namespaces
attribute has no effect on the interpretation
of unprefixed names.
Note:
It is possible to use
the fixed namespace bindings in other attributes of the xsl:stylesheet
element, such as default-mode
. It is also possible to use them in
shadow attributes (see 3.13.4 Shadow Attributes).
It is possible for the fixed-namespaces
attribute itself to be supplied as
a shadow attribute (written with an underscore, _fixed-namespaces
).
It can then refer to static variables
declared in an importing or including stylesheet module. This provides an
alternative way of sharing common namespace bindings throughout a package.
Note:
The ability to fetch namespace bindings using a URI can be exploited in various ways:
Generally, the benefit is that it avoids repeating the same information in every stylesheet module, thereby reducing the amount of boilerplate code and keeping common information in a common place. This satisfies the DRY principle in software engineering: Don't Repeat Yourself.
The document identified by the URI may be a stylesheet module. One way to use the feature is to use the package manifest as the primary source for namespace bindings.
It is also possible to adopt the namespace bindings from a sample source document. For example, if it is known that the stylesheet is designed primarily to process documents whose first start tag takes the form:
<w:document xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
then these three namespace bindings may conveniently be copied to the stylesheet by referencing a sample document of this form.
Note however, that only the namespace bindings from the outermost element of the document will be copied.
It is possible to supply multiple URIs to assemble namespace bindings from more than one source.
Namespace bindings taken from an external document may be overridden
using a local declaration for the prefix. This must appear after the URI
in the content of the fixed-namespaces
attribute.
Note:
Using the fixed-namespaces
attribute rather
than native namespace bindings
to bind namespaces has a number of potential benefits:
It reduces repetitive coding across stylesheet module boundaries, and thus eliminates a source of potential errors.
It ensures that all expressions in a stylesheet module have the same namespace bindings in their static context. This can reduce implementation overheads because it reduces the need to maintain the namespace context at the level of individual expressions through rewrites such as function inlining. With processors that compile stylesheets to a persistent executable form, it can contribute to a reduction in the size of compiled code.
Namespaces bound in this way will never accidentally leak into a result tree;
there is no need to exclude them using [xsl:]exclude-result-prefixes
.
Namespaces declared on literal result elements are used purely to define the namespace of elements and attributes within the result tree; they no longer leak into the static context used when evaluating XPath expressions.
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, when it appears on an element
E, is used to specify the default collation used by all XPath
expressions appearing in attributes or text value templates that have E as an
ancestor, 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 reference, then it is resolved as described in Section 5.3.1 CollationsFO40.. 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 include as the last
collation URI in the list either the Unicode Codepoint Collation or a collation in the UCA family (see 13.4 The Unicode Collation Algorithm) with the parameter
fallback=yes
.
The [xsl:]default-collation
attribute does not affect the collation
used by xsl:sort
or by xsl:merge
.
In the absence of an
[xsl:]default-collation
attribute, the default collation
may be set by the calling application in an implementation-defined way. The recommended default, unless the user
chooses otherwise, is to use the Unicode codepoint collation.
default-mode
AttributeThe [xsl:]default-mode
attribute defines the default value for the
mode attribute of all
xsl:template
and xsl:apply-templates
elements
within its scope.
More specifically, when an element E matches
the pattern (xsl:template[@match] | xsl:apply-templates)[not(@mode) or
normalize-space(@mode) eq "#default"]
(using the Unicode codepoint
collation), then the effective value of the mode
attribute is taken
from the value of the [xsl:]default-mode
attribute of the innermost
ancestor-or-self element of E that has such an attribute. If there is
no such element, then the default is the unnamed
mode. This is equivalent to specifying #unnamed
.
In addition, when the attribute appears on the xsl:package
,
xsl:stylesheet
, or xsl:transform
element of the
principal stylesheet module of the top-level package,
it provides a default value for the initial mode used on stylesheet
invocation.
The value of the [xsl:]default-mode
attribute must
either be an EQName, or the token #unnamed
which refers to
the unnamed mode.
Note:
This attribute is provided to support an approach to stylesheet modularity in which all the template rules for one mode are collected together into a single stylesheet module. Using this attribute reduces the risk of forgetting to specify the mode in one or more places where it is needed, and it also makes it easier to reuse an existing stylesheet module that does not use modes in an application where modes are needed to avoid conflicts with existing template rules.
It is not necessary for the referenced mode to be
explicitly declared in an xsl:mode
declaration, unless this is
mandated by the declared-modes
attribute (which defaults to
yes
on an xsl:package
element).
[Definition: In addition to
declarations, the
xsl:stylesheet
element may contain among its children 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 an
xsl:stylesheet
, xsl:transform
,
or xsl:package
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.2 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 25 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 simplified syntax is allowed for a stylesheet
module that defines only a single template rule for the document node.
The stylesheet module may consist of just a literal result element (see 11.1 Literal Result Elements)
together with its contents. Such a stylesheet module is equivalent to a standard stylesheet module
whose xsl:stylesheet
element contains a
template rule containing the literal result
element; the template rule has a match pattern of /
.
The following example shows a stylesheet that simply evaluates one XPath expression:
<out>{count(//*)}</out>
The output of the stylesheet will be an XML document such as <out>17</out>
showing the number of elements found in the supplied source document.
This simplified stylesheet is defined to be equivalent to the following expanded stylesheet:
<xsl:stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="4.0" expand-text="yes"> <xsl:template match="/"> <out>{count(//*)}</out> </xsl:template> </xsl:stylesheet>
A simplified stylesheet can contain XSLT instructions, in which case the XSLT namespace needs to be declared. This is illustrated in the next example.
This stylesheet outputs an HTML document containing a table that summarizes the value of transactions according to their rate of tax:
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xsl:version="4.0"> <head> <title>Expenditure by Tax Rate</title> </head> <body> <table> <thead> <tr> <th>Gross Amount</th> <th>Tax Rate</th> </tr> </thead> <tbody> <xsl:for-each-group select="//transaction" group-by="vat-rate"> <tr> <td>{sum(current-group()/value)}</td> <td>{current-grouping-key()}</td> </tr> </xsl:for-each-group> </tbody> </table> </body> </html>
Note that it is not possible, in a simplified stylesheet, to define
serialization properties (for example to request a DOCTYPE
declaration). A processor may offer a way to do
this using options in the transformation API.
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="4.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 otherwise '4.0'"/> <xsl:attribute name="expand-text" select="not(number(@xsl:version) le 3.0)"/> <xsl:element name="xsl:template"> <xsl:attribute name="match" select="'/'"/> <xsl:copy-of select="."/> </xsl:element> </xsl:element> </xsl:template> </xsl:stylesheet>
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 template rules, 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 match selection, to be matched by the implicit
match="/"
template rule using the unnamed mode.
Note:
There are two significant changes to simplified stylesheets in XSLT 4.0.
It is no longer required to include an xsl:version
attribute; this
in turn means it is often no longer necessary to declare the xsl
namespace.
The xsl:version
attribute defaults to the version of the XSLT processor,
that is, "4.0" for an XSLT 4.0 processor.
If the xsl:version
attribute is omitted, or is set to "4.0" or a larger
value, then the expand-text
attribute defaults to true
, meaning that
text value templates are recognized.
[Definition: The effective
version of an element in a stylesheet module or package manifest is the decimal value of the [xsl:]version
attribute
(see 3.4 Standard Attributes) on that element or on the innermost
ancestor element that has such an attribute, subject
to special rules for the xsl:output
and xsl:fallback
elements.]
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.
The effective version of an xsl:output
element
is the effective version of its parent element.
There are additional rules for an xsl:fallback
element: see
3.10 Forwards Compatible Processing.
[Definition: An element is processed with backwards compatible behavior if its effective version is less than 4.0.]
Specifically:
If the effective version is equal to 1.0, then the element is processed with XSLT 1.0 behavior as described in 3.9.1 XSLT 1.0 Compatibility Mode.
If the effective version is equal to 2.0, then the element is processed with XSLT 2.0 behavior as described in 3.9.2 XSLT 2.0 Compatibility Mode.
If the effective version is equal to 3.0, then the element is processed with XSLT 3.0 behavior as described in 3.9.3 XSLT 3.0 Compatibility Mode.
If the effective version is any other value less than 4.0, the recommended action is to raise a static error; however, processors may recognize such values and process the element in an implementation-defined way.
Note:
XSLT 1.0 allowed the version
attribute to take any decimal
value, and invoked forwards compatible processing for any value other than
1.0. XSLT 2.0 allowed the attribute to take any decimal value, and invoked
backwards compatible (i.e. 1.0-compatible) processing for any value less
than 2.0. Some stylesheets may therefore be encountered that use values
other than 1.0 or 2.0. In particular, the value 1.1 is sometimes
encountered, as it was used at one stage in a draft language proposal.
It is implementation-defined whether a particular XSLT 4.0 implementation supports backwards compatible behavior for any XSLT version earlier than XSLT 4.0.
[ERR XTDE0160] It is a dynamic error if an element has an effective version of V (with V < 4.0) when the implementation does not support backwards compatible behavior for XSLT version V.
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 4.0 processor are identical to the effects of processing the same stylesheet using a processor for an earlier version of XSLT. 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 4.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 4.0 and XPath 4.0 specifications, it is not defined by reference to earlier versions of the XSLT and XPath specifications.
To write a stylesheet that makes use of features that
are new in version N, while also working with a processor that only
supports XSLT version M (M < N),
it is necessary to understand both the rules for backwards compatible behavior in
XSLT version N, and the rules for
forwards compatible behavior in XSLT version
M. If the xsl:stylesheet
element
specifies a version
attribute with a value greater than 1.0, then an XSLT 1.0
processor will ignore
declarations that were not defined in XSLT
1.0, for example xsl:function
,
xsl:import-schema
,
and xsl:mode
. If any new XSLT
4.0 instructions are used (for example xsl:switch
or xsl:array
), or if new XPath
4.0 features are used (for example, keyword arguments in function calls),
then the stylesheet must provide
fallback behavior that relies only on facilities available in the earliest XSLT version supported. 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.
[Definition: An element in the stylesheet is processed with XSLT 1.0 behavior if its effective version is equal to 1.0.]
In this mode, if any attribute contains an XPath expression, then the expression is evaluated with XPath 1.0 compatibility mode set to
true
. For details of this mode, see Section 2.2.1 Static ContextXP40. Expressions contained in
text value templates are
always evaluated with XPath 1.0
compatibility mode set to false
, since this construct
was not available in XSLT 1.0.
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 25.1 Extension Functions.
Note:
This might appear to contradict the specification of XPath 3.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 XSLT 1.0 compatibility mode is enabled. This is described separately for each such construct.
Processing an instruction with XSLT 1.0 behavior is not compatible with streaming. More specifically, and notwithstanding anything stated in 19 Streamability, an instruction that is processed with XSLT 1.0 behavior is roaming and free-ranging, which has the effect that any construct containing such an instruction is not guaranteed-streamable.
[Definition: An element is processed with XSLT 2.0 behavior if its effective version is equal to 2.0.]
In this specification, no differences are defined for XSLT 2.0 behavior. An XSLT 4.0 processor will therefore produce the same results whether the effective version of an element is set to 2.0 or 4.0.
Note:
An XSLT 2.0 processor, by contrast, will in some cases produce different
results in the two cases. For example, if the stylesheet contains an
xsl:switch
instruction with an
xsl:fallback
child, an XSLT 4.0 processor will process the
xsl:switch
instruction regardless whether the effective
version is 2.0, 3.0, or 4.0, while an
XSLT 2.0 processor will raise a static error
if the effective version is 2.0, and will take the fallback action if the
effective version is 3.0 or 4.0.
[Definition: An element is processed with XSLT 3.0 behavior if its effective version is equal to 3.0.]
In this specification, no differences are defined for XSLT 3.0 behavior. An XSLT 4.0 processor will therefore produce the same results whether the effective version of an element is set to 3.0 or 4.0.
Note:
An XSLT 3.0 processor, by contrast, will in some cases produce different
results in the two cases. For example, if the stylesheet contains an
xsl:switch
instruction with an
xsl:fallback
child, an XSLT 4.0 processor will process the
xsl:switch
instruction regardless whether the effective
version is 2.0, 3.0, or 4.0, while an
XSLT 3.0 processor will raise a static error
if the effective version is 2.0 or 3.0, and will take the fallback action if the
effective version is 4.0.
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 4.0, while retaining the ability to execute the stylesheet with an XSLT 4.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.13.3 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 4.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 is processed with forwards compatible behavior if its effective version is greater than 4.0.]
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.
When an element is processed with forwards compatible behavior:
If the element is in the XSLT namespace and appears as a child of the
xsl:stylesheet
element, and XSLT 4.0 does not allow the element
to appear as a child of the
xsl:stylesheet
element, then the element and its content
must be ignored.
If the element has an attribute that XSLT 4.0 does not allow the element to have, then the attribute must be ignored.
If the element is in the XSLT namespace and appears as a child of an element whose content model requires a sequence constructor, and XSLT 4.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 raised 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 4.0 instructions.
If the element has no xsl:fallback
children, then a
static error is raised in the same way as if forwards compatible
behavior were not enabled.
For example, an XSLT 4.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 4.0, then the stylesheet can use an
xsl:message
element with terminate="yes"
(see
24.1 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>
Note:
The XSLT 1.0 and XSLT 2.0 specifications did not anticipate the
introduction of the xsl:package
element. An XSLT 1.0 or 2.0
processor encountering this element will raise a static error, regardless of the
version
setting.
This problem can be circumvented by using the simplified package
syntax (whereby an
xsl:stylesheet
element is implicitly treated as
xsl:package
), or by writing the stylesheet code in
a separate module from the package manifest, and using the separate module as the
version of the stylesheet that is presented to a 2.0 processor.
For an XSLT 4.0 processor, the effective version of an
xsl:fallback
element that has no explicit version
attribute
is 4.0: more generally, it is the version of XSLT supported by the processor.
This rule is designed to ensure that the xsl:fallback
element
itself is not processed with forwards compatible behavior,
which would be pointless since the whole purpose of the instruction is to provide
code that can be evaluated with an earlier version of XSLT.
Note:
This rule was not present in earlier versions of this specification.
On a strict reading of the XSLT 3.0 specification, for example, an xsl:fallback
instruction with no version
attribute is evaluated with forwards compatible
behavior. This means, for example, that if the stylesheet author writes
<xsl:fallback select="42"/>
(which is incorrect, because
the instruction does not define a select
attribute) then the select
attribute will simply be ignored.
Stylesheet authors can prevent this problem by adding an explicit
version
attribute to xsl:fallback
indicating the version
of XSLT that is needed to evaluate the fallback code.
This specification cannot retrospectively dictate what XSLT 3.0 (or earlier)
processors should do; however, developers of such processors are encouraged to adopt
this rule, so that in an XSLT 4.0 stylesheet, an xsl:fallback
instruction
that cannot be properly evaluated by an XSLT 3.0 processor is rejected rather than
being silently ignored.
XSLT provides two mechanisms to construct a package 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 reference, it is resolved as described in 5.9 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 must be either a standard stylesheet module or a simplified stylesheet. It must not be a package manifest. If it is a simplified stylesheet module then it is transformed into the equivalent standard stylesheet module by applying the transformation described in 3.8 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.
Note:
It is appropriate to use this error code when the resource cannot be retrieved, or when the retrieved resource is not well formed XML. If the resource contains XML that can be parsed but that violates the rules for stylesheet modules, then a more specific error code may be more appropriate.
Duplicate xsl:include
declarations within a stylesheet level are
now ignored, preventing spurious errors caused by the presence of duplicate named components.
[Issue 1449 17 September 2024]
<!-- Category: declaration -->
<xsl:include
href = uri />
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.11.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.]
Note:
A stylesheet level thus groups the declarations in a package by import precedence: two declarations within a package are in the same stylesheet level if and only if they have the same import precedence.
[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.
If two or more xsl:include
declarations within the same stylesheet level
reference the same absolute URI, or reference different absolute URIs that are known to refer
to the same resource, then the duplicate xsl:include
declarations, other than the
first in declaration order, are ignored. Similarly, an xsl:include
declaration that references the top-level stylesheet module within its stylesheet level is ignored.
Note:
The above rule is new in XSLT 4.0. It can prevent the unwanted errors that can
occur when assembling a stylesheet from multiple modules, where each module declares its
dependencies using potentially redundant, and potentially circular xsl:include
declarations.
In XSLT 3.0 and earlier versions, including the same module more than once would usually lead to errors caused by duplicate definitions of components such as global variables, named templates, or functions. In the rare case where the included module only contains template rules, the new rule could potentially cause a backwards incompatibility. However, it is very unlikely that a stylesheet author would do this intentionally.
The new rule does not apply when multiple xsl:include
declarations for the
same module appear in different stylesheet levels,
that is, at different import precedences.
<!-- Category: declaration -->
<xsl:import
href = uri />
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.11.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.11.1 Locating Stylesheet Modules.
[ERR XTSE0190] An xsl:import
element must be a top-level element.
xsl:import
For example,
<xsl:stylesheet version="3.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:
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 references itself via a chain
of xsl:include
and xsl:import
declarations that contains at least one xsl:import
.
Note:
Under the new XSLT 4.0 rules, a cyclic reference that involves
xsl:include
only is ignored. A cycle involving
xsl:import
cannot be ignored, because it makes it
impossible to determine which declarations have the highest
import precedence.
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 Accessor
DM30. This property will typically be set if
the attribute is defined in a DTD as being of type ID
, or if it 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
endorsed in respect of the media type application/xml
by [RFC7303].
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 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="3.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 is the officially
registered media type for XSLT: see 3.3 XSLT Media Type. However,
browsers developed before this media type was registered are more likely to accept
the unofficial designation 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.
This specification provides three features that cause the raw stylesheet to be preprocessed as the first stage of static processing:
Whitespace and commentary are stripped (see 3.13.1 Stripping Whitespace and Commentary from the Stylesheet).
Elements
may be conditionally included or excluded by means of an [xsl:]use-when
attribute as described in 3.13.3 Conditional Element Inclusion.
Attributes may be conditionally computed as described in 3.13.4 Shadow Attributes.
Note that many of the rules affecting the validity of stylesheet documents apply to a stylesheet after this preprocessing phase has been carried out.
The tree representing the stylesheet is preprocessed as follows:
All comments and processing instructions are removed.
All xsl:note
elements are removed, together with their content
(see 3.13.2 The xsl:note element).
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:accumulator
xsl:analyze-string
xsl:apply-imports
xsl:apply-templates
xsl:attribute-set
xsl:call-template
xsl:character-map
xsl:choose
xsl:evaluate
xsl:fork
xsl:merge
xsl:merge-source
xsl:mode
xsl:next-iteration
xsl:next-match
xsl:override
xsl:package
xsl:stylesheet
xsl:switch
xsl:transform
xsl:use-package
Any whitespace text node whose
immediate following-sibling node is an xsl:param
or
xsl:sort
or xsl:context-item
or
xsl:on-completion
element is removed from the
tree, regardless of any xml:space
attributes.
Any whitespace text
node whose immediate preceding-sibling node is an
xsl:catch
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 whitespace text nodes in that part of the
stylesheet to be copied to the result of the sequence constructor.
When the result of the sequence constructor is used to form the content of an
element, this can cause errors if such text nodes are followed by attribute nodes
generated using xsl:attribute
.
Note:
If an xml:space
attribute is specified on a literal result element, it will be
copied to the result tree in the same way as any other attribute.
xsl:note
elementAn xsl:note
element may appear anywhere in the stylesheet, except as the outermost element.
<xsl:note
#any#? = string >
<!-- Content: any -->
</xsl:note>
The element may have any attributes and any children, subject only to rules imposed by
other specifications such as the XML specification. The XSLT processor discards xsl:note
elements at an early stage of processing, without performing any validation, as described
in 3.13.1 Stripping Whitespace and Commentary from the Stylesheet.
An xsl:note
element is typically used for documentation. The format of this documentation
is not prescribed here: it might be free text, or XHTML, or some custom vocabulary understood by a free-standing
documentation generator.
An xsl:note
element might also be used for “commenting out” XSLT declarations or instructions.
Note:
A number of documentation processors have been produced for use with XSLT, and the general convention has been to use user-defined data elements for this purpose. This approach has its drawbacks:
Annotations can only appear at the top level of the stylesheet (between declarations, but not within declarations). Extension instructions can also potentially be used as annotations, but this abuses their intended purpose and may create an unwanted dependency on a specific processor.
Annotations require a custom namespace to be declared, typically on the xsl:stylesheet
element, and this namespace becomes part of the static context for all expressions within the stylesheet,
thus changing (if only very slightly) the semantics of the stylesheet code. This is true even
if the namespace is excluded from the result tree by means of an [xsl:]exclude-result-prefixes
attribute.
Implementations must not interpret the contents of an xsl:note
element
to modify the behavior of the stylesheet in any way, whether or not the resulting behavior remains conformant
with this specification.
Note:
For example, xsl:note
elements must not be used to provide processor-specific performance
hints. There are better mechanisms for this, such as user-defined data elements
and extension attributes.
Any element in the XSLT namespace may have a use-when
attribute whose
value is an XPath expression that can be evaluated statically.
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 attribute is
present and the effective boolean
valueXP40 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 raised 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 raised
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
.
If the xsl:package
,
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 3.13.1 Stripping Whitespace and Commentary from the Stylesheet.
The XPath expression used as the value of the
xsl:use-when
attribute follows the rules for static expressions, including the rules for handling errors.
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 raises 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'"/>
When a no-namespace attribute name N is permitted to appear on an element in the XSLT namespace (provided that N does not start with an underscore), then a value V can be supplied for N in one of two ways:
The conventional way is for an attribute node with name N and value V to appear in the XDM representation of the element node in the stylesheet tree.
As an alternative, a shadow attribute may be supplied allowing the value V to be statically computed during the preprocessing phase. The shadow attribute has a name that is the same as the name N prefixed with an underscore, and the value of the shadow attribute is a value template in which all expressions enclosed between curly braces must be static expressions. The value V is the result of evaluating the value template. If a shadow attribute is present, then any attribute node with name N (sharing the same parent element) is ignored.
For example, an xsl:include
element might be written:
<xsl:include _href="common{ $VERSION }.xsl"/>
allowing the stylesheet to include a specific version of a library module based on the value of a static parameter.
Similarly, a mode might be declared like this:
<xsl:param name="streamable" as="xs:boolean" required="yes" static="yes"/> <xsl:mode _streamable="{ $streamable }" on-no-match="shallow-skip"/>
this allowing the streamability of the mode to be controlled using a static parameter
(Note: this example relies on the fact that the
streamable
attribute accepts a boolean value, which means that
the values true
and false
are accepted as synonyms of
yes
and no
).
This mechanism applies to all attributes in the stylesheet where the attribute
name is in no namespace and the name of the parent element is in the XSLT namespace. This includes attributes that have static
significance such as the use-when
attribute, the version
attribute, and the static
attribute on xsl:variable
.
The mechanism does not apply to shadow attributes (that is, it is not possible to
invoke two stages of preprocessing by using two leading underscores). It does not
apply to attributes of literal result elements, nor to attributes in a namespace
such as the XML or XSLT namespace, nor to namespace declarations.
Note:
If a shadow attribute and its corresponding target attribute are both present in the stylesheet, the non-shadow attribute is ignored. This may be useful to make stylesheet code compatible across XSLT versions; an XSLT 2.0 processor operating in forwards compatible mode will ignore shadow attributes, and will require the target attribute to be valid.
Note:
The statement that the non-shadow attribute is ignored extends to error detection: it is not an error if the non-shadow attribute has an invalid value. However, this is not reflected in the schema for XSLT stylesheets, so validation using this schema may raise errors in such cases.
Note:
An attribute whose name begins with an underscore is treated specially only when it appears on an element in the XSLT namespace. On a literal result element, it is treated in the same way as any other attribute (that is, its effective value is copied to the result tree). On an extension instruction or user-defined data element, as with other attributes on these elements, its meaning is entirely implementation-defined.
Although it is not usually considered good practice, it sometimes happens that variants or versions of an XML vocabulary exist in which the same local names are used, but in different namespaces. There is then a requirement to write code that will process source documents in a variety of different namespaces.
It is possible to define a static stylesheet parameter containing the target namespace, for example:
<xsl:param name="NS" as="xs:string" static="yes" select="'http://example.com/ns/one'"/>
And this can then be used to set the default namespace for XPath expressions:
_xpath-default-namespace="{ $NS }"
However, it is not possible to put this shadow attribute on the
xsl:stylesheet
or xsl:package
element of
the principal stylesheet module, because at that point the variable
$NS
is not in scope. A workaround is to create a stub
stylesheet module which contains nothing but the static parameter declaration
and an xsl:include
of the stylesheet module containing the
real logic. The static stylesheet parameter will then be in scope on the
xsl:stylesheet
element of the included stylesheet module,
and the shadow attribute _xpath-default-namespace="{ $NS }"
can
therefore appear on this xsl:stylesheet
element.
The following stylesheet produces a report giving information about selected employees. The predicate defining which employees are to be included in the report is supplied (as a string containing an XPath expression) in a static stylesheet parameter:
<xsl:param name="filter" static="yes" as="xs:string" select="'true()'"/> <xsl:function name="local:filter" as="xs:boolean"> <xsl:param name="e" as="element(employee)"/> <xsl:sequence _select="$e/({ $filter })"/> </xsl:function> <xsl:template match="/"> <report> <xsl:apply-templates mode="report" select="//employee[local:filter(.)]"/> </report> </xsl:template>
If the supplied value of the filter parameter is, say location =
"UK"
, then the report will cover employees based in the UK.
Note:
The stylesheet function local:filter
is used here in preference
to direct use of the supplied predicate within the select
attribute of the xsl:apply-templates
instruction because it
reduces exposure to code injection attacks. It does not necessarily
eliminate all such risks, however. For example, it would be possible for a
caller to supply an expression that never terminates, thus creating a
denial-of-service risk.
Every XSLT 4.0 processor includes the following named type definitions in the in-scope schema components:
All built-in types defined in [XML Schema Part 2], including xs:anyType
and
xs:anySimpleType
.
The following types defined in [XPath 3.0]:
xs:yearMonthDuration
, xs:dayTimeDuration
,
xs:anyAtomicType
, xs:untyped
, and
xs:untypedAtomic
.
XSLT 4.0 processors may optionally include types
defined in XSD 1.1 (see [XML Schema 1.1 Part 1]). XSD 1.1 adopts the types
xs:yearMonthDuration
, xs:dayTimeDuration
, and
xs:anyAtomicType
previously defined in XPath 2.0, and adds one new
type: xs:dateTimeStamp
. XSD 1.1 also allows implementers to define
additional primitive types, and XSLT 4.0 permits such types to be supported by an
XSLT processor.
A schema-aware XSLT processor additionally supports:
User-defined types, and element and attribute declarations, that are imported
using an xsl:import-schema
declaration as described in
3.15 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 Schema Documents or the
Schema for Schema Documents (Datatypes). The Schema for Schema Documents, as well
as defining built-in types such as xs:integer
and
xs:double
, also defines types that are intended for use only
within that schema, such as xs:derivationControl
. A stylesheet that is designed to process XML Schema
documents as its input or output may import the Schema for Schema Documents.
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 25.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.
The rules concerning the compatibility of schemas imported by different packages have been clarified. It is now explicitly stated that instructions that trigger validation must use the imported schema of the package in which validation is invoked. This differs from the current practice of some XSLT 3.0 processors, which may use (for example) a schema formed from the union of the imported schemas in all packages. [Issue 451 PR 635 24 October 2023]
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 28 Conformance.
<!-- Category: declaration -->
<xsl:import-schema
namespace? = uri
schema-location? = uri >
<!-- 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.14 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 package, 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 within the declaring package; importing components in one stylesheet module makes them available throughout the package.
The schema components imported into different packages within a stylesheet must be compatibleDM40. Specifically, it is not permitted to use the same name in the same XSD symbol space to refer to different schema components within different packages; and the union of the schema components imported into the packages of a stylesheet must constitute a valid schema (as well as the set of schema components imported into each package forming a valid schema in its own right).
Note:
The fact that the schemas used in different packages must be compatible does not mean they must be identical. There are circumstances where validating an element using one schema might produce a different outcome from validation with a different schema, despite these consistency rules: an example is where the two schemas define different membership for a substitution group.
Nevertheless, the consistency rules are strong enough to ensure that an element
node validated using one schema can safely be passed to a function declared in another
package, where the function declares the required
type of an argument as (say) element(*, T)
.
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 one of the following must be true:
the namespace
attribute of the xsl:import-schema
element and the targetNamespace
attribute of the
xs:schema
element are both absent (indicating a no-namespace
schema), or
the namespace
attribute of the xsl:import-schema
element and the targetNamespace
attribute of the
xs:schema
element are both present and both have the same
value, or
the namespace
attribute of the xsl:import-schema
element is absent and the targetNamespace
attribute of the
xs:schema
element is present, in which case the target
namespace is as given on the xs:schema
element.
[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://example.com/ns/yes-no"
<xsl:import-schema> <xs:schema targetNamespace="http://example.com/ns/yes-no" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:local="http://example.com/ns/yes-no"> <xs:simpleType name="yes-no"> <xs:restriction base="xs:string"> <xs:enumeration value="yes"/> <xs:enumeration value="no"/> </xs:restriction> </xs:simpleType> </xs:schema> </xsl:import-schema> <xsl:variable name="condition" select="local:yes-no('yes')" as="local:yes-no"/>
There are two built-in functions
(analyze-string
FO40 and json-to-xml
) whose
result is an XML structure for which a schema is defined. The namespace for these
schema definitions is (in both cases) http://www.w3.org/2005/xpath-functions
. Schema
components for these namespaces are available for reference within the stylesheet if
and only if an xsl:import-schema
declaration is present referencing
this namespace. If such a declaration is present, then the schema that is
imported is the schema defined in the specification of these functions: the schemaLocation
attribute has no effect.
The data model used by XSLT is the XPath 3.0 and XQuery 3.0 data model (XDM), as defined in [XDM 3.0]. 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 3.13.1 Stripping Whitespace and Commentary from the Stylesheet and 4.3.2 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, U+0009 (TAB) , U+000A (NEWLINE) , U+000D (CARRIAGE RETURN) , or U+0020 (SPACE) ).]
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 [XDM 3.0] is capable of representing either an XML 1.0 document (conforming to [XML 1.0] and [Namespaces in XML]) 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 4.0 can be used with either of these XML versions.
Construction of the XDM tree is outside the scope of this specification, so XSLT 4.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 27 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 4.0 and XPath 3.0, for example the productions CharXML and NCNameNames, 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 (and, indeed, between different editions of XML 1.0). Implementations may support any version; it is recommended that an XSLT 4.0 processor that implements the 1.1 versions should also provide a mode that supports the 1.0 versions. It is thus implementation-defined which versions and editions of XML and XML Namespaces are supported by the implementation.
Note:
The specification referenced as [Namespaces in XML] was actually published without a version number.
The current version of [XML Schema 1.1 Part 2] references the XML 1.1 specifications, but the previous version ([XML Schema Part 2]) (that is, XSD 1.0) remains in widespread use, and only
references XML 1.0. With processors lacking support for XSD 1.1,
therefore, datatypes such as xs:NCName
and xs:ID
may be
constrained by the XML 1.0 rules, and not allow the full range of values permitted by
XML 1.1. It is recommended that implementers wishing to support
XML 1.1 should consult [XML Schema 1.0 and XML 1.1] for guidance.
XSLT 4.0 requires a processor to support XDM 3.1 as defined in [XDM 3.1].
A processor may also provide a user option to support versions of XDM later than 3.1, in which case the way it does so is implementation-defined.
Source documents supplied as input to a transformation may be subject to preprocessing. Two kinds of preprocessing are defined: stripping of type annotations (see 4.3.1 Stripping Type Annotations from a Source Tree), and stripping of whitespace text nodes (see 4.3.2 Stripping Whitespace from a Source Tree).
Stripping of type annotations happens before stripping of whitespace text nodes.
The source documents to which this applies are as follows:
The document containing the global context item if it is a node;
Any documents containing a node present in the initial match selection;
Any document containing a node that is returned by the functions document
, doc
FO40,
or collection
FO40;
Any document read using xsl:source-document
.
Note:
This list excludes documents passed as the values of
stylesheet parameters or parameters
of the initial named template or initial function,
trees created by functions such as parse-xml
FO40, parse-xml-fragment
,
analyze-string
FO40, or json-to-xml
,
and values returned from extension
functions.
If a node other than a document node is supplied (for example as the global context item),
then the preprocessing is applied to the entire document containing that node. If several nodes within the same
document are supplied (for example as nodes in the initial match selection, or as nodes returned by the
collection
FO40 function), then the preprocessing is only applied to that document once.
If a whitespace text node is supplied (for example as the global context item) and the rules cause this node
to be stripped from its containing tree, then the behavior is as if this node had not been supplied
(which may cause an error, for example if a global context item is required.)
The rules determining whether or not stripping of annotations and/or whitespace
happens are defined at the level of a package. Declarations within a library package
only affect the handling of documents loaded using a call on the document
, doc
FO40,
or collection
FO40 functions or an evaluation of an xsl:source-document
instruction
appearing lexically within the same package. Declarations within the top-level package also affect the processing
of the global context item and the initial match selection.
The semantics of the document
, doc
FO40,
and collection
FO40 functions are formally defined in terms of mappings from URIs to document nodes
maintained within the dynamic context (see 5.3.3 Initializing the Dynamic Context). The effect of the
declarations that control stripping of type annotations
and whitespace is therefore to modify this mapping (so it now maps the URI to a stripped document). The modification
applies to the dynamic context for calls to these function appearing within a particular package; each package therefore
has a different set of mappings. This means that when two calls to the doc
FO40 function appear in
different packages, specifying the same absolute URI, then in general different documents are returned. An implementation
may return the same document for two such calls if it is able to determine that the effect of the annotation
and whitespace stripping rules in both packages is the same.
The effect of dynamic calls to the document
, doc
FO40,
and collection
FO40 functions is defined in the same way as for other functions with dependencies on
the dynamic context. As described in 5.3.4 Additional Dynamic Context Components used by XSLT, named function references
(such as doc#1
) and calls on function-lookup
FO40 (for example, function-lookup("doc", 1)
)
are defined to retain the XPath static and dynamic context at the point of invocation as part of the closure of the
resulting function item, and to use this preserved context when a dynamic function call is subsequently made using the function item.
[Definition: The term type
annotation is used in this specification to refer to the value returned
by the dm:type-name
accessor of a node: see Section
5.14 type-name Accessor
DM30.]
There is sometimes a requirement to write stylesheets that produce the same results
whether or not the source documents have been validated against a schema. To achieve
this, an option is provided to remove any type
annotations on element and attribute nodes in a source tree, replacing them with an annotation of
xs:untyped
in the case of element nodes, and
xs:untypedAtomic
in the case of attribute nodes.
Such stripping of type annotations can be
requested by specifying input-type-annotations="strip"
on the xsl:package
element. This
attribute has three permitted values: strip
, preserve
, and
unspecified
. The default value is unspecified
.
Specifying unspecified
has the same effect
as omitting the attribute [XSLT 3.0 Erratum E43, bug 30383].
The input-type-annotations
attribute may also
be specified on the xsl:stylesheet
element; if it is specified at
this level then it must be consistent for all stylesheet modules within the same
package.
[ERR XTSE0265] It is a static error if there is a
stylesheet module in a
package that specifies
input-type-annotations="strip"
and another stylesheet module that specifies
input-type-annotations="preserve"
, or if a stylesheet module specifies the value
strip
or preserve
and the same value is not
specified on the xsl:package
element of the containing
package.
Type annotations are stripped from relevant source documents if
at least one stylesheet module in the stylesheet
specifies input-type-annotations="strip"
on the xsl:package
,
xsl:stylesheet
, or xsl:transform
element [XSLT 3.0 Erratum E43, bug 30383].
When type annotations are stripped, the following changes are made to the source tree:
The type annotation of every element node is changed to xs:untyped
The type annotation of every attribute node is changed to
xs:untypedAtomic
The typed value of every element and attribute node is set to be the same as
its string value, as an instance of xs:untypedAtomic
.
The is-nilled
property of every element node is set to
false
.
The values of the is-id
and is-idrefs
properties are not
changed.
Note:
Stripping type annotations does not
necessarily return the document to the state it would be in had validation not
taken place. In particular, any defaulted elements and attributes that were added
to the tree by the validation process will still be present, and elements and
attributes validated as IDs will still be accessible using the
id
FO40 function.
A source tree supplied as input to the transformation process may contain whitespace text nodes that are of no interest, and that do not need to be retained by the transformation. Conceptually, an XSLT processor makes a copy of the source tree from which unwanted whitespace text nodes have been removed. This process is referred to as whitespace stripping.
The stripping process takes as input a set of element names whose child whitespace text nodes are to be preserved.
The way in which this set of element names is established using the
xsl:strip-space
and xsl:preserve-space
declarations is described later in this section.
The stripping process that applies for a particular
package is determined by the xsl:strip-space
and xsl:preserve-space
declarations within that package.
A whitespace text node is preserved if either of the following apply:
The element name of the parent of the text node is in the set of whitespace-preserving element names.
An ancestor element of the text node has an xml:space
attribute
with a value of preserve
, and no closer ancestor element has
xml:space
with a value of default
.
Otherwise, the whitespace text node is stripped.
The xml:space
attributes are not removed from the tree.
<!-- Category: declaration -->
<xsl:strip-space
elements = tokens />
<!-- Category: declaration -->
<xsl:preserve-space
elements = tokens />
The set of whitespace-preserving element names is specified by
xsl:strip-space
and xsl:preserve-space
declarations. Whether an element name is
included in the set of whitespace-preserving names is determined by the best match
among all the xsl:strip-space
or xsl:preserve-space
declarations: it is included if and only if there is no match or the best match is an
xsl:preserve-space
element. The xsl:strip-space
and xsl:preserve-space
elements each have an elements
attribute whose value is a whitespace-separated list of NameTestsXP40; an element name matches an
xsl:strip-space
or xsl:preserve-space
element if
it matches one of the NameTestsXP40.
An element matches a NameTestXP40 if
and only if the NameTestXP40 would be
true for the element as an XPath node test.
[ERR XTSE0270] It is a static error if within any package the same NameTestXP40 appears in both an
xsl:strip-space
and an xsl:preserve-space
declaration if both have the same import
precedence. Two NameTests are considered the same if they match
the same set of names (which can be determined by comparing them after
expanding namespace prefixes to URIs).
Otherwise, when more than one
xsl:strip-space
and xsl:preserve-space
element
within the relevant package matches, the best matching element is determined by
the best matching NameTestXP40.
The rules are similar to those for
template rules:
First, any match with lower import precedence than another match is ignored.
Next, any match that has a lower default priority than the default priority of another match is ignored.
If several matches have the same default priority (which can only happen
if one of the NameTests takes the form *:local
and the other takes
the form prefix:*
), then the declaration that appears last in
declaration order is used.
If an element in a source document has a type
annotation that is a simple type or a complex type with simple content,
then any whitespace text nodes among its children are preserved, regardless of any
xsl:strip-space
declarations. The reason for this is that
stripping a whitespace text node from an element with simple content could make the
element invalid: for example, it could cause the minLength
facet to be
violated.
Stripping of type annotations happens
before stripping of whitespace text nodes, so this situation will not occur if
input-type-annotations="strip"
is specified.
Note:
In [XDM 3.0], processes are described for constructing an
XDM tree from an Infoset or from a PSVI. Those processes deal with whitespace
according to their own rules, and the provisions in this section apply to the
resulting tree. In practice this means that elements that are defined in a DTD or
a Schema to contain element-only content will have whitespace text nodes stripped,
regardless of the xsl:strip-space
and
xsl:preserve-space
declarations in the stylesheet.
However, source trees are not necessarily constructed using those processes; indeed, they are not necessarily constructed by parsing XML documents. Nothing in the XSLT specification constrains how the source tree is constructed, or what happens to whitespace text nodes during its construction. The provisions in this section relate only to whitespace text nodes that are present in the tree supplied as input to the XSLT processor. The XSLT processor cannot preserve whitespace text nodes unless they were actually present in the supplied tree.
The mapping from the Infoset to the XDM data model, described in [XDM 3.0], does not retain attribute types. This means, for
example, that an attribute described in the DTD as having attribute type
NMTOKENS
will be annotated in the XDM tree as
xs:untypedAtomic
rather than xs:NMTOKENS
, and its typed
value will consist of a single xs:untypedAtomic
item rather than a
sequence of xs:NMTOKEN
items.
Attributes with a DTD-derived type of ID, IDREF, or IDREFS will be marked in the XDM
tree as having the is-id
or is-idrefs
properties. It is
these properties, rather than any type
annotation, that are examined by the functions id
FO40
and idref
FO40 described in [Functions and Operators 4.0].
The data model for nodes in a document that is being streamed is no different from the standard XDM data model, in that it contains the same objects (nodes) with the same properties and relationships. The facilities for streaming do not change the data model; instead they impose rules that limit the ability of stylesheets to navigate the data model.
A useful way to visualize streaming is to suppose that at any point in time, there is a current position in the streamed input document which may be the start or end of the document, the start or end tag of an element, or a text, comment, or processing instruction node. From this position, the stylesheet has access to the following information:
Properties intrinsic to the node, such as its name, its base URI, its type
annotation, and its is-id
and is-idref
properties.
The ancestors of the node (but navigation downwards from the ancestors is not permitted).
The attributes of the node, and the attributes of its ancestors. For each such attribute, all the properties of the node including its string value and typed value are available, but there are limitations that restrict navigation from the attribute node to other nodes in the document.
The in-scope namespace bindings of the node.
In the case of attributes, text nodes, comments, and processing instructions, the string value and typed value of the node.
In the case of element nodes, whether or not the element has children. This
information is obtained by calling the has-children
FO40
function. This implies that the processor performs look-ahead (limited to a
single token) to determine whether the start tag is immediately followed by a
matching end tag.
In the case of document nodes, details of unparsed entities in the document.
This information is obtained by calling the
unparsed-entity-uri
and
unparsed-entity-public-id
functions. A processor might
enable this by reading the DTD as soon as the document is opened. Since
comments and processing instructions that precede the DOCTYPE declaration are
available as children of the document node, this also implies that a streaming
processor needs sufficient memory to hold these comments and processing
instructions until the start tag of the first element is encountered.
Information about unparsed entities remains available for the duration of
processing, in the same way as attributes of ancestor elements.
The children and other descendants of a node are not accessible except as a by-product of changing the current position in the document. The same applies to properties of an element or document node that require examination of the node’s descendants, that is, the string value and typed value. This is enforced by means of a rule that only one expression requiring downward navigation from a node is permitted.
Information about the type of a node is in general
considered a property intrinsic to the node, and is available without advancing the
input stream. There is an exception for an expression of the form (/) instance
of document-node(element(invoice))
. This is not guaranteed streamable,
because it requires reading ahead to check that the document node has only one
element child. However, a processor that knows that the parser delivering the
document stream is only capable of delivering well-formed documents may use this
knowledge (along with the limited look-ahead needed to get the name of the outermost
element) to make this expression streamable.
A streaming processor is not required to read any more of the source document than is needed to generate correct stylesheet output. It is not required to read the full source document merely in order to satisfy the requirement imposed by the XML Recommendation that an XML Processor must report violations of well-formedness in the input.
More detailed rules are defined in 19 Streamability.
Maps and arrays were defined in XPath 3.1.
Streaming facilities in this specification are, for the most part, relevant only to streamed processing of XML trees, and not to other structures such as sequences, maps and arrays, which will typically be held in memory unless the processor is capable of avoiding this.
Maps, however, play an important role in enabling streamed applications
to be written. For example, a map can be used as the data structure maintained
by an accumulator (see 18.2 Accumulators) to remember information
that has been retrieved from a streamed document, given that it is not possible to
revisit the same nodes later. There is also a special streamability rule for
map constructor expressions (see 21.3 Maps and Streaming) that allows
such an expression to make multiple downward selections in the streamed input
document: for example one can write { 'authors': data(author), 'editors': data(editor) }
,
which gathers the values of these two elements, or sets of elements, from the input
stream, regardless what order they appear in — even if they are interleaved.
The rules for creating maps and arrays are designed to ensure that the entries in a map, and the members of an array, cannot contain nodes from a streamed document. This is achieved by the way in which the streamability properties of the relevant expressions and functions are defined.
By contrast, sequences can and often do contain nodes from streamed documents, and a major purpose of the rules for streamability is to make this possible.
The XDM data model (see [XDM 3.0]) leaves it to the host language to define limits. This section describes the limits that apply to XSLT.
Limits on some primitive datatypes are defined in [XML Schema Part 2]. Other limits, listed below, are implementation-defined. Note that this does not necessarily mean that each limit must be a simple constant: it may vary depending on environmental factors such as available resources.
The following limits are implementation-defined:
For the xs:decimal
type, the maximum number of decimal digits (the
totalDigits
facet). This must be at least 18 digits. (Note,
however, that support for the full value range of xs:unsignedLong
requires 20 digits.)
For the types xs:date
, xs:time
,
xs:dateTime
, xs:gYear
, and
xs:gYearMonth
: the range of values of the year component, which
must be at least +0001 to +9999; and the maximum number of fractional second
digits, which must be at least 3.
For the xs:duration
type: the maximum absolute values of the
years, months, days, hours, minutes, and seconds components.
For the xs:yearMonthDuration
type: the maximum absolute value,
expressed as an integer number of months.
For the xs:dayTimeDuration
type: the maximum absolute value,
expressed as a decimal number of seconds.
For the types xs:string
, xs:hexBinary
,
xs:base64Binary
, xs:QName
, xs:anyURI
,
xs:NOTATION
, and types derived from them: the maximum length of
the value.
For sequences, the maximum number of items in a sequence.
For backwards compatibility reasons, XSLT 4.0
continues to support the disable-output-escaping
feature introduced in
XSLT 1.0. This is an optional feature and implementations are not
required to support it. A new facility, that of named character maps (see 27.3 Character Maps) was introduced in XSLT 2.0. It provides
similar capabilities to disable-output-escaping
, but without distorting
the data model.
If an implementation supports the
disable-output-escaping
attribute of xsl:text
and
xsl:value-of
, (see 27.5 Disabling Output Escaping),
then the data model for trees constructed by the processor is augmented with a boolean value representing the value of
this property. This boolean value, however, can be set only within a final result tree that is being passed to the
serializer.
Conceptually, each character in a text node on such a result tree has a boolean
property indicating whether the serializer is to disable the normal rules for
escaping of special characters (for example, outputting of &
as
&
) in respect of this character.
Note:
In practice, the nodes in a final result
tree will often be streamed directly from the XSLT processor to the
serializer. In such an implementation, disable-output-escaping
can be
viewed not so much a property stored with nodes in the tree, but rather as
additional information passed across the interface between the XSLT processor and
the serializer.
Many constructs appearing in a stylesheet, for example named templates, modes, and attribute sets, are named using a qualified name: this consists of a local name and an optional namespace URI.
In most cases where such names are written in a stylesheet, the syntax for expressing the name is given by the production EQNameXP40 in the XPath specification. In practice, this means that three forms are permitted:
A simple NCName
appearing on its own (without any prefix). This
represents the local name of the object. The interpretation of unprefixed
names is described below.
A lexical QName written in the
form NCName ":" NCName
where the first part is a namespace
prefix and the second part is the local name. The namespace part of the
object’s name is then derived from the prefix by examining the
applicable static namespaces
for the element node in the stylesheet where the
name appears.
A URIQualifiedNameXP40 in the form "Q{" URI? "}" NCName
where the two parts of the name, that is the namespace part and the local
part, both appear explicitly. If the URI part is omitted (for example
Q{}local
), the resulting expanded QName is a QName whose
namespace part is absent.
The rules for the use of these constructs generally permit leading and trailing whitespace, which is ignored.
Note:
There are a few places where the third form, a URIQualifiedName, is not
permitted. These include the name
attribute of
xsl:element
and xsl:attribute
(which have
a separate namespace
attribute for the purpose), and constructs
defined by other specifications. For example, names appearing within an
embedded xs:schema
element must follow the XSD rules.
[Definition: An expanded
QName is a value in the value space of the xs:QName
datatype as defined in the XDM data model (see [XDM 3.0]): that is, a triple containing namespace prefix (optional), namespace URI
(optional), and local name. Two expanded QNames are equal if the namespace URIs
are the same (or both absent) and the local names are the same. The prefix
plays no part in the comparison, but is used only if the expanded QName needs
to be converted back to a string.]
[Definition: An EQName is a string representing an expanded QName where the string, after removing leading and trailing whitespace, is in the form defined by the EQNameXP40 production in the XPath specification.]
[Definition: A lexical QName
is a string representing an expanded
QName where the string, after removing leading and trailing
whitespace, is within the lexical space of the xs:QName
datatype
as defined in XML Schema (see [XML Schema Part 2]): that is, a local
name optionally preceded by a namespace prefix and a colon.]
Note that every lexical QName is an EQName, but the converse is not true.
The following rules are used when interpreting a lexical QName:
[Definition: A string in the form of a lexical QName may occur as the value of an attribute node in a stylesheet module, or within an XPath expression contained in an attribute or text node within a stylesheet module, or as the result of evaluating an XPath expression contained in such a node. The element containing this attribute or text node is referred to as the defining element of the lexical QName.]
If the lexical QName has a prefix, then the prefix is expanded into a URI reference using the namespace declarations in effect on its defining element. The expanded QName consisting of the local part of the name and the possibly null URI reference is used as the name of the object. The default namespace of the defining element (see Section 6.2 Element Nodes DM30) is not used for unprefixed names.
[ERR XTSE0280] In the case of a prefixed lexical QName used as the value (or as part of the value) of an attribute in the stylesheet, or appearing within an XPath expression in the stylesheet, it is a static error if the defining element has no namespace node whose name matches the prefix of the lexical QName.
[ERR XTDE0290] Where the result of evaluating an XPath expression (or an attribute value template) is required to be a lexical QName, or if it is permitted to be a lexical QName and the actual value takes the form of a lexical QName, then unless otherwise specified it is a dynamic error if the value has a prefix and the defining element has no namespace node whose name matches that prefix. This error may be raised as a static error if the value of the expression can be determined statically.
If the lexical QName has no prefix, then:
In the case of an unprefixed QName used as a NameTest
within an XPath expression (see
5.2 Expressions), and in certain other contexts, the
namespace to be used in expanding the QName may be specified by means
of the [xsl:]xpath-default-namespace
attribute, as
specified in 5.1.2 Unprefixed Lexical QNames in Expressions and Patterns.
If the name is in one of the following categories, then the default namespace of the defining element is used:
Where a QName is used to define the name of an element being
constructed. This applies both to cases where the name is known
statically (that is, the name of a literal result element) and
to cases where it is computed dynamically (the value of the
name
attribute of the
xsl:element
instruction).
The default namespace is used when expanding the first argument
of the function element-available
.
The default namespace applies to any unqualified element names
appearing in the cdata-section-elements
or
suppress-indentation
attributes of
xsl:output
or
xsl:result-document
In all other cases, a lexical
QName with no prefix represents an expanded QName in no namespace
(that is, an xs:QName
value in which both the prefix and
the namespace URI are absent).
The attribute [xsl:]xpath-default-namespace
(see 3.4 Standard Attributes)
may be used on an element in the stylesheet to define the
namespace that will be used for an unprefixed element or type name within an XPath expression, and
in certain other contexts listed below.
The value of the attribute is either the namespace URI to be used, or a zero-length string,
or the value ##any
.
For any element in the stylesheet, this attribute has an effective value, which is the value of
the [xsl:]xpath-default-namespace
on that element or on the innermost containing
element that specifies such an attribute, or the zero-length string if no containing
element specifies such an attribute.
For any element in the stylesheet, the effective value of the attribute determines the value of the default namespace for elements and typesXP40 in the static context of any XPath expression contained in an attribute or text node of that element (including XPath expressions in attribute value templates and text value templates). The effect of this is specified in [XPath 4.0]; in summary, it determines the namespace used for any unprefixed type name or element name.
The special value ##any
only affects:
An unprefixed element name used in a
NameTestXP40,
either within an XPath expression or a pattern.
Its effect is that an unprefixed name matches any element having the required local name,
irrespective of the namespace URI (or lack of it). A pattern such as match="title"
is therefore interpreted as a wildcard match match="*:title
. The default priority
of such a pattern changes accordingly.
An unprefixed type name; the effect is to treat the name as
referring to a type whose namespace is http://www.w3.org/2001/XMLSchema
.
Note:
To take an example, older versions of the internet index of RFCs (requests for comments)
use the namespace URI http://www.rfc-editor.org/rfc-index
, while newer
versions use https://www.rfc-editor.org/rfc-index
(note the change of URI scheme).
XSLT code that needs to work with either version can be simplified by setting the
default namespace to ##any
: but be aware that this might lead to spurious matching
of names in an unrelated namespace.
Any other value of this attribute sets the default namespace for any of the following constructs appearing within its scope:
any unprefixed element name used in a pattern
any unprefixed element name used in the elements
attribute of
the xsl:strip-space
or xsl:preserve-space
instructions
any unprefixed element name used in the as
attribute of an XSLT element
any unprefixed type name used in the type
attribute of an
XSLT element
any unprefixed type name used in the xsl:type
attribute of a
literal result element.
The [xsl:]xpath-default-namespace
attribute must
be in the XSLT namespace if and only if
its parent element is not in the XSLT namespace.
If the effective value of the attribute is a zero-length string, which will be the case if it is explicitly set to a zero-length string or if it is not specified at all, then an unprefixed element name or type name refers to a name that is in no namespace. The default namespace of the parent element (see Section 6.2 Element Nodes DM30) is not used.
The attribute does not affect other names, for example function names,
variable names, or template names, or strings that are interpreted
as lexical QNames during stylesheet evaluation, such as the effective value
of the name attribute of xsl:element
or the string supplied as the first
argument to the key
function.
Unprefixed function names are treated as names in the standard function namespace.
For other unprefixed names, for example variable
names, template names, mode names, or strings that are interpreted as lexical QNames during stylesheet evaluation,
such as the effective value of the
name
attribute of xsl:element
or the string
supplied as the first argument to the key
function, any unprefixed
lexical QName is taken as being a no-namespace name.
[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.
Each of the reserved namespaces has a conventional
prefix. As described in 3.7.1 The fixed-namespaces Attribute, the fixed-namespaces
attribute may bind one of the reserved namespaces simply by referring to its conventional
prefix. For example, fixed-namespaces="xs"
has the effect of binding the prefix
xs
to the namespace http://www.w3.org/2001/XMLSchema
.
The XSLT namespace described in
3.1.1 XSLT Namespace, is reserved,
with conventional prefix xsl
.
[Definition: The standard function
namespace
http://www.w3.org/2005/xpath-functions
,
with conventional prefix fn
,
is used for functions
in the function library defined in [Functions and Operators 4.0] and
for standard functions defined in this specification.]
The namespace
http://www.w3.org/2005/xpath-functions/math
,
with conventional prefix math
,
is used for
mathematical functions in the function library defined in [Functions and Operators 3.0].
The namespace
http://www.w3.org/2005/xpath-functions/map
,
with conventional prefix map
,
is used for
functions defined in this specification relating to the manipulation of
maps.
The namespace
http://www.w3.org/2005/xpath-functions/array
,
with conventional prefix array
,
is reserved for
use as described in [Functions and Operators 3.1].
[Definition: The XML
namespace, defined in [Namespaces in XML] as
http://www.w3.org/XML/1998/namespace
, is used for
attributes such as xml:lang
, xml:space
, and
xml:id
.]
This namespace is always bound to the prefix xml
.
[Definition: The schema
namespace
http://www.w3.org/2001/XMLSchema
,
with conventional prefix xs
,
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
,
with conventional prefix xsi
,
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.
[Definition: The standard error namespace
http://www.w3.org/2005/xqt-errors
,
with conventional prefix err
,
is used for error codes
defined in this specification and related specifications. It is also used
for the names of certain predefined variables accessible within the scope
of an xsl:catch
element.]
The namespace http://www.w3.org/2000/xmlns/
is reserved for use
as described in [Namespaces in XML]. No element or attribute node can
have a name in this namespace, and although the prefix xmlns
is
implicitly bound to this namespace, no namespace node will ever define this
binding.
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.
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, nor in the names of extension functions or extension instructions.
It is not an error to use a reserved namespace in the name of an
extension attribute:
attributes such as xml:space
and xsi:type
fall into this category. XSLT processors must not reject such attributes,
and must not attach any meaning to them other than any meaning
defined by the relevant specification.
[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, an accumulator, or a character map; except that the name
xsl:initial-template
is permitted as a template
name.
Note:
The name xsl:original
is used within xsl:override
to refer to a component that is being overridden. Although
the name xsl:original
is used to refer to the component, the
component has its own name, and no component ever has the name
xsl:original
.
XSLT uses the expression language defined by XPath 3.0 [XPath 3.0]. Expressions are used in XSLT for a variety of purposes including:
selecting nodes for processing;
specifying conditions for different ways of processing a node;
generating text to be inserted in a result tree.
[Definition: Within this specification, the term XPath expression, or simply expression, means a string that matches the production ExprXP40 defined in [XPath 3.0].]
An XPath expression may occur as the value of certain attributes on XSLT-defined elements, and also within curly brackets in attribute value templates and text value templates.
Except where forwards compatible behavior is enabled (see 3.10 Forwards Compatible Processing), it is a static error if the value of such an attribute, or the text between curly brackets in an attribute value template or text value template, does not match the XPath production ExprXP40, or if it fails to satisfy other static constraints defined in the XPath specification, for example that all variable references must refer to variables that are in scope. Error codes are defined in [XPath 3.0].
The transformation fails with a dynamic error if any XPath expression is evaluated and raises a dynamic error. Error codes are defined in [XPath 3.0].
The transformation fails with a type error if an XPath expression raises a type error, or if the result of evaluating the XPath expression is evaluated and raises a type error, or if the XPath processor raises a type error during static analysis of an expression. Error codes are defined in [XPath 3.0].
[Definition: The context within a stylesheet where an XPath expression appears may specify the required
type of the expression. The required type indicates the type of the
value that the expression is expected to return.] If no required type is
specified, the expression may return any value: in effect, the required type is then
item()*
.
[Definition: When
used in this specification without further qualification, the term coercion rules
means the coercion rules defined in [XPath 4.0], applied with XPath 1.0
compatibility mode set to false
.]
Note:
In earlier versions of this specification, these were referred to as the function conversion rules.
Note:
These are the rules defined in [XPath 4.0] for converting the
supplied argument of a function call to the required type of that argument, as
defined in the function signature. The same rules are used in XSLT for converting
the value of a variable to the declared type of the variable, or the result of
evaluating a function or template body to the declared type of the function or
template. They are also used when parameters are supplied to a template using
xsl:with-param
. In all such cases, the rules that apply are
the XPath 4.0 rules without XPath 1.0 compatibility mode. The rules with XPath 1.0
compatibility mode set to true
are used only for XPath function calls, and for the
operands of certain XPath operators.
This specification also invokes the XPath 3.0
coercion rules to
convert the result of evaluating an XSLT sequence constructor to a required type (for example, the sequence
constructor enclosed in an xsl:variable
,
xsl:template
, or xsl:function
element).
Any dynamic error or type error that occurs when applying the coercion rules to convert a value to a required type results in the transformation failing, in the same way as if the error had occurred while evaluating an expression.
Note:
Note the distinction between the two kinds of error that may occur. Attempting to
convert an integer to a date is a type error, because such a conversion is never
possible. Type errors can be raised statically if they can be detected
statically, whether or not the construct in question is ever evaluated. Attempting
to convert the xs:untypedAtomic
item
2003-02-29
to a date is a dynamic error rather
than a type error, because the problem is with this particular value, not with its
type. Dynamic errors are raised only if the instructions or expressions that
cause them are actually evaluated. [XSLT 3.0 Erratum E21, bug 30236]
The XPath specification states that the host language must specify whether the XPath processor normalizes all line breaks on input, before parsing, and if it does so, whether it uses the rules of [XML 1.0] or [XML 1.1]. In the case of XSLT, all handling of line breaks is the responsibility of the XML parser (which may support either XML 1.0 or XML 1.1); the XSLT and XPath processors perform no further changes.
Note:
Most XPath expressions in a stylesheet appear within
XML attributes. They are therefore subject to XML line-ending normalization (for
example, a CRLF sequence is normalized to LF) and also to XML attribute-value
normalization, which replaces tabs and newlines by spaces. XPath expressions
appearing in text value templates, however (see 5.7.2 Text Value Templates) are subject to line-ending normalization but not
attribute-value normalization. In both cases, normalization of whitespace can be
prevented by using character references such as 	
.
XPath defines the concept of an expression contextXP40 which contains all the information that can affect the result of evaluating an expression. The expression context has two parts, the static contextXP40, and the dynamic contextXP40. The components that make up the expression context are defined in the XPath specification (see Section 2.2 Expression ContextXP40). This section describes the way in which these components are initialized when an XPath expression is contained within an XSLT stylesheet.
This section does not apply to static expressions
(whose context is defined in 9.7 Static Expressions), nor to XPath expressions
evaluated using xsl:evaluate
(whose context is defined in
10.4.2 Dynamic context for the target expression). [XSLT 3.0 Erratum E24, bug 30241]
As well as providing values for the static and dynamic context components defined in
the XPath specification, XSLT defines additional context components of its own. These
context components are used by XSLT instructions (for example,
xsl:next-match
and xsl:apply-imports
), and also
by the functions in the extended function library described in this
specification.
The following four sections describe:
5.3.1 Initializing the Static Context
5.3.2 Additional Static Context Components used by XSLT
5.3.3 Initializing the Dynamic Context
5.3.4 Additional Dynamic Context Components used by XSLT
The static contextXP40 of an XPath expression appearing in an XSLT stylesheet is initialized as follows. In these rules, the term containing element means the element within the stylesheet that is the parent of the attribute or text node whose value contains the XPath expression in question, and the term enclosing element means the containing element or any of its ancestors.
XPath 1.0 compatibility mode
is set to true
if and only if the containing element is processed with
XSLT 1.0 behavior (see
3.9 Backwards Compatible Processing).
The statically known namespacesXP40 are the applicable static namespaces for the containing element.
The default namespace for elements and typesXP40 is determined as described in 5.1.2.1 Unprefixed Element Names.
The default function namespaceXP40 is
http://www.w3.org/2005/xpath-functions
(and cannot be changed).
The in-scope schema definitionsXP40 for the XPath expression are the same as the in-scope schema components for the stylesheet, and are as specified in 3.14 Built-in Types.
The in-scope variablesXP40 are defined by the variable binding elements that are in scope for the containing element (see 9 Variables and Parameters).
The statically known function definitionsXP40 are:
The functions defined in [Functions and Operators 4.0] in
namespaces http://www.w3.org/2005/xpath-functions
and
http://www.w3.org/2005/xpath-functions/math
;
The functions defined in this specification in namespaces
http://www.w3.org/2005/xpath-functions
and
http://www.w3.org/2005/xpath-functions/map
;
Constructor functions for all the simple types in the in-scope schema definitionsXP40, including both built-in types and user-defined types;
The stylesheet functions defined in the containing package;
Stylesheet functions defined in used packages, subject to visibility: see 3.5.2 Dependencies between Packages;
any extension functions bound using implementation-defined mechanisms (see 25 Extensibility and Fallback).
Note:
The term extension function includes both vendor-supplied and user-written extension functions.
Note:
It follows from the above that a conformant XSLT processor must implement the entire library of functions defined in [Functions and Operators 4.0] as well as those defined in this specification.
The statically known collationsXP40 are implementation-defined, except that they must always include (a) the Unicode codepoint collation, defined in Section 5.3 Comparison of stringsFO40, and (b) the family of UCA collations described in 13.4 The Unicode Collation Algorithm.
Static base URI: In a conventional interpreted environment, the static base URI of an expression in the stylesheet is the base URI of the containing element in the stylesheet. The concept of the base URI of a node is defined in Section 5.2 base-uri Accessor DM30.
When stylesheets are executed in an environment where no source code is present
(for example, because the code of the stylesheet has been compiled and is distributed
as executable object code), it is recommended (subject to operational
constraints such as security) that the static base URI used during stylesheet evaluation
should be the location from which the stylesheet was loaded for execution
(its “deployed location”). This means, for example, that when the doc
FO40
or document
functions are called with a relative URI, the required document
is by default located relative to the deployed location of the stylesheet.
Whether or not the stylesheet is executed directly from source code,
it is possible that no static base URI is available, for example because the code was supplied
as an anonymous input stream, or because security policies are set to prevent executable code discovering
the location from which it was loaded. If the static base URI is not known, the static-base-uri
FO40
function returns an empty sequence, and other operations that depend on the static base URI may fail with
a dynamic error.
The set of statically
known decimal formatsXP40 is the set of decimal formats defined by
xsl:decimal-format
declarations in the stylesheet.
Some of the components of the XPath static context are used also by XSLT elements. For example, the
xsl:sort
element makes use of the collations defined in the
static context, and attributes such as type
and as
may
reference types defined in the in-scope schema components.
Many top-level declarations in a stylesheet, and attributes on the
xsl:stylesheet
element, affect the behavior of instructions
within the stylesheet. Each of these constructs is described in its appropriate
place in this specification.
A number of these constructs are of particular significance because they are used by functions defined in XSLT, which are added to the library of functions available for use in XPath expressions within the stylesheet. These are:
The set of named keys, used by the key
function
The set of named character maps, used by the character-map
function
The values of system properties, used by the
system-property
function
The set of available instructions, used by the
element-available
function
Note:
If these functions are called within a static expression, the results will reflect the capabilities and configuration of the processor used to perform static analysis, while if they are called elsewhere, the results should reflect the capabilities and configuration of the processor used to perform dynamic evaluation, which might give a different result. These calls should not be pre-evaluated at compile time unless it is known that this will give the same result.
For convenience, the dynamic context is described in two parts: the focus, which represents the place in the source document that is currently being processed, and a collection of additional context variables.
A number of functions specified in [Functions and Operators 4.0] are defined
to be deterministicFO40,
meaning that if they are called twice during the same execution scopeFO40, with the same arguments, then
they return the same results (see Section 1.9 TerminologyFO40). In
XSLT, the execution of a stylesheet defines the execution scope. This means, for
example, that if the function current-dateTime
FO40 is called
repeatedly during a transformation, it produces the same result each time. By
implication, the components of the dynamic context on which these functions depend
are also stable for the duration of the transformation. Specifically, the
following components defined in Section 2.2.2 Dynamic ContextXP40 must be
stable: function implementations, current dateTime,
implicit timezone, available documents,
available collections, and default collection. The
values of global variables and stylesheet parameters are also stable for the
duration of a transformation. The focus is not stable; the additional
dynamic context components defined in 5.3.4 Additional Dynamic Context Components used by XSLT
are also not stable.
As specified in [Functions and Operators 4.0], implementations may provide
user options that relax the requirement for the doc
FO40 and
collection
FO40 functions (and therefore, by implication, the
document
function) to return stable results. By default,
however, the functions must be stable. The manner in which such user options are
provided, if at all, is implementation-defined.
XPath expressions contained in [xsl:]use-when
attributes are not
considered to be evaluated “during the transformation” as defined above. For
details see 3.13.3 Conditional Element Inclusion.
[Definition: A component of the context that has no value is said to be absent.] This is a distinguishable state, and is not the same as having the empty sequence as its value.
[Definition: When a sequence constructor is evaluated, the processor keeps track of which items are being processed by means of a set of implicit variables referred to collectively as the focus.] More specifically, the focus consists of the following three values:
[Definition: The context
item is the item currently being processed. An item (see
[XDM 3.0]) is either an atomic item (such
as an integer, date, or string), a node, or
a function item. It changes whenever instructions such as
xsl:apply-templates
and
xsl:for-each
are used to process a sequence of
items; each item in such a sequence becomes the context item while
that item is being processed.] The context item is returned
by the XPath expression
.
(dot).
Note:
Although XPath 4.0 allows the context value to be an arbitrary sequence, at the interface between XSLT 4.0 and XPath 4.0 it is always either a single item, or absent. XSLT 4.0 therefore continues to use the term context item rather than context valueXP40.
[Definition: The
context position is the position of the context item
within the sequence of items currently being processed. It changes
whenever the context item changes. When an instruction such as
xsl:apply-templates
or
xsl:for-each
is used to process a sequence of
items, the first item in the sequence is processed with a context
position of 1, the second item with a context position of 2, and so
on.] The context position is returned by the XPath expression
position()
.
[Definition: The context
size is the number of items in the sequence of items
currently being processed. It changes whenever instructions such as
xsl:apply-templates
and
xsl:for-each
are used to process a sequence of
items; during the processing of each one of those items, the context
size is set to the count of the number of items in the sequence (or
equivalently, the position of the last item in the
sequence).] The context size is returned by the XPath
expression
last()
.
[Definition: If the context item is a node (as distinct from
an atomic item such as an integer), then it is also referred to as the
context node. The context node is not an independent
variable, it changes whenever the context item changes. When the context
item is an atomic item or a function
item, there is no context node.] The context node is
returned by the XPath expression
self::node()
, and it is used as the starting node for all relative
path expressions.
Where the containing element of an XPath expression is an instruction or a literal result element, the initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing instruction or literal result element.
The context valueXP40 for evaluating global variables declared in the top-level package is set to the global context item supplied when the transformation is invoked (see 2.3 Initiating a Transformation). For global variables declared in a library package, the context value is absent. [XSLT 3.0 Erratum E7, bug 30179].
For an XPath expression contained in a value template, the initial context item, context position, and context size for the XPath expression are the same as the context item, context position, and context size for the evaluation of the containing sequence constructor.
In other cases (for example, where the containing element is
xsl:sort
, xsl:with-param
, or
xsl:key
), the rules are given in the specification of the
containing element.
The current
function can be used within any XPath expression to select the item that was
supplied as the context item to the XPath expression by the XSLT processor.
Unlike .
(dot) this is unaffected by changes to the context item
that occur within the XPath expression. The current
function is described in 20.4.1 fn:current.
On completion of an instruction that changes the focus (such as xsl:apply-templates
or
xsl:for-each
), the focus reverts to its previous value.
When a stylesheet function is called, the focus within the body of the function is initially absent.
When the focus is absent, evaluation of any expression that references the context item, context position, or context size results in a type error [ERR XPDY0002] XP40
The description above gives an outline of the way the focus works. Detailed rules for the effect of each instruction are given separately with the description of that instruction. In the absence of specific rules, an instruction uses the same focus as its parent instruction.
[Definition: A singleton focus based on an item J has the context item (and therefore the context node, if J is a node) set to J, and the context position and context size both set to 1 (one).]
The previous section explained how the focus for an XPath expression appearing in an XSLT stylesheet is initialized. This section explains how the other components of the dynamic contextXP40 of an XPath expression are initialized.
The dynamic variablesXP40 are the current values of the in-scope variable binding elements.
The dynamically known function definitionsXP40
(representing the functions accessible using function-available
or function-lookup
FO40)
include all the functions available in the static context, and may also include an additional
implementation-defined set of functions that are available dynamically but not statically.
Note:
This set therefore includes some functions that are not available for
dynamic calling using xsl:evaluate
, for example stylesheet functions
whose visibility is private, and XSLT-defined functions such as current
and key
.
Note:
The rule that all functions present in the static context must always be present in
the dynamic context is a consistency constraint. The effect of violating a consistency constraint is
implementation-defined: it does not necessarily lead to an error.
For example, if the version of a used package that is available
at evaluation time does not include all public user-defined functions that were available in the version that was
used at analysis time, then a processor may recover by raising an error only if the function
is actually called. Conversely, if the evaluation-time version of the package includes additional public functions, these may
be included in the dynamic context even though they were absent from the static context.
Dynamic calling of functions using function-lookup
FO40
may therefore be an effective strategy for coping with variations between versions of a library package on which a stylesheet
depends.
The default
collationXP40 is defined by the value of the
[xsl:]default-collation
attribute on the innermost enclosing
element that has such an attribute. For details, see 3.7.2 The default-collation Attribute.
[Definition: In this
specification the term default collation means the collation
that is used by XPath operators such as eq
and
lt
appearing in XPath expressions within the
stylesheet.]
This collation is also used by default when comparing strings in the
evaluation of the xsl:key
and
xsl:for-each-group
elements. This may
also (but need not necessarily) be the same as the default collation used
for xsl:sort
elements within the stylesheet. Collations
used by xsl:sort
are described in 13.1.3 Sorting Using Collations.
Note:
The default collation is usually known
statically. One notable exception is when the function call default-collation()
appears in the initializing expression of an optional xsl:function
parameter,
for example:
<xsl:function name="f:myfunc"> <xsl:param name="collation" required="no" select="default-collation()"/> </xsl:function>
In this situation the call on default-collation()
returns the default
collation from the context of the function call, which may differ from the default
collation of the function declaration.
The available
documentsXP40 are defined as part of the XPath 3.0 dynamic context to support the
doc
FO40 function, but this component is also
referenced by the similar XSLT document
function:
see 20.1 fn:document. This variable defines a mapping
between URIs passed to the doc
FO40 or
document
function and the document nodes that are
returned.
The mapping from URIs to document nodes is
affected by xsl:strip-space
declarations and by the
input-type-annotations
attribute, and may therefore vary
from one package to another.
Note:
Defining this as part of the evaluation context is a formal way of specifying that the way in which URIs get turned into document nodes is outside the control of the language specification, and depends entirely on the run-time environment in which the transformation takes place.
The XSLT-defined document
function allows the use of
URI references containing fragment identifiers. The interpretation of a
fragment identifier depends on the media type of the resource
representation. Therefore, the information supplied in
available documentsXP40 for
XSLT processing must provide not only a mapping from URIs to document
nodes as required by XPath, but also a mapping from URIs to media
types.
All other aspects of the dynamic context (for example, the current date and time, the implicit timezone, the default language, calendar, and place, the available documents, text resources, and collections, and the default collection) are implementation-defined, and do not change in the course of a single transformation, except to the extent that they may be different from one package to another.
In addition to the values that make up the focus, an XSLT processor maintains a number of other dynamic context components that reflect aspects of the evaluation context. These components are fully described in the sections of the specification that maintain and use them. They are:
The current template rule,
which is the template rule most
recently invoked by an xsl:apply-templates
,
xsl:apply-imports
, or xsl:next-match
instruction: see 6.9 Overriding Template Rules;
The current mode, which is the
mode set by the most recent call of
xsl:apply-templates
(for a full definition see 6.7 Modes);
The current group and current grouping key, which
provide information about the collection of items currently being processed
by an xsl:for-each-group
instruction: see 14.2.1 fn:current-group and 14.2.2 fn:current-grouping-key;
Note:
In XSLT 3.0 the initial value of these two properties is “absent”, which means that any reference to their values causes a dynamic error. Previously, the initial value was an empty sequence.
The current merge group and current merge key, which provide information about the
collection of items currently being processed by an
xsl:merge
instruction.
The current captured
substrings: this is a sequence of strings, which is maintained
when a string is matched against a regular expression using the
xsl:analyze-string
instruction, and which is accessible
using the regex-group
function: see 17.2 fn:regex-group.
The output state: this is a flag
whose two possible values are final
output state and temporary output state. The initial setting when the stylesheet is invoked by executing a
template is final output
state, and it is switched to temporary output state by
instructions such as xsl:variable
. For more details, see
26.2 Restrictions on the use of xsl:result-document.
The current output URI: this
is the URI associated with the result tree to which instructions are
currently writing. The current output URI is initially the same as the
base output URI. During the evaluation of an
xsl:result-document
instruction, the current output URI
is set to the absolute URI identified by the href
attribute of
that instruction.
The following non-normative table summarizes the initial state of each of the components in the evaluation context, and the instructions which cause the state of the component to change.
[Definition: The initial setting of a component of the dynamic context is used
when evaluating global variables
and stylesheet parameters,
when evaluating the use
and match
attributes of
xsl:key
, and when evaluating the initial-value
of
xsl:accumulator
and the select
expressions or
contained sequence constructors of
xsl:accumulator-rule
].
[Definition: The term non-contextual function
call is used to refer to function calls that do not pass the dynamic
context to the called function. This includes all calls on stylesheet functions and all
dynamic function
invocationsXP40, (that is calls to function items as permitted by
XPath 3.0). It excludes calls to some
functions in the namespace
http://www.w3.org/2005/xpath-functions
, in
particular those that explicitly depend on the context, such as the
current-group
and regex-group
functions. It is implementation-defined whether, and under what circumstances,
calls to extension functions are
non-contextual.]
Named function references (such as position#0
) and
calls on function-lookup
FO40 (for example,
function-lookup("position", 0)
) are defined to retain the XPath
static and dynamic context at the point of invocation as part of the closure of
the resulting function item, and to use this preserved context when a dynamic
function call is subsequently made using the function item. This rule does not
extend to the XSLT extensions to the dynamic context defined in this section. If a
dynamic function call is made that depends on the XSLT part of the dynamic context
(for example, regex-group#1(2)
), then the relevant components of the
context are cleared as described in the table above.
In XSLT 4.0, patterns can match any kind of item: atomic items and function items as well as nodes.
A template rule identifies the items to which it applies by means of a pattern. As well as being used in template rules, patterns are used for numbering (see 12 Numbering), for grouping (see 14 Grouping), and for declaring keys (see 20.2 Keys).
[Definition: A pattern specifies a set of conditions on an item. An item that satisfies the conditions matches the pattern; an item that does not satisfy the conditions does not match the pattern.]
There are three kinds of pattern: predicate patterns, type patterns, and node patterns:
[Definition: A predicate pattern is written as
.
(dot) followed by zero or more predicates in square
brackets, and it matches any item for which each of the predicates evaluates
to true
.]
A predicate pattern .[P1][P2]...
can be regarded as an abbreviation
for the type pattern type(item())[P1][P2]...
.
The detailed semantics are given in 5.4.2.1 Predicate Patterns. This construct can be used to match items of any
kind (nodes, atomic items, and function items). For example, the pattern
.[starts-with(., '$')]
matches any string that starts with the
character $
, or a node whose atomized value starts with
$
. This example shows a predicate pattern with a single
predicate, but the grammar allows any number of predicates (zero or more).
[Definition: A type pattern can be written as
type(T)
(where T is an ItemTypeXP40
followed by zero or more predicates in square
brackets, and it matches any item of type T which each of the predicates evaluates
to true
.]
The parameter T can also be a list of item types, separated by "|"
.
For example, type(array(*) | map(*))
matches arrays and maps, while
type(text() | comment())
matches text nodes and comment nodes.
The most commonly used type patterns can be abbreviated. For example, match="type(record(F1, F2, *))"
can be abbrevated to match="record(F1, F2, *)"
, and match="type(array(xs:string))"
can be abbreviated to match="array(xs:string)"
. The main case where such abbreviation is
not possible is with atomic items: match="type(xs:date)"
cannot be abbreviated because
a bare QName is interpreted as a node pattern, matching elements named xs:date
.
The pattern match="type(text() | comment())"
has almost the same effect as
match="text() | comment()"
, except that the rules for calculating a default priority
are different.
[Definition: A node pattern uses a subset of the syntax for path expressions, and is defined to match a node if the corresponding path expression would select the node. Node patterns may also be formed by combining other patterns using union, intersection, and difference operators.]
The syntax for node patterns
(UnionExprP
in the grammar:
see 5.4.2 Syntax of Patterns) is a subset of the syntax for
expressions. Node patterns are
used only for matching nodes; an item other than a node will never match a
node pattern.
As explained in detail below, a node matches a node pattern if the node can be selected by
deriving an equivalent expression, and evaluating this expression with respect
to some possible context.
Note:
The specification uses the phrases an item matches a pattern and a pattern matches an item interchangeably. They are equivalent: an item matches a pattern if and only if the pattern matches the item.
Here are some examples of patterns:
Predicate Patterns:
.
matches any item.
.[. castable as xs:date]
matches any item
that can be successfully cast to xs:date
: for example,
an xs:date
or xs:dateTime
value, or a string
in the lexical form of a date, or a node whose typed value is an xs:date
or a string in the form of a date.
.[string() => matches('^[0-9]$')]
matches any
item whose string value is a sequence of digits.
.[. castable as xs:date][xs:date(.) le current-date()]
matches any
item that is castable to xs:date
provided that the result of casting
the value to xs:date
is a date in the past.
Type Patterns
type(item())
matches any item.
type(node())
matches any node.
(Note the distinction from the pattern node()
.)
type(xs:date)
matches any
atomic item of type xs:date
(or a type derived by
restriction from xs:date
).
type(xs:date)[. gt current-date()]
matches any date in
the future.
type(xs:string)[starts-with(., 'e')]
matches any xs:string
value that starts with the letter e
. Note there is no type conversion; the pattern
will not match an xs:untypedAtomic
or xs:anyURI
value,
nor will it match any node.
type(fn(*))
matches any
function item.
type(fn($x as xs:integer) as xs:boolean)[.(42)]
matches any function that
accepts an xs:integer
argument and returns a boolean result, provided
that the result of calling the function with the argument value 42
is true
.
type(xs:date | xs:dateTime | xs:time)
matches any atomic item
that is an instance of xs:date
, xs:dateTime
, or xs:time
.
type(array(xs:date) | array(xs:dateTime) | array(xs:time))
matches any array whose
members are all of type xs:date
, any array whose
members are all of type xs:dateTime
, or any array whose
members are all of type xs:time
.
type(map((xs:string|xs:untypedAtomic), *)
matches any map
whose keys are all instances of xs:string
or xs:untypedAtomic
.
enum("red", "green", "blue")
matches any one of the three strings
"red"
, "green"
, or "blue"
.
record(first, last, *)[?location = 'UK']
matches any map whose keys include the strings "first"
and "last"
, and that also has an entry with key "location"
whose
value is "UK"
.
record(longitude, latitude)
matches any map with two entries whose keys are the strings "longitude"
and "latitude"
.
array(xs:integer)[array:size(.) eq 4]
matches any array of four integers.
array(record(first, last, *))
matches any array of maps where each map
contains entries with keys "first"
and "last"
. (Note that
this includes the empty array).
array(record(first, last, *))[array:size(.) gt 0]
matches any non-empty array of maps where each map
contains entries with keys "first"
and "last"
.
type(my:complex)
matches any value that is an instance of the record typeXP40
declared in an xsl:record-type
declaration with name my:complex
type(my:complex)[?i eq 0]
matches any value that is an instance of the
record typeXP40 declared in an xsl:record-type
declaration with name my:complex
and that is a map
with an entry having key i
and value zero.
Node Patterns
*
matches any element.
para
matches any para
element.
chapter|appendix
matches any chapter
element
and any appendix
element.
child::(chapter|appendix)
matches any chapter
element
and any appendix
element. Note that although the child
axis
is explicitly written, an element can match even though it has no parent.
olist/entry
matches any entry
element with an
olist
parent.
appendix//para
matches any para
element with an
appendix
ancestor element.
appendix/descendant::(para|table)
matches any para
or table
element with an
appendix
ancestor element.
schema-element(us:address)
matches any element that is
annotated as an instance of the type defined by the schema element
declaration us:address
, and whose name is either
us:address
or the name of another element in its
substitution group.
attribute(*, xs:date)
matches any attribute annotated as
being of type xs:date
.
/
matches a document node.
document-node()
matches a document node.
document-node(schema-element(my:invoice))
matches the
document node of a document whose document element is named
my:invoice
and matches the type defined by the global
element declaration my:invoice
.
text()
matches any text node.
namespace-node()
matches any namespace
node.
node()
matches any node other than an attribute node,
namespace node, or document node.
id("W33")
matches the element with unique ID
W33
.
para[1]
matches any para
element that is the
first para
child element of its parent. It also matches a
parentless para
element.
//para
matches any para
element in a tree that is rooted at a document node.
bullet[position() mod 2 = 0]
matches any bullet
element that is an even-numbered bullet
child of its
parent.
div[@class="appendix"]//p
matches any p
element
with a div
ancestor element that has a class
attribute with value appendix
.
@class
matches any class
attribute
(not any element that has a class
attribute).
@(class|type|kind)
matches any attribute named class
or type
or kind
.
@*
matches any attribute node.
$xyz
matches any node that is present in
the value of the variable $xyz
.
$xyz//*
matches any element that is a
descendant of a node that is present in the value of the variable
$xyz
.
doc('product.xml')//*
matches any element
within the document whose document URI is product.xml
.
[ERR XTSE0340] Where an attribute is defined to contain a pattern, it is a static error if the pattern does not match the production Pattern40.
The grammar for patterns uses the notation defined in Section A.1.1 NotationXP40.
The lexical rules for patterns are the same as the lexical rules
for XPath expressions, as defined in Section A.3 Lexical structureXP40. Comments are permitted between tokens, using the
syntax (: ... :)
. All other provisions of the XPath grammar apply
where relevant, for example the rules for whitespace handling and
extra-grammatical constraints.
Pattern40 |
::= | PredicatePattern | TypePattern | NodePattern |
PredicatePattern |
::= | "." PredicateXP40* |
TypePattern |
::= | (WrappedItemTest | AnyItemTestXP40 | FunctionTypeXP40 | MapTypeXP40 | ArrayTypeXP40 | RecordTypeXP40 | EnumerationTypeXP40) PredicateXP40* |
NodePattern |
::= | UnionExprP |
Patterns fall into three groups:
A PredicatePattern
matches items according to conditions that the item must
satisfy: for example .[. castable as xs:integer]
matches any value (it might
be an atomic item, a node, or an array) that is castable as an integer.
A TypePattern
matches items according to their type. For example
type(xs:integer)
matches an atomic item that is an instance of xs:integer
,
while record(longitude, latitude)
matches a map that has exactly two entries, with
keys "longitude"
and "latitude"
A NodePattern
matches nodes in a tree, typically by specifying a path that
can be used to locate the nodes: for example order
matches an element node
named order
, while billing-address/city
matches an element named city
whose parent node is an element named billing-address
.
The following sections define the rules for each of these groups.
PredicatePattern |
::= | "." PredicateXP40* |
Predicate |
::= | "[" ExprXP40 "]" |
A PredicatePattern PP matches an item J if and only if the XPath expression taking the same form as PP returns a non-empty sequence when evaluated with a singleton focus based on J.
Note:
The pattern .
, which is a PredicatePattern
with no predicates,
matches every item.
A predicate with the numeric value 1 (one) always matches, and a predicate with
any other numeric value never matches. Numeric predicates in a
PredicatePattern
are therefore not useful, but are defined this
way in the interests of consistency with XPath.