2 Concepts
2.1 Terminology
For a full glossary of terms, see C
Glossary.
[Definition: The software
responsible for transforming source trees into result trees is
referred to as the processor. This is sometimes expanded to
XSLT processor to avoid any confusion with other processors,
for example an XML processor.]
[Definition: A specific product that performs the functions
of an XSLT processor is
referred to as an implementation ].
Note:
The precise meanings of the terms source tree and
result tree, as used in this specification, depend on the
context. In the context of the stylesheet as a whole, the source trees are
the trees provided as the initial input to the transformation,
together with any trees supplied as stylesheet parameters and any
trees accessed using the document, doc
FO or collection
FO functions; while the result trees are the
trees created by an explicit xsl:result-document
instruction as well as the implicit result tree created in the
absence of an xsl:result-document
instruction. In the context of an individual instruction in the
stylesheet, the
term source tree also includes any temporary tree that the instruction
is using for input, and the term result tree includes any
temporary
tree that the instruction is using for output.
In this specification the words must,
must not, should,
should not, may,
required, and recommended are to be interpreted as described in
[RFC2119]. Where the word must relates to the behavior of the XSLT processor, then an
implementation is not conformant unless it behaves as specified,
subject to the more detailed rules in 21
Conformance. Where the word must
relates to a stylesheet, then the processor must enforce this constraint on stylesheets.
[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 should be
described in the vendor's documentation.]
[Definition: The term
implementation-dependent refers to a feature where the
behavior may vary from one implementation
to another, and where the vendor is not expected to provide a full
specification of the behavior.] (This
might apply, for example, to limits on the size of source documents
that can be transformed.)
In all cases where this specification leaves the behavior
implementation-defined or implementation-dependent, the
implementation has the option of providing mechanisms that allow the
user to influence the behavior.
A paragraph labeled as a Note or described as an
example is non-normative.
Many terms used in this document are defined in the XPath
specification [XPath 2.0] or the Data Model
specification [Data Model]. Particular
attention is drawn to the following:
-
[Definition: The term
atomization is defined in Section 2.3.2
AtomizationXP. It is a process that
takes as input a sequence of nodes and atomic values, and returns
a sequence of atomic values, in which the nodes are replaced by
their typed values as defined in [Data
Model].] For some nodes (for
example, elements with element-only content),
atomization generates a dynamic error.
-
[Definition: The
term typed value is defined in Section
5.6 typed-value AccessorDM. Every
node except an element defined in the schema with element-only
content has a typed value. For example, the typed value of an
attribute of type xs:IDREFS is a sequence of zero or
more xs:IDREF values.]
-
[Definition: The term string value is defined in
Section
5.5 string-value AccessorDM. Every
node has a string
value. For example, the string value of an element is the
concatenation of the string values of all its descendant text
nodes.]
-
[Definition: The term XPath 1.0
compatibility mode is defined in Section 2.1.1
Static ContextXP. This is a setting
in the static context of an XPath expression; it has two values,
true and false. When the value is set
to true, the semantics of function calls and certain other
operations are adjusted to give a greater degree of backwards
compatibility between XPath 2.0 and XPath 1.0.]
2.2 Notation
In this document the specification of each XSLT-defined element
type is preceded by a summary of its syntax in the form of a model
for elements of that element type. A full list of all these
specifications can be found in D
Element Syntax Summary. The meaning of syntax summary
notation is as follows:
-
An attribute that is required is
shown with its name in bold. An attribute that may be omitted is
shown with a question mark following its name.
-
The string that occurs in the place of an attribute value
specifies the allowed values of the attribute. If this is
surrounded by curly brackets ({...}), then the
attribute value is treated as an attribute value template, and
the string occurring within curly brackets specifies the allowed
values of the result of evaluating the attribute value template.
Alternative allowed values are separated by |. A
quoted string indicates a value equal to that specific string. An
unquoted, italicized name specifies a particular type of
value.
In all cases where this specification states that the
value of an attribute must be one of a
limited set of values, leading and trailing whitespace in
the attribute value is ignored. In the case of an attribute value template, this
applies to the effective value obtained when the
attribute value template is expanded.
-
Unless the element is required to be
empty, the model element contains a comment specifying the
allowed content. The allowed content is specified in a similar
way to an element type declaration in XML;
sequence constructor means that any mixture
of text nodes, literal result elements,
extension instructions, and XSLT
elements from the instruction category is allowed;
other-declarations means that any mixture of XSLT
elements from the declaration category, other than xsl:import, is allowed,
together with user-defined data elements.
-
The element is prefaced by comments indicating if it belongs
to the instruction category or
declaration category or both. The category of an
element only affects whether it is allowed in the content of
elements that allow a sequence constructor or
other-declarations.
This example illustrates the notation used to describe XSLT
elements.
<!-- Category: instruction
-->
<xsl:example-element
select = expression
debug? = { "yes" | "no" }>
<!-- Content: ((xsl:variable | xsl:param)*, xsl:sequence) -->
</xsl:example-element>
This example defines a (non-existent) element
xsl:example-element. The element is classified as an
instruction. It takes a mandatory select attribute,
whose value is an XPath expression, and an optional debug
attribute, whose value must be either
yes or no; the curly brackets indicate
that the value can be defined as an attribute value template,
allowing a value such as debug="{$debug}", where the
variable
debug is evaluated to yield "yes" or
"no" at run-time.
The content of an xsl:example-element instruction
is defined to be a sequence of zero or more xsl:variable and xsl:param elements, followed by
an xsl:sequence
element.
[ERR
XT0010] A static error is signaled if an XSLT-defined
element is used in a context where it is not permitted, if a
required attribute is omitted, or if the
content of the element does not correspond to the content that is
allowed for the element.
Attributes are validated as follows. These rules apply to the
value of the attribute after removing leading and trailing
whitespace.
Special rules apply if the construct appears in part of the
stylesheet that is
processed with forwards-compatible behavior:
see 3.9 Forwards-Compatible
Processing.
XSLT defines a set of standard functions which are additional to
those defined in [Functions and Operators]. The
signatures of these functions are described using the same notation
as used in [Functions and Operators]. The
names of these functions are all in the standard function
namespace.
2.3 Initiating a
Transformation
This document does not specify any application programming
interfaces or other interfaces for initiating a transformation. This
section, however, describes the information that must be supplied when a transformation is
initiated.
Implementations may allow a
transformation to run as two or more phases, for example parsing,
compilation and execution. Such a distinction is outside the scope of
this specification, which treats transformation as a single process
controlled using a set of stylesheet modules, supplied in the form
of XML documents.
The following information is supplied to execute a
transformation:
-
The stylesheet module that is to act as
the principal stylesheet module
for the transformation. The complete stylesheet is assembled by
recursively expanding the xsl:import and xsl:include declarations in
the principal stylesheet module, as described in 3.10.2 Stylesheet Inclusion and 3.10.3 Stylesheet Import.
-
A set (possibly empty) of values for stylesheet
parameters (see 9.5 Global
Variables and Parameters). These values are available for
use within expressions in the stylesheet.
-
[Definition: A node that acts as the initial
context node for the transformation. This node is accessible
within the stylesheet as the initial value of the XPath
expressions
. (dot) and self::node(), as described
in 2.5.1 Maintaining Position: the
Focus].
If no initial context node is supplied, then the context item,
context
position, and context size will initially be unset, and
the evaluation of any expression that references these values
will result in a dynamic error. (Note that the initial
context size and context position will always be 1 (one) when an
initial context node is supplied, and will be undefined if no
initial context node is supplied).
-
Optionally, the name of a named template which is to be executed
as the entry point to the transformation. This template
must exist within the stylesheet. If no named
template is supplied, then the transformation starts with the
template
rule that best matches the initial context node,
according to the rules defined in 6.4
Conflict Resolution for Template Rules. Either a
named template, or an initial context node, or both, must be supplied.
-
Optionally, an initial mode. If an initial mode is supplied, then in
searching for the template rule that best matches the
initial context node, the
processor considers only those rules that apply to the initial
mode. If no initial mode is supplied, the default mode is
used.
-
[Definition: A base output URI, that is, a URI to
be used as the base URI when resolving a relative URI allocated
to a result tree. If the transformation generates multiple result
trees, then typically each one will be allocated a URI relative
to this base URI.]
[ERR
XT0040] It is a non-recoverable dynamic error if
the invocation of the stylesheet specifies a template name that does
not match the expanded-QName of a named template defined
in the stylesheet.
[ERR
XT0050] It is a non-recoverable dynamic error if
the stylesheet that is invoked declares a visible stylesheet
parameter with required="yes" and no value for this
parameter is supplied during the invocation of the stylesheet. A
stylesheet parameter is visible if it is not masked by another global
variable or parameter with the same name and higher import
precedence.
[Definition: The transformation is performed by evaluating
an initial template; if a named template is supplied when the
transformation is initiated, then this is the initial template;
otherwise, the initial template is the template rule selected according to the
rules of the xsl:apply-templates
instruction for processing the initial context node in the initial
mode.]
Parameters passed to the transformation by the client application
are matched against stylesheet parameters (see 9.5 Global Variables and Parameters),
not against the template parameters declared within the
initial
template. All template parameters within the initial
template to be executed will take their default values.
[ERR
XT0060] It is a non-recoverable dynamic error if
the initial
template defines a template parameter that specifies
required="yes".
A stylesheet can
process further source documents in addition to those supplied when
the transformation is invoked. These additional documents can be
loaded using the functions document (see 16.1 Multiple Source Documents) or doc
FO or collection
FO (see [Functions and
Operators]), or they can be supplied as stylesheet
parameters (see 9.5 Global
Variables and Parameters), or as the result of an extension
function (see 18.1 Extension
Functions).
2.4 Executing a Transformation
[Definition: A
stylesheet contains a set of template rules (see 6 Template Rules). A template rule has two parts:
a pattern that is matched
against nodes, and a sequence constructor that is evaluated
to produce a sequence of items. In most cases these items are nodes,
which are then written to a result tree.]
A transformation as a whole is executed by evaluating the
sequence constructor of the initial template
as described in 5.6 Sequence
Constructors. If the result is a non-empty sequence, then
this sequence is used to construct an implicit result tree, following
the rules described in 5.6.1 Constructing Complex
Content: the effect is as if the sequence
constructor contained in the initial template were contained in an
xsl:result-document
element with no attributes.
[Definition: The
elements appearing within a sequence constructor are referred to as
instructions.]
The main categories of instruction elements are as follows:
-
instructions that create new nodes: xsl:element, xsl:attribute, xsl:processing-instruction,
xsl:comment, xsl:value-of, xsl:text, xsl:namespace;
-
an instruction that creates an arbitrary sequence: xsl:sequence;
-
instructions that cause conditional or repeated evaluation of
nested instructions: xsl:if, xsl:choose, xsl:for-each, xsl:for-each-group;
-
instructions that invoke templates: xsl:apply-templates,
xsl:apply-imports,
xsl:call-template,
xsl:next-match;
-
an instruction that declares variables: xsl:variable;
-
other specialized instructions: xsl:number, xsl:analyze-string,
xsl:message, xsl:result-document.
Often, a sequence constructor will include an
xsl:apply-templates
instruction, which selects a sequence of nodes to be processed. Each
of the selected nodes is processed by searching the stylesheet for a
matching template
rule and evaluating the sequence constructor of that template
rule. The resulting sequences of items are concatenated, in order, to
give the result of the xsl:apply-templates
instruction, as described in 6.3
Applying Template Rules; this sequence is often added to a
result tree. Since the sequence constructors of the selected
template rules
may themselves contain xsl:apply-templates
instructions, this results in a cycle of selecting nodes, identifying
template rules,
constructing sequences, and constructing result trees, that recurses
through the source tree.
2.5 The Stylesheet Evaluation
Context
During the evaluation of a stylesheet, certain information is
maintained about the current state of processing. This information is
referred to collectively as the evaluation context. The variables
that make up the evaluation context are described in this
section.
The evaluation context is structured as a stack. When an instruction is evaluated, it
inherits the state of the evaluation context from its calling
instruction. An instruction may make modifications to the state of
the evaluation context, but on return to its caller, the evaluation
context is always in the same state as it was on entry to the
instruction. The scope of variables in the evaluation context is
dynamic; they are passed implicitly from a calling template to a
called template, except where otherwise specified.
The variables making up the evaluation context are not available
when a stylesheet function is called from an
XPath expression. On entry to a stylesheet function, a new empty
evaluation context is established. Some variables in an empty
evaluation context are said to be undefined, in which case
any reference to this variable causes a dynamic error. Other variables are
initialized to a defined value, such as an empty sequence.
For convenience, the evaluation 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.
2.5.1 Maintaining Position: the
Focus
[Definition: When a sequence
constructor is evaluated, the processor keeps track of which nodes are being
processed by means of a set of implicit variables referred to
collectively as the focus.]
More specifically, the focus consists of the following three
values:
-
[Definition: The context item is the item
currently being processed. An item (see [Data Model]) is either an atomic value (such
as an integer, date, or string), or a node. The context item is
initially set to the initial context node supplied
when the transformation is invoked (see 2.3 Initiating a Transformation). It
changes whenever instructions such as xsl:apply-templates
and xsl:for-each
are used to process a sequence of items; each item in such a
sequence becomes the context item while that item is being
processed.] The context item is
returned by the XPath expression . (dot).
-
[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 value such as an
integer), then it is also referred to as the context node.
The context node is not an independent variable, it changes
whenever the context item changes. When the context item is an
atomic value, there is no context node.] The context node is returned by the XPath
expression
self::node(), and it is used as the starting node for
all relative path expressions.
The current
function can be used within any XPath expression to select the item that was
supplied as the context item to the XPath expression by the XSLT
processor; unlike . (dot) this is unaffected by
changes to the context item that occur within the XPath expression.
The current function
is described in 16.6.1
current.
On completion of an instruction 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 undefined.
The focus is also undefined on initial entry to the stylesheet if no initial
context node supplied.
[ERR
XT0070] When the focus is undefined, evaluation of any
expression that
references the context item, context position, or context size
results in a non-recoverable dynamic error.
The description above gives an outline of the way the focus works. Detailed rules for the
effect of each instruction are given separately with the
description of that instruction. In the absence of specific rules,
an instruction uses the same focus as its parent instruction.
Sometimes the focus is based on a single node.
[Definition: A singleton focus based on a node
N has the context item (and therefore the context node) set to
N, and the context position and context size both set to
1 (one).]
2.5.2 Additional Context
Variables
In addition to the values that make up the focus, an XSLT processor maintains a number of
other internal variables that reflect aspects of the evaluation
context. These variables are fully described in the sections of the
specification that maintain and use these variables. They are:
The following non-normative table summarizes the initial state
of each of the variables in the evaluation context, and the
instructions which cause the state of the variable to change.
| Variable |
Initial Setting |
Set by |
Cleared by |
| focus |
singleton focus
based on the initial context node if
supplied |
xsl:apply-templates,
xsl:for-each,
xsl:for-each-group,
xsl:analyze-string |
calls on stylesheet functions |
| current template |
the initial
template |
xsl:apply-templates,
xsl:apply-imports,
xsl:next-match |
xsl:for-each, xsl:for-each-group,
calls on stylesheet functions |
| current mode |
the initial
mode |
xsl:apply-templates |
calls on stylesheet functions |
| current
group |
empty sequence |
xsl:for-each-group |
calls on stylesheet functions |
| current grouping key |
empty sequence |
xsl:for-each-group |
calls on stylesheet functions |
| current captured
substrings |
empty sequence |
xsl:matching-substring |
xsl:non-matching-substring;
calls on stylesheet functions |
| output state |
final
output state |
Set to temporary output state by
instructions such as xsl:variable, xsl:attribute, etc.,
and by calls on stylesheet functions |
None |
2.6 Parsing and Serialization
An XSLT stylesheet
describes a process that constructs a set of result trees from a set
of source trees.
The stylesheet
does not describe how a source tree is constructed. Frequently an
implementation will operate in conjunction
with an XML parser (or more strictly, in the terminology of [XML 1.0], an XML processor), to build the source
tree from an input XML document. An implementation may also provide an application programming interface
allowing the tree to be constructed directly, or allowing it to be
supplied in the form of a DOM Document object (see [DOM2]). This is outside the scope of this specification.
Users should be aware, however, that since the input to the
transformation is a tree conforming to the XPath data model as
described in [Data Model], constructs that
might exist in the original XML document, or in the DOM, but which
are not within the scope of the data model, cannot be processed by
the stylesheet and
cannot be guaranteed to remain unchanged in the transformation
output. Such constructs include CDATA section boundaries, the use of
entity references, and the DOCTYPE declaration and internal DTD
subset.
[Definition: A
frequent requirement is to output a result tree as an XML document
(or in other formats such as HTML). This process is referred to as
serialization.]
Like parsing, serialization is not part of the transformation
process, and it is not required that an
XSLT processor must be able to perform
serialization. However, for pragmatic reasons, this specification
describes declarations (the xsl:output element and the
xsl:character-map
declarations, see 20
Serialization) which allow a stylesheet to specify the desired
properties of a serialized output file. When serialization is
not being performed, either because the implementation does not
support the serialization option, or because the user is executing
the transformation in a way that does not invoke serialization, then
the content of the xsl:output and xsl:character-map
declarations has no effect. Under these circumstances the processor
may report any errors in an xsl:output or xsl:character-map
declaration, but is not required to do
so.
2.7
Extensibility
XSLT defines a number of features that allow the language to be
extended by implementers, or, if implementers choose to provide the
capability, by users. These features have been designed, so far as
possible, so that they can be used without sacrificing
interoperability. Extensions other than those explicitly defined in
this specification are not permitted.
These features are all based on XML namespaces; namespaces are
used to ensure that the extensions provided by one implementer do not
clash with those of a different implementer.
The most common way of extending the language is by providing
additional functions, which can be invoked from XPath expressions.
These are known as extension functions, and are described
in 18.1 Extension
Functions.
It is also permissible to extend the language by providing new
XSLT instructions. These are referred to as extension
instructions, and are described in 18.2 Extension Instructions. A
stylesheet that uses extension instructions must declare that it is
doing so by using the [xsl:]extension-element-prefixes
attribute.
Extension instructions and extension functions defined according
to these rules may be provided by the
implementer of the XSLT processor, and the implementer may also provide facilities to allow users to create
further extension instructions and extension functions.
This specification defines how extension instructions and
extension functions are invoked, but the facilities for creating new
extension instructions and extension functions are implementation-defined. For further
details, see 18 Extensibility and
Fallback.
The XSLT language can also be extended by the use of extension
attributes (see 3.3 Extension
Attributes), and by means of user-defined data
elements (see 3.6.1
User-defined Data Elements).
2.8 Stylesheets and Schemas
An XSLT stylesheet
can make use of information from a schema. An XSLT transformation can
take place in the absence of a schema (and, indeed, in the absence of
a DTD), but where the source document has undergone schema validity
assessment, the XSLT processor has access to the type information
associated with individual nodes, not merely to the
untyped text.
Information from a schema can be used both statically (when the
stylesheet is
compiled), and dynamically (during evaluation of the stylesheet to
transform a source document).
There are places within a stylesheet, and within XPath expressions and patterns in a
stylesheet, where
it is possible to refer to named type definitions in a schema,
or to element and attribute declarations. For example, it is
possible to declare the types expected for the parameters of a
function. This is done using the SequenceType
XP syntax defined in [XPath
2.0].
[Definition: Type definitions and element and attribute
declarations are referred to collectively as schema
components.]
[Definition: The schema components that may be
referenced by name in a stylesheet are referred to as the in-scope
schema components. This set is the same throughout a
stylesheet.]
The conformance rules for XSLT 2.0, defined in 21 Conformance, distinguish between a
basic
XSLT processor and a schema-aware XSLT processor. As
the names suggest, a basic XSLT processor does not support the
features of XSLT that require access to schema information, either
statically or dynamically. A stylesheet that works with a basic XSLT
processor will work unchanged with a schema-aware XSLT
processor, unless the type information created as a result of schema
processing introduces type errors (for example, an attribute of type
xs:integer cannot be used as an argument of the concat
FO function), or unless the type information
changes the outcome of operations such as comparison and
sorting.
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.12 Built-in Types. The set of built-in
types varies between a basic XSLT processor and a schema-aware XSLT
processor.
The remainder of this section describes facilities that are
available only with a schema-aware XSLT
processor.
Additional schema components (type definitions,
element declarations, and attribute declarations) may be added to the
in-scope schema components by
means of the xsl:import-schema
declaration in a stylesheet.
It is only necessary to import a schema explicitly if one or
more of its schema components are referenced
explicitly by name in the stylesheet; it is not necessary to import a
schema merely because the stylesheet is used to process a source
document that has been assessed against that schema. It is possible
to make use of the information resulting from schema assessment (for
example, the fact that a particular attribute holds a date) even if
no schema has been imported by the stylesheet.
Further, importing a schema does not of itself say anything about
the type of the source document that the stylesheet is expected to process. The imported
type definitions can be used for temporary nodes or for nodes on the
result tree just as much as for nodes in source documents. It
is possible to make assertions about the type of an input document by
means of tests within the stylesheet. For example:
<xsl:template match="document-node(element(my:invoice))" priority="2">
. . .
</xsl:template>
<xsl:template match="document-node()" priority="1">
<xsl:message terminate="yes">Source document is not an invoice</xsl:message>
</xsl:template>
This example will cause the transformation to fail with an error
message unless the document element of the source document is valid
against the top-level element declaration my:invoice,
and has been annotated as such.
It is possible that a source document may contain nodes whose type
annotation is not one of the types imported by the stylesheet. This
creates a potential problem because in the case of an expression such
as data(.) instance of xs:integer the system needs to
know whether the type named in the type annotation of the context
node is derived by restriction from the type xs:integer.
This information is not explicitly available in the data model, as
defined in [Data Model]. The implementation
may choose one of several strategies for dealing with this
situation:
-
The processor may signal a non-recoverable dynamic error if a
source document is found to contain a type annotation that is not
known to the processor.
-
The processor may maintain additional metadata, beyond that
described in [Data Model], that allows
the source document to be processed as if all the necessary
schema information had been imported using xsl:import-schema. Such
metadata might be held in the data model 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 input data model
as if no schema processing had been performed, that is,
effectively to strip all type annotations from elements and
attributes on input, marking them instead as having type
xdt:untypedAny and xdt:untypedAtomic
respectively.
Where a stylesheet author chooses to make assertions about the
types of nodes or of variables and parameters, it is possible for an XSLT processor
to perform static analysis of the stylesheet (that is, analysis in the absence of
any source document). Such analysis may
reveal errors that would otherwise not be discovered until the
transformation is actually executed. An XSLT processor is not
required to perform such static
type-checking. Under some circumstances (see 2.9 Error Handling) type errors that are
detected early may be reported as static
errors. In addition an implementation may
report any condition found during static analysis as a warning,
provided that this does not prevent the stylesheet being evaluated as
described by this specification.
A stylesheet can
also control the type annotations of nodes that it constructs in a
final result tree, or in temporary trees. This can be done in a
number of ways.
-
It is possible to request explicit validation of a complete
result tree. Validation is either strict or lax, as described in
[XML Schema]. If validation of a result
tree fails (strictly speaking, if the outcome of the validity
assessment is invalid), then the transformation
fails, but 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 annotations will be
discarded if the result tree is serialized as an XML document,
but they remain available when the result tree is passed to an
application (perhaps another stylesheet) for further processing.
-
It is also possible to validate individual element and
attribute nodes as they are constructed. This is done using the
type and validation attributes of the
xsl:element, xsl:attribute, xsl:copy, and xsl:copy-of instructions, or
the xsl:type and xsl:validation
attributes of a literal result element.
-
When elements, attributes, or document nodes are
copied, either explicitly using the xsl:copy or xsl:copy-of instructions, or
implicitly when nodes in a sequence are attached to a new parent
node, the options validation="strip" and
validation="preserve" are available, to control
whether existing type annotations are to be retained or not.
When nodes in a temporary tree are validated, type information is
available for use by operations carried out on the temporary tree, in
the same way as for a source document that has undergone schema
assessment.
For details of how validation of element and attribute nodes
works, see 19.2 Validation.
2.9 Error Handling
[Definition: An
error that is detected by examining a stylesheet before execution starts (that is,
before the source document and values of stylesheet parameters are
available) is referred to as a static error.]
Errors classified in this specification as static errors
must be signaled by all implementations:
that is, the processor
must indicate that the error is present. A
static error must be signaled even if it
occurs in a part of the stylesheet that is never evaluated. Static
errors are never recoverable. After signaling a static error, a
processor may continue for the purpose of
signaling additional errors, but it must
eventually terminate abnormally without producing any result
tree.
There is an exception to this rule when the stylesheet specifies
forwards-compatible behavior
(see 3.9 Forwards-Compatible
Processing).
Generally, errors in the structure of the stylesheet, or in the syntax of XPath
expressions contained
in the stylesheet, are classified as static errors. Where this specification states
that an element in the stylesheet must or
must not appear in a certain position, or
that it must or must
not have a particular attribute, or that an attribute
must or must not
have a value satisfying specified conditions, then any contravention
of this rule is a static error unless otherwise specified.
[Definition: An
error that is not detected until a source document is being
transformed is referred to as a dynamic error.]
[Definition: Some dynamic errors are classed as
recoverable errors. When a recoverable error occurs, this
specification allows the processor either to signal the error (by
reporting the error condition and terminating execution) or to take a
defined recovery action and continue processing.] It is implementation-defined whether the
error is signaled or the recovery action is taken.
[Definition: If an implementation chooses to
recover from a recoverable dynamic error, it
must take the optional recovery
action defined for that error condition in this
specification.]
When the implementation makes the choice between signaling a
dynamic error or recovering, it is not restricted in how it makes the
choice; for example, it may provide options
that can be set by the user. When an implementation chooses to
recover from a dynamic error, it may also take other action, such as logging a
warning message.
[Definition: A dynamic error that is not recoverable is
referred to as a non-recoverable dynamic error. When a
non-recoverable dynamic error occurs, the processor must signal the error, and the
transformation fails.]
Because different implementations may optimize execution of the
stylesheet in
different ways, the detection of dynamic errors is to some degree
implementation-dependent. In cases
where an implementation is able to produce the result tree without
evaluating a particular construct, the implementation is never
required to evaluate that construct solely
in order to determine whether doing so causes a dynamic error. For
example, if a variable is
declared but never referenced, an implementation may choose whether or not to evaluate the variable
declaration, which means that if evaluating the variable declaration
causes a dynamic error, some implementations will signal this error
and others will not.
There are some cases where this specification requires that a
construct must not be evaluated: for
example, the content of an xsl:if instruction must not be evaluated if the test condition is false.
This means that an implementation must not
signal any dynamic errors that would arise if the construct were
evaluated.
An implementation may signal a dynamic error before any
source document is available, but only if it can determine that the
error would be signaled for every possible source document and every
possible set of parameter values. For example, some circularity errors fall into this category: see
9.8 Circular Definitions.
The XPath specification states, in effect, that an XPath processor
may evaluate a constant subexpression during the analysis phase, and
if any error occurs during that evaluation, it may report this as a
static error. For XPath expressions used in an XSLT stylesheet,
however, any such errors must not be
reported as static errors in the stylesheet; instead, they must be
held back until the evaluation phase, and signaled only if the XPath
expression is actually evaluated.
An XPath processor may report statically that the expression
1 div 0 fails with a "divide by zero" error. But
suppose this XPath expression occurs in an XSLT construct such
as:
<xsl:choose>
<xsl:when test="system-property('xsl:version') = '1.0'">
<xsl:value-of select="1 div 0"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="xs:double('+INF')"/>
</xsl:otherwise>
</xsl:choose>
Then the XSLT processor must not report an error, because the
relevant XPath construct appears in a context where it will never
be executed by an XSLT 2.0 processor. (An XSLT 1.0 processor will
execute this code successfully, returning positive infinity,
because it uses double arithmetic rather than decimal
arithmetic.)
[Definition: Certain
errors are classified as type errors. A type error occurs when
the value supplied as input to an operation is of the wrong type for
that operation, for example when an integer is supplied to an
operation that expects a node.] If a
type error occurs in an instruction that is actually evaluated, then
it must be signaled in the same way
as a non-recoverable dynamic error.
Alternatively, an implementation may signal
a type error during the analysis phase in the same way as a
static error,
even if it occurs in part of the stylesheet that is never evaluated,
provided it can establish that execution of a particular construct
would never succeed.
It is implementation-defined whether type
errors are signaled statically.
For example, the following construct contains a type error,
because 42 is not allowed as an operand of the
xsl:apply-templates
instruction. An implementation may
optionally signal this as a static error, even though the offending
instruction will never be evaluated, and the type error would
therefore never be signaled as a dynamic error.
<xsl:if test="false()">
<xsl:apply-templates select="42"/>
</xsl:if>
On the other hand, in the following example it is not possible
to determine statically whether the operand of xsl:apply-templates
will have a suitable dynamic type. An implementation may produce a warning in such cases, but it
must not treat it as an error.
<xsl:template match="para">
<xsl:param name="p" as="item()"/>
<xsl:apply-templates select="$p"/>
</xsl:template>
If more than one error arises, an implementation is not
required to signal any errors other than
the first one that it detects. It is implementation-dependent which of
the several errors is signaled. This applies both to static errors
and to dynamic errors. An implementation is allowed to signal more
than one error, but if any errors have been signaled, it must not finish as if the transformation were
successful.
When a transformation signals one or more dynamic errors, the
final state of any persistent resources updated by the transformation
is implementation-dependent.
Implementations are not required to restore
such resources to their initial state. In particular, where a
transformation produces multiple result documents, it is possible
that one or more 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 result tree, it is still possible that errors may occur in
serializing the result tree. For example, it may be impossible to
serialize the result tree using the encoding selected by the user.
Such an error is referred to as a serialization
error.] As with other aspects of
serialization, the handling of serialization errors is implementation-defined: see 20 Serialization.
The error codes used to label error conditions in this
specification (and summarized in E
Summary of Error Conditions) are provided for ease of
reference. Implementations may use these
codes when signaling errors, but they are not required to do so. An implementation that uses these
codes within an API should treat the codes
as unprefixed QNames; additional codes defined by an implementation
(or by an application) can then use QNames in an
implementation-defined namespace without risk of collision.