W3C

XQuery 1.0: An XML Query Language

W3C Working Draft 02 May 2003

This version:
http://www.w3.org/TR/2003/WD-xquery-20030502/
Latest version:
http://www.w3.org/TR/xquery/
Previous versions:
http://www.w3.org/TR/2002/WD-xquery-20021115/ http://www.w3.org/TR/2002/WD-xquery-20020816/ http://www.w3.org/TR/2002/WD-xquery-20020430/ http://www.w3.org/TR/2001/WD-xquery-20011220/ http://www.w3.org/TR/2001/WD-xquery-20010607/
Editors:
Scott Boag (XSL WG), IBM Research <scott_boag@us.ibm.com>
Don Chamberlin (XML Query WG), IBM Almaden Research Center <chamberlin@almaden.ibm.com>
Mary F. Fernandez (XML Query WG), AT&T Labs <mff@research.att.com>
Daniela Florescu (XML Query WG), BEA Systems <danielaf@bea.com>
Jonathan Robie (XML Query WG), DataDirect Technologies <jonathan.robie@datadirect-technologies.com>
Jérôme Siméon (XML Query WG), Bell Labs, Lucent Technologies <simeon@research.bell-labs.com>

Abstract

XML is a versatile markup language, capable of labeling the information content of diverse data sources including structured and semi-structured documents, relational databases, and object repositories. A query language that uses the structure of XML intelligently can express queries across all these kinds of data, whether physically stored in XML or viewed as XML via middleware. This specification describes a query language called XQuery, which is designed to be broadly applicable across many types of XML data sources.

Status of this Document

This is a public W3C Working Draft for review by W3C Members and other interested parties. This section describes the status of this document at the time of its publication. It is a draft document and may be updated, replaced, or made obsolete by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress." A list of current public W3C technical reports can be found at http://www.w3.org/TR/.

Much of this document is the result of joint work by the XML Query and XSL Working Groups, which are jointly responsible for XPath 2.0, a language derived from both XPath 1.0 and XQuery. The XPath 2.0 and XQuery 1.0 Working Drafts are generated from a common source. These languages are closely related, sharing much of the same expression syntax and semantics, and much of the text found in the two Working Drafts is identical.

This version contains a new syntax for identifying types, and new features that allow path expressions to select element and attribute nodes based on their types as well as their names. It introduces the concept of a "module," and permits one module to import a function library defined in another module. It introduces changes to the semantics of element constructors, including automatic validation of the constructed element. It changes some of the details of the semantics of arithmetic and comparison operators, including making the value comparison operators transitive. It introduces a syntax by which an implementation can add its own extensions to XQuery. It includes some grammar changes, including changes in the comment delimiters and the syntax of the cast expression. A detailed list of changes can be found in G Revision Log.

This document is a work in progress. It contains many open issues, and should not be considered to be fully stable. Vendors who wish to create preview implementations based on this document do so at their own risk. While this document reflects the general consensus of the working groups, there are still controversial areas that may be subject to change.

Public comments on this document and its open issues are welcome, in particular comments on Issue 510. Comments should be sent to the W3C XPath/XQuery mailing list, public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/).

XQuery 1.0 has been defined jointly by the XML Query Working Group and the XSL Working Group (both part of the XML Activity).

Patent disclosures relevant to this specification may be found on the XML Query Working Group's patent disclosure page at http://www.w3.org/2002/08/xmlquery-IPR-statements and the XSL Working Group's patent disclosure page at http://www.w3.org/Style/XSL/Disclosures.

Table of Contents

1 Introduction
2 Basics
    2.1 Expression Context
        2.1.1 Static Context
        2.1.2 Evaluation Context
    2.2 Input Functions
    2.3 Expression Processing
        2.3.1 Document Order
        2.3.2 Typed Value and String Value
        2.3.3 Serialization of Query Results
    2.4 Types
        2.4.1 Predefined Types
        2.4.2 Type Checking
        2.4.3 SequenceType
            2.4.3.1 SequenceType Matching
        2.4.4 Type Conversions
            2.4.4.1 Atomization
            2.4.4.2 Effective Boolean Value
    2.5 Error Handling
        2.5.1 Kinds of Errors
        2.5.2 Handling Dynamic Errors
        2.5.3 Errors and Optimization
    2.6 Optional Features
        2.6.1 Basic XQuery
        2.6.2 Schema Import Feature
        2.6.3 Static Typing Feature
        2.6.4 Extensions
            2.6.4.1 Pragmas
            2.6.4.2 Must-Understand Extensions
            2.6.4.3 XQuery Flagger
3 Expressions
    3.1 Primary Expressions
        3.1.1 Literals
        3.1.2 Variables
        3.1.3 Parenthesized Expressions
        3.1.4 Function Calls
        3.1.5 XQuery Comments
    3.2 Path Expressions
        3.2.1 Steps
            3.2.1.1 Axes
            3.2.1.2 Node Tests
        3.2.2 Predicates
        3.2.3 Unabbreviated Syntax
        3.2.4 Abbreviated Syntax
    3.3 Sequence Expressions
        3.3.1 Constructing Sequences
        3.3.2 Combining Sequences
    3.4 Arithmetic Expressions
    3.5 Comparison Expressions
        3.5.1 Value Comparisons
        3.5.2 General Comparisons
        3.5.3 Node Comparisons
        3.5.4 Order Comparisons
    3.6 Logical Expressions
    3.7 Constructors
        3.7.1 Direct Element Constructors
            3.7.1.1 Attributes
            3.7.1.2 Namespaces
            3.7.1.3 Content
            3.7.1.4 Whitespace in Element Content
            3.7.1.5 Type of a Constructed Element
        3.7.2 Computed Constructors
            3.7.2.1 Computed Element Constructors
            3.7.2.2 Computed Attribute Constructors
            3.7.2.3 Document Node Constructors
            3.7.2.4 Text Node Constructors
        3.7.3 Other Constructors and Comments
    3.8 FLWOR Expressions
        3.8.1 For and Let Clauses
        3.8.2 Where Clause
        3.8.3 Order By and Return Clauses
        3.8.4 Example
    3.9 Unordered Expressions
    3.10 Conditional Expressions
    3.11 Quantified Expressions
    3.12 Expressions on SequenceTypes
        3.12.1 Instance Of
        3.12.2 Typeswitch
        3.12.3 Cast
        3.12.4 Castable
        3.12.5 Constructor Functions
        3.12.6 Treat
    3.13 Validate Expressions
4 Modules and Prologs
    4.1 Version Declaration
    4.2 Namespace Declarations
    4.3 Default Namespace Declarations
    4.4 Schema Imports
    4.5 Module Imports
    4.6 Variable Definitions
    4.7 Validation Declaration
    4.8 Xmlspace Declaration
    4.9 Default Collation
    4.10 Function Definitions

Appendices

A XQuery Grammar
    A.1 EBNF
        A.1.1 Parsing Notes
    A.2 Lexical structure
        A.2.1 Whitespace Rules
        A.2.2 Lexical Rules
    A.3 Reserved Function Names
    A.4 Precedence Order
B Type Promotion and Operator Mapping
    B.1 Type Promotion
    B.2 Operator Mapping
C References
    C.1 Normative References
    C.2 Non-normative References
    C.3 Background References
    C.4 Informative Material
D Glossary
E Example Applications (Non-Normative)
    E.1 Joins
    E.2 Grouping
    E.3 Queries on Sequence
    E.4 Recursive Transformations
F XPath 2.0 and XQuery 1.0 Issues (Non-Normative)
G Revision Log (Non-Normative)
    G.1 18 April 2003


1 Introduction

As increasing amounts of information are stored, exchanged, and presented using XML, the ability to intelligently query XML data sources becomes increasingly important. One of the great strengths of XML is its flexibility in representing many different kinds of information from diverse sources. To exploit this flexibility, an XML query language must provide features for retrieving and interpreting information from these diverse sources.

XQuery is designed to meet the requirements identified by the W3C XML Query Working Group [XML Query 1.0 Requirements] and the use cases in [XML Query Use Cases]. It is designed to be a language in which queries are concise and easily understood. It is also flexible enough to query a broad spectrum of XML information sources, including both databases and documents. The Query Working Group has identified a requirement for both a human-readable query syntax and an XML-based query syntax. XQuery is designed to meet the first of these requirements. XQuery is derived from an XML query language called Quilt [Quilt], which in turn borrowed features from several other languages, including XPath 1.0 [XPath 1.0], XQL [XQL], XML-QL [XML-QL], SQL [SQL], and OQL [ODMG].

XQuery Version 1.0 is an extension of XPath Version 2.0. Any expression that is syntactically valid and executes successfully in both XPath 2.0 and XQuery 1.0 will return the same result in both languages. Since these languages are so closely related, their grammars and language descriptions are generated from a common source to ensure consistency, and the editors of these specifications work together closely.

XQuery also depends on and is closely related to the following specifications:

This document specifies a grammar for XQuery, using the same Basic EBNF notation used in [XML], except that grammar symbols always have initial capital letters. Unless otherwise noted (see A.2 Lexical structure), whitespace is not significant in the grammar. Grammar productions are introduced together with the features that they describe, and a complete grammar is also presented in the appendix [A XQuery Grammar].

In the grammar productions in this document, nonterminal symbols are underlined and literal text is enclosed in double quotes. Certain productions (including the productions that define DecimalLiteral, DoubleLiteral, and StringLiteral) employ a regular-expression notation. The following example production describes the syntax of a function call:

[94]    FunctionCall    ::=    QName "(" (ExprSingle ("," ExprSingle)*)? ")"

The production should be read as follows: A function call consists of a QName followed by an open-parenthesis. The open-parenthesis is followed by an optional argument list. The argument list (if present) consists of one or more expressions, separated by commas. The optional argument list is followed by a close-parenthesis. The symbol ExprSingle denotes an expression that does not contain any top-level commas (since top-level commas in a function call are used to separate the function arguments).

Certain aspects of language processing are described in this specification as implementation-defined or implementation-dependent. These terms are defined as follows:

Editorial note  
A future version of this document will include links between terms (in bold font) and their definitions.


2 Basics

The basic building block of XQuery is the expression. The language provides several kinds of expressions which may be constructed from keywords, symbols, and operands. In general, the operands of an expression are other expressions. XQuery is a functional language which allows various kinds of expressions to be nested with full generality. (However, unlike a pure functional language, it does not allow variable substitutability if the variable definition contains construction of new nodes.) XQuery is also a strongly-typed language in which the operands of various expressions, operators, and functions must conform to the expected types.

Like XML, XQuery is a case-sensitive language. All keywords in XQuery use lower-case characters.

The value of an expression is always a sequence, which is an ordered collection of zero or more items. An item is either an atomic value or a node. An atomic value is a value in the value space of an XML Schema atomic type, as defined in [XML Schema] (that is, a simple type that is not a list type or a union type). A node conforms to one of the seven node kinds described in [XQuery 1.0 and XPath 2.0 Data Model]. Each node has a unique node identity. Some kinds of nodes have typed values, string values, and names, which can be extracted from the node. The typed value of a node is a sequence of zero or more atomic values. The string value of a node is a value of type xs:string. The name of a node is a value of type xs:QName.

A sequence containing exactly one item is called a singleton sequence. An item is identical to a singleton sequence containing that item. Sequences are never nested--for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3). A sequence containing zero items is called an empty sequence.

In this document, the namespace prefixes xs: and xsi: are considered to be bound to the XML Schema namespaces http://www.w3.org/2001/XMLSchema and http://www.w3.org/2001/XMLSchema-instance, respectively (as described in [XML Schema]), and the prefix fn: is considered to be bound to the namespace of XPath/XQuery functions, http://www.w3.org/2003/05/xpath-functions (described in [XQuery 1.0 and XPath 2.0 Functions and Operators]). In some cases, where the meaning is clear and namespaces are not important to the discussion, built-in XML Schema typenames such as integer and string are used without a namespace prefix. Also, this document assumes that the default function namespace(see 4.2 Namespace Declarations) is set to the namespace of XPath/XQuery functions, so function names appearing without a namespace prefix can be assumed to be in this namespace.

2.1 Expression Context

The expression context for a given expression consists of all the information that can affect the result of the expression. This information is organized into two categories called the static context and the evaluation context.

2.1.1 Static Context

The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation. This information can be used to decide whether the expression contains a static error.

Many of the components of the static context can be assigned initial values by means of a Prolog (see 4 Modules and Prologs). Any component of the static context that is not assigned a default value in the XQuery specification, and is not assigned a value in the Prolog, may be assigned an implementation-defined initial value. If processing of an expression relies on some component of the static context that has not been assigned a value, a static error is raised.

Editorial note  
The impact on static context of queries that consist of multiple modules is under study by the Working Group.

Static context consists of the following components:

  • In-scope namespaces. This is a set of (prefix, URI) pairs. The in-scope namespaces are used for resolving prefixes used in QNames within the expression. The in-scope namespaces include the namespaces bound to the predefined namespace prefixes xml, xs, xsi, fn, and xdt (defined in 4.2 Namespace Declarations.)

  • Default element namespace. This is a namespace URI. This namespace is used for any unprefixed QName appearing in a position where an element or type name is expected.

  • Default function namespace. This is a namespace URI. This namespace URI is used for any unprefixed QName appearing as the function name in a function call.

  • In-scope schema definitions. This is a generic term for all the element, attribute, and type definitions that are in scope during processing of an expression. It includes the following three parts:

    • In-scope type definitions. The in-scope type definitions always include the built-in types of [XML Schema] and the predefined types in the namespace http://www.w3.org/2003/05/xpath-datatypes, which has the predefined namespace prefix xdt. Additional type definitions may be added to the in-scope type definitions by the external environment. If the Schema Import Feature is supported, in-scope type definitions also include all type definitions found in imported schemas.

      XML Schema distinguishes named types, which are given a QName by the schema designer, must be declared at the top level of a schema, and are uniquely identified by their QName, from anonymous types, which are not given a name by the schema designer, must be local, and are identified in an implementation-dependent way. Both named types and anonymous types can be present in the in-scope type definitions.

    • In-scope element declarations. Each element declaration is identified either by a QName (for a top-level element) or by an implementation-defined element identifier (for a local element). Element declarations may be provided by the language environment.If the Schema Import Feature is supported, in-scope element declarations include all element declarations found in imported schemas. An element declaration includes information about the substitution groups to which this element belongs.

    • In-scope attribute declarations. Each attribute declaration is identified either by a QName (for a top-level attribute) or by an implementation-defined attribute identifier (for a local attribute). Attribute declarations may be provided by the language environment. If the Schema Import Feature is supported, in-scope attribute declarations include all attribute declarations found in imported schemas.

  • In-scope variables. This is a set of (QName, type) pairs. It defines the set of variables that have been declared and are available for reference within the expression. The QName represents the name of the variable, and the type represents its static data type.

    The static types of in-scope variables may be declared in the Prolog, derived from static analysis of the expressions in which the variables are bound, or provided by the external environment.

  • In-scope functions. This part of the static context defines the set of functions that are available to be called from within an expression. Each function is uniquely identified by its QName and its arity (number of parameters). The static context maps the QName and arity into a function signature and a function definition. The function signature specifies the static types of the function parameters and the function result. For a user-defined function, the function definition is an XQuery expression. For an external function, the function definition is implementation-defined.

    For each atomic type in the in-scope type definitions, there is a constructor function in the in-scope functions. Constructor functions are discussed in 3.12.5 Constructor Functions.

  • In-scope collations. This is a set of (URI, collation) pairs. It defines the names of the collations that are available for use in function calls that take a collation name as an argument. A collation may be regarded as an object that supports two functions: a function that given a set of strings, returns a sequence containing those strings in sorted order; and a function that given two strings, returns true if they are considered equal, and false if not.

  • Default collation. This is a collation. This collation is used by string comparison functions when no explicit collation is specified.

  • Validation mode. One of strict, lax, or skip. This specifies the mode in which validation is performed by element constructors and by validate expressions. If no validation mode is specified in the Prolog, the default validation mode is lax.

  • Validation context. Either global or a path, starting with a top-level element name or type name in the in-scope schema definitions. Validation context determines the context in which top-level names are interpreted during validation of an element. The validation context for the outermost expression in a query is global. Validation context is affected by element constructors and by validate expressions.

  • XMLSpace policy. This policy, declared in the Prolog, controls the processing of whitespace by element constructors. Its value may be preserve or strip.

  • Base URI. This is an absolute URI, used when necessary in the resolution of relative URIs (for example, by the fn:resolve-uri function.) The base URI is always provided by the external environment.

XQuery Version 1.0 includes XPath Version 2.0 as a subset. In addition to the static context items listed above, XPath 2.0 requires a static context item named XPath 1.0 compatibility mode. Since XQuery does not support this mode, it always sets this context item to false when evaluating an XPath expression.

2.1.2 Evaluation Context

The evaluation context of an expression is defined as information that is available at the time the expression is evaluated.

One component of the evaluation context, the dynamic variables, can be set by the Prolog. Any component of the evaluation context that is not assigned a default value in the XQuery specification, and is not assigned a value in the Prolog, may be assigned an implementation-defined initial value. If processing of an expression relies on some component of the evaluation context that has not been assigned a value, a dynamic error is raised.

The evaluation context consists of all the components of the static context, and the additional components listed below.

The first three components of the evaluation context (context item, context position, and context size) are called the focus of the expression. The focus enables the processor to keep track of which nodes are being processed by the expression.

The focus for the outermost expression may supplied by the environment in which the expression is evaluated--otherwise, the focus for the outermost expression is undefined. Any reference to a component of an undefined focus raises an error. Certain language constructs, notably the path expression E1/E2 and the predicate expression E1[E2], create a new focus for the evaluation of a sub-expression. In these constructs, E2 is evaluated once for each item in the sequence that results from evaluating E1. Each time E2 is evaluated, it is evaluated with a different focus. The focus for evaluating E2 is referred to below as the inner focus, while the focus for evaluating E1 is referred to as the outer focus. The inner focus exists only while E2 is being evaluated. When this evaluation is complete, evaluation of the containing expression continues with its original focus unchanged.

  • The context item is the item currently being processed. An item is either an atomic value or a node. When the context item is a node, it can also be referred to as the context node. The context item is returned by the expression ".". When an expression E1/E2 or E1[E2] is evaluated, each item in the sequence obtained by evaluating E1 becomes the context item in the inner focus for an evaluation of E2.

  • The context position is the position of the context item within the sequence of items currently being processed. It changes whenever the context item changes. Its value is always an integer greater than zero. The context position is returned by the expression fn:position(). When an expression E1/E2 or E1[E2] is evaluated, the context position in the inner focus for an evaluation of E2 is the position of the context item in the sequence obtained by evaluating E1. The position of the first item in a sequence is always 1 (one). The context position is always less than or equal to the context size.

  • The context size is the number of items in the sequence of items currently being processed. Its value is always an integer greater than zero. The context size is returned by the expression last(). When an expression E1/E2 or E1[E2] is evaluated, the context size in the inner focus for an evaluation of E2 is the number of items in the sequence obtained by evaluating E1.

  • Dynamic variables. This is a set of (QName, value) pairs. It contains the same QNames as the in-scope variables in the static context for the expression. Each variable name is associated with a typed value. The dynamic type associated with the value of a variable may be more specific than the static type associated with the same variable. The value of a variable is, in general, a sequence.

    The typed value of a variable may be set by execution of an expression that binds a value to the variable, by the Prolog, or by the external environment.

  • Current date and time. This information represents an implementation-dependent point in time during processing of a query or transformation. It can be retrieved by the fn:current-date, fn:current-time, and fn:current-dateTime functions. If invoked multiple times during the execution of a query or transformation, these functions always returns the same result.

  • Implicit timezone. This is the timezone to be used when a date, time, or dateTime value that does not have a timezone is used in a comparison or in any other operation. This value is an instance of xdt:dayTimeDuration that is implementation-defined. See [ISO 8601] for the range of legal values of a timezone.

  • Input sequence. An input sequence is a sequence of nodes that can be accessed by the input function. It might be thought of as an "implicit input". The content of the input sequence is determined in an implementation-defined way.

2.2 Input Functions

XQuery has a set of functions that provide access to input data. These functions are of particular importance because they provide a way in which an expression can reference a document or a collection of documents. The input functions are described informally here, and in more detail in [XQuery 1.0 and XPath 2.0 Functions and Operators].

The input sequence is a part of the evaluation context for an expression. The way in which nodes are assigned to the input sequence is implementation-defined. For example, one implementation might provide a fixed mapping from a directory system to the input sequence, another implementation might provide a graphical user interface that allows users to choose a data source for the input sequence, and a third implementation might support UNIX-style pipes, allowing the output of one query to become the input sequence for another query.

The input functions supported by XQuery are as follows:

  • The fn:input function, which takes no parameters, returns the input sequence. For example, the expression fn:input()//customer returns all the customer elements that are descendants of nodes in the input sequence. If no input sequence has been bound, the fn:input function raises a dynamic error.

  • The fn:collection function returns the nodes found in a collection. A collection may be any sequence of nodes. A collection is identified by a string, which must be a valid URI. For example, the expression fn:collection("http://example.org")//customer identifies all the customer elements that are descendants of nodes found in the collection whose URI is http://example.org.

  • The fn:doc function, when its first argument is a string containing a single URI that refers to an XML document, returns a document node whose content is the Data Model representation of the given document.

If a given input function is invoked repeatedly with the same arguments during the scope of a single query or transformation, each invocation returns the same result.

2.3 Expression Processing

Editorial note  
Some material in this section duplicates material in [XQuery 1.0 and XPath 2.0 Data Model]. Work is in progress to decide where this material will be normatively defined (see Issue 554.)

XQuery is defined in terms of the [XQuery 1.0 and XPath 2.0 Data Model] (referred to in this document simply as the Data Model), which represents information in the form of nodes and atomic values. Before an XQuery expression can be processed, the input documents to be operated on by the expression must be represented in the Data Model. For example, an XML document might be converted to the Data Model by the following steps:

  1. The document might be parsed using an XML parser that generates an XML Information Set (see [XML Infoset]).

  2. The parsed document might be validated against one or more schemas. This process, which is described in [XML Schema], results in an abstract information structure called the Post-Schema Validation Infoset (PSVI).

  3. If necessary, the PSVI can be transformed to make it acceptable for processing by a particular system. For example, if the implementation understands only built-in XML Schema types, user-defined typenames in the PSVI might be replaced by their built-in base types or by generic types such as xs:anyType (for elements) and xs:anySimpleType (for attributes).

  4. The PSVI can be transformed into the Data Model by a process described in [XQuery 1.0 and XPath 2.0 Data Model]. During this transformation, an error is raised if the PSVI contains an element, attribute, or type whose expanded name matches a name in the in-scope schema definitions (ISSD), but whose definition in the PSVI is not consistent with the corresponding definition in the ISSD. Typenames in the PSVI that are not present in the ISSD are replaced by xs:anyType (for types of elements) or xs:anySimpleType (for types of attributes). At the conclusion of the transformation process, every element name, attribute name, and type name in the resulting Data Model instance matches an entry in the ISSD.

The above steps provide an example of how a Data Model instance might be constructed. A Data Model instance might also be synthesized directly from a relational database, or constructed in some other way. XQuery is defined in terms of operations on the Data Model, but it does not place any constraints on how the input Data Model instance is constructed (except for the constraint that the result must be consistent with the in-scope schema definitions).

Each element or attribute node in the Data Model has an annotation that indicates its dynamic type. If the Data Model was derived from an input XML document, the dynamic types of the elements and attributes are derived from schema validation. The dynamic type of an element or attribute indicates its range of values--for example, an attribute named version might have the dynamic type xs:decimal, indicating that it contains a decimal value.

The value of an attribute is represented directly within the attribute node. An attribute node whose type is unknown (such as might occur in a schemaless document) is annotated with the dynamic type xdt:untypedAtomic.

The value of an element is represented by the children of the element node, which may include text nodes and other element nodes. The dynamic type of an element node indicates how the values in its child text nodes are to be interpreted. An element whose type is unknown (such as might occur in a schemaless document) is annotated with the type xs:anyType.

Atomic values in the Data Model also carry dynamic type annotations. An atomic value of unknown type is annotated with the type xdt:untypedAtomic. Under certain circumstances (such as during processing of an arithmetic operator), an atomic value of xdt:untypedAtomic may be cast into a more specific type (such as xs:double).

This document provides a description of how each kind of expression is processed. For each expression, the operands and result are instances of the Data Model.

The terms document order, typed value, and string value are described here because they are of particular importance for the processing of expressions.

2.3.1 Document Order

Document order defines a total ordering among all the nodes seen by the language processor. Informally, document order corresponds to a pre-order, depth-first, left-to-right traversal of the nodes in the Data Model.

Within a given document, the document node is the first node, followed by element nodes, text nodes, comment nodes, and processing instruction nodes in the order of their representation in the XML form of the document (after expansion of entities). Element nodes occur before their children, and the children of an element node occur before its following siblings. The namespace nodes of an element immediately follow the element node, in implementation-defined order. The attribute nodes of an element immediately follow its namespace nodes, and are also in implementation-defined order.

The relative order of nodes in distinct documents is implementation-defined but stable within a given query or transformation. Given two distinct documents A and B, if a node in document A is before a node in document B, then every node in document A is before every node in document B. The relative order among free-floating nodes (those not in a document) is also implementation-defined but stable.

2.3.2 Typed Value and String Value

Nodes have a typed value and a string value that can be extracted by calling the fn:data function and the fn:string function, respectively. The typed value of a node is a sequence of atomic values, and the string value of a node is a string. Element and attribute nodes also have a type annotation, which is a type identifier that is found in the in-scope type definitions. The type annotation represents the dynamic (run-time) type of the node. XQuery does not provide a way to directly access the type annotation of an element or attribute node.

The typed value and string value for each kind of node are defined by the dm:typed-value and dm:string-value accessors in [XQuery 1.0 and XPath 2.0 Data Model]. The relationship between the typed value and the string value for various kinds of nodes is described and illustrated by examples below.

  1. For text, document, comment, processing instruction, and namespace nodes, the typed value of the node is the same as its string value, as an instance of xdt:untypedAtomic. (The string value of a document node is formed by concatenating the string values of all its descendant text nodes, in document order.)

  2. The typed value of an attribute node with the type annotation xdt:untypedAtomic is the same as its string value, as an instance of xdt:untypedAtomic. The typed value of an attribute node with any other type annotation is derived from its string value and type annotation in a way that is consistent with schema validation.

    Example: A1 is an attribute having string value "3.14E-2" and type annotation xs:double. The typed value of A1 is the xs:double value whose lexical representation is 3.14E-2.

    Example: A2 is an attribute with type annotation IDREFS, which is a list type derived from IDREF. Its string value is "bar baz faz". The typed value of A2 is a sequence of three atomic values ("bar", "baz", "faz"), each of type IDREF. The typed value of a node is never treated as an instance of a named list type. Instead, if the type annotation of a node is a list type (such as IDREFS), its typed value is treated as a sequence of the underlying base type (such as IDREF).

  3. For an element node, the relationship between typed value and string value depends on the node's type annotation, as follows:

    1. If the type annotation is xs:anyType, or denotes a complex type with mixed content, then the typed value of the node is equal to its string value, as an instance of xdt:untypedAtomic.

      Example: E1 is an element node having type annotation xs:anyType and string value "1999-05-31". The typed value of E1 is "1999-05-31", as an instance of xdt:untypedAtomic.

      Example: E2 is an element node with the type annotation formula, which is a complex type with mixed content. The content of E2 consists of the character "H", a child element named subscript with string value "2", and the character "O". The typed value of E2 is "H2O" as an instance of xdt:untypedAtomic.

    2. If the type annotation denotes a simple type or a complex type with simple content, then the typed value of the node is derived from its string value and its type annotation in a way that is consistent with schema validation.

      Example: E3 is an element node with the type annotation cost, which is a complex type that has several attributes and a simple content type of xs:decimal. The string value of E3 is "74.95". The typed value of E3 is 74.95, as an instance of xs:decimal.

      Example: E4 is an element node with the type annotation hatsizelist, which is a simple type derived by list from the type hatsize, which in turn is derived from xs:integer. The string value of E4 is "7 8 9". The typed value of E4 is a sequence of three values (7, 8, 9), each of type hatsize.

    3. If the type annotation denotes a complex type with empty content, then the typed value of the node is the empty sequence.

    4. If the type annotation denotes a complex type with non-mixed complex content, then the typed value of the node is undefined. The fn:data function raises an error when applied to such a node.

      Example: E5 is an element node with the type annotation weather, which is a complex type whose content type specifies elementOnly. E5 has two child elements named temperature and precipitation. The typed value of E5 is undefined, and the fn:data function applied to E5 raises an error.

2.3.3 Serialization of Query Results

Serialization is the process of converting an instance of the [XQuery 1.0 and XPath 2.0 Data Model] into a sequence of octets. The general framework for serialization of the Data Model is described in [XSLT 2.0 and XQuery 1.0 Serialization].

An XQuery implementation is not required to provide a serialization interface. For example, an implementation may only provide a DOM interface or an interface based on an event stream. In these cases, serialization would be done outside of the scope of this specification.

[XSLT 2.0 and XQuery 1.0 Serialization] defines a set of serialization parameters that govern the serialization process. If an XQuery implementation provides a serialization interface, it must support the "xml" value of the method parameter. In addition, the serialization interface may support (and may expose to users) any of the following serialization parameters (a default value is specified in each case):

  • encoding: default is implementation-defined.

  • cdata-section-elements: default is empty.

  • doctype-system: default is empty.

  • doctype-public: default is empty.

  • escape-uri-attributes: default is no.

  • indent: default is no.

  • media-type: default is implementation-defined.

  • normalize-unicode: default is implementation-defined.

  • omit-xml-declaration: default is yes.

  • standalone: default is yes.

  • character-map: default is empty.

  • version: default is 1.0.

2.4 Types

XQuery is a strongly typed language with a type system based on [XML Schema]. When the type of a value is incompatible with the expected type for the context in which it is used, a type error is raised. A type error may be detected and reported during the analysis phase or during the evaluation phase, as described in 2.4.2 Type Checking.

The XQuery type system is formally defined in [XQuery 1.0 Formal Semantics]. This section presents a summary of types from a user's perspective.

2.4.1 Predefined Types

All the built-in types of [XML Schema] are recognized by XQuery. These built-in types are in the namespace http://www.w3.org/2001/XMLSchema, which has the predefined namespace prefix xs. Some examples of built-in schema types include xs:integer, xs:string, and xs:date.

In addition, XQuery recognizes the predefined types listed below. All these predefined types are in the namespace http://www.w3.org/2003/05/xpath-datatypes, which has the predefined namespace prefix which is xdt.

  1. xdt:anyAtomicType is an abstract type that includes all atomic values (and no values that are not atomic). It is a subtype of xs:anySimpleType, which is the base type for all simple types, including atomic, list, and union types. All specific atomic types such as xs:integer, xs:string, and xdt:untypedAtomic, are subtypes of xdt:anyAtomicType.

  2. xdt:untypedAtomic is a specific atomic type used for untyped data, such as text that is not given a specific type by schema validation. It has no subtypes.

  3. xdt:dayTimeDuration is a subtype of xs:duration whose lexical representation contains only day, hour, minute, and second components.

  4. xdt:yearMonthDuration is a subtype of xs:duration whose lexical representation is restricted to contain only year and month components.

For more details about predefined types, see [XQuery 1.0 and XPath 2.0 Functions and Operators].

Additional types may be defined in schemas and imported into a query by means of a schema import, as discussed in 4.4 Schema Imports, or added to the in-scope type definitions by the external environment.

2.4.2 Type Checking

XQuery defines two phases of processing called the analysis phase and the evaluation phase.

The analysis phase depends on the expression itself and on the static context. The analysis phase does not depend on any input data. The purpose of type-checking during the analysis phase is to provide early detection of type errors and to compute the type of a result.

During the analysis phase, each expression is assigned a static type. In some cases, the static type is derived from the lexical form of the expression; for example, the static type of the literal 5 is xs:integer. In other cases, the static type of an expression is inferred according to rules based on the static types of its operands; for example, the static type of the expression 5 + 1.2 is xs:decimal. The static type of an expression may be either a named type or a structural description--for example, xs:boolean? denotes an optional occurrence of the xs:boolean type. The rules for inferring the static types of various expressions are described in [XQuery 1.0 Formal Semantics]. During the analysis phase, if static type checking is in effect and an operand of an expression is found to have a static type that is not appropriate for that operand, a type error is raised. If static type checking raises no errors and assigns a static type T to an expression, then execution of the expression on valid input data is guaranteed either to produce a value of type T or to raise a dynamic error.

The evaluation phase is performed only after successful completion of the analysis phase. The evaluation phase depends on input data, on the expression being evaluated, and on the evaluation context. During the evaluation phase, a dynamic type is associated with each value as it is computed. The dynamic type of a value may be either a structural type (such as "sequence of integers") or a named type. The dynamic type of a value may be more specific than the static type of the expression that computed it (for example, the static type of an expression might be "zero or more integers or strings," but at run time its value may have the dynamic type "integer.") If an operand of an expression is found to have a dynamic type that is incompatible with the expected type for that operand, a type error is raised.

Even though static typing can catch many type errors before an expression is executed, it is possible for an expression to raise an error during evaluation that was not detected by static analysis. For example, an expression may contain a cast of a string into an integer, which is statically valid. However, if the actual value of the string at run time cannot be cast into an integer, a dynamic error will result. Similarly, an expression may apply an arithmetic operator to a value whose static type is xs:anySimpleType. This is not a static error, but at run time, if the value cannot be successfully cast to a numeric type, a dynamic error will be raised.

It is also possible for static analysis of an expression to raise a type error, even though execution of the expression on certain inputs would be successful. For example, an expression might contain a function that requires an element as its parameter, and the analysis phase might infer the static type of the function parameter to be an optional element. This case would be treated as a static type error, even though the function call would be successful for input data in which the optional element is present.

2.4.3 SequenceType

When it is necessary to refer to a type in an XQuery expression, the syntax shown below is used. This syntax production is called "SequenceType", since it describes the type of an XQuery value, which is a sequence.

SequenceType
[117]    SequenceType    ::=    (ItemType OccurrenceIndicator?)
| "empty" "(" ")"
[133]    OccurrenceIndicator    ::=    "?" | "*" | "+"
[119]    ItemType    ::=    AtomicType | KindTest | "item" "(" ")"
[118]    AtomicType    ::=    QName
[120]    KindTest    ::=    DocumentTest
| ElementTest
| AttributeTest
| ProcessingInstructionTest
| CommentTest
| TextTest
| AnyKindTest
[123]    ProcessingInstructionTest    ::=    "processing-instruction" "(" StringLiteral? ")"
[125]    CommentTest    ::=    "comment" "(" ")"
[126]    TextTest    ::=    "text" "(" ")"
[127]    AnyKindTest    ::=    "node" "(" ")"
[124]    DocumentTest    ::=    "document-node" "(" ElementTest? ")"
[121]    ElementTest    ::=    "element" "(" ((SchemaContextPath LocalName)
| (NodeName ("," TypeName "nillable"?)?))? ")"
[122]    AttributeTest    ::=    "attribute" "(" ((SchemaContextPath "@" LocalName)
| ("@" NodeName ("," TypeName)?))? ")"
[128]    SchemaContextPath    ::=    SchemaGlobalContext "/" SchemaContextStep "/"*
[14]    SchemaGlobalContext    ::=    QName | SchemaGlobalTypeName
[15]    SchemaContextStep    ::=    QName
[13]    SchemaGlobalTypeName    ::=    "type" "(" QName ")"
[130]    LocalName    ::=    QName
[131]    NodeName    ::=    QName | "*"
[132]    TypeName    ::=    QName | "*"

QNames appearing in a SequenceType have their prefixes expanded to namespace URIs by means of the in-scope namespaces and the default element namespace. It is a static error to use a name in a SequenceType if that name is not found in the appropriate part of the in-scope schema definitions. If the name is used as an element name, it must appear in the in-scope element declarations; if it is used as an attribute name, it must appear in the in-scope attribute declarations; and if it is used as a type name, it must appear in the in-scope type definitions.

Here are some examples of SequenceTypes that might be used in XQuery expressions:

  • xs:date refers to the built-in Schema type date

  • attribute()? refers to an optional attribute

  • element() refers to any element

  • element(po:shipto, po:address) refers to an element that has the name po:shipto (or is in the substitution group of that element), and has the type annotation po:address (or a subtype of that type)

  • element(po:shipto, *) refers to an element named po:shipto (or in the substitution group of po:shipto), with no restrictions on its type

  • element(*, po:address) refers to an element of any name that has the type annotation po:address (or a subtype of po:address). If the keyword nillable were used following po:address, that would indicate that the element may have empty content and the attribute xsi:nil="true", even though the declaration of the type po:address has required content.

  • node()* refers to a sequence of zero or more nodes of any type

  • item()+ refers to a sequence of one or more nodes or atomic values

2.4.3.1 SequenceType Matching

During processing of an expression, it is sometimes necessary to determine whether a given value matches a type that was declared using the SequenceType syntax. This process is known as SequenceType matching. For example, an instance of expression returns true if a given value matches a given type, or false if it does not.

SequenceType matching between a given value and a given SequenceType is performed as follows:

If the SequenceType is empty(), the match succeeds only if the value is an empty sequence. If the SequenceType is an ItemType with no OccurrenceIndicator, the match succeeds only if the value contains precisely one item and that item matches the ItemType (see below). If the SequenceType contains an ItemType and an OccurrenceIndicator, the match succeeds only if the number of items in the value is consistent with the OccurrenceIndicator, and each of these items matches the ItemType. As a consequence of these rules, a value that is an empty sequence matches any SequenceType whose occurrence indicator is * or ?.

An OccurrenceIndicator indicates the number of items in a sequence, as follows:

  • ? indicates zero or one items

  • * indicates zero or more items

  • + indicates one or more items

As stated above, an item may be a node or an atomic value. The process of matching a given item against a given ItemType is performed as follows

  1. The ItemType item() matches any single item. For example, item() matches the atomic value 1 or the element <a/>.

  2. If an ItemType consists simply of a QName, that QName must be the name of an atomic type that is in the in-scope type definitions; otherwise a static error is raised. An ItemType consisting of the QName of an atomic type matches a value if the dynamic type of the value is the same as the named atomic type, or is derived from the named atomic type by restriction. For example, the ItemType xs:decimal matches the value 12.34 (a decimal literal); it also matches a value whose dynamic type is shoesize, if shoesize is an atomic type derived by restriction from xs:decimal. The named atomic type may be a generic type such as xdt:anyAtomicType. (Note that names of non-atomic types such as xs:IDREFS are not accepted in this context.)

  3. The following ItemTypes (referred to generically as KindTests) match nodes:

    1. node() matches any node.

    2. text() matches any text node.

    3. processing-instruction() matches any processing instruction node.

    4. processing-instruction(N ) matches any processing instruction node whose name (called its "PITarget" in XML) is equal to N, where N is a StringLiteral. Example: processing-instruction("browser") matches any processing instruction directed to the application named browser.

    5. comment() matches any comment node.

    6. document-node() matches any document node.

    7. document-node(E) matches any document node whose content consists of exactly one element node that matches E, where E is an ElementTest (see below). Example: document-node(element(book)) matches any document node whose content consists of exactly one element node named book, that conforms to the schema declaration for the top-level element book.

    8. An ElementTest (see below) matches an element node, optionally qualifying the node by its name, its type, or both.

    9. An AttributeTest (see below) matches an attribute node, optionally qualifying the node by its name, its type, or both.

An ElementTest is used to match an element node by its name and/or type. An ElementTest may take one of the following forms:

  1. element(), or element(*), or element(*,*). All these forms of ElementTest are equivalent, and they all match any single element node, regardless of its name or type.

  2. element(N, T), where N is a QName and T is a QName optionally followed by the keyword nillable. In this case, T must be the name of a top-level type definition in the in-scope type definitions. The ElementTest matches a given element node if:

    1. the name of the given element node is equal to N (expanded QNames match), or is equal to the name of any element in a substitution group headed by a top-level element with the name N; and:

    2. the type annotation of the given element node is T, or is a named type that is derived by restriction or extension from T. However, this test is not satisfied if the given element node has an attribute xsi:nil="true" and T does not specify nillable.

    The following examples illustrate this form of ElementTest, matching an element node whose name is person and whose type annotation is surgeon (the second example permits the element to have xsi:nil="true"):

    element(person, surgeon)
    element(person, surgeon nillable)
    
  3. element(N), where N is a QName. This form is very similar to the previous form, except that the required type, rather than being named explicitly, is taken from the top-level declaration of element N. In this case, N must be the name of a top-level element declaration in the in-scope element declarations. The ElementTest matches a given element node if:

    1. the name of the given element node is equal to N (expanded QNames match), or is equal to the name of any element in a substitution group headed by N; and:

    2. the type annotation of the given element node is the same as, or derived by restriction or extension from, the type of the top-level declaration for element N. The types to be compared may be either named types (identified by QNames) or anonymous types (identified in an implementation-dependent way). However, this test is not satisfied if the given element node has an attribute xsi:nil="true" and the top-level declaration for element N does not specify nillable.



    The following example illustrates this form of ElementTest, matching an element node whose name is person and whose type annotation conforms to the top-level person element declaration in the in-scope element declarations:

    element(person)
    
  4. element(N, *), where N is a QName. This ElementTest matches a given element node if the name of the node is equal to N (expanded QNames match), or is equal to the name of any element in a substitution group headed by a top-level element with the name N. The given element node may have any type annotation.

    The following example illustrates this form of ElementTest, matching any element node whose name is person or is in the person substitution group, regardless of its type annotation:

    element(person, *)
    
  5. element(*, T), where T is a QName optionally followed by the keyword nillable. In this case, T must be the name of a top-level type definition in the in-scope type definitions. The ElementTest matches a given element node if the node's type annotation is T, or is a named type that is derived by restriction or extension from T. However, this test is not satisfied if the given element node has an attribute xsi:nil="true" and T does not specify nillable.

    The following examples illustrate this form of ElementTest, matching any element node whose type annotation is surgeon, regardless of its name (the second example permits the element to have xsi:nil="true"):

    element(*, surgeon)
    element(*, surgeon nillable)
    
  6. element(P), where P is a valid schema context path beginning with a top-level element name or type name in the in-scope schema definitions and ending with an element name. This ElementTest matches a given element node if:

    1. the name of the given element node is equal to the last name in the path (expanded QNames match), and:

    2. the type annotation of the given element node is the same as the type of the element represented by the schema path P.

    The following examples illustrate this form of ElementTest, matching element nodes whose name is person. In the first example, the node must conform to the schema definition of a person element in a staff element in a hospital element. In the second example, the node must conform to the schema definition of a person element within the top-level type schedule:

    element(hospital/staff/person)
    element(type(schedule)/person)
    

An AttributeTest is used to match an attribute node by its name and/or type. An AttributeTest may take one of the following forms:

  1. attribute(), or attribute(@*), or attribute(@*,*). All these forms of AttributeTest are equivalent, and they all match any single attribute node, regardless of its name or type.

  2. attribute(@N, T), where N and T are QNames. In this case, T must be the name of a top-level simple type definition in the in-scope type definitions. This AttributeTest matches a given attribute node if:

    1. the name of the given attribute node is equal to N (expanded QNames match), and:

    2. the type annotation of the given attribute node is T, or is a named type that is derived by restriction from T.

    The following example illustrates this form of AttributeTest, matching an attribute node whose name is price and whose type annotation is currency:

    attribute(@price, currency)
    
  3. attribute(@N), where N is a QName. This form is very similar to the previous form, except that the required type, rather than being named explicitly, is taken from the top-level attribute declaration with name N.In this case, N must be the name of a top-level attribute declaration in the in-scope attribute declarations. This AttributeTest matches a given attribute node if:

    1. the name of the given attribute node is equal to N (expanded QNames match), and:

    2. the type annotation of the given attribute node is the same as, or derived by restriction from, the type of the top-level attribute declaration for N. The types to be compared may be either named types (identified by QNames) or anonymous types (identified in an implementation-dependent way).



    The following example illustrates this form of AttributeTest, matching an attribute node whose name is price and whose type annotation conforms to the schema declaration for a top-level price attribute:

    attribute(@price)
    
  4. attribute(@N, *), where N is a QName. This AttributeTest matches a given attribute node if the name of the node is equal to N (expanded QNames match). The given attribute node may have any type annotation.

    The following example illustrates this form of AttributeTest, matching any attribute node whose name is price, regardless of its type annotation:

    attribute(@price, *)
    
  5. attribute(@*, T), where T is a QName. In this case, T must be the name of a top-level simple type definition in the in-scope type definitions. This AttributeTest matches a given attribute node if the node's type annotation is T, or is a named type that is derived by restriction from T.

    The following example illustrates this form of AttributeTest, matching any attribute node whose type annotation is currency, regardless of its name:

    attribute(@*, currency)
    
  6. attribute(P), where P is a valid schema context path beginning with a top-level element name or type name in the in-scope schema definitions, and ending with an attribute name (preceded by @). This AttributeTest matches a given attribute node if:

    1. the name of the given attribute node is equal to the last name in the path (expanded QNames match), and:

    2. the type annotation of the given attribute node is the same as the type of the attribute represented by the schema path P.

    The following examples illustrate this form of AttributeTest, matching attribute nodes whose name is price. In the first example, the node must conform to the schema definition of a price attribute in a product element in a catalog element. In the second example, the node must conform to the schema definition of a price attribute within the top-level type plan:

    attribute(catalog/product/@price)
    attribute(type(plan)/@price)
    

2.4.4 Type Conversions

Some expressions do not require their operands to exactly match the expected type. For example, function parameters and returns expect a value of a particular type, but automatically perform certain type conversions, such as extraction of atomic values from nodes, promotion of numeric values, and implicit casting of untyped values. The conversion rules for function parameters and returns are discussed in 3.1.4 Function Calls. Other operators that provide special conversion rules include arithmetic operators, which are discussed in 3.4 Arithmetic Expressions, and value comparisons, which are discussed in 3.5.1 Value Comparisons.

2.4.4.1 Atomization

Type conversions sometimes depend on a process called atomization, which is used when a sequence of atomic values is required. The result of atomization is either a sequence of atomic values or a type error. Atomization of a sequence is defined as the result of invoking the fn:data function on the sequence, as defined in [XQuery 1.0 and XPath 2.0 Functions and Operators].

The semantics of fn:data are repeated here for convenience. The result of fn:data is the sequence of atomic values produced by applying the following rules to each item in the input sequence:

  • If the item is an atomic value, it is returned.

  • If the item is a node, it is replaced by its typed value.

Atomization may be used in processing the following types of expressions:

  • Arithmetic expressions

  • Comparison expressions

  • Function calls and returns

  • Cast expressions

2.4.4.2 Effective Boolean Value

Under certain circumstances (listed below), it is necessary to find the effective boolean value of a sequence. This is defined as the result of invoking the fn:boolean function on the sequence, as defined in [XQuery 1.0 and XPath 2.0 Functions and Operators].

The semantics of fn:boolean are repeated here for convenience. fn:boolean returns false if its operand is any of the following:

  • An empty sequence.

  • The boolean value false.

  • A zero-length string ("").

  • A numeric value that is equal to zero.

  • The double or float value NaN.

Otherwise, fn:boolean returns true.

The effective boolean value of a sequence is computed implicitly during processing of the following types of expressions:

  • Logical expressions (and, or)

  • The fn:not function

  • The where clause of a FLWOR expression

  • Certain types of predicates, such as a[b].

  • Conditional expressions (if)

  • Quantified expressions (some, every)

Note that the definition of effective boolean value is not used when casting a value to the type xs:boolean.