Status of this Document
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.
As the Community Group moves towards publishing dated, stable drafts, some features that the group thinks may likely be removed or substantially changed are marked “at risk” in their changes section. In this draft:
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 (next | previous)
New functions are provided to obtain information about built-in types and types defined in an imported schema. [Issue 148 PR 1523 5 November 2024]
The functions in this section deliver information about schema types (including simple types and complex types). These may represent built-in types (such as xs:dateTime), user-defined types found in the static context (typically because they appear in an imported schema), or types used as type annotations on schema-validated nodes.
For more information on schema types, see 1.8.2 Schema Type Hierarchy. The properties of a schema type are described in terms of the properties of a Simple Type Definition or Complex Type Definition component as described in 3.16.1 The Simple Type Definition Schema Component XS11-1 and 3.4.1 The Complex Type Definition Schema Component XS11-1 respectively. Not all properties are exposed.
The structured representation of a schema type is described in 19.1.1 Record fn:schema-type-record.
Note:
Simple properties of a schema type that can be expressed as strings or booleans are represented in this record structure directly as atomic field values, while complex properties whose values are themselves types (for example, base-type and primitive-type) are represented as functions. This is done partly to make it easier for implementations to compute complex properties on demand rather than in advance, and partly to ensure that the overall structure is always acyclic. For example, the primitive type of xs:decimal is itself xs:decimal, and if this were represented as a field value without a guarding function, serialization of the map using the JSON output method would not terminate.
| Function | Meaning |
|---|
fn:schema-type | Returns a record containing information about a named schema type in the static context. |
fn:type-of | Returns information about the type of a value, as a string. |
fn:atomic-type-annotation | Returns a record containing information about the type annotation of an atomic value. |
fn:node-type-annotation | Returns a record containing information about the type annotation of an element or attribute node. |
- Summary
Returns information about the type of a value, as a string.
- Signature
fn:type-of( |
$value | as item()* | |
) as xs:string |
- Properties
This function is deterministic, context-independent, and focus-independent.
- Rules
The function returns a string, whose lexical form will always match the grammar of SequenceTypeXP, representing a sequence type that matches $value.
If $value is the empty sequence, the function returns the string "empty-sequence()".
Otherwise, the returned string is the concatenation of:
A string representing the distinct item types that are present in $value, formed as follows:
For each item in $value, construct a string representing its item type as described below.
Eliminate duplicate strings from this list by applying the fn:distinct-values function, forming a sequence of strings $ss.
If $ss contains only one string, use that string.
Otherwise, return the result of the expression `({ fn:string-join($ss, "|") })`.
An occurrence indicator: absent if $value contains exactly one item, or "+" if it contains more than one item.
The string representing the type of an individual item J is constructed as follows:
If J is an XNodeDM, the result is one of the following strings, determined by the node kind of the node (see [XQuery and XPath Data Model (XDM) 4.0] section 7.6.9 node-kind Accessor):
"document-node()"
"element()"
"attribute()"
"text()"
"processing-instruction()"
"comment()"
"namespace-node()"
If J is a JNodeDM, the result is in the form jnode(T), where T is the result of applying the type-of function to the ·content· property of J.
If J is an atomic item, the result is a string chosen as follows:
Let T be the type denoted by the type annotation of J.
If T is an anonymous type, set T to the base type of T, and repeat until a type is reached that is not anonymous.
If the name of T is in the namespace http://www.w3.org/2001/XMLSchema, return the string "xs:local" where local is the local part of the name of T.
Otherwise, return the name of T in the form of a URIQualifiedNameXP (that is, "Q{uri}local", or "Q{}local" if the name is in no namespace).
If J is a function item:
If J is an array, return "array(*)".
If J is a map, return "map(*)".
Otherwise, return "function(*)".Otherwise, return "fn(*)".Otherwise, return "functionfn(*)".
- Error Conditions
If the $value argument is omitted and the context value is absentDM, the function raises type error [err:XPDY0002]XP.
- Notes
In general, an item matches more than one type, and there are cases where there is no single matching type that is more specific than all the others. This is especially true with functions, maps, and arrays. This function therefore selects one of the types that matches the item, which is not necessarily the most specific type.
This function should not be used as a substitute for an instance of test. The precise type annotation of the result of an expression is not always predictable, because processors are free to deliver a more specific type than is mandated by the specification. For example, if $n is of type xs:positiveInteger, then the result of abs($n) is guaranteed to be an instance of xs:integer, but an implementation might reasonably return the supplied value unchanged: that is, a value whose actual type annotation is xs:positiveInteger. Similarly the type annotation of the value returned by position() might be xs:long rather than xs:integer.
Implementations should, however, refrain from exposing types that are purely internal. For example, an implementation might have an optimized internal representation for strings consisting entirely of ASCII characters, or for single-character strings; if this is the case then the type annotation returned by this function should be a user-visible supertype such as xs:string.
- Examples
| Variables |
|---|
let $e := <doc>
<p id="alpha" xml:id="beta">One</p>
<p id="gamma" xmlns="http://example.com/ns">Two</p>
<ex:p id="delta" xmlns:ex="http://example.com/ns">Three</ex:p>
<?pi 3.14159?>
</doc> |
| Expression | Result |
|---|
type-of($e//*[@id = 'alpha'])
| "element()"
|
| "element()+"
|
type-of($e//@id[. = 'gamma'])
| "attribute()"
|
type-of($e//node()[. = '3.14159'])
| "processing-instruction()"
|
type-of($e//no-such-node)
| "empty-sequence()"
|
type-of($e/child::node())
| "(element()|processing-instruction())+"
|
| "xs:integer"
|
| "xs:integer+"
|
| "(xs:integer|xs:decimal)+"
|
| "array(*)"
|
| "map(*)"
|
| "function(*)""fn(*)""functionfn(*)"
|
| "jnode(array(*))"
|