Status of this Document
This version of the specification is work in progress. It is produced by the QT4 Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual functions specified in the document may be at different stages of review, reflected in their History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.
This section describes the status of this document at the time of its publication. Other documents may supersede this document.
This document is a working draft developed and maintained by a W3C Community Group, the XQuery and XSLT Extensions Community Group unofficially known as QT4CG (where "QT" denotes Query and Transformation). This draft is work in progress and should not be considered either stable or complete. Standard W3C copyright and patent conditions apply.
The community group welcomes comments on the specification. Comments are best submitted as issues on the group's GitHub repository.
The community group maintains two extensive test suites, one oriented to XQuery and XPath, the other to XSLT. These can be found at qt4tests and xslt40-test respectively. New tests, or suggestions for correcting existing tests, are welcome. The test suites include extensive metadata describing the conditions for applicability of each test case as well as the expected results. They do not include any test drivers for executing the tests: each implementation is expected to provide its own test driver.
Dedication
The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).
Changes in 4.0 ⬇
Use the arrows to browse significant changes since the 3.1 version of this specification.
Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.
The purpose of this document is to define functions and operators for inclusion in XPath 4.0, XQuery 4.0, and XSLT 4.0. The exact syntax used to call these functions and operators is specified in [XML Path Language (XPath) 4.0], [XQuery 4.0: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0].
This document defines three classes of functions:
General purpose functions, available for direct use in user-written queries, stylesheets, and XPath expressions, whose arguments and results are values defined by the [XQuery and XPath Data Model (XDM) 3.14.0].
Constructor functions, used for creating instances of a datatype from values of (in general) a different datatype. These functions are also available for general use; they are named after the datatype that they return, and they always take a single argument.
Functions that specify the semantics of operators defined in [XML Path Language (XPath) 4.0] and [XQuery 4.0: An XML Query Language]. These exist for specification purposes only, and are not intended for direct calling from user-written code.
[XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in 2.7 Schema Information DM31 of the [XQuery and XPath Data Model (XDM) 3.1]. These functions and operations are available for use in [XML Path Language (XPath) 4.0], [XQuery 4.0: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards. [XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in 2.7 Schema Information DM31 of the [XQuery and XPath Data Model (XDM) 4.0]. These functions and operations are available for use in [XML Path Language (XPath) 4.0], [XQuery 4.0: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards. [XML Schema Part 2: Datatypes Second Edition] defines a number of primitive and derived datatypes, collectively known as built-in datatypes. This document defines functions and operations on these datatypes as well as the other types (for example, nodes and sequences of nodes) defined in 2.7 Schema Information DM31 of the [XQuery and XPath Data Model (XDM) 3.14.0]. These functions and operations are available for use in [XML Path Language (XPath) 4.0], [XQuery 4.0: An XML Query Language] and any other host language that chooses to reference them. In particular, they may be referenced in future versions of XSLT and related XML standards.
[XSD 1.1 Part 2] adds to the datatypes defined in [XML Schema Part 2: Datatypes Second Edition]. It introduces a new derived type xs:dateTimeStamp, and it incorporates as built-in types the two types xs:yearMonthDuration and xs:dayTimeDuration which were previously XDM additions to the type system. In addition, XSD 1.1 clarifies and updates many aspects of the definitions of the existing datatypes: for example, it extends the value space of xs:double to allow both positive and negative zero, and extends the lexical space to allow +INF; it modifies the value space of xs:Name to permit additional Unicode characters; it allows year zero and disallows leap seconds in xs:dateTime values; and it allows any character string to appear as the value of an xs:anyURI item. Implementations of this specification may support either XSD 1.0 or XSD 1.1 or both.
In some cases, this specification references XSD for the semantics of operations such as the effect of matching using regular expressions, or conversion of atomic items to strings. In most such cases there is no intended technical difference between the XSD 1.0 and XSD 1.1 specifications, but the 1.1 version often provides clearer explanations and sometimes also corrects technical errors. In such cases this specification often chooses to reference the XSD 1.1 specification. This should not be taken as implying that it is necessary to invoke an XSD 1.1 processor.
References to specific sections of some of the above documents are indicated by cross-document links in this document. Each such link consists of a pointer to a specific section followed a superscript specifying the linked document. The superscripts have the following meanings: XQ [XQuery 4.0: An XML Query Language], XT [XSL Transformations (XSLT) Version 4.0], XP [XML Path Language (XPath) 4.0], and DM [XQuery and XPath Data Model (XDM) 4.0].
Changes in 4.0 ⬇ ⬆
Higher-order functions are no longer an optional feature. [Issue 205 PR 326 1 February 2023]
This recommendation contains a set of function specifications. It defines conformance at the level of individual functions. An implementation of a function conforms to a function specification in this recommendation if all the following conditions are satisfied:
For all combinations of valid inputs to the function (both explicit arguments and implicit context dependencies), the result of the function meets the mandatory requirements of this specification.
For all invalid inputs to the function, the implementation raises (in some way appropriate to the calling environment) a dynamic error.
For a sequence of calls within the same execution scope, the requirements of this recommendation regarding the determinism of results are satisfied (see 1.9.5 Properties of functions).
Other recommendations (“host languages”) that reference this document may dictate:
Subsets or supersets of this set of functions to be available in particular environments;
Mechanisms for invoking functions, supplying arguments, initializing the static and dynamic context, receiving results, and handling errors;
A concrete realization of concepts such as execution scope;
Which versions of other specifications referenced herein (for example, XML, XSD, or Unicode) are to be used.
Any behavior that is discretionary (implementation-defined or implementation-dependent) in this specification may be constrained by a host language.
Note:
Adding such constraints in a host language, however, is discouraged because it makes it difficult to reuse implementations of the function library across host languages.
This specification allows flexibility in the choice of versions of specifications on which it depends:
It is implementation-defined which version of Unicode is supported, but it is recommended that the most recent version of Unicode be used.
It is implementation-defined whether the type system is based on XML Schema 1.0 or XML Schema 1.1.
It is implementation-defined whether definitions that rely on XML (for example, the set of valid XML characters) should use the definitions in XML 1.0 or XML 1.1.
Note:
The XML Schema 1.1 recommendation introduces one new concrete datatype: xs:dateTimeStamp; it also incorporates the types xs:dayTimeDuration, xs:yearMonthDuration, and xs:anyAtomicType which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 3.1]. Furthermore, XSD 1.1 includes the option of supporting revised definitions of types such as xs:NCName based on the rules in XML 1.1 rather than 1.0.The XML Schema 1.1 recommendation introduces one new concrete datatype: xs:dateTimeStamp; it also incorporates the types xs:dayTimeDuration, xs:yearMonthDuration, and xs:anyAtomicType which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 4.0]. Furthermore, XSD 1.1 includes the option of supporting revised definitions of types such as xs:NCName based on the rules in XML 1.1 rather than 1.0.The XML Schema 1.1 recommendation introduces one new concrete datatype: xs:dateTimeStamp; it also incorporates the types xs:dayTimeDuration, xs:yearMonthDuration, and xs:anyAtomicType which were previously defined in earlier versions of [XQuery and XPath Data Model (XDM) 3.14.0]. Furthermore, XSD 1.1 includes the option of supporting revised definitions of types such as xs:NCName based on the rules in XML 1.1 rather than 1.0.
The [XQuery and XPath Data Model (XDM) 4.0] allows flexibility in the repertoire of characters permitted during processing that goes beyond even what version of XML is supported. A processor may allow the user to construct nodes and atomic items that contain characters not allowed by any version of XML. [Definition] A permitted character is one within the repertoire accepted by the implementation.
In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.
The functions and operators defined in this document are contained in one of several namespaces (see [Namespaces in XML]) and referenced using an xs:QName.
This document uses conventional prefixes to refer to these namespaces. User-written applications can choose a different prefix to refer to the namespace, so long as it is bound to the correct URI. The host language may also define a default namespace for function calls, in which case function names in that namespace need not be prefixed at all. In many cases the default namespace will be http://www.w3.org/2005/xpath-functions, allowing a call on the fn:name function (for example) to be written as name() rather than fn:name(); in this document, however, all example function calls are explicitly prefixed.
The URIs of the namespaces and the conventional prefixes associated with them are:
http://www.w3.org/2001/XMLSchema for constructors — associated with xs.
The section 22 Constructor functions defines constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.1]. These datatypes and the corresponding constructor functions are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema, and are named in this document using the xs prefix. The section 22 Constructor functions defines constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 4.0]. These datatypes and the corresponding constructor functions are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema, and are named in this document using the xs prefix. The section 22 Constructor functions defines constructor functions for the built-in datatypes defined in [XML Schema Part 2: Datatypes Second Edition] and in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.14.0]. These datatypes and the corresponding constructor functions are in the XML Schema namespace, http://www.w3.org/2001/XMLSchema, and are named in this document using the xs prefix.
http://www.w3.org/2005/xpath-functions for functions — associated with fn.
The namespace prefix used in this document for most functions that are available to users is fn.
http://www.w3.org/2005/xpath-functions/math for functions — associated with math.
This namespace is used for some mathematical functions. The namespace prefix used in this document for these functions is math. These functions are available to users in exactly the same way as those in the fn namespace.
http://www.w3.org/2005/xpath-functions/map for functions — associated with map.
This namespace is used for some functions that manipulate maps (see 14.4 Functions that operate on maps). The namespace prefix used in this document for these functions is map. These functions are available to users in exactly the same way as those in the fn namespace.
http://www.w3.org/2005/xpath-functions/array for functions — associated with array.
This namespace is used for some functions that manipulate maps (see 15.2 Functions that operate on arrays). The namespace prefix used in this document for these functions is array. These functions are available to users in exactly the same way as those in the fn namespace.
http://www.w3.org/2005/xqt-errors — associated with err.
There are no functions in this namespace; it is used for error codes.
This document uses the prefix err to represent the namespace URI http://www.w3.org/2005/xqt-errors, which is the namespace for all XPath and XQuery error codes and messages. This namespace prefix is not predeclared and its use in this document is not normative.
http://www.w3.org/2010/xslt-xquery-serialization — associated with output.
There are no functions in this namespace: it is used for serialization parameters, as described in [XSLT and XQuery Serialization 3.1]
Functions defined with the op prefix are described here to underpin the definitions of the operators in [XML Path Language (XPath) 4.0], [XQuery 4.0: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0]. These functions are not available directly to users, and there is no requirement that implementations should actually provide these functions. For this reason, no namespace is associated with the op prefix. For example, multiplication is generally associated with the * operator, but it is described as a function in this document:
op:numeric-multiply( |
$arg1 | as xs:numeric | |
$arg2 | as xs:numeric | |
) as xs:numeric |
Sometimes there is a need to use an operator as a function. To meet this requirement, the function fn:op takes any simple binary operator as its argument, and returns a corresponding function. So for example fn:for-each-pair($seq1, $seq2, op("+")) performs a pairwise addition of the values in two input sequences.
Note:
The above namespace URIs are not expected to change from one version of this document to another. The contents of these namespaces may be extended to allow additional functions (and errors, and serialization parameters) to be defined.
Each function (or group of functions having the same name) is defined in this specification using a standard proforma. This has the following sections:
Some functions supplement the prose rules with a more formal specification that describes the effect of the function in terms of an equivalent XPath or XQuery implementation. This is intended to take precedence over the prose rules in the event of any conflict; however, both sections are intended to be complete and not to rely on each other.
In writing the formal equivalents, a number of guidelines have been followed:
Where the equivalent code calls other functions, these should either be primitives defined in the data model specification (see [XQuery and XPath Data Model (XDM) 3.14.0]), or functions that themselves have a formal equivalent; and the dependencies should not be circular.
There should be minimal reliance on XPath or XQuery language features. Although no attempt has been made to precisely define a core set of language constructs, the specifications try to avoid relying on features other than function calls and a few basic operators including the comma operator, equality testing, and simple integer arithmetic.
There is no suggestion that the formal equivalent is a practical implementation; in many cases it might have very poor performance.
In some cases the formal equivalent does not attempt to replicate correct behavior in error cases; if so, this is always clearly stated.
The formal equivalent will always produce a conformant result for the function, but in some cases this will not be the only possible conformant result.
| Editorial note | |
| This worthy intent is not yet fully achieved; for example there are formal specifications that invoke fn:atomic-equal. |
There is no attempt to write formal equivalents for functions that have complex logic (such as fn:format-number) or dependencies (such as fn:doc); the aim of the formal equivalents is to define as rigorously as possible a platform of basic functionality that can be used as a solid foundation for more complex features.
Changes in 4.0 ⬇ ⬆
The term atomic value has been replaced by atomic item. [Issue 1337 PR 1361 2 August 2024]
The terminology used to describe the functions and operators on types defined in [XML Schema Part 2: Datatypes Second Edition] is defined in the body of this specification. The terms defined in this section are used in building those definitions.
This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.1], and which are paraphrased here for ease of reference:This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 4.0], and which are paraphrased here for ease of reference:This document uses the terms string, character, and codepoint with meanings that are normatively defined in [XQuery and XPath Data Model (XDM) 3.14.0], and which are paraphrased here for ease of reference:
[Definition] A character is an instance of the CharXML production of [Extensible Markup Language (XML) 1.0 (Fifth Edition)].
Note:
This definition excludes Unicode characters in the surrogate blocks as well as U+FFFE and U+FFFF, while including characters with codepoints greater than U+FFFF which some programming languages treat as two characters. The valid characters are defined by their codepoints, and include some whose codepoints have not been assigned by the Unicode consortium to any character.
[Definition] A string is a sequence of zero or more characters, or equivalently, a value in the value space of the xs:string datatype.
[Definition] A codepoint is an integer assigned to a character by the Unicode consortium, or reserved for future assignment to a character.
Note:
The set of codepoints is thus wider than the set of characters.
This specification spells “codepoint” as one word; the Unicode specification spells it as “code point”. Equivalent terms found in other specifications are “character number” or “code position”. See [Character Model for the World Wide Web 1.0: Fundamentals]
Because these terms appear so frequently, they are hyperlinked to the definition only when there is a particular desire to draw the reader’s attention to the definition; the absence of a hyperlink does not mean that the term is being used in some other sense.
It is implementation-defined which version of [The Unicode Standard] is supported, but it is recommended that the most recent version of Unicode be used.
This specification adopts the Unicode notation U+xxxx to refer to a codepoint by its hexadecimal value (always four to six hexadecimal digits). This is followed where appropriate by the official Unicode character name and its graphical representation: for example U+20AC (EURO SIGN, €) .
Unless explicitly stated, the functions in this document do not ensure that any returned xs:string values are normalized in the sense of [Character Model for the World Wide Web 1.0: Fundamentals].
Note:
In functions that involve character counting such as fn:substring, fn:string-length and fn:translate, what is counted is the number of XML characters in the string (or equivalently, the number of Unicode codepoints). Some implementations may represent a codepoint above U+FFFF using two 16-bit values known as a surrogate pair. A surrogate pair counts as one character, not two.
Accessors and their semantics are described in [XQuery and XPath Data Model (XDM) 3.14.0]. Some of these accessors are exposed to the user through the functions described below.
Each of these functions has an arity-zero signature which is equivalent to the arity-one form, with the context value supplied as the implicit first argument. In addition, each of the arity-one functions accepts an empty sequence as the argument, in which case it generally delivers an empty sequence as the result: the exception is fn:string, which delivers a zero-length string.
| Function | Accessor | Accepts | Returns |
|---|
fn:node-name | node-name | node (optional) | xs:QName (optional) |
fn:nilled | nilled | node (optional) | xs:boolean (optional) |
fn:string | string-value | item (optional) | xs:string |
fn:data | typed-value | zero or more items | a sequence of atomic items |
fn:base-uri | base-uri | node (optional) | xs:anyURI (optional) |
fn:document-uri | document-uri | node (optional) | xs:anyURI (optional) |
| Function | Meaning |
|---|
fn:base-uri | Returns the base URI of a node. |
fn:document-uri | Returns the URI of a resource where a document can be found, if available. |
fn:nilled | Returns true for an element that is nilled. |
fn:node-name | Returns the name of a node, as an xs:QName. |
fn:string | Returns the value of $value represented as an xs:string. |
fn:data | Returns the result of atomizing a sequence. This process flattens arrays, and replaces nodes by their typed values. |
Changes in 4.0 ⬇ ⬆
Constructor functions now have a zero-arity form; the first argument defaults to the context item. [Issue 658 PR 662 29 August 2023]
Constructor functions are used to convert a supplied value to a given type, and the name of the function is the same as the name of the target type. This section describes constructor functions corresponding to the following types:
Constructor functions are defined for all user-defined named simple types, and for most built-in atomic, list, and union types. The only named simple types that have no constructor function are those that have no instances other than instances of their derived types: specifically, xs:anySimpleType, xs:anyAtomicType, and xs:NOTATION.
There is a constructor function for the union type xs:numeric defined in [XQuery and XPath Data Model (XDM) 3.1]. The function signature is:There is a constructor function for the union type xs:numeric defined in [XQuery and XPath Data Model (XDM) 4.0]. The function signature is:There is a constructor function for the union type xs:numeric defined in [XQuery and XPath Data Model (XDM) 3.14.0]. The function signature is:
xs:numeric( |
$value | as xs:anyAtomicType? | := . |
) as xs:numeric? |
The semantics are determined by the rules in 23.3.7 Casting to union types. These rules have the effect that:
If the argument is an instance of xs:double, xs:float, or xs:decimal, then the result is an instance of the same primitive type, with the same value;
If the argument is an instance of xs:boolean, the result is the xs:double value 0.0e0 or 1.0e0;
If the argument is an instance of xs:string or xs:untypedAtomic, then:
If the value is in the lexical space of xs:double, the result will be the corresponding xs:double value;
Otherwise, a dynamic error [err:FORG0001] occurs;
Note:
The result will never be an instance of xs:float, xs:decimal, or xs:integer. This is because xs:double appears first in the list of member types of xs:numeric, and its lexical space subsumes the lexical space of the other numeric types. Thus, unlike XPath numeric literals, the result does not depend on the lexical form of the supplied value. The reason for this design choice is to retain compatibility with the function conversion rules: functions such as fn:abs and fn:round are declared to expect an instance of xs:numeric as their first or only argument, and compatibility with the function conversion rules defined in earlier versions of these specifications demands that when an untyped atomic item (or untyped node) is supplied as the argument, it is converted to an xs:double value even if its lexical form is that (say) of an integer.
In all other cases, a dynamic error [err:FORG0001] occurs.
In the case of an implementation that supports XSD 1.1, there is a constructor function associated with the built-in union type xs:error.
The function signature is as follows:
xs:error( |
$value | as xs:anyAtomicType? | := . |
) as xs:error? |
The semantics are equivalent to casting to the corresponding union type (see 23.3.7 Casting to union types).
Note:
Because xs:error has no member types, and therefore has an empty value space, casting will always fail with a dynamic error except in the case where the supplied argument is an empty sequence, in which case the result is also an empty sequence.
Constructor functions and cast expressions accept an expression and return a value of a given type. They both convert a source value SV, of a source type, ST to a target value TV, of the given target type TT.
Constructor functions and cast expressions have identical semantics but different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.1] (see 22.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 22.5 Constructor functions for user-defined atomic and union types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example, xs:date("2003-01-01") means exactly the same as "2003-01-01" cast as xs:date?.Constructor functions and cast expressions have identical semantics but different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 4.0] (see 22.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 22.5 Constructor functions for user-defined atomic and union types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example, xs:date("2003-01-01") means exactly the same as "2003-01-01" cast as xs:date?.Constructor functions and cast expressions have identical semantics but different syntax. The name of the constructor function is the same as the name of the built-in [XML Schema Part 2: Datatypes Second Edition] datatype or the datatype defined in 2.7 Schema Information DM31 of [XQuery and XPath Data Model (XDM) 3.14.0] (see 22.1 Constructor functions for XML Schema built-in atomic types) or the user-derived datatype (see 22.5 Constructor functions for user-defined atomic and union types) that is the target for the conversion, and the semantics are exactly the same as for a cast expression; for example, xs:date("2003-01-01") means exactly the same as "2003-01-01" cast as xs:date?.
The cast expression takes a type name to indicate the target type of the conversion. See 3.14.2 Cast XP31. If the type name allows the empty sequence and the expression to be cast is the empty sequence, the empty sequence is returned. If the type name does not allow the empty sequence and the expression to be cast is the empty sequence, a type error is raised [err:XPTY0004]XP.
Where the argument to a cast is a literal, the result of the function may be evaluated statically; if an error is encountered during such evaluation, it may be reported as a static error.
The general rules for casting from primitive types to primitive types are defined in 23.1 Casting from primitive types to primitive types, and subsections describe the rules for specific target types. The general rules for casting from xs:string (and xs:untypedAtomic) follow in 23.2 Casting from xs:string and xs:untypedAtomic. Casting to non-primitive types, including atomic types derived by restriction, union types, and list types, is described in 23.3 Casting involving non-primitive types. Casting from derived types is defined in 23.3.4 Casting from derived types to parent types, 23.3.5 Casting within a branch of the type hierarchy and 23.3.6 Casting across the type hierarchy.
Casting is not supported to or from xs:anySimpleType. Casting to xs:anySimpleType is not permitted and raises a static error: [err:XPST0080]XP.
Similarly, casting is not supported to or from xs:anyAtomicType and will raise a static error: [err:XPST0080]XP. There are no atomic items with the type annotation xs:anyAtomicType, although this can be a statically inferred type.