This document is a working draft developed and maintained by a W3C Community Group,
the
The community group welcomes comments on the specification. Comments are best submitted
as issues on the group's
The community group maintains two extensive test suites,
one oriented to XQuery and XPath, the other to XSLT.
These can be found at
The publications of this community group
This specification defines the syntax and semantics of XSLT 4.0, a language designed primarily for transforming XML documents into other XML documents, but also offering support for other data formats including JSON, HTML, and CSV.
XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation
XSLT 4.0 is designed to be used in conjunction with XPath 4.0, which is defined in
An optional feature of the XSLT language is support for streamed transformations. The XSLT 4.0 specification has been modularized so that streaming is now described in a separate specification document. This has been done in order to make the specifications more manageable, both for editors and readers: it does not alter the status of streaming as an optional feature, available in some processors and not others.
XSLT is a programming language designed principally to transform data.
A transformation in the XSLT language is expressed in the
form of a
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
The term
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
The transformation is achieved by a set of
Stylesheets are modular; they may contain several packages developed independently of each other, and each package may consist of several stylesheet modules.
XSLT 4.0 is a revised version of the XSLT 3.0 Recommendation
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 items.
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 4.0 requires support for XPath 4.0.
A full list of changes is at
For a full glossary of terms, see
The use of the term
The output of a transformation consists of the following:
Zero or more messages. Messages are generated by the
Static or dynamic errors: see
The
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
Where the phrase
Where the phrase
Where the phrase
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
Many terms used in this document are defined in the XPath specification
xs:IDREFS is a sequence of zero or more
xs:IDREF 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
In this document the specification of each
An attribute that is
An attribute that is
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 |. 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:
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) ...”.
Any string.
An XPath
A
An
A
A URI, for example a namespace URI or a collation URI; a whitespace-separated list of URIs.
A
An
A string containing no significant whitespace; a whitespace-separated list of such strings.
A string conforming to the XML schema rules for the type
xs:NMTOKEN; a whitespace-separated list of such
strings.
A string comprising a single Unicode character.
A string in the value space of xs:language, or a zero-length string.
An integer, that is, a string xs:integer.
A decimal value, that is, a string xs:decimal.
An unprefixed name: a string xs:NCName;
An xs:NCName representing a namespace prefix, which must
be in scope for the element on which it appears;
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
XPath comments (delimited by (: ... :))
are permitted anywhere that inter-token whitespace is permitted in attributes whose
type is given as
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 'yes', but the attribute is allowed only on the
first of a sequence of adjacent
Unless the element is
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
This example illustrates the notation used to describe
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
An optional debug attribute, whose
value 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 validation="{ $val }", where the 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
It is a
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
More specifically, the effective value is the value after:
Expanding shadow attributes as described in
Expanding defaults (for example, if an 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
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.
It is a
It is a
Special rules apply if the construct appears in part of the
This specification includes a non-normative XML Schema for XSLT
XSLT defines a set of standard functions which are additional to those defined in
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
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 [xsl:]use-when expressions (see
Dynamic evaluation is further divided into two activities:
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.
The as
attribute of the
This raw result may optionally be post-processed to construct a result tree, to
serialize the result, or both, as described in
Implementations
The language is designed to allow the static analysis of each
The following information is needed prior to static analysis of a package:
The location of the
Information about the packages referenced from this
package using
A set (possibly empty) of values for [xsl:]use-when expressions and shadow attributes) as well as
non-static expressions in the 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
required="yes".
A supplied value is converted if necessary to the declared
type of the stylesheet parameter using the
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.
select expression or
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
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
In XPath 4.0, the concept of
The value given to the
The
In a
If a context item is available within a global variable declaration, then
the
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
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
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
The set of documents that are available to the stylesheet is
Once a stylesheet is primed, the values of global variables
remain stable through all component invocations. In addition, priming a stylesheet
creates an
Parameters passed to the transformation by the client application when a stylesheet is primed are matched against
It is a
The
Processing proceeds by finding the
The following information is needed when dynamic evaluation is
to start with a
The
Optionally, an initial
In searching
for the
If no default-mode attribute of the (explicit or implicit)
It is a
A (named or unnamed)
M is explicitly declared in an public or final visibility attribute, or by virtue of an
M is the unnamed mode.
M is named in the default-mode attribute of the (explicit or implicit)
M is declared in a package used by P, and is given public or final
The declared-modes attribute of the explicit or implicit
no, and M appears as
a mode-name in the mode attribute of a
It is a
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="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
A supplied value is converted if necessary to the declared
type of the template parameter using the
Details of how the result of the initial template is to be returned.
For details, see
The as attribute of that template using the
The design of the API for invoking a transformation should provide some means
for users to designate the
It is a required="yes"
and no value is supplied for that
parameter.
A
Optionally, the name of the xsl:initial-template. The selected template
Optionally, a context item for evaluation of this named
template, defaulting to the
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="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
A supplied value is converted if necessary to the declared
type of the template parameter using the
Details of how the result of the initial named template is to be returned.
For details, see
The as attribute of
that template using the
The
It is a public or final.
When the top-level package is rooted at an 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
It is a required="yes"
and no value is supplied for that parameter.
The name and arity of a
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
A supplied value is converted if necessary to the declared
type of the function parameter using the
Details of how the result of the initial function is to be returned.
For details, see
The as attribute of that function
using the
The
If the
It is a public or final.
When a transformation is invoked by calling an
[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
The
A result tree may be constructed from the build-tree
attribute of the unnamed yes. An API for invoking transformations
Alternatively, the
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 is operator.
The way in which maps, arrays, and functions
are returned requires careful design choices. It is
If a result tree is to be constructed from the item-separator. method attribute in the unnamed
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).
More specifically, the process raises a serialization error if any item in the
The tree that is constructed is referred to as a
If the
The base URI of the document node is set to the
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
The
The first phase of serialization, called json output method
(defined in
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
In previous versions of this specification it was stated that
when the
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
A
<!--
category: instruction -->.
The main categories of
instructions that create new nodes:
instructions that construct maps and arrays:
instructions that copy nodes:
instructions that returns an arbitrary sequence by evaluating an XPath
expression:
instructions that cause conditional or repeated evaluation of nested
instructions:
instructions that generate output conditionally if elements are or are not
empty:
instructions that invoke templates:
Instructions that declare variables:
Instructions to assist debugging:
other specialized instructions:
The classic method of executing an XSLT transformation is to apply
template rules to the root node of an input document (see
This example uses rule-based processing to convert a simple XML input document into an HTML output document.
The input document takes the form:
The stylesheet to render this as HTML can be written as a set of template rules:
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 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 body element is populated by evaluating an
The effect 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
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 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
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
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 .
(dot).
XPath 4.0 generalizes the . 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
Full details of the static and dynamic context are provided in
An XSLT
The
Like parsing, serialization is not part of the transformation process, and it is not
In XSLT 1.0 and 2.0 it was possible to structure a
stylesheet as a collection of modules, using the
In XSLT 3.0 an additional layer of modularization of stylesheet code was enabled
through the introduction of
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
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
Although this specification defines packages as constructs
written using a defined XSLT syntax, implementations
When no packages are explicitly defined, the entire
stylesheet is treated as a single package; the effect is as if the
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
It is also permissible to extend the language by providing new [xsl:]extension-element-prefixes attribute.
Extension instructions and extension functions defined according to these rules
This specification defines how extension instructions and extension functions are
invoked, but the facilities for creating new extension instructions and extension
functions are
The XSLT language can also be extended by the use of
An XSLT
Information from a schema can be used both statically (when the
There are places within a
The set of in-scope schema components may vary between
one package and another, and between different parts of the same package,
but as explained in
The conformance rules for XSLT 4.0, defined in
xs:date cannot be used as an argument of the
<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
The remainder of this section describes facilities that are available only with a
Additional
The xs:schema
element.
An role
attribute, which indicates that the schema components are only to be present in the
static context of a region of the stylesheet where they are explicitly invoked
by means of an [xsl:]schema-role attribute.
It is only necessary to import a schema explicitly if one or more of its
Importing a schema does not of itself say anything about the type of the source
document that the
This example will cause the transformation to fail with an error message, unless
the my:invoice, and has been annotated as such.
A schema-role attribute could be added to the declaration to indicate
which schema the element declaration my:invoice is to be taken from.
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
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.
A schema-role attribute could be added to the
It is possible that a source document may contain nodes whose
my:percentage,
and a type named my:percentage appears in an imported schema, then they
must be the same type.
Where a stylesheet author chooses to make assertions about the types of nodes or of
A
It is possible to request explicit validation of a complete document, that is,
a 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
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:type and
xsl:validation attributes of a literal result element.
When elements, attributes, or document nodes are copied, either explicitly
using the validation="strip" and
validation="preserve" are available, to control whether
existing
When nodes in a
For details of how validation of element and attribute nodes works, see
Streaming is an optional feature of the XSLT 4.0 language.
For full information about streaming, see
Generally, errors in the structure of the
A processor
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
A processor
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.
When a
Because different implementations may optimize execution of the
There are some cases where this specification requires that a construct
An implementation
There are also some regex attribute of the
A
The XPath specification states (see
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:
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
It is
The following construct contains a type error, because
42 is not allowed as the value of the select
expression of the
On the other hand, in the following example it is not possible to determine
statically whether the operand of
If more than one error arises, an implementation is not
When a transformation raises one or more dynamic errors, the final state of any
persistent resources updated by the transformation is
Everything said above about error handling applies equally to errors in evaluating
XSLT instructions, and errors in evaluating XPath
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
Errors defined in related specifications (
Implementations
Additional errors defined by an implementation (or by an application)
This section describes the overall structure of a stylesheet as a collection of XML documents.
A
The names of elements and attributes in source documents and
result documents are namespace-qualified names. In addition, as described in
There are two ways namespace bindings can be established in a stylesheet module:
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)
fixed-namespaces attribute on the
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
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, 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-namespaces attribute, or the
The effect of declaring fixed namespace bindings is described in more detail in
As a general rule:
Prefixes used in the names of elements and attributes in the stylesheet
must be declared using
Prefixes used in QNames appearing in the content of attribute nodes
and text nodes in the stylesheet can usually be declared using
[xsl:]exclude-result-prefixes
and [xsl:]extension-element-prefixes, and the stylesheet-prefix
and result-prefix attributes of
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.
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
XSLT
Except where the rules for
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.
Throughout this specification, an element or attribute that is in no namespace, or
an
By convention, the names of
The media type application/xslt+xml
has been registered for XSLT stylesheet
modules.
The definition of the media type is at
This media type
[xsl:]schema-role is introduced, to allow
different parts of a stylesheet to use different schemas.
default-collation,
default-mode,
default-validation,
exclude-result-prefixes,
expand-text,
extension-element-prefixes,
schema-role,
use-when,
version, and
xpath-default-namespace.
These attributes may also appear on a 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
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
In the case of [xsl:]default-collation,
[xsl:]expand-text, [xsl:]schema-role,
[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
In an
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
The effect of the [xsl:]use-when attribute is described in
Because these attributes may appear on any
Note that the effect of these attributes does
For the detailed effect of each attribute, see the following sections:
see
see
see
see
see
see
see
see
see
see
The version attribute indicates the
version of the XSLT language specification to which the package manifest conforms.
The value 4.04.04.0
A package typically has a name, given in its name
attribute, which
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, 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
The package manifest contains the following elements, arbitrarily ordered:
Zero or more
Zero or more additional
Some declarations of particular relevance to packages include:
The
The optional
Zero or more
Zero or more ordinary
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.
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
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
The effect of the input-type-annotations
attribute is defined in
A more extensive example of a package, illustrating how components
in a package can be overridden in a client package, is given in
If a package has a version number, the version number must conform to the grammar:
Here NCName are as defined in
the XPath
Examples of valid version numbers are 2.0.5 or
3.10-alpha.
NamePart within the version number are referred to as the
This means that 1-alpha-2 is a valid version number, with two
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
Comparison proceeds by comparing
If both versions have the same number of eq operator using the Unicode codepoint
collation), then the versions compare equal.
If the number of NCName. For example, 1.2 is less than
1.2.5, while 2.0 is greater than
2.0-rc1.
If both
If both
If one NCName, the NCName comes first.
For example, the following shows a possible ordered sequence of version numbers:
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
Implementations
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
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
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).
The .* indicates that additional
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 supplied
PackageVersion or 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 ending
PackageVersion or 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
The phrase
A
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 * 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.
Rules for determining the location of the package are described at
Rules for supplying parameters to the package are described at
It is a
It is a
The
It is not intrinsically an error to have two
xsl:package-location is provide
to indicate to the processor where the required package is to be found.A package may be located either explicitly, through one or more
A xsl:package-location points to a resource that may or
may not be an archive. If the target resource is an archive, then xsl:package-location:
path-in-archive, specifying the
location of the package manifest within the archive. The value of
path-in-archive is normalized such that it always begins with the string !/
(the result of replace(., "^(!/)?(.+)", "!/$2")).
archive-type,
specifying the type of archive. Implementations zip. All other values of this
attribute are
It is a archive-type
is present without the attribute path-in-archive, or if it does not have the
value zip or an
The attribute href takes an absolute or relative URI reference,
which is resolved as described in
The URI scheme for archive resources is currently only provisionally defined ( Remove "zip:" or "jar:" from the beginning of the value. Remove jar:<url>!/[<entry>], but variations on this syntax are known (such as using
zip instead of jar). The entry is already accommodated by the attribute
archive-type, so the following adjustments must be made to the value of href
that points to an archive:
!/ and any string text that follows.
The attribute format takes a string, default value
xslt if the attribute is absent, specifying the format of
the xslt indicates that the package manifest is a standard XML
resource as described in these specifications. All other values are
xsl:package-location without the attribute is-priority,
or with is-priority set to true is a xsl:package-location with is-priority set to false is a
Each href, when resolved
as described in
If the returned resource is an archive, the archive entry is to be treated as the
format. If the resource does not conform to the rules for the
format type a
The
It is a
It is a format.
It is a
It is a archive-type
is present without the attribute path-in-archive, or if it does not have the
value zip or an
Use of the package name as a dereferenceable URI is
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.
Consider a using package Q, invoked as follows:
The first $diagnostics-on is true, in which case
the local file q-dev.xsl, if it exists, will be the file:/{$prod-path}/q.zip (which depends upon
the value of static parameter $prod-path), and the entry q.sef
at the root of the archive (assumed to be a ZIP file for lack of a
archive-type). Next will be any xsl:package-location, a
Each of these package locations will be evaluated in turn. If no
An
The actual value of the supplied parameter must be known statically.
The select
attribute, and the value of the select attribute must be
a
It is a select
attribute, or if the value of the select attribute
is not a
It is not an error to supply a value for a parameter which the library package does not declare. Such a value is simply ignored.
The reason for this rule is to make it easier to write code that works with multiple versions of a library package.
Especially in the case of
It is a
Under the rules for global
In the case of a non-static
This section discusses the use of named components in packages.
The components which can be declared in one package and
referenced in another are:
In addition,
Named and unnamed
Not all
Named
Some declarations, such as
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
match attribute and
a name attribute, then it establishes both a template rule and
a
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
In the case of
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.
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
In the case of the
Every
When a
Within this specification, we generally use the notation C/P for a component named C whose declaring package and containing package are both P; and the notation C/PQ 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 C/Q in the used package Q).
The properties of a
The original
The
The
The public, private, abstract,
final, or hidden. The visibility of components
is discussed further in
A set of bindings for the
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.
name attribute of [xsl:]use-attribute-sets attribute of
mode attribute of my:f#1) referring to
stylesheet functions.
Symbolic references exist as properties of the <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
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 A/P,
B/P, and C/P. The hidden (meaning that it
cannot be referenced from within P), and B/P will contain a
binding for the component C/P 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 A/R, B/R, and C/R. This time the declaration of all three components is in the original package Q. Component B/R will contain a binding to C/R, 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
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 mode attribute is treated as a reference to the
Where an name and a match attribute, it is treated as if there
were two separate name attribute and one with a match attribute.
use-accumulators attribute
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.
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 declaration on the declaration itself (if
present), and the rules given in the
The visibility attribute. The permitted value is some subset of private,
public, abstract, or final (never
hidden). In the case of
an visibility attribute; rather the declaration has the
implicit attribute visibility="public".
Any visibility attribute,
and can also be used to reduce the visibility of components where this
attribute is present.
The
The components in question are identified using their 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
An
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 *, 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.
The visibility of a named template, function, variable, attribute set, mode, named item type, 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 private.
No
It is possible to expose the value of a stylesheet parameter by binding a public global variable to its value:
This works for both
XSLT 3.0 made conflicting statements on this; there were places in the specification
that said all stylesheet parameters were public, others that said static parameters were private.
Making stylesheet parameters public, and hence overridable, causes problems with the use
of xsl:original in an overriding declaration. The rules have therefore been changed.
If the package manifest contains an EQName
or NamedFunctionRef (that is, not by virtue of a wildcard
match), then the value of the visibility attribute of the
last such
If the declaration of the component has a visibility
attribute, then the value of this attribute (call this the
If the package manifest contains an prefix:* or *:local or
Q{uri}*), then the value of the visibility
attribute of the last such
If the package manifest contains an *), then the value of the
visibility attribute of the last such
Otherwise, private.
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
| 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 |
It is a visibility attribute, and the component is also listed
explicitly by name in an
It is a names attribute of
It is a component attribute of *
(meaning all component kinds) and the names attribute is not a wildcard.
There is no ambiguity, and no error, if several tokens within the same
If the visibility of a component as established by the above rules
is abstract, then the component must have a declared visibility of abstract.
In other words, the
It is a abstract, unless the component is already abstract
in the absence of the
For a component accepted into a package P
from another package Q, the
When a package P uses a package Q, by virtue of an
For every component C/Q in package Q that is not matched
by any
If C/Q is an public.
In other cases, the
| Visibility in used package C/Q | Visibility in using package C/P |
|---|---|
| public | private |
| final | private |
| private | hidden |
| hidden | hidden |
| abstract | hidden |
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.
The
The rules for determining whether an
No
Attempting to match an EQName will therefore always give an error, while
using a wildcard has no effect.
It is a names attribute of
It is a component attribute of *
(meaning all component kinds) and the names attribute is not a wildcard.
In the absence of a matching visibility attribute of the best-matching
| Visibility in | 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 |
It is a
It is a 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
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
It is a names attribute of
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
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.
It is a
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
To override a component accepted from a used package, the overriding
declaration must appear as a child of the
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.
visibility="private".abstract or public. The
overriding declaration is written as a child of the
This mechanism is distinct from the mechanism for overriding declarations
within the same package by relying on
If the used package Q contains a visibility
attribute of D, or private if this is absent,
except in the case
of public.
The using package P will also contain a component C/PQ
whose body is the same as the body of C/Q and whose 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
The rules in the remainder of this section apply to
components having a name attribute (name attribute that
can appear as a child of match
attribute (that is, a name attribute
and a match attribute, then it defines both a named component and
a template rule, and both sections apply.
It is a
When an attribute set is overridden, the
overriding attribute set must be defined using a single
use-attribute-sets attribute.
It is a
It is a public or abstract
A package is executable if and only if it contains no abstract. A package that is not
executable is not a
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.
It is a
Compatibility is only relevant when comparing two components that have the same
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
The declared types of the parameters
(defaulting to item()*) are pairwise
The declared return types
(defaulting to item()*) are
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.
It is
Two named templates with the same name are compatible if and only if they satisfy all the following rules:
Their return types are
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
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
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
use attributes are the same and the
required types are 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
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.
Stylesheet parameters are always private, and therefore cannot be overridden.
However, an
When overriding a global variable, the initial value may differ.
Stylesheet parameters in a
subtype(S, T) and subtype(T,
S) both hold, where the subtype relation is defined in
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 coercion
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.
A named item type
(declared in an
Two named record types are compared by name, not by content. This is
because named record types may potentially be recursive, so the name
cannot always be expanded to an expressible record type designator.
By implication, the named record type must itself be declared or exposed
with visibility="public".
Modes, named item types, and named record type are not overridable,
so
Within the declaration of an overriding named name attribute), where
the overridden component has public xsl:original as a symbolic reference to
the overridden component. More specifically:
Within a xsl:original
may appear as the value of the name attribute of
<xsl:call-template name="xsl:original"/>.
Within a 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.
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 xsl:original dynamically
(for example using
Within a 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 [xsl:]use-attribute-sets attribute (whether on the
xsl:original as a
reference to the overridden attribute set.
Within the overriding component C/P, the xsl:original is bound to the hidden component C/PQ
described earlier, whose body is that of the component C/Q in the
used package.
It is a 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 attribute of
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.
The process of
Consider a package Q defined as follows:
(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 |
|---|---|---|---|---|---|---|
| A/Q | variable A | Q | Q | final | $B + 1 | $B → B/Q |
| B/Q | variable B | Q | Q | private | $C * 2 | $C → C/Q |
| C/Q | 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:
Package P has five components, whose properties are shown in the following table:
| ID | Symbolic Name | Declaring Package | Containing Package | Visibility | Body | Bindings |
|---|---|---|---|---|---|---|
| A/PQ | variable A | Q | P | final | $B + 1 | $B → B/PQ |
| B/PQ | variable B | Q | P | hidden | $C * 2 | $C → C/P |
| C/PQ | variable C | Q | P | hidden | 22 | none |
| C/P | variable C | P | P | private | $xsl:original + 3 | $xsl:original → C/PQ |
| T/P | template T | P | P | public | value-of select="$A | $A → A/PQ |
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 A/PQ.
The value of A/PQ is the value of B/PQ plus 1.
The value of B/PQ is the value of C/P times 2.
The value of C/P is the value of C/PQ plus 3.
The value of C/PQ 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 A/PQ, B/PQ, and C/PQ are modified copies of the corresponding component A/Q, B/Q, and C/Q in the used package Q. The properties of these components are modified as follows:
The
The
The visibility="private" changes to
visibility="hidden".
The references to other components are rebound as described in this section.
Component C/P is the overriding component. Its properties
are exactly as if it were declared as a top-level component in
P (outside the $xsl:original, and (c) the fact
that it overrides C/Q affects the way that references from
other components are rebound.
Component T/P is a new component declared locally in P.
The general rules for
If the
When a package P uses a package Q, then for every
component C/Q in Q, there is a
Given a component C/P whose xsl:original, there will always be exactly one non-hidden
component D/P whose containing package is P and
whose
In the case of a component reference using the name
xsl:original, this will in general appear within a
component C/P that overrides a component C/Q whose
corresponding component in P is C/PQ, and the
xsl:original reference is bound to C/PQ.
Given a component C/P whose
If D/Q is overridden within P by a component D/P, then the reference is bound to D/P;
Otherwise, the reference is bound to the component D/PQ in P whose corresponding component in Q is D/Q.
When reference resolution is performed on a package that is intended to be used
as a abstract (that is, an implementation must be provided for every
abstract component).
It is a abstract.
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.
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.
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:
and that in a using package Q we find:
The correct output here is <v value="4"/>.
The explanation for this is as follows. Package Q contains a function f:factory/QP
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 v/Q: that is, the overriding declaration
of $v that appears within the
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
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 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#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.
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
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
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
mode
attribute is treated as a
A named mode may be declared in an public, private, or final. The
values of the visibility attribute are interpreted as follows:
| Value | Meaning |
|---|---|
| public | A |
| private | A |
| final | A |
As with other named components, an visibility attribute are public,
private, and final.
The public or final
The abstract.
It is not possible for a package to combine the template rules from two other
packages into a single mode. When
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
Rules declared within P (specifically,
Rules declared within Q, taking
Built-in template rules (see on-no-match attribute of the
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.
If existing XSLT code has been written to use template rules in the unnamed
mode, a convenient way to incorporate this code into a 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
In previous versions of XSLT, modes were implicitly declared by simply using a
mode name in the mode attribute of
By default, within a package that is defined using an explicit
The declared-modes
attribute of yes (the default),
then it is an error to use a mode name
unless the package either contains
an explicit 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
It is a declared-modes attribute of
an 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
The package contains an
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
The mode
attribute of an
An [xsl:]default-mode attribute.
A package
There is an mode attribute, and with no ancestor-or-self having
an [xsl:]default-mode attribute.
There is an match attribute and no mode attribute, and with no ancestor-or-self having
an [xsl:]default-mode attribute.
The
Declarations of visibility attribute. The unnamed decimal format and the
unnamed output format are also local to a package.
If
An
An
An 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.
For example, suppose a 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
The element is a
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.
It is a
If there is no <xsl:global-context-item/>, which imposes no constraints.
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
If the value absent is specified, then the global focus
(context item, position, and size) will be
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 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
It is a as attribute is
present use="absent" is specified.
The global context item is available only within the use="required", in which case an error
is raised:
In earlier releases of this specification, the . (dot), while the initial match selection
is a sequence of nodes or other items supplied to an initial implicit
APIs that were originally designed for use with earlier versions of XSLT are likely to bundle the two concepts together.
A
If the ItemType is one that can only be satisfied by a
schema-validated input document, for example
as="schema-element(invoice)", 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.
It is a use="required", and no global context item is supplied.
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.
This example package should not be confused with the behavior of the
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:
The result returned by this stylesheet would be:
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:
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.
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:
The function csv:preprocess-line calls
normalize-space() on its argument:
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-lineBy 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:
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.
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-fieldMode 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.
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.
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:
csv:quote VariableThe variable csv:quote can be used to specify the character used
in a particular input stream to quote values.
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.
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:
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-processThe 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:
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
As it does elsewhere, the visibility of components declared within
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:
A stylesheet module is represented by an XDM element node (see 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
The principal stylesheet module of a package may take one of three forms:
A package manifest, as described in
An implicit package, which is a subtree rooted at an
A simplified stylesheet, which is a subtree rooted at a literal result element,
as described in
A stylesheet module other than the principal stylesheet module of a package may take either of two forms:
Whichever of the above forms a module takes, the outermost
element (
main-module, is added to the A stylesheet module is represented by an
The version attribute indicates the version
of XSLT that the stylesheet module requires. The attribute is
The value of the version attribute xs:decimal as defined in
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 4.0. If the value is numerically less than 4.0, the
stylesheet is processed using the rules for
The effect of the input-type-annotations attribute is described in
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
The optional main-module attribute is purely documentary.
By including this attribute in every
An
The
Note that the
The child elements of the
As described in
Forwards references to
fixed-namespaces Attributefixed-namespaces attribute making it easier to have the same
namespace declarations in force throughout a stylesheet.
The fixed-namespaces attribute, if present, defines the
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
name attribute of declarations like 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
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
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
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
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 ./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
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.
It is a 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
Namespace prefixes used in element and attribute names in the stylesheet
cannot be declared using this mechanism. Such prefixes must be bound using
[xsl:]exclude-result-prefixes
and [xsl:]extension-element-prefixes attributes, and the
stylesheet-prefix and result-prefix attributes
of
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.
It is possible to use
the default-mode. It is also possible to use them in
shadow attributes (see
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
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
The document identified by the URI may be a stylesheet module.
One way to use the feature is to use the
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:
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.
Using the fixed-namespaces attribute rather
than
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 xsl:default-collation) on a
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 default-collation
attribute on an inner element. It also determines the collation used by certain
XSLT constructs (such as
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
It is a [xsl:]default-collation attribute, after resolving
against the base URI, contains no URI that the implementation recognizes as
a collation URI.
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 fallback=yes.
The [xsl:]default-collation attribute does not affect the collation
used by
In the absence of an
[xsl:]default-collation attribute, the default collation
[xsl:]default-collation attribute, the default collation
default-mode Attribute[xsl:]default-mode attribute defines the
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 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.
In addition, when the attribute appears on the
The value of the [xsl:]default-mode attribute #unnamed which refers to
the
This attribute is provided to support an approach to stylesheet modularity in
which all the template rules for one
It is not necessary for the referenced mode to be
explicitly declared in an declared-modes attribute (which defaults to
yes on an
It is a
An implementation
User-defined data elements can provide, for example,
information used by
information about what to do with any
information about how to construct
optimization hints for the
metadata about the stylesheet,
structured documentation for the stylesheet.
xsl:version attribute
(which means they might not need a declaration of the XSLT namespace). Unless otherwise
specified, a 4.0 simplified stylesheet defaults expand-text to true.
A simplified syntax is allowed for a match=".",
which matches any item.
The following example shows a stylesheet that simply evaluates one XPath expression:
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:
Because the stylesheet contains no elements or attributes in the XSLT namespace, it does not need to contain any namespace declarations.
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:
This example expects as input a parsed JSON document containing an array of records. It outputs a serialized JSON document containing a selection of fields from these records.
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 expand, with the outermost element as the
The allowed content of an instruction or literal result element when used as a simplified stylesheet
is the same as when it occurs within a
The only useful way to initiate the transformation is to supply an item
as the match="." template rule using the
There are several 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
The outermost element of a simplified stylesheet can be any instruction (for example,
xsl:array, xsl:map, or xsl:result-document), allowing the
stylesheet to deliver arrays, maps, or serialized JSON.
The match pattern of the implicit template rule uses match="." rather
than match="/", allowing the
There may be edge cases where this causes a backwards incompatibility. For example,
if a transformation using a simplified stylesheet is invoked supplying an element node
(rather than a document node) as the match="."
matches an element node), whereas in 3.0 it would have been processed using the built-in
template rules for the unnamed mode. A similar situation arises if a simplified stylesheet
module is imported into a larger stylesheet package, and the implicitly-defined template
rule is invoked using
It is technically valid for the outermost element to be
[xsl:]version attribute
(see
These rules do not apply to the version attribute has an entirely different purpose: it is used to
define the version of the output method to be used for serialization.
The
There are additional rules for an
Specifically:
If the
If the
If the
If the
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
It is a
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 version attribute with a value greater than 1.0xsl:version property returned by the
In this mode, if any attribute contains an XPath true. For details of this mode, see 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
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
Certain XSLT constructs also produce different results when XSLT 1.0 compatibility mode is enabled. This is described separately for each such construct.
In this specification, no differences are defined for XSLT 2.0 behavior. An XSLT
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
In this specification, no differences are defined for XSLT 3.0 behavior. An XSLT
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
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
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
The detailed rules follow.
These rules do not apply to the version attribute of the
When an element is processed with forwards compatible behavior:
If the element is in the XSLT namespace and appears as a child of the
If the element has an attribute that XSLT 4.0 does not allow the element to have, then the attribute
If the element is in the XSLT namespace and appears as a child of an element
whose content model requires a
If the element has one or more
If the element has no
For example, an XSLT 4.0
If a stylesheet depends crucially on a terminate="yes" (see
For example,
The XSLT 1.0 and XSLT 2.0 specifications did not anticipate the
introduction of the version setting.
This problem can be circumvented by using the simplified package
syntax (whereby an
For an XSLT 4.0 processor, the 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
This rule was not present in earlier versions of this specification.
On a strict reading of the XSLT 3.0 specification, for example, an 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
XSLT provides two mechanisms to construct a
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,
These declarations use an href attribute, whose value is a
After resolving against the base URI, the way in which the URI reference is used
to locate a representation of a
href attribute of the
The referenced
Implementations
It is a href attribute of
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.
A stylesheet module may include another stylesheet module using an
The href attribute whose value is a URI reference identifying the
stylesheet module to be included. This attribute is used as described in
An
A stylesheet level thus groups the
If two or more
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
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
A stylesheet module may import another
The href attribute whose value is a URI reference identifying the
stylesheet module to be included. This attribute is used as described in
An
For example,
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
It is a
Under the new XSLT 4.0 rules, a cyclic reference that involves
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.
This specification provides several features that cause the
raw stylesheet to be preprocessed as the first stage of static processing:
Whitespace and commentary are stripped (see Any Elements
may be conditionally included or excluded by means of an Attributes may
be conditionally computed as described in [xsl:]use-when
attribute as described in
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
Any text nodes that are now adjacent to each other are merged.
Any
The parent of the text node is not an
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 xml:space attributes:
Any xml:space attributes.
Any xml:space attributes.
Within an xml:space="preserve" attribute, is a
Using xml:space="preserve" in parts of the stylesheet that contain
If an xml:space attribute is specified on a
xsl:note elementAn
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
An
An
A number of documentation processors have been produced for use with XSLT, and the general convention has
been to use
Annotations can only appear at the top level of the stylesheet (between declarations, but not
within declarations).
Annotations require a custom namespace to be declared, typically on the [xsl:]exclude-result-prefixes
attribute.
Implementations
For example,
Any element in the XSLT namespace may have a use-when attribute whose
value is an XPath expression that can be evaluated statically.
A xsl:use-when attribute.
If the attribute is
present and the false, then the element, together with
all the nodes having that element as an ancestor, is effectively excluded from the
use-when attribute itself.
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
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
The XPath expression used as the value of the
xsl:use-when attribute follows the rules for
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.
The effect of these declarations is that a non-schema-aware processor ignores
the
This example includes different stylesheet modules depending on which XSLT processor is in use.
When a no-namespace attribute name N is permitted to appear on an element
in the
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
For example, an
allowing the stylesheet to include a specific version of a library module based on
the value of a
Similarly, a
this allowing the streamability of the mode to be controlled using a 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 use-when attribute, the version
attribute, and the static attribute on
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.
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.
An attribute whose name begins with an underscore is
treated specially only when it appears on an element in the XSLT namespace. On a
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:
And this can then be used to set the default namespace for XPath expressions:
However, it is not possible to put this shadow attribute on the
$NS is not in scope. A workaround is to create a stub
stylesheet module which contains nothing but the static parameter declaration
and an _xpath-default-namespace="{ $NS }" can
therefore appear on this
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:
If the supplied value of the filter parameter is, say location =
"UK", then the report will cover employees based in the UK.
The stylesheet function local:filter is used here in preference
to direct use of the supplied predicate within the select
attribute of the
Every XSLT 4.0 processor includes the following
named type definitions in the
All built-in types defined in xs:anyType and
xs:anySimpleType.
The following types defined in xs:yearMonthDuration, xs:dayTimeDuration,
xs:anyAtomicType, xs:untyped, and
xs:untypedAtomic.
XSLT 4.0 processors 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
User-defined types, and element and attribute declarations, that are imported
using an
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
An implementation may define mechanisms that allow additional
These [xsl:]type and as attributes of those elements that
permit these attributes.
The facilities described in this section are not available with a
The
The type and as
attributes of various
If the role attribute is absent,
the relevant schema components are available in all stylesheet modules
within the [xsl:]schema-role
attribute. Importing components in one stylesheet module makes
them available throughout the [xsl:]schema-role attribute.
The schema components imported into different
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 xs:schema
element, then the schema-location attribute
the namespace attribute of the targetNamespace attribute of the
xs:schema element are both absent (indicating a no-namespace
schema), or
the namespace attribute of the targetNamespace attribute of the
xs:schema element are both present and both have the same
value, or
the namespace attribute of the targetNamespace attribute of the
xs:schema element is present, in which case the target
namespace is as given on the xs:schema element.
It is a 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 role
name specify the same namespace, or
if both specify no namespace, then only the one with highest
After discarding any xs:import elements corresponding
one-for-one with the
The namespace attribute of the xs:import element is
copied from the namespace attribute of 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
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
The schema components included in the
[xsl:]schema-role attribute
of the innermost ancestor element having such an attribute; in the absence of such an attribute,
the unnamed schema role applies. The schema components whose names are available
are the top-level element and attribute
declarations and type definitions that are available for reference within the
synthetic schema document for that schema role. See
It is a
The synthetic schema document does not need to be constructed by a real
implementation. It is purely a mechanism for defining the semantics of
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
The namespace attribute indicates that a schema for the given
namespace is required by 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
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
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
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"
There are two built-in functions
(http://www.w3.org/2005/xpath-functions. Schema
components for these namespaces are available for reference within the stylesheet if
and only if an schemaLocation
attribute has no effect.
A stylesheet might perform a transformation from an input document conforming to
one schema, to an output document conforming to a different schema. To facilitate this,
a schema can be imported with a specific role name, and it is then used only in parts
of the stylesheet within the scope of an [xsl:]schema-role attribute specifying
this role name.
More specifically, within the subtree rooted at an element having an
[xsl:]schema-role attribute, the static context uses in-scope schema
definitions taken from the named schema role.
It is a [xsl:]schema-role in a stylesheet package does
not match the value of the role attribute on some
The introduction of multiple schema roles in XSLT 4.0 enables different input and output documents to be validated against different schemas. For example, a stylesheet might contain the instruction:
to control which schema is used to validate the result document.
Any instructions used to create validated element nodes
in this result document should normally also be within the scope of
the same [xsl:]schema-role.
The fact that multiple schemas can be imported does not relax
the requirement that all
schemas used in a transformation must be
The reason for this restriction is to ensure that stylesheet components (such as functions) using schema components in their type signatures are compatible across the stylesheet as a whole, and that instance documents whose nodes have type annotations resulting from validation against a schema can be checked for conformance with types declared anywhere in the stylesheet.
It is possible to validate different parts of a constructed document against different schemas. However, validating an element in a document validates the entire subtree rooted at that element, so requesting validation at more than one level may be redundant.
The data model used by XSLT is the XPath 4.0 and XQuery
4.0 data model (XDM), as defined in
This section elaborates on some particular features of XDM as it is used by XSLT:
The rules in
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
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
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
The specification referenced as
Atomic types such as xs:string and xs:dateTime are defined
in
The value space of xs:string includes all Unicode characters
other than U+0000 (but not non-characters such as unpaired surrogates).
The type xs:anyURI imposes no constraints on the form of the value.
If the range of dates supports negative years, then it must also support year zero.
The value space for xs:double and xs:float includes
negative zero and positive zero as distinct values.
However, for operations that necessarily involve use of a schema processor (such as
Source documents supplied as input to a transformation may be subject to preprocessing.
Two kinds of preprocessing are defined: stripping of type annotations (see
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
Any documents containing a node present in the
Any document containing a node that is returned by the functions
Any document read using xsl:source-document.
This list excludes documents passed as the values of
parse-xml-fragment,
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
The rules determining whether or not stripping of annotations and/or whitespace
happens are defined at the level of a
The semantics of the
The effect of dynamic calls to the doc#1) and calls on 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.
dm:type-name accessor of a node: see
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 xs:untyped in the case of element nodes, and
xs:untypedAtomic in the case of attribute nodes.
Such stripping of input-type-annotations="strip" on the strip, preserve, and
unspecified. The default value is unspecified.
unspecified has the same effect
as omitting the attribute.
The input-type-annotations attribute may also
be specified on the
It is a input-type-annotations="strip" and another input-type-annotations="preserve", or if a stylesheet module specifies the value
strip or preserve and the same value is not
specified on the
Type annotations are stripped from relevant source documents if
at least one input-type-annotations="strip" on the
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.
Stripping
A
The stripping process takes as input a set of element names whose child
The stripping process that applies for a particular
A
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
The xml:space attributes are not removed from the tree.
The set of whitespace-preserving element names is specified by
elements
attribute whose value is a whitespace-separated list of
It is a
Otherwise, when more than one
First, any match with lower
Next, any match that has a lower
If several matches have the same *:local and the other takes
the form prefix:*), then the declaration that appears last in
If an element in a source document has a minLength facet to be
violated.
Stripping of input-type-annotations="strip" is specified.
In
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
The mapping from the Infoset to the XDM data model, described in 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
The XDM data model (see
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
disable-output-escaping, but without distorting
the data model.
If an disable-output-escaping attribute of
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.
In practice, the nodes in a 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
In most cases where such names are written in a
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 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
A "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.
There are a few places where the third form, a URIQualifiedName, is not
permitted. These include the name attribute of
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.
xs:QName
datatype as defined in the XDM data model (see
xs:QName datatype
as defined in XML Schema (see
Note that every
The following rules are used when interpreting a
If the lexical QName has a prefix, then the prefix is expanded into a URI
reference using the namespace declarations in effect on its
In the case of a prefixed
Where the result of evaluating an XPath expression (or an attribute
value template) is required to be a
If the lexical QName has no prefix, then:
In the case of an unprefixed QName used as a NameTest
within an XPath [xsl:]xpath-default-namespace attribute, as
specified in
If the name is in one of the following categories, then the default
namespace of the
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
The default namespace is used when expanding the first argument
of the function
The default namespace applies to any unqualified element names
appearing in the cdata-section-elements
or
suppress-indentation attributes of
In all other cases, a xs:QName value in which both the prefix and
the namespace URI are absent).
[xsl:]xpath-default-namespace attribute can be set to the value
##any, which causes unprefixed element names to match in any namespace
or none.
The attribute [xsl:]xpath-default-namespace (see
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
The special value ##any only affects:
An unprefixed element name used in a
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.
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
any unprefixed element name used in the elements attribute of
the
any unprefixed element name used in the as
attribute of an
any unprefixed type name used in the type attribute of an
any unprefixed type name used in the xsl:type attribute of a
literal result element.
The [xsl:]xpath-default-namespace attribute
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
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 key function.
Unprefixed function names are treated as names in the
For other unprefixed names, for example variable
names, template names, mode names, or strings that are interpreted as name attribute of
Each of the reserved namespaces has a conventional
prefix. As described in 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 xsl
http://www.w3.org/2005/xpath-functions,
fn
The namespace
http://www.w3.org/2005/xpath-functions/math,
math
The namespace
http://www.w3.org/2005/xpath-functions/map,
map
The namespace
http://www.w3.org/2005/xpath-functions/array,
array
http://www.w3.org/XML/1998/namespace, is used for
attributes such as xml:lang, xml:space, and
xml:id.xml.
http://www.w3.org/2001/XMLSchema,
xs
http://www.w3.org/2001/XMLSchema-instance,
xsi
http://www.w3.org/2005/xqt-errors,
err
The namespace http://www.w3.org/2000/xmlns/ is reserved for use
as described in xmlns is
implicitly bound to this namespace, no namespace node will ever define this
binding.
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
It is not an error to use a reserved namespace in the name of an
xml:space and xsi:type
fall into this category. XSLT processors
It is a xsl:initial-template is permitted as a template
name.
The name xsl:original is used within 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 4.0
selecting nodes for processing;
specifying conditions for different ways of processing a node;
generating text to be inserted in a
XPath expressions may occur:
As the value of certain attributes on XSLT-defined instructions (for example,
the select attribute of the
Within curly brackets in
As the content of a text node within an
In the above cases, the static processing (compilation) of XPath expressions takes place at the same time as the static processing of the stylesheet itself, while evaluation of the XPath expressions takes place dynamically during stylesheet evaluation. There are also, however:
XPath expressions where both the static processing and dynamic evaluation of the XPath expression
takes place during static processing of the stylesheet. These are referred to as
XPath expressions that are dynamically constructed (as character strings):
both the static processing and dynamic evaluation of these expressions occurs during stylesheet
evaluation. See
In general:
It is a
The transformation fails with a
The transformation fails with a
There are some exceptions to these rules, for example:
Static errors may be suppressed where
Dynamic errors may be caught using
Dynamic errors evaluating a predicate within a pattern do not cause the transformation to fail, they merely cause the pattern not to match.
item()*.
false.
In earlier versions of this specification, the coercion rules were referred to as the
These are the rules defined in true are used only for XPath function calls, and for the
operands of certain XPath operators.
This specification also invokes the XPath
Any
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:untypedAtomic2003-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.
The XPath specification states (see
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. Normalization of whitespace can be
prevented by using character references such as 	.
XPath expressions appearing in text nodes, (specifically, in text value templates
— see
In both cases it is unwise to include the characters 	, 
,
and 
 respectively, or constructed dynamically by a call on
the `Width:{char(9)}8mm`.
(The advantage of using this form in preference to XML character references is that
they are more likely to survive when the stylesheet is processed using tools such as XML editors.)
XPath defines the concept of an
This section does not apply to
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,
The following four sections describe:
The
true if and only if the containing element is processed with
The
The
The http://www.w3.org/2005/xpath-functions (and cannot be changed).
The
The
The
The functions defined in 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
The
Stylesheet functions defined in used packages, subject to visibility:
see
any
The term
It follows from the above that a conformant XSLT processor must implement
the entire library of functions defined in
The
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
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
The set of
Some of the components of the XPath static context are used also by type and as may
reference types defined in the
Many top-level declarations in a stylesheet, and attributes on the
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
The set of named character maps, used by the
The values of system properties, used by the
The set of available instructions, used by the
The
If these functions are called within a
For convenience, the dynamic context is described in two parts: the
A number of functions specified in
As specified in
XPath expressions contained in [xsl:]use-when attributes are not
considered to be evaluated “during the transformation” as defined above. For
details see
. (dot).
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
position().
last().
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
The
For an XPath expression contained in a
In other cases (for example, where the containing element is
The . (dot) this is unaffected by changes to the context item
that occur within the XPath expression. The
On completion of an instruction that changes the
When a
When the focus is
The description above gives an outline of the way the
The previous section explained how the
The
The
This set therefore includes some functions that are not available for
dynamic calling using
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
The [xsl:]default-collation attribute on the innermost enclosing
element that has such an attribute. For details, see
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
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
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
The mapping from URIs to document nodes is
affected by input-type-annotations attribute, and may therefore vary
from one package to another.
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
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
XSLT-specific components of the dynamic context can now be retained in the captured context of a function item, in the same way as XPath-defined components of the dynamic context.
In addition to the values that make up the
The
The
The
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 the empty sequence.
The
The
The
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.
| Component | Initial Setting | Set by | Cleared by |
|---|---|---|---|
|
| See |
| Calls to |
|
| If apply-templates invocation is used
(see |
| See |
|
| the initial |
| Calls to |
|
| absent |
| See |
|
| absent |
| See |
|
| absent |
| See |
|
|
| See | |
|
| empty sequence |
|
|
|
|
| Set to | None |
|
|
| Calls to |
use and match attributes of
initial-value of
select expressions or
contained sequence constructors of
http://www.w3.org/2005/xpath-functions, in
particular those that explicitly depend on the context, such as the
Named function references (such as position#0) and
calls on 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. In XSLT 4.0 this rule
extends to the XSLT extensions to the dynamic context defined in this section.
For example the call regex-group#1) delivers a function item that holds a snapshot
of the
XSLT 4.0 introduces two new and closely-related constructs allowing item types to be given names, and to be referred to by name anywhere that item types are used, for example in function declarations and variable declarations.
The
The
Named record types can be recursive, allowing definitions of recursive data structures such as lists and trees.
Declaring a named record type automatically establishes a constructor function for records of that type; the constructor function has the same name as the record type itself.
An
The following example declares a named item type for colors, and uses it in three variable declarations and a function declaration.
The following example declares a named choice type for the two binary
types xs:hexBinary and xs:base64Binary
and uses it in a function declaration that compares two such values
for equality.
Using named item types makes the stylesheet more readable, and improves potential for change: a change
to the set of colors allowed by the type my:color is less likely to affect users of a function
library. However, named item types do not provide true encapsulation or information hiding; users of the
function library can still treat enumeration values as simple strings if they wish.
The ItemType to appear.
The scope of a named item type is the visibility="public" then it also becomes available for use in using
packages. (Since there is no mechanism for the using package to override the definition,
public effectively means final.)
A named item type is essentially an abbreviation for the item type designator appearing in the
as attribute, and the semantics can be defined in terms of textual replacement
of the name by its definition. In consequence, named item types cannot be recursive, since
this would make the textual expansion non-terminating.
The name of the item type is the expanded name formed by resolving the name attribute.
A lexical QName with no prefix is treated as being in the
If two
It is a
It is a as attribute a reference to N,
or to an item type that references N directly or indirectly.
It is permissible to use a private named item type in the declaration of a public variable, function, or template. A package that uses (or overrides) such a component will not be able to use the type name, but it can use the underlying type definition, or provide its own declaration of the relevant item type, using the same name or a different name.
An
The following example declares a named record type for complex numbers, and uses it in a variable declaration and a function declaration.
Note how the record type declaration has implicitly declared a constructor function
cx:complex that can be used to create instances of the item type.
It is a
It is a default
attribute unless it specifies required="no".
An
In the same way as ItemType can appear,
for example in the declarations of functions and variables. Unlike
types declared in
An
Because of its dual role, the name of an
Considered as an item type, the <xsl:namespace-alias stylesheet-prefix="t"
result-prefix="xsl"/>:
This generated
For example, the declaration:
produces the equivalent item type declaration:
Considered as a function declaration, an <xsl:namespace-alias stylesheet-prefix="t"
result-prefix="xsl"/>:
For example, the declaration:
produces the equivalent function declaration:
No entry is generated in the constructed map for a field that is declared as optional with no default. So the declaration:
produces the equivalent function declaration:
This generated
The generated public
then it can also be overridden using
The scope of a named record type is the visibility="public" then it also becomes available for use in using
packages.
The name of the record type is the expanded name formed by resolving the name attribute.
Because function names are always in a namespace, the name must be prefixed.
If two
A record type declaration may refer directly or indirectly to itself if
it satisfies the conditions defined in
A named record type with visibility private may be used in the definition of a
component (such as a variable, a function, a template, or another named record
type) that is itself public. Another package may reference such a component
even though it cannot reference the types used in its definition. The fact that the
record type is private, however, means that it is impossible to
override a variable or function that references the record type.
This example illustrates the definition of a recursive record type.
The record type represents a node of a binary tree containing a payload value
in each node, together with optional references to left and right subtrees.
As well as the data fields, the record type defines a depth function
that returns the maximum depth of the tree, by making recursive calls on its
subtrees.
Method calls (using the operator =?>) are described in
The following code builds a simple tree and calculates its depth:
Returning the result 3.
A more detailed example that uses a recursive named record type appears in the following section.
This example demonstrates a library package that provides a new data type to manipulate sets of atomic items.
A stylesheet that incorporates this package (by referencing
it in an
Here is the implementation of the package.
The example is not yet tested.
The definition of the
The
A name attribute, if any.
The attributes of the
The scope of an
If a
The attributes of the
For any named
For any unnamed
It is a
The following attributes control the interpretation of characters in the
m:r where m is a single character
(the r (the
decimal-separator specifies the string used to separate the
integer part from the fractional part of the formatted number; the default
value is
exponent-separator specifies the string used to separate the
mantissa from the exponent in scientific notation; the default value is
grouping-separator specifies the string typically used as a
thousands separator; the default value is
percent specifies the string used to indicate that the number
is represented as a per-hundred fraction; the default value is
per-mille specifies the string used to indicate that the number
is represented as a per-thousand fraction; the default value is
It is a zero-digit attribute is not a digit or is a digit
that does not have the numeric value zero.
The following attributes control the interpretation of characters in the zero-digit property also affects the characters used to render
digits in the formatted result:
zero-digit specifies the character used to represent the digit
zero; the default value is Nd in the
Unicode property database), and it
digit specifies the character used in the
pattern-separator specifies the character used to separate
positive and negative sub-pictures in a
The following attributes specify strings that may appear in the result of formatting the number:
infinity specifies the string used to represent the
xs:double value INF; the default value is the
string Infinity
NaN specifies the string used to represent the
xs:double value NaN (not-a-number); the default
value is the string NaN
minus-sign specifies the string used to indicate a negative
number; the default value is
It is a
Every (named or unnamed) decimal format defined in a [xsl:]use-when attributes.
The string value of an attribute or text node in the stylesheet may in particular
circumstances contain embedded expressions enclosed between curly brackets.
Attributes and text nodes that use (or are permitted to use) this mechanism are
referred to respectively as
A value template is a string consisting of an alternating sequence of fixed parts and variable parts:
A variable part consists of an optional XPath {}):
more specifically, a string conforming
to the XPath production Expr?.
An expression within a variable part may contain an unescaped curly bracket within
a
Currently no XPath expression starts with an opening curly
bracket, so the use of {{ creates no ambiguity. If an enclosed
expression ends with a closing curly bracket, no whitespace is required between
this and the closing delimiter.
The fact that the expression is optional means that the string contained between the curly brackets may be zero-length, may comprise whitespace only, or may contain XPath comments. The effective value in this case is a zero-length string, which is equivalent to omitting the variable part entirely, together with its curly-bracket delimiters.
A fixed part
may contain any characters, except that a left curly bracket {{ and a right curly bracket }}.
It is a
It is a
It is a
The result of evaluating a
value template is referred to as its
The expansion of a fixed part is obtained by replacing any double curly
brackets ({{ or }}) by the corresponding single curly
bracket.
The expansion of a variable part is as follows:
If an expression is present, the result of evaluating the enclosed XPath
If the expression is omitted, a zero-length string.
This process can raise dynamic errors, for example if the sequence contains an element with a complex content type (which cannot be atomized).
In the case of an attribute value template, the effective value becomes the string value of the new attribute node. In the case of a text value template, the effective value becomes the string value of the new text node.
{}),
following the general rules for
Curly brackets are not treated specially in an attribute value in an XSLT
Not all attributes are designated as attribute value templates. Attributes
whose value is an format attribute of
If the element containing the attribute is processed
with
The above rule applies to attribute value templates but not to text value templates, since the latter were not available in XSLT 1.0.
The following example creates an img result element from a
photograph element in the source; the value of the
src and width attributes are computed using XPath
expressions enclosed in attribute value templates:
With this source
the result would be
The following example shows how the values in a sequence are output as a space-separated list. The following literal result element:
produces the output node:
Curly brackets are
For example:
is
The [xsl:]expand-text may appear on any element in the stylesheet, and
determines whether descendant text nodes of that element are treated as text value
templates. A text node in the stylesheet is treated as a text value template if
(a) it is part of a [xsl:]expand-text attribute, and (c) on the innermost ancestor
element that has such an attribute, the value of the attribute is
yes. The attribute is boolean and
yes
(synonyms true or 1) or no (synonyms
false or 0).
This section describes how text nodes are processed when the yes. Such text nodes are referred to as text value templates.
{}).
The rules for text value templates are given in
The result of evaluating a text value template is a (possibly zero-length) text node. This text node becomes part of the result of the containing sequence constructor, and is thereafter handled exactly as if the value had appeared explicitly as a text node in the stylesheet.
The way in which the effective value is computed does not depend on any
separator attribute on a containing
separator attribute only affects how the text node is combined
with adjacent items in the result of the containing sequence constructor.
Fixed parts consisting entirely of whitespace are significant and are handled in the same way as any other fixed part. This is different from the default treatment of “boundary space” in XQuery.
This will typically output the message text Processing id=A123,
step=5.
Note that although this is a very readable way of expressing the computation
performed by the function, the semantics are somewhat complex, and this could
mean that execution is inefficient. The function computes the value of $x
+ $y as an integer, and then constructs a text node containing the
string representation of this integer (preceded and followed by whitespace).
Because the declared result type of the function is xs:integer,
this text node is then atomized, giving an xs:untypedAtomic item,
and the xs:untypedAtomic item is then cast to an
xs:integer.
The main motivations for adding text value templates to the XSLT language are
firstly, to make it easier to construct parameterized text in contexts such as
select attribute is not
ideal.
The facility is only present if enabled using the
[xsl:]expand-text attribute. This is partly for backwards
compatibility, and partly to avoid creating difficulties when constructing
content that is rich in curly brackets, for example JavaScript code or CSS
style sheets.
Many
Four kinds of nodes may be encountered in a sequence constructor:
A
if the [xsl:]expand-text is no, or in the absence
of this attribute, the text node in the stylesheet is copied to create a
new parentless text node in the result of the sequence constructor.
Otherwise (the [xsl:]expand-text is
yes), the text node in the stylesheet is processed as
described in
A
An XSLT
Several instructions, such as
Three instructions serve primarily to evaluate XPath expressions:
The select
attribute.
The
The
These three instructions may return atomic items, function items, or nodes.
An
However:
For the effect of the
For the effect of the
The way that
The as attribute of the containing
In the absence of an as attribute, the result of a
function is the
The coercion rules do not merge adjacent text nodes
or insert separators between adjacent items. This means it is often inappropriate
to use
The result of a function, or the value of a variable, may contain nodes
(such as elements, attributes, and text nodes) that are not attached to any parent node
in a / causes a type error if the root of the tree containing
the context node is not a document node.
Parentless attribute nodes require particular care because they have no
namespace nodes associated with them. A parentless attribute node is not
permitted to contain namespace-sensitive content (for example, a QName or an
XPath expression) because there is no information enabling the prefix to be
resolved to a namespace URI. Parentless attributes can be useful in an
application (for example, they provide an alternative to the use of
attribute sets: see
The sequence may be returned as the result of the containing element. This
happens, for example, when
the element containing the
sequence constructor is
The sequence may be used to construct the content of a new element or document
node. This happens when the sequence constructor appears as the content of a
as attribute. For details, see
The sequence may be used to construct the
Many instructions, for example
When constructing the content of an element, the inherit-namespaces
attribute of the xsl:inherit-namespaces property of the literal
result element, determines whether namespace nodes are to be inherited. The effect
of this attribute is described in the rules that follow.
The
The containing instruction may generate attribute nodes and/or namespace
nodes, as specified in the rules for the individual instruction. For
example, these nodes may be produced by expanding an
[xsl:]use-attribute-sets attribute, or by expanding the
attributes of a
Any array item in the sequence (see
This situation only arises if the XPath 3.1 feature is implemented.
Note that if the array contains nodes, this operation leaves the nodes in the sequence: they
are not
Any atomic item in the sequence is cast to a string.
Casting from xs:QName or xs:NOTATION to
xs:string always succeeds, because these values retain a
prefix for this purpose. However, there is no guarantee that the prefix
used will always be meaningful in the context where the resulting string
is used.
Any consecutive sequence of strings in the sequence is converted
to a single text node, whose
Any document node within the sequence is replaced by a sequence containing each of its children, in document order.
Zero-length text nodes within the sequence are removed.
Adjacent text nodes within the sequence are merged into a single text node.
Invalid items in the sequence are detected as follows.
It is a
It is a
It is a
It is a
It is a
The error code reflects the fact that this error was at one time classified as a dynamic error rather than a type error.
If the sequence contains two or more namespace nodes with the same
name (or no name) and the same
Since the order of namespace nodes is
If an attribute A in the sequence has the same name as
another attribute B that appears later in the sequence,
then attribute A is discarded from the sequence. Before
discarding attribute A, the processor
Each node in the resulting sequence is attached as a namespace, attribute,
or child of the newly constructed element or document node. Conceptually
this involves making a deep copy of the node; in practice, however, copying
the node will only be necessary if the existing node can be referenced
independently of the parent to which it is being attached. When copying an
element or processing instruction node, its base URI property is changed to
be the same as that of its new parent, unless it has an
xml:base attribute (see xml:base
attribute, its base URI is the value of that attribute, resolved (if it is
relative) against the base URI of the new parent node.
Except for the handling of base URI, the copying
of a node follows the rules of the copy-namespaces="yes" copy-accumulators="no"
validation="preserve".
This has the consequence that the type annotation and the values of the
nilled, is-id, and is-idrefs
properties are retained. However, if the node under construction (the new
parent of the node being copied) uses a validation mode other than
preserve, this will be transient: the values will be
recomputed when the new parent node is validated.
If the newly constructed node is an element node, then namespace fixup is
applied to this node, as described in
If the newly constructed node is an element node, and if namespaces are inherited, then each namespace node of the newly constructed element (including any produced as a result of the namespace fixup process) is copied to each descendant element of the newly constructed element, unless that element or an intermediate element already has a namespace node with the same name (or absence of a name) or that descendant element or an intermediate element is in no namespace and the namespace node has no name.
Consider the following stylesheet fragment:
This fragment consists of a literal result element td, containing
a sequence constructor that consists of two instructions:
td
instruction causes a td element to be created; the new attribute
therefore becomes an attribute of the new td element, while the
text node created by the td element (unless it is zero-length, in which case
it is discarded).
Consider the following stylesheet fragment:
This produces the output (when indented):
The difference between the two cases is that for the e element,
the sequence constructor generates a sequence of five atomic items, which are
therefore separated by spaces. For the f element, the content is a
sequence of five text nodes, which are concatenated without space
separation.
It is important to be aware of the distinction between
select expression unchanged, and
The instructions select attribute of the
instruction, or the select attribute allows the content to be specified by means of an
XPath expression, while the sequence constructor allows it to be specified by
means of a sequence of XSLT instructions. The select attribute or
sequence constructor is evaluated to produce a result sequence, and the
These rules are also used to compute the
Zero-length text nodes in the sequence are discarded.
Adjacent text nodes in the sequence are merged into a single text node.
The sequence is
Every value in the atomized sequence is cast to a string.
The strings within the resulting sequence are concatenated, with a (possibly zero-length) separator inserted between successive strings. The default separator depends on the containing instruction; except where otherwise specified, it is a single space.
In the case of select attribute is used, or a zero-length string otherwise;
a different separator can be specified
using the separator attribute of the instruction.
In the case of
In the case of
The resulting string forms the
Consider the following stylesheet fragment:
This produces the output:
The difference between the three cases is as follows. For the
e attribute, the sequence constructor generates a sequence of
five atomic items, which are therefore separated by spaces. For the
f attribute, the content is supplied as a sequence of five text
nodes, which are concatenated without space separation. For the g
attribute, the
Specifying separator="" on the first
e="12345". A separator attribute on the second
separator on the third
If an attribute value template contains a sequence of fixed and variable parts,
no additional whitespace is inserted between the expansions of the fixed and
variable parts. For example, the a="chapters{4 to 6}" is
a="chapters4 5 6".
In a tree supplied to or constructed by an XSLT processor, the constraints
relating to namespace nodes that are specified in
If an element node has an
If an element node has an attribute node whose
Every element xml and whose http://www.w3.org/XML/1998/namespace. The
namespace prefix xml
http://www.w3.org/XML/1998/namespace
A namespace node xmlns or the string value
http://www.w3.org/2000/xmlns/.
The actual namespace nodes that are added to the tree by the namespace fixup
process are
Namespace fixup
Namespace fixup xs:QName or xs:NOTATION
that forms the typed value of an element or attribute node.
Namespace fixup is not used to create namespace declarations for
xs:QName or xs:NOTATION values appearing in the
content of an element or attribute.
Where values acquire such types as the result of validation, namespace fixup does not come into play, because namespace fixup happens before validation: in this situation, it is the user’s responsibility to ensure that the element being validated has the required namespace nodes to enable validation to succeed.
Where existing elements are copied along with their existing validation="preserve") the rules require that existing
namespace nodes are also copied, so that any namespace-sensitive values remain
valid.
Where existing attributes are copied along with their existing type
annotations, the rules of the XDM data model require that a parentless
attribute node cannot contain a namespace-sensitive typed value; this means
that it is an error to copy an attribute using
validation="preserve" if it contains namespace-sensitive
content.
Namespace fixup is applied to every element that is constructed using a
A source document (an input document, a document returned by the
In an Infoset (see [xsl:]inherit-namespaces="no" on the instruction that
creates the parent element.
This has implications on serialization, defined in xmlns="". When the
same result tree is serialized as XML 1.1, however, it is possible to undeclare
any namespace on the child element (for example, xmlns:foo="") to
prevent this inheritance taking place.
xs:anyURI datatype as defined in
URI References are used in XSLT with three main roles:
As namespace URIs
As collation URIs
As identifiers for resources such as stylesheet modules; these resources are
typically accessible using a protocol such as HTTP. Examples of such
identifiers are the URIs used in the href attributes of
The rules for namespace URIs are given in
The rules for collation URIs are given in
URI references used to identify external resources must conform to the same rules as
the locator attribute (href) defined in section 5.4 of href attribute of
Other URI references appearing in an XSLT stylesheet document, for example the system
identifiers of external entities or the value of the xml:base attribute,
must follow the rules in their respective specifications.
The base URI of an element node in the stylesheet
is determined as defined in xml:base attribute within the
stylesheet, this value
Template rules define the processing that can be applied to items that match a particular
An match attribute or a name attribute, or both. An
match
attribute mode attribute and no
priority attribute. An
name
attribute visibility
attribute.
If an match attribute, then
it is a name attribute, then it is a
A
For details of the optional
If an as attribute of the as attribute defines the required type of the result. The
result of evaluating the as attribute is specified, the default value is item()*,
which permits any value. No conversion then takes place.
It is a
If the visibility attribute is present with the value
abstract then (a) the match attribute.
If the parent of the
There is a name attribute, and the
Both the following conditions are true:
There is a match attribute.
The value of the mode attribute,
or in its absence the string #default,
is a whitespace-separated sequence of tokens in which each token satisfies
one of the following conditions:
The token is an EQName representing the name of a mode that is exposed,
with visibility equal to public, by the package identified by the containing
The token is #default, and there is an ancestor-or-self element with
a default-mode attribute whose value is an EQName representing the name of a mode that is exposed,
with visibility equal to public, by the package identified by the containing
The token #unnamed is not allowed because the unnamed mode never has public visibility.
The token #all is not allowed because its intended meaning would not be obvious.
This section describes
A match attribute. The
match attribute is a
For example, an XML document might contain:
The following emph elements and produces a fo:wrapper element with
a font-weight property of bold.
A match
attribute. The
In XSLT 4.0, patterns can match any kind of item: atomic items and function items as well as nodes.
A
There are several kinds of pattern:
. (dot) followed by zero or more predicates in square
brackets, and it matches any item for which each of the predicates evaluates
to true.
The detailed semantics are given in .[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).
~T (where T is an true.
The parameter T can also be a "|".
For example, ~(array(*) | map(*)) matches arrays and maps, while
~(text() | comment()) matches text nodes and comment nodes.
The type pattern match="~(text() | comment())" has almost the same effect as
the match="text() | comment()",
but the rules for calculating a default priority
are different: see
The syntax for GNode patterns
(
The specification uses the phrases
Here are some examples of 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.
~item() matches any item.
~node() matches any XNode.
(Note the distinction from the pattern node().)
~xs:date matches any
atomic item of type xs:date (or a type derived by
restriction from xs:date).
~xs:date[. gt current-date()] matches any date in
the future.
~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 a node.
~fn(*) matches any
function item.
~(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.
~(xs:date | xs:dateTime | xs:time) matches any atomic item
that is an instance of xs:date, xs:dateTime, or xs:time.
~(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. Contrast
~array(xs:date | xs:dateTime | xs:time) which allows
the three types to be mixed within a single array.
~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".
This can also be written ~record(first, last, location as enum('UK')).
~record(longitude, latitude) matches any map with exactly two entries,
whose keys are the strings "longitude"
and "latitude".
~record(title, author as enum("Dickens")) matches having an entry whose keys is the string "title",
plus an entry whose key is the string "author" and whose associated value
is the string "Dickens".
~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".
~complex matches any value that is an instance of the item type
declared in an "complex"
~complex[?i eq 0] matches any value that is an instance of the
item type declared in an "complex" and that is a map with an entry having key i and value zero.
~jnode("date of birth", xs:date) matches a JNode that encapsulates a map entry
whose key is the string "date of birth" and whose associated value is an atomic item
of type xs:date.
* matches any element node.
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 tableelement 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
(class
attribute).
@(class|type|kind) matches any attribute named class
or type or kind.
@* matches any attribute node.
$xyz matches any GNode that is present in
the value of the variable $xyz. Note that it will not
match any other item that is present in the value of the variable.
$xyz//* matches any element that is a
descendant of a node that is present in the value of the variable
$xyz. It will also match certain JNodes if the
variable $xyz includes JNodes.
doc('product.xml')//* matches any element
within the document whose document URI is product.xml.
The patterns jnode(), jnode(*), and jnode(*, item()*)
are equivalent, and match any JNode.
jnode("date of birth") matches any JNode representing a map
entry with key "date of birth".
jnode(*, array(xs:integer)) matches any JNode representing a map
entry or array item whose value is an array of integers.
jnode(books, array(record(Author, Title)))
matches any JNode representing a map
entry whose key is "books" and whose content is an array of records,
each record having entries named "Author" and "Title" (with other
entries also allowed).
jnode(*, record(Author as enum("Dickens"), Title))
matches any JNode whose content is a map
having an entry with key "Author" and value "Dickens",
plus an entry with key "Title" (with other
entries also allowed).
jnode(()) matches any root JNode (that is, a JNode whose
jnode((), array(map(*))) matches any root JNode whose
Where an attribute is defined to contain a
The complete grammar for patterns is listed in
The lexical rules for patterns are the same as the lexical rules
for XPath expressions, as defined in (: ... :). All other provisions of the XPath grammar apply
where relevant, for example the rules for whitespace handling and
extra-grammatical constraints.
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
~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"
An GNodePattern matches GNodes in a GTree (for example, a tree
representing the contents of an XML or JSON document), by specifying a path that
can be used to locate the nodes: for example order matches an element node
named order within an XTree, or a JNode with ·jkey· "order"
within a JTree; similarly, billing-address/city matches an element node named city
whose parent node is an element named billing-address, or a JNode with ·jkey· "city"
whose parent is a JNode with ·jkey· "billing-address".
The following sections define the rules for each of these groups.
A
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.
The predicate pattern .[P1][P2][P3]
is equivalent to the type pattern ~item()[P1][P2][P3].
For example, the pattern .[contains(., "XSLT")]
matches any item whose atomized value contains "XSLT" as a substring.
It matches values such as the string "XSLT Transformations", the
xs:anyURI value
http://www.w3.org/TR/XSLT, the attribute node
class="XSD XSLT XPath", and the singleton array [ "XSLT 4.0" ].
Evaluation of this example pattern may fail with a dynamic error if the item in question
has an atomized value that is not a string, or that is a sequence of strings: an example might
be the array [ "XSLT", 1999 ]. It will also fail if the item cannot be atomized,
for example if it is a map. The rules in
match="~record(longitude, latitude)"
matches any map that includes the key values "longitude"
and "latitude".
A type pattern matches an item if both the following conditions are true:
The item can be successfully coerced to the given item type, by applying the
The item (after such coercion) satisfies each of the predicates.
For example:
~xs:integer matches any instance of
xs:integer
~xs:integer[. gt 0] matches
any positive integer.
~(xs:string | xs:untypedAtomic)[matches(., '[0-9]+')] matches
any instance of xs:string or xs:untypedAtomic that
contains a sequence of decimal digits.
~node() matches any XNode. (This is not the same as the pattern
node(), which for historical reasons only matches element, text, comment,
and processing instruction nodes).
~record(first as enum("Sharon"), last)
matches any map having entries with the string-valued keys "first" and "last",
where the entry for the key "first" is equal to the string "Sharon"
~jnode(address, record(address-line-1, address-line-2)) matches a JNode whose
·jkey· property is the string "address", and whose content matches the given record type.
More formally, an item $J matches a pattern ~T[P1][P2][P3] if
the XPath expression let $JJ as T := J return exists($JJ[P1][P2][P3]) is true.
As with predicate patterns, numeric predicates are allowed, but serve no useful purpose.
An error in evaluating the equivalent expression (for example, when the item cannot be coerced to the required type) means that the item is treated as not matching the pattern.
The item type in a pattern can be any ItemType, but patterns that match
XNodes or JNodes can usually be expressed more concisely
as a NodePattern (see match="~element(PERSON)" has the same meaning as
match="element(PERSON)", which in turn is usually abbreviated to
match="PERSON" (although match="PERSON" will also match JNodes).
EQName
(for example doc('a.xml')/id('abc'),
it is no longer necessary to put the second call in parentheses.
GNode patterns are used to match GNodes: that is, XNodes or JNodes.
Many of the constructs within a GNode pattern have names that are chosen to align
with the XPath 4.0 grammar.
Constructs whose names are suffixed with P are restricted forms of
the corresponding XPath 4.0 construct without the suffix: for example,
StepExprP is a restricted form of StepExpr. Constructs labeled with
the subpercript “XP” are defined in
The syntax of a
In a EQName used for the function name must bind to
one of the functions
In the case of a call to the
As with XPath expressions, the pattern / union /* can be parsed in
two different ways, and the chosen interpretation is to treat
union as an element name rather than as an operator. The other
interpretation can be achieved by writing (/) union (/*)
This section defines the formal meaning of a
The process for determining whether a GNode matches a
The
/ or //
operator, and (b) it is not contained (directly or indirectly) within a
/ or // operator
An
The adjustments that are made to a
The NodeTest is adjusted to ensure that the pattern will (in most cases) match
XNodes or JNodes but not both. Specifically, if the principal node kind of the
axis is element, then any Selector within the NodeTest
that takes the form of an EQName or Wildcard is wrapped in an match="*" is interpreted as
match="element(*)", and match="employee" is interpreted
as match="element(employee)".
The rationale for this is firstly, that it improves the clarity of the code if it is clear whether patterns are intended to match XNodes or JNodes; and secondly, that it enables pattern matching to be optimized and simplifies streamability analysis.
In addition, the axis is adjusted to allow the step to match a parentless GNode. The
adjustment depends on the axis used in this step, whether it appears
explicitly or implicitly (according to the rules of
If the NodeTest in PS is
document-node() (optionally with arguments), and if no
explicit axis is specified, then the axis in step PS is
taken as self rather than child.
If PS uses the child axis (explicitly or implicitly), and
if the NodeTest in PS is not
document-node() (optionally with arguments), then the
axis in step PS is replaced by child-or-top,
which is defined as follows. If the context node is a parentless
element, comment, processing instruction, or text node then the
child-or-top axis selects the context node; otherwise
it selects the children of the context node. It is a forwards axis
whose principal node kind is element.
If PS uses the attribute axis (explicitly or implicitly),
then the axis in step PS is replaced by
attribute-or-top, which is defined as follows. If the
context node is an attribute node with no parent, then the
attribute-or-top axis selects the context node;
otherwise it selects the attributes of the context node. It is a
forwards axis whose principal node kind is attribute.
If PS uses the namespace axis (explicitly or implicitly), then the axis in step
PS is replaced by namespace-or-top, which
is defined as follows. If the context node is a namespace node with no
parent, then the namespace-or-top axis selects the
context node; otherwise it selects the namespace nodes of the context
node. It is a forwards axis whose principal node kind is
namespace.
The axes child-or-top, attribute-or-top, and
namespace-or-top are introduced only for definitional
purposes. They cannot be used explicitly in a user-written pattern or
expression.
The purpose of this adjustment is to ensure that a pattern such as
person matches any element named person,
even if it has no parent; and similarly, that the pattern
@width matches any attribute named width,
even a parentless attribute. The rule also ensures that a pattern using a
NodeTest of the form document-node(...)
matches a document node. The pattern node() will match any
element, text node, comment, or processing instruction, whether or not it
has a parent. For backwards compatibility reasons, the pattern
node(), when used without an explicit axis, does not
match document nodes, attribute nodes, or namespace nodes. The rules are
also phrased to ensure that positional patterns of the form
para[1] continue to count nodes relative to their parent,
if they have one. To match any XNode at all,
XSLT 4.0 allows the pattern ~node() to be
used.
The adjustment is not necessary in the case of JNodes, because a JNode
with ·jkey· value "person" will necessarily have a parent JNode.
The meaning of the pattern is then defined in terms of the semantics of the
equivalent expression, denoted below as EE.
Specifically, an item N matches a EE is the
N is a GNode, and the result of evaluating the expression
root(.)//(EE) with a
If a pattern appears in an attribute of an XSLT element that
is processed with true.
The p matches any p element. The equivalent expression,
after adjustment, is child-or-top::element(p), and the pattern matches because a p
element will always be present in the result of evaluating the
equivalent root(.)//(child-or-top::element(p)).
Similarly, / matches a
document node, and only a document node. The equivalent expression, after adjustment,
is self::document-node(), and the pattern matches because the result
of the equivalent root(.)//(self::document-node()) returns the root node of the tree containing the
context node if and only if it is a document node.
The node() matches all XNodes selected by the expression
root(.)//(child-or-top::node()), that is, all element, text,
comment, and processing instruction nodes, whether or not they have a parent.
It does not match attribute or namespace nodes because the expression does not
select nodes using the attribute or namespace axes. It does not match document
nodes because for backwards compatibility reasons the child-or-top
axis does not match a document node.
The pattern ~node() matches all XNodes.
The $V matches all XNodes selected by the expression
root(.)//($V), that is, all XNodes in the value of $V (which
will typically be a global variable, though when the pattern is used in
contexts such as the
The doc('product.xml')//product matches all XNodes selected by the
expression root(.)//(doc('product.xml')//product), that is, all
product elements in the document whose URI is
product.xml.
The root(.)/self::E matches an E element that is the root
of a tree (that is, an E element with no parent node).
Although the semantics of book/chapter/section can be examined from right to left. A node
will only match this pattern if it is a section element; and then,
only if its parent is a chapter; and then, only if the parent of that
chapter is a book. When the pattern uses the
// operator, one can still read it from right to left, but this
time testing the ancestors of a node rather than its parent. For example
appendix//section matches every section element that
has an ancestor appendix element.
The formal definition, however, is useful for understanding the meaning of a
pattern such as para[1]. This matches any node selected by the
expression root(.)//(child-or-top::para[1]): that is, any
para element that is the first para child of its
parent, or a para element that has no parent.
The pattern jnode(code, xs:string) matches any
JNode whose ·jkey· is the string "code" and whose ·jvalue·
is an instance of xs:string.
The pattern jnode("date of birth", xs:date) matches any
JNode whose ·jkey· is the string "date of birth" and whose ·jvalue·
is an instance of xs:date.
The pattern jnode(*, array(*)) matches any
JNode whose ·jvalue· is an array, regardless of its ·jkey· property.
The pattern jnode(*, record(Author, Title))[ancestor::books] matches any
JNode whose ·jvalue· is an instance of the type record(Author, Title),
provided it has an ancestor with the ·jkey· value "books".
The pattern jnode(*, record(Author as enum("Dickens"), Title)) matches any
JNode whose ·jvalue· is a map having an Author entry with the value
"Dickens", a Title entry with any value, and optionally
other entries.
The pattern jnode(*)[jkey() = current-date()] matches any
JNode whose ·jkey· property is an xs:date value equal to the current date.
The comparison uses the implicit timezone from the dynamic context. The rules for error
handling in patterns ensure that any JNode whose ·jkey· value is of a type other
than xs:date does not match, because evaluation of the predicate raises an error.
The intersect and except operators
do not always have the intuitive meaning. Simple cases such as
* except A, or @* except (@code, @name)
are unproblematic, but expressions using the descendant axis can
be surprising.
Consider the pattern para except appendix//para.
Perhaps unexpectedly, this matches the para element
in the XML tree shown below:
This is because there is an element $S (specifically,
the section element), such that the expression
$S//(para except appendix//para) selects this
para element.
An implementation, of course, may use any algorithm it wishes for evaluating patterns, so long as the result corresponds with the formal definition above. An implementation that followed the formal definition by evaluating the equivalent expression and then testing the membership of a specific node in the result would probably be very inefficient.
element(p:*) and element(a|b).
priority
attribute is specified on an match attribute.
Unless otherwise specified, the default priority for a pattern is +0.5. For some simple patterns, listed below, there is a lower default priority in the range -1 (minus one) to +1.
A higher numeric value denotes a higher priority: a rule with priority 1 is selected in preference to a rule with priority 0, which in turn is prefered over one with priority -1.
The default priority for the pattern . (a predicate pattern with
no predicates, which matches any item) is -1 (minus one).
For a
For a
For a
For the item type item(), the default priority is -1 (minus one).
For any item type that is a
jnode(*), element() or element(N)), the default
priority is the same as that of the corresponding GNode Pattern:
see
For the item type function(*),
the default priority is -0.5.
For the item types array(*) and map(*),
the default priority is -0.25.
For the item type xs:anyAtomicType,
the default priority is -0.5.
For the 19 XSD-defined primitive atomic types, and for xs:untypedAtomic,
the default priority is 0.
For an atomic type other than a primitive type, the default priority is a value greater than
0 (zero) and less than 0.5 that reflects its depth in the type hierarchy. Specifically, the priority
is computed as 0.5 - 2^-N where N is the number of
derivation steps from xs:anyAtomicType. This formula also works for primitive types. For example:
| Type | Depth (N) | Priority |
|---|---|---|
xs:decimal | 1 | 0 |
xs:integer | 2 | 0.25 |
xs:long | 3 | 0.375 |
xs:int | 4 | 0.4375 |
For an enum type, the default priority is 0.25.
For any other item type, the default priority is 0.
For a
If the pattern is a
If the pattern is a
This is a backwards incompatible change from XSLT 3.0 and earlier versions, which treated the template rule as equivalent to multiple template rules with different priorities.
The change is made because of the increasing complexity of extending
the rule to patterns like @(a|b), or attribute(a|b, xs:integer)
which are defined to be semantically identical to equivalent union patterns;
and to prevent confusion with type patterns such as
type(element(a)|element(b)), where different rules apply.
The change affects any template rule with a union pattern that
(a) has no explicit priority attribute, and (b) has multiple branches with
different default priority. It is
The change has two effects. Firstly, if two alternatives
in a union pattern have different priority
(for example in a pattern such as a | b/c, the priority of one of
the branches will be raised to that of the other branch. Secondly, in cases where
the same item matches both branches, a call on xsl:next-match will
never cause the same template rule to be evaluated repeatedly.
If the pattern is an
If the pattern is a /, then the priority is -0.5.
If the pattern is a processing-instruction(
) or processing-instruction(
) optionally preceded by a
If the pattern is a
The symbols E, A, and T represent an arbitrary element name, attribute name, and type name respectively;
The symbol W represents a
*
(for example prefix:* or *:local);
The symbol * represents
itself.
The presence or absence of the symbol ? following a type
name does not affect the priority.
The default priority of a pattern is always less than one, which means that user-allocated priorities greater than or equal to one will always rank higher than a defaulted priority.
| Format | Priority | Notes |
|---|---|---|
element()
| -0.5 | (equivalent to *) |
element(*)
| -0.5 | (equivalent to *) |
attribute()
| -0.5 | (equivalent to @*) |
attribute(*)
| -0.5 | (equivalent to @*) |
element(W)
| -0.25 | |
attribute(W)
| -0.25 | |
element(E)
| 0 | (equivalent to E) |
element(*, T)
| 0 | (matches by type only) |
attribute(A)
| 0 | (equivalent to @A) |
attribute(*, T)
| 0 | (matches by type only) |
element(W, T)
| 0.125 | |
element(E, T)
| 0.25 | (matches by name and type) |
schema-element(E)
| 0.25 | (matches by substitution group and type) |
attribute(W, T)
| 0.125 | |
attribute(A, T)
| 0.25 | (matches by name and type) |
schema-attribute(A)
| 0.25 | (matches by name and type) |
For a pattern such as element(A|B) or attribute(A|B)
(more specifically, for any
For example, the default priority of element(x|y) is 0, and
the default priority of element(p:*|q:*, t) is 0.125.
The effect of this rule is to make the pattern element(A|B)
equivalent to element(A)|element(B).
If the pattern is a
#any, and the pattern includes
an unprefixed element name E, then the default priority is calculated as if this had been written
*:E.If the pattern is a :**:
If the pattern is a
The default priority of the pattern jnode(*) is −0.5.
The default priority of the equivalent pattern
jnode(*, item()*) is also −0.5.
The default priority of the pattern jnode(S),
where S is any constant, is 0 (zero).
The default priority of the equivalent pattern jnode(S, item()*),
where S is any constant, is also 0 (zero).
The default priority of the pattern jnode(()) is 0 (zero).
The default priority of the equivalent pattern jnode((), item()*) is also 0 (zero).
The default priority of the pattern jnode(*, T),
where T is any sequence type other than item()*, is 0 (zero).
The default priority of the pattern jnode(S, T),
where S is any constant, and T is any sequence type other
than item()*, is +0.25.
The default priority of the pattern jnode((), T),
where T is any sequence type other
than item()*, is +0.25.
In all other cases, the default priority is +0.5.
In many cases this means that highly selective patterns have higher priority than
less selective patterns. The most common kind of pattern (a pattern that tests for
a node of a particular kind, with a particular
However, it is not invariably true that a more selective pattern has higher
priority than a less selective pattern. For example, the priority of the pattern
node()[self::*] is higher than that of the pattern
salary. Similarly, the patterns attribute(*,
xs:decimal) and attribute(*, xs:short) have the same
priority, despite the fact that the latter pattern matches a subset of the nodes
matched by the former. Therefore, to achieve clarity in a
The patterns element(N) and element(N, xs:anyType?)
have different default priority even though they match exactly the same nodes.
Conversely, element(N, xs:anyType) and element(N, xs:anyType?)
have the same default priority even though the first is more restrictive (it does not match
elements that are nilled).
A
The reason for this provision is that it is difficult for the stylesheet author to predict which predicates in a pattern will actually be evaluated. In the case of match patterns in template rules, it is not even possible to predict which patterns will be evaluated against a particular node.
There is a risk that ignoring errors in this way may make programming mistakes harder to debug. Implementations may mitigate this by providing warnings or other diagnostics when evaluation of a pattern triggers an error condition.
Static errors in patterns, including dynamic and type errors that are raised statically as permitted by the specification, are raised in the normal way and cause the transformation to fail.
The requirement to detect and raise a
separator that can be
used to insert content between adjacent items. [This change was in the
editor's draft adopted as a baseline when the WG commenced work.]
The
If the instruction has one or more
Each item in the input sequence is processed by
finding a
Suppose the source document is as follows:
This can be processed using the two template rules shown below.
There is no template rule for the document node; the built-in template rule for
this node will cause the message element to be processed. The
template rule for the message element causes a p element
to be written to the p element are constructed as the result of the
message element (a text node containing the
value Proceed , an emph element node, and a text node
containing the value to the exit!). The two text nodes are
processed using the built-in template rule for text nodes, which returns a copy of
the text node. The emph element is processed using the explicit
template rule that specifies match="emph".
When the emph element is processed, this template rule constructs a
b element. The contents of the b element are
constructed by means of another at once). This is again processed using the built-in template
rule for text nodes, which returns a copy of the text node.
The final result of the match="message" template rule thus consists
of a p element node with three children: a text node containing the
value Proceed , a b element that is the parent of a
text node containing the value at once, and a text node containing
the value to the exit!. This
The default value of the select attribute is child::node(),
which causes all the children of the context node to be processed.
It is a select
attribute is evaluated when the
A select attribute can be used to process items selected by an expression instead of processing all children. The
value of the select attribute is an
The following example processes all of the given-name children of the
author elements that are children of
author-group:
It is also possible to process elements that are not descendants of the context
node. This example assumes that a department element has
group children and employee descendants. It finds an
employee’s department and then processes the group children of
the department.
It is possible to write template rules that are matched according to the schema-defined type of an element or attribute. The following example applies different formatting to the children of an element depending on their type:
The
Multiple
It is possible for there to be two matching descendants where one is a descendant of the other. This case is not treated specially: both descendants will be processed as usual.
For example, given a source document
the rule
will process both the outer div and inner div
elements.
This means that if the template rule for the div element processes
its own children, then these grandchildren will be processed more than once, which
is probably not what is required. The solution is to process one level at a time
in a recursive descent, by using select="div" in place of
select=".//div"
This example reads a non-XML text file and processes it line-by-line, applying different template rules based on the content of each line:
This example reads a JSON data file and formats it as XHTML.
It takes the following JSON data as input:
The following template rules are used. The setting expand-text="yes" is assumed:
The
Implementations may be able to detect such loops in some cases, but the
possibility exists that a
separator attributeIf the separator attribute of
For example, if the ARTICLE element has a number of element children named AUTHOR,
the following code will produce a sorted, comma-separated list of authors:
The node identity of any text nodes that are inserted is
If the separator is a zero-length string, then a zero-length text node is inserted into the sequence. (If the
sequence is used for constructing the value of a node, then zero-length text nodes will be discarded: see
It is possible for a selected item to match more
than one
First, only the matching template rule or rules with the highest
Next, of the remaining matching rules, only those with the highest priority are considered. Other matching template rules with lower priority are eliminated from consideration.
priority attribute on the
The value of the priority attribute xs:decimal type defined in
If this leaves more than one matching template rule, then:
If the on-multiple-match="fail" is specified in the
mode declaration, a dynamic error is raised. The error is treated as
occurring in the
It is a on-multiple-match
attribute with the value fail.
Otherwise, of the matching template rules that remain, the one that
occurs last in
This was a recoverable error in XSLT 2.0, meaning that it was
implementation-defined whether the error was raised, or whether the
ambiguity was resolved by taking the last matching rule in declaration
order. In XSLT 3.0 and 4.0 this situation is not an error unless the
attribute value on-multiple-match="fail" is specified in the
mode declaration. It is also possible to request warnings when this
condition arises, by means of the attribute warning-on-multiple-match="yes".
Modes are identified by an
as="sequence-type" which declares the return type of
all template rules in that mode.
copy-namespaces which determines whether or not the built-in
template rule copies unused namespace bindings.
mode attribute is specified on an
[xsl:]default-mode attribute of a containing
element.
Every
A name
attribute, if any.
The declared-modes attribute of
the [xsl:]default-mode attribute of a containing
element, and the name attribute
equal to that mode name, plus the attribute
visibility="private".
The attributes of the
| Attribute | Values | Meaning |
|---|---|---|
| name | An | Specifies the name of the mode. If omitted, this
|
| as | A SequenceType | Declares the type of value returned by all
template rules in this mode. If any template rules in this mode declare their
return type using an as attribute on |
| streamable | yes or no (default
no) | Determines whether template rules in this mode are to be
capable of being processed using yes is specified, then the body of any |
| use-accumulators | List of accumulator names, or #all (default is the empty list) | Relevant only when this mode is the |
| on-no-match | One of deep-copy,
shallow-copy, deep-skip,
shallow-skip, text-only-copy or
fail (default
text-only-copy) | Determines selection of the built-in |
| on-multiple-match | One of fail or use-last (default
use-last) | Defines the action to be taken when
fail
indicates that it is a use-last indicates that the
situation is not to be treated as an error (the last template in |
| warning-on-no-match | One of yes or no. The default is
| Requests the |
| warning-on-multiple-match | One of yes or no. The default is
| Requests the |
| typed | One of yes, no,
strict, lax, or unspecified.
The default is unspecified. | See |
| copy-namespaces | One of yes or no. The default is
yes. | If on-no-match is shallow-copy,
shallow-copy-all, or deep-copy, this attribute determines the
effective value of the copy-namespaces attribute on the implicit xsl:copy
or xsl:copy-of instruction in the built-in template rule
(see |
| visibility | One of public, private, or
final. The default is private. | See name attribute is absent, then the
visibility attribute if present
private.private. |
warning-on-no-match and warning-on-multiple-match
attributes of
streamable="yes".
For any named name attribute, and that specifies an explicit
value for the required attribute. If there is
no such declaration, the default value of the attribute is used. If
there is more than one such declaration, the one with highest
For the name attribute, and that specifies an explicit value for the
required attribute. If there is no such declaration, the default value of the
attribute is used. If there is more than one such declaration, the one with
highest
It is a name on the
mode
attribute of the [xsl:]default-mode attribute of the innermost containing
element that has such an attribute, which in turn defaults to
the mode attribute is present, then its value
Each token in the mode attribute
An
The token #default, to indicate that the template rule is
applicable to the mode attribute were absent
The token #unnamed, to indicate that the
template rule is applicable to the
The token #all, to indicate that the template rule is
applicable to all modes
More specifically, when a template rule specifies mode="#all" this makes the
template rule
The unnamed mode.
Every mode, other than an
Every mode that is implicitly declared within the containing
The value mode="#all"
cannot be used on a template rule declared within an
It is a mode attribute of
#all appears together with any other value.
In the case of a match
attribute) appearing as a child of mode attribute contains #all or
#unnamed, or if it contains #default and the
mode attribute is omitted when the default mode is the
The mode attribute. The value of this attribute
an
the token #default, to indicate that the
the token #unnamed, to indicate that the
the token #current, to indicate that the
If the attribute is omitted, the
When searching for a template rule to process each item selected by the
mode="#current"; it is also used by the
apply-templates Functionfn:apply-templates is introduced.Sometimes it is useful to be able to apply templates from within an XPath expression. A common example is when using XPath expressions to construct maps and arrays. For example, an array of maps might be constructed by the following code:
Such code can become verbose, and it is difficult to read because the XML form of the instructions bears literal relationship to the serialized form (typically JSON) of the result. XSLT 4.0 offers the alternative of writing it like this:
Explanation: this constructs an array with one member for each element child E of
the context node. The member is a map constructed using the
To make this possible, a subset of the functionality of the
Applies template rules to selected items.
This function is
The function call apply-templates(X), used within an XPath
<xsl:apply-templates select="X"/>
The entries that may appear in the $options map are as follows.
The
| Key | Value | Meaning |
|---|---|---|
| Supplies values for non-tunnel parameters. Each entry in the params
map binds a parameter (identified by an xs:QName value) to a supplied value.
| |
| Supplies values for tunnel parameters. Each entry in the tunnel-params
map binds a tunnel parameter (identified by an xs:QName value) to a supplied value.
| |
| Selects the mode to be used. The value may be set to an xs:QName
that matches a declared mode in the stylesheet, or to one of the special values
#current or #unnamed.
| |
xs:QName | Selects a declared mode by name. | |
#current | Selects the | |
#unnamed | Selects the | |
For each item in the value of the $select argument, the function finds
the best matching template rule in the selected mode and invokes that template rule with the supplied
parameters (if any). The result of
the function is the sequence concatenation of the results of performing this process for each
item in the selected input, in turn.
Errors may arise in the same situations as for the on-no-match="fail" and no matching template rule is found.
It is a private.
Modes are private by default: for a mode to be available for reference by
the visibility="public".
Unlike the
If no mode is specified, the function uses the unnamed mode. It does not use the default mode
(as defined by a containing [xsl:]default-mode attribute). This decision was made
in order to avoid having to retain the default mode for each XPath expression at evaluation time,
and to avoid complex rules for edge cases involving dynamic function calls.
See also the rules in
The function call: | |
apply-templates(*, {'mode': '#current', 'params': { #expand : false() } }) | |
has the same effect as the instruction: | |
The xsl:mode/@typed attribute has been clarified and expanded
to provide better control over the handling of items other than XNodes.
Typically the template rules in a particular typed
attribute of
The allowed values of the attribute are as follows:
yes, true, 1: the items processed
by this mode must be XNodes, and they must not have a type annotation
of xs:untyped or xs:untypedAtomic.
no, false, 0: the items processed
by this mode must be XNodes, and if they are elements or attributes then they must have a type annotation
of xs:untyped or xs:untypedAtomic.
The value strict is equivalent to yes, with the
additional provision that in the match pattern of any template rule that is
NameTest
used in the ForwardStepP of the first StepExprP of
a RelativePathExprP is interpreted as follows:
If the NameTest is an EQName
E, and the principal node kind of the axis of this step is
Element, then:
It is a static error if the in-scope schema declarations do not include a global element declaration for element name E
When matching templates in this mode, the element name
E appearing in this step is interpreted as
schema-element(E). (Informally, this means
that it will only match an element if it has been validated
against this element declaration).
Otherwise (the NameTest is a wildcard or the principal
node kind is Attribute or Namespace), the
template matching proceeds as if the typed attribute were
absent.
The value lax is equivalent to yes, with the
additional provision that in the match pattern of any template rule that is
NameTest
used in the ForwardStepP of the first StepExprP of
a RelativePathExprP is interpreted as follows:
If the NameTest is an EQName
E, and the principal node kind of the axis of this step is
Element, and the in-scope schema declarations include
a global element declaration for element name E, then:
When matching templates in this mode, the element name
E appearing in this step is interpreted as
schema-element(E). (Informally, this means
that it will only match an element if it has been validated
against this element declaration).
Otherwise (the NameTest is a wildcard, or the principal
node kind is Attribute or Namespace, or
there is no element declaration for E), the template
matching proceeds as if the typed attribute were absent.
If the value is ~ followed by an ~xs:anyAtomicType or ~jnode() or ~map(*), this indicates
that all items to be processed using template rules in this mode must be
of the specified item type.
If the value is the string "unspecified", or if it is omitted,
this is equivalent to specifying ~item(), indicating that there
are no constraints.
It is a mode selects an item that does not satisfy the constraints
imposed by the @typed attribute.
It is a typed="strict"
uses a match pattern that contains a RelativePathExprP whose
first StepExprP is an AxisStepP whose
ForwardStepP uses an axis whose principal node kind is
Element and whose NodeTest is an
EQName that does not correspond to the name of any global
element declaration in the
as attribute. The result type
of all template rules in this mode must be consistent with this, as must the values returned
by any built-in template rules for the mode.
Traditionally, template rules have most commonly been used to construct XDM nodes, and the
XSLT 4.0 therefore allows the result type of the template rules in a mode to be declared using the as
attribute on the item()*.
The presence of an as attribute on a mode provides useful documentation and consistency checking,
and enables the XSLT processor to infer a static type for an
If a template rule R is as attribute whose value is the SequenceType
T, then:
If R has an as attribute, the SequenceType S declared
by R must be a subtype of T.
It is a as attribute S,
and the template rule is as attribute T,
and the sequence type S is not a subtype of the sequence type T as defined
by the relationship subtype(S, T) in
If R has no as attribute, then it is treated as if it had an as
attribute set to T. This means that a
If R is applicable
to more than one mode, then it must meet the requirements of each one, which implies that these requirements
must be consistent with each other: for example, if one mode specifies as="node()" and another specifies
as="map(*)", then a type error is inevitable if the template rule is actually evaluated, and
like other type errors this can be raised statically if detected statically. An
In practice the best way to satisfy this rule is to ensure
that if a template rule is applicable to more than one mode (including
the case mode="#all"), then either (a) all those modes should have the same declared result type,
or (b) the template rule should declare an explicit result type that is compatible with each one of the relevant modes.
The requirement to return values of the correct type extends also to the built-in
template rule for the mode (see
xsl:mode element.
This is intended to allow a stylesheet design in which it is easier to
determine which rules might apply to a given An enclosing mode ensures that all the template rules for a mode are together in one place, which
makes it easier for someone reading the stylesheet to establish what is going to happen when an
An enclosing mode
The mode must have a name.
Every contained match
attribute and no name attribute.
Every contained mode
attribute: the template is implicitly
An default-mode attribute whose value is the mode’s name;
it must not have a default-mode attribute with any other value.
This means that
No
Template rules in an enclosing mode may, however, be overridden within an
There must be no other
These rules give rise to the following error conditions:
It is a name
attribute.
It is a name attribute,
with a mode attribute, or with no match attribute.
It is a default-mode
attribute whose value differs from its name attribute, or if any of those child default-mode attribute that differs from the name attribute
of the
It is a mode attribute.
It is a
The following mode might be used for formatting of numbers appearing in text:
shallow-copy-all is introduced.
When an item is
selected by
The built-in
There are on-no-match attribute of the deep-copy, shallow-copy,
shallow-copy-all,deep-skip, shallow-skip,
text-only-copy, or
fail, the default being text-only-copy. The effect of
these
The effect of processing a
tree using a on-no-match="text-only-copy" is that the textual
content of the source document is retained while losing the markup, except where
explicit template rules dictate otherwise. When an element is encountered for
which there is no explicit
The built-in rule for document nodes and element nodes is equivalent to calling
select attribute, and
with the mode attribute set to #current. If the built-in
rule was invoked with parameters, those parameters are passed on in the implicit
This is equivalent to the following in the case where there are no parameters:
The built-in
This text node may have a string value that is zero-length.
The built-in
This text node may have a string value that is zero-length.
The built-in
The built-in
The built-in select
attribute set to ?* (which selects the members of the array), and with the
mode attribute set to #current. If the built-in
rule was invoked with parameters, those parameters are passed on in the implicit
This is equivalent to the following in the case where there are no parameters:
The following example illustrates the use of built-in template rules when there are parameters.
Suppose the stylesheet contains the following instruction:
If there is no explicit template rule that matches the title
element, then the following implicit rule is used:
The effect of processing a tree using a
on-no-match="deep-copy" is that an unmatched element
in the source tree is copied unchanged to the output, together with its entire
subtree. Other unmatched items are also copied unchanged. The subtree is copied
unconditionally, without attempting to match nodes in the subtree against template
rules.
When this default action is selected for a mode M, all items (nodes, atomic items, and functions, including maps and arrays) are processed using a template rule that is equivalent to the following:
where CN is the value of the copy-namespaces attribute of the relevant
yes.
The effect of processing a tree using a
on-no-match="shallow-copy" is that the source tree is
copied unchanged to the output, except for nodes where different processing is
specified using an explicit
When this default action is selected for a mode M, all items (nodes, atomic items, and functions, including maps and arrays) are processed
using a template rule that is equivalent to the following, except that all
parameters supplied in
where CN is the value of the copy-namespaces attribute of the relevant
yes.
This rule is often referred to as the
This rule differs from the traditional identity template rule by using two
select="node() | @*" is that with two separate
instructions, the value of position() in the called templates
forms one sequence starting at 1 for the attributes, and a new sequence
starting at 1 for the children.
The following stylesheet transforms an input document by deleting all elements
named note, together with their attributes and descendants:
This processing mode is introduced in XSLT 4.0 as a variant of shallow-copy
to enable recursive descent processing of trees involving maps and arrays, such as might result
from parsing JSON input.
For all items other than maps and arrays, the effect of shallow-copy-all
is exactly the same as shallow-copy.
For arrays, the processing is as follows. A new result array is created, and its content
is populated by decomposing the input array to a sequence of
That is, the template rule is equivalent to the following, except that this does not show the propagation of template parameters:
A "value",
the corresponding value being a member of the original array. The default processing for a value
record, unless specified otherwise, is to apply templates to the value, as indicated by the rules
that follow.
For maps, the processing is as follows:
If the map contains two or more entries,
then a new result map is created, and its content is populated
by decomposing the input map using the function
If the map contains a single entry { K : V/0 }, then a new single entry
map { K: V/1 } is constructed in which V/1 is the
result of applying templates to V/0 (using the current mode, and passing
on the values of all template parameters).
This rule has the effect that if the input is a value record, the output will also be a value record.
If the map is empty, the result is the empty map.
In the first case, the template rule is equivalent to the following, except that this does not show the propagation of template parameters:
In the second case, the template rule is equivalent to the following, except that this does not show the propagation of template parameters:
The reason there is a special rule for maps with one entry is to ensure that the process terminates.
The overall effect is best understood with an example.
The following stylesheet transforms a supplied JSON document by deleting all properties
named "Note", appearing at any level:
Consider the following JSON input, converted to an array of maps by calling
the function
The logic proceeds as follows:
The outermost array is processed by applying templates to a sequence of value records, the first being in the form:
The result of applying templates to these value records is expected to comprise a new sequence of value records, which is used to construct the final output array.
Each of the value records is processed using the rule for single-entry maps. This rule
produces a new value record by applying templates to the value, that is, to a map of the form
map: { "Title": ..., "Author": ..., ... } representing a book.
Each of these books, being represented by a map with more than two entries, is processed by
a template rule that splits the map into its multiple entries, each represented as a singleton
map (a map with one key and one value). One of these single-entry maps, for example, would be
{"Title": "Steppenwolf"}.
The default processing for a single-entry map of the form
{ "Title": "Steppenwolf" } is to return the value unchanged.
This is achieved by applying templates to the string "Steppenwolf";
the default template rule for strings returns the string unchanged.
When a single-entry map in the form { "Note": "out of print" } is encountered, no output
is produced, meaning that entry in the parent map is effectively dropped. This is because there
is an explicit template rule with match="record(Note)" that matches such single-entry maps.
When a single-entry map in the form "Authors": [ "Bruce Betts", "Erica Colon" ]
is encountered, a new single-entry map is produced; it has the same key ("Authors"),
and a value obtained by applying templates to the array [ "Bruce Betts", "Erica Colon" ].
The default processing for an array, in which none of the constituents are matched by explicit
template rules, ends up delivering a copy of the array.
When the single-entry map "Authors": [ "Enid Blyton", { "Note": "possibly misattributed" } ]
is encountered, the recursive processing results in templates being applied to the map
{ "Note": "possibly misattributed" }. This matches the template rule having
match="record(Note)", which returns no output, so the entry is effectively deleted.
The map entry is deleted, but the map itself remains, so the value becomes
"Authors": [ "Enid Blyton", map: {} ].
The effect of processing a tree using a on-no-match="deep-skip" is that where no explicit template rule is
specified for an element, that element and all its descendants are ignored, and
are not copied to the result tree.
The effect of choosing on-no-match="deep-skip" is as follows:
The built-in rule for document nodes is equivalent to calling
select
attribute, and with the mode attribute set to
#current. If the built-in rule was invoked with parameters,
those parameters are passed on in the implicit
In the case where there are no parameters, this is equivalent to the following rule:
The built-in rule for all items other than document nodes (that is, for all other kinds of node, as well as atomic items and functions, including maps and and arrays) is to do nothing, that is, to return the empty sequence (without applying templates to any children or ancestors).
This is equivalent to the following rule:
The effect of processing a tree using a
on-no-match="shallow-skip" is to drop both the textual
content and the markup from the result document, except where there is an explicit
user-written
The built-in rule for document nodes and element nodes applies templates (in the current mode) first to the node’s
attributes and then to its children. If the built-in rule was invoked
with parameters, those parameters are passed on in the implicit
In the case where there are no parameters, this is equivalent to the following rule:
The built-in template rule for all other kinds of node, and for atomic items and functions (including maps, but not arrays) is empty: that is, when the item is matched, the built-in template rule returns the empty sequence.
This is equivalent to the following rule:
The built-in select
attribute set to ?* (which selects the members of the array), and with the
mode attribute set to #current. If the built-in
rule was invoked with parameters, those parameters are passed on in the implicit
This is equivalent to the following in the case where there are no parameters:
The effect of choosing on-no-match="fail" for a
The built-in template rule is effectively:
with an
It is a on-no-match="fail" when there is no
A
The
select attribute
A global
<xsl:context-item use="absent"/>
The current template rule is not affected by invoking named attribute sets (see <xsl:context-item use="absent"/> is specified.
While evaluating a
These rules ensure that when
Both
The
This is
It is a
The
Because a template rule declared as a child of
If no matching template rule is found, both
If multiple matching template rules with the same explicit or implicit priority are found,
both on-multiple-match and warning-on-multiple-match attributes of the
mode declaration.
If is entirely possible for
If a matching template rule R is found, then the result
of the
All parameters explicitly set using
If the
All
The implicit passing of non-tunnel parameters is new in XSLT 4.0, and happens only if
[xsl:]version is set to 4.0 (or greater) on the instruction, or on some ancestor element
in the stylesheet. There may be cases where this
change introduces a backward incompatibility: specifically, if the invoked template rule declares a default
value for an optional parameter, it will now take the implicitly passed value rather than the
default value. The 3.0 behavior can be therefore be retained by setting version="3.0"
on the
The template rule R is evaluated with the same
In the case where the current template rule T is
declared within an mode="#current", then the set of template rules considered by this instruction
will therefore include any overriding template rules declared in P as well as the original
rules declared in Q.
If no matching template rule is found that satisfies these criteria, the built-in
template rule for the context item is used (see
It is a
For example, suppose the stylesheet doc.xsl contains a example
elements:
Another stylesheet could import doc.xsl and modify the treatment of
example elements as follows:
The combined effect would be to transform an example into an element
of the form:
An
This example shows how an input element such as:
might be transformed into:
The following template rules achieve the required effect:
Note how the $upper-case parameter is passed implicitly through the chain of template rules.
A template rule may have parameters. The parameters are declared in the body of the
template using
Values for these parameters may be supplied in the calling
name attribute of the name attribute of the corresponding
It is not an error for these instructions to supply a parameter that does not match any parameter declared in the template rule that is invoked; unneeded parameter values are simply ignored.
A parameter may be declared as a tunnel="yes" in the
tunnel="yes" in the
corresponding
XSLT offers two constructs for processing each
Both instructions can be used to process the items in a sequence, the
elements in an array, or the entries in a map. Arrays and maps are processed by reducing them
to a sequence of items, so in what follows, the terms
The main difference between the two constructs is that with
A further difference is that
xsl:for-each instructionseparator that can be
used to insert content between adjacent items. [This change was in the
editor's draft adopted as a baseline when the WG commenced work.]
The
The select attribute is
The
The
The
The
For each item in the input sequence, evaluating the
For example, given an XML document with this structure
the following would create an HTML document containing a table with a row for each
customer element
Consider a JSON document of the form:
The following code processes this array to produce an XML representation of the same information. The cities are sorted by name:
In this example it is possible to use the expression $array?* to convert an array to a sequence.
This works because the members of the array are all single items. In the more general case (a member
of the array might be the empty sequence, corresponding to the JSON value null, or it
might be a sequence containing several items), array:members can be
used to deliver the contents of the array as a sequence of
Consider a JSON document of the form:
The requirement is to convert this to the following XML:
The following code achieves this transformation:
In this example the expression $array?* cannot be used on the inner arrays
because JSON nulls (which translate to the empty sequence in XDM) would be lost. Instead
the function { 'value': 12.3 },
while a null entry would be { 'value': () }.
Consider a JSON document of the form:
The following code processes this map to produce an XML representation of the same information. The cities are sorted by name:
In this example the map is decomposed to a sequence of key-value pairs, each represented as
a map with two entries, "key" and "value", which can be accessed using
the lookup expressions ?key and ?value.
separator attributeIf the separator attribute is present, then its
For example, the following instruction:
produces a sequence comprising, in order: the integer 3, the integer 4, a text node with string value "|",
the integer 6, the integer 7, another text node with string value "|",
the integer 9, and the integer 10.
The node identity of any text nodes that are inserted is
If the separator is a zero-length string, then a zero-length text node is inserted into the sequence. (If the
sequence is used for constructing the value of a node, then zero-length text nodes will be discarded: see
xsl:iterate InstructionThe xsl:iterate instruction processes the items in a sequence
in order; unlike xsl:for-each, the result of processing one item can affect the way that
subsequent items are processed.
xsl:iterateConsider the following JSON document representing transactions in a bank account:
The following code converts this to an XML representation that includes a running balance:
Using array:members() in this way makes it possible to process any array, including one whose members
are arbitrary sequences rather than single items. In this particular case, if it is known that the JSON array
will not contain any null entries, or if any null entries are to be ignored,
it becomes possible to simplify the code as follows:
The select attribute contains an
The select expression in turn; the
If
The select
attribute or a non-empty contained select expression if present or the contained sequence constructor
otherwise; if neither is present, the value is the empty sequence.
The select attribute is the empty sequence.
The effect of
The instructions
J is the last instruction in SC, ignoring any
J is in a
J is in a
J is in a
J is in a
It is a
It is a select attribute of
It is a name attribute of an name attribute of an
Parameter names in
The result of the
Any select expression of the
On the first iteration a parameter always takes its initial value (which may depend on variables or other aspects of the dynamic context). Subsequently:
If an
If an
If neither an
The
The select expression or contained sequence
constructor is evaluated using the same context item, position, and size as the
If neither an
The optional select expression or sequence constructor
the context item, position, and size are
If the input sequence is empty, then the result of the
select attribute or
Conceptually,
One of the motivations for introducing the
There are several instructions in XSLT that support conditional processing:
XSLT 3.0 also supports
XSLT offers a number of ways of expressing conditional logic.
XSLT 1.0 offered the
XSLT 2.0 added the XPath conditional expression providing two-way branches for use at a finer-grained level where
<xsl:value-of select="if ($x) then 'red' else 'green'/> to be reduced from eight lines of code to one.
XSLT 4.0 introduces the then and else attributes for <xsl:if test="empty($seq)" then="1" else="head($seq) * my:f(tail($seq))"/>.
The select attribute of
The
then and else
attributes.
The test attribute,
whose value is an
If the then attribute, then it
then attribute and the
contained sequence constructor are mutually exclusive.
The result of the test attribute. The rules for determining the effective boolean
value of an expression are given in
If the effective boolean value of the true, then:
If there is a then attribute, the expression in the then
attribute is evaluated, and the resulting value is returned as the result of the
If there is a non-empty sequence constructor, it is evaluated and the
resulting value is returned as the result of the
Otherwise, the result of the
If the effective boolean value of the test false, then:
If there is an else attribute, the expression in the else
attribute is evaluated, and the resulting value is returned as the result of the
Otherwise, the result of the
If the test expression has no effective boolean value (for example,
if it is a sequence of several integers, or a map), then a
The semantics of the <xsl:if test="C" then="X" else="Y"/>
can equivalently be written <xsl:sequence select="if (C) then X else Y"/>. The same
effect can also be achieved by writing
<xsl:choose><xsl:when test="C" select="X"/><xsl:otherwise select="Y"/></xsl:choose>.
The choice of which of these constructs to use is a largely matter of personal style.
In the following example, the names in a group of names are formatted as a comma separated list:
This adds a comma after every item except the last. This can also be expressed as:
which inserts a comma before every item except the first. (This formulation might be more efficient, since determining whether an item is the last may involve look-ahead.)
The following example shows the use of
xsl:otherwise elements can take a select attribute
in place of a sequence constructor.
The test, which
specifies an
The effective value of an select attribute or a contained
select attribute is present then the
sequence constructor must be empty, and if the sequence constructor is non-empty
then the select attribute must be absent
select
attribute is absent and the sequence constructor is empty, then the
effective value is the empty sequence.
When an
An test attribute is
true. The rules for determining the effective boolean value of an
expression are given in
The select attribute or contained
select expressions and sequence constructors of
test
expressions for
The following example enumerates items in an ordered list using arabic numerals, letters, or roman numerals depending on the depth to which the ordered lists are nested.
select attribute of The following example is equivalent to the one above:
The select attribute of the test attributes of the
The content of the test, which
contains an
The result of an select attribute or a contained
select attribute is present then the
sequence constructor must be empty, and if the sequence constructor is non-empty
then the select attribute must be absent. If the select
attribute is absent and the sequence constructor is empty, then the
result is the empty sequence.
Any
An
The select expression of the
The result of the evaluation is converted to a single atomic item
by applying the
Each of the
An test
expression and converting the result to a sequence of atomic items
by applying the selector value. The
comparison is performed using the rules of the XPath = operator,
using the default collation that is in scope for the
An true.
The first, and only the first, select attribute or contained
The select expressions and sequence constructors of
test
expressions for
There is no requirement that the values of select expressions
should be literals, nor that the values should be distinct.
The following example shows a simple function to convert a month number to a month name:
This function returns the number of days in a month, returning the empty sequence if the supplied month is invalid.
err:stack-trace, err:additional,
and err:map are available within an The
Because a sequence constructor may contain an
An select attribute, or its contained
If the select attribute, then it
select attribute and the
contained sequence constructor are mutually exclusive. If neither is present, the
result of the
The rollback-output attribute is described in
yes.
It is a select attribute of the
Any
The errors attribute,
which lists the error conditions that the errors="*", which catches
all errors. The value is a whitespace-separated list of NameTest that matches
the error code associated with that error condition.
Error codes are QNames. Those defined in this specification and in related
specifications are all in the <xsl:catch
errors="err:FODC0001 err:FODC0005"> where the namespace prefix
err is bound to this namespace. Errors defined by implementers,
and errors raised by an explicit call of the
If more than one
An select
attribute, or a contained
It is a select attribute of the
The result of evaluating the select attribute or the result of
evaluating the contained sequence constructor; if neither is present, the result is
the empty sequence. This result is delivered as the result of the
If a dynamic error occurs during the evaluation of
Within the select expression, or within the sequence constructor
contained by the
| Variable | Type | Value |
|---|---|---|
| err:code | xs:QName | The error code |
| err:description | xs:string? | A description of the error condition; the empty sequence if no description is available (for example, if
the |
| err:value | item()* | Value associated with the error. For an error raised by
calling the terminate="yes", or a failing |
| err:module | xs:string? | The URI (or system ID) of the stylesheet module containing the instruction where the error occurred; the empty sequence if the information is not available. |
| err:line-number | xs:integer? | The line number within the stylesheet module of the
instruction where the error occurred; the empty sequence if the information
is not available. The value |
| err:column-number | xs:integer? | The column number within the stylesheet module of the
instruction where the error occurred; the empty sequence if the information
is not available. The value |
| err:stack-trace | xs:string? | An |
| err:additional | item()* | Additional |
| err:map | map(xs:string, item()*) | A map with entries that are bound to the variables above. The local names of the variables are assigned as keys. No map entries are created for those values that are empty sequences. The variable can be used to pass on all error information to another function. |
Variables declared within the sequence constructor of the
Within an error($err:code, $err:description, $err:value).
The following additional rules apply to the catching of errors:
All dynamic errors occurring during the evaluation of the
select
expression are caught (provided they match one of the
This includes errors occurring in functions or templates invoked in
the course of this evaluation, unless already caught by a nested
It also includes (for
example) errors caused by calling the
terminate="yes", or the
xs:error constructor
function.
It does not include errors that occur while evaluating references to
variables whose declaration and initialization is outside the
The existence of an
Some fatal errors arising in the processing environment, such as running out of
memory, may cause termination of the transformation despite the presence of an
If the sequence constructor or select expression of the
A serialization error that occurs during the serialization of
a
A validation error is treated as occurring in the instruction
that requested validation. For example, if the stylesheet is producing XHTML
output and requests validation of the entire result document by means of the
attribute validation="strict" on the instruction that creates the
outermost html element, then a validation failure can be caught
only at that level. Although the validation error might be detected, for
example, while writing a p element at a location where no
p element is allowed, it is not treated as an error in the
instruction that writes the p element and cannot be caught at that
level.
A type error may be caught if the processor raises it dynamically; this does not affect the processor’s right to raise the error statically if it chooses.
The following rules are provided to define which expression is considered to fail when a type error occurs, and therefore where the error can be caught. The general principle is that where the semantics of a construct C place requirements on the type of some subexpression, a type error is an error in the evaluation of C, not in the evaluation of the subexpression.
For example, consider the following construct:
The expected type of the result of the sequence constructor is
xs:integer; if the value of variable $foo turns
out to be a string, then a type error will occur. It is not possible to catch
this by writing:
This fails to catch the error because the
A similar rule applies to functions: if the body of a function computes a result which does not conform to the required type of the function result, it is not possible to catch this error within the function body itself; it can only be caught by the caller of the function. Similarly, if an expression used to compute an argument to a function returns a value of the wrong type for the function signature, this is not considered an error in this expression, but an error in evaluating the function call as a whole.
A consequence of these rules is that when a type error occurs while initializing a global variable (because the initializer returns a value of the wrong type, given the declared type of the variable), then this error cannot be caught.
Because processors are permitted to raise type errors during static
analysis, it is unwise to attempt to recover from type errors dynamically.
The best strategy is generally to prevent their occurrence. For example,
rather than writing $p + 1 where $p is a parameter
of unknown type, and then catching the type error that occurs if
$p is not numeric, it is better first to test whether
$p is numeric, perhaps by means of an expression such as
$p instance of my:numeric, where my:numeric is
a union type with xs:double, xs:float, and
xs:decimal as its member types.
The fact that the application tries to catch errors does not prevent the
processor from organizing the evaluation in such a way as to prevent errors
occurring. For example exists(//a[10 div . gt 5]) may still do an
“early exit”, rather than examining every item in the sequence just to see if
it triggers a divide-by-zero error.
Except as specified above, the optimizer must not rearrange the evaluation (at compile time or at run time) so that expressions written to be subject to the try/catch are evaluated outside its scope, or expressions written to be external to the try/catch are evaluated within its scope. This does not prevent expressions being rearranged, but any expression that is so rearranged must carry its try/catch context with it.
The XSLT language is designed so that a processor that chooses to execute instructions in document order will always append nodes to the result tree in document order, and never needs to update a result tree in situ. As a result, it is normal practice for XSLT processors to stream the result tree directly to its final destination (for example, a serializer) without ever holding the tree in memory. This applies whether or not the processor is streamable, and whether or not source documents are streamed.
The language specification states (see
The situation becomes more complicated when dynamic errors occur while writing to
a result tree, and the dynamic error is caught by an
Both these strategies are potentially expensive, and both have an adverse effect
on streaming, in that they affect the amount of memory needed to transform large
amounts of data. XSLT 3.0 therefore provides an option to relax the requirement to
recover result trees when failures occur in the course of evaluating an
rollback-output="no" on the
The default value of the attribute is rollback-output="yes".
The effect of specifying rollback-output="no" on
It is a rollback-output="no".
For example, consider the following:
The most likely failure to occur here is a failure to read the streamed input file
in.xml. In the common case where this failure is detected
immediately, for example if the file does not exist or the network connection is
down, no output will have been written to the result document, and the attempt to
catch the error is likely to be successful. If however a failure is detected after
several megabytes of data have been copied to out.xml, for example an
XML well-formedness error in the input file, or a network failure that occurs
while reading the file, recovery of the output file may be impossible. In this
situation the out.xml will be unpredictable.
Note that adding an
When rollback-output="no" is specified, it is still possible to
ensure recovery of errors happens predictably by evaluating the
potentially failing code in
An application might wish to ensure that when a fatal error occurs while
reading an input stream, data written to persistent storage up to the point of
failure is available after the transformation terminates. Setting
rollback-output="no" does not guarantee this, but a processor
might choose to interpret this as the intent.
Changing the attribute to rollback-output="yes" makes the stylesheet
more robust and able to handle error conditions predictably, but the cost may be
substantial; for example it may be necessary to buffer the whole of the result
document in memory.
The following example divides an employee’s salary by the number of years they have served, catching the divide-by-zero error if the latter is zero.
The following example generates a result tree and performs schema validation, outputting a warning message and serializing the invalid tree if validation fails.
The reason that the result tree is constructed in a variable in this example is
so that the unvalidated tree is available to be used within the
The facilities described in this section are designed to make it easier to generate result trees conditionally depending on what is found in the input, without violating the rules for streamability. Although these facilities were introduced to the language specifically to make streaming easier, they are available whether or not streaming is in use, and users have often found them convenient in non-streaming applications.
The facilities are introduced first by example:
The following example generates an events element if and only if
there are one or more event elements. The code could be written like
this:
However, the above code would not be event elements more than once. To make
it streamable, it can be rewritten as:
The effect of the events element if it would have no
children. A streaming implementation will typically hold the start tag of the
events element in a buffer, to be sent to the output destination
only if and when a child node is generated.
The following example generates an h3 element and a summary paragraph
only if a list of items is non-empty. The code could be written like this:
However, the above code would not be item-for-sale elements more than once.
To make it streamable, it can be rewritten as:
The effect of the
The following example generates a summary paragraph only if a list of items is empty. The code could be written like this:
However, the above code would not be item-for-sale elements more than once
(the fact that the list is empty is irrelevant, because streamability is
determined statically). To make the code streamable, it can be rewritten as:
The effect of the
For further examples showing the use of these instructions when streaming,
see
xsl:where-populated instructionThe
The sequence constructor is evaluated in the usual way (taking into account
any
The result of the instruction is the value of the expression
$R[not(deemed-empty(.))] where the function
deemed-empty($item as item()) returns true if and only if
$item is one of the following:
A document or element node that has no children.
If an element has attributes or namespaces, these do not prevent the element being deemed empty.
If a document or element node has children, the node is not deemed
empty, even if the children are empty. For example, a document node
created using an <xsl:variable name="temp"><a/></xsl:variable>
is not deemed empty, even though the contained <a/>
element is empty.
A node, other than a document or element node, whose string value is zero-length.
A whitespace-only text node is not deemed empty.
An atomic item such that the result of casting the atomic item to a string is zero-length.
This can happen only when the atomic item is of type
xs:string, xs:anyURI,
xs:untypedAtomic, xs:hexBinary, or
xs:base64Binary.
A map whose size (number of key/value pairs) is zero.
An array (see
The following example generates an HTML unnumbered list, if and only if the
list is non-empty. Note that the presence of the class attribute
does not make the list non-empty. The code is written to be streamable.
xsl:on-empty instructionThe select attribute and the contained sequence
constructor are mutually exclusive
When an
It must be the only
It must not be followed in the sequence constructor by any other
xs:string, produces a zero-length string; or
An
If an
This means that the (vacuous) results produced by other instructions in the sequence constructor are discarded. This is relevant mainly when the result of the sequence constructor is used for something other than constructing a node: for example if it forms the result of a function, or the value of a variable, and the function or variable specifies a required type.
When streaming, it may be necessary to buffer vacuous items in the result sequence until it is known whether the result will contain items that are non-vacuous. In many common situations, however — in particular, when the sequence constructor is being used to create the content of a node — vacuous items can be discarded immediately because they do not affect the content of the node being constructed.
In nearly all cases, the rules for
There is one minor exception to this rule: if the sequence constructor delivers multiple zero-length strings,
then in the absence of the
Attribute and namespace nodes created by the sequence constructor
are significant; the
Where the sequence constructor is a child of an instruction with
an [xsl:]use-attribute-sets attribute, any attribute nodes created by expanding the referenced
attribute set(s) are not part of the result of the sequence constructor and therefore play no role in determining
whether an
If
If
The select attribute and the contained sequence
constructor are mutually exclusive
An
The
Unlike
The name attribute, which specifies the name of the variable. The value of
the name attribute is an
The as attribute,
which specifies the as attribute is a
select attribute or the contained select attribute, then
the sequence constructor
If the as attribute is specified, then the
It is a
If the as attribute is omitted, the
For the effect of the static attribute, see
The visibility attribute
If the visibility attribute is present with the value
abstract then the select attribute
The
As a child of
As a child of
As a child of
As a child of
The attributes applicable to
| Parent Element | name | select | as | required | tunnel | static |
|---|---|---|---|---|---|---|
| mandatory | optional | optional | yes| | yes| | ||
| mandatory | optional | optional | yes| | yes| | ||
| mandatory | optional | optional | yes| | yes| | ||
| mandatory | optional | optional | ||||
| mandatory | mandatory | optional |
In the table, the entries for the name,
select, and as attributes indicate whether the attribute
must appear, is optional, or must be absent; the entries for the
required, tunnel, and static attributes
indicate the values that are permitted if the attribute is present, with the default
value shown in bold. (The value yes can also be written
true or 1, while no can also be written
false or 0.)
The name attribute is mandatory: it specifies the name of the parameter.
The value of the name attribute is an
It is a name attribute of two sibling
If the select attribute, then
the sequence constructor
The static attribute can take the value yes only on
Local variables may
The optional tunnel attribute may be used to indicate that a parameter
is a no; the value yes may be specified only for
The as attribute,
which specifies the as attribute is a
as attribute is omitted, then the
required type is item()*.
The
The
It is a
For example, the following declares a parameter that requires the supplied
value (after atomization) to be either a QName, or the string "*",
or the empty sequence:
The optional required attribute of
yes (these are always mandatory), and the only valueno (these are always
initialized to a default value).
The default value for a required="yes"; in all
other cases it is required="no".
required attributerequired attribute is present and has the value
yes.select attribute.
The static context for evaluating the default value depends on where the
relevant expression appears in the stylesheet, in the usual way. Note however that
for
The dynamic context is different for different kinds of parameter:
For
For
For <xsl:param name="dot" required="no" select="."/> to take its
default value from the context item of the caller.
If a parameter is not select
attribute or the contained
This specification does not dictate whether and when the default value of a
parameter is evaluated. For example, if the default is specified as
<xsl:param name="p"><foo/></xsl:param>, then
it is not specified whether a distinct foo element node will be
created on each invocation of the template, or whether the same
foo element node will be used for each invocation. However, it
is permissible for the default value to depend on the values of other
parameters, or on the evaluation context, in which case the default must
effectively be evaluated on each invocation.
select attribute or a non-empty sequence
constructor.
as attribute, or a zero-length string if not.
as
attribute which does not permit the empty sequence), then the parameter is
The effect of these rules is that specifying <xsl:param name="p"
as="xs:date" select="2"/> is an error, but if the default value of
the parameter is never used, then the processor has discretion whether or not
to raise the error. By contrast, <xsl:param name="p"
as="xs:date"/> is treated as if required="yes" had
been specified: the empty sequence is not a valid instance of
xs:date, so in effect there is no default value and the
parameter is therefore treated as being mandatory.
Various errors can arise with regard to mandatory parameters when no value is
supplied. In the rules below, tunnel attribute with the value yes.
It is a static error if a parameter to
It is a name attribute equals T and
that has no non-tunnel name attribute equals P. (All names are
compared as QNames.)
It is a
This includes the following cases:
The template is invoked using name and
tunnel attributes match the corresponding attributes
of the mandatory parameter.
The mandatory parameter is a tunnel parameter, and the template is
invoked using name and
tunnel attributes match the corresponding attributes
of the mandatory parameter.
The template is invoked as the entry point to the transformation,
either by invoking an initial mode (
as or select attribute no longer
attempts to create an implicit document node if the sequence constructor contains
certain instructions (such as A
If the select attribute, then the value of the
attribute
If the select
attribute nor an as attribute, then the
is equivalent to
If a
The element has no select attribute
The element has no as attribute
The element has non-empty content (that is, the variable-binding element has one or more child nodes)
There is no
then the content of the variable-binding
element specifies the
Otherwise, the
These combinations are summarized in the table below.
| select attribute | as attribute | content | Effect |
|---|---|---|---|
| present | absent | empty | Value is obtained by evaluating the select
attribute |
| present | present | empty | Value is obtained by evaluating the select
attribute, coerced to the type required by the as
attribute |
| present | absent | present | Static error |
| present | present | present | Static error |
| absent | absent | empty | Value is a zero-length string |
| absent | present | empty | Value is the empty sequence, provided the as
attribute permits the empty sequence |
| absent | absent | includes a | Value is obtained by evaluating the sequence constructor |
| absent | absent | present and does not include a | Value is a document node whose content is obtained by evaluating the sequence constructor |
| absent | present | present | Value is obtained by evaluating the sequence constructor,
coerced to the type required by the as attribute |
It is a select attribute and has non-empty content.
The value of the following variable is the sequence of integers (1, 2, 3):
The value of the following variable is an integer, assuming that the attribute
@size exists, and is annotated either as an integer, or as
xs:untypedAtomic:
The value of the following variable is a zero-length string:
The value of the following variable is a document node containing an empty element as a child:
The value of the following variable is a sequence of integers (2, 4, 6):
The value of the following variable is a sequence of parentless attribute nodes:
The value of the following variable is the empty sequence:
The actual value of the variable depends on the as attribute.
When a variable is used to select nodes by position, be careful not to do:
This will output the values of all the td elements, space-separated
(or with td
element), because the variable n will be bound to a node, not a
number. Instead, do one of the following:
or
or
A document node is created implicitly when evaluating an
as attribute, unless the children of this element include
a
Most of the disqualifying elements return maps or arrays, and wrapping a map or array
in a document node makes no sense. For select
attribute on the containing
The construct:
can be regarded as a shorthand for:
The base URI of the document node is taken from the base URI of the variable binding
element in the stylesheet. (See
No document-level validation takes place (which means, for example, that there is no
checking that ID values are unique). However,
The base URI of other nodes in the tree is determined by the rules for
constructing complex content (see xml:base attribute within the temporary tree will change the base
URI for its parent element and that element’s descendants, just as it would
within a document constructed by parsing.
The document-uri and unparsed-entities properties of the
new document node are set to empty.
A
The following stylesheet uses a temporary tree as the intermediate
result of a two-phase transformation, using different phase1.xsl will be declared with
mode="phase1", while those in module phase2.xsl will
be declared with mode="phase2":
The algorithm for matching nodes against template rules is exactly the same
regardless which tree the nodes come from. If different template rules are to be
used when processing different trees, then unless nodes from different trees can
be distinguished by means of
Both
It is an error if no value is supplied for a mandatory stylesheet parameter
If a
It is a
For a global variable or the default value of a stylesheet parameter, the
If the declaration appears within the
If the declaration appears within a
An XPath error will be raised if the evaluation of a global variable or parameter
references the context item, context position, or context size when the
The private.
This rule has the effect that the names of
For the effect of the static attribute, see
The visibility attribute
If the visibility attribute is present with the value
abstract then the select attribute
The following example declares a global parameter para-font-size,
which is referenced in an
The implementation must provide a mechanism allowing the user to supply a value
for the parameter para-font-size when invoking the stylesheet; the
value 12pt acts as a default.
In XSLT 4.0, a global variable is in scope within its own definition. Trivial
self-references such as <xsl:variable name="x" select="$x+1"/> are
prevented by the general rules on circularities: see
Static variables and parameters are global variables and can be used in the same way
as other global variables. In addition, they can be used in
[xsl:]use-when expressions and in shadow attributes.
static="yes" declares a
The static attribute yes on an
When the static attribute is present with the value
yes, the visibility attribute private.
This rule prevents static variables being overridden in another package. Since the
values of such variables may be used at compile time (for example, during
processing of [xsl:]use-when expressions), the rule is necessary to
ensure that packages can be independently compiled.
It is possible to make the value of a static variable or parameter available in a using package by binding a non-static public variable to its value, for example:
When the attribute static="yes" is specified, the
select attribute must be present to
define the value of the variable
If the select attribute is present, then it is evaluated using the rules
for
The rules for the scope of static variables, and the
handling of duplicate declarations, are similar to the rules for non-static
variables, but with additional constraints designed to disallow forwards references.
The reason for disallowing forwards references is to ensure that
use-when attributes can always be evaluated as early as possible, and
in particular to ensure that the value of a use-when attribute never has
circular dependencies. The additional constraints are as follows:
The static context for evaluation of a
If two static variables declared within the same package have the same name,
the one that has higher
This rule ensures that when a static variable reference is encountered, the value of the most recently declared static variable with that name can be used, knowing that this value cannot be overridden by a subsequent declaration having higher import precedence.
It is a static="yes" is inconsistent with
another static variable of the same name that is declared earlier in
stylesheet tree order and that has lower
It is not an error to have two global variables or parameters with the same name, one static and one non-static, provided that they have different import precedence. If the static variable has higher precedence, then it will be used as the selected binding for all global variable references with this name, whether or not they appear in static expressions. If the non-static variable has higher precedence, then the static variable will be used as the selected binding for variable references appearing in static expressions, while the non-static variable will be used for variable references in non-static expressions. The two variables may have different values. In the case of global parameters, however, a transformation API may restrict them to have the same value.
If the two variable declarations have the same import precedence, and there is
no declaration with higher import precedence, then error condition
Static expressions appear in a number of contexts, in particular:
In [xsl:]use-when attributes (see
In the select attribute of static="yes");
In shadow attributes (see
There are no syntactic constraints on the XPath expression that can be used as a
Specifically, the components of the static and dynamic context are defined by the following two tables:
| Component | Value |
|---|---|
| XPath 1.0 compatibility mode | false |
| Statically known namespaces | the
|
| Default namespace for elements and types | determined by the xpath-default-namespace attribute if present
(see |
| Default function namespace | the |
| In-scope schema types | The type definitions that would be available in the absence of any
|
| In-scope element declarations | None |
| In-scope attribute declarations | None |
| In-scope variables | The |
| Context item static type | |
| In-scope named item types | None |
| Statically known function definitions | The functions defined in fn
math, map, and arraythe functions
functions that appear in both this specification and in constructor functions for built-in types; the set of extension functions that are present in the static context of every XPath expression (other than a static expression) within the content of the element that contains the static expression. false in
respect of such functions, and true in respect of
functions that can be called within the static expression. It also has the
effect that these extension functions will be recognized within the static
expression itself; however, the fact that a function is available in this
sense gives no guarantee that a call on the function will succeed. |
| Statically known collations | Implementation-defined |
| Default collation | The Unicode Codepoint Collation |
| Static Base URI | The base URI of the containing element in the stylesheet document (see |
| Statically known documents | Implementation-defined |
| Statically known collections | Implementation-defined |
| Statically known default collection type | Implementation-defined |
| Statically known decimal formats | A single unnamed |
| Component | Value |
|---|---|
| Context item, position, and size | |
| Variable values | A value for every variable present in the in-scope variables. For |
| Dynamically known function definitions | The same as the statically known function definitions |
| Current dateTime | Implementation-defined |
| Implicit timezone | Implementation-defined |
| Executable Base URI | The same as the Static Base URI |
| Default collation | The Unicode Codepoint Collation |
| Default language | Implementation-defined |
| Default calendar | Implementation-defined |
| Default place | Implementation-defined |
| Available documents | Implementation-defined |
| Available text resources | Implementation-defined |
| Available collections | Implementation-defined |
| Default collection | Implementation-defined |
| Available URI collections | Implementation-defined |
| Default URI collection | Implementation-defined |
| Environment variables | Implementation-defined |
Within a [xsl:]use-when expressions within the
same stylesheet module, but will not necessarily return the same result as the same
call in an [xsl:]use-when expression within a different stylesheet
module, or as a call on the same function executed during the transformation
proper.
If a
An
An
The result of evaluating a local
For any
A global
A local
It is not visible in any region where it is
It is not visible within the subtree rooted at an
It is not visible within the subtree rooted at an
Within an
The binding is not visible for the
If a binding is visible for an element then it is visible for every attribute of that element and for every text node child of that element.
An tunnel="yes"
is also visible in the test attribute of the containing
A binding
The following is allowed:
It is also not an error if a binding established by a local
The following is not an error, but the effect is probably not what was intended.
The template outputs <x value="1"/>, because the declaration of
the inner variable named $x has no effect on the value of the outer
variable named $x.
Once a variable has been given a value, the value cannot subsequently be changed. XSLT does not provide an equivalent to the assignment operator available in many procedural programming languages.
This is because an assignment operator would make it harder to create an implementation that processes a document other than in a batch-like way, starting at the beginning and continuing through to the end.
As well as global variables and local variables, an XPath
Where a reference to a variable occurs in an XPath expression, it is resolved first by reference to range variables that are in scope, then by reference to local variables and parameters, and finally by reference to global variables and parameters. A range variable may shadow a local variable or a global variable. XPath also allows a range variable to shadow another range variable.
Parameters are passed to templates using the name attribute specifies the name of the name attribute is
an
The
passing parameters to an iteration of the
passing parameters to a dynamic invocation of an XPath expression using
supplying the values of
In consequence,
It is a name attributes that represent the same
The value of the parameter is specified in the same way as for
select
and as attributes and the content of the
It is possible to have an as attribute on the
as
attribute on the corresponding
In this situation, the supplied value of the parameter will first be processed
according to the rules of the as attribute on the
as attribute on the
For example, suppose the supplied value is a node with xs:untypedAtomic, and the as="xs:integer", while the as="xs:double". Then the node will first be
atomized and the resulting untyped atomic item will be cast to
xs:integer. If this succeeds, the xs:integer will
then be promoted to an xs:double.
The
The optional tunnel attribute may be used to indicate that a parameter
is a no. Tunnel parameters are described in tunnel attribute no.
In other cases it is a required="yes" and no value for this parameter is supplied by the
calling instruction.
The following two declarations create a circularity:
The definition of a global variable can be circular even if no other variable is
involved. For example the following two declarations (see
The definition of a variable is also circular if the evaluation of the variable
invokes an match attribute of any template
rule in the
Similarly, a variable definition is circular if it causes a call on the
match or
use attributes. So the following definition is circular:
An attribute set is circular if its use-attribute-sets attribute
references itself, directly or indirectly. So the following definitions establish
a circularity:
Because attribute sets can invoke functions, global variables, or templates, and can also include instructions such as literal result elements that themselves invoke attribute sets, examples of circularity involving attribute sets can be more complex than this simple example illustrates. It is also possible to construct examples in which self-reference among attribute sets could be regarded as (terminating or non-terminating) recursion. However, because such self-references have no practical utility, any requirement to evaluate an attribute set in the course of its own evaluation is considered an error.
In previous versions of this specification, self-reference among attribute sets was defined as a static error. In XSLT 3.0 it is not always detectable statically, because attribute sets can bind to each other across package boundaries. Nevertheless, in cases where a processor can detect a static circularity, it can raise this error during the analysis phase, under the general provision for raising dynamic errors during stylesheet analysis if execution can never succeed.
In general, a
For example, in the following declarations, the function declares a local variable
$b, but it returns a result that does not require the variable to be
evaluated. It is
Although a circularity is detected as a dynamic error,
there is no unique instruction whose evaluation triggers the error condition, and the
result of any attempt to catch the error using an
Circularities usually involve global variables or parameters, but they can also exist
between
Circularity is not the same as recursion. Stylesheet functions (see
Recursive functions can also be defined using global variable declarations. For example, the variable
declaration <xsl:variable name="f" select="fn($n){if ($n=0) then 0 else $f($n - 1)}"/> does
not constitute a circularity, because the variable can be evaluated (delivering a function) without knowing its
own value.
The requirement to report a circularity as a dynamic error
overrides the rule that dynamic errors in evaluating
This section describes three constructs that can be used to provide subroutine-like
functionality that can be invoked from anywhere in the stylesheet: named templates (see
[xsl:]use-attribute-sets
attribute. These all have the characteristic that they can cause evaluation of
constructs that are not lexically contained within the calling
construct.
name attribute
defines a name attribute is an name attribute, it may, but need not, also have a match
attribute.
The match, mode and priority attributes on an
name
and visibility attributes on an
It is a
The template name xsl:initial-template is specially
recognized in that it provides a default entry point for stylesheet execution (see
An name attribute that identifies the template to be invoked. Unlike
It is a name
attribute does not match the name attribute of any hidden). For more details of the process of binding the
called template, see
The target name attribute matches the name
attribute of the private or final) it may be
an overriding template in a package that uses the containing package.
The result of evaluating an
Parameters for a named template can be supplied using
As an alternative to the use of
a call on the template written as:
can be replaced with the instruction:
For this to work, the name of the template must be in a non-null namespace, and
this namespace must be designated as an extension element namespace using the
attribute [xsl:]extension-element-prefixes on the instruction itself,
or on some containing element (see
The name of the instruction must match the name of the called template, and the
names of its attributes (other than xsl:default-collation affects the evaluation of any XPath expression
used to compute a parameter value.
The way in which attribute values are handled depends on the type declaration of the template parameter:
If the declared type is xs:boolean, with no occurrence indicator,
then the attribute is treated
as an yes, true, or 1,
or no, false, or 0, in the same way as boolean
attributes on XSLT instructions.
If the declared type is any other atomic or union type, with no occurrence indicator,
then the attribute is treated as an xs:untypedAtomic item,
which forces conversion to the required type by applying the casting rules.
In all other cases (that is, if the type of the parameter is not declared,
or if it is not atomic, or if there is an occurrence
indicator) the attribute is treated as an XPath expression and its value is converted
to the required type using the
If an instruction is recognized as an implicit call on a named template, then the static
and dynamic rules that apply are the same as if it were expanded into an
is essentially equivalent to:
except that the interpretation of the parameter values E1, E2, and E3
depends on the declared type as explained above.
Some of the implications of this equivalence are:
The binding of the instruction to a specific named template (for example, if there
are overriding declarations in multiple packages) follows the binding rules in
A value must be supplied for any parameter declared with required="yes".
The context item for the evaluation of the extension instruction must satisfy any constraints
defined in an
It is an error if the instruction has attributes that do not correspond to the names of parameters declared on the named template.
It is not possible to supply values for
For backwards compatibility, if an external implementation of an extension instruction is available to the implementation, then that takes precedence over the existence of a named template with a matching name.
The XSLT namespace cannot be designated as an extension element namespace, so the template
names xsl:initial-template and xsl:original cannot be used as
extension instructions.
The
The context item for a template must be either a single item, or absent. It cannot be an arbitrary value.
If the as attribute is present then its value must be an as="item()".
It is a as attribute is
present use="absent" is specified.
A
If an
The use attribute of
required,
optional, or absent.
The default is
optional.
If the containing name
attribute then the only permitted value is required.
If the value required is specified, then there must be a
context item. (This will automatically be the case if the template is
invoked using
If the value optional is specified, or if the attribute is
omitted, or if the
If the value absent is specified, then the contained sequence
constructor, and any
It is not an error to call such a template with a non-absent focus; the
context item is simply treated as absent. This option is useful when
streaming, since an
The processor match pattern,
that is, if no item that satisfies the match pattern can also satisfy the required
context item type.
The
It is a
Parameters are passed to named templates using the
In the case of
The optional tunnel attribute may be used to indicate that a
parameter is a no. Tunnel parameters are described in
This example defines a named template for a numbered-block with a
parameter to control the format of the number.
Tunnel parameters are conceptually similar to the dynamically scoped variables found in some functional programming languages (for example, early versions of LISP), where evaluating a variable reference involves searching down the dynamic call stack for a matching variable name. There are two main use cases for the feature:
They provide a way to supply context information that might be needed by many
templates (for example, the fact that the output is to be localized for a particular language),
but which cannot be placed in a global variable because it might vary from one phase of processing
to another. Passing such information using conventional parameters is error-prone, because
a single
This style of processing is even more useful when handling JSON input, because with maps and arrays, there is no ancestor axis to examine properties of nodes further up the tree; with a recursive descent of the tree, all context information needs to be passed down explicitly. One way of handling this is for each level of processing in the tree to bind a tunnel parameter to the map or array encountered at that level, which then becomes available to all template rules processing data further down the tree.
They are particularly useful when writing a customization layer for an existing stylesheet. For example, if you want to override a template rule that displays chemical formulae, you might want the new rule to be parameterized so you can apply the house-style of a particular scientific journal. Tunnel parameters allow you to pass this information to the overriding template rule without requiring modifications to all the intermediate template rules. Again, a global variable could be used, but only if the same house-style is to be used for all chemical formulae processed during a single transformation.
A tunnel="yes". A template that requires access to the value of a
tunnel parameter must declare it using an tunnel="yes".
On any template call using an <xsl:with-param tunnel="yes">,
overlaid on a base set of tunnel parameters. If the
<xsl:with-param tunnel="yes"> has the same
When a template specifies <xsl:param tunnel="yes">,
this declares the intention to make use of a
Two sibling
All other options of
If a tunnel parameter is declared in an
tunnel="yes", and if the
parameter is
Suppose that the equations in a scientific paper are to be sequentially numbered, but that the format of the number depends on the context in which the equations appear. It is possible to reflect this using a rule of the form:
At any level of processing above this level, it is possible to determine how the equations will be numbered, for example:
The parameter value is passed transparently through all the intermediate layers
of template rules until it reaches the rule with match="equation".
The effect is similar to using a global variable, except that the parameter can
take different values during different phases of the transformation.
Attribute sets generate named collections of attributes that can be used repeatedly on
different constructed elements. The name attribute specifies the name of the attribute set. The value of the
name attribute is an EQName, which is expanded as
described in
The content of the
The effect of the streamable attribute is explained in
use-attribute-sets attribute on the xsl:use-attribute-sets attribute on a literal result element. An
attribute set may be defined in terms of other attribute sets by using the
use-attribute-sets attribute on the
[xsl:]use-attribute-sets attribute is in each case a
whitespace-separated list of names of attribute sets. Each name is specified as an
It is a use-attribute-sets attribute of an
xsl:use-attribute-sets attribute of a name attribute of any
An
The relevant attribute set
Each declaration is expanded to a sequence of instructions as follows.
First, one use-attribute-sets attribute, if
present, retaining the order in which the EQNames appear. This is followed
by the sequence of contained
[xsl:]use-attribute-sets attribute; the effect of the
pseudo-instruction is to cause the referenced
Similarly, an [xsl:]use-attribute-sets
attribute of an
An
The following two (mutually recursive) rules define how
an [xsl:]use-attribute-set attribute is expanded:
An
An
For rules regarding cycles in attribute set
declarations, see
The effect of an
In all cases the result of evaluating an
The visibility attribute determines the
visibility of the attribute set in packages other than the containing
package. If the visibility attribute is present on any of the
If the visibility attribute is present with the
value abstract then there must be no use-attribute-sets
attribute.
Attribute sets are evaluated as follows:
The use-attribute-sets attribute. The sequence of attribute
nodes produced by evaluating this attribute is prepended to the sequence
produced by evaluating the
xsl:use-attribute-sets attribute, which is evaluated
in the same way as the use-attribute-sets attribute of
The [xsl:]use-attribute-sets attribute forming
the initial input to the algorithm. However, the static context for the evaluation
depends on the position of the
The above rule means that for an select attribute, the focus for evaluating any referenced attribute
sets is the node selected by the select attribute, rather than the context item of
the
The set of attribute nodes produced by expanding
xsl:use-attribute-sets may include several attributes with the
same name. When the attributes are added to an element node, only the last of the
duplicates will take effect.
The way in which each instruction uses the results of expanding the
[xsl:]use-attribute-sets attribute is described in the
specification for the relevant instruction: see
The result of evaluating an attribute set is a sequence of attribute nodes. Evaluating the same attribute set more than once can produce different results, because although an attribute set does not have parameters, it may contain expressions or instructions whose value depends on the evaluation context.
Each attribute node produced by expanding an attribute set has a
The following example creates a named title-style and uses it in a
The following example creates a named attribute set base-style and
uses it in a template rule with multiple specifications of the attributes:
is specified only in the attribute set
is specified in the attribute set, is specified on the literal result
element, and in an
is specified in the attribute set, and on the literal result element
is specified in the attribute set, and in an
Stylesheet fragment:
Result:
fn namespace.
The effect of an
The content of the
The children and attributes of the
The xsl:function/@name attribute defines the function’s name.
The xsl:param children define the function’s parameters:
The xsl:param/@name attribute defines the name of the parameter.
The xsl:param/@required attribute determines whether the parameter is mandatory or optional.
The xsl:param/@as attribute determines the required type of the parameter.
The xsl:param/@select attribute determines a default value for an optional parameter.
The xsl:function/@as attribute defines the return type of the function.
The implementation of the function is defined by the
An
The name of the function is given by the name
attribute.
It is a private.
XSLT 4.0 allows the function name to be unprefixed, provided that its
private. This represents a QName
in no namespace. A function call using an unprefixed function name is resolved to
a no-namespace function name in preference to a function in the default function namespace,
which for XSLT is always the fn namespace.
To prevent the namespace URI used for the function name appearing in
the result document, use the exclude-result-prefixes attribute on
the
The name of the function must not be in a
The function parameters are defined by child required="no"; otherwise, it is required.
The default value for an optional parameter can be defined using the select attribute or the
contained select attribute and the contained sequence
constructor is empty, then the default value will be the empty sequence. This will lead to a type error if the
required type of the parameter does not permit the empty sequence.
When considering function overriding, dynamic function calls,
and details such as the function-lookup function, it is useful to think
of an
This is not an exact equivalence, however, because of the rules allowing default values of function parameters to be context-dependent.
The
For example, the following f:compare, with an arity range of (2 to 3).
The effect of calling f:compare($a, $b) is the same as the effect
of calling f:compare($a, $b, { "order": "ascending" }).
Functions are not polymorphic. Although the XPath function call mechanism
allows two functions to have the same name and
The
It is a static error if an select
attribute or non-empty contentrequired="no".
It is a static error if an required="no", unless all following-sibling
required="no".
The as attribute of the false.
If the as attribute is omitted, no conversion takes place and any
value is accepted.
The default value for an optional parameter
(one with required="no") will often be supplied using a
simple literal or constant expression, for example
<xsl:param name="married" as="xs:boolean" select="false()"/>,
or <xsl:param name="options" as="map(*)" select="{}"/>.
However, to allow greater flexibility,
the default value can also be context-dependent. For example,
<xsl:param name="node" as="node()" select="."/> declares a parameter whose
default value is the context item from the dynamic context of the caller, while
<xsl:param name="collation" as="xs:string" select="default-collation()"/>
declares a parameter whose default value is the default collation from the dynamic context of the caller.
The detailed rules are as follows. In these rules, the term
The
The
The
The
The effect of these rules is that the select expression for an optional parameter
is evaluated in the same way as a static expression, except that it may contain context-dependent
subexpressions such as ., position(), last(),
static-base-uri(), and default-collation() to access the
dynamic context of the caller. It may also contain expressions such as name()
or @x = "abc" that have an implicit dependency on the dynamic context of the caller.
The result of the function
If a reduced-arity form of the function is invoked by omitting optional arguments, then
the result of the function is obtained by evaluating the sequence constructor after binding the
omitted arguments to their default values, which are obtained by evaluating the select
attribute or sequence constructor of the relevant
Within the sequence constructor, the
It is not possible within the body of the
The optional as attribute indicates the as attribute is a
If the as attribute as attribute is omitted, the calculated result is
used as supplied, and no conversion takes place.
Using the
It is possible to have multiple function declarations sharing the same function name and arity:
Multiple
A function declared using
A function declared within one package may be overridden
(using
The rules governing these three scenarios are given in the sections that follow.
Two stylesheet functions with the same name may appear in a package if their
In addition, a stylesheet function may be overridden by another stylesheet function with the same name that
has higher
It is a
It is a
Similarly it is a static error
The optional override-extension-function attribute defines what
happens if an override-extension-function attribute
has the value yes, then this function is used in preference; if it
has the value no, then the other function is used in preference. The
default value is yes.
Specifying override-extension-function="yes" ensures
interoperable behavior: the same code will execute with all processors.
Specifying override-extension-function="no" is useful when
writing a fallback implementation of a function that is available with some
processors but not others: it allows the vendor’s implementation of the
function (or a user’s implementation written as an extension function)
to be used in preference to the stylesheet implementation, which is useful when
the extension function is more efficient.
The override-extension-function attribute does
The override attribute is a override-extension-function,
retained for compatibility with XSLT 2.0. If both attributes are present then they
When a package is referenced in
If the visibility attribute of abstract then the
The XPath specification states that the function that is executed as the result of
a function call is identified by looking in the static context for a
XSLT 4.0 allows a http://www.w3.org/2005/xpath-functions.
A no-namespace function might be a private
An
it is
the override-extension-function or override
attribute has the value no and there is already a
The optional override-extension-function attribute defines what
happens if this function has the same name and an
override-extension-function attribute
has the value yes, then this function is used in preference; if it
has the value no, then the other function is used in preference. The
default value is yes.
Specifying override-extension-function="yes" ensures
interoperable behavior: the same code will execute with all processors.
Specifying override-extension-function="no" is useful when
writing a fallback implementation of a function that is available with some
processors but not others: it allows the vendor’s implementation of the
function (or a user’s implementation written as an extension function)
to be used in preference to the stylesheet implementation, which is useful when
the extension function is more efficient.
The override-extension-function attribute does
The override attribute is a override-extension-function,
retained for compatibility with XSLT 2.0. If both attributes are present then they
When the public or
abstract (See also
If a
The true if and only if a call on
For legacy reasons there is also a single-argument version of
true if there is a
function with the given name regardless of arity.
The standard rules for
Stylesheet functions have been designed to be largely deterministic: unless a
stylesheet function calls some
One exception to the intrinsic determinism of stylesheet functions arises because
constructed nodes have distinct identity. This means that when a function that
creates a new node is called, two calls on the function will return nodes that can
be distinguished: for example, with such a function, f:make-node() is
f:make-node() will return false.
Three classes of functions can be identified:
doc($X) is doc($X): that is, two calls supplying the same
URI return the same node.
Proactive functions: these offer the guarantee that each invocation of the
function causes a single execution of the function body, or behaves exactly
as if it did so. In particular this means that when the function creates new
nodes, it creates new nodes on each invocation. By default,
Elidable functions: these offer no guarantee of determinism, and no
guarantee of proactive evaluation. If the function creates new nodes, then
two calls on the function with the same arguments may or may not return the
same nodes, at the implementation’s discretion. Examples of elidable functions include
the
The new-each-time attribute of new-each-time="no" means the function is deterministic; the value
new-each-time="yes" means it is proactive; and the value
new-each-time="maybe" means it is elidable.
The definition of
Processors have considerable freedom to optimize execution of stylesheets, and of
function calls in particular, but the strategies that are adopted must respect the
specification as to whether functions are deterministic, proactive, or elidable.
For example, consider a function call that appears within an
new-each-time="maybe") makes it more
likely that an implementation will be able to apply this optimization, as well as
other optimizations such as caching or memoization.
The cache attribute is an optimization hint which the processor can
use or ignore at its discretion; however it
The default value is cache="no".
The value cache="yes" encourages the processor to retain memory of
previous calls of this function
during the same transformation and to reuse results from this memory whenever
possible. The default value cache="no" encourages the
processor not to retain memory of previous calls.
In all cases the results must respect the semantics. If a function is proactive
(new-each-time="yes") then caching of results may be infeasible,
especially if the function result can include nodes; but it is not an error to
request it, since some implementations may be able to provide caching, or
analogous optimizations, even for proactive functions. (One possible strategy is
to return a copy of the cached result, thus creating the illusion that the
function has been evaluated anew.)
Memoization is essentially a trade-off between time and space; a memoized
function can be expected to use more memory to deliver faster execution.
Achieving an optimum balance may require configuring the size of the cache that
is used; implementations
Memoization of a function generally involves creating an associative table (for
example, a hash map) that maps argument values to function results. To get this
right, it is vital that the key for this table should correctly reflect what it
means for two function calls to have “the same arguments”. Does it matter, for
example, that one call passes the xs:string value "Paris", while
another passes the xs:untypedAtomic item "Paris"? If the function
is declared with new-each-time="maybe", then the rules say that
these cannot be treated as “the same arguments”: the definition of
The following example creates a recursive str:reverse that reverses
the words in a supplied sentence, and then invokes this function from within a
The following example illustrates the use of the as attribute in a
function definition. It returns a string containing the representation of its
integer argument, expressed as a roman numeral. For example, the function call
num:roman(7) will return the string "vii". This
example uses the xs:string. So
the text node is
XPath 3.0 introduces the ability to pass function items as arguments to a function. A function that takes function items as arguments is known as a higher-order function.
The following example is a higher-order function that operates on any tree-structured data, for example an organization chart. Given as input a function that finds the direct subordinates of a node in this tree structure (for example, the direct reports of a manager, or the geographical subdivisions of an administrative area), it determines whether one object is present in the subtree rooted at another object (for example, whether one person is among the staff managed directly or indirectly by a manager, or whether one parcel of land is contained directly or indirectly within another parcel). The function does not check for cycles in the data.
(This example is written to use the
Given source data representing an organization chart in the form of elements such as:
the following function can be defined to get the direct reports of a manager:
It is then possible to test whether one employee $E reports
directly or indirectly to another employee $M by means of the
function call:
The two instructions described in this section, xsl:sequence
and xsl:select, can be used to evaluate XPath expressions that
are statically known: that is, the XPath expressions are statically processed
during the static processing of the stylesheet, and are dynamically evaluated
during the dynamic evaluation of the stylesheet. The
xsl:sequence Instructionas attribute is available on the The
The select attribute and the contained select attribute, then it select attribute and no contained
The effect of the instruction is as follows:
Evaluate the expression in the select attribute if present,
or the contained
Use the as attribute, defaulting to item()*.
The converted result is the value returned by the
For the elements select attribute is present
and the instruction has children other than
The xsl:fallback
instruction is relevant only to an XSLT 1.0 processor operating in forwards compatibility mode.
An XSLT 2.0 or 3.0 processor operating in forwards compatibility mode will ignore the @as
attribute.
The <xsl:sequence select="..." as="item()"/> to
make this clear to the reader.
The main use case for allowing
It can also be used to limit the scope of local variables or of standard
attributes such as [xsl:]default-collation.
The following code:
produces the output: 37
xsl:for-each to Construct a SequenceThe following code constructs a sequence containing the value of the
@price attribute for selected elements,
or a computed price for those elements that
have no @price attribute:
Note that the existing @price attributes could equally have been
added to the $prices sequence using xs:decimal. Using xs:decimal atomic item to the result sequence, is a more direct
way of achieving the same result.
This example could alternatively be solved at the XPath level:
or, in XSLT 4.0:
The apparently redundant + operator is there to atomize the attribute
value: the expression on the right hand side of the / operator must
not return a sequence containing both nodes and
non-nodes (atomic items or function items).
xsl:select InstructionThe
evaluates the contained XPath expression, in the current static and dynamic context, and returns (in this example) a map with two entries.
While the select
attribute) can also be used to evaluate
an arbitrary XPath expression and return its result, the
An XPath expression written within an XML attribute is subjected by the XML parser to attribute value normalization, which changes the arrangement of whitespace within the value. While this will rarely affect the actual meaning of the expression, it can mean that formatting is lost. Multi-line attribute values are therefore best avoided. The loss of formatting also makes it difficult for an XSLT processor to provide precise error locations.
When an XPath expression appears in an attribute value, then one of the
characters " or '
respectively. When an expression is written within a text node, this problem does not
arise, and both characters can be used without escaping.
The content of the < and <=
to be written without escaping.
The instruction name
With the increasing richness of the XPath language, expressions of ten or twenty lines become increasingly common, and this instruction makes such expressions more manageable. This often arises when constructing maps and arrays designed to be serialized as JSON. For example, a function might be defined that takes an element node as input and constructs a map containing selected information:
Any
The effect of the
Let E be the string value of the last text node child of the instruction, if any.
If E is absent, zero-length, or consists entirely of whitespace, then let V be the empty sequence.
Otherwise, let V be the result of evaluating E as an XPath expression in the current static and dynamic context.
The result of the as attribute,
defaulting to item()*.
The text node cannot contain text value templates.
The
Many instructions take their input either from an XPath expression
contained in a select attribute, or from a sequence constructor
forming the content of the instruction, the two options being mutually exclusive.
Instructions that follow this pattern
include select attribute. However, there are a few subtle differences,
for example in the case of select attribute is used, a zero-length
string for a sequence constructor comprising an
trusted=yes|no is added to no, which may cause backwards
incompatibility. Dynamic evaluation using The
The expression given as the value of the xpath attribute is evaluated
and the result is converted to a string using the
xpath attribute is referred to
as the
It is a
The as attribute, if present, indicates the required type of the result.
If the attribute is absent, the required type is item()*, which allows
any result. The result of evaluating the
The target expression may contain variable references; the values
of such variables may be supplied using an with-params attribute if
the names are only known dynamically. If the with-params attribute is
present then it must contain an expression whose value, when evaluated, is of type
map(xs:QName, item()*) (see
It is a with-params
attribute of the map(xs:QName, item()*).
The
XPath 1.0 compatibility mode is false.
Trust level: the trusted attribute. If the value is yes,
the target expression has the same level of trust, and may therefore access
the same external resources, as the calling stylesheet. If the value is
no, the target expression has no access to external resources,
other than any resources made explicitly available via some secure
Statically known namespaces and default namespaces for elements and for types:
if the namespace-context attribute is present, then its
value is an
It is a namespace-context
attribute of the
if the namespace-context attribute is absent, then the
[xsl:]xpath-default-namespace,
if present, is used to establish the default namespace for elements and
types in the target expression, as described in
XPath 3.0 allows expanded names to be written in a context-independent
way using the syntax Q{namespace-uri}local-name
Default function namespace: the
In-scope schema definitions: if the schema-aware attribute is
present and has the yes, then the in-scope schema definitions from the stylesheet
context of the [xsl:]schema-role
on the
If the containing stylesheet does not import a schema, then the in-scope schema definitions
for the target expression will contain only the built-in schema types, regardless of the value
of the schema-aware attribute.
In-scope variables: the names of the in-scope variables
are the union of the names appearing in the name attribute of
the contained with-params attribute, if present. The corresponding type is
item()* in the case of a name found as a key in the
with-params map, or the type named in the as
attribute of item()*) otherwise.
If a variable name is present both the static
with-params map, the value from the latter takes
precedence.
Variables declared in the stylesheet in
Function signatures:
All functions defined in fn, math, map, and array namespaces;
Constructor functions for named simple types included in the in-scope schema definitions;
All user-defined functions present in the containing package provided their visibility is
not hidden or private;
An
Note that this set deliberately excludes XSLT-defined functions in the
Statically known collations: the same as the collations available at this point in the stylesheet.
Default collation: the same as the default collation defined at this point
in the stylesheet (for example, by use of the
[xsl:]default-collation attribute)
Base URI: if the base-uri attribute is present, then its
The dynamic context for evaluation of the target expression is as follows:
The context-item attribute. If this attribute is
absent then the context value,
position, and size for evaluation of the target expression are all
If the result of evaluating the context-item expression
The attribute name context-item is a misnomer; it reflects the fact
that in XSLT 3.0, the supplied expression was required to return a single item, rather than
an arbitrary sequence.
The with-params attribute;
if the same QName is bound in both, the value in the
with-params map takes precedence.
The XSLT-specific aspects of the dynamic context described in
The
All other aspects of the dynamic context are the same as the dynamic context
for the may restrict
the availability of external resources (for example, available documents)
or provide options to restrict their availability, for security
reasons.
For example, a processor may disallow access using the
xsl:evaluate instructionThe XPath expression is evaluated in the same
It is a
Implementations wanting to avoid the cost of repeated compilation of the same XPath expression should cache the compiled form internally.
Stylesheet authors need to be aware of the security risks
associated with the use of
A processor
If the feature is statically disabled, then:
A call to element-available('xsl:evaluate') returns false,
wherever it appears;
A call to system-property('xsl:supports-dynamic-evaluation')
returns the string "no", wherever it appears;
If an
No static error is raised if an
If the feature is dynamically disabled, then:
A call to element-available('xsl:evaluate') appearing in a
[xsl:]use-when attribute) returns true;
A call to element-available('xsl:evaluate') appearing anywhere
else returns false;
A call to system-property('xsl:supports-dynamic-evaluation')
appearing in a [xsl:]use-when
attribute) returns the string "yes";
A call to system-property('xsl:supports-dynamic-evaluation')
appearing anywhere else returns the string "no";
If an
In the absence of an
It is a
In consequence of these rules, the recommended approach for stylesheet authors to
write code that works whether or not
There may be circumstances where may be inappropriate to allow use of
There may be security risks associated with the ability to execute code
from an untrusted source, which cannot be inspected during static
analysis. This risk is reduced in XSLT 4.0, because a processor
is trusted="no",
which disables access to external resources. However, some risk remains
because untrusted code may still consume unbounded CPU or memory resource.
There may be environments where the available computing resources are sufficient to enable pre-compiled stylesheets to be executed, but not to enable XPath expressions to be compiled into executable code.
A common requirement is to sort a table on the value of an expression which is selected at run-time, perhaps by supplying the expression as a string-valued parameter to the stylesheet. Suppose that such an expression is supplied to the parameter:
Then the data may be sorted as follows:
Note the importance in this use case of caching the compiled expression, since it is evaluated repeatedly, once for each item in the list being sorted.
If the
The main difference between this function and the standard
The Q{namespace-uri}local#arity, which is then evaluated to return a
function item representing the requested function.
This section describes instructions that directly create new nodes.
The content of the element is a
The base URI of the new element is copied from the base URI of the literal result
element in the stylesheet, unless the content of the new element includes an
xml:base attribute, in which case the base URI of the new element is
the value of that attribute, resolved (if it is a relative URI reference) against the base URI of the literal result element in
the stylesheet. (Note, however, that this is only relevant when creating a parentless
element. When the literal result element is copied to form a child of an element or
document node, the base URI of the new copy is taken from that of its new
parent.)
The attributes xsl:type and xsl:validation may be used
on a literal result element to invoke validation of the contents of the element
against a type definition or element declaration in a schema, and to determine the
The value of the xsl:validation attribute, if present, must be one of
the values strict, lax, preserve, or
strip. The value of the xsl:type attribute, if
present, must be an
Attribute nodes for a literal result element may be created by including
xsl:use-attribute-sets attribute of the literal result element, if
present.
The sequence that is used to construct the content of the literal result element
(as described in
The sequence of namespace nodes produced as described in
The sequence of attribute nodes produced by expanding the
xsl:use-attribute-sets attribute (if present) following the
rules given in
The attributes produced by processing the attributes of the literal result
element itself, other than attributes in the
The sequence produced by evaluating the contained
The significance of this order is that an attribute produced by an
xsl:use-attribute-sets
attribute. This is because of the rules in
Although the above rules place namespace nodes before attributes, this is not
strictly necessary, because the rules in
Each attribute of the literal result element, other than an attribute in the
The value of such an attribute is interpreted as an {}). The new attribute node will have the same
xs:untypedAtomic, and the
The eventual xsl:validation and xsl:type attributes of the
parent literal result element, and on the instructions used to create its
ancestor elements. If the xsl:validation attribute is set to
preserve or strip, the type annotation will be
xs:untypedAtomic, and the xsl:validation attribute is set to strict or
lax, or if the xsl:type attribute is used, the
type annotation on the attribute will be set as a result of the schema
validation process applied to the parent element. If neither attribute is
present, the type annotation on the attribute will be
xs:untypedAtomic.
If the name of a constructed attribute is xml:id, the processor must
perform attribute value normalization by effectively applying the
is-id
property.
If the attribute name is xml:space, it is default or
preserve. Although the XML specification states that other
values are erroneous, a document containing such values is well-formed; if
erroneous values are to be rejected, schema validation should be used.
The xml:base, xml:lang, xml:space, and
xml:id attributes have two effects in XSLT. They behave as
standard XSLT attributes, which means for example that if they appear on a
literal result element, they will be copied to the xml:base attribute in the stylesheet
affects the base URI of the element on which it appears, and an
xml:space attribute affects the interpretation of
The same is true of the schema-defined attributes xsi:type,
xsi:nil, xsi:noNamespaceSchemaLocation, and
xsi:schemaLocation. If the stylesheet is processed by a schema
processor, these attributes will be recognized and interpreted by the schema
processor, but in addition the XSLT processor treats them like any other
attribute on a literal result element: that is, their
None of these attributes will be generated in the
It is a
If there is a need to create attributes in the XSLT namespace, this can be
achieved using
The created element node will have a copy of the namespace nodes that were present
on the element node in the stylesheet tree with the exception of any namespace
node whose
The following namespaces are designated as excluded namespaces:
The http://www.w3.org/1999/XSL/Transform)
A namespace URI declared as an extension namespace (see
A namespace URI designated by using an
[xsl:]exclude-result-prefixes attribute either on the
literal result element itself or on an ancestor element. The attribute
The value of the attribute is either #all, or a
whitespace-separated list of tokens, each of which is either a namespace
prefix or #default. The namespace bound to each of the prefixes
is designated as an excluded namespace.
It is a [xsl:]exclude-result-prefixes attribute and there is
no namespace binding in scope for that prefix.
The prefix must be declared in a
The default namespace of the parent element of the
[xsl:]exclude-result-prefixes attribute (see #default in the list of namespace
prefixes.
It is a #default is used within the
[xsl:]exclude-result-prefixes attribute and the parent
element of the [xsl:]exclude-result-prefixes attribute
has no default namespace.
The value #all indicates that all namespaces that are in scope
for the stylesheet element that is the parent of the
[xsl:]exclude-result-prefixes attribute are designated as
excluded namespaces.
The designation of a namespace as an excluded namespace is effective within
the subtree of the stylesheet module rooted at the element bearing the
[xsl:]exclude-result-prefixes attribute; a subtree rooted at
an
The excluded namespaces, as described above,
When a stylesheet uses a namespace declaration only for the purposes of
addressing a [xsl:]exclude-result-prefixes attribute will
avoid superfluous namespace declarations in the serialized
In XSLT 4.0, a simpler approach is to declare such namespaces in a fixed-namespaces
attribute on the xsl:stylesheet element: see
Consider the following stylesheet:
The result of this stylesheet will be:
The namespaces a.uri and b.uri are excluded by virtue
of the exclude-result-prefixes attribute on the
c.uri is excluded by virtue of the
xsl:exclude-result-prefixes attribute on the foo
element. The setting #all does not affect the namespace
d.uri because d.uri is not an in-scope namespace
for the xmlns:a2="a.uri" because the effect of
exclude-result-prefixes is to designate the namespace URI
a.uri as an excluded namespace, irrespective of how many
prefixes are bound to this namespace URI.
If the stylesheet is changed so that the literal result element has an
attribute b:bar="3", then the element in the xmlns:b="b.uri" (the processor may choose a different
namespace prefix if this is necessary to avoid conflicts). The
exclude-result-prefixes attribute makes b.uri an
excluded namespace, so the namespace node is not automatically copied from the
stylesheet, but the presence of an attribute whose name is in the namespace
b.uri forces the namespace fixup process (see
A literal result element may have an optional xsl:inherit-namespaces
attribute, with the value yes or no. The default value
is yes. If the value is set to yes, or is omitted, then
the namespace nodes created for the newly constructed element are copied to the
children and descendants of the newly constructed element, as described in
no, then these namespace nodes are not automatically copied to the
children. This may result in namespace undeclarations (such as
xmlns="" or, in the case of XML 1.1, xmlns:p="")
appearing on the child elements when they are serialized.
When a stylesheet is used to define a transformation whose output is itself a stylesheet module, or in certain other cases where the result document uses namespaces that it would be inconvenient to use in the stylesheet, namespace aliasing can be used to declare a mapping between a namespace URI used in the stylesheet and the corresponding namespace URI to be used in the result document.
Either of the
The effect is that when names in the namespace identified by the
the namespace URI in the
the namespace URI in the
The effect of an
Where namespace aliasing changes the namespace URI part of the result-prefix attribute of the
The stylesheet-prefix is the
result-prefix
attribute is the stylesheet-prefix attribute specifies the
namespace URI that will appear in the stylesheet, and the
result-prefix attribute specifies the corresponding namespace URI
that will appear in the
It is the p
appears in the stylesheet-prefix or result-prefix attribute,
there must be an in-scope namespace declaration of the form xmlns:p="....";
it is not sufficient to declare the namespace in the fixed-namespaces
attribute of the
The default namespace (as declared by xmlns) may be specified by
using #default instead of a prefix. If no default namespace is in
force, specifying #default denotes the null namespace URI. This
allows elements that are in no namespace in the stylesheet to acquire a namespace
in the result document, or vice versa. result-prefix="#default" is specified and
no default namespace is in force, attributes whose namespace matches the literal namespace
URI are renamed to be in no namespace.
If a
It is a
No error occurs if there is more than one such
result-prefix differs; in this case the
result-prefix used is the one that appears last in
It is a #default is specified for either the
stylesheet-prefix or the result-prefix
attributes of the
When a literal result element is processed, its namespace nodes are handled as follows:
A namespace node whose string value is a
A namespace node whose string value is a
In the event that the same URI is used as a
These rules achieve the effect that the element generated from the literal
result element will have an in-scope namespace node that binds the
result-prefix to the stylesheet-prefix and the
When literal result elements are being used to create element, attribute, or
namespace nodes that use the
For example, the stylesheet
will generate an XSLT stylesheet from a document of the form:
The output of the transformation will be a stylesheet such as the following.
Whitespace has been added for clarity. Note that an implementation may output
different namespace prefixes from those appearing in this example; however, the
rules guarantee that there will be a namespace node that binds the prefix
xsl to the URI
http://www.w3.org/1999/XSL/Transform, which makes it safe to
use the QName xsl:version in the content of the generated
stylesheet.
It may be necessary also to use aliases for namespaces other than the XSLT
namespace URI. For example, it can be useful to define an alias for the
namespace http://www.w3.org/2001/XMLSchema-instance, so that the
stylesheet can use the attributes xsi:type, xsi:nil,
and xsi:schemaLocation on a literal result element, without
running the risk that a schema processor will interpret these as applying to
the stylesheet itself. Equally, literal result elements belonging to a
namespace dealing with digital signatures might cause XSLT stylesheets to be
mishandled by general-purpose security software; using an alias for the
namespace would avoid the possibility of such mishandling.
It is possible to define an alias for the XML namespace.
produces the output:
This allows an xml:space attribute to be generated in the output
without affecting the way the stylesheet is parsed. The same technique can be
used for other attributes such as xml:lang, xml:base,
and xml:id.
Namespace aliasing is only necessary when literal result elements are used. The
problem of reserved namespaces does not arise when using
xsl:element
The name attribute and an optional namespace attribute.
The result of evaluating the
The content of the
The use-attribute-sets attribute, whose value is a
whitespace-separated list of QNames that identify
The name attribute is interpreted as an
It is a name attribute
In the case of an namespace attribute, it is a name attribute is a
If a fixed-namespaces attribute is present on the containing
If the namespace attribute is not present then the
If the namespace attribute is present, then it too is interpreted as
an xs:anyURI
type. If the string is zero-length, then the name attribute is used as the local part of the
It is a namespace attribute xs:anyURI datatype or if it is the string
http://www.w3.org/2000/xmlns/.
The XDM data model requires the name of a node to be an instance of
xs:QName, and XML Schema defines the namespace part of an
xs:QName to be an instance of xs:anyURI. However,
the schema specification, and the specifications that it refers to, give
implementations some flexibility in how strictly they enforce these
constraints.
The prefix of the name attribute (or the absence of a prefix) is
copied to the prefix part of the xml to refer to a namespace other than the XML namespace,
or any use of the prefix
xmlns.
The inherit-namespaces attribute, with the value yes or
no. The default value is yes. If the value is set to
yes, or is omitted, then the namespace nodes created for the newly
constructed element (whether these were copied from those of the source node, or
generated as a result of namespace fixup) are copied to the children and
descendants of the newly constructed element, as described in no,
then these namespace nodes are not automatically copied to the children. This may
result in namespace undeclarations (such as xmlns="" or, in the case
of XML Namespaces 1.1, xmlns:p="") appearing on the child elements
when
the element is serialized.
The base URI of the new element is copied from the base URI of the
xml:base attribute, in which case the
base URI of the new element is the value of that attribute, resolved (if it is a
relative URI) against the base URI of the
The values of the nilled,
is-id, and is-idrefs properties of the new element
depend on the type and validation attributes of the
The optional attributes type and validation may be used
on the
The final type annotation of the element in the type and
validation attributes of the instructions used to create the
ancestors of the element.
xsl:attribute
The name attribute and an optional namespace attribute. Except
in error cases, the result of evaluating an
The string value of the new attribute node may be defined either by using the
select attribute, or by the select attribute is present then the
sequence constructor must be empty, and if the sequence constructor is non-empty
then the select attribute must be absent. If the select
attribute is absent and the sequence constructor is empty, then the
string value of the new attribute node will be a zero-length string. The way in which
the value is constructed is specified in
It is a select attribute of the
If the separator attribute is present, then the select attribute, or a zero-length string when the content is
specified using a
The name attribute is interpreted as an
It is a name
attribute
In the case of an namespace attribute, it is a name attribute is the string
xmlns.
In the case of an namespace attribute, it is a name attribute is a
If a fixed-namespaces attribute is present on the containing
If the namespace attribute is not present, then the
If the namespace attribute is present, then it too is interpreted as an
xs:anyURI type.
If the string is zero-length, then the name
attribute is used as the local part of the
It is a namespace attribute xs:anyURI datatype or if it is the string
http://www.w3.org/2000/xmlns/.
The same considerations apply as for elements:
The prefix of the name attribute (or the absence of a prefix) is copied to the
prefix part of the xml to refer to a namespace other than the XML
namespace, or any use of the prefix xmlns.
If the name of a constructed attribute is xml:id, the processor must
perform attribute value normalization by effectively applying the
is-id property. This
applies whether the attribute is constructed using the
The effect of setting the is-id property is that the parent element
can be located within the containing document by use of the
xml:id processor, as
defined in xml:id
processing are performed during validation.
The following instruction creates the attribute colors="red green
blue":
It is not an error to write:
However, this will not result in the namespace declaration
xmlns:xsl="http://www.w3.org/1999/XSL/Transform" being output.
Instead, it will produce an attribute node with local name xsl, and
with a system-allocated namespace prefix mapped to the namespace URI
file://some.namespace. This is because the namespace fixup process
is not allowed to use xmlns as the name of a namespace node.
As described in
If a collection of attributes is generated repeatedly, this can be done
conveniently by using named attribute sets: see
The optional attributes type and validation may be used
on the
The process of validation also determines the values of
the is-id and is-idrefs properties on the new attribute
node.
The final type and validation attributes of the instructions
used to create the ancestors of the attribute.
select attribute,
and it can take a sequence constructor as its content. The only remaining distinction
between the This section describes three different ways of creating text nodes: by means of
literal text nodes in the stylesheet, or by using the
If and when the sequence that results from evaluating a
The following function returns a sequence of three text nodes:
When this function is called as follows:
the result is:
No additional spaces are inserted, because the calling
is:
because in this case the three text nodes are atomized to form three strings, and spaces are inserted between adjacent strings.
This example reflects the traditional usage of
It is possible to construct text nodes whose string value is zero-length. A
zero-length text node, when atomized, produces a zero-length string. However,
zero-length text nodes are ignored when they appear in a sequence that is used to
form the content of a node, as described in
A
Text is processed at the tree level. Thus, markup of < in a
template will be represented in the stylesheet tree by a text node that includes
the character <. This will create a text node in the <
character, which will be represented by the markup < (or an
equivalent character reference) when the result tree is serialized as an XML
document, unless otherwise specified using disable-output-escaping (see
A non-whitespace text node in the stylesheet that is not contained within an
is equivalent to:
cdata is added to The
The
Special rules apply to separator attribute is present,
and if the select attribute is present, then all items in the
The
The string value of the new text node may be defined either by using the
select attribute, or by the
select
attribute is present then the sequence constructor must be empty, and if the
sequence constructor is non-empty then the select attribute must
be absent. If the select attribute is absent and the sequence
constructor is empty, then the result of the instruction is a text node whose
string value is zero-length. The way in which the value is constructed
is specified in
It is a select attribute of the
If the separator attribute is present, then the
select attribute, or a zero-length string when the content is
specified using a
If the element or one of its ancestors has an
[xsl:]expand-text attribute, and the nearest ancestor with such an
attribute has the value yes, then any unescaped curly brackets in the
value of the element indicate the presence of
In the absence of such an attribute, or if the
no, the content of the
For the effect of the cdata attribute, see
For the effect of the disable-output-escaping attribute, see
It is not always necessary to use the
Historically,
The instruction:
produces the output:
xsl:textThe instruction:
produces the output:
This illustrates that all whitespace text node children of
cdata is added to The XDM data model (see <e>x < y</e> and <e><![CDATA[x < y]]></e> have
exactly the same representation in XDM: an element node with a text node child, the string value
of the text node being "x < y".
It is however possible to request that a text node should be serialized as a CDATA section. If all elements
with a given name are to be serialized as CDATA, this can be achieved using the serialization parameter
cdata-section-elements (available, for example, as an attribute on cdata attribute on the
The cdata attribute, if its effective value is yes,
is a request to the processor to serialize the text node as a CDATA section.
For example, the text node produced by the instruction <xsl:text cdata="yes">>>></xsl:text>
might be serialized as <![CDATA[>>>]]>. Honoring this request
requires close coupling between the processor and the serializer, and
processors
It is cdata attribute of the
A processor delivering output in the form of an in-memory tree using a data model
(such as the DOM model) that includes CDATA nodes cdata attribute to generate such nodes.
If the cdata attribute is present, regardless of its disable-output-escaping attribute is ignored.
The attribute is likely to have effect only in the following circumstances:
The output of the transformation is sent directly to a serializer (or to another destination, such as a DOM, that recognizes CDATA).
The serialization method is xml or xhtml (perhaps
invoked indirectly via the html or adaptive output methods).
The text node is not bound to a variable.
The parent element of the text node is not listed in the cdata-section-elements
serialization parameter (in this case every text node child of the element
should be serialized as a CDATA section, regardless of any cdata
attributes).
The text node is not used as input to the process of constructing
an attribute, comment, processing instruction, or another text node:
see
The text node is not used as input to the process of constructing
a
The cdata attribute is an
will request serialization as a CDATA section if the text contains either of the
characters < or &.
Whether or not the output of an
The effect of setting cdata="yes" (in cases where it has any effect at all)
is as if the text node were wrapped in a containing element
whose name is listed in the cdata-section-elements parameter,
with the start and end tags of that element then being stripped from the serialized output.
This implies:
If the text node includes the character sequence ]]>, then the CDATA section
must be closed, and a new CDATA section opened, after the ]].
Similarly, if the text node includes a codepoint that cannot be represented using the selected encoding, then the CDATA section must be closed, and a new CDATA section opened, after the escaped representation of that codepoint.
Unicode normalization does not operate across the boundary between a CDATA and a non-CDATA text node.
Character mapping (as defined by the use-character-maps parameter)
does not take place within a CDATA text node.
Special characters such as & and <
in a CDATA text node are not escaped.
The
Except in error situations, the result of evaluating the
The new document is not serialized. To construct a document that is to form a
final result rather than an intermediate result, use the
The optional attributes type and validation may be used on
the
The base URI of the new document node is taken from the base URI of the
The document-uri and unparsed-entities properties of the
new document node are set to empty.
The following example creates a temporary tree held in a variable. The use of an
enclosed
The
The name attribute that specifies the name of the processing instruction
node. The value of the name attribute is interpreted as an
The string value of the new processing instruction node may be defined either by
using the select attribute, or by the select
attribute is present then the sequence constructor must be empty, and if the
sequence constructor is non-empty then the select attribute must be
absent. If the select attribute is absent and the sequence
constructor is empty, then the string value of the new
processing instruction node will be a zero-length string. The way in which the value
is constructed is specified in
It is a select attribute of the
Except in error situations, the result of evaluating the
This instruction:
creates the processing instruction
Note that the xml-stylesheet processing instruction contains
name="value". Although
these have the same textual form as attributes in an element start tag, they are
not represented as XDM attribute nodes, and cannot therefore be constructed using
It is a name
attribute
Because these rules disallow the name xml, the
If the result of evaluating the content of the
?>, this string is modified by inserting a space between the
? and > characters.
The base URI of the new processing instruction is copied from the base URI of the
The
The name attribute that specifies the name of the namespace node (that is,
the namespace prefix). The value of the name attribute is interpreted as
an name attribute is a zero-length string, a namespace node is added for
the default namespace.
The string value of the new namespace node (that is, the namespace URI) may be
defined either by using the select attribute, or by the select attribute is present
then the sequence constructor must be empty, and if the sequence constructor is
non-empty then the select attribute must be absent. Since
the string value of a namespace node cannot be a zero-length string, either a select attribute or a non-empty sequence
constructor
It is a xs:anyURI, or if it is the string
http://www.w3.org/2000/xmlns/.
It is a select attribute of the select
attribute is absent when the element has empty content.
Note the restrictions described in
This literal result element:
would typically cause the output document to contain the element:
In this case, the element is constructed using a literal result element, and the
namespace xmlns:xs="http://www.w3.org/2001/XMLSchema" could therefore
have been added to the
It is a name
attribute xmlns.
It is a xml and whose string value is not
http://www.w3.org/XML/1998/namespace, or a namespace node whose
string value is http://www.w3.org/XML/1998/namespace and whose
name is not xml.
It is a select attribute or the contained
For details of other error conditions that may arise, see
It is rarely necessary to use
Adding a namespace node to the
Namespace prefixes for element and attribute names are initially established by
the rules of the instruction that creates the element or attribute node, and in
the event of conflicts, they may be changed by the namespace fixup process
described in
If a namespace prefix is mapped to a particular namespace URI using the
Given the instruction:
a possible serialization of the
The processor must invent a namespace prefix for the URI p.uri; it
cannot use the prefix p because that prefix has been explicitly
associated with a different URI.
The xmlns="" (nor the
new forms of namespace undeclaration permitted in undeclare-prefixes="yes" is specified on
The
The string value of the new comment node may be defined either by using the
select attribute, or by the select attribute is present then the sequence
constructor must be empty, and if the sequence constructor is non-empty then the
select attribute must be absent. If the select
attribute is absent and the sequence constructor is empty, then the
string value of the new comment node will be a zero-length string. The way in which
the value is constructed is specified in
It is a select attribute of the
For example, this
would create the comment
In the generated comment node, the processor x2D (hyphen) that is followed by another occurrence of x2D (hyphen) or
that ends the comment.
The select attribute if present, or
the
It is a select
attribute when the context item is absent.
If the select expression returns the empty sequence,
the
It is a select expression
When the selected item is an atomic item
or function item, the
When the selected item is an attribute node,
text node, comment node, processing instruction node, or namespace node, the
is-id and is-idrefs properties. The
When the selected item is a document node or
element node, the select attribute is present then the sequence constructor is
evaluated with the selected item as the
When the selected item is a document node, the
unparsed-entities property of the existing document node is copied
to the new document node.
When the selected item is an element or attribute node,
the values of the is-id, is-idrefs, and
nilled properties of the new element or attribute depend on the
values of the validation and type attributes, as defined
in
The use-attribute-sets attribute, whose value is a
whitespace-separated list of QNames that identify
The copy-namespaces attribute, with the value yes or
no. The default value is yes. The attribute is used
only when copying element nodes. If the value is set to yes, or is
omitted, then all the namespace nodes of the source element are copied as
namespace nodes for the result element. These copied namespace nodes are prepended
to the sequence produced as a result of evaluating the use-attribute-sets attribute). If the value is set to
no, then the namespace nodes are not copied. However, namespace
nodes will still be added to the result element as
The inherit-namespaces attribute, with the value yes or
no. The default value is yes. The attribute is used
only when copying element nodes. If the value is set to yes, or is
omitted, then the namespace nodes created for the newly constructed element
(whether these were copied from those of the source node, or generated as a result
of namespace fixup) are copied to the children and descendants of the newly
constructed element, as described in no, then these namespace nodes are not
automatically copied to the children. This may result in namespace undeclarations
(such as xmlns="" or, in the case of XML Namespaces 1.1,
xmlns:p="") appearing on the child elements when a
It is a copy-namespaces attribute has the value no and
its explicit or implicit validation attribute has the value
preserve. It is also a type error if either of these
instructions (with validation="preserve") is used to copy an
attribute having namespace-sensitive content, unless the parent element is
also copied. A node has namespace-sensitive content if its typed value
contains an item of type xs:QName or xs:NOTATION
or a type derived therefrom. The reason this is an error is because the
validity of the content depends on the namespace context being
preserved.
When attribute nodes are copied, whether with
The optional attributes type and validation may be used
on the
The final type and validation attributes of the instructions
used to create the ancestors of the node.
When a node is copied, its base URI is copied, except
when the result of the xml:base attribute, in which case the base URI of the new
node is taken as the value of its xml:base attribute, resolved if it
is relative against the base URI of the
When an xml:id attribute is copied, using either the
In most cases the value will already have been subjected to attribute value normalization on the source tree, but if this processing has not been performed on the source tree, it is not an error for it to be performed on the result tree.
xml:id attribute that has
not been subjected to attribute value normalization is copied from a source tree
to a result tree, it is implementation-defined whether attribute value
normalization will be applied during the copy process.The
The select attribute contains an
If the item is an element node, a new element is constructed and appended to
the result sequence. The new element will have the same
The new element will also have namespace nodes copied from the original
element node, unless they are excluded by specifying
copy-namespaces="no". If this attribute is omitted, or takes
the value yes, then all the namespace nodes of the original
element are copied to the new element. If it takes the value
no, then none of the namespace nodes are copied: however,
namespace nodes will still be created in the select
select expression.
The values of the is-id,
is-idrefs, and nilled properties of the new
element depend on the values of the validation and
type attributes, as defined in
If the item is a document node, the instruction adds a new document node to
the result sequence; the children of this document node will be one-to-one
copies of the children of the original document node (each copied according
to the rules for its own node kind). The
unparsed-entities property of the original document node
is copied to the new document node.
If the item is an attribute or namespace node, or a text node, a comment, or
a processing instruction, the same rules apply as with
If the item is an atomic item or a function
item, the value is appended to the result sequence, as with
The optional attributes type and validation may be used
on the select attribute. These attributes are ignored when copying an
item that is not an element, attribute or document node.
The specified type and validation apply directly only to
elements, attributes and document nodes created as copies of nodes actually
selected by the select expression, they do not apply to nodes that
are implicitly copied because they have selected nodes as an ancestor. However,
these attributes do indirectly affect the
These two attributes are both optional, and if one is specified then the other
Errors may occur when copying namespace-sensitive elements or attributes using
validation="preserve".
If removal of namespaces is requested using
copy-namespaces="no", then any validation that is requested is
applied to the tree that remains after the relevant namespaces have been removed.
This will cause validation to fail if there is namespace-sensitive content that
depends on the presence of the removed namespaces.
The base URI of a node is copied, except in the case of an element node having an
xml:base attribute, in which case the base URI of the new node is
taken as the value of the xml:base attribute, resolved if it is
relative against the base URI of the xml:base attribute.
For any node N that is explicitly selected by the evaluation of the
select expression, the base URI of the new copy is as follows:
If N is an element node having an xml:base attribute,
the base URI of the new node is taken as the value of the xml:base attribute,
resolved if it is relative against the static base URI of the xsl:copy-of instruction.
Otherwise, the base URI of the new copy is the same as the base URI of N.
For any element or processing instruction node that has N as an ancestor,
the base URI of the new copy is set to be the same as that of its new parent,
with the following exception: if a copied element has an xml:base
attribute, then its base URI is set to the value of that attribute,
resolved if it is relative against the base URI of the new parent node.
If two elements in a subtree have different base URIs for some reason
unconnected with xml:base attributes (for example, if they originated in different
external entities), then these differences are lost when the subtree is copied.
As a consequence of rules specified elsewhere (see xsl:copy-of instruction is subsequently attached
as a child to a new element or document node, the final copy of the node inherits
its base URI from its new parent node, unless this is overridden using an xml:base attribute.
The effect of the copy-accumulators attribute is described in
The
1.12.2 or 3(c)ii), and secondly, formatting the place
marker for output as a text node in the result sequence.value attribute, or
it can be computed based on the position of a selected node within the tree that
contains it.
It is a value attribute of select, level, count, and
from attributes are all absent.
The facilities described in this section are specifically designed to enable the
calculation and formatting of section numbers, paragraph numbers, and the like. For
formatting of other numeric quantities, the
Furthermore, formatting of integers where there is no requirement to calculate the
position of a node in the document can now be accomplished using the
start-at AttributeThe start-at attribute -?[0-9]+(\s+-?[0-9]+)*. This
sequence of integers is used to start-at attribute, and $V is the sequence of integers to
be formatted, then the following transformation is applied to $V:
This means that if there are N integers in the start-at
attribute, then these are used to re-base the first N numbers, while
numbers after the Nth are re-based using the last (Nth)
integer in the start-at attribute. If the start-at
attribute contains more integers than are required, the surplus is ignored.
For example, if the attribute is given as
start-at="3 0 0", and the number sequence to be formatted is
(1, 1, 1, 1), then the re-based sequence is 3, 0, 0,
0.
The value attribute contains the xs:integer(round(number($V))). If
the start-at attribute is present, this sequence is then re-based as
described in
If the instruction is processed with
All items in the
If the atomized sequence is empty, it is replaced by a sequence containing the
xs:double value NaN as its only item;
If any value in the sequence cannot be converted to an integer (this includes
the case where the sequence contains a NaN value) then the string
NaN is inserted into the formatted result string in its proper
position. The error described in the following paragraph does not apply in this
case.
It is a value
attribute of
The value zero does not arise when numbering nodes in a source document, but it
can arise in other numbering sequences. It is permitted specifically because the
rules of the
The resulting sequence is formatted as a string using the
The following example numbers a sorted list:
If no value attribute is specified, then the select attribute is
present, then the expression contained in the select attribute is
evaluated to determine the selected node. If the select attribute is
omitted, then the selected node is the
It is a value or select attribute, when the
It is a select attribute of the
The following attributes control how the selected node is to be numbered:
The level attribute specifies rules for selecting the nodes that
are taken into account in allocating a number; it has the values
single, multiple or any. The default
is single.
The count attribute is a count attribute is not specified, then it defaults to
the pattern that matches any node with the same node kind as the selected node
and, if the selected node has an
The from attribute is a
In addition, the attributes specified in value attribute is
specified.
The level, count and from
attributes. Where level is single or any, this
sequence will either be empty or contain a single number; where level is
multiple, the sequence may be of any length. The sequence is
constructed as follows:
Let matches-count($node) be a function that returns true if and only if
the given node $node matches the pattern given in the count
attribute, or the implied pattern (according to the rules given above) if the
count attribute is omitted.
Let matches-from($node) be a function that returns true if and only if
the given node $node matches the pattern given in the from
attribute, or if $node is the root node of a tree. If the
from attribute is omitted, then the function returns true if and only
if $node is the root node of a tree.
Let $S be the selected node.
When level="single":
Let $A be the node sequence selected by the following
expression:
$S/ancestor-or-self::node()[matches-count(.)][1]
(this selects the innermost ancestor-or-self node that matches the
count pattern)
Let $F be the node sequence selected by the expression:
$S/ancestor-or-self::node()[matches-from(.)][1]
(this selects the innermost ancestor-or-self node that matches the
from pattern)
Let $AF be the value of:
$A[ancestor-or-self::node()[. is $F]]
(this selects $A if it is in the subtree rooted at $F, or the empty sequence otherwise)
If $AF is empty, return the empty sequence, ()
Otherwise return the value of:
1 + count($AF/preceding-sibling::node()[matches-count(.)])
(the number of preceding siblings of the counted node that match the
count pattern, plus one).
When level="multiple":
Let $A be the node sequence selected by the expression:
$S/ancestor-or-self::node()[matches-count(.)]
(the set of ancestor-or-self nodes that match the count
pattern)
Let $F be the node sequence selected by the expression:
$S/ancestor-or-self::node()[matches-from(.)][1]
(the innermost ancestor-or-self node that matches the from
pattern)
Let $AF be the value of:
$A[ancestor-or-self::node()[. is $F]]
(the nodes selected in the first step that are in the subtree rooted at the node selected in the second step)
Return the result of the expression:
for $af in $AF return
1+count($af/preceding-sibling::node()[matches-count(.)])
(a sequence of integers containing, for each of these nodes, one plus the
number of preceding siblings that match the count pattern)
When level="any":
Let $A be the node sequence selected by the expression:
$S/(preceding::node()|ancestor-or-self::node())[matches-count(.)]
(the set of nodes consisting of the selected node together with all nodes,
other than attributes and namespaces, that precede the selected node in
document order, provided that they match the count pattern)
Let $F be the node sequence selected by the expression:
$S/(preceding::node()|ancestor-or-self::node())[matches-from(.)][last()]
(the last node in document order that matches the from pattern and
that precedes the selected node, using the same definition)
Let $AF be the node sequence $A[. is $F or . >>
$F]
(the nodes selected in the first step, excluding those that precede the node selected in the second step)
If $AF is empty, return the empty sequence, ()
Otherwise return the value of the expression count($AF)
The resulting sequence of numbers is referred to as the
If the start-at attribute is present, then the
The sequence of numbers is then converted into a string using the
The following will number the items in an ordered list:
The following two rules will number title elements. This is intended
for a document that contains a sequence of chapters followed by a sequence of
appendices, where both chapters and appendices contain sections, which in turn
contain subsections. Chapters are numbered 1, 2, 3; appendices are numbered A, B,
C; sections in chapters are numbered 1.1, 1.2, 1.3; sections in appendices are
numbered A.1, A.2, A.3. Subsections within a chapter are numbered 1.1.1, 1.1.2,
1.1.3; subsections within an appendix are numbered A.1.1, A.1.2, A.1.3.
This example numbers notes sequentially within a chapter, starting from the number 100: :
This specification is aligned with that of the
The following attributes are used to control conversion of a sequence of numbers into a string. The numbers are integers greater than or equal to 0 (zero). The attributes are all optional.
The main attribute is format. The default value for the
format attribute is 1. The format attribute
is split into a sequence of tokens where each token is a maximal sequence of
alphanumeric characters or a maximal sequence of non-alphanumeric characters.
Each non-alphanumeric token is either a prefix, a separator, or a suffix. If there is
a non-alphanumeric token but no format token, then the single non-alphanumeric token
is used as both the prefix and the suffix. The prefix, if it exists, is the
non-alphanumeric token that precedes the first format token: the prefix always
appears exactly once in the constructed string, at the start. The suffix, if it
exists, is the non-alphanumeric token that follows the last format token: the suffix
always appears exactly once in the constructed string, at the end. All other
non-alphanumeric tokens (those that occur between two format tokens) are
The nth format token is used to format the nth number in the
sequence. If there are more numbers than format tokens, then the last format token is
used to format remaining numbers. If there are no format tokens, then a format token
of 1 is used to format all numbers. Each number after the first is
separated from the preceding number by the separator token preceding the format token
used to format that number, or, if that is the first format token, then by
. (dot).
Given the sequence of numbers 5, 13, 7 and the format token
A-001(i), the output will be the string E-013(vii)
Format tokens are interpreted as follows:
Any token where the last character has a decimal digit value of 1 (as specified
in the Unicode character property database, see 1 generates the sequence
0 1 2 ... 10 11 12 ..., and a format token 01
generates the sequence 00 01 02 ... 09 10 11 12 ... 99 100 101. A
format token of ١ then ٢ then
٣ ...
A format token A generates the sequence A B C ... Z AA AB
AC....
A format token a generates the sequence a b c ... z aa ab
ac....
A format token i generates the sequence i ii iii iv v vi vii
viii ix x ....
A format token I generates the sequence I II III IV V VI VII
VIII IX X ....
A format token w generates numbers written as lower-case words,
for example in English, one two three four ....
A format token W generates numbers written as upper-case words,
for example in English, ONE TWO THREE FOUR ....
A format token Ww generates numbers written as title-case words,
for example in English, One Two Three Four ....
Any other format token indicates a numbering sequence in which that token
represents the number 1 (one) (but see the note below).
It is 1.
In some traditional numbering sequences additional signs are added to denote
that the letters should be interpreted as numbers; these are not included in
the format token. An example, see also the example below, is classical Greek
where a
ordinal attribute recognized for any given
language.For all format tokens other than the first kind above (one that consists of decimal
digits), there 1. The numbering sequence associated
with the format token 1 has a lower bound of 0 (zero).
The above expansions of numbering sequences for format tokens such as a
and i are indicative but not prescriptive. There are various conventions
in use for how alphabetic sequences continue when the alphabet is exhausted, and
differing conventions for how roman numerals are written (for example,
IV versus IIII as the representation of the number 4).
Sometimes alphabetic sequences are used that omit letters such as i and
o. This specification does not prescribe the detail of any sequence
other than those sequences consisting entirely of decimal digits.
Many numbering sequences are language-sensitive. This applies especially to the
sequence selected by the tokens w, W and Ww.
It also applies to other sequences, for example different languages using the
Cyrillic alphabet use different sequences of characters, each starting with the
letter #x410 (Cyrillic capital letter A). In such cases, the lang
attribute specifies which language’s conventions are to be used; its xs:language, or a zero-length string. If no
lang value is specified, or if the
value is a zero-length string, the language that is used is lang attribute were omitted.
The optional ordinal attribute is used to
indicate whether cardinal or ordinal numbers are required, and to select other
options relating to the grammatical context of the number to be formatted. The
allowed set of values is no or
0 or false, then cardinal numbers appropriate to the
selected language are output. If the value is yes or 1 or
true, then ordinal numbers appropriate to the target language are
output. Other values are
For example, in English, the value ordinal="yes" when used with the
format token 1 outputs the sequence 1st 2nd 3rd 4th ...,
and when used with the format token w outputs the sequence first
second third fourth ....
In some languages, the form of numbers (especially ordinal numbers) varies
depending on the grammatical context: they may have different genders and may
decline with the noun that they qualify. In such cases the value of the
ordinal attribute may be used to indicate the variation of the
cardinal or ordinal number required, in an
The way in which the variation is indicated will depend on the conventions of the language.
For inflected languages that vary the ending of the word, the approach recommended
in the previous version of this specification was to indicate the required ending,
preceded by a hyphen: for example in German, appropriate values might be
ordinal="-e", ordinal="-er",
ordinal="-es", ordinal="-en".
Another approach, which might usefully be adopted by an implementation based on
the open-source ICU localization library ordinal="%spellout-ordinal-masculine", or
ordinal="%spellout-cardinal-year". (The attribute name
ordinal in this case is a misnomer, but serves the purpose.)
The specification format="1" ordinal="-º" lang="it", if supported,
should produce the sequence:
The specification format="Ww" ordinal="-o" lang="it", if supported,
should produce the sequence:
The letter-value attribute disambiguates between numbering sequences
that use letters. In many languages there are two commonly used numbering sequences
that use letters. One numbering sequence assigns numeric values to letters in
alphabetic sequence, and the other assigns numeric values to each letter in some
other manner traditional in that language. In English, these would correspond to the
numbering sequences specified by the format tokens a and i.
In some languages, the first member of each sequence is the same, and so the format
token alone would be ambiguous. A value of alphabetic specifies the
alphabetic sequence; a value of traditional specifies the other
sequence. If the letter-value attribute is not specified, then it is
Implementations may use
The grouping-separator attribute gives the separator used as a grouping
(for example, thousands) separator in decimal numbering sequences, and the optional
grouping-size specifies the size (normally 3) of the grouping. For
example, grouping-separator="," and grouping-size="3" would
produce numbers of the form 1,000,000 while
grouping-separator="." and grouping-size="2" would
produce numbers of the form 1.00.00.00. If only one of the
grouping-separator and grouping-size attributes is
specified, then it is ignored.
The grouping-separator attribute
The grouping-size attribute
xs:integer. If the resulting integer is positive then it defines the
number of digits between adjacent grouping separators; it if is zero or negative,
then no grouping separators are inserted.
These examples use non-Latin characters which might not display correctly in all browsers, depending on the system configuration.
| Description | Format Token | Sequence |
|---|---|---|
| French cardinal words |
format="Ww" lang="fr"
| Un, Deux, Trois, Quatre |
| German ordinal words |
format="w" ordinal="-e" lang="de"
| erste, zweite, dritte, vierte |
| Katakana numbering |
format="ア"
| ア, イ, ウ, エ, オ, カ, キ, ク, ケ, コ, サ, シ, ス, セ, ソ, タ, チ, ツ, テ, ト, ナ, ニ, ヌ, ネ, ノ, ハ, ヒ, フ, ヘ, ホ, マ, ミ, ム, メ, モ, ヤ, ユ, ヨ, ラ, リ, ル, レ, ロ, ワ, ヰ, ヱ, ヲ, ン |
| Katakana numbering in iroha order |
format="イ"
| イ, ロ, ハ, ニ, ホ, ヘ, ト, チ, リ, ヌ, ル, ヲ, ワ, カ, ヨ, タ, レ, ソ, ツ, ネ, ナ, ラ, ム, ウ, ヰ, ノ, オ, ク, ヤ, マ, ケ, フ, コ, エ, テ, ア, サ, キ, ユ, メ, ミ, シ, ヱ, ヒ, モ, セ, ス |
| Thai numbering |
format="๑"
| ๑, ๒, ๓, ๔, ๕, ๖, ๗, ๘, ๙, ๑๐, ๑๑, ๑๒, ๑๓, ๑๔, ๑๕, ๑๖, ๑๗, ๑๘, ๑๙, ๒๐ |
| Traditional Hebrew numbering |
format="א" letter-value="traditional"
| א, ב, ג, ד, ה, ו, ז, ח, ט, י, יא, יב, יג, יד, טו, טז, יז, יח, יט, כ |
| Traditional Georgian numbering |
format="ა" letter-value="traditional"
| ა, ბ, გ, დ, ე, ვ, ზ, ჱ, თ, ი, ია, იბ, იგ, იდ, იე, ივ, იზ, იჱ, ით, კ |
| Classical Greek numbering (see note) |
format="α" letter-value="traditional"
| |
| Old Slavic numbering |
format="а" letter-value="traditional"
| А, В, Г, Д, Е, Ѕ, З, И, Ѳ, Ӏ, АӀ, ВӀ, ГӀ, ДӀ, ЕӀ, ЅӀ, ЗӀ, ИӀ, ѲӀ, К |
Note that Classical Greek is an example where the format token is not the same as the representation of the number 1.
A sort key specification may occur immediately within an
When used within
The
The value of a select attribute or by the contained select=".", which has the effect of sorting on
the actual value of the item if it is an atomic item, or on the typed-value of the
item if it is a node. If a select attribute is present, its value
It is a select attribute has
non-empty content.
Those attributes of the select attribute of the containing instruction
(specifically,
The stable attribute is permitted only on the first
It is a stable
attribute.
stable attribute, or has
a stable attribute whose yes.
The items in the order
attribute of this descending, in which case
B will precede A in the sorted sequence. If, however, the
relevant sort key values compare equal, then the second sort key value of
A is compared with the second sort key value of B,
according to the rules of the second
If two items have equal order="descending" was specified on any or all of the
The Nth sort key value is computed by evaluating either the
select attribute or the contained . (dot) if neither is present. This evaluation is done with the
The
The
The
As in any other XPath expression, the select expression of
The
xs:decimal are compared
as decimals, without first converting to xs:double.
It is possible to force the system to compare <xsl:sort
select="xs:date(@dob)"/> will force the attributes to be compared as
dates. In the absence of such a cast, the sort key values are compared using the
rules appropriate to their datatype. Any values of type
xs:untypedAtomic are cast to xs:string.
For backwards compatibility with XSLT 1.0, the data-type attribute
remains available. If this has the text, the atomized number, the atomized sort key values are converted to
doubles before being compared. The conversion is done by using the
data-type attribute has
any other
data-type attribute of
the text or
number, the effect is implementation-defined.
If the data-type
attribute, is a sequence containing more than one item, then the effective
sort key value is the first item in the sequence.
In general the
If both S1 and S2 are empty sequences, then they compare equal.
A sequence that is empty is considered to be less than a sequence that is not empty.
If neither sequence is empty, then
head(S1) and
head(S2) are compared
according to the rules below.
If they compare equal, the result is obtained
by comparing tail(S1) to
tail(S2).
Otherwise, the result of comparing these two items is used as the result of the sequence comparison.
For example:
(1, 2, 3) precedes (1, 2, 4).
(1, 2) precedes (1, 2, 3)
() precedes (1, 2)
Individual atomic items are compared by calling the function
fn:compare(A1, A2, C),
where C is the appropriate collation,
as described in the next section.
This will raise an error if the values are
not comparable (for example, if one is an xs:integer and the other is
an xs:date).
It is a
The above error condition may occur if the sequence is heterogeneous (for example, if it contains both strings and numbers). The error can generally be prevented by invoking a cast or constructor function within the sort key component.
The error condition is subject to the usual caveat that a processor is not required to evaluate any expression solely in order to determine whether it raises an error. For example, if there are several sort key components, then a processor is not required to evaluate or compare minor sort key values unless the corresponding major sort key values are equal.
In XSLT 4.0 the error can no longer occur if the items in the sequence
all have the same data type. An order relation is now defined for all
atomic types (including, for example, xs:duration).
The rules given in this section apply when comparing values whose type is
xs:string or a type derived by restriction from
xs:string, or whose type is xs:anyURI or a type
derived by restriction from xs:anyURI.
For more information about collations, see case-order and lang are
ignored.
Every implementation http://www.w3.org/2005/xpath-functions/collation/codepoint, which
provides the ability to compare strings based on the Unicode codepoint values of
the characters in the string.
Furthermore, every implementation must recognize collation URIs
representing tailorings of the Unicode Collation Algorithm (UCA), as described in
If the collation attribute,
then the strings are compared according to the rules for the named compare($a, $b, $collation).
If the collation attribute of
It is a collation attribute of
It is entirely for the implementation to determine whether it recognizes a particular collation URI. For example, if the implementation allows collation URIs to contain parameters in the query part of the URI, it is the implementation that determines whether a URI containing an unknown or invalid parameter is or is not a recognized collation URI. The fact that this situation is described as an error thus does not prevent an implementation applying a fallback collation if it chooses to do so.
The lang and case-order attributes are ignored if a
collation attribute is present. But in the absence of a
collation attribute, these attributes provide input to an
lang and case-order attributes, is
implementation-defined.The lang attribute indicates that a collation suitable for a
particular natural language xs:language, or a zero-length string. Supplying the
zero-length string has the same effect as omitting the attribute. If a
language is requested that is not supported, the processor
lang attribute were omitted.
The fallback algorithm described above is
identical to the rules in RFC4647 Basic Filtering used in BCP 47,
and is specified in
The case-order attribute indicates whether the desired
collation lower-first (indicating that lower-case letters precede
upper-case letters in the collating sequence) or upper-first
(indicating that upper-case letters precede lower-case).
When lower-first is requested, the returned collation
So, for example, if lang="en", then A a B b are
sorted with case-order="upper-first" and a A b B
are sorted with case-order="lower-first".
As a further example, if lower-first is requested, then a sorted sequence
might be “MacAndrew, macintosh, macIntosh, Macintosh, MacIntosh,
macintoshes, Macintoshes, McIntosh”. If upper-first is requested, the same
sequence would sort as “MacAndrew, MacIntosh, Macintosh, macIntosh,
macintosh, MacIntoshes, macintoshes, McIntosh”.
If none of the collation, lang, or
case-order attributes is present, the collation is chosen in an
collation, lang, or case-order
attributes is present (on It is usually appropriate, when sorting, to use a strong collation, that is, one that takes account of secondary differences (accents) and tertiary differences (case) between strings that are otherwise equal. A weak collation, which ignores such differences, may be more suitable when comparing strings for equality.
Useful background information on international sorting is provided in case-order attribute may be
interpreted as described in section 6.6 of
The collation, case-order, and lang attributes are
ignored when no string comparisons are performed during the sorting process; this
includes the cases where (a) the sequences to be sorted are empty, (b) the sort
keys are of a non-string type such as xs:integer, or (c) data-type="number" is
specified. In these cases, an implementation may raise errors in the value
of these attributes, but is not required to do so. As always, an implementation
may issue warnings.
The
The select attribute or by evaluating the contained
sequence constructor (but not both). If there is no select attribute and
no sequence constructor then the
It is a select
attribute has any content other than
The result of the
The following stylesheet function sorts a sequence of atomic items using the value itself as the sort key.
The following example defines a function that sorts books by price, and uses this function to output the five books that have the lowest prices:
When used within
For example, suppose an employee database has the form
Then a list of employees sorted by name could be generated using:
When used within
xsl:for-each-group/@split-when is available to
give applications more complete control over how a sequence is partitioned
xsl:for-each-group/@merge-when is available to
give applications control to create groups based on clustering, overlap, and networks.
The facilities described in this section are designed to allow items in a sequence to be
grouped based on common values; for example it allows grouping of elements having the
same value for a particular attribute, or elements with the same name, or elements with
common values for any other
Simple elimination of duplicates can also be achieved using the function
In addition these facilities allow grouping based on sequential position, for example
selecting groups of adjacent para elements. The facilities also provide an
easy way to do fixed-size grouping, for example identifying groups of three adjacent
nodes, which is useful when arranging data in multiple columns.
For each group of items identified, it is possible to evaluate a
It is also possible for one item to participate in more than one group.
Grouping can also be achieved by constructing a map. For example,
the function call map:build(//employee, fn { department }) constructs a map
in which employees are grouped by department.
xsl:for-each-group ElementThe
The select attribute contains an
select attribute.
A group is never empty. If the population is empty, the number of groups will be zero.
The assignment of items to groups depends on the group-by,
group-adjacent, group-starting-with,
group-ending-with, split-when,merge-when
These group-by,
group-adjacent, group-starting-with,
group-ending-with,
split-when,merge-when
It is a collation attribute or the
composite attribute if neither the
group-by attribute nor the group-adjacent attribute is
specified.
group-by or group-adjacent attributes is present,
then for each item in the group-by or group-adjacent attribute is
evaluated; the result is atomized; and any xs:untypedAtomic items
are cast to xs:string. If
composite="yes" is specified, there is a single grouping key
whose value is the resulting sequence; otherwise, there is a set of grouping
keys, consisting of the distinct atomic items present in the result
sequence.
When calculating grouping keys for an item in the population, the
group-by
or group-adjacent attribute is evaluated with that
item as the
If the group-by attribute is present, and if
the composite attribute is omitted or takes the value
no, then an item in the population group-by expression evaluates
to a sequence, and each item in the sequence is treated as
a separate grouping key. The item is included in as many groups as there
are distinct grouping keys (which may be zero).
If the group-adjacent attribute is used, and
if the composite attribute is omitted or takes the value
no, then each item in the population
It is a group-adjacent expression is the empty sequence or a
sequence containing more than one item, unless
composite="yes" is specified.
Atomic collation
attribute, resolved if relative against the base URI of the
collation
attribute then the count(distinct-values(($K1, $K2), $collation)) = 1.
Composite grouping keys are equal if they contain the same number of items and the items are pairwise equal when compared according to the rules in the previous paragraph.
It is a
For more information on collations, see
The way in which an
If the group-by attribute is present, the items in the group-by
attribute is evaluated to produce a sequence of zero or more composite="yes" is specified, there will be a single
grouping key, which will in general be a sequence of zero or more atomic
items; otherwise, there will be zero or more grouping keys, each of which
will be a single atomic item. For each one of these
An item in the population may thus be appended to zero, one, or many groups. An item will never be
appended more than once to the same
group; if two or more grouping keys for the same item are equal, then the
duplicates are ignored. An
The number of groups will be the same as the number of distinct grouping key
values present in the
If the population contains values of different numeric types that differ from
each other by small amounts, then the eq operator is not
transitive, because of rounding effects occurring during type promotion. The
effect of this is described in
If the group-adjacent attribute is present, the items in the
If the group-starting-with attribute is present, then its value
The items in the
If the group-ending-with attribute is present, then its value
The items in the
If the split-when attribute is present, then its value
$group is set to the
contents of the current group being constructed, and $next is the next item in the population.
If the true, then this
item forms the start of a new group; if it is false, the item is added to the existing
group.
The variable $group is implicitly declared, and split-when
expression, and its type is item()+.
The variable $next is implicitly declared, and split-when
expression, and its type is item().
For example:
split-when="count($group) = 3" starts a new
group whenever the existing group has exactly three members; that is, it partitions the
population into groups of size 3 (with the last group being smaller if necessary).
split-when="$next[self::h1]" starts a new
group whenever an h1 element is encountered. The effect is the
same as specifying group-starting-with="h1"
split-when="foot($group)/@continued='no'" starts a new
group immediately after any element having @continued="no". The effect is the
same as specifying group-ending-with="*[@continued='no']"
split-when="node-name($group[last()] != node-name($next)"
starts a new group whenever the name of an item differs from the name of the previous
item. The effect is the same as specifying group-adjacent="node-name(.)".
split-when="foot($group)[self::hr] or $next[self::hr]"
starts a new group immediately before and immediately after every hr
element. (That is, hr elements become singleton groups.)
split-when="$next ne foot($group) + 1"
starts a new group whenever the current item is not equal to the previous item
plus one. For example 1, 2, 5, 6, 7, 10, 11 is grouped as (1, 2), (5, 6, 7),
(10, 11).
split-when="sum($group/string-length()) gt 40" starts a new
group when the sum of the string lengths of the items in the current group exceeds 40.
split-when="ends-with(foot($group), '.') and matches($next, '^\p{Lu}')"
starts a new group when the last item in the current group ends with "." and the
next item starts with a capital letter.
split-when="deep-equal(slice($group, -2 to -1), ('', ''))"
starts a new group after two consecutive zero-length strings.
split-when="count($group) gt 1 and head($group)/@name = foot($group)/@name"
starts a new group if the last item in the current group has the same value for @name
as the first item in that group (provided they are not the same item).
If the merge-when attribute is present, then its value
The sequence comparator is
supplied with two variables: $group-a and $group-b.
Each of these variables is implicitly declared, and merge-when
expression, and its type is item()+.
The sequence comparator is evaluated not item by item (as with
split-when) but group by group. The context item is $group-a) within the sequence of groups being
constructed, and the context size is the number of groups at the moment of
evaluation.
The process begins by creating singleton groups. For each item in the
After the groups are created, they are evaluated pairwise against the
$group-a is set to the items in the first group in a pair of
groups, G1, and $group-b to the second group,
G2.
If the true, then all items in G2
are merged with the items in G1, preserving original sequence order,
and the grouping keys of G2 are merged with those of G1,
sorted in ascending order. The process of merging two groups is identical to
the process described in
The process is repeated until it is the case that there is no pair of groups
for which the true, or there is only one
group.
Every item in the population will be appended to exactly one group.
Unlike other grouping methods, a group created by merge-when may
have more than one grouping key. Although those grouping keys are not
significant for the semantics of the grouping operation, they can be used to
examine the original population, and they are useful for the merge
operation.
merge-when is most effective for building clusters or
networks. For example:
merge-when="$group-a/(@id | is-related-to) = $group-b/(@id |
is-related-to)" creates groups of elements. In a group with
more than one item, each item has at least one other item that it relates
to, or that relates to the same item it relates to. That is, each group
represents a kind of network cluster.
Suppose we have elements containing text units where word tokens of
significance are wrapped in children tok elements.
merge-when="every $a in $group-a, $b in $group-b satisfies
count($a/tok[. = $b/tok]) ge 3" creates groups of possibly
related texts. In groups of more than one item, any pair of texts has
at least three common word-tokens.
merge-when="some $a in $group-a, $b in $group-b satisfies
count($a/tok[. = $b/tok]) ge 3" creates groups of related
texts, likely less cohesive than in the previous example. In groups of
more than one item, every text has at least one other text with which it
has three word-tokens in common.
merge-when="not($group-a = $group-b)" creates maximal groups
of distinct values. For example, 4, 1, 5, 1, 9, 4, 1 is
grouped as 4, 1, 5, 9 (with grouping keys 1, 2, 3,
5), 1, 4 (with grouping keys 4, 6),
and 1 (with grouping key 7). Note, the first
group is always the result of the
In merge-when="count($group-a) le 3 and
count(distinct-values(($group-a, $group-b) ! node-name(.))) eq 1" no
group has more than three items. Within each group, every item has the
same node name. The effect is the same as specifying
group-by="node-name(.)" then subgrouping with
split-when="count($group) = 3".
merge-when="some $a in $group-a, $b in $group-b satisfies
tokenize($a/@class) = tokenize($b/@class)" creates groups of
elements. In a group with multiple items, every item has at least one
other item that has at least one of its tokens in @class.
merge-when="some $a in $group-a, $b in $group-b satisfies abs($a -
$b) le 2" creates groups of numerals. Each numeral has at least
one other numeral where the two differ by two or less. For example,
3, 9, 4, 1, 10, 6 is grouped as (3, 4, 1, 6)
(with grouping keys 1, 3, 4, 6) and (9, 10) (with
grouping keys 2, 5).
merge-when="some $a in $group-a, $b in $group-b satisfies abs($a -
$b) le xs:dayTimeDuration('PT2H')" creates groups of time
values. Within groups of more than one item, each time value has at least
one other time value that is two hours or less apart. For example,
xs:time("11:12:00Z"), xs:time("13:24:55Z"),
xs:time("09:44:10Z"), xs:time("14:09:22Z"),
xs:time("08:16:30Z") is grouped as (xs:time("11:12:00Z"),
xs:time("09:44:10Z"), xs:time("08:16:30Z")) (with grouping keys
1, 3, 5) and (xs:time("13:24:55Z"),
xs:time("14:09:22Z")) (with grouping keys 2,
4).
merge-when="every $a in $group-a, $b in $group-b satisfies
(string-to-codepoints($a) = string-to-codepoints($b))" creates
groups of strings. In groups with more than one member, each member
shares at least one codepoint with every other member. For example,
("animal", "bison", "cat", "dog", "zebra") is grouped as
("animal", "bison", "zebra") (linking letters are a, i,
n, and b), ("cat") (although it shares letter a with
"animal," the group has already been merged with "bison," which has no
common letter with "cat"), and ("dog"). The grouping keys
are 1, 2, 5, 3, and 4,
respectively.
In all cases the order of items within each group is predictable,
and reflects the original
As always, a different algorithm may be used if it achieves the same effect.
The position() takes successive values 1, 2, ... last().
Two pieces of information are available during the processing of each group (that is,
while evaluating the sequence constructor contained in the
select attribute or sequence
constructor of an
Information about the
In XSLT 2.0, the
current-group#0 retains the value of the current
group within its captured context.Returns the group currently being processed by an
This function is
The evaluation context for XPath
The function
The current group is bound during evaluation of the
The effect of
If the streamable="yes",
or within a streamable template), then the
invocation construct sets the current group to
If the
Otherwise the
The current group is initially use attribute or contained sequence constructor of initial-value attribute of select attribute of contained sequence constructor of
It is a
It is a
current-grouping-key#0 retains the value of the current
grouping key within its captured context.Returns the grouping key of the group currently being processed using the
This function is
The evaluation context for XPath
The function
The current grouping key is bound during evaluation of an
group-by,
group-adjacent, or merge-when attribute. If group-starting-with, group-ending-with,
or split-when attribute
The effect of
If the streamable="yes",
or within a streamable template), then the
invocation construct sets the current grouping key to
If the
Otherwise the
The current grouping key is initially use attribute or contained sequence constructor of initial-value attribute of select attribute of contained sequence constructor of
While an group-by or
group-adjacent attribute is being evaluated, the
composite="no" is specified (explicitly
or implicitly), or a sequence of atomic items if composite="yes" is
specified.
While an merge-when
attribute is being evaluated, the
At other times, the current grouping key will be
The xs:float while another is a numerically equal
xs:decimal. The xs:untypedAtomic items to xs:string.
The function takes no arguments.
It is a
It is a
group-by expression of this initial item.
If there are no
Otherwise, the
The select
group-starting-with, group-ending-withsplit-when
For example, this means that if the @category, you can sort the groups in order of
their grouping key by writing <xsl:sort
select="current-grouping-key()"/>; or you can sort the groups in
order of size by writing <xsl:sort
select="count(current-group())"/>
The following example groups a list of nodes based on common values. The resulting groups are numbered and sorted, and a total is calculated for each group.
Source XML document:
More specifically, the aim is to produce a four-column table, containing one row
for each distinct country. The four columns are to contain first, a sequence
number giving the number of the row; second, the name of the country, third, a
comma-separated alphabetical list of the city names within that country, and
fourth, the sum of the pop attribute for the cities in that
country.
Desired output:
Solution:
Sometimes it is necessary to use a composite grouping key: for example, suppose the source document is similar to the one used in the previous examples, but allows multiple entries for the same country and city, such as:
Now suppose we want to list the average value of @pop for each
(country, name) combination. One way to handle this is to concatenate the parts of
the key, for example <xsl:for-each-group select="concat(@country, '/',
@name)">. A second solution is to nest one
The next example identifies a group not by the presence of a common value, but
rather by adjacency in document order. A group consists of an h2
element, followed by all the p elements up to the next
h2 element.
Source XML document:
Desired output:
Solution:
The use of title="{self::h2}" rather than title="{.}" is
to handle the case where the first element is not an h2 element.
The next example illustrates how a group of related elements can be identified by
the last element in the group, rather than the first. Here the absence of the
attribute continued="yes" indicates the end of the group.
Source XML document:
Desired output:
Solution:
The next example shows how an item can be added to multiple groups. Book titles will be added to one group for each indexing term marked up within the title.
Source XML document:
Desired output:
Solution:
In this example, the membership of a node within a group is based both on
adjacency of the nodes in document order, and on common values. In this case, the
grouping key is a boolean condition, true or false, so the effect is that a
grouping establishes a maximal sequence of nodes for which the condition is true,
followed by a maximal sequence for which it is false, and so on.
Source XML document:
Desired output:
Solution:
This requires creating a p element around the maximal sequence of
sibling nodes that does not include a ul or ol
element.
This can be done by using group-adjacent, with a grouping key that is
true if the element is a ul or ol element, and false
otherwise:
Consider a map with composite keys that might appear in a JSON document as:
And suppose we wish to group this into a two-level map, thus:
This can be achieved as follows:
Consider a sequence of atomic items that we wish to group according to cluster. For the sake of illustration we restrict ourselves to integers. For each integer, the group it is in should include every other integer of proximate distance two or less.
We want to return the following four groups:
Solution:
The next example shows how the component parts of multiple versions of a text can be collated when they refer to overlapping reference systems. Suppose we have a text, with various commentaries and glosses, and we wish to collate them by text cluster, for online presentation.
We wish to collate text portions, and display the grouped clusters in an HTML fragment:
In this solution, we bind all the texts to a variable, $versions,
and we pass a template copy of the desired HTML output through a designated XSLT mode.
At the appropriate place, we collate the versions by using group-by-cluster:
If the population contains values of different numeric types that differ from each
other by small amounts, then the eq operator is not transitive, because
of rounding effects occurring during type promotion. It is thus possible to have
three values A, B, and C among the grouping keys of
the population such that A eq B, B eq C, but A ne
C.
For example, this arises when computing
because the values of type xs:float and xs:double both
compare equal to the value of type xs:decimal but not equal to each
other.
In this situation the results
For each item J in the
If there is exactly one group G, then J is added to this group, unless J is already a member of this group.
If there is no group G, then a new group is created with J as its first item.
If there is more than one group G (which can only happen in exceptional circumstances involving non-transitivity), then one of these groups is selected in an implementation-dependent way, and J is added to this group, unless J is already a member of this group.
The effect of these rules is that (a) every item in a non-singleton group has a grouping key that is equal to that of at least one other item in that group, (b) for any two distinct groups, there is at least one pair of items (one from each group) whose grouping keys are not equal to each other.
The
For example, if two log files contain details of events sorted by date and time, then
the
The data written to the output sequence can be computed in an arbitrary way from the data in the input sequences, provided it follows the ordering of the input sequences.
The
The following examples illustrate some of the possibilities. The detailed explanation of the constructs used follows later in this section.
This example takes as input a homogeneous collection of XML log files each of which
contains a sorted sequence of event elements with a
timestamp attribute validated as an instance of
xs:dateTime. It merges the events from the input files into a single
sorted output file.
The example assumes that there are several input files each
of which has a structure similar to the following, in which the
timestamp attribute has a typed value that is an instance of
xs:dateTime:
The output file will have the same structure, and will contain copies of all the
event elements from all of the input files, in sorted order. Note that multiple events with the same timestamp can occur
either within a single file or across multiple files: the order of appearance of
these events in the output file corresponds to the order of the log files within
the collection (which might or might not be predictable, depending on the
implementation).
This example takes as input two log files with different structure, producing a single merged output in which the entries have a common structure:
Here the first input file has a structure similar to that shown in the previous example, while the second input has a different structure, of the form:
The templates in mode standardize-log-entry convert the log entries to a
common output format, for example:
The
date and time.
The effect of the
The input sequences to the merge operation are defined by the
The sequence constructor contained in the
The
Any
An group-adjacent
attribute, except that it requires the input to be sorted on the grouping key.
Each
The name attribute provides a means of
distinguishing items from different merge sources within the
name attribute
is present on an name attribute of any sibling name attribute is absent, then an
If the for-each-item attribute is present then the
for-each-source, use-accumulators, and streamable attributes
must all be absent. If use-accumulators or streamable attributes is present for-each-source attribute must be present. If the
for-each-source attribute is present then the
for-each-item attribute must be absent.
The use-accumulators attribute defines the
set of accumulators that are applicable to the streamed document, as explained in
If neither of
for-each-item and for-each-source is
present, the select attribute. This is evaluated using the dynamic context of the
containing
When the for-each-item
attribute is present, the for-each-item attribute of the
select
attribute is evaluated to select the items that make up one merge input sequence. The
for-each-item expression is evaluated with
the dynamic context of the containing select attribute is evaluated with the
The
The
The
When the for-each-source attribute is
present, its value must be an expression that returns a sequence of URIs.
The expression is evaluated with the same
dynamic context as the containing xs:string*, and the actual result of
the expression is converted to this type using the for-each-item attribute:
in particular, the
Examples of expressions that return a sequence of URIs are:
for-each-source="'inputA.xml', 'inputB.xml'"
for-each-source="(1 to $N) ! ('input' || $N || '.xml')"
for-each-source="uri-collection('input/dir/')
Relative URIs are resolved relative to the base URI of the
The attributes validation and
type are used to control schema validation of documents read by
virtue of their appearance in the result of the for-each-source
expression. These attributes are mutually exclusive streamable="yes". for-each-source attribute is absent, then the
validation and type attributes
If the sort-before-merge attribute is absent or has
the value no, then each merge input sequence yes, then each input sequence will
first be sorted to ensure that it is in the correct order. stable="yes" to the first such element.
The following event elements within the relevant
document.
This example can be extended to merge any number of input documents with the same structure:
In both the above examples the anchor items are document nodes, and the items in the input sequence are elements within the document that is rooted at this node. This is a common usage pattern, but by no means the only way in which the construct can be used.
The number of anchor items selected by an
The following code merges two log files having different internal structure:
Although the merge keys are computed in different ways for the two input
sequences, the keys must be compatible across the two sequences: in this case they
are both atomic items of type xs:dateTime.
In the common case where there is only one input sequence of a particular kind, the
for-each-item attribute of
select
expression is then evaluated relative to the
Where one or more of the inputs to the merging process is not pre-sorted, a sort
can be requested using the sort-before-merge attribute. For
example:
It is a
The keys on which the input sequences are sorted are referred to as merge keys. If
the attribute sort-before-merge has the value yes, the
input sequences will be sorted into the correct sequence before the merge operation
takes place (alternatively, the processor no, then the input sequences
The merge key for each type of input sequence (that is, for each
stable attribute); the
The select attribute and the contained
It is a select attribute
has non-empty content.
From XSLT 4.0, the select expression or contained sequence constructor
may evaluate (after atomization) to an arbitrary sequence of atomic items. Previously,
only a singleton atomic item or the empty sequence was allowed.
The value of Nth item in the merge key of an item
J in a
If K has a select attribute, then the result
of evaluating and atomizing that select expression;
If K contains a non-empty sequence constructor, then the result of evaluating and atomizing that sequence constructor;
Otherwise, the result of atomizing the context item.
In each case the evaluation uses a streamable="yes" is specified on the
This means that position() and last() return 1 (one).
This differs from the way position() is the position in the unsorted sequence, and
last() is the size of the unsorted sequence.
The effect of the stable="yes"
would place an item A before an item B in the
The merge keys of the various input sequences to a merge operation must be compatible
with each other, since the merge operation will decide the ordering of the result
sequence by comparing merge key values across input sequences. This means that across
all the
Each
For each integer J in 1..N, consider the set S of
lang, order, collation,
case-order, and data-type it must be the case that for
any two elements s1 and s2 in S, the
collation attribute, the absolute collation URI must be the same
after resolving against the base URI.
If any of the attributes lang, order,
collation, case-order, or data-type are
It is a
It is a lang, order,
collation, case-order, or data-type.
Values are considered to differ if collation attribute, the values are
compared as absolute URIs after resolving against the base URI. The error
It is a sort-before-merge is present
with the value yes.
It is a le operator with the corresponding item selected by the corresponding
sort key in another input sequence.
During processing of an
These values are made available through the functions
The use attribute or contained sequence constructor of
initial-value attribute of
select attribute of contained sequence constructor of
Taken together, these rules mean that any invocation of
When an inner select attribute of an
On completion of the evaluation of the
current-merge-group retains the value of the current
merge-key within its captured context.Returns the group of items currently being processed by an
This function is
The
The name attribute of the
corresponding
The map itself is not made visible, but this function returns values derived from the map. Specifically, if the map is denoted by $G:
$source is supplied
and is non-empty, theif (map:contains($source)) then $G($source) else error().
Informally, if there is an name attribute matches $source, the function returns
the items in the current merge group that are contributed by this merge source;
otherwise it raises a dynamic error (see below).
$source is absent or empty)sort(map:keys($G))!$G(.), where the sort() function
sorts the names of
Within the
Items are first ordered by the
Items from different input sequences selected by the same
select
attribute of the
Finally, duplicate items from the same input sequence retain their order from the input sequence.
Duplicates are not eliminated: for example, if the same node is selected in more than one input sequence, it may appear twice in the current merge group.
It is a
It is a
It is a $source argument of the name attribute of any
Because the
If an name attribute, then
it is not possible to discover the items in the current merge group that derive
specifically from that source, but these items will still be present in the current
merge group, and will be included in the result when the function is called with no
arguments.
Returns the merge key of the
merge group currently being processed using the
This function is
The evaluation context for XPath
The function
While the select expression, or the contained sequence constructor,
or the context item, as appropriate.
At other times, the current merge key will be
The xs:float while another is a numerically equal
xs:decimal. The xs:untypedAtomic items to xs:string.
It is a
It is a
current-merge-key#0 retains the value of the current
group within its captured context.Returns the merge key of the
merge group currently being processed using the
This function is
The function returns the result of the expression
current-merge-key-array()?*, that is, the result
of flattening the contents of the current merge key into
a sequence of atomic items.
The same error conditions apply as for the
This function is retained from XSLT 3.0 both for backwards compatibility,
and for convenience. It is useful in the common case where there is a single
merge key whose value is a single atomic item; it is also usable if there
are multiple merge keys whose values are single atomic items. In the general
case where there are multiple merge keys each of which may contain zero or more
atomic items, the function
The
The merge key values for each item in an input sequence are calculated based on the
corresponding
The groups are processed one by one, based on the values of
the merge keys for the group. If group G has a set of merge
key values M, while group H has a set of merge key values
N, then in the result of the lang, order, collation,
case-order, and data-type attributes of the merge key
definitions.
NaNeq operator, under the collating rules for the corresponding merge
key definition. In rare cases, when considering more than two sets of merge key
values, ambiguities may arise because of the non-transitivity of the eq
operator when applied across different numeric types. In this situation, the
partitioning of items into sets having distinct key values is handled in the same way
as for
The
The current-merge-group()[1]
The position()=1,
the second has position()=2, and so on).
The
If any of the streamable="yes" (explicitly or implicitly), then absent.
This means that within the last() raises error
Otherwise, the number of groups, that is, the number of distinct sets of merge key values.
Consider a situation where there are two merge sources, named "master" and
"update"; the master source identifies a single merge input file (the master
file), while the update source identifies a set of N update files,
perhaps one for each day of the week. The required logic is that if a merge key is
present only in the master file, then the corresponding item should be copied to
the output; if it is present in a single update file then that item replaces the
corresponding item from the master file; if it is present in several update files,
then an error is raised. This can be achieved as follows:
Some words of explanation:
Error messages are produced if there is an update element whose key does not correspond to any element in the master source, or if there is more than one update element corresponding to the same master element.
In the absence of errors, if there is a single update element then it is copied to the output; if there is none, then the master element is copied.
Previous sections introduced examples designed to illustrate some specific features
of the
This example applies transactions from a transaction file to a master file. Records in the master file for which there is no corresponding transaction are copied unchanged. The transaction file contains instructions to delete, replace, or insert records identified by an ID value. The master file is known to be sorted on the ID value; the transaction file is unsorted.
Master file document structure:
Transaction file document structure:
Solution:
The
While this gives the intersection:
Sometimes it is convenient to be able to compute multiple results during a single scan of the input data. For example, a transformation may wish to rename selected elements, and also to output a count of how many elements have been renamed. Traditionally in a functional language this means computing two separate functions of the input sequence, which (in the absence of sophisticated optimization) will result in the input being scanned twice. This is inconsistent with streaming, where the input is only available to be scanned once, and it can also lead to poor performance in non-streaming applications.
To meet this requirement, XSLT 3.0 introduces the instruction
The semantics of the instruction require a number of result sequences to be computed during a single pass of the input. A processor may interpret this as a request to use multiple threads. However, implementations using a single thread are feasible, and this instruction is not intended primarily as a means for stylesheet authors to express their intentions with regard to multi-threaded execution.
Because multiple results are computed during a single pass of the input, and then concatenated into a single sequence, this instruction will generally involve some buffering of results. The amount of memory used should not exceed that needed to hold the results of the instruction. However, within this principle, implementations may adopt a variety of strategies for evaluation; for example, there may be cases where buffering of the input is more efficient than buffering of output.
Generally, stylesheet authors indicate that buffering of input is the preferred
strategy by using the
The content model of the
A sequence of
A single group-by attribute, because in all other cases the containing
The first form is appropriate when splitting a single input stream into a fixed number of output streams, known statically: for example, one output stream for credit transactions, a second for debit transactions. The second form is appropriate when the number of output streams depends on the data: for example, one output stream for each distinct city name found in the input data.
The following section describes the
xsl:fork InstructionThe content model can be described as follows: there is either a single
The result of the
Any
By using the
The presence of an
This section gives examples of how splitting using
Consider a transaction file that contains a sequence of debits and credits:
where the requirement is to split this into two separate files containing credits and debits respectively.
This can be achieved in
In the absence of the
One possible implementation model for this is as follows: a single thread reads
the source document, and sends parsing events such as start-element and
end-element to two other threads, each of which is writing one of the two result
documents. Each of these implements the downwards-selecting path expression using
a process that waits until the next transaction start-element event
is received; when this event is received, the process examines the
@value attribute to determine whether or not this transaction is
to be copied; if it is, then all events until the matching
transaction end-element event are copied to the serializer for the
result document; otherwise, these events are discarded.
Consider a transaction file that contains a sequence of debits and credits:
where the requirement is to split this into a number of separate files, one for each account number found in the input.
This can be achieved in
In the absence of the group-by attribute
needs to be buffered. (The streamability rules do not recognize an
One possible implementation model for this is as follows: the processor opens a
new serializer each time a new account number is encountered in the input, and
writes the <transactions> start tag to the serializer. When a
transaction element is encountered in the input, it is copied to
the relevant serializer, according to the value of the account
attribute. At the end of the input, a <transactions> end tag is
written to each of the serializers, and each output file is closed.
In the more general case, where the body of the
The rules for streamability do not allow two instructions in a sequence
constructor to both read child or descendant elements of the context node, which
makes it tricky to perform a calculation in which multiple child elements act as
operands. This restriction can be avoided by using
A possible implementation strategy here is for events from the XML parser to be
sent to two separate agents (perhaps but not necessarily running in different
threads), one of which computes xs:decimal(price) and the other
xs:decimal(discount); on completion the results computed by the
two agents are appended to the sequence that forms the value of the variable.
With this strategy, the processor would require sufficient memory to hold the results of evaluating each branch of the fork. If these results (unlike this example) are large, this could defeat the purpose of streaming by requiring large amounts of memory; nevertheless, this code is treated as streamable.
An alternative solution to this requirement is to use map constructors: see
In this example the input is a narrative document containing note
elements at any level of nesting. The requirement is to output a copy of the input
document in which (a) the note elements have been removed, and (b) a
footnote is added at the end indicating how many note
elements have been deleted.
The note elements to be copied to the result; the second instruction
(the literal result element footnote) outputs a count of the number
of descendant note elements.
Note that although the processing makes a single pass over the input stream, there
is some buffering of results required, because the results of the instructions
within the
In a formal sense, however, the result is exactly the same as if the
An alternative way of solving this example problem would be to
count the number of note elements using an accumulator: see
The function library for XPath 3.0 defines several functions that make use of regular expressions:
These functions are described in
Supplementing these functions, XSLT provides
an instruction
The
The regular expressions used by this instruction, and the flags that control the
interpretation of these regular expressions,
As described in
xsl:analyze-string Instructionselect attribute
in place of a contained sequence constructor.
The select attribute), a
regular expression (the regex attribute),
and a set of flags.
If the result of evaluating the select expression is the empty sequence,
it is treated as a zero-length string.
If the value is not a string, it is converted to a string by applying the
The flags attribute may be used to control the interpretation of the
regular expression. If the attribute is omitted, the effect is the same as supplying
a zero-length string. This is interpreted in the same way as the $flags
attribute of the functions m, the match operates in multiline mode. If it
contains the letter s, it operates in dot-all mode. If it contains the
letter i, it operates in case-insensitive mode. If it contains the
letter x, then whitespace within the regular expression is ignored. For
more detailed specifications of these modes, see
Because the regex attribute is an attribute value template, curly
brackets within the regular expression must be doubled. For example, to match a
sequence of one to five characters, write regex=".{{1,5}}". For
regular expressions containing many curly brackets it may be more convenient to
use a notation such as regex="{'[0-9]{1,5}[a-z]{3}[0-9]{1,2}'}", or
to use a variable:
The
The content of the
A single
A single
A single
It is a
Any
For the select
attribute and the contained sequence
constructor are mutually exclusive
This instruction is designed to process all the non-overlapping substrings of the
input string that match the regular expression supplied: that is,
the
It is a regex
attribute
It is a flags
attribute
Processing proceeds as follows.
Let M be the sequence of
The instruction then processes each of these segments in turn. For a matching segment, it evaluates
the select
attribute or its contained sequence constructor. The context item for this evaluation
is the string value of the matching or non-matching segment (as an instance of xs:string);
the context position is the
position of this segment within the sequence of matching and non-matching segments, and
the context size is the number of segments.
If the select attribute. That is, the corresponding segment produces no output.
Two functions are available for processing the values of captured groups associated with a matching segment.
Examples of the use of these functions can be found in
Returns the set of captured groups associated with a matching segment
during evaluation of the
This function is
The
The Nth captured group (where N > 0) is the segment of the input string matched
by the subexpression contained by the Nth left parenthesis in the regex,
excluding any non-capturing parenthesized expressions. The zeroth captured substring is the segment
of the input string that matches the entire regex. In both cases, a segment
is identified by a record containing both the captured string itself (as value)
and the start position (1-based) of the
captured group within the input string (as position).
This means that the string value of group zero is
the same as the value of . (dot).
The result map contains no entry for a number N if there is no captured group with the number N. This can occur for a number of reasons:
N is negative.
The regular expression contains fewer than N capturing subexpressions.
The Nth capturing subexpression exists, but did not match any part of the input string.
The string value of a captured group may be the empty string.
The set of captured groups is a context variable with dynamic scope. It is initially
an empty sequence. During the evaluation of an
The value of the
The
It distinguishes capturing subexpressions that matched an empty string from capturing subexpressions that did not match anything.
It identifies not just the string that was captured, but its position within the input.
In 4.0 regular expressions may contain capturing subexpressions within a lookahead. In this
situation a segment returned in the result of
regex-group#1 retains the value of the current
captured substrings within its captured context.Returns the string captured by a capturing subexpression of the regular expression
used during evaluation of the
This function is
The function regex-group(N) returns the result of the
expression regex-groups()?N?value otherwise "".
The function may return a zero-length string for a number of reasons:
$number is negative.
The regular expression does not contain a capturing subexpression with the given number.
The capturing subexpression exists, and did not match any part of the input string.
The capturing subexpression exists, and matched a zero-length substring of the input string.
The set of captured groups is a context variable with dynamic scope. It is initially
an empty sequence. During the evaluation of an
The value of the
The examples in this section assume that the stylesheet specifies expand-text="yes"
to enable the use of
Task: replace all newline characters in the abstract element by
empty br elements:
Solution:
Task: replace all occurrences of [...] in the body by
cite elements, retaining the content between the square brackets
as the content of the new element.
Solution:
Note that this simple approach fails if the body element contains
markup that needs to be retained. In this case it is necessary to apply the
regular expression processing to each text node individually. If the
[...] constructs span multiple text nodes (for example, because
there are elements within the square brackets) then it probably becomes necessary
to make two or more passes over the data.
Task: the input string contains a date such as 23 March 2002.
Convert it to the form 2002-03-23.
Solution (with no error handling if the input format is incorrect):
Note the use of normalize-space to simplify the work done by the
regular expression, and the use of doubled curly brackets because the
regex attribute is an attribute value template.
Task: remove all empty and whitespace-only lines from a file.
Task: extract a chapter or appendix number from a string such
as Chapter 5 or Appendix A.
Task: insert hyphens at the points in a string marked by transition from lower-case to upper-case.
In this example the matching substrings are zero-length, and these
zero-length strings are replaced with hyphens. The parts between the
lower-to-upper case transitions are non-matching substrings, and these
are output
There are many variants of CSV formats. Some, but not all,
are handled by new XPath 4.0 functions such as
Each record occupies one line.
Fields are separated by commas.
Quotation marks around a field are optional, unless the field contains a comma or quotation mark, in which case they are mandatory.
A quotation mark within the value of a field is represented by a pair of two adjacent quotation marks.
For example, the input record:
contains six fields, specifically:
Ten Thousand
10000
<zero-length-string>
10,000
It's "10 Grand", mister
10K
The following code parses such CSV input into an XML structure containing
row and col elements:
Note that because this regular expression matches a zero-length string, it is not permitted in XSLT 2.0.
xsl:source-document instructionThe
The streamable attribute (default "no")
allows streamed processing to be requested.
The document to be read is determined by the href attribute (which is defined as
an
Specifically, if an href attribute, it is
A different node will necessarily be returned if there
are differences in attributes such as validation, type,
streamable, or use-accumulators, or if the calls are in different
The result of the
The source document is read from the supplied URI and parsed to form a tree of nodes in the XDM data model.
The contained sequence constructor is evaluated with the root node of this tree
as the context item, and with the context
position and context size set to one; and the resulting sequence is returned as
the result of the
The use-accumulators attribute defines the
set of accumulators that are applicable to the document, as explained in
The validation and type attributes of
streamable="yes" is specified,
the copy that is produced is itself a
streamed document. The process is described in more detail in
These two attributes are both optional, and if one is specified then the other
The presence of a validation or type attribute on an
input-type-annotations attribute to have no effect on any document
read using that instruction.
In effect, setting validation to strict or
lax, or supplying the type attribute, requests
document-level validation of the input as it is read. Setting
validation="preserve" indicates that if the incoming document
contains type annotations (for example, produced by validating the output of a
previous step in a streaming pipeline) then they should be retained, while the
value strip indicates that any such type annotations should be
dropped.
It is a consequence of the way validation is defined in XSD that the type
annotation of an element node can be determined during the processing of its
start tag, although the actual validity of the element is not known until the
end tag is encountered. When validation is requested, a streamed document
should not present data to the stylesheet except to the extent that such data
could form the leading part of a valid document. If the document proves to be
invalid, the processor should not pass invalid data to the stylesheet to be
processed, but should immediately raise the appropriate error. For the
purposes of
Determines, as far as possible, whether a document is available for streamed processing using
This function is
The intent of the streamable="yes" and
with a particular URI as the value of its href
attribute, whether a document is available at that location for streamed processing.
If the $uri argument is an empty sequence then the function returns false.
If the function returns true then the caller can conclude that the following conditions are true:
The supplied URI is valid;
A resource can be retrieved at that URI;
An XML representation of the resource can be delivered, which is well-formed at least to the extent that some initial sequence of octets can be decoded into characters and matched against the production:
prolog (EmptyElemTag | STag )
as defined in the XML 1.0 or XML 1.1 Recommendation.
If the function returns false, the caller can conclude that either one of the above conditions is not satisfied, or
the processor detected some other condition that would prevent a call on streamable="yes" executing successfully.
Like true,
The value of the $uri argument
If the URI is invalid, such that a call on
Accumulators were introduced in XSLT 3.0 to enable data that is read during streamed processing of a document to be accumulated, processed or retained for later use. However, they may equally be used with non-streamed processing.
There are two ways the values of an accumulator can be
established for a given tree: they can be computed by evaluating the rules appearing
in the copy-accumulators="yes". Accumulator values are also copied during
the implicit invocation of the snapshot function performed by the
Accumulators can apply to trees rooted at any kind of node. But because they are most often applied to trees rooted at a document node, this section sometimes refers to the “document” to which an accumulator applies; use of this term should be taken to include all trees whether or not they are rooted at a document node.
Accumulators can apply to trees rooted at nodes (such as text nodes) that cannot have children, though this serves no useful purpose. In the case of a tree rooted at an attribute or namespace node, there is no way to obtain the value of the accumulator.
The following sections give first, the syntax rules for defining an accumulator; then an informal description of the semantics; then a more formal definition; and finally, examples. But to illustrate the concept intuitively, the following simple example shows how an accumulator can be used for numbering of nodes:
This example assumes document input in which figure elements can
appear within chapter elements (which we assume are not nested), and
the requirement is to render the figures with a caption that includes the figure
number within its containing chapter.
When the document is processed using streaming, the
The required accumulator can be defined and used like this:
An name attribute defines the name of the accumulator. The value of
the name attribute is an
An
The capture attribute is allowed only on an phase="end". Its effect is described in
The functions as
attribute of the
The initial value of the accumulator is obtained by evaluating the expression in
the initial-value attribute. This
attribute is mandatory. The expression in the
initial-value attribute is evaluated with a
The values of the accumulator for individual nodes in a tree are obtained by
applying the match attribute of
phase
attribute indicates whether the rule fires before descendants are processed
(phase="start", which is the default), or after descendants are
processed (phase="end").
The select attribute and the contained sequence constructor of the
select attribute is present then the sequence constructor must be
empty. The expression in the select
attribute of
An additional variable is present in the context. The name of this variable
is value (in no namespace), and its type is the type that
appears in the as attribute of the
The context item for evaluation of the expression or sequence constructor will always be a node
that matches the match attribute.
The result of both the initial-value and select expressions (or contained sequence
constructor) is converted to the type declared in the as
attribute by applying the as attribute defaults to item()*.
The effect of the streamable attribute
is defined in
The effect of the capture attribute
is defined in
It is not the case that every accumulator is applicable to every tree. The details depend on how the accumulator is declared, and how the tree is created. The rules are as follows:
An accumulator is applicable to a tree unless otherwise specified in these rules.
(For example, when a document is read using the
Regardless of the rules below, an accumulator is not applicable to a streamable="yes". (The converse
does not apply: for unstreamed documents, accumulators are applicable regardless
of the value of the streamable attribute.)
For a document read using the
use-accumulators
attribute of that instruction.
For a document read using the for-each-source attribute of an
use-accumulators
attribute of the
For a document containing nodes supplied in the
For a tree T created by copying a node in a tree S
using the copy-accumulators="yes", an accumulator is applicable to
T if and only if it is applicable to S.
If an accumulator is not applicable to the tree containing the context item, calls
to the functions
The reason that accumulators are not automatically applicable to every streamed document is to avoid the cost of evaluating them, and to avoid the possibility of dynamic errors occuring if they are not designed to work with a particular document structure.
In the case of unstreamed documents, there are no compelling reasons to restrict which accumulators are applicable, because an implementation can avoid the cost of evaluating every accumulator against every document by evaluating the accumulator lazily, for example, by only evaluating the accumulator for a particular tree the first time its value is requested for a node in that tree. In the interests of orthogonality, however, restricting the applicable accumulators works in the same way for streamable and non-streamable documents.
The value of the use-accumulators attribute of
#all. The list may be empty, and the default value is
an empty list. Every EQName in the list must be the name of an
accumulator, visible in the containing package, and declared with
streamable="yes". The value #all indicates that all
accumulators that are visible in the containing package are applicable (except
that for a streamable input document, an accumulator is not applicable unless
it specifies streamable="yes").
It is a use-accumulators
attribute#all along with any
other value; or if any token (other than
#all) is not the name of a
Informally, an accumulator is evaluated by traversing a tree, as follows.
Each node is visited twice, once before processing its descendants, and once after processing its descendants. For consistency, this applies even to leaf nodes: each is visited twice. Attribute and namespace nodes, however, are not visited.
Before the traversal starts, a variable (called the accumulator variable) is
initialized to the value of the expression given as the initial-value
attribute.
On each node visit, the match attribute must match the node, and the phase
attribute must be start if this is the first visit, and
end if it is the second visit. If there is a matching rule, then a
new value is computed for the accumulator variable using the expression contained
in that rule’s select
attribute or the contained sequence constructor. If there is more than
one matching rule, the last in document order is used. If there is no matching
rule, the value of the accumulator variable does not change.
Each node is labeled with a pre-descent value for the accumulator, which is the
value of the accumulator variable immediately
The function
Although this description is expressed in procedural terms, it can be seen that the two values of the accumulator for any given node depend only on the node and its preceding and (in the case of the post-descent value) descendant nodes. Calculation of both values is therefore deterministic and free of side-effects; moreover, it is clear that the values can be computed during a streaming pass of a document, provided that the rules themselves use only information that is available without repositioning the input stream.
It is permitted for the select expression of an accumulator rule, or the contained
sequence constructor, to invoke an accumulator function. For a streamable accumulator, the rules ensure that
a rule with phase="start" cannot call the
{ "phase": p, "node": n } where p is the string
"start" or "end" and n is a node.
The traversal of a tree contains two
traversal events for each node in the tree, other than attribute and namespace
nodes. One of these events (the “start event”) has phase "start", the other (the
“end event”) has phase "end".
The order of traversal events within a traversal is such that, given any two nodes M and N with start/end events denoted by M0, M1, N0, and N1, :
For any node N, N0 precedes N1;
If M is an ancestor of N then M0 precedes N0 and N1 precedes M1;
If M is on the preceding axis of N then M1 precedes N0.
The accumulator defines a (private) delta function Δ. The delta function computes the value of the accumulator for one traversal event in terms of its value for the previous traversal event. The function is defined as follows:
The signature of Δ is function ($old-value as T,
$event as map(*)) as T, where T is the sequence type
declared in the as attribute of the accumulator
declaration;
The implementation of the function is equivalent to the following algorithm:
Let R be the set of phase attribute equals $event("phase")
and whose match attribute is a
$event("node")
If R is empty, return $old-value
Let Q be the
Return the value of the expression in the select
attribute of Q, or the
contained sequence constructor, evaluating this with a
$event("node") and with a dynamic context that binds
the variable whose name is $value (in no namespace) to the value
$old-value.
The argument names old-value and event
are used here purely for definitional purposes; these names are not
available for use within the select expression or contained sequence
constructor.
There is a slight variation here for an accumulator rule specifying
phase="end" and capture="yes". For details,
see
For every node N, other than attribute and namespace nodes, the accumulator defines a pre-descent value B/N and a post-descent value A/N whose values are as follows:
Let T be the fn:root(N).
Let SB be the subsequence of T starting at the first
event in T and ending with the start event for node N
(that is, the event { "phase": "start", "node": N }).
Let SA be the subsequence of T starting at the first
event in T, and ending with the end event
for node N (that is, the event { "phase": "end", "node": N
}).
Let Z be the result of evaluating the expression contained in the
initial-value attribute of the
root(N).
Then the pre-descent value B/N is the value of
fn:fold-left(SB, Z, Δ), and the post-descent value
A/N is the value of fn:fold-left(SA, Z,
Δ).
If a dynamic error occurs when evaluating the initial-value expression
of select expression of
In the above rule, the phrase
Particularly in the case of streamed accumulators, this may mean that the implementation has to “hold back” the error
until the next time the accumulator is referenced, to give applications the opportunity to catch the error using
Errors that occur during the evaluation of the pattern in the match attribute of
Returns the pre-descent value of the selected accumulator at the context node.
This function is
The $name argument specifies the name of the xs:QName, or
The function returns the pre-descent value B(N)of the selected accumulator
where N is the context node, as defined in
If the context item is a node in a streamed document, then the accumulator
must be declared with streamable="yes".
The converse is not true: an accumulator declared to be streamable is available on both streamed and unstreamed nodes.
It is a
It is a
It is a
It is a streamable="yes"). Implementations
It is an error if there is a cyclic set of dependencies among accumulators such
that the (pre- or post-descent) value of an accumulator depends directly or indirectly on itself.
A processor
The term
The phase="start" rule for that node. In effect, there is a phase="start" rule
for every node, where the default rule is to leave the accumulator value unchanged; the
phase="start" rule.
In XSLT 4.0, the argument can be supplied as a QName literal, for example
accumulator-before( #accum ).
Given the accumulator: | |
and the template rule: | |
The stylesheet will precede the output from processing each section with a section number that runs sequentially 1, 2, 3... irrespective of the nesting of sections. |
Returns the post-descent value of the selected accumulator at the context node.
This function is
The $name argument specifies the name of the xs:QName, or
The function returns the post-descent value A(N) of the selected accumulator
where N is the context node, as defined in
If the context item is a node in a streamed document, then the accumulator
must be declared with streamable="yes".
The converse is not true: an accumulator declared to be streamable is available on both streamed and unstreamed nodes.
The following errors apply:
For constraints on the use of
The phase="end" rule for that node. In effect, there is a phase="end" rule
for every node, where the default rule is to leave the accumulator value unchanged; the
phase="end" rule.
In XSLT 4.0, the argument can be supplied as a QName literal, for example
accumulator-before( #accum ).
Given the accumulator: | |
and the template rule: | |
The stylesheet will output at the end of each section a (crude) count of the number of words in that section. |
If a
It is a
Accumulators cannot be referenced from, or overridden in, a different package from the one in which they are declared.
The capture attribute is intended primarily for use with streamable accumulators, but
in the interests of consistency, it has the same effect both for streamable and non-streamable
accumulators. If an accumulator rule with phase="end" and capture="yes"
matches an element node,
then the rule is evaluated not with the matched element node as the context item, but rather with a snapshot
copy of the matched node. The snapshot copy is made following the rules of the
If a rule with capture="yes" matches a node other than an element, the attribute
has no effect.
The principal effect of specifying capture="yes" is to relax
the rules for streamability. With this option, the phase="end" accumulator rule
has access to the full subtree rooted at the node being visited. In a typical implementation,
a streaming processor encountering an element that matches a capturing accumulator rule
will make an on-the-fly in-memory copy of that element, allowing the phase="end"
accumulator rule full access to the subtree, and also to attributes of ancestors.
This means that an accumulator that needs access to the typed value or string value of an element can get this directly with a rule that matches the element, avoiding the need to write rules that match the element’s text node children.
For example, to capture a copy of the most recent h2 element in a document,
the following accumulator might be declared:
and subsequent processing wishing to copy the most recent h2 element into the result
tree can simply use <xsl:copy-of select="accumulator-before('most-recent-h2')"/>.
Without the capture="yes" attribute, this accumulator would be rejected
as non-streamable, because the select expression on the accumulator rule
is consuming.
Suppose a document contains definitions of technical terms with markup such as:
and the requirement is to generate a glossary that lists all the defined terms in the document, as an appendix.
This can be achieved by capturing all the defined terms in a map:
Suppose that the input XML document contains an element <glossary/> marking
the point where the glossary is to be inserted. The glossary can then be generated
using a template rule such as:
It is a capture="yes" unless it also specifies phase="end".
Since capture="yes" causes the subtree of the relevant element node
to be built in memory, using this option on an element that has a large subtree is best
avoided, because it can defeat the purpose of streaming.
When nodes (including streamed nodes) are copied using the
copy-accumulators="yes", then the pre-descent and post-descent
values of accumulators for that tree are not determined by traversing the tree as
described in
This applies also to the implicit invocation of the
If an accumulator is not applicable to a tree S, then it is also not applicable to any tree formed by copying nodes from S using the above methods.
During streamed processing, accumulator values will typically be computed “on
the fly”; when the
Accumulator values for a non-streamed document will often be computed lazily,
that is, they will not be computed unless and until they are needed. A call on
Consider an XHTML document in which the title of the document is represented by
the content of a title element appearing as a child of the
head element, which in turn appears as a child of the
html element. Suppose that we want to process the document in
streaming mode, and that we want to avoid outputting the content of the
h1 element if it is the same as the document title.
This can be achieved by remembering the value of the title in an accumulator variable.
Subsequently, while processing an h1 element appearing later in
the document, the value can be referenced:
Suppose that there is a requirement to output, at the end of the HTML rendition of a document, a paragraph giving the total number of words in the document.
An accumulator can be used to maintain a (crude) word count as follows:
tokenize#1 relies on XPath 3.1
The final value can be output at the end of the document:
Consider a document in which section elements are nested within
section elements to arbitrary depth, and there is a requirement
to render the document with hierarchic section numbers of the form
3.5.1.4.
The current section number can be maintained in an accumulator in the form of a sequence of integers, managed as a stack. The number of integers represents the current level of nesting, and the value of each integer represents the number of preceding sibling sections encountered at that level. For convenience the first item in the sequence represents the top of the stack.
To illustrate this, consider the values after processing a series of start and end tags:
| events | accumulator value | required section number |
|---|---|---|
<section> | 0, 1 | 1 |
<section> | 0, 1, 1 | 1.1 |
</section> | 1, 1 | |
<section> | 0, 2, 1 | 1.2 |
</section> | 2, 1 | |
<section> | 0, 3, 1 | 1.3 |
<section> | 0, 1, 3, 1 | 1.3.1 |
</section> | 1, 3, 1 | |
<section> | 0, 2, 3, 1 | 1.3.2 |
</section> | 2, 3, 1 | |
</section> | 3, 1 | |
</section> | 1 |
The section number for a section can thus be generated as:
The contained sequence constructor is
evaluated with the variable $value set to the current value, and
with the context node as the node being visited.
In the two calls on map:put(), it is necessary to explicitly
convert @publisher to an xs:string value, because
this is the declared type of the keys in the result map. Relying on
atomization would produce keys of type xs:untypedAtomic, which
would not satisfy the declared type of the map.
The accumulated histogram might be displayed as follows:
xs:QName value instead.
[This change was in the editor's draft accepted by the WG as its baseline when
it started work.]
This section describes XSLT-specific additions to the XPath function library. Some of these
additional functions also make use of
information specified by
Provides access to XML documents identified by a URI.
The one-argument form of this function is
The two-argument form of this function is
The
The first argument contains a sequence of URI references. These are resolved as described below.
The second argument, if present, may be either a node, or an options map.
Supplying a node is allowed for backwards compatibility: the effect of supplying a node $N
is the same as supplying the map {"base-uri": fn:base-uri($N)}.
The effect is that the base URI of the node is used to resolve any relative URI references
contained in the first argument.
If the second argument is supplied as a map, then the
| Key | Value | Meaning |
|---|---|---|
| Determines the base URI used to resolve any relative URI supplied
in the first argument. This in turn affects the base URI of the constructed
document.
| |
| Indicates whether processing the document may cause other
external resources to be fetched (including, for example, external entities, an external DTD,
or documents referenced using xsi:schemaLocation or
XInclude elements).
| |
true | The document may include references to other external resources. | |
false | The document must not include references to other external resources unless access to these resources has been explicitly enabled. | |
| Determines whether DTD validation takes place.
| |
true | The input is parsed using a validating XML parser.
The input must contain a DOCTYPE declaration to identify
the DTD to be used for validation. The DTD may be internal or external.
| |
false | DTD validation does not take place. However, if a
DOCTYPE declaration is present, then it is read, for example
to perform entity expansion.
| |
| Determines whether two calls on the true, but this may be overridden
by implementation-defined configuration options.
| |
true | Given the same explicit and implicit arguments, multiple
calls return the same document node: that is, the function is | |
false | Multiple calls with the same explicit and implicit arguments may return the same document node or different document nodes at the discretion of the implementation. | |
| Determines whether whitespace-only text nodes are removed
from the resulting document.
| |
true | Whitespace stripping is to take place according
to the | |
false | All whitespace-only text nodes are preserved, unless either (a) DTD validation marks them as ignorable, or (b) XSD validation recognizes the containing element as having element-only or empty content. | |
| Determines whether any xi:include elements in the input
are to be processed using an XInclude processor.
| |
true | Any xi:include elements are expanded. If there are
xi:include elements and no XInclude processor is available then
a dynamic error is raised.
| |
false | Any xi:include elements are handled as
ordinary elements without expansion.
| |
| Determines whether XSD validation takes place, using the
schema definitions present in the static context. The effect of requesting
validation is the same as invoking the validation and type options,
using the schema identified in the schema option if specified.
| |
strict | Strict XSD validation takes place | |
lax | Lax XSD validation takes place | |
skip | No XSD validation takes place | |
type Q{uri}local | XSD validation takes place against the schema-defined type, present in the selected schema, that has the given URI and local name. | |
| When XSD validation takes place, determines whether
schema components referenced using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes within the source document are to be used. The option is ignored
if XSD validation does not take place.
| |
true | XSD validation uses the schema components referenced
using xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in addition to the schema components present in the static context;
these components must be compatible as described in | |
false | Any xsi:schemaLocation and xsi:noNamespaceSchemaLocation
attributes in the document are ignored. | |
| When XSD validation takes place, identifies the schema to be used for validation.
If supplied, the value must match the role attribute of an role
attribute.
| |
A sequence of absolute URI references is obtained as follows.
For an item in $uri-sequence that is an instance of
xs:string, xs:anyURI, or
xs:untypedAtomic, the value is cast to xs:anyURI. If
the resulting URI reference is an absolute URI reference then it is used
If the second argument $options is an XNode,
then R is resolved against the base URI of that node.
If $options is supplied as a map and includes a value for the
base-uri option, then R is resolved against that URI.
Otherwise R is resolved against the static base URI from the static context of the
expression containing the call to the
For an item in $uri-sequence that is a node N,
the node is xs:string,
xs:anyURI, or xs:untypedAtomic. Each of these values
is cast to xs:anyURI, and if the resulting URI reference is an
absolute URI reference then it is used
If the second argument $options is an XNode,
then R is resolved against the base URI of that node.
If $options is supplied as a map and includes a value for the
base-uri option, then R is resolved against that URI.
Otherwise R is resolved against the base URI of N.
A relative URI is resolved against a base URI using the rules of the
If $uri-sequence (after atomizing any nodes) contains an
item other than an atomic item of type xs:string, xs:anyURI, or
xs:untypedAtomic then a type error is raised
Each of these absolute URI references is then processed as follows. Any fragment
identifier that is present in the URI reference is removed, and the resulting absolute
URI is cast to a string and then passed to the
If the URI reference contained no fragment identifier, then this document node is
included in the sequence of nodes returned by the
If the URI reference contained a fragment identifier, then the fragment identifier is
interpreted according to the rules for the media type of the resource representation
identified by the URI, and is used to select zero or more nodes that are
descendant-or-self nodes of the returned document node. As described in
The sequence of nodes returned by the function is in document order, with no duplicates.
This order has no necessary relationship to the order in which URIs were supplied in the
$uri-sequence argument.
When a URI reference
A processor
The set of media types recognized by a processor is
When a URI reference
One effect of these rules is that in an interpreted environment
where the source code of the stylesheet is available and its base URI is known, then unless
XML entities or xml:base are used, the expression document("") refers
to the document node of the containing stylesheet module (the definitive rules are in
The XPath rules for function calling ensure that it is a type error if the supplied
value of the second argument is anything other than a single node. If
Keys provide a way to work with documents that contain an implicit cross-reference structure. They make it easier to locate the nodes within a document that have a given value for a given attribute or child element, and they provide a hint to the implementation that certain access paths in the document need to be efficient.
The name attribute specifies the name
of the key. The value of the name attribute is
an match attribute
is a match
attribute.
The key name is scoped to the containing
The value of the key may be specified either using the use attribute
or by means of the contained
It is a use attribute and
has non-empty content, or if it has empty content and no use
attribute.
If the use attribute is present, its value is an
Similarly, if a
use attribute and the
When evaluation of the composite attribute:
When the attribute is absent or has the value no, each atomic
item in the sequence acts as an individual key. For example, if
match="book" use="author" composite="no" is specified, then
a book element may be located using the value of any
author element.
When the attribute is present and has the value yes, the
sequence of atomic items is treated as a composite key that must be matched
in its entirety. For example, if match="book" use="author"
composite="yes" is specified, then a book element may
be located using the value of all its author elements, supplied
in the correct order.
If there are several composite
attribute. The "no" if the attribute is absent.
There is no requirement that all the values of a key should have the same type.
The presence of an match pattern if the values of the
An
Keys can only be used to search within a tree that is rooted at a document node.
The optional collation attribute is used only when deciding whether
two strings are equal for the purposes of key matching. Specifically, two key
values $a and $b are considered equal if the result of
the function call deep-equal($a, $b,
$collation) returns true. The effective collation for an
collation attribute if present, resolved against the base URI of
the
It is a collation
attribute whose value (after resolving against the base URI) is not a URI
recognized by the implementation as referring to a collation.
It is a xs:anyURI values, or if the implementation can determine
that they are different URIs referring to the same collation.
It is a composite attribute.
It is possible to have:
multiple
a node that matches the match patterns of several different
a node that returns more than one value from its
a key value that identifies more than one node (the key values for different nodes do not need to be unique).
An
Returns the nodes within a document or subtree that match a supplied key value.
The two-argument form of this function is
The three-argument form of this function is
The
The $key-name argument specifies the name of the xs:QName, or
The $key-value argument to the composite attribute of the corresponding xsl:key
declaration.
If composite is no or
absent, the set of requested key values is formed by atomizing the
supplied value of the argument, using the standard
If the second argument is an empty sequence, the result of the function will be an empty sequence.
If composite is yes, the requested key
value is the sequence formed by atomizing the supplied value of the argument,
using the standard
If the second argument is an empty sequence, the result of the function will be the set of nodes having an empty sequence as the value of the key specifier.
Two atomic items K1 and K2 are deemed equal if they satisfy one of the following rules:
If both K1 and K2 are of type
xs:string, xs:untypedAtomic,
or xs:anyURI, then they are deemed equal if
compare(K1, K2, $collation)
returns zero, where $collation is the collation of the key definition.
Otherwise, they are deemed equal if atomic-equal(K1, K2)
returns true.
When composite="yes", then two sequences of atomic
items S1 and S2 are deemed equal if deep-equal(S1,
S2, { 'items-equal': $F })) returns true, where $F is the function
just described for comparing atomic items.
The rules for comparing items have changed in this version of the specification, in the interests of bringing keys into line with maps. The main differences are:
Numeric equality is transitive. In particular, when comparing an xs:double
value to an xs:decimal, they must now be exactly numerically equal; the xs:decimal
was previously converted to the nearest xs:double.
The implicit timezone is no longer used when comparing date/time values with a timezone to values without one. To be equal, the values must either both have a timezone, or both be without one.
The third argument is used to identify the selected subtree. If the argument is present,
the selected subtree is the set of nodes that have $top as an
ancestor-or-self node. If the argument is omitted, the selected subtree is the document
containing the context node. This means that the third argument effectively defaults to
/.
The result of the
$N/ancestor-or-self::node() intersect $top is non-empty. (If the
third argument is omitted, $top defaults to /)
$N matches the pattern specified in the match attribute of
an name attribute matches
the name specified in the $key-name argument.
When composite="no", and the
$key-value, using the equality
comparison defined above.
When composite="yes", and the
$key-value, under the rules of the
The sequence returned by the
Different rules apply when
A key (that is, a set of composite attribute
is no.
When a key is processed in backwards compatible mode, then:
The result of evaluating the key specifier in any
When the first argument to the
It is a $key-name is not a valid QName, or if there is no namespace
declaration in scope for the prefix of the QName, or if the name obtained by
expanding the QName is not the same as the expanded name of any
It is a
Untyped atomic items are converted to strings, not to the type of the other operand.
This means, for example, that if the expression in the use attribute
returns a date, supplying an untyped atomic item in the call to the
Given a declaration an expression and that the | |
Suppose a document describing a function library uses a and a Then the stylesheet could generate hyperlinks between the references and definitions as follows: | |
When called with two arguments, the | |
For example, suppose a document contains bibliographic references in the form
Then the stylesheet could use the following to transform the This relies on the ability in XPath 2.0 to have a function call on the
right-hand side of the The following code would also work: | |
This example uses a composite key consisting of first name and last name to locate employees in an employee file. The key can be defined like this: A particular employee can then be located using the function call: |
Delivers the content of a key, for a specific document or subtree, as a map.
This function is
The effect of the function is to return a map $M such that
map:get($M, $key) returns the same result as key($key-name, $key, $top).
The function is defined only for maps that satisfy the following constraints:
The key's collation must be the Unicode Codepoint Collation.
The key must not specify composite=yes.
The $key-name argument specifies the name of the xs:QName, or
a string containing an
The $top argument is used to identify the selected subtree. If the argument is present,
the selected subtree is the set of nodes that have $top as an
ancestor-or-self node. If the argument is omitted, the selected subtree is the document
containing the context node. This means that the third argument effectively defaults to
/.
The returned map contains one entry (K, V) for every atomic item K
where the result of key($key-name, K, $top) is not empty, with V
set to the result of key($key-name, K, $top).
It is a
It is a composite=yes.
It is a
The function has two main uses:
It enables the key values present in a key to be enumerated.
It enables the keys for multiple documents to be combined into a single map, for example
by using
This example uses a key identifying employees in an employee file by their social security number. The key might be defined like this: Given two documents |
Returns a deep copy of the sequence supplied as the $input argument, or of the
context item if the argument is absent.
The zero-argument form of this function is
The one-argument form of this function is
The zero-argument form of this function is defined so that copy-of()
returns the value of internal:copy-item(.), where internal:copy-item (which
exists only for the purpose of this exposition) is defined below. Informally, copy-of()
copies the context item.
The single argument form of this function is defined in terms of the
internal:copy-item as follows: copy-of($input) is equivalent
to $input ! internal:copy-item(.). Informally, copy-of($input) copies each item in the
input sequence in turn.
The internal:copy-item function is defined as follows:
The streamability analysis, however, is different: see
The use of new-each-time="maybe" in the above definition means that
if the internal:copy-item function is called more than once with the same node as argument
(whether or not these calls are part of the same call on copy-of), then it is
One case where such optimization might be possible is when the copy is immediately atomized.
The
All nodes in the result sequence will be parentless.
If atomic items or functions (including maps and arrays) are present in the input sequence, they will be included unchanged at the corresponding position of the result sequence.
Accumulator values are taken from the copied
document as described in
Using | |
This example copies from the source document all employees who work in marketing and
are based in Dubai. Because there are two accesses using the child axis, it is not
possible to do this without buffering each employee in memory, which can be achieved
using the | |
Returns a copy of a sequence, retaining copies of the ancestors and descendants of any node in the input sequence, together with their attributes and namespaces.
The zero-argument form of this function is
The one-argument form of this function is
The zero-argument form of this function is defined so that snapshot()
returns the value of internal:snaphot-item(.), where internal:snapshot-item (which
exists only for the purpose of this exposition) is defined below. Informally, snapshot()
takes a snapshot of the context item.
The single argument form of this function is defined in terms of the
internal:snapshot-item as follows: snapshot($input) is equivalent
to $input ! internal:snapshot-item(.). Informally, snapshot($input) takes a snapshot of each item in the
input sequence in turn.
The internal:snapshot-item function behaves as follows:
If the supplied item is an atomic item or a function item (including maps and arrays), then it returns that item unchanged.
If the supplied item is a node, then it returns a
copy-namespaces set to yes,
copy-accumulators set to yes, and
validation set to preserve, with the additional property
that for every ancestor of N, the copy also has a corresponding ancestor
whose name, node-kind, and base URI are the same as the corresponding ancestor of
N, and that has copies of the attributes, namespaces and accumulator values of the
corresponding ancestor of N. But the ancestor has a type annotation of
xs:anyType, has the properties nilled,
is-id, and is-idref set to false, and has no children
other than the child that is a copy of N or one of its
ancestors.
If the function is called more than once with the same argument, it is snapshot($X) is snapshot($X) is
Except for the effect on accumulators, the internal:snapshot-item function can be expressed
as follows:
The
For parentless nodes, the effect of snapshot($x) is identical to the effect
of copy-of($x).
Using | |
This example copies from the source document all employees who work in marketing and
are based in Dubai. It assumes that employees are grouped by location. Because there
are two accesses using the child axis (referencing | |
current#0 retains the value of the current
item within its captured context.Returns the item that is the context item for the evaluation of the containing XPath expression
This function is
The
means the same as
However, within square brackets, or on the right-hand side of the /
operator, the current item is generally different from the context item.
If the
If the
The instruction: | |
will process all | |
which means the same as | |
and so would process all |
Returns the URI (system identifier) of an unparsed entity
This function is
Calling the single-argument form of this function has the same effect as calling the two-argument form with the context item as the second argument.
The two-argument $entity-name argument, in
the document containing the node supplied as the
value of the $doc argument. It
returns the zero-length xs:anyURI if there is no such entity. This function
maps to the dm:unparsed-entity-system-id accessor defined in
It is a $node,
or the context item if the second argument is omitted,
is a node in a tree whose root is not a document node.
The following errors may be raised when $node is omitted:
If the context item is absent,
If the context item is not a node,
The XDM accessor dm:unparsed-entity-system-id is defined to return an absolute URI,
obtained by resolving the system identifier as written against the base URI of the document. If no
base URI is available for the document, the
XML permits more than one unparsed entity declaration with the same name to appear,
and says that the first declaration is the one that should be used. This rule
Returns the public identifier of an unparsed entity
This function is
Calling the single-argument form of this function has the same effect as calling the two-argument form with the context item as the second argument.
The two-argument $entity-name argument, in the document containing the node supplied as the
value of the $doc argument. It returns the zero-length string if
there is no such entity, or if the entity has no public identifier. This function maps
to the dm:unparsed-entity-public-id accessor defined in
It is a $node,
or the context item if the second argument is omitted,
is a node in a tree whose root is not a document node.
The following errors may be raised when $node is omitted:
If the context item is absent,
If the context item is not a node,
XML permits more than one unparsed entity declaration with the same name to appear,
and says that the first declaration is the one that should be used. This rule
Returns the value of a system property
This function is
The value of the $name argument
xs:QName, or
The
Implementations
xsl:version, a number giving the version of XSLT implemented by the
"4.0".
The value will always be a
string in the lexical space of the decimal datatype defined in XML Schema (see
xsl:vendor, a string identifying the implementer of the
xsl:vendor-url, a string containing a URL identifying the implementer
of the
xsl:product-name, a string containing the name of the implementation,
as defined by the implementer. This
xsl:product-version, a string identifying the version of the
implementation, as defined by the implementer. This
xsl:is-schema-aware, returns the string "yes" in the
case of a processor that claims conformance as a "no" in the case of a
xsl:supports-serialization, returns the string "yes" in
the case of a processor that offers the "no" otherwise.
xsl:supports-backwards-compatibility, returns the string
"yes" in the case of a processor that offers the "no" otherwise.
xsl:supports-namespace-axis, returns the string "yes" in
the case of a processor that offers the XPath namespace axis even when not in
backwards compatible mode, or "no" otherwise. Note that a processor
that supports backwards compatible mode must support the namespace axis when in
that mode, so this property is not relevant to that case.
xsl:supports-streaming, returns the string "yes" in the
case of a processor that offers the streaming feature (see "no" otherwise.
xsl:supports-dynamic-evaluation, returns the string
"yes" unless dynamic evaluation (that is,
use of "no".
xsl:supports-higher-order-functions, always returns the string
"yes".
xsl:xpath-version, a number giving the version of XPath implemented by the
"4.0".
The value will always be a
string in the lexical space of the xs:decimal data type.
This allows the value to be converted to a number
for the purpose of magnitude comparisons.
xsl:xsd-version, a number giving the version of XSD (XML Schema) implemented by the
"1.0" or "1.1".
This property is relevant even when the processor is not schema-aware, since the built-in datatypes
for XSD 1.1 differ from those in XSD 1.0.
Some of these properties relate to the conformance levels and features offered by the
Except where otherwise specified, the actual values returned for the above properties
are
The set of system properties that are supported, in addition to those listed above, is
also
It is a $property-name argument
An implementation must not return the value
3.0
as the value of the xsl:version system property unless it is
conformant to XSLT 3.0.
It is recognized that vendors who are enhancing XSLT 1.0 or
2.0 processors may wish to release interim implementations before all the
mandatory features of this specification are implemented. Since such products are not
conformant to XSLT 3.0, this specification cannot define their behavior. However,
implementers of such products are encouraged to return a value for the
xsl:version system property that is intermediate between 1.0 and 3.0,
and to provide the
In XSLT 4.0, the argument can be supplied as a QName literal, for example
system-property( #xsl:version ).
TODO: add change metadata (PR 1243)
Returns a list of system property names that are suitable for passing to
the
This function is
The function returns a sequence of QNames, being the names of the system properties
recognized by the processor, in some
The prefix part of a returned QName is
The function is
The function returns a list of QNames, containing no duplicates.
The QNames in this list are suitable for passing to the
Q{uri}local. Because the prefix
of the returned QName is unpredictable, the Q{uri}local is likely
to be more convenient. Conversion of an xs:QName value to an EQName in
Q{uri}local format can be achieved using the function:
Maps are defined in the XDM Data Model: see
select attribute
as an alternative to the contained sequence constructor.
select
attribute and a sequence constructor are present.
Three instructions are added to XSLT to facilitate the construction of maps.
The instruction
The select attribute and the contained sequence constructor are mutually
exclusive: if a select attribute is present, then the content
The result of evaluating the select expression or the contained
sequence constructor is referred to as the
The input sequence $maps.
Informally:
The order of entries in the returned map will reflect the order of items in the sequence that results from evaluation of the input sequence.
The handling of duplicate keys is described in
There is no requirement that the supplied input maps should have the same or
compatible types.
The type of a map (for example map(xs:integer,
xs:string)) is descriptive of the entries it currently contains, but is not
a constraint on how the map may be combined with other maps.
A common coding pattern is to supply the input as a set of single-entry maps, that is,
maps containing a single key-value pair. Moreover, it is often convenient to construct these
using the
A type error occurs if the result of the input sequence
map(*)*.
In practice, the effect of this rule is that the result of the
select expression or sequence
constructor contained in the
It is legitimate to construct a map using an instruction such as
<xsl:map select="{'a':1, 'b':2}"/>. In this situation
The instruction
The select attribute and the contained sequence constructor are mutually
exclusive: if a select attribute is present, then the content
The key of the entry in the new map is the value obtained by evaluating the
expression in the key attribute, converted to the required type
xs:anyAtomicType by applying the xs:untypedAtomic, it is cast to xs:string.
The associated value is the value obtained by evaluating the expression in the
select attribute, or the contained sequence constructor, with no
conversion. If there is no select attribute and the sequence constructor
is empty, the associated value is the empty sequence.
The following example binds a variable to a map whose content is statically known:
In simple cases like this the same effect can be achieved using the
A third option is to construct the map in XPath:
The following example binds a variable to a map acting as an index into a source document:
Again, an alternative is to use an XPath expression:
The following example modifies a supplied map $input by changing
all the keys to upper case. A dynamic error occurs if this results in duplicate
keys:
The following example modifies a supplied map $input by wrapping
each of the values in an array:
This could also be written:
(The notation * = expression indicates that this instruction accepts
any number of additional attributes in no namespace.)
element-catalog.xml
to declare 'any permitted attribute of a given name type/pattern', in this case xs:NCName
The instruction
Unlike all other xsl:as and
xsl:duplicates as well as the use-when or xpath-default-namespace) attached to the as, duplicates, use-when etc.) as potential
entry keys, leaving any valid NCName as a candidate.
The $record. For each of the attributes of the instruction whose name
is an xs:NCName an entry is added to $record whose
key is the name of the attribute (as xs:string) and whose value is
the result of evaluating the value of that attribute as an expression in the
current context.
As the values of the attributes whose names are xs:NCName are considered to be XPath expressions,
two consequences follow for such attributes:
xs:NCName.
The order of attribute-generated entries in $record will reflect
the order of attributes returned along the attribute:: axis, which is
After processing the applicable attributes of the instruction, any contained
sequence constructor is evaluated and the result $record. By this means entries can be added whose keys are not
NCNames, or conditionally generated entries can be included.
Each of the map entries in
$record is modified by applying the xsl:as
attribute of the $record is returned as the instruction result.
as attribute, restricting type.
The treatment of duplicate keys between entries defined in the attributes of
The effect of this instruction, in the absence of errors, is equivalent to execution of the XSLT
which for the instruction:
would produce
The following example constructs a map using
with the following input
will produce a resulting map:
xsl:map/@duplicates is available,
allowing control over how duplicate keys are handled by the xsl:record/@xsl:duplicates is added to control duplicate keys handling in the This section describes what happens when two or more maps in the input sequence of
an fn:atomic-equal(K, L) returns true.
In the absence of the [xsl:]duplicates attribute,
a
The result of evaluating the [xsl:]duplicates attribute, if present, "use-first", "use-last",
"use-any", "combine", or "reject",
or a function with arity 2. These values correspond to the permitted
values of the duplicates option of the
The result of the $maps
is the input sequence to $duplicates
is the [xsl:]duplicates
attribute, then the result of the instruction is the result of the function
call map:merge($maps, { "duplicates": $duplicates }).
The following table shows some possible values
of the duplicates attribute, and explains their effect:
| Attribute | Effect |
|---|---|
duplicates="'use-first'" | The first of the duplicate values is used. |
duplicates="'use-last'" | The last of the duplicate values is used. |
duplicates="'combine'" | The duplicates="op(',')". |
duplicates="fn($a, $b) { max(($a, $b)) }" | The highest of the duplicate values is used. |
duplicates="fn($a, $b) { min(($a, $b)) }" | The lowest of the duplicate values is used. |
duplicates="concat(?, ', ', ?) }" | The comma-separated string concatenation of the duplicate values is used. |
duplicates="op('+')" | The sum of the duplicate values is used. |
duplicates="fn($a, $b) { subsequence(($a, $b), 1, 4) }" | The first four of the duplicates are retained; any further duplicates are discarded. |
duplicates="fn($a, $b) { distinct-values(($a, $b)) }" | When multiple entries have the same key, the corresponding values are retained only if they are distinct from other values having the same key. |
This example takes as input an XML document such as:
and constructs a map whose JSON representation is:
The logic is:
Specifying the effect by reference to
The position of the merged entry in the result corresponds to the position of the first of the duplicate keys in the input.
The key used for the merged entry in the result corresponds
to one of the duplicate keys in the input: it is
xs:dateTime
values in different timezones.
This section gives some examples of where maps can be useful.
This example uses maps in conjunction with the
A complex number might be represented as a map with two entries, the keys being
the xs:boolean value true for the real part, and the
xs:boolean value false for the imaginary part. A
library for manipulation of complex numbers might include functions such as the
following:
Given a set of book elements, it is possible to construct an index in
the form of a map allowing the books to be retrieved by ISBN number.
Assume the book elements have the form:
An index may be constructed as follows:
This index may then be used to retrieve the book for a given ISBN using either of
the expressions map:get($isbn-index, "0470192747") or
$isbn-index("0470192747").
In this simple form, this replicates the functionality available using
book elements in multiple source documents. It also allows
processing of all the books using a construct such as <xsl:for-each
select="map:keys($isbn-index)">
As in JavaScript, a map whose keys are strings and whose associated values are function items can be used in a similar way to a class in object-oriented programming languages.
Suppose an application needs to handle customer order information that may arrive in three different formats, with different hierarchic arrangements:
Flat structure:
Orders within customer elements:
Orders within product elements:
An application can isolate itself from these differences by defining a set of
functions to navigate the relationships between customers, orders, and products:
orders-for-customer, orders-for-product,
customer-for-order, product-for-order. These
functions can be implemented in different ways for the three different input
formats. For example, with the first format the implementation might be:
Having established which input format is in use, the application can bind the
appropriate implementation of these functions to a variable such as
$input-navigator, and can then process the input using XPath
expressions such as the following, which selects all products for which there is
no order: //product[empty($input-navigator("orders-for-product")(.))]
Arrays are defined in the XDM Data Model: see
The instruction
There are three typical ways an array might be constructed.
An array whose members are all single items can be constructed using an instruction such as:
This constructs an array of five strings: ['Mon', 'Tues', "Weds', "Thurs', 'Fri']
The values, of course, do not need to be literals.
An array whose members can be computed by applying a mapping to a sequence of items can be constructed using an instruction such as:
This constructs an array with five members, each being a sequence of two
strings: [('Monday', 'Mon'), ('Tuesday', 'Tue'), ('Wednesday', 'Wed'), ('Thursday', 'Thu'), ('Friday', 'Fri')]
A more complex example might be:
which creates an array with one member for each line of an input file, the relevant member being a sequence of words appearing on that line.
This returns an array of twelve members, each being a sequence of integers, for example the last
member is the sequence (1, 2, 3, 4, 6, 12).
Another example might be:
This returns the array [ (1, 2, 3, 4), (5, 6, 7, 8, 9), 10 ].
The detailed rules follow.
In these rules, the term
A parcel encapsulates a value, which may be any sequence; the value of the parcel is the result of calling the corresponding function item with no arguments.
The effect of the select attribute or its contained sequence constructor.
The
If the for-each attribute is absent, then:
Let S be the sequence that results from
evaluation of the select expression or the contained
sequence constructor.
The result of the If S/i is a Otherwise,
the array member is the singleton item S/i.
If the for-each attribute is present, then:
Let F = F/1, F/2, ..., F/n
be the sequence that results from evaluation
of the for-each attribute.
The resulting array contains one member for each item in F, retaining order.
The member corresponding to a particular item F/i is as follows:
Let S be the result of evaluating the select expression
or the contained sequence constructor with a
If S contains a single item and that item is a
If S contains multiple items and one of those items is a
It
is a for-each attribute includes items constructed
using an
When the for-each attribute is present, then it is not necessary
to use the xsl:array-member instruction, since each evaluation
of the select attribute or the containing sequence constructor
generates one array member. However, use of xsl:array-member
to construct the array member is permitted, provided that it constructs
the entire array member and not an individual item within it.
The content of an array is effectively a sequence of sequences, which the XDM data
model cannot represent directly. Representing an array member as a
select and for-each attributes
of xsl:array are both absent.
If the select attribute then
the sequence constructor must be empty, except for any
If the select attribute then
the sequence constructor must be empty, except for any
The following example constructs the array [1, 2, 3, 4, 5]:
The following example constructs an array of text nodes:
The following example constructs an array by tokenizing a string:
The result is the array [ "The", "cat", "sat", "on", "the", "mat" ].
The following example constructs an array containing items computed using nested instructions:
The result is the array [ "0-1-2-3", "4-5-6-7", "8-9-10-11", "12-13-14-15", "16-17-18-19" ].
Note that in this last example, the xsl:sequence.
The following example constructs an array whose members are sequences:
This returns an array with one member for each child paragraph, the content of the array member being the list of distinct words appearing in that paragraph.
The following example constructs an array in which the members are obtained by applying templates to the children of the context item:
The following example constructs a heterogeneous array containing a number of properties of a supplied node, some of which are sequence-valued:
When applied to an input element such as
the result would be the array:
The
The result is [ [ 10, 11, 12], [ 20, 21, 22 ], [ 30, 31, 32 ], [ 40, 41, 42 ] ].
Given a book containing chapters which in turn contain sections, the following code produces a nested array representing the (crude) word counts of the sections within each chapter:
The result might be an array of the form [[842, 316], [450, 217], ...]
indicating that the first section of the second chapter has a word count of 450.
The $A1
and $A2, and sorts the result:
The following code transposes a regular nested array (such as [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ] ])
so the result is organized by columns rather than rows ([ [ 1, 4, 7 ], [ 2, 5, 8 ], [ 3, 6, 9 ] ]):
As with maps (see
Unlike maps, array constructors have no special rules allowing the members of the array to be constructed using multiple consuming subexpressions.
The
The content of the message may be specified by using either or both of the optional
select attribute and the
If the
If the select attribute,
then the value of the attribute select
attribute were added to the start of the
If the select attribute, then an empty message is produced.
The tree produced by the
In many cases, the XML document produced using
An implementation might implement
The terminate attribute is interpreted as an
If the terminate attribute is yes, then the no. Note that because the order of evaluation of
instructions is
The optional error-code attribute
(also interpreted as an terminate. The
XTMM9000 and namespace URI
http://www.w3.org/2005/xqt-errors. User-defined error codes
http://www.w3.org/2005/xqt-errors. When the value of
terminate is yes, the error code may be matched in an
XPath 4.0 allows an error-code="{http://example.com/ns}my:error-code".
When a transformation is terminated by use of <xsl:message
terminate="yes"/>, the effect is the same as when a XTMM9000; this may be
overridden using the error-code attribute of the
One convenient way to do localization is to put the localized information (message
text, etc.) in an XML document, which becomes an additional input file to the
L
are stored in an XML file resources/L.xml in the
form:
Then a stylesheet could use the following approach to localize messages:
Any select expression or the contained
An example of such an error is the serialization error that occurs when processing
the instruction <xsl:message select="@code"/> (on the grounds
that free-standing attributes cannot be serialized). Making such errors
recoverable means that it is implementation-defined whether or not they are
raised to the user and whether they cause termination of the transformation. If
the processor chooses to recover from the error, the content of any resulting
message is implementation-dependent.
One possible recovery action is to include a description of the error in the generated message text.
The true; if the value of the expression is false, and
assertions are enabled, then a dynamic error occurs.
By default, assertions are disabled.
An implementation
If assertion checking is enabled, the instruction is evaluated as follows:
The expression in the test attribute is evaluated. If the
effective boolean value of the result is true, the assertion
succeeds, and no further action is taken. If the effective boolean value is
false, or if a dynamic error occurs during evaluation of the expression, then
the assertion fails.
If the assertion fails, then the effect of the instruction is governed by the
rules for evaluation of an select attribute, error-code attribute, and
contained terminate="yes". However, the default error code if the
error-code attribute is omitted is XTMM9001 rather
than XTMM9000.
To the extent that the behavior of
If evaluation of the test expression
fails with a dynamic error, the effect is exactly the same as if the
evaluation returns false, including the fact that the
instruction fails with error code XTMM9001.
If an assertion fails, then the following sibling
instructions of the
This means that
When a transformation is terminated by use of XTMM9001; this may be
overridden using the error-code attribute of the
As with any other dynamic error, an error caused by an assertion failing may be
trapped using
The result of the
The following example shows a stylesheet function that checks that the value of
its supplied argument is in range. The check is performed only if the $DEBUG is set to true.
Implementations should avoid optimizing
This guidance is not intended to prevent optimizations such as lazy evaluation, where evaluation of a sequence constructor may finish early, as soon as enough information is available to evaluate the containing instruction.
An implementation
For example, given the assertion <xsl:assert
test="count(//title)=1"/>, a processor might generate code for the
expression <xsl:value-of select="//title"/> that stops searching
for title elements after finding the first one. In the event that the
source document contains more than one title, execution of the
stylesheet may fail in arbitrary ways, or it may produce incorrect output.
xs:QName value instead.
[This change was in the editor's draft accepted by the WG as its baseline when
it started work.]
XSLT allows three kinds of extension: extension attributes, extension instructions, and extension functions.
This specification does not define any mechanism for creating or binding implementations
of
It is a [xsl:]extension-element-prefixes attribute.
An element from the
XSLT namespace may have any attribute not from the XSLT namespace, provided that
the
It is not necessary to declare the namespace used for an extension attribute using
[xsl:]extension-element-prefixes or otherwise.
The presence of an extension attribute
A processor
To allow the user to opt out of some provision in the specification that has
undesirable performance implications (for example, the requirement that functions like
To enable interoperability with third-party software that is not otherwise achievable.
To allow the user to disable functionality for security reasons.
Extension attributes
xml,
xhtml, html, text, json,
and adaptive. For example, an extension attribute might
be used to define the amount of indentation to be used when
indent="yes" is specified.
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 [xsl:]exclude-result-prefixes
attribute.
xsl:message
The following code might be used to indicate to a particular implementation that
the
Implementations that do not recognize the namespace
http://vendor.example.com/xslt/extensions will simply ignore the
extra attribute, and evaluate the
It is a
The set of functions that can be called from a
The definition of the term fn, math,
map, and array namespaces,
anonymous XPath inline functions, maps and arrays,
and partial function applications (including partial applications of extension functions). It also excludes
functions obtained by invoking XPath-defined functions such as
Technically, the definition of extension functions excludes anonymous functions obtained by calling or partially applying other extension functions. Since such functions are by their nature implementation-defined, they may however share some of the characteristics of extension functions.
Determines whether a particular function is or is not available for use. The function is
particularly useful for calling within an [xsl:]use-when attribute (see
This function is
A function is said to be available within an XPath expression if it is present in the
The value of $name xs:QName, or
$arity argument is present and non-empty,true if and only if there is an available function whose name matches the value of the
$function-name argument and whose $arity argument.
$arity argument is omitted or empty,true if and only if there is at least one available function (with some arity)
whose name matches the value of the $name argument.
When the containing expression is evaluated with true, the false in
respect of a function name and arity for which no implementation is available (other
than the fallback error function that raises a dynamic error whenever it is called).
This means that it is possible (as in XSLT 1.0) to use logic such as the following to
test whether a function is available before calling it:
It is a $name argument
The fact that a function with a given name is available gives no guarantee that any particular call on the function will be successful. For example, it is not possible to determine the types of the arguments expected.
The introduction of the
If a function is present in the static context but with no useful
functionality (for example, if the system has been configured for security reasons so
that false.
It is not necessary that there be a direct equivalence between the
results of [xsl:]use-when conditions to test whether static calls on the function
are possible.
In XSLT 4.0, the argument can be supplied as a QName literal, for example
function-available( #fn:matches ). Note that in this case the default function
namespace is not used for unprefixed names.
A stylesheet that is designed to use XSLT 2.0 facilities when running under an XSLT 2.0 or XSLT 3.0 processor, but to fall back to XSLT 1.0 capabilities when not, might be written using the code: Here an XSLT 2.0 or XSLT 3.0 processor will
always take the | |
A stylesheet that is designed to use facilities in some future XSLT version when
they are available, but to fall back to XSLT 2.0 or XSLT
3.0 capabilities when not, might be written using code such as the
following. This hypothesizes the availability in some future version of a function
In this case the two-argument version of |
If the function name used in a
It is a
Implementations may also provide mechanisms allowing extension functions to raise recoverable dynamic errors, or to execute within an environment that treats some or all of the errors listed above as recoverable.
When the containing element is processed with
When XSLT 1.0 behavior is not enabled, this
is a static error
There is no prohibition on calling extension functions that have side-effects (for example, an extension function that writes data to a file). However, the order of execution of XSLT instructions is not defined in this specification, so the effects of such functions are unpredictable.
Implementations are not
The ability to execute extension functions represents a potential security
weakness, since untrusted stylesheets may invoke code that has privileged
access to resources on the machine where the
All observations in this section regarding the errors that can occur when invoking
extension functions apply equally when invoking
An implementation sql:connect
might return an object that represents a connection to a relational database; the
resulting connection object might be passed as an argument to calls on other
extension functions such as sql:insert and
sql:select.
The way in which such objects are represented in the type system is integer, string, or
anyURI.
Used to control how a stylesheet behaves if a particular schema type is or is not available in the static context.
This function is
A schema type (that is, a simple type or a complex type) is said to be available within
an XPath expression if it is a type definition that is present in the
The value of the $name argument xs:QName, or
The function returns true if and only if there is an available type whose name matches
the value of the $name argument.
It is a
The [xsl:]use-when expression, because the static context for the expression
does not include any user-defined types.
In XSLT 4.0, the argument can be supplied as a QName literal, for example
type-available( #xs:dateTimeStamp ).
Since an element that is a child of an
In XSLT 4.0 it is possible to use extension instructions to invoke named templates: see
A namespace is designated as an extension namespace by using an
[xsl:]extension-element-prefixes attribute on an element in the
stylesheet (see
The default namespace (as declared by xmlns) may be designated as an
extension namespace by including #default in the list of namespace
prefixes.
A
It is a [xsl:]extension-element-prefixes attribute or, when
#default is specified, if there is no default namespace.
The prefix must be declared in a
The designation of a namespace as an extension namespace is effective for the
element bearing the [xsl:]extension-element-prefixes attribute and
for all descendants of that element within the same stylesheet module.
Determines whether a particular instruction is or is not available for use. The function
is particularly useful for calling within an [xsl:]use-when attribute (see
This function is
The value of the $name argument
xs:QName,
or
If the resulting true if and only if the local name matches the name of an XSLT element that is defined
in this specification and implemented by the XSLT processor.
If the false.
If the true if and
only if the processor has an
The term true simply because the name matches the name of a
If the processor does not have an implementation of a particular extension instruction
available, and such an extension instruction is evaluated, then the processor
It is a
For element names in the XSLT namespace:
This function can be useful to distinguish processors that implement XSLT 3.0 from processors that implement other (older or newer) versions of the specification, and to distinguish full implementations from incomplete implementations. (Incomplete implementations, of course, cannot be assumed to behave as described in this specification.)
In earlier versions of this specification,
true only for
elements classified as instructions. The distinction between instructions and
other elements, however, is sometimes rather technical, and in XSLT 3.0 the effect
of the function has therefore been aligned to do what its name might suggest.
If an instruction is recognized but offers no useful
functionality (for example, if the system has been configured for security reasons
so that false.
For element names in other namespaces:
The result of the
In XSLT 4.0, the argument can be supplied as a QName literal, for example
element-available( #xsl:switch ). Note that in this case the default element
namespace is not used for unprefixed names.
The content of an
When not performing fallback, evaluating an
There are two situations where a
Fallback processing is not invoked in other situations, for example it is not
invoked when an XPath expression uses unrecognized syntax or contains a call to
an unknown function. To handle such situations dynamically, the stylesheet
should call functions such as
When a
This is different from the situation with unrecognized
The output of a transformation includes a
The way in which these results are
delivered to an application is
Serialization of results
is described further in
escape-solidus is provided to control
whether the character / is escaped as \/ by the
JSON serialization method.
select attribute
of canonical is available to give control
over serialization of XML, XHTML, and JSON.
json-lines is available to enable
output as one JSON value per line.
The
The select attribute and the contained select attribute is present then the
sequence constructor must be empty, and if the sequence constructor is non-empty
then the select attribute must be absent select attribute or the
As with the
The
The
The
The name of the instruction,
The decision whether or not to serialize the raw result depends on the
If the result is not serialized, then the decision whether to
return the build-tree attribute. If the build-tree attribute is yes, then
a build-tree attribute is then ignored.
For example, with method="xml" a tree is always constructed, whereas
with method="json" a tree is never constructed.
The
Technically, the result of evaluating the
The format attribute, if specified, format attribute is omitted, the unnamed
It is a format attribute format attribute
contains no curly brackets), then the processor
The only way to select the unnamed format attribute.
The parameter-document attribute allows serialization
parameters to be supplied in an external document. The external document must contain
an output:serialization-parameters element with the format described in
If present, the parameter-document attribute is dereferenced, after resolution
against the base URI of the should be ignored.
A serialization parameter specified in the
parameter-document takes precedence over a value supplied directly as
an attribute of cdata-section-elements and suppress-indentation
attributes are merged in the same way as when multiple
The attributes method, allow-duplicate-names, build-tree, byte-order-mark
canonical, cdata-section-elements, doctype-public,
doctype-system, encoding,
escape-solidus
escape-uri-attributes, html-version, indent, item-separator,
json-lines,
json-node-output-method,
media-type, normalization-form,
omit-xml-declaration, standalone, suppress-indentation,
undeclare-prefixes, use-character-maps, and
output-version may be used to override attributes defined in the
selected
With the exception of use-character-maps, these attributes are all
defined as
In the case of cdata-section-elements
and suppress-indentation, the
value of the serialization parameter is the union of the expanded names of the
elements named in this instruction and the elements named in the selected
output definition.
In the case of use-character-maps, the character maps referenced
in this instruction supplement and take precedence over those defined in the
selected output definition.
In the case of doctype-public and doctype-system,
setting the
In the case of item-separator, setting the "#absent" has the effect of
overriding any value for this attribute obtained from the output definition.
The corresponding serialization parameter is not set (is “absent”). It is not
possible to set the value of the serialization parameter to the literal
7-character string "#absent".
In all other cases, the
In the case of the attributes method, json-node-output-method
cdata-section-elements, suppress-indentation, and
use-character-maps, the
The output-version attribute on the version attribute on
version is
available with a different meaning as a standard attribute: see
There are some serialization parameters that apply to some output methods but not to
others. For example, the indent attribute has no effect on the
text output method. If a value is supplied for an attribute that is
inapplicable to the output method, its value is not passed to the serializer. The
processor
The item-separator serialization parameter
is used when the text serialization method is used, then the result of serialization
will be a string obtained by converting each integer to a string, and separating the
strings using the defined item-separator.
The href attribute is optional. The default value is the zero-length
string. The
href
attribute of If the implementation provides an API to access href attribute. In addition, if a build-tree is yes), then this value is used as the base
URI of the document node at the root of the
The base URI of the
It will often be the case that one
As well as being potentially significant in any API that provides access to final result trees, the base URI of the new document node is relevant if the final result tree, rather than being serialized, is supplied as input to a further transformation.
The optional attributes type and validation may be used on
the validation and
type attributes are ignored.
Validation applies after inserting item separators as determined by the
item-separator serialization parameter, and an inappropriate choice
of item-separator may cause the result to become invalid.
A format attribute and the
serialization attributes. Such an implementation
Implementations may provide additional mechanisms, outside the scope of this
specification, for defining the way in which
The following example takes an XHTML document as input, and breaks it up so that
the text following each <h1> element is included in a separate document. A
new document toc.html is constructed to act as an index:
There are restrictions on the use of the
The instructions in the
It is a
It is a
Note, this means that it is an error to evaluate more than one
href attribute, or to evaluate any
href attribute if an initial
In addition, an implementation
It is a
In addition, an implementation
current-output-uri#0 retains the value of the current
output URI within its captured context.Returns the value of the
This function is
On initial invocation of a stylesheet component, the current output uri is set to the
During execution of an href
attribute, the current output URI changes to the absolute URI obtained by resolving the href attribute against the base output URI.
The current output URI is cleared (set to
The current output URI may also be
The current output URI is not cleared when evaluating a local variable, even though current-output-uri to be set as the value of a
tunnel parameter, so that the original
base output URI is accessible even when writing nested result documents.
xsi:schemaLocation
and xsi:noNamespaceSchemaLocation attributes have been tightened up.
It is possible to control the type and validation attributes of the
xsl:type and xsl:validation attributes
of a
The [xsl:]type attribute is used to request validation of an element or
attribute against a specific simple or complex type defined in a schema. The
[xsl:]validation attribute is used to request validation against the
global element or attribute declaration whose name matches the name of the element or
attribute being validated.
The [xsl:]type and [xsl:]validation attributes are mutually
exclusive. Both are optional, but if one is present then the other
validation attribute with the value specified
in the [xsl:]default-validation attribute of
the innermost containing element having such an attribute; if this is not
specified, the effect is the same as specifying validation="strip".
The [xsl:]default-validation attribute defines the
default value of the validation attribute of all
xsl:validation attribute of all
strip. The permitted values are preserve and
strip.
The default-validation attribute on the outermost element of the principal
stylesheet module of the
The [xsl:]default-validation attribute has no
effect on the
It is a [xsl:]type and [xsl:]validation attributes are
present on the
Validation always uses the [xsl:]schema-role attribute of the instruction itself,
or of a containing element. See also
A stylesheet might take as its primary input a document conforming to schema X,
and produce as its primary output a document conforming to schema Y.
To be sure that the output is indeed valid against schema Y, the safest
course of action is to evaluate an [xsl:]schema-role attribute that selects schema Y and nothing else.
Otherwise, if the validation occurs within a module that imports both X
and Y, the outcome of validation might differ because of the
differences between the two schemas.
The detailed rules for validation vary depending on the kind of node being validated.
The rules for element and attribute nodes are given in
[xsl:]validation AttributeThe [xsl:]validation attribute defines the validation action to be
taken. It determines not only the validation="strict", this will cause the child element to be
checked against an element declaration, but if the instruction that constructs
its parent element specifies validation="strip", then the final
effect will be that the child node is annotated as xs:untyped.
In the paragraphs below, the term
The value strip indicates that the new node and each of the
contained nodes will have the xs:untyped if it is an element, or
xs:untypedAtomic if it is an attribute. Any previous type
annotation present on a contained element or attribute node (for example,
a type annotation that is present on an element copied from a source
document) is also replaced by xs:untyped or
xs:untypedAtomic as appropriate. The typed value of the
node is changed to be the same as its string value, as an instance of
xs:untypedAtomic. In the case of elements the
nilled property is set to false. The values
of the is-id and is-idrefs properties are
unchanged. Schema validation is not invoked.
The value preserve indicates that nodes that are copied will
retain their xs:anyType in the case of elements, or
xs:untypedAtomic in the case of attributes. Schema
validation is not invoked. The detailed effect depends on the
instruction:
In the case of xs:anyType, and the
type annotations of contained nodes are retained unchanged.
The nilled,
is-id and is-idrefs properties on the
new element are set to false.
In the case of validation="strip":
that is, the new attribute will have the type annotation
xs:untypedAtomic.
The is-id and
is-idrefs properties on the new attribute are set
to false.
In the case of nilled, is-id and
is-idrefs properties are also
unchanged.
In the case of
Where the node being copied is an attribute, the copied
attribute will retain its is-id and is-idrefs
properties.
Where the node being copied is an element, the copied element
will have a xs:anyType (because
this instruction does not copy the content of the element, it
would be wrong to assume that the type is unchanged); but any
contained nodes will have their type annotations retained in
the same way as with nilled, is-id, and
is-idrefs properties are handled in the
same way as
The value strict indicates that
schema validation is carried out according to the process described
in [xsl:]validation="strict" is equivalent to constructing
an untyped node N, and then validating it using the
expression;
fn:xsd-validator({'validation-mode':'strict'})(N) ->
if (?is-valid) then ?typed-node else error()More details on the error conditions appear below.
The value lax indicates that
lax validation is carried out according to the process described
in [xsl:]validation="lax" is equivalent to constructing
an untyped node N, and then validating it using the
expression;
fn:xsd-validator({'validation-mode':'lax'})(N) ->
if (?is-valid) then ?typed-node else error()More details on the error conditions appear below.
The effect of these rules is that when validation succeeds, the validate
expression returns a copy of the operand node, augmented with type annotations and expanded
default values. When validation fails (more accurately, when the outcome of validity assessment
is that the operand node is found to be invalid), the expression raises a dynamic error.
If an element that is being validated has an xsi:type
attribute, then the value of the xsi:type attribute will
be taken into account when performing the validation. However, the
presence of an xsi:type attribute will not of itself
cause an element to be validated: if validation against a named type
is required, as distinct from validation against a top-level element
declaration, then it must be requested using the XSLT
[xsl:]type attribute on the instruction that invokes
the validation, as described in section
For reasons of backwards compatibility, the error conditions raised by XSLT validation have their own error codes:
If the validation attribute of an
xsl:validation attribute of a literal result element, has
the strict, and schema validity assessment
concludes that the validity of the element or attribute is invalid or
unknown, a
If the validation attribute of an
xsl:validation attribute of a literal result element, has
the strict, and there is no matching
top-level declaration in the schema, then a
If the validation attribute of an
xsl:validation attribute of a literal result element, has
the lax, and schema validity assessment
concludes that the element or attribute is invalid, a
A type or validation attribute is defined
(explicitly or implicitly) for an instruction that constructs a new
attribute node, if the effect of this is to cause the attribute value to
be validated against a type that is derived from, or constructed by list
or union from, the primitive types xs:QName or
xs:NOTATION.
[xsl:]type AttributeThe [xsl:]type attribute takes as its value an
If the [xsl:]type attribute is present, then the newly constructed
element or attribute is validated against the type definition identified by
this attribute. Schema validation is carried out according to the process described
in [xsl:]type attribute:
fn:xsd-validator(N, {'type':T})(N) ->
if (?is-valid) then ?typed-node else error()For reasons of backwards compatibility, the error conditions raised by XSLT validation have their own error codes:
If the element or attribute is not considered valid, as defined above,
the transformation fails
If an element node is validated against the type
xs:untyped, the effect is the same as specifying
validation="strip": that is, the elements and attributes in the
subtree rooted at the target element are copied with a type annotation of
xs:untyped or xs:untypedAtomic respectively.
If an element or attribute node is validated against the type
xs:untypedAtomic, the effect is the same as specifying
[xsl:]type="xs:string" except that when validation succeeds,
the returned element or attribute has a type annotation of
xs:untypedAtomic. Validation fails in the case of an element
with element children.
It is a type attribute of an
xsl:type attribute of a literal result
element, is not a valid QName, or if it uses a prefix that
is not defined in
It is a type attribute of an
It is a type attribute of an
It is a [xsl:]type attribute is defined for a constructed element
or attribute, and the outcome of schema validity assessment against that
type is that the validity property of that element or
attribute information item is other than valid.
Like other type errors, this error may be raised statically if it can be
detected statically. For example, the instruction <xsl:attribute
name="dob" type="xs:date">1999-02-29</xsl:attribute> may
result in a static error being raised. If the error is not raised
statically, it will be raised when the instruction is evaluated.
xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributesIt is xsi:schemaLocation or xsi:noNamespaceSchemaLocation
attributes in the tree being validated. If it does so, then it
Any schema loaded using these attributes must be
Any schema loaded using these attributes must not override or redefine any schema components in the static context.
Any schema components loaded using this mechanism must be used for this validity assessment only, and must not affect the outcome of any subsequent validity assessments of other documents.
A processor may choose to cache such schema components but the existence of such a cache should only affect performance, not the validation outcome.
A consequence of validating a document using schema components that are not
in the static context is that nodes may be annotated with types
that are not in the static context. But the rules for
It is possible to apply validation to a document node. This happens when a new
document node is constructed by one of the XSLT elements type
attribute, or a validation attribute with the value
strict or lax.
Document-level validation is not applied to the document node that is created
implicitly when a variable-binding element has no select attribute
and no as attribute (see validation="preserve" on
The values validation="preserve" and validation="strip"
do not request validation. In the first case, all element and attribute nodes
within the tree rooted at the new document node retain their xs:untyped, while attributes have their type annotation set to
xs:untypedAtomic.
When validation is requested for a document node (that is, when
validation is set to strict or lax, or
when a type attribute is present), the following processing takes
place:
A
The single element node child is validated, using the supplied values of the
validation and type attributes, as described in
The type attribute on
The validation rule Validation Root Valid (ID/IDREF)
is
applied to the single element node child of the document node. This means
that validation will fail if there are non-unique ID values or dangling
IDREF values in the document tree.
Identity constraints, as defined in section 3.11 of xs:unique, xs:key, and
xs:keyref.)
There is no check that the tree contains unparsed entities whose names match
the values of nodes of type xs:ENTITY or
xs:ENTITIES. This is because there is no facility in XSLT
3.0 to create unparsed entities in a
All other children of the document node (comments and processing instructions) are copied unchanged.
It is a
xml:id attributesThis section provides a non-normative summary of the effect of validation on
attributes named xml:id. The normative rules can be inferred from rules
given elsewhere in this section.
When an attribute named xml:id is encountered
in the course of validation:
A validation error occurs if it the attribute is not lexically valid against type xs:ID.
The typed value of the attribute is whitespace-normalized.
The attribute is labeled with type annotation xs:ID.
The attribute acquires the is-id property.
The previous rule applies whether validation is strict, lax, or by type;
validation will never fail (or be skipped) on the grounds
that no global attribute declaration named xsl:id is available.
Checking xml:id attributes for uniqueness happens if and only if
validation is applied at the level of a document node.
A
The rules governing the output of the serializer are defined in
xsl:output declarationescape-solidus is provided to control
whether the character / is escaped as \/ by the
JSON serialization method.
canonical is available to give control
over serialization of XML, XHTML, and JSON.
json-lines is available to enable
output as one JSON value per line.
The
A name
attribute, if any.
An output definition is scoped to a package. If this is a
A stylesheet always includes an unnamed
A named format attribute used in an
format
attribute. It is also used when serializing the
All the cdata-section-elements
and suppress-indentation attributes, the
output definition uses the union of the values from all the constituent
use-character-maps
attribute, the output definition uses the concatenation of the sequences of
The parameter-document attribute allows serialization
parameters to be supplied in an external document. The external document must contain an
output:serialization-parameters element with the format described in
If present, the URI supplied in the parameter-document
attribute is dereferenced, after resolution against the base URI of the
A serialization parameter specified in the
parameter-document takes precedence over a value supplied directly in
the output declaration, except that the values of the
cdata-section-elements and suppress-indentation attributes
are merged in the same way as when multiple
It is a cdata-section-elements, suppress-indentation, and
use-character-maps), with the values of the attributes being not
equal, unless there is another
If the result is not serialized, then the decision whether to return the raw result
or to construct a tree depends on the build-tree attribute.
If the effective value of the build-tree attribute is yes, then a
final result tree is created by invoking the process of sequence normalization. Conversely,
if the result is serialized, then the decision whether or not to construct a tree depends
on the choice of serialization method, and the build-tree attribute is
then ignored. For example, with method="xml" a tree is always constructed,
whereas with method="json" a tree is never constructed.
The default for build-tree may differ for user-defined serialization
methods or for serialization methods introduced in future versions of this
specification.
indent parameter is now defined to be
no for all output methods other than html and xhtml.
If none of the
There are some serialization parameters that apply to some output methods but not to
others. For example, the indent attribute has no effect on the
text output method. If a value is supplied for an attribute that is
inapplicable to the output method, its value is not passed to the serializer. The
processor
An implementation
The location to which href attribute of the
The method attribute on the
The value method attribute on
xml, html, xhtml,
text, json, or adaptive.
The default for the method attribute depends on the contents of the tree
being serialized, and is chosen as follows. If the document node of the
If the html (in lower case), and namespace URI
http://www.w3.org/1999/xhtml, then the default output method is
normally xhtml. However, if the
1.0, and if the result tree is generated implicitly
(rather than by an explicit xml.
If the html (in any combination of upper and
lower case) and a null namespace URI, then the default output method is
html.
In all other cases, the default output method is xml.
The default output method is used if the selected method attribute.
The other attributes on
The value of the encoding attribute provides the value of the
encoding parameter to the serialization method. The default value
is xml and xhtml methods it UTF-8 or UTF-16.
encoding attribute of the byte-order-mark attribute is
implementation-defined.The byte-order-mark attribute defines whether a byte order mark is
written at the start of the file. If the value yes is specified, a
byte order mark is written; if no is specified, no byte order mark is
written. The default value depends on the encoding used. If the encoding is
UTF-16, the default is yes; for UTF-8 it
is no. The value of the byte order mark indicates whether high order
bytes are written before or after low order bytes; the actual byte order used is
The value of the canonical attribute provides the value of the
canonical parameter to the serialization method.
The default value is no.
The cdata-section-elements attribute is a whitespace-separated list
of QNames. The default value is an empty list. After expansion of these names
using the cdata-section-elements parameter to the serialization method. In
the case of an unprefixed name, the default namespace (that is, the namespace
declared using xmlns="uri") is used.
This differs from the rule for most other QNames used in a stylesheet. The
reason is that these names refer to elements in the result document, and
therefore follow the same convention as the name of a literal result element or
the name attribute of
The value of the doctype-system attribute provides the value of the
doctype-system parameter to the serialization method. If the attribute is absent or has a zero-length
string as its value, then the serialization parameter is not set (is
“absent”).
The value of the doctype-public attribute provides the value of the
doctype-public parameter to the serialization method. If the attribute is absent or has a zero-length
string as its value, then the serialization parameter is not set (is
“absent”).
The value of doctype-public must conform to the rules for a
The value of the escape-solidus attribute provides the value
of the escape-solidus parameter to the serialization method.
The default value is yes.
The value of the escape-uri-attributes attribute provides the value
of the escape-uri-attributes parameter to the serialization method.
The default value is yes.
The value of the html-version attribute provides
the value of the html-version parameter to the serialization method.
The set of permitted values, and the default value, are
This serialization parameter is new in version 3.0. If it is
absent, the html output method uses the value of the version
parameter in its place. For XHTML serialization, the html-version
parameter indicates the version of XHTML to be used, while the
version parameter indicates the version of XML.
The value of the include-content-type attribute provides the value
of the include-content-type parameter to the serialization method.
The default value is yes.
The value of the indent attribute provides the value of the
indent parameter to the serialization method. The default value is
yes in the case of the html and xhtml
output methods, no in the case of all other output methods.
The value of the item-separator attribute provides the value of the
item-separator parameter to the serialization method. The value of
the serialization parameter can be any string (including a zero-length string), or
absent. To set the parameter to absent, the item-separator attribute
can either be omitted, or set to the special value
item-separator="#absent"; it is not possible to set the value of
the serialization parameter to the literal 7-character string "#absent".
The item-separator attribute has no
effect if the sequence being serialized contains only one itembuild-tree is
yes
The value of the json-lines attribute determines whether the JSON
output method should output multiple JSON values in json-lines format (one
value per line). The default value is no.
The value of the json-node-output-method attribute determines how
any nodes appearing within maps or arrays are serialized by the json
output method. The default value is xml. The syntax and semantics of
the value follow the same rules as the method attribute.
The value of the media-type attribute provides the value of the
media-type parameter to the serialization method. The default
value is text/xml in the case of the xml output method,
text/html in the case of the html and
xhtml output methods, and text/plain in the case of
the text output method. json output method is application/json; the default
for the adaptive output method is
The value of the normalization-form attribute provides the value of
the normalization-form parameter to the serialization method. A value
that is an NMTOKEN other than one of those enumerated for the
normalization-form attribute specifies an implementation-defined
normalization form; the behavior in this case is not specified by this document.
The default value is none.
The value of the omit-xml-declaration attribute provides the value
of the omit-xml-declaration parameter to the serialization method.
The default value is no.
The value of the standalone attribute provides the value of the
standalone parameter to the serialization method. The default
value is omit; this means that no standalone attribute
is to be included in the XML declaration.
The suppress-indentation attribute is a whitespace-separated list of
QNames. The default value is an empty list. After expansion of these names using
the suppress-indentation parameter to the serialization method. In the
case of an unprefixed name, the default namespace (that is, the namespace declared
using xmlns="uri") is used.
This differs from the rule for most other QNames used in a stylesheet. The
reason is that these names refer to elements in the result document, and
therefore follow the same convention as the name of a literal result element or
the name attribute of
The value of the undeclare-prefixes attribute provides the value of the
undeclare-prefixes parameter to the serialization method. The default
value is no.
The use-character-maps attribute provides a list of named character
maps that are used in conjunction with this
The value of the version attribute provides the value of the
version parameter to the serialization method. The set of
permitted values, and the default value, are
version attribute of the
If the processor performs serialization, then it must raise any serialization errors that occur. These have the same
effect as
The character map that is supplied as a parameter to the serializer is determined
from the
The
The use-character-maps attribute.
The name attribute provides a name for the character map. When a character
map is used by an
The name of a character map is local to the
It is a
The optional use-character-maps attribute lists the names of further
character maps that are included into this character map.
It is a use-character-maps attribute of the name attribute of any
It is a use-character-maps attribute.
It is not an error if the same character map is referenced more than once, directly or indirectly.
For every name attribute, and the content is
a map of type map{xs:string, xs:string} that maps characters (represented as
xs:string instances of length 1) to their replacement strings.
Recursive expansion of character maps using use-character-maps
attributes may produce several mappings for the same character. In this situation,
the last character mapping takes precedence. To establish the ordering, the following
rules are used:
Within a single use-character-maps
attribute are considered before the characters defined in the child
The character maps referenced in a single use-character-maps
attribute are considered in the order in which they are listed in that
attribute. The expansion is depth-first: each referenced character map is fully
expanded before the next one is considered.
Two
The
The character map that is passed as a parameter to the serializer contains a mapping
for the character specified in the character attribute to the string
specified in the string attribute.
Character mapping is not applied to characters for which output escaping has been
disabled as described in
If a character is mapped, then it is not subjected to XML or HTML escaping.
Character maps can be useful when producing serialized output in a format that resembles, but is not strictly conformant to, HTML or XML. For example, when the output is a JSP page, there might be a need to generate the output:
Although this output is not well-formed XML or HTML, it is valid in Java Server
Pages. This can be achieved by allocating three Unicode characters (which are not
needed for any other purpose) to represent the strings <%,
%>, and ", for example:
When this character map is referenced in the
This works on the assumption that when an apostrophe or quotation mark is generated as part of an attribute value by the use of character maps, the serializer will (where possible) use the other choice of delimiter around the attribute value.
The following example illustrates a composite character map constructed in a modular fashion:
When character maps are used, there is no guarantee that the serialized output will be well-formed XML (or HTML). Furthermore, the fact that the result tree was validated against a schema gives no guarantee that the serialized output will still be valid against the same schema. Conversely, it is possible to use character maps to produce schema-valid output from a result tree that would fail validation.
The value of the string attribute must be a literal string; this
means it must consist entirely of characters that are valid in XML 1.0 or XML 1.1,
depending on the version of XML used for the containing stylesheet module. The string
can however be expressed as a shadow attribute (see <xsl:output-character char="⎘" _string="{char(0x0C)}"/>.
This depends on the processor allowing the form-feed character to appear in strings:
the data model allows this, but processors are not
The contents of a character map declared using
Delivers the content of a character map declared using
This function is
The static context for a stylesheet package includes a set of named character maps. This function delivers the content of a character map if a character map with the given name is present in the static context of the containing package, or an empty sequence otherwise.
The returned character map is in a format suitable for use within the $options
parameter of the
Consider the following character map declaration: | |
Then the result of the function call | |
This might be used in a call to the function | |
Normally, when using the XML, HTML, or XHTML output method, the serializer will
escape special characters such as & and < when
outputting text nodes. This ensures that the output is well-formed. However, it is
sometimes convenient to be able to produce output that is almost, but not quite
well-formed XML; for example, the output may include ill-formed sections which are
intended to be transformed into well-formed XML by a subsequent non-XML-aware
process. For this reason, XSLT defines a mechanism for disabling output escaping.
This feature is
This is an optional feature: it is not
This feature requires the serializer (described in disable-escaping associated with every character in a
text node. When this property is set, the normal action of the serializer to escape
special characters such as & and < is
suppressed.
An disable-output-escaping attribute; the allowed values are
yes or no. The default is no; if the value
is yes, then every character in the text node generated by evaluating
the disable-escaping property set.
For example,
should generate the single character <.
If output escaping is disabled for an
Similarly, if an
Furthermore, a request to disable output escaping has no effect when the newly
constructed text node is used to form the value of an attribute, comment, processing instruction,
or namespace node. This is because the rules for constructing such nodes (see
If output escaping is disabled for text within an element that would normally be
output using a CDATA section, because the element is listed in the
cdata-section-elements, then the relevant text will not be included
in a CDATA section. In effect, CDATA is treated as an alternative escaping mechanism,
which is disabled by the disable-output-escaping option.
For example, if <xsl:output cdata-section-elements="title"/> is
specified, then the following instructions:
should generate the output:
The disable-output-escaping attribute may be used with the
html output method as well as with the xml output
method. The text output method ignores the
disable-output-escaping attribute, since this method does not perform
any output escaping.
A
If output escaping is disabled for a character that is not representable in the
encoding that the
Since disabling output escaping might not work with all implementations and can
result in XML that is not well-formed, it
When disable-output-escaping is used, there is no guarantee that the serialized output will be well-formed XML (or HTML). Furthermore, the fact that the result tree was validated against a schema gives no guarantee that the serialized output will still be valid against the same schema. Conversely, it is possible to use disable-output-escaping to produce schema-valid output from a result tree that would fail validation.
The facility to define character maps for use during serialization, as described
in
A
The following optional features are defined:
The schema-awareness feature, defined in
The serialization feature, defined in
The backwards compatibility feature, defined in
The streaming feature, defined in
A processor that does not claim conformance with an optional feature
An XSLT processor takes as its inputs a stylesheet and zero or more XDM trees conforming to the data model defined in
The output of the XSLT processor consists of zero or more
Certain facilities in this specification are described as producing
A conforming
When a
Some errors, notably
A conforming processor
A requirement is mandatory unless the specification includes wording (such as the use of
the words
Some of the optional features are defined in such a way that if the feature is not provided, the data model is constrained to exclude certain kinds of item. For example:
A processor that does not provide the
A
It is not necessarily possible to trigger this error. A processor that does not provide an optional feature might not define or recognize any representation of the items that are disallowed. The error code is provided for use in cases where a processor is able to interoperate with other software that does not have the same constraints — for example, where a package compiled with a non-schema-aware processor is able to invoke functions in a package that was compiled with a schema-aware processor. Even in that case, processors have the option of filtering or converting the input so that it meets the relevant constraints: for example, a non-schema-aware processor when presented with a schema-validated document in the form of a PSVI might simply ignore the properties it does not understand.
The dynamic error is optional: for example a processor might report no error if the offending item is not actually used.
The phrase
A conformant processor
[xsl:]validation and [xsl:]type attributes, and the
ability to handle input documents whose nodes have type annotations other than
xs:untyped and xs:untypedAtomic. The mandatory
requirements of this specification are taken to include the mandatory requirements
of XPath 4.0, as described in
A
A processor that rejects an
A xs:untyped
or xs:untypedAtomic. Therefore, such a processor [xsl:]validation attribute
with a value of preserve or lax, or a
[xsl:]default-validation attribute with a value of
preserve as if the value were strip.
The values lax and preserve indicate that the validation
to be applied depends on the calling application, so it is appropriate for the
request to be treated differently by different kinds of processor. By contrast,
requesting strict validation, either through the
[xsl:]validation attribute or the type attribute,
indicates that the stylesheet is expecting to deal with typed data, and therefore
cannot be processed without performing the validation.
A [xsl:]type attribute; or an [xsl:]validation or
[xsl:]default-validation attribute with a value other than
strip, preserve, or
lax; or an
typed attribute is
equal to yes or strict; or an as
attribute whose value is a
xs:untyped or
xs:untypedAtomic (for example, as="element(*,
xs:integer)").
A
Atomic items
An atomic item may also belong to an implementation-defined type that has been
added to the context for use with
The set of constructor functions available are limited to those that construct values of the above atomic types.
The static context, which defines the full set of type names recognized by an
XSLT processor and also by the XPath processor, includes these atomic types,
plus xs:anyType, xs:anySimpleType,
xs:untyped, and xs:anyAtomicType.
Element nodes xs:untyped, and attribute nodes with the type annotation
xs:untypedAtomic.
xml,
xhtml, html, and text. Where the
specification uses words such as
A processor may claim conformance with the serialization feature whether or not it
supports the setting disable-output-escaping="yes" on
A processor that does not claim conformance with the serialization feature
A processor that does not claim conformance with the serialization feature
item-separator
property even if it has no other serialization capabilities.
If the processor claims conformance with
the serialization feature then it
If the processor does not claim conformance with
the serialization feature, then it
A processor that claims conformance with the Serialization
Feature must satisfy the mandatory requirements of
Note that a processor that does not claim conformance with the
The reason this is a dynamic error rather than a static error is to allow
stylesheets to contain conditional logic, following different paths depending on
whether the XSLT processor implements XSLT 1.0, 2.0, or
3.0. The selection of which path to use can be controlled by using the
xsl:version system property.
A processor that claims conformance with the
There are no incompatibilities between 3.0 and 2.0 that would
justify a 2.0-compatibility mode. When a 3.0 processor encounters a stylesheet
that specifies version="2.0", evaluation therefore proceeds exactly
as if it specified version="3.0". However, a software product may
invoke an XSLT 2.0 processor in preference to an XSLT 3.0 processor when the
stylesheet specifies version="2.0", in which case any use of new 3.0
constructs will be rejected.
There are cases where setting [xsl:]version to a value less than
4.0 affects the behavior of an XSLT 4.0 stylesheet: see
streamable="yes" on
A processor that does not claim conformance with the streaming feature is not required to use streamed processing and is not required to determine whether any construct is guaranteed streamable. Such a processor must, however, implement the semantics of all constructs in the language provided that enough memory is available to perform the processing without streaming.
A processor that conforms with the feature "yes" in response to the function call
system-property('xsl:supports-streaming'); a processor that does not
conform with the feature "no".
The term
This appendix provides a summary of error conditions that a processor
may raise. This list includes all error codes defined in this specification, but this
is not an exhaustive list of all errors that can occur. Implementations
The appendix is non-normative because the same information is given normatively elsewhere.
This appendix gives the grammar for XSLT patterns. The top-level rule for
patterns is
This is an extension of the grammar for XPath expressions.
The extended BNF notation is explained at
Productions that are identical to their counterparts in XPath 4.0 are suffixed
XP and link to the corresponding production in the XPath 4.0 specification.
Productions whose names end with P are restrictions of the corresponding
XPath production: for example, ArgumentListP is a restricted form of the
XPath production ArgumentList.
The following symbols represent portions of terminal symbols; they are not themselves terminal symbols referenced in the grammar.
This appendix provides a summary of XSLT language features whose effect is explicitly
The implementation-defined features are grouped into categories for convenience.
This category covers interfaces for initiating a transformation, setting its parameters, initializing the static and dynamic context, and collecting the results. In general terms, it is implementation defined how input is passed to the processor and how it returns its output. This includes the interpretation of URIs used to refer to stylesheet packages and modules, source documents and collections, collations, and result documents.
More specifically:
This category covers extensions and extensibility: mechanisms for providing vendor or user extensions to the language without sacrificing interoperability.
In general terms, it is implementation-defined:
whether and under what circumstances the implementation recognizes any extension functions, extension instructions, extension attributes, user-defined data elements, additional types, additional serialization methods or serialization parameters, or additional collations, and if so, what effect they have.
whether, how, and under what circumstances the implementation allows users to define extension functions, extension instructions, extension attributes, user-defined data elements, additional types, additional serialization methods or serialization parameters, or additional collations. If it does allow users to do so, it must follow the rules given elsewhere in this specification.
what information is available to such extensions (for example, whether they have access to the static and dynamic context.)
where such extensions are allowed, the extent to which the processor enforces their correct behavior (for example, checking that strings returned by extension functions contain only valid XML characters)
More specifically:
This specification, and the specifications that it refers to, include facilities for adapting the output of a transformation to meet local expectations: examples include the formatting of numbers and dates, and the choice of collations for sorted output. The general principles are:
The specification does not mandate any particular localizations that processors must offer: for example, a conformant processor might choose to provide output in Japanese only.
The specification provides fallback mechanisms so that if a particular localization is requested and is not available, processing does not fail.
More specifically:
As well as the optional conformance features identified in
When this specification refers normatively to other specifications, it generally gives implementations freedom to decide (within constraints) which version of the referenced specification should be used. Specifically:
To accommodate variations in the way that the XSLT language is deployed, and the constraints of different processing environments, defaults for some options are implementation-defined. In addition, limits on the sizes of ranges of values permitted are in general implementation-defined:
Some aspects of error handling are implementation-defined:
The functions available for use within an XSLT stylesheet can be classified based firstly, on where the function is defined, and secondly, on where it can be used. Specifically, the set of functions available is slightly different for :
Regular XPath expressions within the stylesheet, for example those appearing in
select or test attributes, or between braces in a
XPath expressions evaluated dynamically using
The categories are listed in the following table:
| Category | Defined where? | Available where? | Notes |
|---|---|---|---|
| User-defined functions | Defined using | R, D | Functions are private by default; private functions can be referenced only
within the package where they are declared (and not in |
| Constructor functions for built-in types | R, S, D | These functions are all in the namespace conventionally associated with the
prefix xs. The semantics of a constructor function are identical
to the semantics of a cast expression. | |
| Constructor functions for user-defined types | R, D (if schema-aware="yes") | This category includes a function for every named user-defined simple type in an imported schema; the function allows the conversion of strings and certain other values to instances of the user-defined type. | |
| Functions defined in XPath 4.0 | R, S, D | Includes functions in the namespaces conventionally
referred to be the prefixes fn and math. | |
| Functions defined in XSLT 4.0 | This specification | R, S (see note), D | See |
| Extension functions | Implementation-defined: see | R, S, D | Availability is |
This appendix acts as an index of functions defined in this specification, to augment
the set of functions defined in
For convenience, schemas are provided for validation of XSLT 4.0 stylesheets
using the XSD 1.1 and Relax NG schema languages. These are non-normative. Neither will detect
every static error that might arise in an XSLT 4.0 stylesheet (for example, there is no attempt
to check the syntax of XPath expressions); in addition, these schemas may reject some stylesheets
that are valid, for example because they rely on xsl:use-when to eliminate sections of code
that would otherwise be invalid.
The following XSD 1.1 schema describes the structure of an XSLT stylesheet module. There are some limitations:
It
does not define all the constraints that apply to a stylesheet (for example, it does not
attempt to define a datatype that precisely represents attributes containing XPath
Stylesheets that use [xsl:]version attribute greater than
4.0), or that have sections excluded using [xsl:]use-when
attributes, are not required to conform to the schema.
The specification allows
A copy of this schema is available at
The schema as written uses a lax wildcard to permit literal result elements to appear
in a sequence constructor. This assumes that the schema used for validation will not
contain any global element declaration that matches the element name of a literal
result element. The content model for an element such as invoice
appearing within a stylesheet is not the same as the content model for the same
element appearing within a source document (it is likely to contain XSLT instructions
rather than other elements from the target vocabulary): therefore, including such
declarations in the schema used for validating a stylesheet is inappropriate.
The reason that lax validation rather than skip validation is used is so that XSLT instructions appearing as children of the literal result element will themselves be validated, using the appropriate global element declaration.
The schema uses XSD 1.1 assertions to represent some of the non-grammatical
constraints appearing in the specification, for example the rule that some elements
can have either a select attribute or a contained sequence constructor,
but not both. At this stage, no attempt has been made to represent every such
constraint, even where it is not difficult to express the rule. There will always be
some constraints that cannot be expressed at all, for example those that require
access to multiple stylesheet modules, those that require access to the in-scope
schema components, and those that involve parsing a non-regular grammar, such as the
grammar for patterns.
Apart from assertions, the only other significant use of XSD 1.1 features is that the
elements
The following Relax-NG schema may be used to validate XSLT 4.0 stylesheet modules. Similar caveats apply as for the XSD 1.1 version.
A copy of this schema is available at
TODO: Needs updating for 4.0.
A number of changes affecting XSLT 4.0 have been made in other related specifications. Some of the more significant changes are as follows:
A number of new kinds of ItemType are introduced, for example choice item types, record types, and enumeration types.
The coercion rules (previously “function conversion rules”) allow atomic items
of primitive types to be supplied where a restricted type is required: for example
if the required type is xs:positiveInteger, it is now acceptable to supply the
value 42.
XPath 4.0 introduces abbreviated syntax for condition ?? action1 !! action2) and forfn($x, $y) { $x + $y }).
This section lists all known incompatibilities with XSLT 3.0, that is, situations
where a stylesheet that is error-free
according to the XSLT 3.0 specification and where all elements have an effective version
of 3.0 or less, will produce different results depending on whether it is
run under an XSLT 3.0 processor or an XSLT 4.0 processor.
The rules for comparing values in
The rules for matching nodes against patterns using the intersect
and except operators have changed to deliver a more intuitive result.
The rules for comparing values in
In previous versions, a template rule whose match pattern was a union pattern and that had no explicity priority was treated as equivalent to a set of template rules, one for each alternative in the union, each potentially with different default priority. This rule has not been carried forward into XSLT 4.0: instead, the priority of the rule is taken as being the highest priority of any of the alternatives.
In XSLT 4.0, an
This change in the specification applies only if the version="3.0"
to the instruction, or to some ancestor element (for example, the xsl:transform element).
A match="." (matching any item), whereas in XSLT 3.0
the implicit match pattern was match="/" (matching document nodes only). This change
is made to allow such stylesheets to be used to process JSON input, but it also has
the effect of changing the behavior of the stylesheet if it is applied to other items, such as
element or text nodes.
Non-static
This specification also corrects a number of errors and omissions in XSLT 3.0, in a way that might create incompatibilities for some processors, depending on how they interpreted the XSLT 3.0 specification:
XSLT 3.0 (and earlier releases) did not fully define the evaluation context for the
default values of template parameters. For example, if the default value of a parameter of a
template rule invoked
Where different packages import different schemas, the specification is now more prescriptive about which schema is used for validation. The rules may differ from the conventions adopted by implementations of XSLT 3.0.
XSLT 3.0 failed to specify a default value for the serialization parameter indent
where the serialization method is json or adaptive. XSLT 4.0 specifies
a default value of no.
See also