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 using an XSLT stylesheet is referred to as the
processor. This is sometimes expanded to XSLT
processor to avoid any confusion with other
processors, for example an XML processor.]
[Definition: A specific product that performs the
functions of an XSLT processor is referred to as an
implementation ].
[Definition: The term result tree is used to
refer to any tree constructed by instructions in the stylesheet.
A result tree is either a final result tree or a
temporary tree.]
[Definition: A final result tree is a
result
tree that forms part of the final output of a
transformation. Once created, the contents of a final
result tree are not accessible within the stylesheet
itself.] The xsl:result-document
instruction always creates a final result tree, and a final
result tree may also be created implicitly by the initial
template. The conditions under which this happens are
described in 2.4
Executing a Transformation. A final result tree
may be serialized as described in
20 Serialization.
[Definition: The term source tree means any
tree provided as input to the transformation. This includes
the document containing the initial context node if
any, documents containing nodes supplied as the values of
stylesheet parameters,
documents obtained from the results of functions such as
document,
doc
FO, and
collectionFO, and
documents returned by extension functions or extension
instructions. In the context of a particular XSLT
instruction, the term source tree means any tree
provided as input to that instruction; this may be a source
tree of the transformation as a whole, or it may be a
temporary tree produced during the
course of the transformation.]
[Definition: The term temporary tree means
any tree that is neither a source tree nor a final
result tree.] Temporary
trees are used to hold intermediate results during the
execution of the transformation.
In this specification the phrases must, must not,
should, should
not, may, required, and recommended are to be interpreted as
described in [RFC2119].
Where the phrase must,
must not, or required relates to the behavior of the XSLT
processor, then an implementation is not conformant unless
it behaves as specified, subject to the more detailed rules
in 21 Conformance.
Where the phrase must,
must not, or required relates to a stylesheet, then the
processor must enforce this
constraint on stylesheets by reporting an error if the
constraint is not satisfied.
Where the phrase should,
should not, or recommended relates to a stylesheet, then a
processor may produce warning
messages if the constraint is not satisfied, but
must not treat this as an
error.
[Definition: In this specification,
the term implementation-defined refers to a feature
where the implementation is allowed some flexibility, and
where the choices made by the implementation must be described in documentation that
accompanies any conformance claim.]
[Definition: The term
implementation-dependent refers to a feature where
the behavior may vary from one
implementation to another, and where the vendor is not
expected to provide a full specification of the
behavior.] (This might
apply, for example, to limits on the size of source
documents that can be transformed.)
In all cases where this specification leaves the
behavior implementation-defined or
implementation-dependent, the implementation has the option
of providing mechanisms that allow the user to influence
the behavior.
A paragraph labeled as a Note or described as an
example is non-normative.
Many terms used in this document are defined in the
XPath specification [XPath 2.0] or
the XDM specification [Data
Model]. Particular attention is drawn to the
following:
-
[Definition: The term atomization is defined in
Section
2.4.2 AtomizationXP. It
is a process that takes as input a sequence of nodes
and atomic values, and returns a sequence of atomic
values, in which the nodes are replaced by their typed
values as defined in [Data
Model].] For some
nodes (for example, elements with element-only
content), atomization generates a dynamic
error.
-
[Definition: The term typed value is
defined in Section
5.15 typed-value
AccessorDM. Every node
except an element defined in the schema with
element-only content has a typed value. For example,
the typed
value of an attribute of type
xs:IDREFS is a sequence of zero or more
xs:IDREF values.]
-
[Definition: The term string value is
defined in
Section 5.13 string-value
AccessorDM. Every node
has a string value. For example, the
string
value of an element is the concatenation of the
string
values of all its descendant text
nodes.]
-
[Definition: The term
XPath 1.0 compatibility mode is defined in
Section
2.1.1 Static ContextXP.
This is a setting in the static context of an XPath
expression; it has two values, true and
false. When the value is set to true, the
semantics of function calls and certain other
operations are adjusted to give a greater degree of
backwards compatibility between XPath 2.0 and XPath
1.0.]
[Definition: The term core function means a
function that is specified in [Functions and Operators] and that
is in the standard function
namespace.]
2.2 Notation
[Definition: An XSLT element is an element in
the XSLT namespace whose syntax and
semantics are defined in this specification.] For a non-normative list of XSLT
elements, see D
Element Syntax Summary.
In this document the specification of each XSLT element is
preceded by a summary of its syntax in the form of a model
for elements of that element type. A full list of all these
specifications can be found in D Element Syntax
Summary. The meaning of syntax summary notation is
as follows:
-
An attribute that is required is shown with its name in bold.
An attribute that may be omitted is shown with a
question mark following its name.
-
An attribute that is deprecated is shown in a grayed
font within square brackets.
-
The string that occurs in the place of an attribute
value specifies the allowed values of the attribute. If
this is surrounded by curly brackets
({...}), then the attribute value is
treated as an attribute value
template, and the string occurring within curly
brackets specifies the allowed values of the result of
evaluating the attribute value template. Alternative
allowed values are separated by |. A
quoted string indicates a value equal to that specific
string. An unquoted, italicized name specifies a
particular type of value.
In all cases where this specification states that
the value of an attribute must be one of a limited set of values,
leading and trailing whitespace in the attribute value
is ignored. In the case of an attribute value
template, this applies to the effective
value obtained when the attribute value template is
expanded.
-
Unless the element is required to be empty, the model element
contains a comment specifying the allowed content. The
allowed content is specified in a similar way to an
element type declaration in XML; sequence
constructor means that any mixture of text nodes,
literal result
elements, extension instructions,
and XSLT elements from the instruction
category is allowed; other-declarations means
that any mixture of XSLT elements from the declaration
category, other than xsl:import, is
allowed, together with user-defined data elements.
-
The element is prefaced by comments indicating if it
belongs to the instruction category or
declaration category or both. The category
of an element only affects whether it is allowed in the
content of elements that allow a sequence constructor or
other-declarations.
This example illustrates the notation used to describe
XSLT
elements.
<!-- Category:
instruction -->
<xsl:example-element
select = expression
debug? = { "yes" | "no" }>
<!-- Content: ((xsl:variable | xsl:param)*, xsl:sequence) -->
</xsl:example-element>
This example defines a (non-existent) element
xsl:example-element. The element is
classified as an instruction. It takes a mandatory
select attribute, whose value is an XPath
expression, and an optional
debug attribute, whose value must be either yes or
no; the curly brackets indicate that the
value can be defined as an attribute value
template, allowing a value such as
debug="{$debug}", where the variable
debug is evaluated to yield
"yes" or "no" at run-time.
The content of an xsl:example-element
instruction is defined to be a sequence of zero or more
xsl:variable
and xsl:param
elements, followed by an xsl:sequence
element.
[ERR XTSE0010] A static error is signaled if an
XSLT-defined element is used in a context where it is not
permitted, if a required
attribute is omitted, or if the content of the element does
not correspond to the content that is allowed for the
element.
Attributes are validated as follows. These rules apply
to the value of the attribute after removing leading and
trailing whitespace.
-
[ERR
XTSE0020] It is a static error if an
attribute (other than an attribute written using curly
brackets in a position where an attribute value
template is permitted) contains a value that is not
one of the permitted values for that attribute.
-
[ERR
XTDE0030] It is a non-recoverable dynamic
error if the effective value of an
attribute written using curly brackets, in a position
where an attribute value
template is permitted, is a value that is not one
of the permitted values for that attribute. If the
processor is able to detect the error statically (for
example, when any XPath expressions within the curly
brackets can be evaluated statically), then the
processor may optionally signal this as a static
error.
Special rules apply if the construct appears in part of
the stylesheet that is processed with
forwards-compatible
behavior: see 3.9
Forwards-Compatible Processing.
[Definition: Some constructs defined in this
specification are described as being deprecated. The
use of this term implies that stylesheet authors
should not use the construct, and
that the construct may be removed in a later version of
this specification.] All
constructs that are deprecated in this specification are
also (as it happens) optional features that implementations are not required to provide.
XSLT defines a set of standard functions which are
additional to those defined in [Functions and Operators]. The
signatures of these functions are described using the same
notation as used in [Functions
and Operators]. The names of these functions are all in
the standard function
namespace.
2.3 Initiating
a Transformation
This document does not specify any application
programming interfaces or other interfaces for initiating a
transformation. This section, however, describes the
information that is supplied when a transformation is
initiated. Except where otherwise indicated, the
information is required.
Implementations may allow a
transformation to run as two or more phases, for example
parsing, compilation and execution. Such a distinction is
outside the scope of this specification, which treats
transformation as a single process controlled using a set
of stylesheet modules, supplied in
the form of XML documents.
The following information is supplied to execute a
transformation:
-
The stylesheet module that is
to act as the principal
stylesheet module for the transformation. The
complete stylesheet is assembled by
recursively expanding the xsl:import and
xsl:include
declarations in the principal stylesheet module, as
described in 3.10.2 Stylesheet
Inclusion and 3.10.3
Stylesheet Import.
-
A set (possibly empty) of values for stylesheet parameters
(see 9.5 Global
Variables and Parameters). These values are
available for use within expressions in the stylesheet.
-
[Definition: A node that acts as
the initial context node for the transformation.
This node is accessible within the stylesheet as
the initial value of the XPath expressions .
(dot) and self::node(), as described in
5.4.3.1 Maintaining Position: the
Focus].
If no initial context node is supplied, then the
context
item, context position, and
context
size will initially be undefined, and the
evaluation of any expression that references these
values will result in a dynamic error. (Note that the
initial context size and context position will always
be 1 (one) when an initial context node is supplied,
and will be undefined if no initial context node is
supplied).
-
Optionally, the name of a named template which is
to be executed as the entry point to the
transformation. This template must exist within the stylesheet. If
no named template is supplied, then the transformation
starts with the template rule that best matches
the initial context node,
according to the rules defined in 6.4 Conflict Resolution for Template
Rules. Either a named template, or an initial
context node, or both, must
be supplied.
-
Optionally, an initial mode. This must either be the default mode, or a
mode that is explicitly named in the mode
attribute of an xsl:template
declaration within the stylesheet. If an initial
mode is supplied, then in searching for the template
rule that best matches the initial context node,
the processor considers only those rules that apply to
the initial mode. If no initial mode is supplied, the
default
mode is used.
-
A base output URI. [Definition: The base output URI is a
URI to be used as the base URI when resolving a
relative URI allocated to a final
result tree. If the transformation generates more
than one final result tree, then typically each one
will be allocated a URI relative to this base URI.
] The way in
which a base output URI is established is implementation-defined.
-
A mechanism for obtaining a document node and a
media type, given an absolute URI. The total set of
available documents (modeled as a mapping from URIs to
document nodes) forms part of the context for
evaluating XPath expressions, specifically the doc
FO function. The XSLT document function
additionally requires the media type of the resource
representation, for use in interpreting any fragment
identifier present within a URI Reference.
Note:
The set of documents that are available to the
stylesheet is implementation-dependent,
as is the processing that is carried out to construct
a tree representing the resource retrieved using a
given URI. Some possible ways of constructing a
document (specifically, rules for constructing a
document from an Infoset or from a PSVI) are
described in [Data
Model].
[ERR XTDE0040] It is a non-recoverable dynamic
error if the invocation of the stylesheet specifies a template
name that does not match the expanded-QName of a named
template defined in the stylesheet.
[ERR XTDE0045] It is a non-recoverable dynamic
error if the invocation of the stylesheet specifies an initial
mode (other than the
default mode) that does not match the expanded-QName in the
mode attribute of any template defined in the
stylesheet.
[ERR XTDE0047] It is a non-recoverable dynamic
error if the invocation of the stylesheet specifies both an
initial mode and an
initial template.
[ERR XTDE0050] It is a non-recoverable dynamic
error if the stylesheet that is invoked declares a
visible stylesheet parameter with
required="yes" and no value for this parameter
is supplied during the invocation of the stylesheet. A
stylesheet parameter is visible if it is not masked by
another global variable or parameter with the same name and
higher import precedence.
[Definition: The transformation is performed by
evaluating an initial template. If a named
template is supplied when the transformation is
initiated, then this is the initial template;
otherwise, the initial template is the template rule
selected according to the rules of the xsl:apply-templates
instruction for processing the initial context node in the
initial mode.]
Parameters passed to the transformation by the client
application are matched against stylesheet parameters (see
9.5 Global Variables and
Parameters), not against the template
parameters declared within the initial
template. All template parameters within the
initial template to be executed will take their default
values.
[ERR XTDE0060] It is a non-recoverable dynamic
error if the initial template defines a
template parameter that
specifies required="yes".
A stylesheet can process further source
documents in addition to those supplied when the
transformation is invoked. These additional documents can
be loaded using the functions document (see
16.1 Multiple Source
Documents) or doc
FO or
collectionFO (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 three parts: a
pattern that is
matched against nodes, a (possibly empty) set of template
parameters, and a sequence constructor that is
evaluated to produce a sequence of items.] In many cases these items are newly
constructed nodes, which are then written to a result tree.
A transformation as a whole is executed by evaluating
the sequence constructor of the
initial template as described in
5.7 Sequence
Constructors.
If the initial template has an as
attribute, then the result sequence of the initial template
is checked against the required type in the same way as for
any other template. If this result sequence is non-empty,
then it is used to construct an implicit final
result tree, following the rules described in 5.7.1 Constructing
Complex Content: the effect is as if the initial
template T were called by an implicit template
of the form:
<xsl:template name="IMPLICIT">
<xsl:result-document href="">
<xsl:call-template name="T"/>
</xsl:result-document>
</xsl:template>
An implicit result tree is also created when the result
sequence is empty, provided that no xsl:result-document
instruction has been evaluated during the course of the
transformation. In this situation the implicit result tree
will consist of a document node with no children.
Note:
This means that there is always at least one result
tree. It also means that if the content of the initial
template is a single xsl:result-document
instruction, as in the example above, then only one
result tree is produced, not two. It is useful to make
the result document explicit as this is the only way of
invoking document-level validation.
If the result of the initial template is non-empty,
and an explicit xsl:result-document
instruction has been evaluated with the empty attribute
href="", then an error will occur
[see ERR
XTDE1490], since it is not possible to create
two final result trees with the same URI.
A sequence constructor is a
sequence of sibling nodes in the stylesheet, each of which
is either an XSLT instruction, a literal result element, a
text node, or an extension instruction.
[Definition: An instruction is either an
XSLT instruction or an extension
instruction.]
[Definition: An XSLT instruction is an
XSLT
element whose syntax summary in this specification
contains the annotation <!-- category: instruction
-->.]
Extension instructions are
described in 18.2
Extension Instructions.
The main categories of XSLT instruction are as
follows:
-
instructions that create new nodes: xsl:document,
xsl:element,
xsl:attribute,
xsl:processing-instruction,
xsl:comment,
xsl:value-of,
xsl:text,
xsl:namespace;
-
an instruction that returns an arbitrary sequence by
evaluating an XPath expression: xsl:sequence;
-
instructions that cause conditional or repeated
evaluation of nested instructions: xsl:if, xsl:choose, xsl:for-each,
xsl:for-each-group;
-
instructions that invoke templates: xsl:apply-templates,
xsl:apply-imports,
xsl:call-template,
xsl:next-match;
-
Instructions that declare variables: xsl:variable,
xsl:param;
-
other specialized instructions: xsl:number, xsl:analyze-string,
xsl:message,
xsl:result-document.
Often, a sequence constructor will
include an xsl:apply-templates
instruction, which selects a sequence of nodes to be
processed. Each of the selected nodes is processed by
searching the stylesheet for a matching template rule
and evaluating the sequence constructor of that
template rule. The resulting sequences of items are
concatenated, in order, to give the result of the xsl:apply-templates
instruction, as described in 6.3 Applying Template
Rules; this sequence is often added to a result tree. Since
the sequence constructors of the
selected template rules may themselves
contain xsl:apply-templates
instructions, this results in a cycle of selecting nodes,
identifying template rules, constructing
sequences, and constructing result trees, that recurses through a
source
tree.
2.5 The Evaluation
Context
The results of some expressions and instructions in a
stylesheet may depend on information provided contextually.
This context information is divided into two categories:
the static context, which is known during static analysis
of the stylesheet, and the dynamic context, which is not
known until the stylesheet is evaluated. Although
information in the static context is known at analysis
time, it is sometimes used during stylesheet
evaluation.
Some context information can be set by means of
declarations within the stylesheet itself. For example, the
namespace bindings used for any XPath expression are
determined by the namespace declarations present in
containing elements in the stylesheet. Other information
may be supplied externally or implicitly: an example is the
current date and time.
The context information used in processing an XSLT
stylesheet includes as a subset all the context information
required when evaluating XPath expressions. The XPath 2.0
specification defines a static and dynamic context that the
host language (in this case, XSLT) may initialize, which
affects the results of XPath expressions used in that
context. XSLT augments the context with additional
information: this additional information is used firstly by
XSLT constructs outside the scope of XPath (for example,
the xsl:sort
element), and secondly, by functions that are defined in
the XSLT specification (such as key and format-number)
that are available for use in XPath expressions appearing
within a stylesheet.
The static context for an expression or other construct
in a stylesheet is determined by the place in which it
appears lexically. The details vary for different
components of the static context, but in general, elements
within a stylesheet module affect the static context for
their descendant elements within the same stylesheet
module.
The dynamic context is maintained as a stack. When an
instruction or expression is evaluated, it may add dynamic
context information to the stack; when evaluation is
complete, the dynamic context reverts to its previous
state. An expression that accesses information from the
dynamic context always uses the value at the top of the
stack.
The most commonly used component of the dynamic context
is the context item. This is an implicit
variable whose value is the item (it may be a node or an
atomic value) currently being processed. The value of the
context item can be referenced within an XPath expression
using the expression . (dot).
Full details of the static and dynamic context are
provided in 5.4
The Static and Dynamic Context.
2.6 Parsing and
Serialization
An XSLT stylesheet describes a process that
constructs a set of final result trees from a set
of source
trees.
The stylesheet does not describe how a
source
tree is constructed. Some possible ways of
constructing source trees are described in [Data Model]. Frequently an
implementation will operate in
conjunction with an XML parser (or more strictly, in the
terminology of [XML 1.0], an XML
processor), to build a source tree from an input XML
document. An implementation may
also provide an application programming interface allowing
the tree to be constructed directly, or allowing it to be
supplied in the form of a DOM Document object (see [DOM Level 2]). This is outside the
scope of this specification. Users should be aware,
however, that since the input to the transformation is a
tree conforming to the XDM data model as
described in [Data Model],
constructs that might exist in the original XML document,
or in the DOM, but which are not within the scope of the
data model, cannot be processed by the stylesheet and
cannot be guaranteed to remain unchanged in the
transformation output. Such constructs include CDATA
section boundaries, the use of entity references, and the
DOCTYPE declaration and internal DTD subset.
[Definition: A frequent requirement is to output a
final result tree as an XML
document (or in other formats such as HTML). This process
is referred to as serialization.]
Like parsing, serialization is not part of the
transformation process, and it is not required that an XSLT processor must be able to perform serialization.
However, for pragmatic reasons, this specification
describes declarations (the xsl:output element and
the xsl:character-map
declarations, see 20
Serialization), and attributes on the xsl:result-document
instruction, that allow a stylesheet to specify the desired
properties of a serialized output file. When
serialization is not being performed, either because the
implementation does not support the serialization option,
or because the user is executing the transformation in a
way that does not invoke serialization, then the content of
the xsl:output
and xsl:character-map
declarations has no effect. Under these circumstances the
processor may report any errors
in an xsl:output
or xsl:character-map
declaration, or in the serialization attributes of xsl:result-document,
but is not required to do so.
2.7
Extensibility
XSLT defines a number of features that allow the
language to be extended by implementers, or, if
implementers choose to provide the capability, by users.
These features have been designed, so far as possible, so
that they can be used without sacrificing interoperability.
Extensions other than those explicitly defined in this
specification are not permitted.
These features are all based on XML namespaces;
namespaces are used to ensure that the extensions provided
by one implementer do not clash with those of a different
implementer.
The most common way of extending the language is by
providing additional functions, which can be invoked from
XPath expressions. These are known as extension functions, and are
described in 18.1
Extension Functions.
It is also permissible to extend the language by
providing new instructions. These are referred to
as extension instructions, and
are described in 18.2
Extension Instructions. A stylesheet that uses
extension instructions must declare that it is doing so by
using the [xsl:]extension-element-prefixes
attribute.
Extension instructions and extension functions defined
according to these rules may be
provided by the implementer of the XSLT processor, and the
implementer may also provide
facilities to allow users to create further extension
instructions and extension functions.
This specification defines how extension instructions
and extension functions are invoked, but the facilities for
creating new extension instructions and extension functions
are implementation-defined.
For further details, see 18
Extensibility and Fallback.
The XSLT language can also be extended by the use of
extension attributes (see
3.3 Extension
Attributes), and by means of user-defined data elements (see
3.6.2 User-defined
Data Elements).
2.8 Stylesheets and
XML Schemas
An XSLT stylesheet can make use of information
from a schema. An XSLT transformation can take place in the
absence of a schema (and, indeed, in the absence of a DTD),
but where the source document has undergone schema validity
assessment, the XSLT processor has access to the type
information associated with individual nodes, not merely to
the untyped text.
Information from a schema can be used both statically
(when the stylesheet is compiled), and
dynamically (during evaluation of the stylesheet to
transform a source document).
There are places within a stylesheet, and within XPath expressions and
patterns in a
stylesheet,
where it is possible to refer to named type definitions in
a schema, or to element and attribute declarations. For
example, it is possible to declare the types expected for
the parameters of a function. This is done using the
SequenceType
XP syntax defined in [XPath 2.0].
[Definition: Type definitions and element and
attribute declarations are referred to collectively as
schema components.]
[Definition: The schema
components that may be referenced by name in a
stylesheet
are referred to as the in-scope schema components.
This set is the same throughout all the modules of a
stylesheet.]
The conformance rules for XSLT 2.0, defined in 21 Conformance, distinguish
between a basic XSLT processor and a
schema-aware XSLT
processor. As the names suggest, a basic XSLT processor
does not support the features of XSLT that require access
to schema information, either statically or dynamically. A
stylesheet
that works with a basic XSLT processor will produce the
same results with a schema-aware XSLT processor
provided that the source documents are untyped (that
is, they are not validated against a schema). However, if
source documents are validated against a schema then the
results may be different from the case where they are not
validated. Some constructs that work on untyped data may
fail with typed data (for example, an attribute of type
xs:date cannot be used as an argument of the
substringFO function)
and other constructs may produce different results
depending on the data type (for example, given the element
<product price="10.00"
discount="2.00"/>, the expression @price gt
@discount will return true if the attributes have
type xs:decimal, but will return false if they
are untyped).
There is a standard set of type definitions that are
always available as in-scope schema
components in every stylesheet. These are defined in
3.13 Built-in Types.
The set of built-in types varies between a basic XSLT processor and a
schema-aware XSLT
processor.
The remainder of this section describes facilities that
are available only with a schema-aware XSLT
processor.
Additional schema components (type
definitions, element declarations, and attribute
declarations) may be added to the in-scope schema
components by means of the xsl:import-schema
declaration in a stylesheet.
The xsl:import-schema
declaration may reference an external schema document by
means of a URI, or it may contain an inline
xs:schema element.
It is only necessary to import a schema explicitly if
one or more of its schema components are referenced
explicitly by name in the stylesheet; it is not necessary
to import a schema merely because the stylesheet is used to
process a source document that has been assessed against
that schema. It is possible to make use of the information
resulting from schema assessment (for example, the fact
that a particular attribute holds a date) even if no schema
has been imported by the stylesheet.
Further, importing a schema does not of itself say
anything about the type of the source document that the
stylesheet
is expected to process. The imported type definitions can
be used for temporary nodes or for nodes on a result tree just
as much as for nodes in source documents. It is
possible to make assertions about the type of an input
document by means of tests within the stylesheet. For
example:
<xsl:template match="document-node(schema-element(my:invoice))" priority="2">
. . .
</xsl:template>
<xsl:template match="document-node()" priority="1">
<xsl:message terminate="yes">Source document is not an invoice</xsl:message>
</xsl:template>
This example will cause the transformation to fail
with an error message unless the document element of the
source document is valid against the top-level element
declaration my:invoice, and has been
annotated as such.
It is possible that a source document may contain nodes
whose type
annotation is not one of the types imported by the
stylesheet. This creates a potential problem because in the
case of an expression such as data(.) instance of
xs:integer the system needs to know whether the type
named in the type annotation of the context node is derived
by restriction from the type xs:integer. This
information is not explicitly available in an XDM
tree, as defined in [Data
Model]. The implementation may choose one of several
strategies for dealing with this situation:
-
The processor may signal a non-recoverable dynamic
error if a source document is found to contain a
type
annotation that is not known to the processor.
-
The processor may maintain additional metadata,
beyond that described in [Data Model], that allows the
source document to be processed as if all the necessary
schema information had been imported using xsl:import-schema.
Such metadata might be held in the data structure
representing the source document itself, or it might be
held in a system catalog or repository.
-
The processor may be configured to use a fixed set
of schemas, which are automatically used to validate
all source documents before they can be supplied as
input to a transformation. In this case it is
impossible for a source document to have a type
annotation that the processor is not aware of.
-
The processor may be configured to treat the source
document as if no schema processing had been performed,
that is, effectively to strip all type annotations from
elements and attributes on input, marking them instead
as having type xs:untyped and
xs:untypedAtomic
respectively.
Where a stylesheet author chooses to make assertions
about the types of nodes or of variables and parameters, it is possible for an XSLT
processor to perform static analysis of the stylesheet (that is,
analysis in the absence of any source document). Such
analysis may reveal errors that
would otherwise not be discovered until the transformation
is actually executed. An XSLT processor is not required to perform such static
type-checking. Under some circumstances (see 2.9 Error Handling) type errors that
are detected early may be
reported as static errors. In addition an implementation
may report any condition found
during static analysis as a warning, provided that this
does not prevent the stylesheet being evaluated as
described by this specification.
A stylesheet can also control the
type
annotations of nodes that it constructs in a final
result tree, or in temporary trees. This can be done
in a number of ways.
-
It is possible to request explicit validation of a
complete document, that is, a tree rooted at a document
node. This applies both to temporary trees constructed
using the xsl:document (or
xsl:copy)
instruction and also to final result trees
constructed using xsl:result-document.
Validation is either strict or lax, as described in
[XML Schema Part 1]. If
validation of a result tree fails (strictly
speaking, if the outcome of the validity assessment is
invalid), then the transformation fails,
but in all other cases, the element and attribute nodes
of the tree will be annotated with the names of the
types to which these nodes conform. These type
annotations will be discarded if the result tree is
serialized as an XML document, but they remain
available when the result tree is passed to an
application (perhaps another stylesheet) for further
processing.
-
It is also possible to validate individual element
and attribute nodes as they are constructed. This is
done using the type and
validation attributes of the xsl:element,
xsl:attribute,
xsl:copy, and
xsl:copy-of
instructions, or the xsl:type and
xsl:validation attributes of a literal
result element.
-
When elements, attributes, or document nodes are
copied, either explicitly using the xsl:copy or xsl:copy-of
instructions, or implicitly when nodes in a sequence
are attached to a new parent node, the options
validation="strip" and
validation="preserve" are available, to
control whether existing type annotations are to be
retained or not.
When nodes in a temporary tree are validated, type
information is available for use by operations carried out
on the temporary tree, in the same way as for a source
document that has undergone schema assessment.
For details of how validation of element and attribute
nodes works, see 19.2
Validation.
2.9 Error
Handling
[Definition: An error that is detected by examining a
stylesheet
before execution starts (that is, before the source
document and values of stylesheet parameters are available)
is referred to as a static error.]
Errors classified in this specification as static errors
must be signaled by all
implementations: that is, the processor must indicate that the error is present. A
static error must be signaled
even if it occurs in a part of the stylesheet that is never
evaluated. Static errors are never recoverable. After
signaling a static error, a processor may continue for the purpose of signaling
additional errors, but it must
eventually terminate abnormally without producing any
final result tree.
There is an exception to this rule when the stylesheet
specifies forwards-compatible
behavior (see 3.9
Forwards-Compatible Processing).
Generally, errors in the structure of the stylesheet, or in
the syntax of XPath expressions contained in the
stylesheet, are classified as static errors. Where this
specification states that an element in the stylesheet
must or must
not appear in a certain position, or that it
must or must
not have a particular attribute, or that an
attribute must or must not have a value satisfying specified
conditions, then any contravention of this rule is a static
error unless otherwise specified.
[Definition: An error that is not detected until a
source document is being transformed is referred to as a
dynamic error.]
[Definition: Some dynamic errors are classed as
recoverable errors. When a recoverable error occurs,
this specification allows the processor either to signal
the error (by reporting the error condition and terminating
execution) or to take a defined recovery action and
continue processing.] It is
implementation-defined
whether the error is signaled or the recovery action is
taken.
[Definition: If an implementation chooses
to recover from a recoverable dynamic error, it
must take the optional
recovery action defined for that error condition in
this specification.]
When the implementation makes the choice between
signaling a dynamic error or recovering, it is not
restricted in how it makes the choice; for example, it
may provide options that can be
set by the user. When an implementation chooses to recover
from a dynamic error, it may also take other action, such as
logging a warning message.
[Definition: A dynamic error
that is not recoverable is referred to as a
non-recoverable dynamic error. When a
non-recoverable dynamic error occurs, the processor must signal the error, and the transformation
fails.]
Because different implementations may optimize execution
of the stylesheet in different ways, the
detection of dynamic errors is to some degree implementation-dependent.
In cases where an implementation is able to produce the
final result trees without
evaluating a particular construct, the implementation is
never required to evaluate that
construct solely in order to determine whether doing so
causes a dynamic error. For example, if a variable is declared but
never referenced, an implementation may choose whether or not to evaluate the
variable declaration, which means that if evaluating the
variable declaration causes a dynamic error, some
implementations will signal this error and others will
not.
There are some cases where this specification requires
that a construct must not be
evaluated: for example, the content of an xsl:if instruction
must not be evaluated if the test
condition is false. This means that an implementation
must not signal any dynamic
errors that would arise if the construct were
evaluated.
An implementation may signal a
dynamic
error before any source document is available, but only
if it can determine that the error would be signaled for
every possible source document and every possible set of
parameter values. For example, some circularity errors fall into this
category: see 9.8 Circular
Definitions.
The XPath specification states (see Section
2.3.1 Kinds of ErrorsXP) that
if any expression (at any level) can be evaluated during
the analysis phase (because all its explicit operands are
known and it has no dependencies on the dynamic context),
then any error in performing this evaluation may be reported as a static error. For XPath
expressions used in an XSLT stylesheet, however, any such
errors must not be reported as
static errors in the stylesheet unless they would occur in
every possible evaluation of that stylesheet; instead, they
must be signaled as dynamic errors, and signaled only if
the XPath expression is actually evaluated.
An XPath processor may report statically that the
expression 1 div 0 fails with a "divide by
zero" error. But suppose this XPath expression occurs in
an XSLT construct such as:
<xsl:choose>
<xsl:when test="system-property('xsl:version') = '1.0'">
<xsl:value-of select="1 div 0"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="xs:double('INF')"/>
</xsl:otherwise>
</xsl:choose>
Then the XSLT processor must not report an error,
because the relevant XPath construct appears in a context
where it will never be executed by an XSLT 2.0 processor.
(An XSLT 1.0 processor will execute this code
successfully, returning positive infinity, because it
uses double arithmetic rather than decimal
arithmetic.)
[Definition: Certain errors are classified as type
errors. A type error occurs when the value supplied as
input to an operation is of the wrong type for that
operation, for example when an integer is supplied to an
operation that expects a node.] If a type error occurs in an
instruction that is actually evaluated, then it
must be signaled in the
same way as a non-recoverable dynamic
error. Alternatively, an implementation may signal a type error during the analysis
phase in the same way as a static error, even if it occurs
in part of the stylesheet that is never evaluated, provided
it can establish that execution of a particular construct
would never succeed.
It is implementation-defined
whether type errors are signaled statically.
The following construct contains a type error, because
42 is not allowed as an operand of the
xsl:apply-templates
instruction. An implementation may optionally signal this as a static
error, even though the offending instruction will never
be evaluated, and the type error would therefore never be
signaled as a dynamic error.
<xsl:if test="false()">
<xsl:apply-templates select="42"/>
</xsl:if>
On the other hand, in the following example it is not
possible to determine statically whether the operand of
xsl:apply-templates
will have a suitable dynamic type. An implementation
may produce a warning in such
cases, but it must not treat it
as an error.
<xsl:template match="para">
<xsl:param name="p" as="item()"/>
<xsl:apply-templates select="$p"/>
</xsl:template>
If more than one error arises, an implementation is not
required to signal any errors
other than the first one that it detects. It is implementation-dependent
which of the several errors is signaled. This applies both
to static errors and to dynamic errors. An implementation
is allowed to signal more than one error, but if any errors
have been signaled, it must not
finish as if the transformation were successful.
When a transformation signals one or more dynamic
errors, the final state of any persistent resources updated
by the transformation is implementation-dependent.
Implementations are not required
to restore such resources to their initial state. In
particular, where a transformation produces multiple result
documents, it is possible that one or more serialized
result documents may be written
successfully before the transformation terminates, but the
application cannot rely on this behavior.
Everything said above about error handling applies
equally to errors in evaluating XSLT instructions, and
errors in evaluating XPath expressions. Static errors and dynamic
errors may occur in both cases.
[Definition: If a transformation has
successfully produced a final result tree, it is still
possible that errors may occur in serializing the result
tree. For example, it may be impossible to serialize the
result tree using the encoding selected by the user. Such
an error is referred to as a serialization
error.] If the
processor performs serialization, then it must do so as specified in 20 Serialization, and in
particular it must signal any
serialization errors that occur.
Errors are identified by a QName. For errors defined in
this specification, the namespace of the QName is always
http://www.w3.org/2005/xqt-errors (and is
therefore not given explicitly), while the local part is an
8-character code in the form PPSSNNNN. Here
PP is always XT (meaning XSLT), and
SS is one of SE