20.2.1 The xsl:key Declaration

<!-- Category: declaration -->
<xsl:key
  name = eqname
  match = pattern
  use? = expression
  composite? = boolean
  collation? = uri >
  <!-- Content: sequence-constructor -->
</xsl:key>

The xsl:key declaration is used to declare keys. The name attribute specifies the name of the key. The value of the name attribute is an EQName, which is expanded as described in 5.1.1 Qualified Names. The match attribute is a Pattern; an xsl:key element applies to all nodes that match the pattern specified in the match attribute.

[Definition: A key is defined as a set of xsl:key declarations in the same package that share the same name.]

The key name is scoped to the containing package, and is available for use in calls to the key function within that package.

The value of the key may be specified either using the use attribute or by means of the contained sequence constructor.

[ERR XTSE1205] It is a static error if an xsl:key declaration has 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 expression specifying the values of the key. The expression will be evaluated with a singleton focus based on the node that matches the pattern. The result of evaluating the expression is atomized.

Similarly, if a sequence constructor is present, it is used to determine the values of the key. The sequence constructor will be evaluated with the node that matches the pattern as the context node. The result of evaluating the sequence constructor is atomized.

[Definition: The expression in the use attribute and the sequence constructor within an xsl:key declaration are referred to collectively as the key specifier. The key specifier determines the values that may be used to find a node using this key.]

When evaluation of the key specifier results in a sequence (after atomization) containing more than one atomic value, the effect depends on the value of the composite attribute:

• When the attribute is absent or has the value no, each atomic value 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 values 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 xsl:key declarations in the same package with the same key name, then they must all have the same effective value for their composite attribute. The effective value is the actual value of the attribute if present, or "no" if the attribute is absent.

The presence of an xsl:key declaration makes it easy to find a node that matches the match pattern if the values of the key specifier (when applied to that node) are known. It also provides a hint to the implementation that access to the nodes by means of these values needs to be efficient (many implementations are likely to construct an index or hash table to achieve this).

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) is true. The effective collation for an xsl:key declaration is the collation specified in its collation attribute if present, resolved against the base URI of the xsl:key element, or the default collation that is in scope for the xsl:key declaration otherwise; the effective collation must be the same for all the xsl:key declarations making up a key.

[ERR XTSE1210] It is a static error if the xsl:key declaration has a collation attribute whose value (after resolving against the base URI) is not a URI recognized by the implementation as referring to a collation.

[ERR XTSE1220] It is a static error if there are several xsl:key declarations in the same package with the same key name and different effective collations. Two collations are the same if their URIs are equal under the rules for comparing xs:anyURI values, or if the implementation can determine that they are different URIs referring to the same collation.

[ERR XTSE1222] It is a static error if there are several xsl:key declarations in a package with the same key name and different effective values for the composite attribute.

It is possible to have:

• multiple xsl:key declarations with the same name;

• a node that matches the match patterns of several different xsl:key declarations, whether these have the same key name or different key names;

• a node that returns more than one value from its key specifier (which can be treated either as separate individual key values, or as a single composite key value);

• a key value that identifies more than one node (the key values for different nodes do not need to be unique).

An xsl:key declaration with higher import precedence does not override another of lower import precedence; all the xsl:key declarations in the stylesheet are effective regardless of their import precedence.

20.2.2 fn:key

Summary

Returns the nodes that match a supplied key value.

Signatures

fn:key(	$key-name	as xs:string,
	$key-value	as xs:anyAtomicType*) as node()*

fn:key(	$key-name	as xs:string,
	$key-value	as xs:anyAtomicType*,
	$top	as node()) as node()*

Properties

The two-argument form of this function is deterministic^FO30, focus-dependent^FO30, and context-dependent^FO30.

The three-argument form of this function is deterministic^FO30, focus-independent^FO30, and context-dependent^FO30.

Rules

The key function does for keys what the element-with-id^FO30 function does for IDs.

The $key-name argument specifies the name of the key. The value of the argument must be a string containing an EQName. If it is a lexical QName, then it is expanded as described in 5.1.1 Qualified Names (no prefix means no namespace).

The $key-value argument to the key function is considered as a sequence. The effect depends on the value of 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 function conversion rules. Each of the resulting atomic values is considered as a requested key value. The result of the function is a sequence of nodes, in document order and with duplicates removed, comprising those nodes in the selected subtree (see below) that are matched by an xsl:key declaration whose name is the same as the supplied key name, where the result of evaluating the key specifier contains a value that is equal to one of these requested key values, under the rules appropriate to the XPath eq operator for the two values in question, using the collation attributes of the xsl:key declaration when comparing strings. No error is reported if two values are encountered that are not comparable; they are regarded for the purposes of this function as being not equal.

  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 function conversion rules. The result of the function is a sequence of nodes, in document order and with duplicates removed, comprising those nodes in the selected subtree (see below) that are matched by an xsl:key declaration whose name is the same as the supplied key name, where the result of evaluating the key specifier is deep-equal to the requested key value, under the rules appropriate to the deep-equal^FO30 function applied to the two values in question, using the collation attributes of the xsl:key declaration when comparing strings. Note that the deep-equal^FO30 function reports no error if two values are encountered that are not comparable; they are regarded for the purposes of this function as being not equal.

  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.

Different rules apply when XSLT 1.0 compatible behavior is enabled.

A key (that is, a set of xsl:key declarations sharing the same key name) is processed in backwards compatible mode if (a) at least one of the xsl:key elements in the definition of the key enables backwards compatible behavior, and (b) the effective value of the composite attribute is no.

When a key is processed in backwards compatible mode, then:

• The result of evaluating the key specifier in any xsl:key declaration having this key name is converted after atomization to a sequence of strings, by applying a cast to each item in the sequence.

• When the first argument to the key function specifies this key name, then the value of the second argument is converted after atomization to a sequence of strings, by applying a cast to each item in the sequence. The values are then compared as strings.

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 key function can be described more specifically as follows. The result is a sequence containing every node $N that satisfies the following conditions:

• $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 xsl:key declaration whose name attribute matches the name specified in the $key-name argument.

• When composite="no", and the key specifier of that xsl:key declaration is evaluated with a singleton focus based on $N, the atomized value of the resulting sequence includes a value that compares equal to at least one item in the atomized value of the sequence supplied as $key-value, under the rules of the eq operator with the collation selected as described above.

  When composite="yes", and the key specifier of that xsl:key declaration is evaluated with a singleton focus based on $N, the atomized value of the resulting sequence compares equal to the atomized value of the sequence supplied as $key-value, under the rules of the deep-equal^FO30 function with the collation selected as described above.

The sequence returned by the key function will be in document order, with duplicates (that is, nodes having the same identity) removed.

Error Conditions

[ERR XTDE1260] It is a dynamic error if the value 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 xsl:key declaration in the containing package. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

[ERR XTDE1270] It is a dynamic error to call the key function with two arguments if there is no context node, or if the root of the tree containing the context node is not a document node; or to call the function with three arguments if the root of the tree containing the node supplied in the third argument is not a document node.

Notes

Untyped atomic values 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 value in the call to the key function will return an empty sequence.

Examples

Example: Using a Key to Follow Cross-References

Given a declaration

<xsl:key name="idkey" match="div" use="@id"/>

an expression key("idkey",@ref) will return the same nodes as id(@ref), assuming that the only ID attribute declared in the XML source document is:

<!ATTLIST div id ID #IMPLIED>

and that the ref attribute of the context node contains no whitespace.

 

Example: Using a Key to Generate Hyperlinks

Suppose a document describing a function library uses a prototype element to define functions

<prototype name="sqrt" return-type="xs:double">
  <arg type="xs:double"/>
</prototype>

and a function element to refer to function names

<function>sqrt</function>

Then the stylesheet could generate hyperlinks between the references and definitions as follows:

<xsl:key name="func" match="prototype" use="@name"/>

<xsl:template match="function">
<b>
  <a href="#{generate-id(key('func',.))}">
    <xsl:apply-templates/>
  </a>
</b>
</xsl:template>

<xsl:template match="prototype">
  <p>
    <a name="{generate-id()}">
      <b>Function: </b>
      ...
    </a>
  </p>
  </xsl:template>

When called with two arguments, the key function always returns nodes that are in the same document as the context node. To retrieve a node from any other document, it is necessary either to change the context node, or to supply a third argument.

Example: Using Keys to Reference other Documents

For example, suppose a document contains bibliographic references in the form <bibref>XSLT</bibref>, and there is a separate XML document bib.xml containing a bibliographic database with entries in the form:

<entry name="XSLT">...</entry>

Then the stylesheet could use the following to transform the bibref elements:

<xsl:key name="bib" match="entry" use="@name"/>

<xsl:template match="bibref">
  <xsl:variable name="name" select="."/>
  <xsl:apply-templates select="document('bib.xml')/key('bib',$name)"/>
</xsl:template>

Note:

This relies on the ability in XPath 2.0 to have a function call on the right-hand side of the / operator in a path expression.

The following code would also work:

<xsl:key name="bib" match="entry" use="@name"/>

<xsl:template match="bibref">
  <xsl:apply-templates select="key('bib', ., document('bib.xml'))"/>
</xsl:template>

 

Example: Using a Composite Key

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:

<xsl:key name="emp-name-key" 
         match="employee" 
         use="name/first, name/last" 
         composite="yes"/>                     
         

A particular employee can then be located using the function call:

key('emp-name-key', ('Tim', 'Berners-Lee'), doc('employees.xml'))

20.4.1 fn:current

Summary

Returns the item that is the context item for the evaluation of the containing XPath expression

Signature

fn:current() as item()

Properties

This function is deterministic^FO30, context-dependent^FO30, and focus-dependent^FO30.

Rules

The current function, used within an XPath expression, returns the item that was the context item at the point where the expression was invoked from the XSLT stylesheet. This is referred to as the current item. For an outermost expression (an expression not occurring within another expression), the current item is always the same as the context item. Thus,

<xsl:value-of select="current()"/>

means the same as

<xsl:value-of select="."/>

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 current function is used within a pattern, its value is the item that is being matched against the pattern.

Error Conditions

[ERR XTDE1360] If the current function is evaluated within an expression that is evaluated when the context item is absent, a dynamic error occurs.

When the current is called by means of a dynamic function call (for example, current#0()), it is evaluated as if the context item is absent ([see ERR XTDE1360]).

Examples

The instruction:

<xsl:apply-templates select="//glossary/entry[@name=current()/@ref]"/>

will process all entry elements that have a glossary parent element and that have a name attribute with value equal to the value of the current item's ref attribute. This is different from

<xsl:apply-templates select="//glossary/entry[@name=./@ref]"/>

which means the same as

<xsl:apply-templates select="//glossary/entry[@name=@ref]"/>

and so would process all entry elements that have a glossary parent element and that have a name attribute and a ref attribute with the same value.

20.4.2 fn:unparsed-entity-uri

Summary

Returns the URI (system identifier) of an unparsed entity

Signatures

fn:unparsed-entity-uri($entity-name as xs:string) as xs:anyURI

fn:unparsed-entity-uri(	$entity-name	as xs:string,
	$doc	as node()) as xs:anyURI

Properties

This function is deterministic^FO30, focus-dependent^FO30, and context-dependent^FO30.

Rules

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 unparsed-entity-uri function returns the URI of the unparsed entity whose name is given by the value of the $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 [XDM 3.0].

Error Conditions

[ERR XTDE1370] It is a dynamic error if $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, dynamic error [ERR XPDY0002] ^XP30.

• If the context item is not a node, type error [ERR XPTY0004] ^XP30.

Notes

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 unparsed-entity-uri function should return the system identifier as written, without any attempt to make it absolute.

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 should be respected during construction of the data model; the data model instance should not contain more than one unparsed entity with the same name.

20.4.3 fn:unparsed-entity-public-id

Summary

Returns the public identifier of an unparsed entity

Signatures

fn:unparsed-entity-public-id($entity-name as xs:string) as xs:string

fn:unparsed-entity-public-id(	$entity-name	as xs:string,
	$doc	as node()) as xs:string

Properties

This function is deterministic^FO30, focus-dependent^FO30, and context-dependent^FO30.

Rules

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 unparsed-entity-public-id function returns the public identifier of the unparsed entity whose name is given by the value of the $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 [XDM 3.0].

Error Conditions

[ERR XTDE1380] It is a dynamic error if $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, dynamic error [ERR XPDY0002] ^XP30.

• If the context item is not a node, type error [ERR XPTY0004] ^XP30.

Notes

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 should be respected during construction of the data model; the data model instance should not contain more than one unparsed entity with the same name.

20.4.4 fn:system-property

Summary

Returns the value of a system property

Signature

fn:system-property($property-name as xs:string) as xs:string

Properties

This function is deterministic^FO30, focus-independent^FO30, and context-dependent^FO30. It depends on namespaces.

Rules

The value of the $property-name argument must be a string containing an EQName. If it is a lexical QName with a prefix, then it is expanded into an expanded QName using the namespace declarations in the static context of the expression. If there is no prefix, the name is taken as being in no namespace.

The system-property function returns a string representing the value of the system property identified by the name. If there is no such system property, the zero-length string is returned.

Implementations must provide the following system properties, which are all in the XSLT namespace:

• xsl:version, a number giving the version of XSLT implemented by the processor; for implementations conforming to the version of XSLT specified by this document, this is the string "3.0". The value will always be a string in the lexical space of the decimal datatype defined in XML Schema (see [XML Schema Part 2]). This allows the value to be converted to a number for the purpose of magnitude comparisons.

• xsl:vendor, a string identifying the implementer of the processor

• xsl:vendor-url, a string containing a URL identifying the implementer of the processor; typically this is the host page (home page) of the implementer's Web site.

• xsl:product-name, a string containing the name of the implementation, as defined by the implementer. This should normally remain constant from one release of the product to the next. It should also be constant across platforms in cases where the same source code is used to produce compatible products for multiple execution platforms.

• xsl:product-version, a string identifying the version of the implementation, as defined by the implementer. This should normally vary from one release of the product to the next, and at the discretion of the implementer it may also vary across different execution platforms.

• xsl:is-schema-aware, returns the string "yes" in the case of a processor that claims conformance as a schema-aware XSLT processor, or "no" in the case of a basic XSLT processor.

• xsl:supports-serialization, returns the string "yes" in the case of a processor that offers the serialization feature, or "no" otherwise.

• xsl:supports-backwards-compatibility, returns the string "yes" in the case of a processor that offers the XSLT 1.0 compatibility feature, or "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 27.5 Streaming Feature), or "no" otherwise.

• xsl:supports-dynamic-evaluation, returns the string "yes" in the case of a processor that offers the dynamic evaluation feature (see 27.6 Dynamic Evaluation Feature), or "no" otherwise.

• xsl:supports-higher-order-functions, returns the string "yes" in the case of a processor that offers the higher-order functions feature, or "no" otherwise.

• xsl:xpath-version, a number giving the version of XPath implemented by the processor. The value will always be a string in the lexical space of the decimal datatype defined in XML Schema (see [XML Schema Part 2]). This allows the value to be converted to a number for the purpose of magnitude comparisons. Typical values are "3.0" or "3.1". The value "3.0" indicates that the processor implements XPath 3.0 plus the extensions defined in 21 Maps and 22 Processing JSON Data.

• xsl:xsd-version, a number giving the version of XSD (XML Schema) implemented by the processor. The value will always be a string in the lexical space of the decimal datatype defined in XML Schema (see [XML Schema Part 2]). This allows the value to be converted to a number for the purpose of magnitude comparisons. Typical values are "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 processor: these options are described in 27 Conformance.

The actual values returned for the above properties are implementation-defined.

The set of system properties that are supported, in addition to those listed above, is also implementation-defined. Implementations must not define additional system properties in the XSLT namespace.

Error Conditions

[ERR XTDE1390] It is a dynamic error if the value supplied as the $property-name argument is not a valid QName, or if there is no namespace declaration in scope for the prefix of the QName. If the processor is able to detect the error statically (for example, when the argument is supplied as a string literal), then the processor may optionally signal this as a static error.

Notes

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 element-available and function-available functions to allow users to test which features have been fully implemented.

20.4.5 fn:available-system-properties

Summary

Returns a list of system property names that are suitable for passing to the system-property function, as a sequence of QNames.

Signature

fn:available-system-properties() as xs:QName*

Properties

This function is deterministic^FO30, context-independent^FO30, and focus-independent^FO30.

Rules

The function returns a sequence of QNames, being the names of the system properties recognized by the processor, in some implementation-dependent order.

The prefix part of a returned QName is implementation-dependent.

The function is deterministic^FO30: that is, the set of available system properties does not vary during the course of a transformation.

Notes

The function returns a list of QNames, containing no duplicates.

It is intended that the QNames in this list should be suitable for passing to system-property. However, they must first be converted to the form expected by the system-property function, which is either a lexical QName or to an EQName in the form 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:

<xsl:function name="f:QName-to-brace-notation" as="xs:string">
  <xsl:param name="qname" as="xs:QName"/>
  <xsl:sequence select="'Q{' || namespace-uri-from-QName($qname) || '}' 
                             || local-name-from-QName($qname)"/>
</xsl:function>