W3C

XQuery 1.0: An XML Query Language

W3C Working Draft 22 August 2003

This version:
http://www.w3.org/TR/2003/WD-xquery-20030822/
Latest version:
http://www.w3.org/TR/xquery/
Previous versions:
http://www.w3.org/TR/2003/WD-xquery-20030502/ 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. Fernández (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 section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a public W3C Working Draft for review by W3C Members and other interested parties. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document 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 section entitled "Processing Model" that provides a more complete and detailed description of expression processing. It also contains specific error codes for various error conditions, and a glossary in which many terms are defined. The section on Optional Features has been rewritten. The term Basic XQuery is no longer used. A new optional feature called the Full Axis Feature (supporting all the XPath axes except namespace) has been added. Three new types of computed constructors are introduced, and the syntax for declaring various objects in module prologs has changed. Changes have been made in the details of certain kinds of expressions. A complete list of changes can be found in I Revision Log.

Public comments on this document are welcome. Feedback is especially requested on the remaining open XQuery issues: Issues 152, 307, 546, 554, and 564. 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/).

This Working Draft references the Last Call Working Drafts of [XQuery 1.0 and XPath 2.0 Data Model] and [XQuery 1.0 and XPath 2.0 Functions and Operators]. Since these Last Call Working Drafts are not being re-published along with this Working Draft, it is possible that some differences may exist between this Working Draft and the Last Call Working Drafts. The public is encouraged to provide feedback on any differences that they find. The Working Groups are planning to publish a set of synchronized documents as early as possible.

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.

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.1.1 Predefined Types
        2.1.2 Dynamic Context
    2.2 Processing Model
        2.2.1 Data Model Generation
        2.2.2 Schema Import Processing
        2.2.3 Expression Processing
            2.2.3.1 Static Analysis Phase
            2.2.3.2 Dynamic Evaluation Phase
        2.2.4 Serialization
        2.2.5 Consistency Constraints
    2.3 Important Concepts
        2.3.1 Document Order
        2.3.2 Typed Value and String Value
        2.3.3 Input Sources
    2.4 Types
        2.4.1 SequenceType
            2.4.1.1 SequenceType Matching
        2.4.2 Type Conversions
            2.4.2.1 Atomization
            2.4.2.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 Schema Import Feature
        2.6.2 Static Typing Feature
        2.6.3 Full Axis 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 Context Item Expression
        3.1.5 Function Calls
        3.1.6 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 Namespace Declaration Attributes
            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 Other Direct Constructors
        3.7.3 Computed Constructors
            3.7.3.1 Computed Element Constructors
            3.7.3.2 Computed Attribute Constructors
            3.7.3.3 Document Node Constructors
            3.7.3.4 Text Node Constructors
            3.7.3.5 Computed Processing Instruction Constructors
            3.7.3.6 Computed Comment Constructors
            3.7.3.7 Computed Namespace Constructors
        3.7.4 Namespace Nodes on Constructed Elements
    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 Module Declaration
    4.2 Version Declaration
    4.3 Base URI Declaration
    4.4 Namespace Declaration
    4.5 Default Namespace Declaration
    4.6 Schema Import
    4.7 Module Import
    4.8 Variable Declaration
    4.9 Validation Declaration
    4.10 Xmlspace Declaration
    4.11 Default Collation Declaration
    4.12 Function Declaration

Appendices

A XQuery Grammar
    A.1 EBNF
        A.1.1 Grammar Notes
    A.2 Lexical structure
        A.2.1 White Space 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 Context Components
    C.1 Static Context Components
    C.2 Dynamic Context Components
    C.3 Serialization Parameters
D References
    D.1 Normative References
    D.2 Non-normative References
    D.3 Background References
    D.4 Informative Material
E Glossary
F Summary of Error Conditions
G Example Applications (Non-Normative)
    G.1 Joins
    G.2 Grouping
    G.3 Queries on Sequence
    G.4 Recursive Transformations
H XPath 2.0 and XQuery 1.0 Issues (Non-Normative)
I Revision Log (Non-Normative)
    I.1 22 August 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].

[Definition: XQuery operates on the abstract, logical structure of an XML document, rather than its surface syntax. This logical structure is known as the data model, which is defined in the [XQuery 1.0 and XPath 2.0 Data Model] document.]

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:

[96]    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.

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. [Definition: XQuery is a functional language which means that expressions can be nested with full generality. (However, unlike a pure functional language, it does not allow variable substitutability if the variable declaration contains construction of new nodes.)] [Definition: 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.[Definition: A sequence is an ordered collection of zero or more items.] [Definition: An item is either an atomic value or a node.] [Definition: 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).] [Definition: A node is an instance of 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.

[Definition: 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). [Definition: 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.4 Namespace Declaration) 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

[Definition: 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 dynamic context.

2.1.1 Static Context

[Definition: 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. If analysis of an expression relies on some component of the static context that has not been assigned a value, a static error is raised.[err:XP0001]

The individual components of the static context are summarized below. Further rules governing the semantics of these components can be found in C.1 Static Context Components.

  • [Definition: XPath 1.0 compatibility mode. This component must be set by all host languages that include XPath 2.0 as a subset, indicating whether rules for compatibility with XPath 1.0 are in effect. XQuery sets the value of this component to false. ]

  • [Definition: 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.] Each in-scope namespace is classified as either an active namespace or a passive namespace. For details of this distinction, see 3.7.4 Namespace Nodes on Constructed Elements.

    Some namespaces are predefined; additional namespaces can be defined by Prologs, by namespace declaration attributes, and by computed namespace constructors.

  • [Definition: Default element/type 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.] The initial default element/type namespace may be provided by the external environmentor by a declaration in the Prolog of a module.

  • [Definition: 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. The initial default function namespace may be provided by the external environmentor by a declaration in the Prolog of a module.]

  • [Definition: 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:

    • [Definition: In-scope type definitions. The in-scope type definitions always include the predefined types listed in 2.1.1.1 Predefined Types. 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.

    • [Definition: 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). 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.]

    • [Definition: 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). If the Schema Import Feature is supported, in-scope attribute declarations include all attribute declarations found in imported schemas.]

  • [Definition: In-scope variables. This is a set of (QName, type) pairs. It defines the set of variables that are available for reference within an expression. The QName is the name of the variable, and the type is the static type of the variable.]

    Variable declarations in the Prolog of a module are added to the in-scope variables of the module. An expression that binds a variable (such as a let, for, some, or every expression) extends the in-scope variables of its subexpressions with the new bound variable and its type. Within a function declaration, the in-scope variables are extended by the names and types of the function parameters.

  • [Definition: In-scope functions. This component defines the set of functions that are available to be called from within an expression. Each function is uniquely identified by its expanded QName and its arity (number of parameters). Each function in in-scope functions has a function signature and a function implementation.] [Definition: The function signature specifies the name of the function and the static types of its parameters and its result.] [Definition: The function implementation enables the function to map instances of its parameter types into an instance of its result type. For a user-defined function, the function implementation is an XQuery expression. For an external function, the function implementation is implementation dependent.]

    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.

  • [Definition: 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.

  • [Definition: Default collation. This collation is used by string comparison functions when no explicit collation is specified.]

  • [Definition: Validation mode. The validation mode specifies the mode in which validation is performed by element constructors and by validate expressions. ] Its value is one of strict, lax, or skip. The initial validation mode may be provided by the environment external to a query or by the validation declaration in the Prolog of a module. If no validation mode is specified in either of these ways, the initial validation mode is lax.

    The validation mode for a subexpression is inherited from the containing expression. A validate expression that specifies a mode changes the validation mode of its subexpressions to the specified mode.

  • [Definition: Validation context. An expression's validation context determines the context in which elements constructed by the expression are validated. ] Its value is either global or a context path that starts with a top-level element name or type name in the in-scope schema definitions. The default validation context of a module is global.

    The validation context for a subexpression is inherited from the containing expression. An element constructor extends the validation context of its subexpressions with the name of the constructed element, and a validate expression that specifies a context redefines the validation context of its subexpressions.

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

  • [Definition: Base URI. This is an absolute URI, used when necessary in the resolution of relative URIs (for example, by the fn:resolve-uri function.)]

  • [Definition: Statically-known documents. This is a mapping from strings onto types. The string represents the absolute URI of a resource that is potentially accessible using the fn:doc function. The type is the type of the document node that would result from calling the fn:doc function with this URI as its argument. ] If the argument to fn:doc is anthing other than a string literal that is present in statically-known documents, then the static type of fn:doc is document-node()?.

  • [Definition: Statically-known collections. This is a mapping from strings onto types. The string represents the absolute URI of a resource that is potentially accessible using the fn:collection function. The type is the type of the sequence of nodes that would result from calling the fn:collection function with this URI as its argument.] If the argument to fn:collection is anthing other than a string literal that is present in statically-known collections, then the static type of fn:collection is node()?.

2.1.1.1 Predefined Types

The in-scope type definitions in the static context are initialized with certain predefined types, including all the built-in types of [XML Schema]. 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. Element and attribute definitions in the xs namespace are not implicitly included in the static context.

In addition, the predefined types of XQuery include the 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 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].

2.1.2 Dynamic Context

[Definition: The dynamic context of an expression is defined as information that is available at the time the expression is evaluated.] If evaluation of an expression relies on some part of the dynamic context that has not been assigned a value, a dynamic error is raised.[err:XP0002]

The individual components of the dynamic context are summarized below. Further rules governing the semantics of these components can be found in C.2 Dynamic Context Components.

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

[Definition: The first three components of the dynamic 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.

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.

  • [Definition: The context item is the item currently being processed in a path expression. An item is either an atomic value or a node.][Definition: 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.

  • [Definition: The context position is the position of the context item within the sequence of items currently being processed in a path expression. ]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.

  • [Definition: The context size is the number of items in the sequence of items currently being processed in a path expression.] 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.

  • [Definition: 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. The QName is the name of the variable and the value is the dynamic value of the variable.]

  • [Definition: 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.]

  • [Definition: 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.]

  • [Definition: Accessible documents. This is a mapping of strings onto document nodes. The string represents the absolute URI of a resource. The document node is the representation of that resource as an instance of the data model, as returned by the fn:doc function when applied to that URI. ]The set of accessible documents may be the same as, or a subset or superset of, the set of statically-known documents, and it may be empty.

  • [Definition: Accessible collections. This is a mapping of strings onto sequences of nodes. The string represents the absolute URI of a resource. The sequence of nodes represents the result of the fn:collection function when that URI is supplied as the argument. ] The set of accessible collections may be the same as, or a subset or superset of, the set of statically-known collections, and it may be empty.

2.2 Processing Model

XQuery is defined in terms of the data model and in terms of the expression context.

Processing Model Overview

Figure 1: Processing Model Overview

Figure 1 provides a schematic overview of the processing steps that are discussed in detail below. XQuery distinguishes between the external processing domain, which includes generation of the data model (see 2.2.1 Data Model Generation), schema import processing (see 2.2.2 Schema Import Processing) and serialization (see 2.2.4 Serialization), and the query processing domain, which includes the static analysis and dynamic evaluation phases (see 2.2.3 Expression Processing). Consistency constraints on the query processing domain are defined in 2.2.5 Consistency Constraints.

Editorial note  
There is an open issue on how much of the external processing domain is considered normative (open issue 561).

2.2.1 Data Model Generation

Before an expression can be processed, the input documents to be accessed by the expression must be represented in the data model. Figure 1 depicts the steps by which an XML document may be converted to the data model:

  1. A document may be parsed using an XML parser that generates an XML Information Set (see [XML Infoset]). The parsed document may then 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). If a document has no associated schema, its Information Set is preserved. (See DM1 in Fig. 1.)

  2. The Information Set or PSVI may be transformed into the data model by a process described in [XQuery 1.0 and XPath 2.0 Data Model]. (See DM2 in Fig. 1.)

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 (see DM3 in Fig. 1.) 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.

Each atomic value, element node, and attribute node in the data model is annotated with its dynamic type. The dynamic type specifies a range of values -- for example, an attribute named version might have the dynamic type xs:decimal, indicating that it contains a decimal value. For example, 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 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 xdt:untypedAny.

An atomic value of unknown type is annotated with the type xdt:untypedAtomic.

2.2.2 Schema Import Processing

The in-scope schema definitions in the static context may be extracted from actual XML Schemata as described in [XQuery 1.0 and XPath 2.0 Formal Semantics] (see step SI1 in Figure 1) or may be generated by some other mechanism (see step SI2 in Figure 1). In either case, the result must satisfy the consistency constraints defined in 2.2.5 Consistency Constraints.

2.2.3 Expression Processing

XQuery defines two phases of processing called the static analysis phase and the dynamic evaluation phase (see Fig. 1).

2.2.3.1 Static Analysis Phase

[Definition: The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on any input data.]

During the static analysis phase, the query is parsed into an internal representation called the operation tree (step SQ1 in Figure 1). A parse error is raised as a static error.[err:XP0003] The static context is initialized by the implementation (step SQ2). The static context is then changed and augmented based on information in the prolog (step SQ3). In particular, the in-scope schema definitions are populated with information from imported schemata. The static context is used to resolve type names, function names, namespace prefixes and variable names. If a name in the operation tree is not found in the static context, a static error [err:XP0008] is raised (step SQ4).

The operation tree is then normalized by making explicit the implicit operations such as atomization, type promotion and extraction of Effective Boolean Values (step SQ5). The normalization process is described in [XQuery 1.0 and XPath 2.0 Formal Semantics]. An implementation is free to use any strategy or algorithm whose result conforms to these specifications.

If the Static Typing Feature is supported, each expression is assigned a static type (step SQ6). [Definition: 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 and XPath 2.0 Formal Semantics].] 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.

During the analysis phase, if the Static Typing Feature 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.[err:XQ0004] 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.

During the static analysis phase, if the static type assigned to an expression other than () is empty, a static error is raised.[err:XQ0005] This catches cases in which a query refers to an element or attribute that is not present in the in-scope schema definitions, possibly because of a spelling error.

The purpose of type-checking during the static analysis phase is to provide early detection of type errors and to infer type information that may be useful in optimizing the evaluation of an expression.

2.2.3.2 Dynamic Evaluation Phase

[Definition: The dynamic evaluation phase is performed only after successful completion of the static analysis phase. The dynamic evaluation phase depends on the operation tree of the expression being evaluated (step DQ1), on the input data (step DQ4), and on the dynamic context (step DQ5), which in turn draws information from the external environment (step DQ3) and the static context (step DQ2).] Execution of the evaluation phase may create new data-model values (step DQ4) and it may extend the dynamic context (step DQ5)--for example, by binding values to variables.

Editorial note  
This is an open issue. It would be possible to evaluate an expression containing a static type error, and this might be quite useful because static analysis is conservative. Static type analysis could be used to warn of potential errors without inhibiting execution of an expression.

[Definition: 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 evaluation time its value may have the dynamic type "integer.")]

If an operand of an expression is found to have a dynamic type that is not appropriate for that operand, a type error is raised.[err:XP0006]

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 xdt:untypedAtomic. 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.2.4 Serialization

[Definition: Serialization is the process of converting an instance of the [XQuery 1.0 and XPath 2.0 Data Model] into a sequence of octets (step DM4 in Figure 1.) ] 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 serialization parameters listed (with default values) in C.3 Serialization Parameters.

2.2.5 Consistency Constraints

In order for an expression to be well defined, the expression, its static context, and its dynamic context must be mutually consistent. The consistency constraints listed below are prerequisites for correct functioning of an XQuery implementation. Enforcement of these consistency constraints is beyond the scope of this specification.

2.3 Important Concepts

The concepts described in this section are normatively defined in [XQuery 1.0 and XPath 2.0 Data Model] and [XQuery 1.0 and XPath 2.0 Functions and Operators]. They are summarized here because they are of particular importance in the processing of expressions.

2.3.1 Document Order

[Definition: Document order defines a total ordering among all the nodes seen by the language processor and is defined formally in the data model.] 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 dependent 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 dependent but stable.

2.3.2 Typed Value and String Value

Nodes have a typed value and a string value. [Definition: The typed value of a node is a sequence of atomic values and can be extracted by applying the fn:data function to the node. The typed value for each kind of node is defined by the dm:typed-value accessor in [XQuery 1.0 and XPath 2.0 Data Model]. ] [Definition: The string value of a node is a string and can be extracted by applying the the fn:string function to the node. The string value for each kind of node is defined by the dm:string-value accessor in [XQuery 1.0 and XPath 2.0 Data Model].] [Definition: Element and attribute nodes have a type annotation, which represents (in an implementation-dependent way) 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 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 a type error [err:XP0007] 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 Input Sources

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].

An expression can access input documents either by calling one of the input functions or by referencing some part of the expression context that is initialized by the external environment, such as a variable or a pre-initialized context item.

The input functions supported by XQuery are as follows:

  • The fn:doc function takes a string containing a URI that refers to an XML document, and returns a document node whose content is the data model representation of the given document.

  • 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.

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.4 Types

XQuery is a strongly typed language with a type system based on [XML Schema]. The XQuery type system is formally defined in [XQuery 1.0 and XPath 2.0 Formal Semantics]. During the analysis phase, if static type checking is in effect and an expression has a static type that is not appropriate for the context in which the expression is used, a type error is raised.[err:XQ0004] During the evaluation phase, if the type of a value is incompatible with the expected type of the context in which the value is used, a type error is raised.[err:XP0006] A type error may be detected and reported either during the static analysis phase or during the dynamic evaluation phase.

2.4.1 SequenceType

[Definition: 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
[124]    SequenceType    ::=    (ItemType OccurrenceIndicator?)
| ("empty" "(" ")")
[140]    OccurrenceIndicator    ::=    "?" | "*" | "+"
[126]    ItemType    ::=    AtomicType | KindTest | ("item" "(" ")")
[125]    AtomicType    ::=    QName
[127]    KindTest    ::=    DocumentTest
| ElementTest
| AttributeTest
| PITest
| CommentTest
| TextTest
| AnyKindTest
[130]    PITest    ::=    "processing-instruction" "(" (NCName | StringLiteral)? ")"
[132]    CommentTest    ::=    "comment" "(" ")"
[133]    TextTest    ::=    "text" "(" ")"
[134]    AnyKindTest    ::=    "node" "(" ")"
[131]    DocumentTest    ::=    "document-node" "(" ElementTest? ")"
[128]    ElementTest    ::=    "element" "(" ((SchemaContextPath LocalName)
| (NodeName ("," TypeName "nillable"?)?))? ")"
[129]    AttributeTest    ::=    "attribute" "(" ((SchemaContextPath "@" LocalName)
| ("@" NodeName ("," TypeName)?))? ")"
[135]    SchemaContextPath    ::=    SchemaGlobalContext "/" (SchemaContextStep "/")*
[14]    SchemaGlobalContext    ::=    QName | SchemaGlobalTypeName
[15]    SchemaContextStep    ::=    QName
[13]    SchemaGlobalTypeName    ::=    "type" "(" QName ")"
[137]    LocalName    ::=    QName
[138]    NodeName    ::=    QName | "*"
[139]    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/type namespace. It is a static error [err:XP0008] 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.1.1 SequenceType Matching

[Definition: During evaluation 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.

Editorial note  
The definition of SequenceType matching still needs to be correlated with the definition of type matching in [XQuery 1.0 and XPath 2.0 Formal Semantics].

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, but can often be replaced by an atomic type with an occurrence indicator, such as xs:IDREF*.)

  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 an NCName. Example: processing-instruction(xml-stylesheet) matches any processing instruction whose PITarget is xml-stylesheet.

      For backward compatibility with XPath 1.0, the PITarget of a processing instruction in a KindTest may also be expressed as a string literal, as in this example: processing-instruction("xml-stylesheet").

    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), mixed with zero or more comments and processing instructions. Example: document-node(element(book)) matches any document node whose content contains exactly one element node named book, that conforms to the schema declaration for the top-level element book (possibly mixed with comments and processing instructions).

    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.

[Definition: 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 the nilled property 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)
    

[Definition: 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.2 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.5 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.2.1 Atomization

Type conversions sometimes depend on a process called atomization. [Definition: Atomization is applied to a value when the value is used in a context in which 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.2.2 Effective Boolean Value

Under certain circumstances (listed below), it is necessary to find the effective boolean value of a value. [Definition: The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value, 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.

2.5 Error Handling

2.5.1 Kinds of Errors

As described in 2.2.3 Expression Processing, XQuery defines an analysis phase, which does not depend on input data, and an evaluation phase, which does depend on input data. Errors may be raised during each phase.

[Definition: A static error is an error that must be detected during the analysis phase. A syntax error is an example of a static error. The means by which static errors are reported during the analysis phase is implementation defined. ]

[Definition: A dynamic error is an error that must be detected during the evaluation phase and may be detected during the analysis phase. Numeric overflow is an example of a dynamic error. ]

[Definition: A type error may be raised during the analysis or evaluation phase. During the analysis phase, a type error occurs when the static type of an expression does not match the expected type of the context in which the expression occurs. During the evaluation phase, a type error occurs when the dynamic type of a value does not match the expected type of the context in which the value occurs. ]

The result of the analysis phase is either success or one or more type errors and/or static errors.

The result of the evaluation phase is either a result value, a type error, or a dynamic error. If evaluation of an expression yields a value (that is, it does not raise an error), the value must be the value specified by the dynamic semantics defined in [XQuery 1.0 and XPath 2.0 Formal Semantics].

If any expression (at any level) can be evaluated during the analysis phase (because all its explicit operands are known and it has no dependencies on the dynamic context), then any error in performing this evaluation may be reported as a static error. However, the fn:error() function must not be evaluated during the analysis phase. For example, an implementation is allowed (but not required) to treat the following expression as a static error, because it calls a constructor function with a constant string that is not in the lexical space of the target type:

xs:date("Next Tuesday")

[XQuery 1.0 and XPath 2.0 Formal Semantics] defines the set of static, dynamic, and type errors. In addition to these errors, an XQuery implementation may raise implementation defined warnings, either during the analysis phase or the evaluation phase. The circumstances in which warnings are raised, and the ways in which warnings are handled, are implementation defined.

In addition to the errors defined in this specification, an implementation may raise a dynamic error if insufficient resources are available for processing a given expression. For example, an implementation may specify limitations on the maximum numbers or sizes of various objects. These limitations, and the consequences of exceeding them, are implementation defined.

2.5.2 Handling Dynamic Errors

Except as noted in this document, if any operand of an expression raises a dynamic error, the expression also raises a dynamic error. If an expression can validly return a value or raise a dynamic error, the implementation may choose to return the value or raise the dynamic error. For example, the logical expression expr1 and expr2 may return the value false if either operand returns false, or may raise a dynamic error if either operand raises a dynamic error.

If more than one operand of an expression raises an error, the implementation may choose which error is raised by the expression. For example, in this expression:

($x div $y) + xs:decimal($z)

both the sub-expressions ($x div $y) and xs:decimal($z) may raise an error. The implementation may choose which error is raised by the "+" expression. Once one operand raises an error, the implementation is not required, but is permitted, to evaluate any other operands.

A dynamic error carries an error value. [Definition: An error value is a single item or the empty sequence.] For example, an error value might be an integer, a string, a QName, or an element. An implementation may provide a mechanism whereby an application-defined error handler can process error values and produce diagnostics; in the absence of such an error handler, the string-value of the error value may be used directly as an error message.

A dynamic error may be raised by a built-in function or operator. For example, the div operator raises an error if its second operand equals zero.

An error can be raised explicitly by calling the fn:error function, which only raises an error and never returns a value. The fn:error function takes an optional item as its parameter, which is the error value. For example, the following function call raises a dynamic error whose error value is a string:

fn:error(fn:concat("Unexpected value ", fn:string($v)))

2.5.3 Errors and Optimization

Because different implementations may choose to evaluate or optimize an expression in different ways, the detection and reporting of dynamic errors is implementation dependent.

When an implementation is able to evaluate an expression without evaluating some subexpression, the implementation is never required to evaluate that subexpression solely to determine whether it raises a dynamic error. For example, if a function parameter is never used in the body of the function, an implementation may choose whether to evaluate the expression bound to that parameter in a function call.

In some cases, an optimizer may be able to achieve substantial performance improvements by rearranging an expression so that the underlying operations such as projection, restriction, and sorting are performed in a different order than that specified in [XQuery 1.0 and XPath 2.0 Formal Semantics]. In such cases, dynamic errors may be raised that would not have been raised if the expression were evaluated as written. For example, consider the following expression:

$N[@x castable as xs:date]
      [xs:date(@x) gt xs:date("2000-01-01")]

This expression cannot raise a casting error if it is evaluated exactly as written (i.e., left to right). An implementation is permitted, however, to reorder the predicates to achieve better performance (for example, by taking advantage of an index). This reordering could cause the above expression to raise an error. However, an expression must not be rearranged in a way that causes it to return a result value that is different from the result value defined by [XQuery 1.0 and XPath 2.0 Formal Semantics].

To avoid unexpected errors caused by reordering of expressions, tests that are designed to prevent dynamic errors should be expressed using conditional expressions, as in the following example:

$N[if (@x castable as xs:date)
   then xs:date(@x) gt xs:date("2000-01-01")
   else false()]

In the case of a conditional expression, the implementation is required not to evaluate the then branch if the condition is false, and not to evaluate the else branch if the condition is true. Conditional and typeswitch expressions are the only expressions that provide guaranteed conditions under which a particular subexpression will not be evaluated.

2.6 Optional Features

XQuery defines three optional features called the Schema Import Feature, the Static Typing Feature, and the Full Axis Feature.

2.6.1 Schema Import Feature

If an XQuery implementation that does not support the Schema Import Feature encounters a Schema Import, it raises a static error.[err:XQ0009] In such an implementation, the in-scope type definitions consist only a fixed set of predefined types.

Editorial note  
This set is to be determined.


If the Schema Import Feature is supported, in-scope schema definitions are derived from schemas named in Schema Import clauses in the Prolog. If more than one schema is imported, the definitions contained in these schemas are collected into a single pool of definitions. This pool of definitions must satisfy the conditions for schema validity set out in Sections 3 and 5 of [XML Schema] Part 1. In brief, the definitions must be valid, they must be complete, and they must be unique--that is, the pool of definitions must not contain two or more schema components with the same name and target namespace. If any of these conditions is violated, a static error is raised.[err:XQ0012]

2.6.2 Static Typing Feature

[Definition: An XQuery implementation that does not support the Static Typing Feature is not required to raise type errors during the static analysis phase.] However, non-type-related static errors must be detected and raised during the static analysis phase.

2.6.3 Full Axis Feature

An XQuery implementation that does not support the Full Axis Feature raises a static error [err:XQ0010] if any of the following axes are encountered in a path expression:

ancestor
ancestor-or-self
following
following-sibling
preceding
preceding-sibling

An XQuery implementation that supports the Full Axis Feature must recognize the axes on the above list (however, XQuery does not recognize the namespace axis defined by XPath).

2.6.4 Extensions

An XQuery implementation may make two kinds of extensions to this specification, called pragmas and must-understand extensions. While an XQuery implementation may support either of these kinds of extensions, this does not negate the requirement to support the XQuery functionality defined in this specification.

2.6.4.1 Pragmas

[Definition: A pragma may be used to provide additional information to an XQuery implementation.]

[1]    Pragma    ::=    "(::" "pragma" QName PragmaContents* "::)" /* gn: parens */
[5]    PragmaContents    ::=    Char

The QName is any QName that contains an explicit namespace prefix. PragmaContents may consist of any sequence of characters that does not include the sequence "::)". Pragmas may be used anywhere that ignorable whitespace is allowed. See A.2 Lexical structure for the exact lexical states where pragmas are recognized. A pragma is identified by its QName.

If an implementation does not support a pragma, then that pragma shall be ignored. If an implementation does support a pragma and the implementation determines that the PragmaContents are invalid, then a static error is raised.[err:XQ0013] Otherwise, the effect of the pragma on the result of the Query is implementation defined.

The following example shows how a pragma might be used:

declare namespace exq = "http://example.org/XQueryImplementation"
   (:: pragma exq:timeout 1000 ::)
   count($doc//author)

An implementation that supports the exq:timeout pragma might raise a dynamic error if it is unable to count the authors within 1000 seconds. An implementation that does not support this pragma would execute as long as necessary to count the authors.

2.6.4.2 Must-Understand Extensions

[Definition: An implementation may extend XQuery functionality by supporting must-understand extensions. A must-understand extension may be used anywhere that ignorable whitespace is allowed.]

[2]    MUExtension    ::=    "(::" "extension" QName ExtensionContents* "::)" /* gn: parens */
[6]    ExtensionContents    ::=    Char

The QName is any QName that contains an explicit namespace prefix. ExtensionContents may consist of any sequence of characters that does not include the sequence "::)". See A.2 Lexical structure for the exact lexical states where these extensions are recognized. A must-understand extension is identified by its QName.

If an implementation does not support a must-understand extension, then a static error is raised.[err:XQ0014] If an implementation does support a must-understand extension and the implementation determines that the ExtensionContents are invalid, then a static error is raised. Otherwise, the effect of the must-understand extension on the result of the Query is implementation defined.

The following example shows how a must-understand extension might be used:

   declare namespace exq = "http://example.org/XQueryImplementation"

   for $e in doc("employees.xml")//employee
   order by $e/lastname (:: extension exq:RightToLeft ::)
   return $e

An implementation that supports the exq:RightToLeft extension might order the last names by examining characters from right to left instead of from left to right. An implementation that does not support this extension would raise a static error.

2.6.4.3 XQuery Flagger

[Definition: An XQuery Flagger is a facility that is provided by an implementation that is able to identify queries that contain must-understand extensions. If an implementation supports must-understand extensions, then an XQuery Flagger must be provided.] The XQuery Flagger is disabled by default; the mechanism by which the XQuery Flagger is enabled is implementation defined. If the XQuery Flagger is enabled, a static error [err:XQ0015] is raised if the query contains a must-understand extension.

An XQuery Flagger is provided to assist programmers in producing queries that are portable among multiple conforming XQuery implementations.

The following example illustrates how an XQuery Flagger might be used:

xquery RightToLeft.xquery -Flagger=on

If RightToLeft.xquery contains a must-understand extension such as exq:RightToLeft, then this XQuery invocation will result in a static error. If the XQuery Flagger was not enabled and the implementation supports exq:RightToLeft, then this query might execute without error.

3 Expressions

This section introduces each of the basic kinds of expression. Each kind of expression has a name such as PathExpr, which is introduced on the left side of the grammar production that defines the expression. Since XQuery is a composable language, each kind of expression is defined in terms of other expressions whose operators have a higher precedence. In this way, the precedence of operators is represented explicitly in the grammar.

The order in which expressions are discussed in this document does not reflect the order of operator precedence. In general, this document introduces the simplest kinds of expressions first, followed by more complex expressions. For a complete overview of the grammar, see the Appendix [A XQuery Grammar].

[40]    Expr    ::=    ExprSingle ("," ExprSingle)*
[41]    ExprSingle    ::=    FLWORExpr
| QuantifiedExpr
| TypeswitchExpr
| IfExpr
| OrExpr

A query may consist of one or more modules, as described in 4 Modules and Prologs. If a query is executable, one of its modules has a Query Body containing an expression whose value is the result of the query. An expression is represented in the XQuery grammar by the symbol Expr.

The XQuery operator that has lowest precedence is the comma operator, which is used to concatenate two operands to form a sequence. As shown in the grammar, a general expression (Expr) can consist of two operands (ExprSingle) separated by a comma. The name ExprSingle denotes an expression that does not contain a top-level comma operator (despite its name, an ExprSingle may evaluate to a sequence containing more than one item.)

The symbol ExprSingle is used in various places in the grammar where an expression is not allowed to contain a top-level comma. For example, each of the arguments of a function call must be an ExprSingle, because commas are used to separate the arguments of a function call.

After the comma, the expressions that have next lowest precedence are FLWORExpr, QuantifiedExpr, TypeswitchExpr, IfExpr, and OrExpr. Each of these expressions is described in a separate section of this document.

3.1 Primary Expressions

[Definition: Primary expressions are the basic primitives of the language. They include literals, variables, function calls, constructors, and the use of parentheses to control precedence of operators. ] Constructors are described in 3.7 Constructors.

[75]    PrimaryExpr    ::=    Literal | FunctionCall | ContextItemExpr | ("$" VarName) | ParenthesizedExpr | Constructor
[20]    VarName    ::=    QName

3.1.1 Literals

[Definition: A literal is a direct syntactic representation of an atomic value.] XQuery supports two kinds of literals: numeric literals and string literals.

[93]    Literal    ::=    NumericLiteral | StringLiteral
[94]    NumericLiteral    ::=    IntegerLiteral | DecimalLiteral | DoubleLiteral
[7]    IntegerLiteral    ::=    Digits
[8]    DecimalLiteral    ::=    ("." Digits) | (Digits "." [0-9]*) /* ws: explicit */
[9]    DoubleLiteral    ::=    (("." Digits) | (Digits ("." [0-9]*)?)) ("e" | "E") ("+" | "-")? Digits /* ws: explicit */
[10]    StringLiteral    ::=    ('"' (PredefinedEntityRef | CharRef | ('"' '"') | [^"&])* '"') | ("'" (PredefinedEntityRef | CharRef | ("'" "'") | [^'&])* "'") /* ws: significant */
[22]    PredefinedEntityRef    ::=    "&" ("lt" | "gt" | "amp" | "quot" | "apos") ";" /* ws: explicit */
[24]    CharRef    ::=    "&#" (Digits | ("x" HexDigits)) ";" /* ws: explicit */
[16]    Digits    ::=    [0-9]+
[23]    HexDigits    ::=    [0-9] | [a-f] | [A-F]+

The value of a numeric literal containing no "." and no e or E character is an atomic value whose type is xs:integer and whose value is obtained by parsing the numeric literal according to the rules of the xs:integer datatype. The value of a numeric literal containing "." but no e or E character is an atomic value whose type is xs:decimal and whose value is obtained by parsing the numeric literal according to the rules of the xs:decimal datatype. The value of a numeric literal containing an e or E character is an atomic value whose type is xs:double and whose value is obtained by parsing the numeric literal according to the rules of the xs:double datatype.

The value of a string literal is an atomic value whose type is xs:string and whose value is the string denoted by the characters between the delimiting apostrophes or quotation marks. If the literal is delimited by apostrophes, two adjacent apostrophes within the literal are interpreted as a single apostrophe. Similarly, if the literal is delimited by quotation marks, two adjacent quotation marks within the literal are interpreted as one quotation mark.

Note:

If a string literal is used in an XQuery expression contained within the value of an XML attribute, the characters used to delimit the literal should be different from the characters that are used to delimit the attribute.(See 3.7.1.1 Attributes for examples of expressions used in attribute values.)

A string literal may contain a predefined entity reference, which is a short sequence of characters, beginning with an ampersand, that represents a single character that might otherwise have syntactic significance. Each predefined entity reference is replaced by the character it represents when the string literal is processed. The predefined entity references recognized by XQuery are as follows:

Entity Reference Character Represented
&lt; <
&gt; >
&amp; &
&quot; "
&apos; '

A string literal may also contain a character reference, which is an XML-style reference to a Unicode character, identified by its decimal or hexadecimal code point. For example, the Euro symbol (€) can be represented by the character reference &#8364;.

Here are some examples of literal expressions:

  • "12.5" denotes the string containing the characters '1', '2', '.', and '5'.

  • 12 denotes the integer value twelve.

  • 12.5 denotes the decimal value twelve and one half.

  • 125E2 denotes the double value twelve thousand, five hundred.

  • "He said, ""I don't like it.""" denotes a string containing two quotation marks and one apostrophe.

  • Ben &amp; Jerry&apos;s denotes the string "Ben & Jerry's".

  • &#8364;99.50 denotes the string "€99.50".

The boolean values true and false can be represented by calls to the built-in functions fn:true() and fn:false(), respectively.

Values of other XML Schema built-in types can be constructed by calling the constructor for the given type. The constructors for XML Schema built-in types are defined in [XQuery 1.0 and XPath 2.0 Functions and Operators]. In general, the name of a constructor function for a given type is the same as the name of the type (including its namespace). For example:

  • xs:integer("12") returns the integer value twelve.

  • xs:date("2001-08-25") returns an item whose type is xs:date and whose value represents the date 25th August 2001.

  • xdt:dayTimeDuration("PT5H") returns an item whose type is xdt:dayTimeDuration and whose value represents a duration of five hours.

It is also possible to construct values of various types by using a cast expression. For example:

  • 9 cast as hatsize returns the atomic value 9 whose type is hatsize.

3.1.2 Variables

A variable reference is a QName preceded by a $-sign. Two variable references are equivalent if their local names are the same and their namespace prefixes are bound to the same namespace URI in the in-scope namespaces. An unprefixed variable reference is in no namespace.

Every variable reference must match a name in the in-scope variables, which include variables from the following sources:

  1. A variable may be declared in a Prolog, in the current module or an imported module. See 4 Modules and Prologs for a discussion of modules and Prologs.

  2. A variable may be added to the in-scope variables by the host language environment.

  3. A variable may be bound by an XQuery expression. The kinds of expressions that can bind variables are FLWOR expressions (3.8 FLWOR Expressions), quantified expressions (3.11 Quantified Expressions), and typeswitch expressions (3.12.2 Typeswitch). Function calls also bind values to the formal parameters of functions before executing the function body.



Every variable binding has a static scope. The scope defines where references to the variable can validly occur. It is a static error [err:XP0016] to reference a variable that is not in scope. If a variable is bound in the static context for an expression, that variable is in scope for the entire expression.

If a variable reference matches two or more bindings that are in scope, then the reference is taken as referring to the inner binding, that is, the one whose scope is smaller. At evaluation time, the value of a variable reference is the value of the expression to which the relevant variable is bound. The scope of a variable binding is defined separately for each kind of expression that can bind variables.

3.1.3 Parenthesized Expressions

[95]    ParenthesizedExpr    ::=    "(" Expr? ")"

Parentheses may be used to enforce a particular evaluation order in expressions that contain multiple operators. For example, the expression (2 + 4) * 5 evaluates to thirty, since the parenthesized expression (2 + 4) is evaluated first and its result is multiplied by five. Without parentheses, the expression 2 + 4 * 5 evaluates to twenty-two, because the multiplication operator has higher precedence than the addition operator.

Empty parentheses are used to denote an empty sequence, as described in 3.3.1 Constructing Sequences.

3.1.4 Context Item Expression

[74]    ContextItemExpr    ::=    "."

A context item expression evaluates to the context item, which may be either a node (as in the expression fn:doc("bib.xml")//book[count(./author)>1]) or an atomic value (as in the expression (1 to 100)[. mod 5 eq 0]).

3.1.5 Function Calls

A function call consists of a QName followed by a parenthesized list of zero or more expressions, called arguments. If the QName in the function call has no namespace prefix, it is considered to be in the default function namespace.

If the expanded QName and number of arguments in a function call do not match the name and arity of an in-scope function in the static context, a static error is raised.[err:XP0017]

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

A function call is evaluated as follows:

  1. Each argument expression is evaluated, producing an argument value. The order of argument evaluation is implementation-dependent and a function need not evaluate an argument if the function can evaluate its body without evaluating that argument.

  2. Each argument value is converted by applying the function conversion rules listed below.

  3. If the function is a built-in function, it is executed using the converted argument values. The result is a value of the function's declared return type.

  4. If the function is a user-declared function, the converted argument values are bound to the formal parameters of the function, and the function body is evaluated. The value returned by the function body is then converted to the declared return type of the function by applying the function conversion rules.

    When a converted argument value is bound to a function parameter, the argument value retains its most specific dynamic type, even though this may be a subtype of the type of the formal parameter. For example, a function with a parameter $p of type xs:decimal can be invoked with an argument of type xs:integer, which is derived from xs:decimal. During the processing of this function invocation, the dynamic type of $p inside the body of the function is considered to be xs:integer. Similarly, the value returned by a function retains its most specific type, which may be a subtype of the declared return type of the function. For example, a function that has a declared return type of xs:decimal may in fact return a value of dynamic type xs:integer.

    A function does not inherit a focus (context item, context position, and context size) from the environment of the function call. During evaluation of a function body, the focus is undefined, except where it is defined by the action of some expression inside the function body. It is a static error [err:XP0018] for an expression to depend on the focus when the focus is undefined.

The function conversion rules are used to convert an argument value or a return value to its expected type; that is, to the declared type of the function parameteror return. The expected type is expressed as a SequenceType. The function conversion rules are applied to a given value as follows:

  • If the expected type is a sequence of an atomic type (possibly with an occurrence indicator *, +, or ?), the following conversions are applied:

    1. Atomization is applied to the given value, resulting in a sequence of atomic values.

    2. Each item in the atomic sequence that is of type xdt:untypedAtomic is cast to the expected atomic type.

    3. For each numeric item in the atomic sequence that can be promoted to the expected atomic type using the promotion rules in B.1 Type Promotion, the promotion is done.

  • If, after the above conversions, the resulting value does not match the expected type according to the rules for SequenceType Matching, a type error is raised.[err:XP0006] Note that the rules for SequenceType Matching permit a value of a derived type to be substituted for a value of its base type.

A core library of functions is defined in [XQuery 1.0 and XPath 2.0 Functions and Operators]. Additional functions may be declared in a Prolog, imported from a library module, or provided by the external environment as part of the static context. For details on processing function names that have no namespace prefix, see 4.4 Namespace Declaration.

Since the arguments of a function call are separated by commas, any argument expression that contains a top-level comma operator must be enclosed in parentheses. Here are some illustrative examples of function calls:

  • three-argument-function(1, 2, 3) denotes a function call with three arguments.

  • two-argument-function((1, 2), 3) denotes a function call with two arguments, the first of which is a sequence of two values.

  • two-argument-function(1, ()) denotes a function call with two arguments, the second of which is an empty sequence.

  • one-argument-function((1, 2, 3)) denotes a function call with one argument that is a sequence of three values.

  • one-argument-function(( )) denotes a function call with one argument that is an empty sequence.

  • zero-argument-function( ) denotes a function call with zero arguments.

3.1.6 XQuery Comments

[3]    ExprComment    ::=    "(:" (ExprCommentContent | ExprComment)* ":)" /* gn: comments */
[4]    ExprCommentContent    ::=    Char /* gn: parens */

XQuery comments can be used to provide informative annotation. These comments are lexical constructs only, and do not affect the processing of an expression. Comments are delimited by the symbols (: and :). Comments may be nested.

Comments may be used anywhere that ignorable whitespace is allowed. See A.2 Lexical structure for the exact lexical states where comments are recognized.

The following is an example of a comment:

(: Houston, we have a problem :)

3.2 Path Expressions

A path expression can be used to locate nodes within a tree.

[69]    PathExpr    ::=    ("/" RelativePathExpr?)
| ("//" RelativePathExpr)
| RelativePathExpr
/* gn: leading-lone-slash */
[70]    RelativePathExpr    ::=    StepExpr (("/" | "//") StepExpr)*

A path expression consists of a series of one or more steps, separated by "/" or "//", and optionally beginning with "/" or "//". An initial "/" or "//" is an abbreviation for one or more initial steps that are implicitly added to the beginning of the path expression, as described below.

A path expression consisting of a single step is evaluated as described in 3.2.1 Steps.

Each occurrence of // in a path expression is expanded as described in 3.2.4 Abbreviated Syntax, leaving a sequence of steps separated by /. This sequence of steps is then evaluated from left to right. Each operation E1/E2 is evaluated as follows: Expression E1 is evaluated, and if the result is not a sequence of nodes, a type error is raised.[err:XP0019] Each node resulting from the evaluation of E1 then serves in turn to provide an inner focus for an evaluation of E2, as described in 2.1.2 Dynamic Context. Each evaluation of E2 must result in a sequence of nodes; otherwise, a type error is raised.[err:XP0019] The sequences of nodes resulting from all the evaluations of E2 are merged, eliminating duplicate nodes based on node identity and sorting the results in document order.

As an example of a path expression, child::div1/child::para selects the para element children of the div1 element children of the context node, or, in other words, the para element grandchildren of the context node that have div1 parents.

A "/" at the beginning of a path expression is an abbreviation for the initial step fn:root(self::node()) treat as document-node(). The effect of this initial step is to begin the path at the root node of the tree that contains the context node. If the context item is not a node, a type error is raised.[err:XP0020] At evaluation time, if the root node above the context node is not a document node, a dynamic error is raised.[err:XP0050]

A "//" at the beginning of a path expression is an abbreviation for the initial steps fn:root(self::node()) treat as document-node()/descendant-or-self::node(). The effect of these initial steps is to establish an initial node sequence that contains all nodes in the same tree as the context node. This node sequence is then filtered by subsequent steps in the path expression. If the context item is not a node, a type error is raised.[err:XP0020] At evaluation time, if the root node above the context node is not a document node, a dynamic error is raised.[err:XP0050]

3.2.1 Steps

[71]    StepExpr    ::=    AxisStep | FilterStep
[72]    AxisStep    ::=    (ForwardStep | ReverseStep) Predicates
[73]    FilterStep    ::=    PrimaryExpr Predicates
[84]    ForwardStep    ::=    (ForwardAxis NodeTest) | AbbrevForwardStep
[85]    ReverseStep    ::=    (ReverseAxis NodeTest) | AbbrevReverseStep

A step generates a sequence of items and then filters the sequence by zero or more predicates. The value of the step consists of those items that satisfy the predicates. Predicates are described in 3.2.2 Predicates. XQuery provides two kinds of step, called a filter step and an axis step.

A filter step consists simply of a primary expression followed by zero or more predicates. The result of the filter expression consists of all the items returned by the primary expression for which all the predicates are true. If no predicates are specified, the result is simply the result of the primary expression. This result may contain nodes, atomic values, or any combination of these. The ordering of the items returned by a filter step is the same as their order in the result of the primary expression.

The result of an axis step is always a sequence of zero or more nodes, and these nodes are always returned in document order. An axis step may be either a forward step or a reverse step, followed by zero or more predicates. An axis step might be thought of as beginning at the context node and navigating to those nodes that are reachable from the context node via a specified axis. Such a step has two parts: an axis, which defines the "direction of movement" for the step, and a node test, which selects nodes based on their kind, name, and/or type. If the context item is not a node, a type error is raised.[err:XP0020]

In the abbreviated syntax for a step, the axis can be omitted and other shorthand notations can be used as described in 3.2.4 Abbreviated Syntax.

The unabbreviated syntax for an axis step consists of the axis name and node test separated by a double colon. The result of the step consists of the nodes reachable from the context node via the specified axis that have the node kind, name, and/or type specified by the node test. For example, the step child::para selects the para element children of the context node: child is the name of the axis, and para is the name of the element nodes to be selected on this axis. The available axes are described in 3.2.1.1 Axes. The available node tests are described in 3.2.1.2 Node Tests. Examples of steps are provided in 3.2.3 Unabbreviated Syntax and 3.2.4 Abbreviated Syntax.

3.2.1.1 Axes
[88]    ForwardAxis    ::=    ("child" "::")
| ("descendant" "::")
| ("attribute" "::")
| ("self" "::")
| ("descendant-or-self" "::")
| ("following-sibling" "::")
| ("following" "::")
[89]    ReverseAxis    ::=    "parent" "::"
| "ancestor" "::"
| "preceding-sibling" "::"
| "preceding" "::"
| "ancestor-or-self" "::"

XQuery supports the following axes (subject to limitations as described in 2.6.3 Full Axis Feature):

  • the child axis contains the children of the context node

  • the descendant axis contains the descendants of the context node; a descendant is a child or a child of a child and so on; thus the descendant axis never contains attribute or namespace nodes

  • the parent axis contains the parent of the context node, if there is one

  • the ancestor axis contains the ancestors of the context node; the ancestors of the context node consist of the parent of context node and the parent's parent and so on; thus, the ancestor axis will always include the root node, unless the context node is the root node

  • the following-sibling axis contains all the following siblings of the context node; if the context node is an attribute node or namespace node, the following-sibling axis is empty

  • the preceding-sibling axis contains all the preceding siblings of the context node; if the context node is an attribute node or namespace node, the preceding-sibling axis is empty

  • the following axis contains all nodes, in the same tree as the context node, that are after the context node in document order, excluding any descendants and excluding attribute nodes and namespace nodes

  • the preceding axis contains all nodes, in the same tree as the context node, that are before the context node in document order, excluding any ancestors and excluding attribute nodes and namespace nodes

  • the attribute axis contains the attributes of the context node; the axis will be empty unless the context node is an element

  • the self axis contains just the context node itself

  • the descendant-or-self axis contains the context node and the descendants of the context node

  • the ancestor-or-self axis contains the context node and the ancestors of the context node; thus, the ancestor-or-self axis will always include the root node

Axes can be categorized as forward axes and reverse axes. An axis that only ever contains the context node or nodes that are after the context node in document order is a forward axis. An axis that only ever contains the context node or nodes that are before the context node in document order is a reverse axis.

The parent, ancestor, ancestor-or-self, preceding, and preceding-sibling axes are reverse axes; all other axes are forward axes. The ancestor, descendant, following, preceding and self axes partition a document (ignoring attribute and namespace nodes): they do not overlap and together they contain all the nodes in the document.

In a sequence of nodes selected by a step, the context positions of the nodes are determined in a way that depends on the axis. If the axis is a forward axis, context positions are assigned to the nodes in document order. If the axis is a reverse axis, context positions are assigned to the nodes in reverse document order. In either case, the first context position is 1.

3.2.1.2 Node Tests

A node test is a condition that must be true for each node selected by a step. The condition may be based on the kind of the node (element, attribute, text, document, comment, processing instruction, or namespace), the name of the node, or (in the case of element and attribute nodes), the type annotation of the node.

[90]    NodeTest    ::=    KindTest | NameTest
[91]    NameTest    ::=    QName | Wildcard
[92]    Wildcard    ::=    "*"
| (NCName ":" "*")
| ("*" ":" NCName)
/* ws: explicit */

Every axis has a principal node kind. If an axis can contain elements, then the principal node kind is element; otherwise, it is the kind of nodes that the axis can contain. Thus:

  • For the attribute axis, the principal node kind is attribute.

  • For all other axes, the principal node kind is element.

A node test that consists of a QName is called a name test. A name test is true if and only if the kind of the node is the principal node kind and the expanded-QName of the node is equal to the expanded-QName specified by the name test. For example, child::para selects the para element children of the context node; if the context node has no para children, it selects an empty set of nodes. attribute::abc:href selects the attribute of the context node with the QName abc:href; if the context node has no such attribute, it selects an empty set of nodes.

A QName in a name test is expanded into an expanded-QName using the in-scope namespaces in the expression context. It is a static error [err:XP0008] if the QName has a prefix that does not correspond to any in-scope namespace. An unprefixed QName, when used as a name test on an axis whose principal node kind is element, has the namespaceURI of the default element/type namespace in the expression context; otherwise, it has no namespaceURI.

A name test is not satisfied by an element node whose name does not match the QName of the name test, even if it is in a substitution group whose head is the named element.

A node test * is true for any node of the principal node kind. For example, child::* will select all element children of the context node, and attribute::* will select all attributes of the context node.

A node test can have the form NCName:*. In this case, the prefix is expanded in the same way as with a QName, using the in-scope namespaces in the static context. If the prefix is not found in the in-scope namespaces, a static error is raised.[err:XP0008] The node test is true for any node of the principal node kind whose expanded-QName has the namespace URI to which the prefix is bound, regardless of the local part of the name.

A node test can also have the form *:NCName. In this case, the node test is true for any node of the principal node kind whose local name matches the given NCName, regardless of its namespace.

An alternative form of a node test is called a KindTest, which can select nodes based on their kind, name, and type annotation. The syntax and semantics of a KindTest are described in 2.4.1 SequenceType. When a KindTest is used in a node test, only those nodes on the designated axis that match the KindTest are selected. Shown below are several examples of KindTests that might be used in path expressions:

  • node() matches any node.

  • text() matches any text node.

  • comment() matches any comment node.

  • element() matches any element node.

  • element(person) matches any element node whose name is person (or is in the substitution group headed by person), and whose type annotation conforms to the top-level schema declaration for a person element.

  • element(person, *) matches any element node whose name is person (or is in the substitution group headed by person), without any restriction on type annotation.

  • element(person, surgeon) matches any element node whose name is person (or is in the substitution group headed by person), and whose type annotation is surgeon.

  • element(*, surgeon) matches any element node whose type annotation is surgeon, regardless of its name.

  • element(hospital/staff/person) matches any element node whose name and type annotation conform to the schema declaration of a person element in a staff element in a top-level hospital element.

  • attribute() matches any attribute node.

  • attribute(@price, *) matches any attribute whose name is price, regardless of its type annotation.

  • attribute(@*, xs:decimal) matches any attribute whose type annotation is xs:decimal, regardless of its name.

  • document-node() matches any document node.

  • document-node(element(book)) matches any document node whose content consists of a single element node that satisfies the KindTest element(book), mixed with zero or more comments and processing instructions.

3.2.2 Predicates

[76]    Predicates    ::=    ("[" Expr "]")*

A predicate consists of an expression, called a predicate expression, enclosed in square brackets. A predicate serves to filter a sequence, retaining some items and discarding others. For each item in the sequence to be filtered, the predicate expression is evaluated using an inner focus derived from that item, as described in 2.1.2 Dynamic Context. The result of the predicate expression is coerced to a Boolean value, called the predicate truth value, as described below. Those items for which the predicate truth value is true are retained, and those for which the predicate truth value is false are discarded.

The predicate truth value is derived by applying the following rules, in order:

  1. If the value of the predicate expression is an atomic value of a numeric type, the predicate truth value is true if the value of the predicate expression is equal to the context position, and is false otherwise.

  2. Otherwise, the predicate truth value is the effective boolean value of the predicate expression.

Here are some examples of axis steps that contain predicates:

  • This example selects the second chapter element that is a child of the context node:

    child::chapter[2]
    
  • This example selects all the descendants of the context node whose name is "toy" and whose color attribute has the value "red":

    descendant::toy[attribute::color = "red"]
    
  • This example selects all the employee children of the context node that have a secretary subelement:

    child::employee[secretary]
    

Here are some examples of filter steps that contain predicates:

  • List all the integers from 1 to 100 that are divisible by 5. (See 3.3.1 Constructing Sequences for an explanation of the to operator.)

    (1 to 100)[. mod 5 eq 0]
    
  • The result of the following expression is the integer 95:

    (99 to 0)[5]
    

3.2.3 Unabbreviated Syntax

This section provides a number of examples of path expressions in which the axis is explicitly specified in each step. The syntax used in these examples is called the unabbreviated syntax. In many common cases, it is possible to write path expressions more concisely using an abbreviated syntax, as explained in 3.2.4 Abbreviated Syntax.

  • child::para selects the para element children of the context node

  • child::* selects all element children of the context node

  • child::text() selects all text node children of the context node

  • child::node() selects all the children of the context node, whatever their node type

  • attribute::name selects the name attribute of the context node

  • attribute::* selects all the attributes of the context node

  • parent::* selects the parent of the context node. If the context node is an attribute node, this expression returns the element node (if any) to which the attribute node is attached.

  • descendant::para selects the para element descendants of the context node

  • ancestor::div selects all div ancestors of the context node

  • ancestor-or-self::div selects the div ancestors of the context node and, if the context node is a div element, the context node as well

  • descendant-or-self::para selects the para element descendants of the context node and, if the context node is a para element, the context node as well

  • self::para selects the context node if it is a para element, and otherwise selects nothing

  • child::chapter/descendant::para selects the para element descendants of the chapter element children of the context node

  • child::*/child::para selects all para grandchildren of the context node

  • / selects the root of the node hierarchy that contains the context node

  • /descendant::para selects all the para elements in the same document as the context node

  • /descendant::list/child::member selects all the member elements that have a list parent and that are in the same document as the context node

  • child::para[fn:position() = 1] selects the first para child of the context node

  • child::para[fn:position() = fn:last()] selects the last para child of the context node

  • child::para[fn:position() = fn:last()-1] selects the last but one para child of the context node

  • child::para[fn:position() > 1] selects all the para children of the context node other than the first para child of the context node

  • following-sibling::chapter[fn:position() = 1]selects the next chapter sibling of the context node

  • preceding-sibling::chapter[fn:position() = 1]selects the previous chapter sibling of the context node

  • /descendant::figure[fn:position() = 42] selects the forty-second figure element in the document

  • /child::doc/child::chapter[fn:position() = 5]/child::section[fn:position() = 2]selects the second section of the fifth chapter of the doc document element

  • child::para[attribute::type="warning"]selects all para children of the context node that have a type attribute with value warning

  • child::para[attribute::type='warning'][fn:position() = 5]selects the fifth para child of the context node that has a type attribute with value warning

  • child::para[fn:position() = 5][attribute::type="warning"]selects the fifth para child of the context node if that child has a type attribute with value warning

  • child::chapter[child::title='Introduction']selects the chapter children of the context node that have one or more title children with string-value equal to Introduction

  • child::chapter[child::title] selects the chapter children of the context node that have one or more title children

  • child::*[self::chapter or self::appendix] selects the chapter and appendix children of the context node

  • child::*[self::chapter or self::appendix][fn:position() = fn:last()] selects the last chapter or appendix child of the context node

3.2.4 Abbreviated Syntax

[86]    AbbrevForwardStep    ::=    "@"? NodeTest
[87]    AbbrevReverseStep    ::=    ".."

The abbreviated syntax permits the following abbreviations:

  1. The most important abbreviation is that the axis name can be omitted from an axis step. If the axis name is omitted from an axis step, the default axis is child unless the axis step contains an AttributeTest; in that case, the default axis is attribute. For example, the path expression section/para is an abbreviation for child::section/child::para, and the path expression section/@id is an abbreviation for child::section/attribute::id. Similarly, section/attribute(@id) is an abbreviation for child::section/attribute::attribute(@id). Note that the latter expression contains both an axis specification and a node test.

  2. There is also an abbreviation for attributes: attribute:: can be abbreviated by @. For example, a path expression para[@type="warning"] is short for child::para[attribute::type="warning"] and so selects para children with a type attribute with value equal to warning.

  3. // is effectively replaced by /descendant-or-self::node()/ during processing of a path expression. For example, //para is an abbreviation for /descendant-or-self::node()/child::para and so will select any para element in the document (even a para element that is a document element will be selected by //para since the document element node is a child of the root node); div1//para is short for div1/descendant-or-self::node()/child::para and so will select all para descendants of div1 children.

    Note that the path expression //para[1] does not mean the same as the path expression /descendant::para[1]. The latter selects the first descendant para element; the former selects all descendant para elements that are the first para children of their parents.

  4. A step consisting of .. is short for parent::node(). For example, ../title is short for parent::node()/child::title and so will select the title children of the parent of the context node.

Note:

The expression ., known as a context item expression, is a primary expression, and is described in 3.1.4 Context Item Expression.

Here are some examples of path expressions that use the abbreviated syntax:

  • para selects the para element children of the context node

  • * selects all element children of the context node

  • text() selects all text node children of the context node

  • @name selects the name attribute of the context node

  • @* selects all the attributes of the context node

  • para[1] selects the first para child of the context node

  • para[fn:last()] selects the last para child of the context node

  • */para selects all para grandchildren of the context node

  • /doc/chapter[5]/section[2] selects the second section of the fifth chapter of the doc

  • chapter//para selects the para element descendants of the chapter element children of the context node

  • //para selects all the para descendants of the document root and thus selects all para elements in the same document as the context node

  • //list/member selects all the member elements in the same document as the context node that have a list parent

  • .//para selects the para element descendants of the context node

  • .. selects the parent of the context node

  • ../@lang selects the lang attribute of the parent of the context node

  • para[@type="warning"] selects all para children of the context node that have a type attribute with value warning

  • para[@type="warning"][5] selects the fifth para child of the context node that has a typeattribute with value warning

  • para[5][@type="warning"] selects the fifth para child of the context node if that child has a type attribute with value warning

  • chapter[title="Introduction"] selects the chapter children of the context node that have one or more title children with string-value equal to Introduction

  • chapter[title] selects the chapter children of the context node that have one or more title children

  • employee[@secretary and @assistant] selects all the employee children of the context node that have both a secretary attribute and an assistant attribute

  • book/(chapter|appendix)/section selects every section element that has a parent that is either a chapter or an appendix element, that in turn is a child of a book element that is a child of the context node.

  • book/fn:id(publisher)/name returns the same result as fn:id(book/publisher)/name.

  • If E is any expression that returns a sequence of nodes, then the expression E/. returns the same nodes in document order, with duplicates eliminated based on node identity.

3.3 Sequence Expressions

XQuery supports operators to construct and combine sequences of items. Sequences are never nested--for example, combining the values 1, (2, 3), and ( ) into a single sequence results in the sequence (1, 2, 3).

3.3.1 Constructing Sequences

[40]    Expr    ::=    ExprSingle ("," ExprSingle)*
[62]    RangeExpr    ::=    AdditiveExpr ( "to" AdditiveExpr )?

One way to construct a sequence is by using the comma operator, which evaluates each of its operands and concatenates the resulting values, in order, into a single result sequence. Empty parentheses can be used to denote an empty sequence. In places where the grammar calls for ExprSingle, such as the arguments of a function call, any expression that contains a top-level comma operator must be enclosed in parentheses.

A sequence may contain duplicate values or nodes, but a sequence is never an item in another sequence. When a new sequence is created by concatenating two or more input sequences, the new sequence contains all the items of the input sequences and its length is the sum of the lengths of the input sequences.

Here are some examples of expressions that construct sequences:

  • This expression is a sequence of five integers:

    (10, 1, 2, 3, 4)
    
  • This expression constructs one sequence from the sequences 10, (1, 2), the empty sequence (), and (3, 4):

    (10, (1, 2), (), (3, 4))
    

    It evaluates to the sequence:

    10, 1, 2, 3, 4

  • This expression contains all salary children of the context node followed by all bonus children:

    (salary, bonus)
    
  • Assuming that $price is bound to the value 10.50, this expression:

    ($price, $price)
    

    evaluates to the sequence

    10.50, 10.50

A RangeExpr can be used to construct a sequence of consecutive integers. Each of the operands of the to operator is converted as though it was an argument of a function with the expected parameter type xs:integer. A type error [err:XP0006] is raised if the operand cannot be converted to a single integer. A sequence is constructed containing the two integer operands and every integer between the two operands. If the first operand is less than the second, the sequence is in increasing order, otherwise it is in decreasing order.

  • This example uses a range expression as one operand in constructing a sequence:

    (10, 1 to 4)
    

    It evaluates to the sequence:

    10, 1, 2, 3, 4

  • This example constructs a sequence of length one:

    10 to 10
    

    It evaluates to a sequence consisting of the single integer 10.

3.3.2 Combining Sequences

[66]    UnionExpr    ::=    IntersectExceptExpr ( ("union" | "|") IntersectExceptExpr )*
[67]    IntersectExceptExpr    ::=    ValueExpr ( ("intersect" | "except") ValueExpr )*
[68]    ValueExpr    ::=    ValidateExpr | PathExpr

XQuery provides several operators for combining sequences of nodes. The union and | operators are equivalent. They take two node sequences as operands and return a sequence containing all the nodes that occur in either of the operands. The intersect operator takes two node sequences as operands and returns a sequence containing all the nodes that occur in both operands. The except operator takes two node sequences as operands and returns a sequence containing all the nodes that occur in the first operand but not in the second operand. All of these operators return their result sequences in document order without duplicates based on node identity. If an operand of union, intersect, or except contains an item that is not a node, a type error is raised.[err:XP0006]

Here are some examples of expressions that combine sequences. Assume the existence of three element nodes that we will refer to by symbolic names A, B, and C. Assume that $seq1 is bound to a sequence containing A and B, $seq2 is also bound to a sequence containing A and B, and $seq3 is bound to a sequence containing B and C. Then:

  • $seq1 union $seq1 evaluates to a sequence containing A and B.

  • $seq2 union $seq3 evaluates to a sequence containing A, B, and C.

  • $seq1 intersect $seq1 evaluates to a sequence containing A and B.

  • $seq2 intersect $seq3 evaluates to a sequence containing B only.

  • $seq1 except $seq2 evaluates to the empty sequence.

  • $seq2 except $seq3 evaluates to a sequence containing A only.

In addition to the sequence operators described here,[XQuery 1.0 and XPath 2.0 Functions and Operators] includes functions for indexed access to items or sub-sequences of a sequence, for indexed insertion or removal of items in a sequence, and for removing duplicate values or nodes from a sequence.

3.4 Arithmetic Expressions

XQuery provides arithmetic operators for addition, subtraction, multiplication, division, and modulus, in their usual binary and unary forms.

[63]    AdditiveExpr    ::=    MultiplicativeExpr ( ("+" | "-") MultiplicativeExpr )*
[64]    MultiplicativeExpr    ::=    UnaryExpr ( ("*" | "div" | "idiv" | "mod") UnaryExpr )*
[65]    UnaryExpr    ::=    ("-" | "+")* UnionExpr

The binary subtraction operator must be preceded by whitespace if it could otherwise be interpreted as part of the previous token. For example, a-b will be interpreted as a name, but a - b will be interpreted as an arithmetic operation.

An arithmetic expression is evaluated by applying the following rules, in order, until an error is raised or a value is computed:

  1. Atomization is applied to each operand.

  2. If either operand is now an empty sequence, the result of the operation is an empty sequence.

  3. If either operand is now a sequence of length greater than one, a type error is raised.[err:XP0006]

  4. If either operand is now of type xdt:untypedAtomic, it is cast to the default type for the given operator. The default type for the idiv operator is xs:integer; the default type for all other arithmetic operators is xs:double. If the cast fails, a dynamic error is raised.[err:XP0021]

  5. If the operand types are now valid for the given operator, the operator is applied to the operands, resulting in an atomic value or a dynamic error (for example, an error might result from dividing by zero.) The combinations of atomic types that are accepted by the various arithmetic operators, and their respective result types, are listed in B.2 Operator Mapping together with the functions in [XQuery 1.0 and XPath 2.0 Functions and Operators] that define the semantics of the operation for each type.

  6. If the operand types are still not valid for the given operator, a type error is raised.

XQuery supports two division operators named div and idiv. The div operator accepts operands of any numeric types. The type of the result of the div operator is the least common type of its operands; however, if both operands are of type xs:integer, div returns a result of type xs:decimal. The idiv operator, on the other hand, requires its operands to be of type xs:integer and returns a result of type xs:integer, rounded toward zero.

Here are some examples of arithmetic expressions:

  • The first expression below returns -1.5, and the second expressions returns -1:

    -3 div 2
    -3 idiv 2
    
  • Subtraction of two date values results in a value of type xdt:dayTimeDuration:

    $emp/hiredate - $emp/birthdate
    
  • This example illustrates the difference between a subtraction operator and a hyphen:

    $unit-price - $unit-discount
    
  • Unary operators have higher precedence than binary operators, subject of course to the use of parentheses:

    -($bellcost + $whistlecost)
    

3.5 Comparison Expressions

Comparison expressions allow two values to be compared. XQuery provides four kinds of comparison expressions, called value comparisons, general comparisons, node comparisons, and order comparisons.

[61]    ComparisonExpr    ::=    RangeExpr ( (ValueComp
| GeneralComp
| NodeComp
| OrderComp) RangeExpr )?
[81]    ValueComp    ::=    "eq" | "ne" | "lt" | "le" | "gt" | "ge"
[80]    GeneralComp    ::=    "=" | "!=" | "<" | "<=" | ">" | ">=" /* gn: lt */
[82]    NodeComp    ::=    "is" | "isnot"
[83]    OrderComp    ::=    "<<" | ">>"

3.5.1 Value Comparisons

Value comparisons are intended for comparing single values. The result of a value comparison is defined by applying the following rules, in order:

  1. Atomization is applied to each operand. If the result, called an atomized operand, does not contain exactly one atomic value, a type error is raised.[err:XQ0004][err:XP0006]

  2. Any atomized operand that has the dynamic type xdt:untypedAtomic is cast to the type xs:string.

  3. The result of the comparison is true if the value of the first operand is (equal, not equal, less than, less than or equal, greater than, greater than or equal) to the value of the second operand; otherwise the result of the comparison is false. B.2 Operator Mapping describes which combinations of atomic types are comparable, and how comparisons are performed on values of various types. If the value of the first atomized operand is not comparable with the value of the second atomized operand, a type error is raised.[err:XQ0004][err:XP0006]

Here are some examples of value comparisons:

  • The following comparison is true only if $book1 has a single author subelement and its value is "Kennedy":

    $book1/author eq "Kennedy"
    
  • The following comparison is true because the two constructed nodes have the same value after atomization, even though they have different identities:

    <a>5</a> eq <a>5</a>
    
  • The following comparison is true if hatsize and shoesize are both user-defined types that are derived by restriction from a primitive numeric type:

    hatsize(5) eq shoesize(5)
    

3.5.2 General Comparisons

General comparisons are existentially quantified comparisons that may be applied to operand sequences of any length. The result of a general comparison that does not raise an error is always true or false.

Atomization is applied to each operand of a general comparison. The result of the comparison is true if and only if there is a pair of atomic values, one belonging to the result of atomization of the first operand and the other belonging to the result of atomization of the second operand, that have the required magnitude relationship. Otherwise the result of the general comparison is false. The magnitude relationship between two atomic values is determined as follows:

  1. If either atomic value has the dynamic type xdt:untypedAtomic, that value is cast to a required type, which is determined as follows:

    1. If the dynamic type of the other atomic value is a numeric type, the required type is xs:double.

    2. If the dynamic type of the other atomic value is xdt:untypedAtomic, the required type is xs:string.

    3. Otherwise, the required type is the dynamic type of the other atomic value.

    If the cast to the required type fails, a dynamic error is raised.[err:XP0021]

  2. After any necessary casting, the atomic values are compared using one of the value comparison operators eq, ne, lt, le, gt, or ge, depending on whether the general comparison operator was =, !=, <, <=, >, or >=. The values have the required magnitude relationship if the result of this value comparison is true.

When evaluating a general comparison in which either operand is a sequence of items, an implementation may return true as soon as it finds an item in the first operand and an item in the second operand for which the underlying value comparison is true. Similarly, a general comparison may raise a dynamic error as soon as it encounters an error in evaluating either operand, or in comparing a pair of items from the two operands. As a result of these rules, the result of a general comparison is not deterministic in the presence of errors.

Here are some examples of general comparisons:

  • The following comparison is true if the value of any author subelement of $book1 has the string value "Kennedy":

    $book1/author = "Kennedy"
    
  • The following example contains three general comparisons. The value of the first two comparisons is true, and the value of the third comparison is false. This example illustrates the fact that general comparisons are not transitive.

    (1, 2) = (2, 3)
    (2, 3) = (3, 4)
    (1, 2) = (3, 4)
    
  • Suppose that $a, $b, and $c are bound to element nodes with type annotation xdt:untypedAtomic, with string values "1", "2", and "2.0" respectively. Then ($a, $b) = ($c, 3.0) returns false, because $b and $c are compared as strings. However, ($a, $b) = ($c, 2.0) returns true, because $b and 2.0 are compared as numbers.

3.5.3 Node Comparisons

The result of a node comparison is defined by applying the following rules, in order:

  1. Each operand must be either a single node or an empty sequence; otherwise a type error is raised.[err:XQ0004][err:XP0006]

  2. If either operand is an empty sequence, the result of the comparison is an empty sequence.

  3. A comparison with the is operator is true if the two operands are nodes that have the same identity; otherwise it is false. A comparison with the isnot operator is true if the two operands are nodes that have different identities; otherwise it is false. See [XQuery 1.0 and XPath 2.0 Data Model] for a discussion of node identity.

Use of the is operator is illustrated below.

  • The following comparison is true only if the left and right sides each evaluate to exactly the same single node:

    //book[isbn="1558604820"] is //book[call="QA76.9 C3845"]
    
  • The following comparison is false because each constructed node has its own identity:

    <a>5</a> is <a>5</a>
    

3.5.4 Order Comparisons

The result of an order comparison is defined by applying the following rules, in order:

  1. Both operands must be either a single node or an empty sequence; otherwise a type error is raised.[err:XQ0004][err:XP0006]

  2. If either operand is an empty sequence, the result of the comparison is an empty sequence.

  3. A comparison with the << operator returns true if the first operand node is earlier than the second operand node in document order; otherwise it returns false.

  4. A comparison with the >> operator returns true if the first operand node is later than the second operand node in document order; otherwise it returns false.

Here is an example of an order comparison:

  • The following comparison is true only if the node identified by the left side occurs before the node identified by the right side in document order:

    //purchase[parcel="28-451"] << //sale[parcel="33-870"]
    

3.6 Logical Expressions

A logical expression is either an and-expression or an or-expression. If a logical expression does not raise an error, its value is always one of the boolean values true or false.

Logical Expressions
[55]    OrExpr    ::=    AndExpr ( "or" AndExpr )*
[56]    AndExpr    ::=    InstanceofExpr ( "and" InstanceofExpr )*

The first step in evaluating a logical expression is to find the effective boolean value of each of its operands (see 2.4.2.2 Effective Boolean Value).

The value of an and-expression is determined by the effective boolean values (EBV's) of its operands. If an error is raised during computation of one of the effective boolean values, an and-expression may raise a dynamic error, as shown in the following table:

AND: EBV2 = true EBV2 = false error in EBV2
EBV1 = true true false error
EBV1 = false false false false or error
error in EBV1 error false or error error

The value of an or-expression is determined by the effective boolean values (EBV's) of its operands. If an error is raised during computation of one of the effective boolean values, an or-expression may raise a dynamic error, as shown in the following table:

OR: EBV2 = true EBV2 = false error in EBV2
EBV1 = true true true true or error
EBV1 = false true false error
error in EBV1 true or error error error

The order in which the operands of a logical expression are evaluated is implementation-dependent. The tables above are defined in such a way that an or-expression can return true if the first expression evaluated is true, and it can raise an error if evaluation of the first expression raises an error. Similarly, an and-expression can return false if the first expression evaluated is false, and it can raise an error if evaluation of the first expression raises an error. As a result of these rules, a logical expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of logical expressions:

  • The following expressions return true:

    1 eq 1 and 2 eq 2
    
    1 eq 1 or 2 eq 3
    
  • The following expression may return either false or raise a dynamic error:

    1 eq 2 and 3 idiv 0 = 1
    
  • The following expression may return either true or raise a dynamic error:

    1 eq 1 or 3 idiv 0 = 1
    
  • The following expression must raise a dynamic error:

    1 eq 1 and 3 idiv 0 = 1
    

In addition to and- and or-expressions, XQuery provides a function named not that takes a general sequence as parameter and returns a boolean value. The not function reduces its parameter to an effective boolean value. It then returns true if the effective boolean value of its parameter is false, and false if the effective boolean value of its parameter is true. If an error is encountered in finding the effective boolean value of its operand, not raises the same dynamic error. The not function is described in [XQuery 1.0 and XPath 2.0 Functions and Operators].

3.7 Constructors

XQuery provides constructors that can create XML structures within a query. Constructors are provided for every kind of node in the data model ([XQuery 1.0 and XPath 2.0 Data Model]). Two kinds of constructors are provided: direct constructors, which use an XML-like notation, and computed constructors, which use a notation based on enclosed expressions.

[79]    Constructor    ::=    ElementConstructor
| XmlComment
| XmlPI
| CdataSection
| CompDocConstructor
| CompElemConstructor
| CompAttrConstructor
| CompNSConstructor
| CompTextConstructor
| CompXmlPI
| ComputedXmlComment
[97]    ElementConstructor    ::=    "<" QName AttributeList ("/>" | (">" ElementContent* "</" QName S? ">")) /* ws: explicit */
/* gn: lt */
[27]    ElementContentChar    ::=    Char - [{}<&]
[108]    ElementContent    ::=    ElementContentChar
| "{{"
| "}}"
| ElementConstructor
| EnclosedExpr
| CdataSection
| CharRef
| PredefinedEntityRef
| XmlComment
| XmlPI
/* ws: significant */
[109]    AttributeList    ::=    (S (QName S? "=" S? AttributeValue)?)* /* ws: explicit */
[110]    AttributeValue    ::=    ('"' (EscapeQuot | QuotAttrValueContent)* '"')
| ("'" (EscapeApos | AposAttrValueContent)* "'")
/* ws: significant */
[111]    QuotAttrValueContent    ::=    QuotAttContentChar
| CharRef
| "{{"
| "}}"
| EnclosedExpr
| PredefinedEntityRef
/* ws: significant */
[112]    AposAttrValueContent    ::=    AposAttContentChar
| CharRef
| "{{"
| "}}"
| EnclosedExpr
| PredefinedEntityRef
/* ws: significant */
[28]    QuotAttContentChar    ::=    Char - ["{}<&]
[29]    AposAttContentChar    ::=    Char - ['{}<&]
[17]    EscapeQuot    ::=    '"' '"'
[25]    EscapeApos    ::=    "''"
[113]    EnclosedExpr    ::=    "{" Expr "}"

This section contains a conceptual description of the semantics of various kinds of constructor expressions. An XQuery implementation is free to use any implementation technique that produces the same result as the processing steps described in this section.

3.7.1 Direct Element Constructors

An element constructor creates an XML element. If the name, attributes, and content of the element are all constants, the element constructor is based on standard XML notation and is called a direct element constructor. For example, the following expression is a direct element constructor that creates a book element containing attributes, subelements, and text:

<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>

Unqualified element names used in a direct element constructor are implicitly qualified by the default namespace for element names. In a direct element constructor, the name used in the end tag must exactly match the name used in the corresponding start tag, including its prefix or absence of a prefix.

In a direct element constructor, curly braces { } delimit enclosed expressions, distinguishing them from literal text. Enclosed expressions are evaluated and replaced by their value, whereas material outside curly braces is simply treated as literal text, as illustrated by the following example:

<example>
   <p> Here is a query. </p>
   <eg> $i//title </eg>
   <p> Here is the result of the query. </p>
   <eg>{ $i//title }</eg>
</example>

The above query might generate the following result (whitespace has been added for readability to this result and other result examples in this document):

<example>
  <p> Here is a query. </p>
  <eg> $i//title </eg>
  <p> Here is the result of the query. </p>
  <eg><title>Harold and the Purple Crayon</title></eg>
</example>

Since XQuery uses curly braces to denote enclosed expressions, some convention is needed to denote a curly brace used as an ordinary character. For this purpose, a pair of identical curly brace characters within the content of an element or attribute are interpreted by XQuery as a single curly brace character (that is, the pair "{{" represents the character "{" and the pair "}}" represents the character "}".) A single left curly brace ("{") is interpreted as the beginning delimiter for an enclosed expression. A single right curly brace ("}") without a matching left curly brace is treated as a static error.[err:XP0003]

The result of an element constructor is a new element node, with its own node identity. All the attribute and descendant nodes of the new element node are also new nodes with their own identities, even if they are copies of existing nodes.

The Base URI of a constructed element node is taken from the static context. The Base URIs of the copied descendant nodes are also taken from the static context rather than by preserving their original Base URIs.

3.7.1.1 Attributes

The start tag of a direct element constructor may contain one or more attributes. As in XML, each attribute is specified by a name and a value. In a direct element constructor, the name of each attribute is specified by a constant QName, and the value of the attribute is specified by a string of characters enclosed in single or double quotes. As in the main content of the element constructor, an attribute value may contain expressions enclosed in curly braces, which are evaluated and replaced by their value during processing of the element constructor.

Each attribute in a direct element constructor creates a new attribute node, with its own node identity, whose parent is the constructed element node. (Exception: namespace declaration attributes (see 3.7.1.2 Namespace Declaration Attributes) do not create attribute nodes.) All the attribute nodes generated by an element constructor must have distinct names.

Conceptually, an attribute (other than a namespace declaration attribute) in a direct element constructor is processed by the following steps:

  1. Predefined entity references and character references in the attribute content are expanded into their referenced strings, as described in 3.1.1 Literals.

  2. Each consecutive sequence of literal characters in the attribute content is treated as a string containing those characters. Whitespace in attribute content is normalized according to the rules for "Attribute Value Normalization" in [XML] (each whitespace character is replaced by a space (#x20) character.)

  3. Each enclosed expression is converted to a string as follows:

    1. Atomization is applied to the value of the enclosed expression, converting it to a sequence of atomic values.

    2. If the result of atomization is an empty sequence, the result is the zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

    3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair.

  4. Adjacent strings resulting from the above steps are concatenated with no intervening blanks. The resulting string becomes the value of the attribute.

  • Example:

    <shoe size="7"/>
    

    The value of the size attribute is "7".

  • Example:

    <shoe size="{7}"/>
    

    The value of the size attribute is "7".

  • Example:

    <shoe size="{()}"/>
    

    The value of the size attribute is the zero-length string.

  • Example:

    <chapter ref="[{1, 5 to 7, 9}]"/>
    

    The value of the ref attribute is "[1 5 6 7 9]".

  • Example:

    <shoe size="As big as {$hat/@size}"/>
    

    The value of the size attribute is the string "As big as ", concatenated with the string value of the node denoted by the expression $hat/@size.

3.7.1.2 Namespace Declaration Attributes

The names used inside an element constructor may be qualified names that include namespace prefixes. Namespace prefixes can be bound to namespaces in the Prolog, by namespace declaration attributes, or by computed namespace constructors. It is a static error to use a namespace prefix that has not been bound to a namespace.[err:XP0008]

A namespace declaration attribute is used inside a direct element constructor, and serves to add a namespace to the in-scope namespaces for the constructed element. A namespace declaration attribute always has the name xmlns or a QName with the prefix xmlns. If the value of a namespace declaration attribute is not a literal string, a static error is raised.[err:XQ0022] A namespace declaration attribute does not cause an attribute node to be created. Namespace declaration attributes are discussed further in 4.4 Namespace Declaration and [XML Names]. The following element constructor illustrates the use of namespace declaration attributes that define the namespace prefixes metric and english:

<box xmlns:metric = "http://example.org/metric/units"
     xmlns:english = "http://example.org/english/units">
  <height> <metric:meters>3</metric:meters> </height>
  <width> <english:feet>6</english:feet> </width>
  <depth> <english:inches>18</english:inches> </depth>
</box>
3.7.1.3 Content

The part of a direct element constructor between the start tag and the end tag is called the content of the element constructor. This content may consist of literal text characters, nested element constructors, and expressions enclosed in curly braces. In general, the value of an enclosed expression may be any sequence of nodes and/or atomic values. Enclosed expressions can be used in the content of an element constructor to compute both the content and the attributes of the constructed node.

Conceptually, the content of an element constructor is processed as follows:

  1. The content is evaluated to produce a sequence of nodes called the content sequence, as follows:

    1. Predefined entity references and character references are expanded into their referenced strings, as described in 3.1.1 Literals.

    2. Each consecutive sequence of literal characters evaluates to a single text node containing the characters. However, if the sequence consists entirely of boundary whitespace as defined in 3.7.1.4 Whitespace in Element Content and the Prolog does not specify xmlspace = preserve, then no text node is generated.

    3. Each nested element constructor is evaluated according to the rules in this section, resulting in a new element node.

    4. Enclosed expressions are evaluated as follows: For each node returned by an enclosed expression, a new deep copy of the node is constructed, including all its children, attributes, and namespace nodes (if any). Each copied node has a new node identity. Copied element nodes are given the type annotation xs:anyType, and copied attribute nodes are given the type annotation xs:anySimpleType. For each adjacent sequence of one or more atomic values returned by an enclosed expression, a new text node is constructed, containing the result of casting each atomic value to a string, with a single blank character inserted between adjacent values.

  2. If the content sequence contains a document node, a type error is raised.[err:XQ0023]

  3. If the content sequence contains an attribute node following a node that is not an attribute node, a type error is raised.[err:XQ0024] Attribute nodes occurring at the beginning of the content sequence become attributes of the new element node. If two or more attributes of the new element node have the same name, a dynamic error is raised.[err:XQ0025]

  4. Adjacent text nodes in the content sequence are coalesced into a single text node by concatenating their contents, with no intervening blanks.

  5. The resulting sequence of nodes becomes the children and attributes of the new element node in the data model representation.

  6. The new element node is automatically validated, as described in 3.7.1.5 Type of a Constructed Element.

  • Example:

    <a>{1}</a>
    

    The constructed element node has one child, a text node containing the value "1".

  • Example:

    <a>{1, 2, 3}</a>
    

    The constructed element node has one child, a text node containing the value "1 2 3".

  • Example:

    <c>{1}{2}{3}</c>
    

    The constructed element node has one child, a text node containing the value "123".

  • Example:

    <b>{1, "2", "3"}</b>
    

    The constructed element node has one child, a text node containing the value "1 2 3".

  • Example:

    <fact>I saw 8 cats.</fact>
    

    The constructed element node has one child, a text node containing the value "I saw 8 cats.".

  • Example:

    <fact>I saw {5 + 3} cats.</fact>
    

    The constructed element node has one child, a text node containing the value "I saw 8 cats.".

  • Example:

    <fact>I saw <howmany>{5 + 3}</howmany> cats.</fact>
    

    The constructed element node has three children: a text node containing "I saw ", a child element node named howmany, and a text node containing " cats.". The child element node in turn has a single text node child containing the value "8".

3.7.1.4 Whitespace in Element Content

In a direct element constructor, whitespace characters may appear in element content. In some cases, enclosed expressions and/or nested elements may be separated only by whitespace characters. For example, in the expression below, the end-tag </title> and the start-tag <author> are separated by a newline character and four space characters:

<book isbn="isbn-0060229357">
    <title>Harold and the Purple Crayon</title>
    <author>
        <first>Crockett</first>
        <last>Johnson</last>
    </author>
</book>

We will refer to whitespace characters that occur by themselves in the boundaries between tags and/or enclosed expressions, as in the above example, as boundary whitespace. The Prolog contains a declaration called xmlspace that controls whether boundary whitespace is preserved by element constructors. If xmlspace is not declared in the prolog or is declared as xmlspace = strip, boundary whitespace is not considered significant and is discarded. On the other hand, if xmlspace = preserve is declared in the prolog, boundary whitespace is considered significant and is preserved.

  • Example:

    <cat> <breed>{$b}</breed>
       <color>{$c}</color> 
    </cat>
    

    The constructed cat element node has two child element nodes named breed and color. Whitespace surrounding the child elements has been stripped away by the element constructor (assuming that the Prolog did not specify xmlspace = preserve.)

  • Example:

    <a> {"abc"} </a>
    

    If xmlspace is not declared or is declared as xmlspace = strip, this example is equivalent to <a>abc</a>. However, if xmlspace = preserve is declared, this example is equivalent to <a>  abc  </a>.

  • Example:

    <a> z {"abc"}</a>
    

    Since the whitespace surrounding the z is not boundary whitespace, it is always preserved. This example is equivalent to <a> z abc</a>.

For the purpose of the above rule, whitespace characters generated by character references such as &#x20; are not considered to be boundary whitespace, and are always preserved.

  • Example:

    <a>&#x20;{"abc"}</a>
    

    This example is equivalent to <a> abc</a>, regardless of the declaration of xmlspace.

It is important to remember that whitespace generated by an enclosed expression is never considered to be boundary whitespace, and is always preserved.

  • Example:

    <a>{" "}</a>
    

    This example is equivalent to <a>  </a>, regardless of the declaration of xmlspace.

3.7.1.5 Type of a Constructed Element

A direct element constructor automatically validates the newly constructed element, using the schema validation process described in [XML Schema]. The validation process results in a type annotation for the element node and for each of its attribute nodes. The validation process may also result in adding additional attributes, with default values, to the constructed element. Validation is performed using the validation mode and validation context from the static context of the element constructor, according to the following rules:

  • If validation mode = skip, no validation is attempted. The constructed element node is given a type annotation of xs:anyType, and each of its attributes is given a type annotation of xdt:untypedAtomic.

  • If validation mode = strict, the in-scope element declarations are searched for an element declaration whose unique name matches the name of the constructed element, as interpreted in the validation context of the element constructor. If no such element declaration is found, validation fails and a dynamic error [err:XQ0026] is raised (if the name of the constructed element is known statically, this can be a static error). If such an element declaration is found, the newly constructed element is converted to an Infoset representation using the rules for "Data Model to Infoset Mapping" in [XQuery 1.0 and XPath 2.0 Data Model]. The resulting Infoset is then validated according to the rules for "Assessing Schema Validity" in [XML Schema]. This validation process results in a Post-Schema Validation Infoset (PSVI). If, in this PSVI, the [validity] property of the constructed element is valid, then the PSVI is converted back into a data model representation, using the rules for "PSVI to Data Model Mapping" in [XQuery 1.0 and XPath 2.0 Data Model]. Otherwise, validation fails and a dynamic error is raised.[err:XQ0027]

  • If validation mode = lax, the in-scope element declarations are searched for an element declaration that matches the name of the constructed element, as interpreted in the validation context of the element constructor. If such an element declaration is found, the constructed element is processed as though validation mode = strict; otherwise it is processed as though validation mode = skip.

A direct element constructor adds the name of the constructed element to the validation context for expressions that are nested inside the element constructor. This process is illustrated by the following example:

<customer>
   <hat>{7}</hat> <shoe>{"8"}</shoe>
</customer>

If <customer> is the outermost element constructor in the query, it is validated with a global validation context. However, it adds the name of the constructed element to the validation context for nested expressions, causing <hat> and <shoe> to be validated with the validation context /customer.

It is important to understand that the type annotation of a constructed element may be different from the type of the expression from which the element was constructed. In the above example, the hat element was constructed from an expression of type xs:integer, and the shoe element was constructed from an expression of type xs:string. If validation mode = skip, then after validation the hat and shoe elements will both have a type annotation of xs:anyType. However, if validation mode = strict, then after validation the hat and shoe elements will have type annotations that are derived from their element declarations--possibly schema-defined types such as hatsize and shoesize.

The validation process for a constructed element may be affected by the presence of an xsi:type attribute. For example, the following constructed element has an attribute that causes it to be validated as an integer:

<a xsi:type="xs:integer">47</a>

3.7.2 Other Direct Constructors

XQuery allows a query to generate a processing instruction, an XML comment, or a CDATA section directly in the query result. In each case, this is accomplished by using a constructor expression whose syntax is based on the syntax of the equivalent construct in XML.

[105]    CdataSection    ::=    "<![CDATA[" Char* "]]>" /* ws: significant */
[106]    XmlPI    ::=    "<?" PITarget Char* "?>" /* ws: explicit */
[18]    PITarget    ::=    NCName
[107]    XmlComment    ::=    "<!--" Char* "-->" /* ws: significant */

Each of the above constructors is terminated by the first occurrence of its ending delimiter. In other words, the content of a processing instruction may not contain the string "?>", the content of an XML comment may not contain the string "-->", and the content of a CDATA section may not contain the string "]]>" .

The following example illustrates a constructed processing instruction:

<?format role="output" ?>

The following example illustrates a constructed XML comment:

<!-- Tags are ignored in the following section -->

Note that an XML comment constructor actually constructs a comment node in the data model. An XQuery comment, on the other hand, (see 3.1.6 XQuery Comments) is simply a comment used in documenting a query, and is not evaluated. Consider the following example.

(: This is an XQuery comment :)
<!-- This is an XML comment -->

The result of evaluating the above expression is as follows.

<!-- This is an XML comment -->

The following example illustrates a constructed CDATA section:

<![CDATA[ 
    <address>123 Roosevelt Ave. Flushing, NY 11368</address>
]]>

A CDATA section constructor constructs a text node whose content is the same as the content of the constructor. When this text node becomes a child of an element node, it is merged with adjacent text nodes in the normal way. A CDATA section constructor may be useful because it removes the need to escape special characters such as "<" and "&" within the scope of the CDATA section.

An implementation may choose to serialize text that was constructed using a CDATA section constructor by means of a CDATA section in the serialized output, but it is not obliged to do so. The fact that a CDATA section was used to construct the text is not visible in the data model.

3.7.3 Computed Constructors

An alternative way to create nodes is by using a computed constructor. A computed constructor begins with a keyword that identifies the type of node to be created: element, attribute, document, text, pi (denoting a processing instruction), comment, or namespace.

For those kinds of nodes that have names (element, attribute, processing instruction, and namespace nodes), the keyword that specifies the node kind is followed by the name of the node to be created. This name may be specified either as a QName or (except for namespace nodes) as an expression enclosed in braces, called the name expression, that returns a string or a QName.

The final part of a computed constructor is an expression enclosed in braces, called the content expression, that generates the content of the node.

[99]    CompElemConstructor    ::=    (("element" QName "{") | ("element" "{" Expr "}" "{")) Expr? "}"
[101]    CompAttrConstructor    ::=    (("attribute" QName "{") | ("attribute" "{" Expr "}" "{")) Expr? "}"
[98]    CompDocConstructor    ::=    "document" "{" Expr "}"
[104]    CompTextConstructor    ::=    "text" "{" Expr? "}"
[102]    CompXmlPI    ::=    (("pi" NCName "{") | ("pi" "{" Expr "}" "{")) Expr? "}"
[103]    ComputedXmlComment    ::=    "comment" "{" Expr "}"
[100]    CompNSConstructor    ::=    ("namespace" NCName "{") Expr "}"

The following example illustrates the use of computed element and attribute constructors in a simple case where the names of the constructed nodes are constants. This example generates exactly the same result as the first example in 3.7.1 Direct Element Constructors:

element book { 
   attribute isbn {"isbn-0060229357" }, 
   element title { "Harold and the Purple Crayon"},
   element author { 
      element first { "Crockett" }, 
      element last {"Johnson" }
   }
}
3.7.3.1 Computed Element Constructors

The name expression of a computed element constructor is processed as follows:

  1. If the name expression returns an expanded QName, that QName is used as the name of the constructed element.

  2. If the name expression returns a string, that string is cast to a QName and its prefix is expanded using the in-scope namespaces. The resulting expanded QName is used as the name of the constructed element. A dynamic error is raised if the string cannot be cast to a QName [err:XP0021] or if expansion of its prefix is not successful.[err:XP0008]

  3. If the name expression does not return a QName or a string, a type error is raised.[err:XQ0004][err:XP0006]



The content expression of a computed element constructor is processed as follows:

  1. For each node returned by the content expression, a new deep copy of the node is constructed, including all its children, attributes, and namespace nodes (if any). Each copied node has a new node identity. Copied element nodes are given the type annotation xs:anyType, and copied attribute nodes are given the type annotation xs:anySimpleType. For each adjacent sequence of one or more atomic values returned by the content expression, a new text node is constructed, containing the result of casting each atomic value to a string, with a single blank character inserted between adjacent values. The resulting sequence of nodes is called the content sequence. Any sequence of adjacent text nodes in the content sequence is merged into a single text node.

  2. If the content sequence contains a document node, a type error is raised.[err:XQ0023]

  3. If the content sequence contains a namespace node following a node that is not a namespace node, a type error is raised.[err:XQ0040] Namespace nodes occurring in the content sequence are attached to the constructed element node.

  4. If the content sequence contains an attribute node following a node that is not an attribute node or a namespace node, a type error is raised.[err:XQ0024] Attribute nodes occurring in the content sequence become attributes of the new element node. If two or more of these attribute nodes have the same name, an error is raised.[err:XQ0025]

  5. Element, text, comment, and processing instruction nodes in the content sequence become the children of the constructed element node.

The Base URI of a constructed element node is taken from the static context. The Base URIs of the copied descendant nodes are also taken from the static context rather than by preserving their original Base URIs.

A computed element constructor automatically validates the constructed node, using the validation mode and validation context from its static context, as described in 3.7.1.5 Type of a Constructed Element. If the name of the constructed element is specified by a constant QName, this QName is added to the validation context for nested expressions. On the other hand, if the name of the constructed element is specified by a name expression, the validation context for nested expressions is set to global.

A computed element constructor might be used to make a modified copy of an existing element. For example, if the variable $e is bound to an element with numeric content, the following constructor might be used to create a new element with the same name and attributes as $e and with numeric content equal to twice the value of $e:

element {node-name($e)}
   {$e/@*, 2 * data($e)}

In this example, if $e is bound by the expression let $e := <length units="inches">{5}</length>, then the result of the example expression is the element <length units="inches">10</length>.

One important purpose of computed constructors is to allow the name of a node to be computed. We will illustrate this feature by an expression that translates the name of an element from one language to another. Suppose that the variable $dict is bound to a sequence of entries in a translation dictionary. Here is an example entry:

<entry word="address">
   <variant lang="German">Adresse</variant>
   <variant lang="Italian">indirizzo</variant>
</entry> 

Suppose further that the variable $e is bound to the following element:

<address>123 Roosevelt Ave. Flushing, NY 11368</address>

Then the following expression generates a new element in which the name of $e has been translated into Italian and the content of $e (including its attributes, if any) has been preserved. The first enclosed expression after the element keyword generates the name of the element, and the second enclosed expression generates the content and attributes:

  element 
    {data($dict/entry[word=name($e)]/variant[lang="Italian"])}
    {$e/@*, $e/*}

The result of this expression is as follows:

<indirizzo>123 Roosevelt Ave. Flushing, NY 11368</indirizzo>

Additional examples of computed element constructors can be found in G.4 Recursive Transformations.

3.7.3.2 Computed Attribute Constructors

The name expression of a computed attribute constructor is processed as follows:

  1. If the name expression returns an expanded QName, that QName is used as the name of the constructed attribute.

  2. If the name expression returns a string, that string is cast to a QName and the resulting expanded QName is used as the name of the constructed attribute. However, if the string begins with xmlns, a dynamic error is raised.[err:XQ0044] If the string cannot be cast to a QName, a dynamic error is raised.[err:XP0021]

  3. If the name expression does not return a QName or a string, a dynamic error is raised.[err:XP0006]

The content expression of a computed attribute constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, the value of the attribute is the zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string, as an instance of xs:untypedAtomic, is the value of the attribute.

A computed attribute constructor does not perform any automatic validation of the constructed attribute. However, if the computed attribute constructor is inside an element constructor, the attribute will be validated during validation of its parent element.

  • Example:

    attribute size {4 + 3}
    

    The value of the size attribute is "7".

  • Example:

    attribute
       { if ($sex = "M") then "husband" else "wife" }
       { <a>Hello</a>, 1 to 3, <b>Goodbye</b> }
    

    The name of the constructed attribute is either husband or wife. Its value is "Hello 1 2 3 Goodbye".

An attribute generated by a computed attribute constructor must not be a namespace declaration attribute--that is, its name must not be xmlns or a QName with prefix xmlns.

3.7.3.3 Document Node Constructors

All document node constructors are computed constructors. The result of a document node constructor is a new document node, with its own node identity.

A document node constructor is useful when the result of a query is to be a document in its own right. The following example illustrates a query that returns an XML document containing a root element named author-list:

document
   {
      <author-list>
         {doc("bib.xml")//book/author}
      </author-list>
   }

The content expression of a document node constructor is processed as follows:

  1. For each node returned by the content expression, a new deep copy of the node is constructed, including its children, attributes, and namespace nodes (if any). Each copied node has a new node identity. Copied element nodes are given the type annotation xs:anyType, and copied attribute nodes are given the type annotation xs:anySimpleType. For each adjacent sequence of one or more atomic values returned by the content expression, a new text node is constructed, containing the result of casting each atomic value to a string, with a single blank character inserted between adjacent values. The resulting sequence of nodes is called the content sequence.

  2. If the content sequence contains a document, attribute, or namespace node, a type error is raised.[err:XQ0028]

  3. The resulting sequence of nodes becomes the children of the new document node.

The base URI of a constructed document node is taken from the static context.

No schema validation is performed on the constructed document. The [XML] rules that govern the structure of an XML document (for example, the document node must have exactly one child that is an element node) are not enforced by the XQuery document node constructor.

3.7.3.4 Text Node Constructors

All text node constructors are computed constructors. The result of a text node constructor is a new text node, with its own node identity.

The content expression of a text node constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, no text node is constructed. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content of the constructed text node.

The following example illustrates a text node constructor:

text {"Hello"}
3.7.3.5 Computed Processing Instruction Constructors

A computed processing instruction constructor (CompXmlPI) constructs a new processing instruction node with its own node identity. The name expression of a computed processing instruction constructor is processed as follows:

  1. If the name expression returns an expanded QName: If the URI part of the QName is empty, the local part of the QName is used as the name (target) of the processing instruction; otherwise a dynamic error is raised.[err:XQ0041]

  2. If the name expression returns a string, that string is cast to a QName, which is then treated as in the previous item. If the cast fails, a dynamic error is raised.[err:XP0021]

  3. If the name expression does not return a QName or a string, a dynamic error is raised.[err:XP0006]

The content expression of a computed processing instruction constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, it is replaced by a zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content of the constructed processing instruction.

The following query contains an example of a computed processing instruction constructor. The result of the query is a processing instruction node.

let $target := "audio-output",
    $content := "beep" return
    pi {$target} {$content}
3.7.3.6 Computed Comment Constructors

A computed comment constructor (ComputedXMLComment) constructs a new comment node with its own node identity. The content expression of a computed comment constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, it is replaced by a zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content of the constructed comment.

The following query contains an example of a computed comment constructor. The result of the query is a comment node.

let $homebase := "Houston" return
comment {fn:concat($homebase, ", we have a problem.")}
3.7.3.7 Computed Namespace Constructors

A computed namespace constructor (CompNSConstructor) constructs a new namespace node with its own node identity. The immediately enclosing expression of the computed namespace constructor must be a computed element constructor; otherwise a static error is raised.[err:XQ0042] The constructed namespace node is attached to the element node constructed by the enclosing expression.

A constructed namespace node is the dynamic equivalent of a namespace declaration attribute. It binds a namespace prefix to a URI and adds the namespace prefix to the in-scope namespaces for its enclosing element.

The name expression of a computed namespace constructor is processed as follows:

  1. If the name expression returns an expanded QName: If the URI part of the QName is empty, the local part of the QName is used as the name (prefix) of the namespace node; otherwise a dynamic error is raised.[err:XQ0041] If two or more computed namespace constructors within the same computed element constructor attempt to bind the same prefix, a dynamic error is raised.[err:XQ0043]

  2. If the name expression returns a string, that string is cast to a QName, which is then treated as in the previous item. If the cast fails, a dynamic error is raised.[err:XP0021]

  3. If the name expression does not return a QName or a string, a dynamic error is raised.[err:XP0006]

The content expression of a computed namespace constructor is processed as follows:

  1. Atomization is applied to the value of the content expression, converting it to a sequence of atomic values.

  2. If the result of atomization is an empty sequence, it is replaced by a zero-length string. Otherwise, each atomic value in the atomized sequence is cast into a string.

  3. The individual strings resulting from the previous step are merged into a single string by concatenating them with a single space character between each pair. The resulting string becomes the content (URI) of the constructed namespace node.

The following query contains an example of a computed namespace constructor, properly nested within a computed element constructor. The computed namespace constructor defines the namespace prefix metric, which is used in a computed attribute constructor.

let $ename := "altitude",
    $evalue := "10000", 
    $nsURI := "http://example.org/metric-system",
    $attrname := "metric:unit",
    $attrvalue := "meter" 
    return
       element {$ename} {
          namespace metric {$nsURI},
          attribute {$attrname} {$attrvalue},
          $evalue
       }

The previous example is equivalent to the following direct element constructor:

<altitude
   xmlns:metric = "http://example.org/metric-system"
   metric:unit = "meter">10000</altitude>

3.7.4 Namespace Nodes on Constructed Elements

When an element node is constructed by either a direct or computed element constructor, it may have some attached namespace nodes. These namespace nodes do not affect the resolution of namespace prefixes during query processing. The resolution of namespace prefixes during processing of a query expression is done strictly according to the in-scope namespaces of the expression. The namespace nodes that are attached to an element may affect the way the element is serialized (see 2.2.4 Serialization). Namespace nodes may also affect the behavior of certain functions that operate on nodes, such as fn:name.

This section specifies the namespace nodes that are attached to a constructed element. For this purpose, it introduces the terms active namespace and passive namespace. [Definition: A namespace that is declared by a namespace declaration attribute in a direct element constructor, or by a computed namespace constructor inside a computed element constructor, is classified as an active namespace.] [Definition: A namespace that is declared in the Prolog, or that is predefined in the static context, is classified as a passive namespace, except for the predefined xml namespace, which is classified as active.]

When an element is constructed by a direct or computed element constructor, the namespace nodes attached to the element node are listed below. These namespace nodes are attached to the element node before any validation takes place.

  • A namespace node is created corresponding to each in-scope active namespace--that is, each namespace declared in a namespace declaration attribute of this (or any enclosing) direct element constructor, each computed namespace within this (or any enclosing) computed element constructor, and the xml namespace. These namespace nodes use the same prefixes and URIs as the namespace declarations from which they are derived (the prefix becomes the name of the namespace node, and the URI becomes the string value of the namespace node).

  • A namespace node is created corresponding to any namespace used in the name of the element or in the names of its attributes. However, a namespace node need not be created if there is already a namespace node for a given namespace URI on a given element. The string value of the created namespace node is the namespace URI of the element or attribute name. The name of the namespace node (which represents the namespace prefix) is implementation-dependent; it must not conflict with the name of any other namespace node for the same element.

    Note:

    Implementations may in many cases be able to choose a namespace prefix that is familiar to the user, such as a prefix that is associated with the corresponding namespace URI in either the source document or the query. In some cases, for example to avoid duplicate declarations of the same prefix, an arbitrary choice must be made.

    Where a namespace node is created to declare the namespace URI used in an element name, the namespace prefix can be null (that is, the default namespace can be used) provided this does not clash with an existing declaration of the default namespace on the same element. A namespace node created to declare the namespace URI of an attribute name cannot use a null prefix, because attributes never use the default namespace URI.

3.8 FLWOR Expressions

XQuery provides a feature called a FLWOR expression that supports iteration and binding of variables to intermediate results. This kind of expression is often useful for computing joins between two or more documents and for restructuring data. The name FLWOR, pronounced "flower", is suggested by the keywords for, let, where, order by, and return.

[42]    FLWORExpr    ::=    (ForClause | LetClause)+ WhereClause? OrderByClause? "return" ExprSingle
[43]    ForClause    ::=    "for" "$" VarName TypeDeclaration? PositionalVar? "in" ExprSingle ("," "$" VarName TypeDeclaration? PositionalVar? "in" ExprSingle)*
[45]    LetClause    ::=    "let" "$" VarName TypeDeclaration? ":=" ExprSingle ("," "$" VarName TypeDeclaration? ":=" ExprSingle)*
[122]    TypeDeclaration    ::=    "as" SequenceType
[44]    PositionalVar    ::=    "at" "$" VarName
[46]    WhereClause    ::=    "where" Expr
[47]    OrderByClause    ::=    ("order" "by" | "stable" "order" "by") OrderSpecList
[48]    OrderSpecList    ::=    OrderSpec ("," OrderSpec)*
[49]    OrderSpec    ::=    ExprSingle OrderModifier
[50]    OrderModifier    ::=    ("ascending" | "descending")? (("empty" "greatest") | ("empty" "least"))? ("collation" StringLiteral)?

The for and let clauses in a FLWOR expression generate a sequence of tuples of bound variables, called the tuple stream. The where clause serves to filter the tuple stream, retaining some tuples and discarding others. The order by clause imposes an ordering on the tuple stream. The return clause constructs the result of the FLWOR expression. The return clause is evaluated once for every tuple in the tuple stream, after filtering by the where clause, using the variable bindings in the respective tuples. The result of the FLWOR expression is an ordered sequence containing the concatenated results of these evaluations.

The following example of a FLWOR expression includes all of the possible clauses. The for clause iterates over all the departments in an input document, binding the variable $d to each department number in turn. For each binding of $d, the let clause binds variable $e to all the employees in the given department, selected from another input document. The result of the for and let clauses is a tuple stream in which each tuple contains a pair of bindings for $d and $e ($d is bound to a department number and $e is bound to a set of employees in that department). The where clause filters the tuple stream by keeping only those binding-pairs that represent departments having at least ten employees. The order by clause orders the surviving tuples in descending order by the average salary of the employees in the department. The return clause constructs a new big-dept element for each surviving tuple, containing the department number, headcount, and average salary.

for $d in doc("depts.xml")//deptno
let $e := doc("emps.xml")//emp[deptno = $d]
where count($e) >= 10
order by avg($e/salary) descending
return
   <big-dept>
      {
      $d,
      <headcount>{count($e)}</headcount>,
      <avgsal>{avg($e/salary)}</avgsal>
      }
   </big-dept>

The clauses in a FLWOR expression are described in more detail below.

3.8.1 For and Let Clauses

The purpose of the for and let clauses in a FLWOR expression is to produce a tuple stream in which each tuple consists of one or more bound variables.

The simplest example of a for clause contains one variable and an associated expression. It evaluates the expression and iterates over the items in the resulting sequence, binding the variable to each item in turn.

A for clause may also contain multiple variables, each with an associated expression. In this case, the for clause iterates each variable over the items that result from evaluating its expression. The resulting tuple stream contains one tuple for each combination of values in the Cartesian product of the sequences resulting from evaluating the given expressions. The order of the tuples in the tuple stream is determined by the order of the given expressions, as illustrated in the examples below.

A let clause may also contain one or more variables, each with an associated expression. Unlike a for clause, however, a let clause binds each variable to the result of its associated expression, without iteration. The variable bindings generated by let clauses are added to the binding tuples generated by the for clauses. If there are no for clauses, the let clauses generate one tuple containing all the variable bindings.

Although for and let clauses both bind variables, the manner in which variables are bound is quite different, as illustrated by the following examples. The first example uses a let clause:

let $s := (<one/>, <two/>, <three/>)
return <out>{$s}</out>

The variable $s is bound to the result of the expression (<one/>, <two/>, <three/>). Since there are no for clauses, the let clause generates one tuple that contains the binding of $s. The return clause is invoked for this tuple, creating the following output:

<out>
   <one/>
   <two/>
   <three/>
</out>

The next example is a similar query that contains a for clause instead of a let clause:

for $s in (<one/>, <two/>, <three/>)
return <out>{$s}</out>

In this example, the variable $s iterates over the given expression; first it is bound to <one/>, then to <two/>, and finally to <three/>. One tuple is generated for each of these bindings, and the return clause is invoked for each tuple, creating the following output:

<out>
   <one/>
</out>
<out>
   <two/>
</out>
<out>
   <three/>
</out>

The following example illustrates how binding tuples are generated by a for clause that contains multiple variables. Note that the order of the tuple stream is determined primarily by the order of the sequence bound to the leftmost variable, and secondarily by sequences bound to other variables, working from left to right.

for $i in (1, 2), $j in (3, 4)

The tuple stream generated by the above for clause is as follows (the order is significant):

($i = 1, $j = 3)
($i = 1, $j = 4)
($i = 2, $j = 3)
($i = 2, $j = 4)

The scope of a variable bound in a for or let clause comprises all subexpressions of the containing FLWOR expression that appear after the variable binding. The scope does not include the expression to which the variable is bound. The following example illustrates how for and let clauses may reference variables that were bound in earlier clauses in the same FLWOR expression:

for $x in $w
let $y := f($x)
for $z in g($x, $y)
return h($x, $y, $z)

Each variable bound in a for or let clause may have an optional type declaration, which is a type declared using the syntax in 2.4.1 SequenceType. If the type of a value bound to the variable does not match the declared type according to the rules for SequenceType Matching, a type error is raised.[err:XQ0004][err:XP0006] For example, the following expression raises a type error because the variable $salary has a type declaration that is not satisfied by the value that is bound to the variable:

let $salary as xs:decimal :=  "cat"
return $salary * 2

Each variable bound in a for clause may have an associated positional variable that is bound at the same time. The name of the positional variable is preceded by the keyword at. The positional variable always has an implied type of xs:integer. As a variable iterates over the items in a sequence, its positional variable iterates over the ordinal numbers of these items, starting with 1. Positional variables are illustrated by the following for clause:

for $car at $i in ("Ford", "Chevy"),
$pet at $j in ("Cat", "Dog")

The tuple stream generated by the above for clause is as follows (the order is significant):

($i = 1, $car = "Ford", $j = 1, $pet = "Cat")
($i = 1, $car = "Ford", $j = 2, $pet = "Dog")
($i = 2, $car = "Chevy", $j = 1, $pet = "Cat")
($i = 2, $car = "Chevy", $j = 2, $pet = "Dog")

3.8.2 Where Clause

The optional where clause serves as a filter for the tuples of variable bindings generated by the for and let clauses. The expression in the where clause, called the where-expression, is evaluated once for each of these tuples. If the effective boolean value of the where-expression is true, the tuple is retained and its variable bindings are used in an execution of the return clause. If the effective boolean value of the where-expression is false, the tuple is discarded. The effective boolean value of an expression is defined in 2.4.2.2 Effective Boolean Value.

The following expression illustrates how a where clause might be applied to a positional variable in order to perform sampling on an input sequence. This expression approximates the average value in a sequence by sampling one value out of each one hundred input values.

avg(for $x at $i in $inputvalues
    where $i mod 100 = 0   
    return $x)

3.8.3 Order By and Return Clauses

The return clause of a FLWOR expression is evaluated once for each tuple in the tuple stream, and the results of these evaluations are concatenated to form the result of the FLWOR expression. If no order by clause is present, the order of the tuple stream is determined by the orderings of the sequences returned by the expressions in the for clauses. If an order by clause is present, it determines the order of the tuple stream. The order of the tuple stream, in turn, determines the order in which the return clause is evaluated using the variable bindings in the respective tuples.

An order by clause contains one or more ordering specifications, called orderspecs, as shown in the grammar above. For each tuple in the tuple stream, the orderspecs are evaluated, using the variable bindings in that tuple. The relative order of two tuples is determined by comparing the values of their orderspecs, working from left to right until a pair of unequal values is encountered. If the values to be compared are strings, the orderspec may indicate the collation to be used (if no collation is specified, the default collation is used.)

The process of evaluating and comparing the orderspecs is based on the following rules:

  • Atomization is applied to the result of the expression in each orderspec. If the result of atomization is neither a single atomic value nor an empty sequence, a type error is raised.[err:XQ0004][err:XP0006]

  • If the value of an orderspec has the dynamic type xdt:untypedAtomic (such as character data in a schemaless document), it is cast to the type xs:string.

  • Each orderspec must return values of the same type for all tuples in the tuple stream, and this type must be a (possibly optional) atomic type for which the gt operator is defined--otherwise, a type error is raised.[err:XQ0004][err:XP0006]

When two orderspec values are compared to determine their relative position in the ordering sequence, the greater-than relationship is defined as follows:

  • When the orderspec specifies empty least, a value W is considered to be greater than a value V if one of the following is true:

    • V is an empty sequence and W is not an empty sequence.

    • V is NaN, and W is neither NaN nor an empty sequence.

    • No collation is specified, and W gt V is true.

    • A specific collation C is specified, and fn:compare(V, W, C) is less than zero.

  • When the orderspec specifies empty greatest, a value W is considered to be greater than a value V if one of the following is true:

    • W is an empty sequence and V is not an empty sequence.

    • W is NaN, and V is neither NaN nor an empty sequence.

    • No collation is specified, and W gt V is true.

    • A specific collation C is specified, and fn:compare(V, W, C) is less than zero.

  • When the orderspec specifies neither empty least nor empty greatest, it is implementation defined whether the rules for empty least or empty greatest are used.

If T1 and T2 are two tuples in the tuple stream, and V1 and V2 are the first pair of values encountered when evaluating their orderspecs from left to right for which one value is greater than the other (as defined above), then:

  1. If V1 is greater than V2: If the orderspec specifies descending, then T1 precedes T2 in the tuple stream; otherwise, T2 precedes T1 in the tuple stream.

  2. If V2 is greater than V1: If the orderspec specifies descending, then T2 precedes T1 in the tuple stream; otherwise, T1 precedes T2 in the tuple stream.

If neither V1 nor V2 is greater than the other for any pair of orderspecs for tuples T1 and T2, then:

  1. If stable is specified, the original order of T1 and T2 is preserved in the tuple stream.

  2. If stable is not specified, the order of T1 and T2 in the tuple stream is implementation defined.

An order by clause makes it easy to sort the result of a FLWOR expression, even if the sort key is not included in the result of the expression. For example, the following expression returns employee names in descending order by salary, without returning the actual salaries:

for $e in $employees order by $e/salary return $e/name

The order by clause is the only facility provided by XQuery for specifying an order other than document order. Therefore, every query in which an order other than document order is required must contain a FLWOR expression, even though iteration would not otherwise be necessary. For example, a list of books with price less than 100 might be obtained by a simple path expression such as $books//book[price < 100]. But if these books are to be returned in alphabetic order by title, the query must be expressed as follows:

for $b in $books//book[price < 100]
order by $b/title
return $b

The following example illustrates an order by clause that uses several options. It causes a collection of books to be sorted in primary order by title, and in secondary descending order by price. A specific collation is specified for the title ordering, and in the ordering by price, books with no price are specified to occur last (as though they have the least possible price). Whenever two books with the same title and price occur, the keyword stable indicates that their input order is preserved.

for $b in $books//book
stable order by $b/title collation "eng-us",
   $b/price descending empty least
return $b

3.8.4 Example

The following example illustrates how FLWOR expressions can be nested, and how ordering can be specified at multiple levels of an element hierarchy. The example query inverts a document hierarchy to transform a bibliography into an author list. The input bibliography is a list of books in which each book contains a list of authors. The example is based on the following input:

<bib>
  <book>
    <title>TCP/IP Illustrated</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Advanced Unix Programming</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Data on the Web</title>
    <author>Abiteboul</author>
    <author>Buneman</author>
    <author>Suciu</author>
  </book>
</bib>

The following query transforms the input document into a list in which each author's name appears only once, followed by a list of titles of books written by that author. The distinct-values function is used to eliminate duplicates (by value) from a list of author nodes. The author list, and the lists of books published by each author, are returned in alphabetic order using the default collation.

<authlist>
 {
   for $a in distinct-values($books)//author
   order by $a
   return
     <author>
        <name>
          { $a/text() }
        </name>
        <books>
          {
            for $b in $books//book[author = $a]
            order by $b/title
            return $b/title 
          }
        </books>
     </author>
 }
</authlist>

The result of the above expression is as follows:

<authlist>
   <author>
      <name>Abiteboul</name>
      <books>
         <title>Data on the Web</title>
      </books>
   </author>
   <author>
      <name>Buneman</name>
      <books>
         <title>Data on the Web</title>
      </books>
   </author>
   <author>
      <name>Stevens</name>
      <books>
         <title>TCP/IP Illustrated</title>
         <title>Advanced Unix Programming</title>
      </books>
   </author>
   <author>
      <name>Suciu</name>
      <books>
         <title>Data on the Web</title>
      </books>
   </author>
</authlist>

3.9 Unordered Expressions

In general, XQuery expressions return sequences that have a well-defined order. For example, the result of an axis step in a path expression is always returned in document order. Similarly, the result of a FLWOR expression is ordered by its order by clause and/or the expressions in its for clauses. However, in some expressions, the order of the result may not be significant to the user. In such an expression, one ordering may be much more efficient to materialize than another, and a significant performance advantage may be realized by allowing the system to materialize the results of the expression in the order it finds most efficient. XQuery provides a function named unordered for this purpose.

The unordered function takes any sequence of items as its argument, and returns the same sequence of items in a nondeterministic order. A call to the unordered function may be thought of as giving permission for the argument expression to be materialized in whatever order the system finds most efficient. The unordered function may be applied to the result of a query or to a subexpression inside a query.

The use of the unordered function is illustrated by the following example, which joins together two documents named parts.xml and suppliers.xml. The example returns the part numbers of red parts, paired with the supplier numbers of suppliers who supply these parts. If the unordered function were not used, the resulting list of (part number, supplier number) pairs would be required to have an ordering that is controlled primarily by the document order of parts.xml and secondarily by the document order of suppliers.xml. However, this might not be the most efficient way to process the query if the ordering of the result is not important. An XQuery implementation might be able to process the query more efficiently by using an index to find the red parts, or by using suppliers.xml rather than parts.xml to control the primary ordering of the result. The unordered keyword gives the query evaluator freedom to make these kinds of optimizations.

unordered(
  for $p in doc("parts.xml")//part[color = "Red"],
      $s in doc("suppliers.xml")//supplier
  where $p/suppno = $s/suppno  
  return
    <ps>
       { $p/partno, $s/suppno }
    </ps>
)

3.10 Conditional Expressions

XQuery supports a conditional expression based on the keywords if, then, and else.

Conditional Expression
[54]    IfExpr    ::=    "if" "(" Expr ")" "then" ExprSingle "else" ExprSingle

The expression following the if keyword is called the test expression, and the expressions following the then and else keywords are called the then-expression and else-expression, respectively.

The first step in processing a conditional expression is to find the effective boolean value of the test expression, as defined in 2.4.2.2 Effective Boolean Value.

The value of a conditional expression is defined as follows: If the effective boolean value of the test expression is true, the value of the then-expression is returned. If the effective boolean value of the test expression is false, the value of the else-expression is returned.

Conditional expressions have a special rule for propagating dynamic errors. If the effective value of the test expression is true, the conditional expression ignores (does not raise) any dynamic errors encountered in the else-expression. In this case, since the else-expression can have no observable effect, it need not be evaluated. Similarly, if the effective value of the test expression is false, the conditional expression ignores any dynamic errors encountered in the then-expression, and the then-expression need not be evaluated.

Here are some examples of conditional expressions:

  • In this example, the test expression is a comparison expression:

    if ($widget1/unit-cost < $widget2/unit-cost) 
      then $widget1
      else $widget2
    
  • In this example, the test expression tests for the existence of an attribute named discounted, independently of its value:

    if ($part/@discounted) 
      then $part/wholesale 
      else $part/retail
    

3.11 Quantified Expressions

Quantified expressions support existential and universal quantification. The value of a quantified expression is always true or false.

[51]    QuantifiedExpr    ::=    (("some" "$") | ("every" "$")) VarName TypeDeclaration? "in" ExprSingle ("," "$" VarName TypeDeclaration? "in" ExprSingle)* "satisfies" ExprSingle

A quantified expression begins with a quantifier, which is the keyword some or every, followed by one or more in-clauses that are used to bind variables, followed by the keyword satisfies and a test expression. Each in-clause associates a variable with an expression that returns a sequence of values. The in-clauses generate tuples of variable bindings, using values drawn from the Cartesian product of the sequences returned by the binding expressions. Conceptually, the test expression is evaluated for each tuple of variable bindings. Results depend on the effective boolean values of the test expressions, as defined in 2.4.2.2 Effective Boolean Value. The value of the quantified expression is defined by the following rules:

  1. If the quantifier is some, the quantified expression is true if at least one evaluation of the test expression has the effective boolean value true; otherwise the quantified expression is false. This rule implies that, if the in-clauses generate zero binding tuples, the value of the quantified expression is false.

  2. If the quantifier is every, the quantified expression is true if every evaluation of the test expression has the effective boolean value true; otherwise the quantified expression is false. This rule implies that, if the in-clauses generate zero binding tuples, the value of the quantified expression is true.

The scope of a variable bound in a quantified expression comprises all subexpressions of the quantified expression that appear after the variable binding. The scope does not include the expression to which the variable is bound.

Each variable bound in an in-clause of a quantified expression may have an optional type declaration, which is a datatype declared using the syntax in 2.4.1 SequenceType. If the type of a value bound to the variable does not match the declared type according to the rules for SequenceType Matching, a type error is raised.[err:XQ0004][err:XP0006]

The order in which test expressions are evaluated for the various binding tuples is implementation defined. If the quantifier is some, an implementation may return true as soon as it finds one binding tuple for which the test expression has an effective Boolean value of true, and it may raise a dynamic error as soon as it finds one binding tuple for which the test expression raises an error. Similarly, if the quantifier is every, an implementation may return false as soon as it finds one binding tuple for which the test expression has an effective Boolean value of false, and it may raise a dynamic error as soon as it finds one binding tuple for which the test expression raises an error. As a result of these rules, the value of a quantified expression is not deterministic in the presence of errors, as illustrated in the examples below.

Here are some examples of quantified expressions:

  • This expression is true if every part element has a discounted attribute (regardless of the values of these attributes):

    every $part in //part satisfies $part/@discounted
    
  • This expression is true if at least one employee element satisfies the given comparison expression:

    some $emp in //employee satisfies ($emp/bonus > 0.25 * $emp/salary)
    
  • In the following examples, each quantified expression evaluates its test expression over nine tuples of variable bindings, formed from the Cartesian product of the sequences (1, 2, 3) and (2, 3, 4). The expression beginning with some evaluates to true, and the expression beginning with every evaluates to false.

    some $x in (1, 2, 3), $y in (2, 3, 4) 
         satisfies $x + $y = 4
    
    every $x in (1, 2, 3), $y in (2, 3, 4) 
         satisfies $x + $y = 4
    
  • This quantified expression may either return true or raise a type error, since its test expression returns true for one variable binding and raises a type error for another:

    some $x in (1, 2, "cat") satisfies $x * 2 = 4
    
  • This quantified expression may either return false or raise a type error, since its test expression returns false for one variable binding and raises a type error for another:

    every $x in (1, 2, "cat") satisfies $x * 2 = 4
    
  • This quantified expression contains a type declaration that is not satisfied by every item in the test expression. If the Static Typing Feature is implemented, this expression raises a type error during the analysis phase. Otherwise, the expression may either return true or raise a type error during the evaluation phase.

    some $x as xs:integer in (1, 2, "cat") satisfies $x * 2 = 4
    

3.12 Expressions on SequenceTypes

In addition to their use in function parameters and results, SequenceTypes are used in instance of, typeswitch, cast, castable, and treat expressions.

3.12.1 Instance Of

[57]    InstanceofExpr    ::=    TreatExpr ( "instance" "of" SequenceType )?

The boolean operator instance of returns true if the value of its first operand matches the type named in its second operand, according to the rules for SequenceType Matching; otherwise it returns false. For example:

  • 5 instance of xs:integer

    This example returns true because the given value is an instance of the given type.

  • 5 instance of xs:decimal

    This example returns true because the given value is an integer literal, and xs:integer is derived by restriction from xs:decimal.

  • <a>{5}</a> instance of xs:integer

    This example returns false because the given value is not an integer; instead, it is an element containing an integer.

  • <a>{5}</a> instance of element(*, xs:integer)

    This example returns true if the validation process on the constructed element is successful and the schema definition for element a calls for content of type xs:integer.

  • . instance of element()

    This example returns true if the context item is an element node.

3.12.2 Typeswitch

[52]    TypeswitchExpr    ::=    "typeswitch" "(" Expr ")" CaseClause+ "default" ("$" VarName)? "return" ExprSingle
[53]    CaseClause    ::=    "case" ("$" VarName "as")? SequenceType "return" Expr

The typeswitch expression chooses one of several expressions to evaluate based on the dynamic type of an input value.

In a typeswitch expression, the typeswitch keyword is followed by an expression enclosed in parentheses, called the operand expression. This is the expression whose type is being tested. The remainder of the typeswitch expression consists of one or more case clauses and a default clause.

Each case clause specifies a SequenceType followed by a return expression. The effective case is the first case clause such that the value of the operand expression matches the SequenceType in the case clause, using the rules of SequenceType Matching. The value of the typeswitch expression is the value of the return expression in the effective case. If the value of the operand expression is not a value of any type named in a case clause, the value of the typeswitch expression is the value of the return expression in the default clause.

A case or default clause may optionally specify a variable name. Within the return expression of the case or default clause, this variable name is bound to the value of the operand expression, and its static type is considered to be the SequenceType named in the case or default clause. If the return expression does not depend on the value of the operand expression, the variable may be omitted from the case or default clause.

The scope of a variable binding in a case or default clause comprises that clause. It is not an error for more than one case or default clause in the same typeswitch expression to bind variables with the same name.

The following example shows how a typeswitch expression might be used to process an expression in a way that depends on its dynamic type.

typeswitch($customer/billing-address)
   case $a as element(*, USAddress) return $a/state
   case $a as element(*, CanadaAddress) return $a/province
   case $a as element(*, JapanAddress) return $a/prefecture
   default return "unknown"

3.12.3 Cast

[60]    CastExpr    ::=    ComparisonExpr ( "cast" "as" SingleType )?
[123]    SingleType    ::=    AtomicType "?"?

Occasionally it is necessary to convert a value to a specific datatype. For this purpose, XQuery provides a cast expression that creates a new value of a specific type based on an existing value. A cast expression takes two operands: an input expression and a target type. The type of the input expression is called the input type. The target type must be a named atomic type, represented by a QName, optionally followed by the occurrence indicator ? if an empty sequence is permitted. If the target type has no namespace prefix, it is considered to be in the default element/type namespace. The semantics of the cast expression are as follows:

  1. Atomization is performed on the input expression.

  2. If the result of atomization is a sequence of more than one atomic value, a type error is raised.[err:XQ0004][err:XP0006]

  3. If the result of atomization is an empty sequence:

    1. If ? is specified after the target type, the result of the cast expression is an empty sequence.

    2. If ? is not specified after the target type, a type error is raised.[err:XQ0004][err:XP0006]

  4. If the result of atomization is a single atomic value, the result of the cast expression depends on the input type and the target type. In general, the cast expression attempts to create a new value of the target type based on the input value. Only certain combinations of input type and target type are supported. The rules are listed below. For the purpose of these rules, we use the terms subtype and supertype in the following sense: if type B is derived from type A by restriction, then B is a subtype of A, and A is a supertype of B.

    1. cast is supported for the combinations of input type and target type listed in [XQuery 1.0 and XPath 2.0 Functions and Operators]. For each of these combinations, both the input type and the target type are built-in schema types. For example, a value of type xs:string can be cast into the type xs:decimal. For each of these built-in combinations, the semantics of casting are specified in [XQuery 1.0 and XPath 2.0 Functions and Operators].

    2. cast is supported if the input type is a derived atomic type and the target type is a supertype of the input type. In this case, the input value is mapped into the value space of the target type, unchanged except for its type. For example, if shoesize is derived by restriction from xs:integer, a value of type shoesize can be cast into the type xs:integer.

    3. cast is supported if the target type is a derived atomic type and the input type is xs:string or xdt:untypedAtomic. The input value is first converted to a value in the lexical space of the target type by applying the whitespace normalization rules for the target type; a dynamic error [err:XP0029] is raised if the resulting lexical value does not satisfy the pattern facet of the target type. The lexical value is then converted to the value space of the target type using the schema-defined rules for the target type; a dynamic error[err:XP0029] is raised if the resulting value does not satisfy all the facets of the target type.

    4. cast is supported if the target type is a derived atomic type and the input type is a supertype of the target type. The input value must satisfy all the facets of the target type (in the case of the pattern facet, this is checked by generating a string representation of the input value, using the rules for casting to xs:string). The resulting value is the same as the input value, but with a different dynamic type.

    5. If a primitive type P1 can be cast into a primitive type P2, then any subtype of P1 can be cast into any subtype of P2, provided that the facets of the target type are satisfied. First the input value is cast to P1 using rule (b) above. Next, the value of type P1 is cast to the type P2, using rule (a) above. Finally, the value of type P2 is cast to the target type, using rule (d) above.

    6. For any combination of input type and target type that is not in the above list, a cast expression raises a type error.[err:XQ0004][err:XP0006]

If casting from the input type to the target type is supported but nevertheless it is not possible to cast the input value into the value space of the target type, a dynamic error is raised.[err:XP0021] This includes the case when any facet of the target type is not satisfied. For example, the expression "2003-02-31" cast as xs:date would raise a dynamic error.

3.12.4 Castable

[59]    CastableExpr    ::=    CastExpr ( "castable" "as" SingleType )?

XQuery provides a form of Boolean expression that tests whether a given value is castable into a given target type. The expression V castable as T returns true if the value V can be successfully cast into the target type T by using a cast expression; otherwise it returns false. The castable predicate can be used to avoid errors at evaluation time. It can also be used to select an appropriate type for processing of a given value, as illustrated in the following example:

if ($x castable as hatsize)
then $x cast as hatsize
else if ($x castable as IQ)
then $x cast as IQ
else $x cast as xs:string

3.12.5 Constructor Functions

Constructor functions provide an alternative syntax for casting.

For every built-in atomic type T that is defined in [XML Schema], as well as the predefined types xdt:dayTimeDuration, xdt:yearMonthDuration, and xdt:untypedAtomic, a built-in constructor function is provided. The signature of the built-in constructor function for type T is as follows:

T($x as item) as T

The constructor function for type T accepts any single item (either a node or an atomic value) as input, and returns a value of type T (or raises a dynamic error). Its semantics are exactly the same as a cast expression with target type T. The built-in constructor functions are described in more detail in [XQuery 1.0 and XPath 2.0 Functions and Operators]. The following are examples of built-in constructor functions:

  • This example is equivalent to "2000-01-01" cast as xs:date.

    xs:date("2000-01-01")
    
  • This example is equivalent to ($floatvalue * 0.2E-5) cast as xs:decimal.

    xs:decimal($floatvalue * 0.2E-5)
    
  • This example returns a dayTimeDuration value equal to 21 days. It is equivalent to "P21D" cast as xdt:dayTimeDuration.

    xdt:dayTimeDuration("P21D")
    

For each user-defined top-level atomic type T in the in-scope type definitions that is in a namespace, a constructor function is effectively defined. Like the built-in constructor functions, the constructor functions for user-defined types have the same name (including namespace) as the type, accept any item as input, and have semantics identical to a cast expression with the user-defined type as target type. For example, if usa:zipcode is a user-defined top-level atomic type in the in-scope type definitions, then the expression usa:zipcode("12345") is equivalent to the expression "12345" cast as usa:zipcode.

User-defined atomic types that are not in a namespace do not have implicit constructor functions. To construct an instance of such a type, it is necessary to use a cast expression. For example, if the user-defined type apple is derived from xs:integer but is not in a namespace, an instance of this type can be constructed as follows:

17 cast as apple

3.12.6 Treat

[58]    TreatExpr    ::=    CastableExpr ( "treat" "as" SequenceType )?

XQuery provides an expression called treat that can be used to modify the static type of its operand.

Like cast, the treat expression takes two operands: an expression and a SequenceType. Unlike cast, however, treat does not change the dynamic type or value of its operand. Instead, the purpose of treat is to ensure that an expression has an expected type at evaluation time.

The semantics of expr1 treat as type1 are as follows:

  • During static analysis:

    The static type of the treat expression is type1. This enables the expression to be used as an argument of a function that requires a parameter of type1.

  • During expression evaluation:

    If expr1 matches type1, using the SequenceType Matching rules in 2.4.1 SequenceType, the treat expression returns the value of expr1; otherwise, it raises a dynamic error.[err:XP0006] If the value of expr1 is returned, its identity is preserved. The treat expression ensures that the value of its expression operand conforms to the expected type at run-time.

  • Example:

    $myaddress treat as element(*, USAddress)
    

    The static type of $myaddress may be element(*, Address), a less specific type than element(*, USAddress). However, at run-time, the value of $myaddress must match the type element(*, USAddress) using SequenceType Matching rules; otherwise a dynamic error is raised.[err:XP0050]

3.13 Validate Expressions

[77]    ValidateExpr    ::=    "validate" SchemaMode? SchemaContext? "{" Expr "}" /* gn: validate */
[12]    SchemaMode    ::=    "lax" | "strict" | "skip"
[78]    SchemaContext    ::=    ("context" SchemaContextLoc) | "global"
[136]    SchemaContextLoc    ::=    (SchemaContextPath? QName) | SchemaGlobalTypeName
[135]    SchemaContextPath    ::=    SchemaGlobalContext "/" (SchemaContextStep "/")*
[14]    SchemaGlobalContext    ::=    QName | SchemaGlobalTypeName
[13]    SchemaGlobalTypeName    ::=    "type" "(" QName ")"
[15]    SchemaContextStep    ::=    QName

A validate expression can be used to validate a document node or an element node with respect to the in-scope schema definitions, using the schema validation process described in [XML Schema]. If the argument of a validate expression does not evaluate to exactly one document or element node, a type error is raised.[err:XQ0030]

In the result of the validate expression, the input node and all its descendant nodes are replaced by new nodes that have their own identity and contain type annotations and default values generated by the validation process. The hierarchical relationships among the input nodes are preserved among the nodes created by the validation process.

The result of a validate expression is equivalent to the following steps:

  1. The input node and its descendants are converted from the data model to an XML Information Set ([XML Infoset]), using the mapping described in [XQuery 1.0 and XPath 2.0 Data Model]. If the input node is a document node, the resulting Information Set must represent a well-formed XML document (for example, the document node must have exactly one child that is an element node); otherwise a type error is raised.[err:XQ0030]

  2. The Information Set produced in the previous step is validated according to the rules in [XML Schema], using the in-scope schema definitions. If the topmost node is a document node, the validation process includes checking of uniqueness and reference constraints. If the topmost node is an element node, checks of uniqueness and reference constraints are omitted. The result of this step is a Post-Schema Validation Infoset (PSVI). If the validation process is not successful, a type error is raised.[err:XQ0027]

  3. The PSVI produced in the previous step is converted back into the data model, using the mapping described in [XQuery 1.0 and XPath 2.0 Data Model].

A validate expression may specify a validation mode, which may have one of the following three values:

  • strict requires that each element to be validated must be present in the in-scope element declarations, and that the content of each element must conform to its definition.

  • skip indicates that no validation is to be attempted. In this mode, each element node is given the type annotation xs:anyType, and each attribute node is given the type annotation xdt:untypedAtomic.

  • lax behaves like strict for elements that are present in the in-scope element declarations, and like skip for elements that are not present.

If no validation mode is specified for a validate expression, the expression uses the validation mode in its static context. If a validation mode is specified, that validation mode is made effective in the static context for nested expressions.

A validate expression may also contain a validation context that affects the interpretation of element names. If the validation context is global, all top-level element names in the material to be validated are checked against top-level in-scope schema definitions. Alternatively, the validation context may specify that top-level element names in the validated material are to be interpreted as local names within a given schema context. In this case, the validation context begins with the name of a top-level element or type. The steps inside the validation context trace a path relative to this top-level element or type, as illustrated by the following examples, which are based on schemas defined in [XML Schema], Part 0:

  • Suppose that $x is bound to a shipTo element. Then validate strict context po:purchaseOrder {$x} validates the value of $x in strict mode, in the context of the top-level element declaration po:purchaseOrder.

  • Suppose that $y is bound to a productName element. Then validate context po:purchaseOrder/items/item {$y} validates the value of $y in the context of an item element, inside an items element, inside the top-level element declaration po:purchaseOrder.

  • Suppose that $z is bound to a zip element. Then validate context type(po:USAddress) {$z} validates the value of $z in the context of the top-level type declaration po:USAddress.

If no validation context is specified for a validate expression, the expression uses the validation context in its static context. If a validation context is specified, that validation context is made effective in the static context for nested expressions.

Since each element constructor automatically performs validation on the constructed element, it is rarely necessary to use an explicit validate expression. Typically, an explicit validate expression is used to enclose an element constructor if the user wishes to specify a validation mode or validation context that is different from that of the static context, thus affecting the behavior of the element constructor and its nested expressions. For example, the following expression constructs an element named zip and specifies that it must be validated in strict mode and in the context of the top-level type named po:Address:

validate strict context type(po:Address)
   { <zip>90952</zip> }

4 Modules and Prologs

[30]    Module    ::=    MainModule | LibraryModule
[31]    MainModule    ::=    Prolog QueryBody
[32]    LibraryModule    ::=    ModuleDecl Prolog
[34]    Prolog    ::=    (Version Separator)? ((NamespaceDecl
| XMLSpaceDecl
| DefaultNamespaceDecl
| DefaultCollationDecl
| BaseURIDecl
| SchemaImport
| ModuleImport
| VarDecl
| ValidationDecl
| FunctionDecl) Separator)*
[35]    Separator    ::=    ";"
[39]    QueryBody    ::=    Expr

[Definition: A module is a fragment of XQuery code that can independently undergo the analysis phase described in 2.2.3 Expression Processing]. [Definition: A module that contains a Prolog followed by a Query Body is called a main module.] A query has exactly one main module. In a main module, the Query Body can be evaluated, and its value is the result of the query. [Definition: A module that contains a module declaration followed by a Prolog is called a library module.] A library module cannot be evaluated directly; instead, it provides function and variable declarations that can be imported into other modules. No module may contain both a module declaration and a Query Body.

[Definition: The Prolog is a series of declarations and imports that create the environment for query processing.] Each declaration or import is followed by a semicolon. The Prolog may contain a version declaration that specifies the version of the XQuery language that is used in the module. The Prolog may also include imports of schemas and modules, and declarations of namespaces, variables, functions, and various processing options. Declarations and imports may be specified in any order, except that the version declaration, if present, must come first; and variable declarations must avoid circular definitions as described in 4.8 Variable Declaration.

[Definition: The Query Body, if present, consists of an expression that defines the result of the query.] Evaluation of expressions is described in 3 Expressions. A module can be evaluated only if it has a Query Body.

4.1 Module Declaration

[33]    ModuleDecl    ::=    "module" "namespace" NCName "=" StringLiteral Separator

A module declaration serves to identify a module as a library module. A module declaration consists of the keyword module followed by a namespace prefix and a URI that serves as the target namespace of the module. The names of all variables and functions declared in a library module must be explicitly qualified by the target namespace prefix.[err:XQ0048]

Any module may import a library module by means of a module import that specifies the target namespace of the library module to be imported. When a module imports one or more library modules, the variables and functions declared in the imported modules are added to the static context and (where applicable) to the dynamic context of the importing module.

The following is an example of a module declaration:

module math = "http://example.org/math-functions";

4.2 Version Declaration

[36]    Version    ::=    "xquery" "version" StringLiteral

A version declaration specifies the applicable XQuery syntax and semantics for a module. The version number "1.0" indicates the requirement that the query must be processed by an XQuery Version 1.0 processor. If the version declaration is not present, the version is presumed to be "1.0". An XQuery implementation must raise a static error [err:XQ0031] when processing a query labeled with a version that the implementation does not support. It is the intent of the XQuery working group to give later versions of this specification numbers other than "1.0", but this intent does not indicate a commitment to produce any future versions of XQuery, nor if any are produced, to use any particular numbering scheme.

The following is an example of a version declaration:

xquery version "1.0";

4.3 Base URI Declaration

[116]    BaseURIDecl    ::=    "declare" "base-uri" StringLiteral

A base URI declaration specifies the base URI property of the static context, which is used when resolving relative URIs within a module. A static error [err:XQ0032] is raised if more than one base URI declaration is found in a query prolog. Note that the fn:doc function resolves a relative URI using the base URI of the calling module.

The following is an example of a base URI declaration:

declare base-uri "http://example.org";

4.4 Namespace Declaration

[117]    NamespaceDecl    ::=    "declare" "namespace" NCName "=" StringLiteral

A namespace declaration declares a namespace prefix and associates it with a namespace URI, adding the (prefix, URI) pair to the set of in-scope namespaces. The string literal used in a namespace declaration must be a valid URI, and may not be a zero-length string.[err:XQ0046] The namespace declaration is in scope throughout the query in which it is declared, unless it is overridden by a namespace declaration attribute in an element constructor.

The following query illustrates a namespace declaration:

declare namespace foo = "http://example.org";
<foo:bar> Lentils </foo:bar> 

In the query result, the newly created node is in the namespace associated with the namespace URI http://example.org.

Multiple declarations of the same namespace prefix in the Prolog result in a static error.[err:XQ0033] However, a declaration of a namespace in the Prolog can override a prefix that has been predeclared in the static context.

It is a static error [err:XP0008] to use a QName with a namespace prefix that has not been declared.

In an element constructor, a namespace declaration attribute can be used to bind a prefix to a namespace, adding a (prefix, URI) pair to the set of in-scope namespaces for the element in which it occurs and for nested expressions. The binding of a prefix by a namespace declaration attribute overrides any binding of the same prefix by a higher-level element or by the Prolog. The value of a namespace declaration attribute must be a valid URI. In the Data Model, a namespace declaration attribute generates a namespace node rather than an attribute node. Namespace nodes are not retrieved by queries that return the attributes of an element. The following query illustrates a namespace declaration attribute that binds the prefix foo within the scope of a constructed element:

<foo:bar xmlns:foo="http://example.org">{ //foo:bing }</foo:bar>

When element or attribute names are compared, they are considered identical if the local part and namespace URI match. Namespace prefixes need not be identical for two names to match, as illustrated by the following example:

declare namespace xx = "http://example.org";

let $i := <foo:bar xmlns:foo = "http://example.org">
              <foo:bing> Lentils </foo:bing>
          </foo:bar>
return $i/xx:bing

Although the namespace prefixes xx and foo differ, both are bound to the namespace URI "http://example.org". Since xx:bing and foo:bing have the same local name and the same namespace URI, they match. The output of the above query is as follows.

<foo:bing> Lentils </foo:bing>

XQuery has several predeclared namespace prefixes that are present in the in-scope namespaces before each query is processed. These prefixes may be used without an explicit declaration. They may be overridden by namespace declarations in the Prolog or by namespace declaration attributes on constructed elements (except for the prefix xml, which may not be redeclared.) The predeclared namespace prefixes are as follows:

  • xml = http://www.w3.org/XML/1998/namespace

  • xs = http://www.w3.org/2001/XMLSchema

  • xsi = http://www.w3.org/2001/XMLSchema-instance

  • fn = http://www.w3.org/2003/05/xpath-functions

  • xdt = http://www.w3.org/2003/05/xpath-datatypes

  • local = http://www.w3.org/2003/08/xquery-local-functions (see 4.12 Function Declaration.)

Additional predeclared namespace prefixes may be added to the in-scope namespaces by an implementation.

The namespace prefix xmlns also has a special significance (it identifies a namespace declaration attribute), and it may not be redeclared.

4.5 Default Namespace Declaration

[118]    DefaultNamespaceDecl    ::=    (("declare" "default" "element") | ("declare" "default" "function")) "namespace" StringLiteral

Default namespace declarations can be used in a Prolog to facilitate the use of unprefixed QNames. The string literal used in a default namespace declaration must be a valid URI, and may be a zero-length string.[err:XQ0046] The following kinds of default namespace declarations are supported:

  • Declaration of a default element/type namespace declares a namespace URI that is associated with unprefixed names of elements and types. If no default element/type namespace is declared, unqualified names of elements and types are in no namespace. The following example illustrates the declaration of a default namespace for elements and types:

    declare default element namespace "http://example.org/names";
    

    If a direct element constructor includes an attribute named xmlns, it is considered to be a namespace declaration attribute that specifies a new default element/type namespace within the scope of the constructed element and its descendants. For example, within the scope of the following constructed element, the default element/type namespace is http://example.org/altnames.

    <abc xmlns="http://example.org/altnames">Content goes here.</abc>
    
  • A Prolog may contain a declaration for a default function namespace. If no default function namespace is declared, the default function namespace is the namespace of XPath/XQuery functions, http://www.w3.org/2003/05/xpath-functions. The following example illustrates the declaration of a default function namespace:

    declare default function namespace 
          "http://example.org/math-functions";
    

    The effect of declaring a default function namespace is that all functions in the default function namespace, including implicitly-declared constructor functions, are aliased with a name that has the original local name, but no namespace URI. The function may then be called using either its original name or its alias--that is, the namespace prefix becomes optional. When a function call uses a function name with no prefix, the local name of the function must match a function (including implicitly-declared constructor functions) in the default function namespace.[err:XP0017]

Unqualified attribute names and variable names are in no namespace.

4.6 Schema Import

[142]    SchemaImport    ::=    "import" "schema" SchemaPrefix? StringLiteral ("at" StringLiteral)?
[143]    SchemaPrefix    ::=    ("namespace" NCName "=") | ("default" "element" "namespace")

A schema import imports the element, attribute, and type definitions from a named schema into the in-scope schema definitions. The string literals in a schema import must be valid URIs. The schema import specifies the target namespace of the schema to be imported, and optionally the location of the schema. A schema import may also bind a namespace prefix to the target namespace of the imported schema, or may declare that target namespace to be the default element/type namespace. The optional location indication can be disregarded by an implementation if it has another way to locate the given schema.

The following example imports the schema for an XHTML document, specifying both its target namespace and its location, and binding the prefix xhtml to this namespace:

import schema namespace xhtml="http://www.w3.org/1999/xhtml" 
   at "http://example.org/xhtml/xhtml.xsd";

The following example imports a schema by specifying only its target namespace, and makes it the default element/type namespace for the query:

import schema default element namespace "http://example.org/abc";

It is a static error [err:XQ0035] to import two schemas that both define the same name in the same symbol space and in the same scope. For instance, a query may not import two schemas that include top-level element declarations for two elements with the same expanded name. However, it is not an error for a module to import the schema with target namespace http://www.w3.org/2001/XMLSchema (predeclared prefix xs), even though the built-in types defined in this schema are implicitly included in the in-scope type definitions.

Note:

XQuery 1.0 supports querying of DTD-validated documents only if the Static Typing Feature is not enabled. Since XQuery 1.0 does not provide a means for importing Document Type Definitions (DTDs), implementations supporting the Static Typing Feature level are not required to recognize or support type information in DTDs.

If static typing of queries that access DTD-validated documents is required, the DTD should be converted to an XML Schema and the resulting schema should be imported into the query. We request public comment on this restriction.

4.7 Module Import

[37]    ModuleImport    ::=    "import" "module" ("namespace" NCName "=")? StringLiteral ("at" StringLiteral)?

A module import imports the function declarations and variable declarations from the Prolog of a library module into the in-scope functions and in-scope variables of the importing module. The module import identifies the module to be imported by its target namespace, and may also specify its location by using an at clause. Implementations may locate modules in any manner that is convenient, and are free to ignore the specified location if they have another way to find a module. By means of an optional namespace clause, a module import may bind a namespace prefix to the target namespace of the imported module. It is a static error if a module import does not identify an accessible module to be imported.[err:XQ0047]

Each module has its own static context. A module import imports only functions and variable declarations; it does not import other objects from the imported module, such as its in-scope schema definitions or in-scope namespaces. Module imports are not transitive--that is, importing a module provides access only to function and variable declarations contained directly in the imported module. For example, if module A imports module B, and module B imports module C, module A does not have access to the functions and variables declared in module C. Two modules may import each other.

It is a type error [err:XQ0036] to import a module if the importing module's in-scope type definitions do not include definitions for the type names that appear in variable declarations, function parameters, or function returns found in the imported module. It is a static error [err:XQ0037] to import a module that contains function declarations or variable declarations whose names are already declared in the static context of the importing module.

To illustrate the above rules, suppose that a certain schema defines a type named triangle. Suppose that a library module imports the schema, binds its target namespace to the prefix geo, and declares a function with the function signature math:area($t as geo:triangle) as xs:double. If a query wishes to use this function, it must import both the library module and the schema on which it is based. Importing the library module alone would not provide access to the type definition on which the area function is declared.

The following example illustrates a module import:

import module 
   namespace math = "http://example.org/math-functions";

4.8 Variable Declaration

[38]    VarDecl    ::=    "declare" S "variable" "$" VarName TypeDeclaration? (("{" Expr "}") | "external")
[20]    VarName    ::=    QName
[122]    TypeDeclaration    ::=    "as" SequenceType

A variable declaration adds the static type of a variable to the in-scope variables, and may also add a value for the variable to the dynamic variables. If the expanded QName of the variable is the same as that of another variable in in-scope variables, a static error is raised.[err:XQ0049]

If a variable declaration includes a type, that type is added to the static context as the type of the variable. If a variable declaration includes an expression but not an explicit type, the static type of the variable is inferred from the static type of the expression. If a variable declaration includes both a type and an expression, the static type of the expression must be compatible with the declared static type; otherwise a type error is raised.[err:XQ0004]

If a variable declaration includes an expression, the value of the expression is bound to the variable in the dynamic context. If the variable declaration includes the keyword external, a value must be provided for the variable by the external environment before the query can be evaluated. If the value provided by the external environment is not compatible with the declared type of the variable, a type error is raised.[err:XP0006]

If a variable declaration contains neither a type nor an expression, the type and value of the variable must both be provided by the external environment at evaluation time. The static type of such a variable is considered to be xs:anyType.

A variable or function may appear in the expression part of a variable declaration only if that variable or function is declared before the variable declaration (that is, it must be declared or imported earlier in the Prolog than the variable declaration in which it is used.)

All variable names declared in a library module must be explicitly qualified by the namespace prefix of the module's target namespace.[err:XQ0048] When a library module is imported, variables declared in the imported module are added to the in-scope variables of the importing module.

Variable names that have no namespace prefix are in no namespace. Variable declarations that have no namespace prefix may appear only in a main module.

The term variable declaration always refers to a declaration of a variable in a Prolog. The binding of a variable to a value in a query expression, such as a FLWOR expression, is known as a variable binding, and does not make the variable visible to an importing module.

Here are some examples of variable declarations:

  • The following declaration specifies both the type and the value of a variable. This declaration causes the type xs:integer to be associated with variable $x in the static context, and the value 7 to be associated with variable $x in the dynamic context.

    declare variable $x as xs:integer {7};
    
  • The following declaration specifies a value but not a type. The static type of the variable is inferred from the static type of its value. In this case, the variable $x has a static type of xs:decimal, inferred from its value which is 7.5.

    declare variable $x {7.5};
    
  • The following declaration specifies a type but not a value. The keyword external indicates that the value of the variable will be provided by the external environment. At evaluation time, if the variable $x in the dynamic context does not have a value of type xs:integer, a type error is raised.

    declare variable $x as xs:integer external;
    
  • The following declaration specifies neither a type nor a value. It simply declares that the query depends on the existence of a variable named $x, whose type and value will be provided by the external environment. During query analysis, the type of $x is considered to be xs:anyType. During query evaluation, the dynamic context must include a type and a value for $x, and its value must be compatible with its type.

    declare variable $x external;
    

4.9 Validation Declaration

[141]    ValidationDecl    ::=    "declare" "validation" SchemaMode
[12]    SchemaMode    ::=    "lax" | "strict" | "skip"

The validation declaration in the Prolog sets the validation mode in the static context to strict, lax, or skip. This establishes a default validation mode for the query. The default validation context for the query is always set to global. The default validation mode and validation context can be overridden by validate expressions within the body of the query. The significance of validation mode and validation context are described in 3.13 Validate Expressions.

The following example illustrates a validation declaration:

declare validation strict;

4.10 Xmlspace Declaration

[114]    XMLSpaceDecl    ::=    "declare" "xmlspace" ("preserve" | "strip")

The xmlspace declaration in a Prolog controls whether boundary whitespace is preserved by element and attribute constructors during execution of the query, as described in 3.7.1.4 Whitespace in Element Content. If xmlspace preserve is specified, boundary whitespace is preserved. If xmlspace strip is specified or if no xmlspace declaration is present, boundary whitespace is stripped (deleted).

The following example illustrates an xmlspace declaration:

declare xmlspace preserve;

4.11 Default Collation Declaration

[115]    DefaultCollationDecl    ::=    "declare" "default" "collation" StringLiteral

A Prolog may declare a default collation, which is the name of the collation to be used by all functions and operators that require a collation if no other collation is specified. For example, the gt operator on strings is defined by a call to the fn:compare function, which takes an optional collation parameter. Since the gt operator does not specify a collation, the fn:compare function implements gt by using the default collation specified in the Prolog. The default collation is identified by a literal string containing a URI.

The following example illustrates a default collation declaration:

declare default collation
         "http://example.org/languages/Icelandic";

If a Prolog specifies no default collation, the system provided default collation is chosen. If the system does not provide a default collation, the Unicode codepoint collation (http://www.w3.org/2003/05/xpath-functions/collation/codepoint) is used. If a Prolog specifies more than one default collation, or value specified does not identify a collation known to the implementation, a static error is raised.[err:XQ0038]

4.12 Function Declaration

In addition to the built-in functions described in [XQuery 1.0 and XPath 2.0 Functions and Operators], XQuery allows users to declare functions of their own. A function declaration specifies the name of the function, the names and datatypes of the parameters, and the datatype of the result. All datatypes are specified using the syntax described in 2.4.1 SequenceType. A function declaration causes the declared function to be added to the in-scope functions of the module in which it appears.

[119]    FunctionDecl    ::=    "declare" "function" QName "(" ParamList? (")" | (")" "as" SequenceType)) (EnclosedExpr | "external") /* gn: parens */
[120]    ParamList    ::=    Param ("," Param)*
[121]    Param    ::=    "$" VarName TypeDeclaration?
[122]    TypeDeclaration    ::=    "as" SequenceType

A function declaration specifies whether a function is user-defined or external. [Definition: For a user-defined function, the function declaration includes an expression called the function body that defines how the result of the function is computed from its parameters.].

[Definition: External functions are functions that are implemented outside the query environment.] For example, an XQuery implementation might provide a set of external functions in addition to the core function library described in [XQuery 1.0 and XPath 2.0 Functions and Operators]. External functions are identified by the keyword external. The purpose of a function declaration for an external function is to declare the datatypes of the function parameters and result, for use in type checking of the query that contains or imports the function declaration.

An XQuery implementation may provide a facility whereby external functions can be implemented using a host programming language, but it is not required to do so. If such a facility is provided, the protocols by which parameters are passed to an external function, and the result of the function is returned to the invoking query, are implementation-defined. An XQuery implementation may augment the type system of [XQuery 1.0 and XPath 2.0 Data Model] with additional types that are designed to facilitate exchange of data with host programming languages, or it may provide mechanisms for the user to define such types. For example, a type might be provided that encapsulates an object returned by an external function, such as an SQL database connection.

The declared function name in a function declaration must be a QName with a non-empty namespace prefix. If the namespace prefix of a declared function name is empty, a static error is raised.[err:XQ0045] If the expanded QName of the function is the same as that of another function in in-scope functions, a static error is raised.[err:XQ0034]

In order to allow main modules to declare functions for local use within the module without defining a new namespace, XQuery predefines the namespace prefix local to the namespace http://www.w3.org/2003/08/xquery-local-functions, and reserves this namespace for use in defining local functions. It is a static error if the declared name in a function declaration uses one of the predefined namespace prefixes other than local.[err:XQ0045]

If a function parameter is declared using a name but no type, its default type is item*. If the result type is omitted from a function declaration, its default result type is item*.

The parameters of a function declaration are considered to be variables whose scope is the function body. It is an static error [err:XQ0039] for a function declaration to have more than one parameter with the same name. The type of a function parameter can be any type that can be expressed as a SequenceType (see 2.4.1 SequenceType).

The following example illustrates the declaration and use of a local function that accepts a sequence of valid employee elements (as defined in the in-scope element declarations), summarizes them by department, and returns a sequence of valid dept elements (again, as defined in the in-scope element declarations).

  • Using a function, prepare a summary of employees that are located in Denver.

    declare function local:summary($emps as element(employee)*) 
       as element(dept)*
    {
       for $d in distinct-values($emps/deptno)
       let $e := $emps[deptno = $d]
       return
          <dept>
             <deptno>{$d}</deptno>
             <headcount> {count($e)} </headcount>
             <payroll> {sum($e/salary)} </payroll>
          </dept>
    };
    
    local:summary(doc("acme_corp.xml")//employee[location = "Denver"])
    

Rules for converting function arguments to their declared parameter types, and for converting the result of a function to its declared result type, are described in 3.1.5 Function Calls

A function declaration may be recursive--that is, it may reference itself. Mutually recursive functions, whose bodies reference each other, are also allowed. The following example declares a recursive function that computes the maximum depth of a node hierarchy, and calls the function to find the maximum depth of a particular document. In its declaration, the user-declared function local:depth calls the built-in functions empty and max, which are in the default function namespace.

  • Find the maximum depth of the document named partlist.xml.

    declare function local:depth($e as node()) as xs:integer
    {
       (: A node with no children has depth 1 :)
       (: Otherwise, add 1 to max depth of children :)
       if (empty($e/*)) then 1
       else max(for $c in $e/* return local:depth($c)) + 1
    };
    
    local:depth(doc("partlist.xml"))
    

In XQuery 1.0, user-declared functions may not be overloaded. A user-declared function is uniquely identified by its expanded QName. However, some of the built-in functions in the XQuery core library are overloaded--for example, the fn:string function can be called with either zero arguments or one argument.

Since a constructor function is effectively declared for every user-defined atomic type in the in-scope type definitions, a static error [err:XQ0034] is raised if the Prolog attempts to declare a function with the same expanded QName as any of these types.

Note:

If a future version of XQuery supports overloading of user-declared functions, an ambiguity may arise between a function that takes a node as parameter and a function with the same name that takes an atomic value as parameter (since a function call automatically extracts the atomic value of a node when necessary). The designers of such a future version of XQuery can avoid this ambiguity by writing suitable rules to govern function overloading. Nevertheless, users who are concerned about this possibility may choose to explicitly extract atomic values from nodes when calling functions that expect atomic values.

A XQuery Grammar

A.1 EBNF

The following grammar uses the same Basic Extended Backus-Naur Form (EBNF) notation as [XML], except that grammar symbols always have initial capital letters. The notation "< ... >" is used to indicate a grouping of terminals that together may help disambiguate the individual symbols. To help readability, this "< ... >" notation is absent in the EBNF in the main body of this document.

Comments on grammar productions are between '/*' and '*/' symbols. A 'gn:' prefix means a 'Grammar Note', and are meant as clarifications for parsing rules, and are explained in A.1.1 Grammar Notes. A 'ws:' prefix explains the white space rules for the production, the details of which are explained in A.2.1 White Space Rules

Named Terminals
[1]    Pragma    ::=    "(::" "pragma" QName PragmaContents* "::)" /* gn: parens */
[2]    MUExtension    ::=    "(::" "extension" QName ExtensionContents* "::)" /* gn: parens */
[3]    ExprComment    ::=    "(:" (ExprCommentContent | ExprComment)* ":)" /* gn: comments */
[4]    ExprCommentContent    ::=    Char /* gn: parens */
[5]    PragmaContents    ::=    Char
[6]    ExtensionContents    ::=    Char
[7]    IntegerLiteral    ::=    Digits
[8]    DecimalLiteral    ::=    ("." Digits) | (Digits "." [0-9]*) /* ws: explicit */
[9]    DoubleLiteral    ::=    (("." Digits) | (Digits ("." [0-9]*)?)) ("e" | "E") ("+" | "-")? Digits /* ws: explicit */
[10]    StringLiteral    ::=    ('"' (PredefinedEntityRef | CharRef | ('"' '"') | [^"&])* '"') | ("'" (PredefinedEntityRef | CharRef | ("'" "'") | [^'&])* "'") /* ws: significant */
[11]    S    ::=    [http://www.w3.org/TR/REC-xml#NT-S]
[12]    SchemaMode    ::=    "lax" | "strict" | "skip"
[13]    SchemaGlobalTypeName    ::=    "type" "(" QName ")"
[14]    SchemaGlobalContext    ::=    QName | SchemaGlobalTypeName
[15]    SchemaContextStep    ::=    QName
[16]    Digits    ::=    [0-9]+
[17]    EscapeQuot    ::=    '"' '"'
[18]    PITarget    ::=    NCName
[19]    NCName    ::=    [http://www.w3.org/TR/REC-xml-names/#NT-NCName]
[20]    VarName    ::=    QName
[21]    QName    ::=    [http://www.w3.org/TR/REC-xml-names/#NT-QName]
[22]    PredefinedEntityRef    ::=    "&" ("lt" | "gt" | "amp" | "quot" | "apos") ";" /* ws: explicit */
[23]    HexDigits    ::=    [0-9] | [a-f] | [A-F]+
[24]    CharRef    ::=    "&#" (Digits | ("x" HexDigits)) ";" /* ws: explicit */
[25]    EscapeApos    ::=    "''"
[26]    Char    ::=    [http://www.w3.org/TR/REC-xml#NT-Char]
[27]    ElementContentChar    ::=    Char - [{}<&]
[28]    QuotAttContentChar    ::=    Char - ["{}<&]
[29]    AposAttContentChar    ::=    Char - ['{}<&]
Non-Terminals
[30]    Module    ::=    MainModule | LibraryModule
[31]    MainModule    ::=    Prolog QueryBody
[32]    LibraryModule    ::=    ModuleDecl Prolog
[33]    ModuleDecl    ::=    <"module" "namespace"> NCName "=" StringLiteral Separator
[34]    Prolog    ::=    (Version Separator)? ((NamespaceDecl
| XMLSpaceDecl
| DefaultNamespaceDecl
| DefaultCollationDecl
| BaseURIDecl
| SchemaImport
| ModuleImport
| VarDecl
| ValidationDecl
| FunctionDecl) Separator)*
[35]    Separator    ::=    ";"
[36]    Version    ::=    <"xquery" "version" StringLiteral>
[37]    ModuleImport    ::=    <"import" "module"> ("namespace" NCName "=")? StringLiteral <"at" StringLiteral>?
[38]    VarDecl    ::=    <"declare" S "variable" "$"> VarName TypeDeclaration? (("{" Expr "}") | "external")
[39]    QueryBody    ::=    Expr
[40]    Expr    ::=    ExprSingle ("," ExprSingle)*
[41]    ExprSingle    ::=    FLWORExpr
| QuantifiedExpr
| TypeswitchExpr
| IfExpr
| OrExpr
[42]    FLWORExpr    ::=    (ForClause | LetClause)+ WhereClause? OrderByClause? "return" ExprSingle
[43]    ForClause    ::=    <"for" "$"> VarName TypeDeclaration? PositionalVar? "in" ExprSingle ("," "$" VarName TypeDeclaration? PositionalVar? "in" ExprSingle)*
[44]    PositionalVar    ::=    "at" "$" VarName
[45]    LetClause    ::=    <"let" "$"> VarName TypeDeclaration? ":=" ExprSingle ("," "$" VarName TypeDeclaration? ":=" ExprSingle)*
[46]    WhereClause    ::=    "where" Expr
[47]    OrderByClause    ::=    (<"order" "by"> | <"stable" "order" "by">) OrderSpecList
[48]    OrderSpecList    ::=    OrderSpec ("," OrderSpec)*
[49]    OrderSpec    ::=    ExprSingle OrderModifier
[50]    OrderModifier    ::=    ("ascending" | "descending")? (<"empty" "greatest"> | <"empty" "least">)? ("collation" StringLiteral)?
[51]    QuantifiedExpr    ::=    (<"some" "$"> | <"every" "$">) VarName TypeDeclaration? "in" ExprSingle ("," "$" VarName TypeDeclaration? "in" ExprSingle)* "satisfies" ExprSingle
[52]    TypeswitchExpr    ::=    <"typeswitch" "("> Expr ")" CaseClause+ "default" ("$" VarName)? "return" ExprSingle
[53]    CaseClause    ::=    "case" ("$" VarName "as")? SequenceType "return" Expr
[54]    IfExpr    ::=    <"if" "("> Expr ")" "then" ExprSingle "else" ExprSingle
[55]    OrExpr    ::=    AndExpr ( "or" AndExpr )*
[56]    AndExpr    ::=    InstanceofExpr ( "and" InstanceofExpr )*
[57]    InstanceofExpr    ::=    TreatExpr ( <"instance" "of"> SequenceType )?
[58]    TreatExpr    ::=    CastableExpr ( <"treat" "as"> SequenceType )?
[59]    CastableExpr    ::=    CastExpr ( <"castable" "as"> SingleType )?
[60]    CastExpr    ::=    ComparisonExpr ( <"cast" "as"> SingleType )?
[61]    ComparisonExpr    ::=    RangeExpr ( (ValueComp
| GeneralComp
| NodeComp
| OrderComp) RangeExpr )?
[62]    RangeExpr    ::=    AdditiveExpr ( "to" AdditiveExpr )?
[63]    AdditiveExpr    ::=    MultiplicativeExpr ( ("+" | "-") MultiplicativeExpr )*
[64]    MultiplicativeExpr    ::=    UnaryExpr ( ("*" | "div" | "idiv" | "mod") UnaryExpr )*
[65]    UnaryExpr    ::=    ("-" | "+")* UnionExpr
[66]    UnionExpr    ::=    IntersectExceptExpr ( ("union" | "|") IntersectExceptExpr )*
[67]    IntersectExceptExpr    ::=    ValueExpr ( ("intersect" | "except") ValueExpr )*
[68]    ValueExpr    ::=    ValidateExpr | PathExpr
[69]    PathExpr    ::=    ("/" RelativePathExpr?)
| ("//" RelativePathExpr)
| RelativePathExpr
/* gn: leading-lone-slash */
[70]    RelativePathExpr    ::=    StepExpr (("/" | "//") StepExpr)*
[71]    StepExpr    ::=    AxisStep | FilterStep
[72]    AxisStep    ::=    (ForwardStep | ReverseStep) Predicates
[73]    FilterStep    ::=    PrimaryExpr Predicates
[74]    ContextItemExpr    ::=    "."
[75]    PrimaryExpr    ::=    Literal | FunctionCall | ContextItemExpr | ("$" VarName) | ParenthesizedExpr | Constructor
[76]    Predicates    ::=    ("[" Expr "]")*
[77]    ValidateExpr    ::=    (<"validate" "{"> | (<"validate" "global"> "{") | (<"validate" "context"> SchemaContextLoc "{") | (<"validate" SchemaMode> SchemaContext? "{")) Expr "}" /* gn: validate */
[78]    SchemaContext    ::=    ("context" SchemaContextLoc) | "global"
[79]    Constructor    ::=    ElementConstructor
| XmlComment
| XmlPI
| CdataSection
| CompDocConstructor
| CompElemConstructor
| CompAttrConstructor
| CompNSConstructor
| CompTextConstructor
| CompXmlPI
| ComputedXmlComment
[80]    GeneralComp    ::=    "=" | "!=" | "<" | "<=" | ">" | ">=" /* gn: lt */
[81]    ValueComp    ::=    "eq" | "ne" | "lt" | "le" | "gt" | "ge"
[82]    NodeComp    ::=    "is" | "isnot"
[83]    OrderComp    ::=    "<<" | ">>"
[84]    ForwardStep    ::=    (ForwardAxis NodeTest) | AbbrevForwardStep
[85]    ReverseStep    ::=    (ReverseAxis NodeTest) | AbbrevReverseStep
[86]    AbbrevForwardStep    ::=    "@"? NodeTest
[87]    AbbrevReverseStep    ::=    ".."
[88]    ForwardAxis    ::=    <"child" "::">
| <"descendant" "::">
| <"attribute" "::">
| <"self" "::">
| <"descendant-or-self" "::">
| <"following-sibling" "::">
| <"following" "::">
[89]    ReverseAxis    ::=    <"parent" "::">
| <"ancestor" "::">
| <"preceding-sibling" "::">
| <"preceding" "::">
| <"ancestor-or-self" "::">
[90]    NodeTest    ::=    KindTest | NameTest
[91]    NameTest    ::=    QName | Wildcard
[92]    Wildcard    ::=    "*"
| <NCName ":" "*">
| <"*" ":" NCName>
/* ws: explicit */
[93]    Literal    ::=    NumericLiteral | StringLiteral
[94]    NumericLiteral    ::=    IntegerLiteral | DecimalLiteral | DoubleLiteral
[95]    ParenthesizedExpr    ::=    "(" Expr? ")"
[96]    FunctionCall    ::=    <QName "("> (ExprSingle ("," ExprSingle)*)? ")"
[97]    ElementConstructor    ::=    "<" QName AttributeList ("/>" | (">" ElementContent* "</" QName S? ">")) /* ws: explicit */
/* gn: lt */
[98]    CompDocConstructor    ::=    <"document" "{"> Expr "}"
[99]    CompElemConstructor    ::=    (<"element" QName "{"> | (<"element" "{"> Expr "}" "{")) Expr? "}"
[100]    CompNSConstructor    ::=    <"namespace" NCName "{"> Expr "}"
[101]    CompAttrConstructor    ::=    (<"attribute" QName "{"> | (<"attribute" "{"> Expr "}" "{")) Expr? "}"
[102]    CompXmlPI    ::=    (<"pi" NCName "{"> | (<"pi" "{"> Expr "}" "{")) Expr? "}"
[103]    ComputedXmlComment    ::=    <"comment" "{"> Expr "}"
[104]    CompTextConstructor    ::=    <"text" "{"> Expr? "}"
[105]    CdataSection    ::=    "<![CDATA[" Char* "]]>" /* ws: significant */
[106]    XmlPI    ::=    "<?" PITarget Char* "?>" /* ws: explicit */
[107]    XmlComment    ::=    "<!--" Char* "-->" /* ws: significant */
[108]    ElementContent    ::=    ElementContentChar
| "{{"
| "}}"
| ElementConstructor
| EnclosedExpr
| CdataSection
| CharRef
| PredefinedEntityRef
| XmlComment
| XmlPI
/* ws: significant */
[109]    AttributeList    ::=    (S (QName S? "=" S? AttributeValue)?)* /* ws: explicit */
[110]    AttributeValue    ::=    ('"' (EscapeQuot | QuotAttrValueContent)* '"')
| ("'" (EscapeApos | AposAttrValueContent)* "'")
/* ws: significant */
[111]    QuotAttrValueContent    ::=    QuotAttContentChar
| CharRef
| "{{"
| "}}"
| EnclosedExpr
| PredefinedEntityRef
/* ws: significant */
[112]    AposAttrValueContent    ::=    AposAttContentChar
| CharRef
| "{{"
| "}}"
| EnclosedExpr
| PredefinedEntityRef
/* ws: significant */
[113]    EnclosedExpr    ::=    "{" Expr "}"
[114]    XMLSpaceDecl    ::=    <"declare" "xmlspace"> ("preserve" | "strip")
[115]    DefaultCollationDecl    ::=    <"declare" "default" "collation"> StringLiteral
[116]    BaseURIDecl    ::=    <"declare" "base-uri"> StringLiteral
[117]    NamespaceDecl    ::=    <"declare" "namespace"> NCName "=" StringLiteral
[118]    DefaultNamespaceDecl    ::=    (<"declare" "default" "element"> | <"declare" "default" "function">) "namespace" StringLiteral
[119]    FunctionDecl    ::=    <"declare" "function"> <QName "("> ParamList? (")" | (<")" "as"> SequenceType)) (EnclosedExpr | "external") /* gn: parens */
[120]    ParamList    ::=    Param ("," Param)*
[121]    Param    ::=    "$" VarName TypeDeclaration?
[122]    TypeDeclaration    ::=    "as" SequenceType
[123]    SingleType    ::=    AtomicType "?"?
[124]    SequenceType    ::=    (ItemType OccurrenceIndicator?)
| <"empty" "(" ")">
[125]    AtomicType    ::=    QName
[126]    ItemType    ::=    AtomicType | KindTest | <"item" "(" ")">
[127]    KindTest    ::=    DocumentTest
| ElementTest
| AttributeTest
| PITest
| CommentTest
| TextTest
| AnyKindTest
[128]    ElementTest    ::=    <"element" "("> ((SchemaContextPath LocalName)
| (NodeName ("," TypeName "nillable"?)?))? ")"
[129]    AttributeTest    ::=    <"attribute" "("> ((SchemaContextPath "@" LocalName)
| ("@" NodeName ("," TypeName)?))? ")"
[130]    PITest    ::=    <"processing-instruction" "("> (NCName | StringLiteral)? ")"
[131]    DocumentTest    ::=    <"document-node" "("> ElementTest? ")"
[132]    CommentTest    ::=    <"comment" "("> ")"
[133]    TextTest    ::=    <"text" "("> ")"
[134]    AnyKindTest    ::=    <"node" "("> ")"
[135]    SchemaContextPath    ::=    <SchemaGlobalContext "/"> <SchemaContextStep "/">*
[136]    SchemaContextLoc    ::=    (SchemaContextPath? QName) | SchemaGlobalTypeName
[137]    LocalName    ::=    QName
[138]    NodeName    ::=    QName | "*"
[139]    TypeName    ::=    QName | "*"
[140]    OccurrenceIndicator    ::=    "?" | "*" | "+"
[141]    ValidationDecl    ::=    <"declare" "validation"> SchemaMode
[142]    SchemaImport    ::=    <"import" "schema"> SchemaPrefix? StringLiteral <"at" StringLiteral>?
[143]    SchemaPrefix    ::=    ("namespace" NCName "=") | (<"default" "element"> "namespace")

A.1.1 Grammar Notes

This section contains general notes on the EBNF productions, which may be helpful in understanding how to create a parser based on this EBNF, how to read the EBNF, and generally call out issues with the syntax. The notes below are referenced from the right side of the production, with the notation: /* gn: <id> */.

grammar-note: parens

A look-ahead of one character is required to distinguish function patterns from a QName followed by a comment. For example: address (: this may be empty :) may be mistaken for a call to a function named "address" unless this lookahead is employed.

grammar-note: lt

Token disambiguation of the overloaded "<" pattern is defined in terms of positional lexical states. The "<" comparison operator can not occur in the same places as a "<" tag open pattern. The "<" comparison operator can only occur in the OPERATOR state and the "<" tag open pattern can only occur in the DEFAULT and the ELEMENT_CONTENT states. (These states are only a specification tool, and do not mandate an implementation strategy for this same effect.)

grammar-note: validate

The ValidateExpr in the exposition, which does not use the "< ... >" token grouping, presents the production in a much simplified, and understandable, form. The ValidateExpr presented in the appendix is technically correct, but structurally hard to understand, because of limitations of the "< ... >" token grouping.

grammar-note: leading-lone-slash

The "/" presents an issue because it occurs both in a leading position and an operator position in expressions. Thus, expressions such as "/ * 5" can easily be confused with the path expression "/*". Therefore, a stand-alone slash, in a leading position, that is followed by an operator, will need to be parenthesized in order to stand alone, as in "(/) * 5". "5 * /", on the other hand, is fine.

grammar-note: comments

Expression comments are allowed inside expressions everywhere that ignorable white space is allowed. Note that expression comments are not allowed in constructor content.

A.2 Lexical structure

Legal characters are those allowed in the [XML] recommendation.

When patterns are simple string matches, the strings are embedded directly into the EBNF. In other cases, named terminals are used.

It is up to an implementation to decide on the exact tokenization strategy, which may be different depending on the parser construction. In the EBNF, the notation "< ... >" is used to indicate a grouping of terminals that together may help disambiguate the individual symbols.

This document uses lexical states to assist with terminal symbol recognition. The states specify lexical constraints and transitions based on grammatical positioning. The rules for calculating these states are given in the A.2.2 Lexical Rules section. The specification of these states in this document does not imply any tokenization strategy on the part of implementations.

When tokenizing, the longest possible match that is valid in the current lexical state is preferred .

All keywords are case sensitive.

A.2.1 White Space Rules

For readability, White space may be used in most expressions even though not explicitly notated in the EBNF. White space may be freely added between terminals, except a few cases where white space is needed to disambiguate the token. For instance, in XML, "-" is a valid character in an element or attribute name. When used as an operator after the characters of a name, it must be separated from the name, e.g. by using white space or parentheses.

Special white space notation is specified with the EBNF productions, when it is different from the default rules, as follows.

Whitespace: explicit

"ws: explicit" means that the EBNF notation must explicitly notate where white space is allowed, otherwise white space may not be freely used.

Whitespace: significant

"ws: significant" means that white space is significant as value content.

For XQuery, White space is not freely allowed in the non-computed Constructor productions, but is specified explicitly in the grammar, in order to be more consistent with XML. The lexical states where white space must have explicit specification are as follows: START_TAG, END_TAG, ELEMENT_CONTENT, XML_COMMENT, PROCESSING_INSTRUCTION, PROCESSING_INSTRUCTION_CONTENT, CDATA_SECTION, QUOT_ATTRIBUTE_CONTENT, and APOS_ATTRIBUTE_CONTENT.

A.2.2 Lexical Rules

The lexical contexts and transitions between lexical contexts is described in terms of a series of states and transitions between those states.

The tables below define the complete lexical rules for XQuery. Each table corresponds to a lexical state and shows that the tokens listed are recognized when in that state. When a given token is recognized in the given state, the transition to the next state is given. In some cases, a transition will "push" the current state or a specific state onto an abstract stack, and will later restore that state by a "pop" when another lexical event occurs.

The lexical states have, in many cases, close connection to the parser productions. However, just because a token is recognized in a certain lexical state, does not mean it will be legal in the current EBNF production.

Note:

There is no requirement for a lexer/parser to be implemented in terms of lexical states... these are only a declarative way to specify the behavior. The only requirement is to produce results that are consistent with the results of these tables.

The DEFAULT State

This state is for patterns that occur at the beginning of an expression or subexpression.

Pattern Transition To State
DecimalLiteral, "..", ".", DoubleLiteral, IntegerLiteral, <NCName ":" "*">, <"stable" "order" "by">, QName, "]", ")", <"*" ":" NCName>, "*", StringLiteral, <"typeswitch" "(">, <"declare" "validation">
OPERATOR
<"declare" "default" "collation">, <"declare" "namespace">, <"declare" "base-uri">, <"module" "namespace">
NAMESPACEDECL
<"declare" "default" "element">, <"declare" "default" "function">, <"import" "schema">, <"import" "module">
NAMESPACEKEYWORD
"$", <"for" "$">, <"let" "$">, <"some" "$">, <"every" "$">
VARNAME
<"declare" S "variable" "$">
VARNAME
pushState(DEFAULT)
<")" "as">
ITEMTYPE
<"element" "(">, <"attribute" "(">, <"comment" "(">, <"text" "(">, <"node" "(">, <"document-node" "(">
KINDTEST
pushState(OPERATOR)
<"processing-instruction" "(">
KINDTESTFORPI
pushState(OPERATOR)
"<!--"
XML_COMMENT
pushState()
"<?"
PROCESSING_INSTRUCTION
pushState()
"<![CDATA["
CDATA_SECTION
pushState()
"<"
START_TAG
pushState(OPERATOR)
<"declare" "xmlspace">
XMLSPACE_DECL
"}"
popState()
<"validate" "{">, <"validate" "global">
DEFAULT
pushState(OPERATOR)
<"validate" "context">, <"validate" SchemaMode>
KINDTEST
pushState(OPERATOR)
<"element" "{">, <"attribute" "{">
pushState(OPERATOR);pushState(DEFAULT)
<"attribute" QName "{">, <"namespace" NCName "{">, <"element" QName "{">, <"document" "{">, <"text" "{">, <"pi" "{">, <"pi" NCName "{">, <"comment" "{">
pushState(OPERATOR)
<"declare" "function">
DEFAULT
pushState(DEFAULT)
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
"{", <"xquery" "version" StringLiteral>, <"at" StringLiteral>, "@", <"ancestor-or-self" "::">, <"ancestor" "::">, <"attribute" "::">, <"child" "::">, <"descendant-or-self" "::">, <"descendant" "::">, <"following-sibling" "::">, <"following" "::">, AxisNamespace, <"parent" "::">, <"preceding-sibling" "::">, <"preceding" "::">, <"self" "::">, ",", <"if" "(">, "[", "(", "-", "+", <QName "(">, ";", QuerySeperator, "//", "/", S
(maintain state)


The OPERATOR State

This state is for patterns that are defined for operators.

Pattern Transition To State
<"declare" "function">
DEFAULT
pushState(DEFAULT)
"external", "and", <"at" StringLiteral>, "at", ":=", ",", "div", "else", "=", "except", "eq", "ge", "gt", "le", "lt", "ne", ">=", ">>", ">", "idiv", "global", "intersect", "in", "isnot", "is", "[", "(", "<=", "<<", "<", "-", "mod", "*", "!=", <"order" "by">, "or", "+", "return", "satisfies", ";", QuerySeperator, "//", "/", "then", "to", "union", "|", "where", "{", SchemaMode
DEFAULT
<"validate" "{">
DEFAULT
pushState(OPERATOR)
<"declare" "default" "collation">
NAMESPACEDECL
<"import" "schema">, <"import" "module">, <"declare" "default" "element">, <"declare" "default" "function">
NAMESPACEKEYWORD
<"declare" "namespace">, <"declare" "base-uri">
NAMESPACEDECL
<"instance" "of">, <"castable" "as">, <"cast" "as">, <"treat" "as">, "case", "as", <")" "as">
ITEMTYPE
<"declare" "xmlspace">
XMLSPACE_DECL
"}"
popState()
"$", <"for" "$">, <"let" "$">, <"some" "$">, <"every" "$">
VARNAME
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
"]", IntegerLiteral, DecimalLiteral, DoubleLiteral, <"typeswitch" "(">, <"stable" "order" "by">, "collation", ")", "ascending", "descending", <"empty" "greatest">, <"empty" "least">, StringLiteral, "default", QName, <NCName ":" "*">, <"*" ":" NCName>, ".", "..", S
(maintain state)


The NAMESPACEDECL State

This state occurs inside of a namespace declaration, and is needed to recognize a NCName that is to be used as the prefix, as opposed to allowing a QName to occur. (Otherwise, the difference between NCName and QName are ambiguous.)

Pattern Transition To State
StringLiteral
DEFAULT
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
"=", NCName, S
(maintain state)


The NAMESPACEKEYWORD State

This state occurs at places where the keyword "namespace" is expected, which would otherwise be ambiguous compared to a QName. QNames can not occur in this state.

Pattern Transition To State
StringLiteral, <"at" StringLiteral>
DEFAULT
"namespace"
NAMESPACEDECL
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
<"default" "element">, <"declare" "default" "element">, <"declare" "default" "function">, S
(maintain state)


The XMLSPACE_DECL State

This state occurs at places where the keywords "preserve" and "strip" is expected to support "declare xmlspace". QNames can not occur in this state.

Pattern Transition To State
"preserve", "strip"
DEFAULT
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()


The ITEMTYPE State

This state distinguishes tokens that can occur only inside the ItemType production.

Pattern Transition To State
"$"
VARNAME
<"empty" "(" ")">
OPERATOR
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
<"element" "(">, <"attribute" "(">, <"comment" "(">, <"text" "(">, <"node" "(">, <"document-node" "(">
KINDTEST
pushState(OCCURRENCEINDICATOR)
<"processing-instruction" "(">
KINDTESTFORPI
pushState(OPERATOR)
QName, <"item" "(" ")">
OCCURRENCEINDICATOR


The KINDTEST State
Pattern Transition To State
"{"
DEFAULT
<SchemaGlobalContext "/">, SchemaGlobalTypeName
SCHEMACONTEXTSTEP
")"
popState()
"*", QName
CLOSEKINDTEST
<"element" "(">
KINDTEST
pushState(KINDTEST)
"@", S, "context", "global", StringLiteral
(maintain state)


The KINDTESTFORPI State
Pattern Transition To State
")"
popState()
S, NCName, StringLiteral
(maintain state)


The CLOSEKINDTEST State
Pattern Transition To State
")"
popState()
","
KINDTEST
"{"
DEFAULT
"nillable"
(maintain state)


The OCCURRENCEINDICATOR State
Pattern Transition To State
NotOccurrenceIndicator
OPERATOR
input_stream.backup(1)
"?", "*", "+"
OPERATOR


The SCHEMACONTEXTSTEP State

This state distinguishes the SchemaContextStep from the SchemaGlobalContext.

Pattern Transition To State
<SchemaContextStep "/">, "@"
(maintain state)
"{"
DEFAULT
QName
CLOSEKINDTEST


The VARNAME State

This state differentiates variable names from qualified names. This allows only the pattern of a QName to be recognized when otherwise ambiguities could occur.

Pattern Transition To State
VarName
OPERATOR
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()


The START_TAG State

This state allows attributes in the native XML syntax, and marks the beginning of an element construction. Element constructors also push the current state, popping it at the conclusion of an end tag. In the START_TAG state, the string ">" is recognized as a token which is associated with the transition to the original state.

Pattern Transition To State
"/>"
popState()
">"
ELEMENT_CONTENT
'"'
QUOT_ATTRIBUTE_CONTENT
"'"
APOS_ATTRIBUTE_CONTENT
"{"
DEFAULT
pushState()
S, QName, "="
(maintain state)


The ELEMENT_CONTENT State

This state allows XML-like content, without these characters being misinterpreted as expressions. The character "{" marks a transition to the DEFAULT state, i.e. the start of an embedded expression, and the "}" character pops back to the ELEMENT_CONTENT state. To allow curly braces to be used as character content, a double left or right curly brace is interpreted as a single curly brace character. The string "</" is interpreted as the beginning of an end tag, which is associated with a transition to the END_TAG state.

Pattern Transition To State
"</"
END_TAG
"{"
DEFAULT
pushState()
"<!--"
XML_COMMENT
pushState()
"<?"
PROCESSING_INSTRUCTION
pushState()
"<![CDATA["
CDATA_SECTION
pushState()
"<"
START_TAG
pushState()
PredefinedEntityRef, CharRef, "{{", "}}", ElementContentChar
(maintain state)


The END_TAG State

When the end tag is terminated, the state is popped to the state that was pushed at the start of the corresponding start tag.

Pattern Transition To State
">"
popState()
"{"
DEFAULT
pushState()
S, QName
(maintain state)


The XML_COMMENT State

The "<--" token marks the beginning of an XML Comment, and the "-->" token marks the end. This allows no special interpretation of other characters in this state.

Pattern Transition To State
"-->"
popState()
Char, PragmaContents, ExtensionContents
(maintain state)


The EXPR_COMMENT State

The "(:" token marks the beginning of an expression Comment, and the ":)" token marks the end. This allows no special interpretation of other characters in this state.

Pattern Transition To State
":)", "::)"
popState()
"(:"
EXPR_COMMENT
pushState()
"(::"
EXT_KEY
pushState()
ExprCommentContent
(maintain state)


The EXT_KEY State

The "(::" token marks the beginning of an expression extension, which must be followed by a keyword.

Pattern Transition To State
QName, QName
EXPR_COMMENT
"pragma", "extension"
(maintain state)


The PROCESSING_INSTRUCTION State

In this state, only lexemes that are legal in a processing instruction name are recognized.

Pattern Transition To State
PITarget
PROCESSING_INSTRUCTION_CONTENT


The PROCESSING_INSTRUCTION_CONTENT State

In this state, only characters are that are legal in processing instruction content are recognized.

Pattern Transition To State
"?>"
popState()
Char
(maintain state)


The CDATA_SECTION State

In this state, only lexemes that are legal in a CDATA section are recognized.

Pattern Transition To State
"]]>"
popState()
Char
(maintain state)


The QUOT_ATTRIBUTE_CONTENT State

This state allows content legal for attributes. The character "{" marks a transition to the DEFAULT state, i.e. the start of an embedded expression, and the "}" character pops back to the original state. To allow curly braces to be used as character content, a double left or right curly brace is interpreted as a single curly brace character. This state is the same as APOS_ATTRIBUTE_CONTENT, except that apostrophes are allowed without escaping, and an unescaped quote marks the end of the state.

Pattern Transition To State
'"'
START_TAG
"{"
DEFAULT
pushState()
EscapeQuot, PredefinedEntityRef, CharRef, "{{", "}}", QuotAttContentChar
(maintain state)


The APOS_ATTRIBUTE_CONTENT State

This state is the same as QUOT_ATTRIBUTE_CONTENT, except that quotes are allowed, and an unescaped apostrophe marks the end of the state.

Pattern Transition To State
"'"
START_TAG
"{"
DEFAULT
pushState()
EscapeApos, PredefinedEntityRef, CharRef, "{{", "}}", AposAttContentChar
(maintain state)


A.3 Reserved Function Names

The following is a list of names that must not be used as user function names, in an unprefixed form, because these functions could be confused with expression syntax.

  • attribute

  • comment

  • document-node

  • element

  • empty

  • if

  • item

  • node

  • processing-instruction

  • text

  • type

  • typeswitch

A.4 Precedence Order

The grammar defines built-in precedence, which is summarised here. In the cases where a number of operators are a choice at the same production level, the expressions are always evaluated from left to right. The operators in order of increasing precedence are:

1 (comma)
2 FLWORExpr, some, every, TypeswitchExpr, IfExpr, or
3 and
4 instance of
5 treat
6 castable
7 cast
8 eq, ne, lt, le, gt, ge, =, !=, <, <=, >, >=, is, isnot, <<, >>
9 to
10 +, -
11 *, div, idiv, mod
12 unary -, unary +
13 union, |
14 intersect, except
15 ValidateExpr, /, //
16 [ ]

B Type Promotion and Operator Mapping

B.1 Type Promotion

Under certain circumstances, an atomic value can be promoted from one type to another. Type promotion is used in function calls (see 3.1.5 Function Calls) and in processing of operators that accept numeric operands (listed in the tables below). The following type promotions are permitted:

  1. A value of type xs:float (or any type derived by restriction from xs:float) can be promoted to the type xs:double. The result is the xs:double value that is the same as the original value. This kind of promotion may cause loss of precision.

  2. A value of type xs:decimal (or any type derived by restriction from xs:decimal) can be promoted to either of the types xs:float or xs:double. The result is the value of the target type that is closest to the original value.

Note that promotion is different from subtype substitution. For example:

  • A function that expects a parameter $p of type xs:float can be invoked with a value of type xs:decimal. This is an example of promotion. The value is actually converted to the expected type. Within the body of the function, $p instance of xs:decimal returns false.

  • A function that expects a parameter $p of type xs:decimal can be invoked with a value of type xs:integer. This is an example of subtype substitution. The value retains its original type. Within the body of the function, $p instance of xs:integer returns true.

B.2 Operator Mapping

The tables in this section list the combinations of types for which the various operators of XQuery are defined. For each valid combination of types, the table indicates the function(s) that are used to implement the operator and the type of the result. Definitions of the functions can be found in [XQuery 1.0 and XPath 2.0 Functions and Operators]. Note that in some cases the function does not implement the full semantics of the given operator. For a complete description of each operator (including its behavior for empty sequences or sequences of length greater than one), see the descriptive material in the main part of this document.

Operators listed in the tables may be validly applied to operands whose types are derived by restriction from the listed operand types. For example, a table entry indicates that the gt operator may be applied to two xs:date operands, returning xs:boolean. Therefore, the gt operator may also be applied to two (possibly different) subtypes of xs:date, also returning xs:boolean.

In the operator tables, the term numeric refers to the types xs:integer, xs:decimal, xs:float, and xs:double. An operator whose operands and result are designated as numeric might be thought of as representing four operators, one for each of the numeric types. For example, the numeric + operator might be thought of as representing the following four operators:

Operator First operand type Second operand type Result type
+ xs:integer xs:integer xs:integer
+ xs:decimal xs:decimal xs:decimal
+ xs:float xs:float xs:float
+ xs:double xs:double xs:double

A numeric operator accepts operands of the four numeric types and any type that is derived by restriction from one of the four numeric types. If the result type of an operator is listed as numeric, it means "the first numeric type, in promotion order, into which all operands can be converted by subtype substitution and promotion." As an example, suppose that the type hatsize is derived from xs:integer and the type shoesize is derived from xs:float. Then if the + operator is invoked with operands of type hatsize and shoesize, it returns a result of type xs:float. Similarly, if + is invoked with two operands of type hatsize it returns a result of type xs:integer.

In the following tables, the term Gregorian refers to the types xs:gYearMonth, xs:gYear, xs:gMonthDay, xs:gDay, and xs:gMonth. For binary operators that accept two Gregorian-type operands, both operands must have the same type (for example, if one operand is of type xs:gDay, the other operand must be of type xs:gDay.)

Binary Operators
Operator Type(A) Type(B) Function Result type
A + B numeric numeric op:numeric-add(A, B) numeric
A + B xs:date xdt:yearMonthDuration op:add-yearMonthDuration-to-date(A, B) xs:date
A + B xdt:yearMonthDuration xs:date op:add-yearMonthDuration-to-date(B, A) xs:date
A + B xs:date xdt:dayTimeDuration op:add-dayTimeDuration-to-date(A, B) xs:date
A + B xdt:dayTimeDuration xs:date op:add-dayTimeDuration-to-date(B, A) xs:date
A + B xs:time xdt:dayTimeDuration op:add-dayTimeDuration-to-time(A, B) xs:time
A + B xdt:dayTimeDuration xs:time op:add-dayTimeDuration-to-time(B, A) xs:time
A + B xs:datetime xdt:yearMonthDuration op:add-yearMonthDuration-to-dateTime(A, B) xs:dateTime
A + B xdt:yearMonthDuration xs:datetime op:add-yearMonthDuration-to-dateTime(B, A) xs:dateTime
A + B xs:datetime xdt:dayTimeDuration op:add-dayTimeDuration-to-dateTime(A, B) xs:dateTime
A + B xdt:dayTimeDuration xs:datetime op:add-dayTimeDuration-to-dateTime(B, A) xs:dateTime
A + B xdt:yearMonthDuration xdt:yearMonthDuration op:add-yearMonthDurations(A, B) xdt:yearMonthDuration
A + B xdt:dayTimeDuration xdt:dayTimeDuration op:add-dayTimeDurations(A, B) xdt:dayTimeDuration
A - B numeric numeric op:numeric-subtract(A, B) numeric
A - B xs:date xs:date op:subtract-dates(A, B) xdt:dayTimeDuration
A - B xs:date xdt:yearMonthDuration op:subtract-yearMonthDuration-from-date(A, B) xs:date
A - B xs:date xdt:dayTimeDuration op:subtract-dayTimeDuration-from-date(A, B) xs:date
A - B xs:time xs:time op:subtract-times(A, B) xdt:dayTimeDuration
A - B xs:time xdt:dayTimeDuration op:subtract-dayTimeDuration-from-time(A, B) xs:time
A - B xs:datetime xs:datetime fn:subtract-dateTimes-yielding-dayTimeDuration(A, B) xdt:dayTimeDuration
A - B xs:datetime xdt:yearMonthDuration op:subtract-yearMonthDuration-from-dateTime(A, B) xs:dateTime
A - B xs:datetime xdt:dayTimeDuration op:subtract-dayTimeDuration-from-dateTime(A, B) xs:dateTime
A - B xdt:yearMonthDuration xdt:yearMonthDuration op:subtract-yearMonthDurations(A, B) xdt:yearMonthDuration
A - B xdt:dayTimeDuration xdt:dayTimeDuration op:subtract-dayTimeDurations(A, B) xdt:dayTimeDuration
A * B numeric numeric op:numeric-multiply(A, B) numeric
A * B xdt:yearMonthDuration xs:decimal op:multiply-yearMonthDuration(A, B) xdt:yearMonthDuration
A * B xs:decimal xdt:yearMonthDuration op:multiply-yearMonthDuration(B, A) xdt:yearMonthDuration
A * B xdt:dayTimeDuration xs:decimal op:multiply-dayTimeDuration(A, B) xdt:dayTimeDuration
A * B xs:decimal xdt:dayTimeDuration op:multiply-dayTimeDuration(B, A) xdt:dayTimeDuration
A idiv B xs:integer xs:integer op:integer-div(A, B) xs:integer
A div B numeric numeric op:numeric-divide(A, B) numeric; but xs:decimal if both operands are xs:integer
A div B xdt:yearMonthDuration xs:decimal op:divide-yearMonthDuration(A, B) xdt:yearMonthDuration
A div B xdt:dayTimeDuration xs:decimal op:divide-dayTimeDuration(A, B) xdt:dayTimeDuration
A mod B numeric numeric op:numeric-mod(A, B) numeric
A eq B numeric numeric op:numeric-equal(A, B) xs:boolean
A eq B xs:boolean xs:boolean op:boolean-equal(A, B) xs:boolean
A eq B xs:string xs:string op:numeric-equal(fn:compare(A, B), 1) xs:boolean
A eq B xs:date xs:date op:date-equal(A, B) xs:boolean
A eq B xs:time xs:time op:time-equal(A, B) xs:boolean
A eq B xs:dateTime xs:dateTime op:datetime-equal(A, B) xs:boolean
A eq B xdt:yearMonthDuration xdt:yearMonthDuration op:yearMonthDuration-equal(A, B) xs:boolean
A eq B xdt:dayTimeDuration xdt:dayTimeDuration op:dayTimeDuration-equal(A, B) xs:boolean
A eq B Gregorian Gregorian op:gYear-equal(A, B) etc. xs:boolean
A eq B xs:hexBinary xs:hexBinary op:hex-binary-equal(A, B) xs:boolean
A eq B xs:base64Binary xs:base64Binary op:base64-binary-equal(A, B) xs:boolean
A eq B xs:anyURI xs:anyURI op:anyURI-equal(A, B) xs:boolean
A eq B xs:QName xs:QName op:QName-equal(A, B) xs:boolean
A eq B xs:NOTATION xs:NOTATION op:NOTATION-equal(A, B) xs:boolean
A ne B numeric numeric fn:not(op:numeric-equal(A, B)) xs:boolean
A ne B xs:boolean xs:boolean fn:not(op:boolean-equal(A, B)) xs:boolean
A ne B xs:string xs:string fn:not(op:numeric-equal(fn:compare(A, B), 1)) xs:boolean
A ne B xs:date xs:date fn:not(op:date-equal(A, B)) xs:boolean
A ne B xs:time xs:time fn:not(op:time-equal(A, B)) xs:boolean
A ne B xs:dateTime xs:dateTime fn:not(op:datetime-equal(A, B)) xs:boolean
A ne B xdt:yearMonthDuration xdt:yearMonthDuration fn:not(op:yearMonthDuration-equal(A, B)) xs:boolean
A ne B xdt:dayTimeDuration xdt:dayTimeDuration fn:not(op:dayTimeDuration-equal(A, B) xs:boolean
A ne B Gregorian Gregorian fn:not(op:gYear-equal(A, B)) etc. xs:boolean
A ne B xs:hexBinary xs:hexBinary fn:not(op:hex-binary-equal(A, B)) xs:boolean
A ne B xs:base64Binary xs:base64Binary fn:not(op:base64-binary-equal(A, B)) xs:boolean
A ne B xs:anyURI xs:anyURI fn:not(op:anyURI-equal(A, B)) xs:boolean
A ne B xs:QName xs:QName fn:not(op:QName-equal(A, B)) xs:boolean
A ne B xs:NOTATION xs:NOTATION fn:not(op:NOTATION-equal(A, B)) xs:boolean
A gt B numeric numeric op:numeric-greater-than(A, B) xs:boolean
A gt B xs:boolean xs:boolean op:boolean-greater-than(A, B) xs:boolean
A gt B xs:string xs:string op:numeric-greater-than(fn:compare(A, B), 0) xs:boolean
A gt B xs:date xs:date op:date-greater-than(A, B) xs:boolean
A gt B xs:time xs:time op:time-greater-than(A, B) xs:boolean
A gt B xs:dateTime xs:dateTime op:datetime-greater-than(A, B) xs:boolean
A gt B xdt:yearMonthDuration xdt:yearMonthDuration op:yearMonthDuration-greater-than(A, B) xs:boolean
A gt B xdt:dayTimeDuration xdt:dayTimeDuration op:dayTimeDuration-greater-than(A, B) xs:boolean
A lt B numeric numeric op:numeric-less-than(A, B) xs:boolean
A lt B xs:boolean xs:boolean op:boolean-less-than(A, B) xs:boolean
A lt B xs:string xs:string op:numeric-less-than(fn:compare(A, B), 0) xs:boolean
A lt B xs:date xs:date op:date-less-than(A, B) xs:boolean
A lt B xs:time xs:time op:time-less-than(A, B) xs:boolean
A lt B xs:dateTime xs:dateTime op:datetime-less-than(A, B) xs:boolean
A lt B xdt:yearMonthDuration xdt:yearMonthDuration op:yearMonthDuration-less-than(A, B) xs:boolean
A lt B xdt:dayTimeDuration xdt:dayTimeDuration op:dayTimeDuration-less-than(A, B) xs:boolean
A ge B numeric numeric fn:not(op:numeric-less-than(A, B)) xs:boolean
A ge B xs:string xs:string op:numeric-greater-than(fn:compare(A, B), -1) xs:boolean
A ge B xs:date xs:date fn:not(op:date-less-than(A, B)) xs:boolean
A ge B xs:time xs:time fn:not(op:time-less-than(A, B)) xs:boolean
A ge B xs:dateTime xs:dateTime fn:not(op:datetime-less-than(A, B)) xs:boolean
A ge B xdt:yearMonthDuration xdt:yearMonthDuration fn:not(op:yearMonthDuration-less-than(A, B)) xs:boolean
A ge B xdt:dayTimeDuration xdt:dayTimeDuration fn:not(op:dayTimeDuration-less-than(A, B)) xs:boolean
A le B numeric numeric fn:not(op:numeric-greater-than(A, B)) xs:boolean
A le B xs:string xs:string op:numeric-less-than(fn:compare(A, B), 1) xs:boolean
A le B xs:date xs:date fn:not(op:date-greater-than(A, B)) xs:boolean
A le B xs:time xs:time fn:not(op:time-greater-than(A, B)) xs:boolean
A le B xs:dateTime xs:dateTime fn:not(op:datetime-greater-than(A, B)) xs:boolean
A le B xdt:yearMonthDuration xdt:yearMonthDuration fn:not(op:yearMonthDuration-greater-than(A, B)) xs:boolean
A le B xdt:dayTimeDuration xdt:dayTimeDuration fn:not(op:dayTimeDuration-greater-than(A, B)) xs:boolean
A is B node node op:node-equal(A, B) xs:boolean
A isnot B node node fn:not(op:node-equal(A, B)) xs:boolean
A << B node node op:node-before(A, B) xs:boolean
A >> B node node op:node-after(A, B) xs:boolean
A union B node* node* op:union(A, B) node*
A | B node* node* op:union(A, B) node*
A intersect B node* node* op:intersect(A, B) node*
A except B node* node* op:except(A, B) node*
A to B xs:integer xs:integer op:to(A, B) xs:integer+
A , B item* item* op:concatenate(A, B) item*
Unary Operators
Operator Operand type Function Result type
+ A numeric op:numeric-unary-plus(A) numeric
- A numeric op:numeric-unary-minus(A) numeric

C Context Components

The tables in this section describe how values are assigned to the various components of the static context and dynamic context, and to the parameters that control the serialization process.

C.1 Static Context Components

The following table describes the components of the static context. The following aspects of each component are described:

  • Default value: This is the value of the component if it is not overridden or augmented by the implementation or by a query.

  • Can be overwritten or augmented by implementation: Indicates whether an XQuery implementation is allowed to replace the default value of the component by a different value and/or to augment the default value by additional values.

  • Can be overwritten or augmented by a query: Indicates whether a query is allowed to replace and/or augment the initial value provided by default or by the implementation. If so, indicates how this is accomplished (for example, by a declaration in the prolog).

  • Scope: Indicates where the component is applicable. "Global" indicates that the component applies throughout a module. "Lexical" indicates that the component applies within the expression in which it is defined (same as "global" if the component is declared in the prolog of a module.)

  • Consistency Rules: Indicates rules that must be observed in assigning values to the component. If any consistency rule is violated, a static error is raised. Additional consistency rules may be found in 2.2.5 Consistency Constraints.

Static Context Components
Component Default predefined value Can be overwritten or augmented by implementation? Can be overwritten or augmented by a query? Scope Consistency rules
XPath 1.0 Compatability Mode false no no global Must be false.
In-scope namespaces fn, xml, xs, xsi, xdt, local overwriteable and augmentable (except for xml) overwriteable and augmentable by prolog or element constructor lexical Only one namespace can be assigned to a given prefix per lexical scope.
Default element/type namespace no namespace overwriteable overwriteable by prolog or element constructor lexical Only one default namespace per lexical scope.
Default function namespace fn overwriteable (not recommended) overwriteable by prolog global Only one declaration per prolog.
In-scope type definitions Built-in types in xs, xdt augmentable augmentable by schema import in prolog global Only one definition per global or local type.
In-scope element declarations none augmentable augmentable by schema import in prolog global Only one definition per global or local element name.
In-scope attribute declarations none augmentable augmentable by schema import in prolog global Only one definition per global or local attribute name.
In-scope variables none augmentable overwriteable and augmentable by prolog and by variable-binding expressions lexical Only one definition per variable per lexical scope.
In-scope functions Functions in fn namespace, and constructors for built-in atomic types augmentable augmentable by module import and by function declaration in prolog global Only one user-declared function with a given name; only one built-in function with a given name and argument cardinality.
In-scope collations only the default collation augmentable no global Each URI uniquely identifies a collation.
Default collation Unicode codepoint collation overwriteable overwriteable by prolog global Only one default collation.
Validation mode lax overwriteable overwriteable by prolog or validate expression lexical Only one validation mode per lexical scope.
Validation context global no overwriteable by validate expression lexical Only one validation context per lexical scope.
XMLSpace policy strip overwriteable overwriteable by prolog global Only one XMLSpace declaration per prolog.
Base URI none overwriteable overwriteable by prolog global Only one base-uri declaration per prolog.
Statically-known documents none augmentable no global None
Statically-known collections none augmentable no global None

C.2 Dynamic Context Components

The following table describes the components of the dynamic context. The following aspects of each component are described:

  • Default value: This is the value of the component if it is not overridden or augmented by the implementation or by a query.

  • Can be overwritten or augmented by implementation: Indicates whether an XQuery implementation is allowed to replace the default value of the component by a different value and/or to augment the default value by additional values.

  • Can be overwritten or augmented by a query: Indicates whether a query is allowed to replace and/or augment the initial value provided by default or by the implementation. If so, indicates how this is accomplished.

  • Scope: Indicates where the component is applicable. "Global" indicates that the component applies throughout a module. "Dynamic" indicates that the value of the component can be influenced by the evaluation of expressions within a query.

  • Consistency Rules: Indicates rules that must be observed in assigning values to the component. Additional consistency rules may be found in 2.2.5 Consistency Constraints.

Dynamic Context Components
Component Default predefined value Can be overwritten or augmented by implementation? Can be overwritten or augmented by a query? Scope Consistency rules
Context item none overwriteable overwritten during evaluation of path expressions and predicates dynamic none
Context position none overwriteable overwritten during evaluation of path expressions and predicates dynamic Must be consistent with context item and context size
Context size none overwriteable overwritten during evaluation of path expressions and predicates dynamic Must be consistent with context item
Dynamic variables none augmentable overwriteable and augmentable by prolog and by variable-binding expressions dynamic Names and values must be consistent with in-scope variables.
Current date and time none Must be initialized by implementation no global Remains constant during evaluation of a query.
Implicit timezone none overwriteable no global Remains constant during evaluation of a query.
Accessible documents none augmentable no global None
Accessible collections none augmentable no global None

C.3 Serialization Parameters

The following table specifies default values for the parameters that control the process of serializing a Data Model instance into XML notation. The meanings of the various parameters are defined in [XSLT 2.0 and XQuery 1.0 Serialization]. For each parameter, an XQuery implementation may (but is not required to) provide a means whereby a user can override the default value.

Serialization Parameters
Parameter Default Value
encoding implementation-defined
cdata-section-elements empty
doctype-system empty
doctype-public empty
escape-uri-attributes no
indent no
media-type implementation-defined
normalize-unicode implementation-defined
omit-xml-declaration yes
standalone yes
character-map empty
version 1.0

D References

D.1 Normative References

XQuery 1.0 and XPath 2.0 Functions and Operators
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Functions and Operators W3C Working Draft, 2 May 2003. See http://www.w3.org/TR/xpath-functions/
XQuery 1.0 and XPath 2.0 Formal Semantics
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Formal Semantics. W3C Working Draft, 22 Aug. 2003. See http://www.w3.org/TR/xquery-semantics/.
XML Schema
World Wide Web Consortium. XML Schema, Parts 0, 1, and 2. W3C Recommendation, 2 May 2001. See http://www.w3.org/TR/2001/REC-xmlschema-0-20010502/, http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/, and http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/.
XQuery 1.0 and XPath 2.0 Data Model
World Wide Web Consortium. XQuery 1.0 and XPath 2.0 Data Model. W3C Working Draft, 2 May 2003. See http://www.w3.org/TR/xpath-datamodel/.
XSLT 2.0 and XQuery 1.0 Serialization
World Wide Web Consortium. XSLT 2.0 and XQuery 1.0 Serialization. W3C Working Draft, 2 May 2003. See http://www.w3.org/TR/xslt-xquery-serialization/.
XML
World Wide Web Consortium. Extensible Markup Language (XML) 1.0. W3C Recommendation. See http://www.w3.org/TR/2000/REC-xml-20001006
XML Names
World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See http://www.w3.org/TR/REC-xml-names/
ISO/IEC 10646
ISO (International Organization for Standardization). ISO/IEC 10646-1993 (E). Information technology -- Universal Multiple-Octet Coded Character Set (UCS) -- Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization, 1993 (plus amendments AM 1 through AM 7).
ISO/IEC 10646-2000
ISO (International Organization for Standardization). ISO/IEC 10646-1:2000. Information technology -- Universal Multiple-Octet Coded Character Set (UCS) -- Part 1: Architecture and Basic Multilingual Plane. [Geneva]: International Organization for Standardization, 2000.
Unicode
The Unicode Consortium. The Unicode Standard, Version 2.0. Reading, Mass.: Addison-Wesley Developers Press, 1996.
Unicode3
The Unicode Consortium. The Unicode Standard, Version 3.0. Reading, Mass.: Addison-Wesley Developers Press, 2000. ISBN 0-201-61633-5.

D.2 Non-normative References

XML Query 1.0 Requirements
World Wide Web Consortium. XML Query 1.0 Requirements. W3C Working Draft, 27 Jun 2003. See http://www.w3.org/TR/xquery-requirements/.
XQueryX 1.0
World Wide Web Consortium. XQueryX, Version 1.0. W3C Working Draft, 7 June 2001. See http://www.w3.org/TR/xqueryx
Editorial note  
As of the date of this publication, XQueryX has not incorporated recent language changes; it will be made consistent with this document in its next edition.
XPath 2.0
World Wide Web Consortium. XML Path Language (XPath) Version 2.0. W3C Working Draft, 22 Aug. 2003. See http://www.w3.org/TR/xpath20/
XSLT 2.0
World Wide Web Consortium. XSL Transformations (XSLT) 2.0. W3C Working Draft. See http://www.w3.org/TR/xslt20/
XML Query Use Cases
World Wide Web Consortium. XML Query Use Cases. W3C Working Draft, 22 Aug. 2003. See http://www.w3.org/TR/xquery-use-cases/.
ISO 8601
International Organization for Standardization (ISO). Representations of Dates and Times, 2000-08-03. Available from http://www.iso.ch/

D.3 Background References

XQL
J. Robie, J. Lapp, D. Schach. XML Query Language (XQL). See http://www.w3.org/TandS/QL/QL98/pp/xql.html.
XML-QL
Alin Deutsch, Mary Fernandez, Daniela Florescu, Alon Levy, and Dan Suciu. A Query Language for XML. See http://www.research.att.com/~mff/files/final.html
SQL
International Organization for Standardization (ISO). Information Technology-Database Language SQL. Standard No. ISO/IEC 9075:1999. (Available from American National Standards Institute, New York, NY 10036, (212) 642-4900.)
ODMG
Rick Cattell et al. The Object Database Standard: ODMG-93, Release 1.2. Morgan Kaufmann Publishers, San Francisco, 1996.
Lorel
Serge Abiteboul, Dallan Quass, Jason McHugh, Jennifer Widom, and Janet L. Wiener. The Lorel Query Language for Semistructured Data. International Journal on Digital Libraries, 1(1):68-88, April 1997. See "http://www-db.stanford.edu/~widom/pubs.html
YATL
S. Cluet, S. Jacqmin, and J. Simeon. The New YATL: Design and Specifications. Technical Report, INRIA, 1999.
Quilt
Don Chamberlin, Jonathan Robie, and Daniela Florescu. Quilt: an XML Query Language for Heterogeneous Data Sources. In Lecture Notes in Computer Science, Springer-Verlag, Dec. 2000. Also available at http://www.almaden.ibm.com/cs/people/chamberlin/quilt_lncs.pdf. See also http://www.almaden.ibm.com/cs/people/chamberlin/quilt.html.
XPath 1.0
World Wide Web Consortium. XML Path Language (XPath) Version 1.0. W3C Recommendation, Nov. 16, 1999. See http://www.w3.org/TR/xpath.html

D.4 Informative Material

RFC2396
T. Berners-Lee, R. Fielding, and L. Masinter. Uniform Resource Identifiers (URI): Generic Syntax. IETF RFC 2396. See http://www.ietf.org/rfc/rfc2396.txt.
Character Model
World Wide Web Consortium. Character Model for the World Wide Web. W3C Working Draft. See http://www.w3.org/TR/charmod/
XML Infoset
World Wide Web Consortium. XML Information Set. W3C Recommendation 24 October 2001. See http://www.w3.org/TR/xml-infoset/
XPointer
World Wide Web Consortium. XML Pointer Language (XPointer). W3C Last Call Working Draft 8 January 2001. See http://www.w3.org/TR/WD-xptr
XSLT 1.0
World Wide Web Consortium. XSL Transformations (XSLT) 1.0. W3C Recommendation. See http://www.w3.org/TR/xslt

E Glossary

accessible collections

Accessible collections. This is a mapping of strings onto sequences of nodes. The string represents the absolute URI of a resource. The sequence of nodes represents the result of the fn:collection function when that URI is supplied as the argument.

accessible documents

Accessible documents. This is a mapping of strings onto document nodes. The string represents the absolute URI of a resource. The document node is the representation of that resource as an instance of the data model, as returned by the fn:doc function when applied to that URI.

active namespace

A namespace that is declared by a namespace declaration attribute in a direct element constructor, or by a computed namespace constructor inside a computed element constructor, is classified as an active namespace.

atomic value

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).

atomization

Atomization is applied to a value when the value is used in a context in which 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].

AttributeTest

An AttributeTest is used to match an attribute node by its name and/or type.

base URI

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

context item

The context item is the item currently being processed in a path expression. An item is either an atomic value or a node.

context node

When the context item is a node, it can also be referred to as the context node.

context position

The context position is the position of the context item within the sequence of items currently being processed in a path expression.

context size

The context size is the number of items in the sequence of items currently being processed in a path expression.

current date and time

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.

data model

XQuery operates on the abstract, logical structure of an XML document, rather than its surface syntax. This logical structure is known as the data model, which is defined in the [XQuery 1.0 and XPath 2.0 Data Model] document.

default collation

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

default element/type namespace

Default element/type 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

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. The initial default function namespace may be provided by the external environmentor by a declaration in the Prolog of a module.

document order

Document order defines a total ordering among all the nodes seen by the language processor and is defined formally in the data model.

dynamic context

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

dynamic error

A dynamic error is an error that must be detected during the evaluation phase and may be detected during the analysis phase. Numeric overflow is an example of a dynamic error.

dynamic evaluation phase

The dynamic evaluation phase is performed only after successful completion of the static analysis phase. The dynamic evaluation phase depends on the operation tree of the expression being evaluated (step DQ1), on the input data (step DQ4), and on the dynamic context (step DQ5), which in turn draws information from the external environment (step DQ3) and the static context (step DQ2).

dynamic type

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 evaluation time its value may have the dynamic type "integer.")

Dynamic variables

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. The QName is the name of the variable and the value is the dynamic value of the variable.

effective boolean value

The effective boolean value of a value is defined as the result of applying the fn:boolean function to the value, as defined in [XQuery 1.0 and XPath 2.0 Functions and Operators].

ElementTest

An ElementTest is used to match an element node by its name and/or type.

empty sequence

A sequence containing zero items is called an empty sequence.

error value

An error value is a single item or the empty sequence.

expression context

The expression context for a given expression consists of all the information that can affect the result of the expression.

external function

External functions are functions that are implemented outside the query environment.

focus

The first three components of the dynamic context (context item, context position, and context size) are called the focus of the expression.

functional langauge

XQuery is a functional language which means that expressions can be nested with full generality. (However, unlike a pure functional language, it does not allow variable substitutability if the variable declaration contains construction of new nodes.)

function implementation

The function implementation enables the function to map instances of its parameter types into an instance of its result type. For a user-defined function, the function implementation is an XQuery expression. For an external function, the function implementation is implementation dependent.

function signature

The function signature specifies the name of the function and the static types of its parameters and its result.

implementation defined

Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementor for each particular implementation.

implementation dependent

Implementation-dependent indicates an aspect that may differ between implementations, is not specified by this or any W3C specification, and is not required to be specified by the implementor for any particular implementation.

implicit timezone

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.

in-scope attribute declarations

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). If the Schema Import Feature is supported, in-scope attribute declarations include all attribute declarations found in imported schemas.

in-scope collations

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.

in-scope element declarations

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). 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 functions

In-scope functions. This component defines the set of functions that are available to be called from within an expression. Each function is uniquely identified by its expanded QName and its arity (number of parameters). Each function in in-scope functions has a function signature and a function implementation.

in-scope namespaces

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.

in-scope schema definitions

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.

in-scope type definitions

In-scope type definitions. The in-scope type definitions always include the predefined types listed in 2.1.1.1 Predefined Types. If the Schema Import Feature is supported, in-scope type definitions also include all type definitions found in imported schemas.

in-scope variables

In-scope variables. This is a set of (QName, type) pairs. It defines the set of variables that are available for reference within an expression. The QName is the name of the variable, and the type is the static type of the variable.

item

An item is either an atomic value or a node.

library module

A module that contains a module declaration followed by a Prolog is called a library module.

literal

A literal is a direct syntactic representation of an atomic value.

main module

A module that contains a Prolog followed by a Query Body is called a main module.

module

A module is a fragment of XQuery code that can independently undergo the analysis phase described in 2.2.3 Expression Processing

must understand

An implementation may extend XQuery functionality by supporting must-understand extensions. A must-understand extension may be used anywhere that ignorable whitespace is allowed.

node

A node is an instance of one of the seven node kinds described in [XQuery 1.0 and XPath 2.0 Data Model].

passive namespace

A namespace that is declared in the Prolog, or that is predefined in the static context, is classified as a passive namespace, except for the predefined xml namespace, which is classified as active.

pragma

A pragma may be used to provide additional information to an XQuery implementation.

primary expression

Primary expressions are the basic primitives of the language. They include literals, variables, function calls, constructors, and the use of parentheses to control precedence of operators.

Prolog

The Prolog is a series of declarations and imports that create the environment for query processing.

query body

The Query Body, if present, consists of an expression that defines the result of the query.

sequence

A sequence is an ordered collection of zero or more items.

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 matching

During evaluation 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.

serialization

Serialization is the process of converting an instance of the [XQuery 1.0 and XPath 2.0 Data Model] into a sequence of octets (step DM4 in Figure 1.)

singleton sequence

A sequence containing exactly one item is called a singleton sequence.

statically-known collections

Statically-known collections. This is a mapping from strings onto types. The string represents the absolute URI of a resource that is potentially accessible using the fn:collection function. The type is the type of the sequence of nodes that would result from calling the fn:collection function with this URI as its argument.

statically-known documents

Statically-known documents. This is a mapping from strings onto types. The string represents the absolute URI of a resource that is potentially accessible using the fn:doc function. The type is the type of the document node that would result from calling the fn:doc function with this URI as its argument.

static analysis phase

The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on any input data.

static context

The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation.

static error

A static error is an error that must be detected during the analysis phase. A syntax error is an example of a static error. The means by which static errors are reported during the analysis phase is implementation defined.

static type

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 and XPath 2.0 Formal Semantics].

Static Typing Feature

An XQuery implementation that does not support the Static Typing Feature is not required to raise type errors during the static analysis phase.

string value

The string value of a node is a string and can be extracted by applying the the fn:string function to the node. The string value for each kind of node is defined by the dm:string-value accessor in [XQuery 1.0 and XPath 2.0 Data Model].

strongly typed

XQuery is also a strongly-typed language in which the operands of various expressions, operators, and functions must conform to the expected types.

type annotation

Element and attribute nodes have a type annotation, which represents (in an implementation-dependent way) the dynamic (run-time) type of the node.

typed value

The typed value of a node is a sequence of atomic values and can be extracted by applying the fn:data function to the node. The typed value for each kind of node is defined by the dm:typed-value accessor in [XQuery 1.0 and XPath 2.0 Data Model].

type error

A type error may be raised during the analysis or evaluation phase. During the analysis phase, a type error occurs when the static type of an expression does not match the expected type of the context in which the expression occurs. During the evaluation phase, a type error occurs when the dynamic type of a value does not match the expected type of the context in which the value occurs.

user-defined function

For a user-defined function, the function declaration includes an expression called the function body that defines how the result of the function is computed from its parameters.

validation context

Validation context. An expression's validation context determines the context in which elements constructed by the expression are validated.

validation mode

Validation mode. The validation mode specifies the mode in which validation is performed by element constructors and by validate expressions.

XML space policy

XMLSpace policy. This policy, declared in the Prolog, controls the processing of whitespace by element constructors.

XPath 1.0 compatibility mode

XPath 1.0 compatibility mode. This component must be set by all host languages that include XPath 2.0 as a subset, indicating whether rules for compatibility with XPath 1.0 are in effect. XQuery sets the value of this component to false.

XQuery Flagger

An XQuery Flagger is a facility that is provided by an implementation that is able to identify queries that contain must-understand extensions. If an implementation supports must-understand extensions, then an XQuery Flagger must be provided.

F Summary of Error Conditions

err:XP0001

It is a static error if analysis of an expression relies on some component of the static context that has not been assigned a value.

err:XP0002

It is a dynamic error if evaluation of an expression relies on some part of the dynamic context that has not been assigned a value.

err:XP0003

It is a static error if an expression is not a valid instance of the grammar defined in A.1 EBNF.

err:XQ0004

During the analysis phase, it is a type error if the static typing feature is in effect and an expression is found to have a static type that is not appropriate for the context in which the expression occurs.

err:XQ0005

During the analysis phase, it is a type error if the static typing feature is in effect and the static type assigned to an expression other than the expression () is the empty type.

err:XP0006

During the evaluation phase, it is a type error if a value does not match a required type as specified by the matching rules in 2.4.1.1 SequenceType Matching.

err:XP0007

It is a type error if the fn:data function is applied to a node whose type annotation denotes a complex type with non-mixed complex content.

err:XP0008

It is a static error if an expression refers to a type name, function name, namespace prefix, or variable name that is not defined in the static context.

err:XQ0009

An implementation that does not support the Schema Import Feature may raise a static error if a query prolog contains a schema import statement.

err:XQ0010

An implementation that does not support the Full Axis Feature may raise a static error if a path expression references an unsupported axis (ancestor, ancestor-or-self, following, following-sibling, preceding, or preceding-sibling).

err:XQ0012

If the Schema Import Feature is in effect, it is a static error if the set of definitions contained in all imported schemas do not satisfy the conditions for schema validity specified in Sections 3 and 5 of [XML Schema] Part 1. In particular, the definitions must be valid, they must be complete, and they must be unique -- that is, the pool of definitions must not contain two or more schema components with the same name and target namespace.

err:XQ0013

It is a static error if an implementation supports a pragma and the implementation determines that the PragmaContents are invalid.

err:XQ0014

It is a static error if an implementation does not support a must-understand extension or an implementation does support a must-understand extension and the implementation determines that the ExtensionContents are invalid.

err:XQ0015

It is a static error if the XQuery Flagger is enabled and the query contains a must-understand extension.

err:XP0016

It is a static error to reference a variable that is not in scope.

err:XP0017

It is a static error if the expanded QName and number of arguments in a function call do not match the name and arity of an in-scope function in the static context.

err:XP0018

It is a static error for an expression to depend on the focus when the focus is undefined.

err:XP0019

It is a type error if the result of a step expression (StepExpr) is not a sequence of nodes.

err:XP0020

It is a type error if in an axis expression, the context item is not a node.

err:XP0021

It is a dynamic error if a value in a cast expression cannot be cast to the required type.

err:XQ0022

It is a static error if the value of a namespace declaration attribute is not a literal string.

err:XQ0023

It is a type error if the content sequence in an element constructor contains a document node.

err:XQ0024

It is a type error if the content sequence in an element constructor contains an attribute node following a node that is not an attribute node or a namespace node.

err:XQ0025

It is a dynamic error if two or more attribute values in the content sequence of an element constructor have the same name.

err:XQ0026

In an element-constructor expression, it is a dynamic error if the validation mode is strict and the in-scope element declarations do not contain an element declaration whose unique name matches the name of the constructed element.

err:XQ0027

In an element-constructor or validate expression, it is a dynamic error if validation fails.

err:XQ0028

It is a type error if the content sequence in a document constructor contains a document, attribute, or namespace node.

err:XP0029

It is a dynamic error in a cast expression if the input value does not satisfy the facets of the target type.

err:XQ0030

It is a type error if the argument of a validate expression does not evaluate to exactly one document or element node.

err:XQ0031

It is a static error if the version number specified in a version declaration is not supported by the implementation.

err:XQ0032

A static error is raised if the query prolog contains multiple declarations for the base URI.

err:XQ0033

It is a static error if the query prolog contains multiple declarations for the same namespace prefix.

err:XQ0034

It is a static error if more than one function declared or imported by a module has the same expanded QName.

err:XQ0035

It is a static error to import two schemas that both define the same name in the same symbol space and in the same scope.

err:XQ0036

It is a type error to import a module if the importing module's in-scope type definitions do not include definitions for the type names that appear in variable declarations, function parameters, or function returns found in the imported module.

err:XQ0037

It is a static error to import a module that contains function declarations or variable declarations whose names are already declared in the static context of the importing module.

err:XQ0038

It is a static error if a query prolog specifies more than one default collation, or value specified does not identify a collation known to the implementation.

err:XQ0039

It is an static error for a function declaration to have more than one parameter with the same name.

err:XQ0040

It is a type error if the content sequence in an element constructor contains a namespace node node following a node that is not a namespace node.

err:XQ0041

It is a dynamic error if the name expression in a computed processing instruction or computed namespace constructor returns a QName whose URI part is not empty.

err:XQ0042

It is a static error if the enclosing expression of a computed namespace constructor is not a computed element constructor.

err:XQ0043

It is a dynamic error if two or more computed namespace constructors within the same computed element constructor attempt to bind the same namespace prefix.

err:XQ0044

It is a dynamic error if the name expression of a computed attribute constructor returns a string that begins with the characters xmlns.

err:XQ0045

It is a static error if the declared function name in a function declaration has no namespace prefix or has one of the predefined namespace prefixes other than local.

err:XQ0046

It is a static error if the URI in a namespace declaration or default namespace declaration is not a valid URI. In addition, the URI in a (non-default) namespace declaration may not be a zero-length string.

err:XQ0047

It is a static error if the target URI (and location hint, if present) in a module import do not identify an accessible module.

err:XQ0048

It is a static error if a function or variable declared in a library module is not in the target namespace of the library module.

err:XQ0049

It is a static error if more than one variable declared or imported by a module has the same expanded QName.

err:XP0050

It is a dynamic error if dynamic type of the operand of a treat expression does not match the type specified by the treat expression.

G Example Applications (Non-Normative)

This section contains examples of several important classes of queries that can be expressed using XQuery. The applications described here include joins across multiple data sources, grouping and aggregation, queries based on sequential relationships, and recursive transformations.

G.1 Joins

Joins, which combine data from multiple sources into a single result, are a very important type of query. In this section we will illustrate how several types of joins can be expressed in XQuery. We will base our examples on the following three documents:

  1. A document named parts.xml that contains many part elements; each part element in turn contains partno and description subelements.

  2. A document named suppliers.xml that contains many supplier elements; each supplier element in turn contains suppno and suppname subelements.

  3. A document named catalog.xml that contains information about the relationships between suppliers and parts. The catalog document contains many item elements, each of which in turn contains partno, suppno, and price subelements.

A conventional ("inner") join returns information from two or more related sources, as illustrated by the following example, which combines information from three documents. The example generates a "descriptive catalog" derived from the catalog document, but containing part descriptions instead of part numbers and supplier names instead of supplier numbers. The new catalog is ordered alphabetically by part description and secondarily by supplier name.

<descriptive-catalog>
   { 
     for $i in doc("catalog.xml")//item,
         $p in doc("parts.xml")//part[partno = $i/partno],
         $s in doc("suppliers.xml")//supplier[suppno = $i/suppno]
     order by $p/description, $s/suppname
     return
        <item>
           {
           $p/description,
           $s/suppname,
           $i/price
           }
        </item>
   }
</descriptive-catalog>

The previous query returns information only about parts that have suppliers and suppliers that have parts. An outer join is a join that preserves information from one or more of the participating sources, including elements that have no matching element in the other source. For example, a left outer join between suppliers and parts might return information about suppliers that have no matching parts.

The following query demonstrates a left outer join. It returns names of all the suppliers in alphabetic order, including those that supply no parts. In the result, each supplier element contains the descriptions of all the parts it supplies, in alphabetic order.

for $s in doc("suppliers.xml")//supplier
order by $s/suppname
return
   <supplier>
      { 
        $s/suppname,
        for $i in doc("catalog.xml")//item
                 [suppno = $s/suppno],
            $p in doc("parts.xml")//part
                 [partno = $i/pno]
        order by $p/description
        return $p/description 
      }
   </supplier>

The previous query preserves information about suppliers that supply no parts. Another type of join, called a full outer join, might be used to preserve information about both suppliers that supply no parts and parts that have no supplier. The result of a full outer join can be structured in any of several ways. The following query generates a list of supplier elements, each containing nested part elements for the parts that it supplies (if any), followed by a list of part elements for the parts that have no supplier. This might be thought of as a "supplier-centered" full outer join. Other forms of outer join queries are also possible.

<master-list>
 {
    for $s in doc("suppliers.xml")//supplier
    order by $s/suppname
    return
        <supplier>
           { 
             $s/suppname,
             for $i in doc("catalog.xml")//item
                     [suppno = $s/suppno],
                 $p in doc("parts.xml")//part
                     [partno = $i/partno]
             order by $p/description
             return
                <part>
                   {
                     $p/description,
                     $i/price
                   }
                </part> 
           }
        </supplier> 
    ,
    (: parts that have no supplier :)
    <orphan-parts>
       { for $p in doc("parts.xml")//part
         where empty(doc("catalog.xml")//item
               [partno = $p/partno] )
         order by $p/description
         return $p/description 
       }
    </orphan-parts>
 }
</master-list>

The previous query uses an element constructor to enclose its output inside a master-list element. The concatenation operator (",") is used to combine the two main parts of the query. The result is an ordered sequence of supplier elements followed by an orphan-parts element that contains descriptions of all the parts that have no supplier.

G.2 Grouping

Many queries involve forming data into groups and applying some aggregation function such as count or avg to each group. The following example shows how such a query might be expressed in XQuery, using the catalog document defined in the previous section.

This query finds the part number and average price for parts that have at least 3 suppliers.

for $pn in distinct-values(doc("catalog.xml")//partno)
let $i := doc("catalog.xml")//item[partno = $pn]
where count($i) >= 3
order by $pn
return 
   <well-supplied-item>
      <partno> {$p} </partno>
      <avgprice> {avg($i/price)} </avgprice>
   </well-supplied-item>

The distinct-values function in this query eliminates duplicate part numbers from the set of all part numbers in the catalog document. The result of distinct-values is a sequence in which order is not significant.

Note that $pn, bound by a for clause, represents an individual part number, whereas $i, bound by a let clause, represents a set of items which serves as argument to the aggregate functions count($i) and avg($i/price). The query uses an element constructor to enclose each part number and average price in a containing element called well-supplied-item.

The method illustrated above generalizes easily to grouping by more than one data value. For example, consider a census document containing a sequence of person elements, each with subelements named state, job, and income. A census analyst might need to prepare a report listing the average income for each combination of state and job. This report might be produced using the following query:

for $s in distinct-values(doc("census.xml")//state),
    $j in distinct-values(doc("census.xml")//job)
let $p := doc("census.xml")//person[state = $s and job = $j]
order by $s, $j
return 
   if (exists($p)) then
      <group>
         <state> {$s} </state>
         <job> {$j} </job>
         <avgincome> {avg($p/income)} </avgincome>
      </group>
   else ()

The if-then-else expression in the above example prevents generation of groups that contain no data. For example, the census data may contain some persons who live in Nebraska, and some persons whose job is Deep Sea Fisherman, but no persons who live in Nebraska and have the job of Deep Sea Fisherman. If output groups are desired for all possible combinations of states and jobs, the if-then-else expression can be omitted from the query. In this case, the output may include "empty" groups such as the following:

<group>
   <state>Nebraska</state>
   <job>Deep Sea Fisherman</state>
   <avgincome/>
</group>

G.3 Queries on Sequence

XQuery uses the << and >> operators to compare nodes based on document order. Although these operators are quite simple, they can be used to express complex queries for XML documents in which sequence is meaningful. The first two queries in this section involve a surgical report that contains procedure, incision, instrument, action, and anesthesia elements.

The following query returns all the action elements that occur between the first and second incision elements inside the first procedure. The original document order among these nodes is preserved in the result of the query.

let $proc := input()//procedure[1]
for $i in $proc//action
where $i >> ($proc//incision)[1]
   and $i << ($proc//incision)[2]
return $i

It is worth noting here that document order is defined in such a way that a node is considered to precede its descendants in document order. In the surgical report, an action is never part of an incision, but an instrument is. Since the >> operator is based on document order, the predicate $i >> ($proc//incision)[1] is true for any instrument element that is a descendant of the first incision element in the first procedure.

For some queries, it may be helpful to define a function that can test whether a node precedes another node without being its ancestor. The following function returns true if its first operand precedes its second operand but is not an ancestor of its second operand; otherwise it returns false:

declare function local:precedes($a as node(), $b as node()) 
   as boolean
   {
      $a << $b
        and
      empty($a//node() intersect $b) 
   };

Similarly, a local:follows function could be written:

declare function local:follows($a as node(), $b as node()) 
   as boolean
   {
      $a >> $b
        and
      empty($b//node() intersect $a) 
   };

Using the local:precedes function, we can write a query that finds instrument elements between the first two incisions, excluding from the query result any instrument that is a descendant of the first incision:

let $proc := input()//procedure[1]
for $i in $proc//instrument
where local:precedes(($proc//incision)[1], $i)
   and local:precedes($i, ($proc//incision)[2])
return $i

The following query reports incisions for which no prior anesthesia was recorded in the surgical report. Since an anesthesia is never part of an incision, we can use << instead of the less-efficient local:precedes function:

for $proc in input()//procedure
where some $i in $proc//incision satisfies
         empty($proc//anesthesia[. << $i])
return $proc

In some documents, particular sequences of elements may indicate a logical hierarchy. This is most commonly true of HTML. The following query returns the introduction of an XHTML document, wrapping it in a div element. In this example, we assume that an h2 element containing the text "Introduction" marks the beginning of the introduction, and the introduction continues until the next h2 or h1 element, or the end of the document, whichever comes first.

let $intro := input()//h2[text()="Introduction"],
    $next-h := input()//(h1|h2)[. >> $intro][1]
return
   <div>
     {
       $intro,
       if (empty($next-h))
         then //node()[. >> $intro]
         else //node()[. >> $intro and . << $next-h]
     }
   </div>

Note that the above query makes explicit the hierarchy that was implicit in the original document. In this example, we assume that the h2 element containing the text "Introduction" has no subelements.

G.4 Recursive Transformations

Occasionally it is necessary to scan over a hierarchy of elements, applying some transformation at each level of the hierarchy. In XQuery this can be accomplished by defining a recursive function. In this section we will present two examples of such recursive functions.

Suppose that we need to compute a table of contents for a given document by scanning over the document, retaining only elements named section or title, and preserving the hierarchical relationships among these elements. For each section, we retain subelements named section or title; but for each title, we retain the full content of the element. This might be accomplished by the following recursive function:

declare function local:sections-and-titles($n as node()) as node()?
   {
   if (local-name($n) = "section")
   then element
          { local-name($n) }
          { for $c in $n/* return local:sections-and-titles($c) }
   else if (local-name($n) = "title")
   then $n
   else ( )
   };

The "skeleton" of a given document, containing only its sections and titles, can then be obtained by invoking the local:sections-and-titles function on the root node of the document, as follows:

local:sections-and-titles(doc("cookbook.xml"))

As another example of a recursive transformation, suppose that we wish to scan over a document, transforming every attribute named color to an element named color, and every element named size to an attribute named size. This can be accomplished by the following recursive function:

declare function local:swizzle($n as node()) as node() 
  { 
   typeswitch($n)
     case $a as attribute(@color, *)
       return element color { string($a) } 
     case $es as element(size, *) 
       return attribute size { string($es) } 
     case $e as element() 
       return element 
         { local-name($e) } 
         { for $c in $e/(* | @*) return local:swizzle($c) } 
     case $d as document-node() 
       return document 
         { for $c in $d/* return local:swizzle($c) } 
     default return $n 
  };

The transformation can be applied to a whole document by invoking the local:swizzle function on the root node of the document, as follows:

local:swizzle(doc("plans.xml"))

H XPath 2.0 and XQuery 1.0 Issues (Non-Normative)

Values for Status has the following meaning:

resolved: a decision has been finalized and the document updated to reflect the decision.

decided: recommendations and decision(s) has been made by one or more of the following: a task-force, XPath WG, or XQuery WG.

draft: a proposal has been developed for possible future inclusion in a published document.

active: issue is actively being discussed.

unassigned: discussion of issue deferred.

subsumed: issue has been subsumed by another issue.

(parameters used: kwSort: cluster, kwFull: brief, kwDate: 00000000).


Num Cl Pr Cluster Status Locus Description Responsible
293 1 decided xquery Cdata and CharRef Semantics
444 1 decided formal-semantics Support for mixed content in the type system
96 o-1 (in)equality-operators decided xpath Normalized Equality
114 o-1 axes decided xquery XPath Axes
328 1 cdata section decided xquery What does CDATA section constructor construct?
257 D 1 collections decided xpath Does collection() always return same result?
561 1 conformance decided xpath Normativity of External Mappings
546 1 conformance-levels active xpath Are there more processing model options that could make sense as consistent features and thus as conformance levels?
286 1 constructor-expr decided xquery Element Construction vs Streaming
290 1 constructor-expr decided xquery Element Attribute Constructor Name Type
529 1 constructor-expr decided xquery Node identity in the formal semantics
329 1 constructors decided xquery Duplicate attribute constructors
258 D 2 documents decided xpath Identity of Document Nodes
554 1 editorial active xpath What is the really normative text?
339 2 errors decided xquery Error type for attributes constructed too late
340 1 errors decided xpath How to identify errors?
553 1 errors decided xpath Rules for reporting dynamic errors statically
563 1 errors decided xquery Is dynamic evaluation performed if error in static analysis?
317 1 extensions decided xquery XQuery Extension Mechanisms
538 1 extensions decided xquery Can (and should) keyword extensions be allowed in XQuery by equipping them with a namespace prefix?
272 1 external-functions decided xpath External Functions
273 1 external-objects decided xpath External Objects
555 1 formal semantics active formal-semantics Formal Semantics of Module Import
556 1 formal semantics active formal-semantics Formal Semantics of Variable Definitions
557 1 formal semantics active formal-semantics Formal semantics of Validation Declaration
559 1 formal semantics active formal-semantics New Sequence Type needs to be fully implemented in Formal Semantics
558 1 formal semantics decided formal-semantics The content of element types should always allow PI's and comment node types
560 1 formal semantics decided formal-semantics Exactness of Type Inference
335 1 formal-semantics decided xpath XPath/XQuery's current semantics greatly interferes with optimization
265 2 FTTF-xml:lang decided xpath-fulltext How do we determine the xml:lang for a node if it inherits xml:lang from a higher-level node?
266 2 FTTF-xml:lang decided xpath-fulltext Do we support the sublanguage portion of xml:lang?
124 o-1 functions decided xquery External Functions
157 o-1 functions decided xquery Function Libraries
327 1 functions decided xpath Evaluate unused function parameters?
223 o-1 functions external decided xquery We need a way to declare external functions
458 1 Language decided formal-semantics What is in the default context?
459 1 Language decided formal-semantics Serialization
492 1 Language decided formal-semantics Derivation by extension in XQuery
493 1 Language decided formal-semantics May the content of a text node be the empty string?
499 1 Language decided formal-semantics Casting and validation
510 1 Language decided formal-semantics Is validate working on sequences?
295 1 lexical-representation decided xquery Lexical Representation of Atomic Values
537 1 modules decided xquery What happens to imported schemas that are used in function signatures?
74 o-1 module-semantics decided xquery Module syntax
75 o-1 module-semantics decided xquery Importing Modules
79 o-1 module-syntax decided xquery Encoding
228 o-2 namespace functions decided xpath Should we keep the default function namespace, and the xf: namespace?
247 2 namespaces decided xpath What does default namespace(s) affect?
319 1 namespaces decided xquery Namespace definitions and in-scope namespaces
343 1 namespaces decided xpath Do functions in the null namespace clash with functions in the default namespace?
549 1 namespaces decided xquery Computed namespace-constructor
564 1 schema-import active xquery Loading same schema-component twice
528 1 semantics decided xpath Semantics of text constructor on empty sequence
481 1 Semantics active formal-semantics Semantics of Schema Context
496 1 Semantics active formal-semantics Support for lax and strict wildcards
437 1 Semantics decided formal-semantics Static type errors and warnings
441 1 Semantics decided formal-semantics Implementation of and conformance levels for static type checking
450 1 Semantics decided formal-semantics Semantics of data()
452 1 Semantics decided formal-semantics Semantics of order by
453 1 Semantics decided formal-semantics Semantics of element and attribute constructors
457 1 Semantics decided formal-semantics Dynamic context for current date and time
461 1 Semantics decided formal-semantics Data model syntax and literal values
473 1 Semantics decided formal-semantics When to process the query prolog
478 1 Semantics decided formal-semantics Semantics of special functions
479 1 Semantics decided formal-semantics Non-determinism in the semantics
482 1 Semantics decided formal-semantics Type equivalence rules
484 1 Semantics decided formal-semantics Treatment of nillability and xsi:nil
487 1 Semantics decided formal-semantics Representation of text nodes in formal values
491 1 Semantics decided formal-semantics Validation of an empty string against a string list
503 1 Semantics decided formal-semantics Collations in the static environment
508 1 Semantics decided formal-semantics Namespaces in element constructors
514 1 Semantics decided formal-semantics Raising errors
520 1 Semantics decided formal-semantics Coercion between untyped and atomic values
521 1 Semantics decided formal-semantics Semantics of XPath 1.0 compatibility
525 1 Semantics decided formal-semantics Static context accessible from the dynamic context
443 1 Semantics? active formal-semantics Namespace resolution
244 2 serialization decided xquery CDATA sections and serialization
155 o-1 sort decided xquery Sorting by Non-exposed Data
243 3 sort decided xpath Provide an example of sorting "disappearing"
251 2 sort decided xquery Sorting "input to loop", not the result
318 1 sort decided xquery Add 'order by' clause to FLWR?
562 1 static typing decided formal-semantics What static typing for fn:root?
455 1 Static typing decided formal-semantics Typing for the typeswitch default clause
472 1 Static typing decided formal-semantics Static typing of union
475 1 Static typing decided formal-semantics Typing for descendant
488 1 Static typing decided formal-semantics Static typing of path expressions in the presence of derivation by extension
509 1 Static typing decided formal-semantics Static typing for validate
513 1 Static typing decided formal-semantics Imprecise static type of constructed elements
144 o-1 syntax decided xquery Escaping Quotes and Apostrophes
246 2 syntax decided xquery Nested XQuery comments allowed?
341 1 syntax decided xpath Problems with SequenceType
532 1 syntax decided xpath Alignment between path expressions and sequence types
535 1 syntax decided xpath Lexical state tables
547 1 syntax decided xquery Use "declare" for declarations
548 1 syntax decided xpath Lexical Rules: states normative?
550 1 syntax decided xquery Location of Comments
552 1 syntax decided xpath Should the quotes in processing-instruction("...") be optional?
307 T 1 types active xpath Schema Types from input documents?
206 T 2 types decided xpath Typing support in XPath
224 T 2 types decided xquery Why do we want to allow optional returns and DataType?
297 T 1 types decided xpath Should XPath have "type binding" in variable?
306 T 1 types decided xpath PSVI to Data Model mapping part of normative text?
308 T 1 types decided xpath Type Soundness
310 T 1 types decided xquery Are the children of a newly constructed element typed?
316 T 1 types decided xpath Is anySimpleType = anySimpleType*?
320 T 1 types decided xquery Should different conformance levels give the same result for the same query and data?
325 T 1 types decided xpath Refering to element that is not in the in-scope schema def.
526 1 types decided xpath Semantics for anySimpleType and untypedAtomic
527 1 types decided formal-semantics Static typing of XPath index expressions
539 1 types decided formal-semantics Semantics of fs:cast-untypedAtomic in backward compatibility mode
540 1 types decided formal-semantics How does the static semantics works in the case where the input types are unions?
551 1 types decided xpath Constructor functions for unprefixed user defined types
566 1 types decided xpath "treat" should work up and down type hierarchy
524 1 type semantics decided xpath Plural datatypes different from Singular *?
43 T 1 type-semantics decided xquery Defining Behavior for Well Formed, DTD, and Schema Documents
47 T 2 type-semantics decided xquery Subtype Substitutability
48 T 3 type-semantics decided algebra CASE not a subtype
279 T 1 type-semantics decided xpath Should there be a lightweight cast?
334 T 1 type-semantics decided xpath How are documents for which validation has failed processed?
523 1 type-semantics decided xpath input(), collection(), document(); validation semantics
531 1 type-semantics decided xquery Should discard the type of copied subelement
533 1 type-semantics decided formal-semantics Strict static typing for automatic coercion of untyped atomic to atomic values
534 1 type-semantics decided formal-semantics Semantics of function calls and notion of "expected type"
541 1 type-semantics decided formal-semantics Should it be a static error if an expression other than () has type empty?
542 1 type-semantics decided formal-semantics What should be the type of an attribute or element that is well-formed but not validated, or is validated in skip mode?
543 1 type-semantics decided xpath How can a path expression match elements in the substitution group of a given element?
544 1 type-semantics decided xpath How can a path expression match nodes of a given type?
56 T 3 type-syntax decided xquery Human-Readable Syntax for Types
446 1 Typing decided formal-semantics Complexity of interleaving
449 1 Typing decided formal-semantics Constraint on attribute and element content models
486 1 Typing decided formal-semantics Support for PI, comment and namespace nodes
501 1 Typing decided formal-semantics Support for XML Schema groups
516 1 Typing decided formal-semantics Typeswitch and type substitutability
519 1 Typing decided formal-semantics Type of document node
321 1 validate decided xquery Is validate strict or lax?
322 1 validate decided xquery "validate" strict/lax override?
530 1 validation decided xquery Default default validation mode
250 2 variables decided xquery Declaring Variables in Prolog
191 o-1 whitespace decided xquery Whitespace handling in element constructors
311 1 whitespace decided xquery Whitespace and Attribute Constructors
338 1 whitespace decided xquery Handling of whitespace and character references
152 o-1 xqueryx active xqueryx XML-based Syntax

293. cdata-charref-semantics: Cdata and CharRef Semantics

Locus: xquery Cluster: Priority: 1 Status: decided
Originator: Michael Rys
Cdata and CharRef Semantics

Description

The data model cannot represent CDATA or CharRef, since the Information Set looses this information.

Proposed Resolution

The XQuery document should make it clear that:

1. CDATA sections and CharRefs inside XQueries that are not embedded inside XML (which is what the XQuery document only talks about), are syntactic helps to write queries that otherwise would need entitization (in the case if CDATA sections) or a unicode input device (CharRefs).

2. Implementations can chose to use this information as serialization hints to preserve the CDATA and entitization.

Actual Resolution

Decision by: xquery on 2002-12-11 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0317.html (W3C-members only))

Decided to close, with document changes as described by Mike Kay in http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0095.html, including editorial comments.

444. FS-Issue-0101: Support for mixed content in the type system

Locus: formal-semantics Cluster: Priority: 1 Status: decided
Originator: FS Editors
Support for mixed content in the type system

Description

Support for mixed content in the type system is an open issue. This reopens issue [resolved issue #FS-Issue-0016]. Dealing with mixed content with interleaving raises complexity issue. See also #FS-Issue-0103.

Actual Resolution

Decision by: xsl on 2003-03-07 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0269.html (W3C-members only))Joint meeting

Decision by: xquery on 2003-03-07 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0269.html (W3C-members only))Joint meeting

The formal semantics is a specification of the behavior of an XQuery processor, not a recipe for implementation. The uses of interleaving in the specification are sufficiently restricted that a practical implementation can be written.

96. xquery-normalized-equality: Normalized Equality

Locus: xpath Cluster: (in)equality-operators Priority: o-1 Status: decided
Originator: Mary Fernandez
Normalized Equality

Description

When elements are compared, are comments and PIs considered in the comparison? How is whitespace handled? Do we need to allow more than one way to handle these in comparisons?

Actual Resolution

Decision by: xquery on 2002-09-04 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Sep/0078.html (W3C-members only))

Decision by: xsl on 2002-10-03 (http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Oct/0025.html (W3C-members only))The XSL WG is not agreeable to blessing this.

"When elements are compared, are comments and PIs considered in the comparison?": NO

"How is whitespace handled?": This depends on the whitespace in the instance as per the data model.

"Do we need to allow more than one way to handle these in comparisons?": NO, not in XPath 2.0/XQuery 1.0.

114. xquery-xpath-axes: XPath Axes

Locus: xquery Cluster: axes Priority: o-1 Status: decided
Originator: XQuery Editors
XPath Axes

Description

XPath supports 13 axes. The current Working Draft says that XQuery will support a subset of these axes, including at least those axes required by the abbreviated syntax. The definitive set of axes to be supported by XQuery has not yet been determined. In the current Working Draft, the examples use abbreviated syntax, but the grammar supports unabbreviated syntax.

For the axes required by the abbreviated syntax, should XQuery allow both the unabbreviated and abbreviated syntax? If we decide not to support additional axes, no new functionality would be added by supporting the unabbreviated syntax. Opinions vary as to whether the unabbreviated syntax is clearer.

Proposed Resolution

Text is in Working Draft 2001-11-28 sec 2.3.

Actual Resolution

Decision by: xsl on 2002-01-22 (http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Jan/0067.html (W3C-members only))

Decision by: xquery on 2002-01-23 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Jan/0345.html (W3C-members only))

Acceptance of text in December 2001 published Working Draft.

Decision by: xquery on 2002-07-17 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Jul/0329.html (W3C-members only)) Decided: additional axes will not be included in XQuery Version 1.

The XML Query WG has decided not to support the full set of XPath axes in Version 1. We are trying to keep XQuery small, and that means we want to avoid providing the same functionality in multiple ways unless there is a compelling reason to do so. We also felt that we could easily add the full set of axes in future versions if users clearly demand it.

Experienced XPath users leverage the full set of axes to express complex queries. In examining many XPath expressions, we have found that they can be expressed in XQuery using other features, often using FLWR expressions. The two different approaches use different idioms, and are based on different programming models. We decided not to try to support both models, because it increases the learning required to master the entire language, and increases the probability that distinct user communities will evolve, and they will have difficulty reading each other's queries.

Another reason for not supporting the axes in Version 1 is that they have a lot of semantics, and these can be a burden for an optimizer. An implementation may well be able to do precedes or follows efficiently without an efficient way to perform all the enumerations required by the axes. For instance, an implementation may be able to efficiently determine whether one node is before another node (which means it supports 'precedes' efficiently), yet still have no efficient way of listing all nodes that precede a given node in reverse order (which is required to support the 'preceding' axis). And these axes come in pairs, so an implementation must be able to enumerate the nodes in either document order or reverse document order. Interactions between forward and reverse axes can also be tricky for query optimizers.

We also note that it is easy to write a function library that mimics the axes.

Decision by: xquery on 2003-06-25 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0031.html (W3C-members only))

Consensus of the XQuery group to make all of the axes (minus namespace) optional as a set (all or nothing).

328. cdata-section: What does CDATA section constructor construct?

Locus: xquery Cluster: cdata section Priority: 1 Status: decided
Originator: Michael Kay
What does CDATA section constructor construct?

Description

Section 3.7.5 describes CDATA section constructor, but these cannot be represented in the data model.

Actual Resolution

Decision by: xquery on 2002-12-11 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0317.html (W3C-members only))

Decided to close, with document changes as described by Mike Kay in http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0095.html, including editorial comments.

257. collection-always-return-same: Does collection() always return same result?

Issue Class: D Locus: xpath Cluster: collections Priority: 1 Status: decided
Originator: XPath TF
Does collection() always return same result?

Description

Does collection() always return same result for the same URI? The same within the scope of a query/transformation? Are the nodes in the sequence identical?

Actual Resolution

Decision by: xpath-tf on 2002-10-16 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Oct/0278.html (W3C-members only))

Decision by: xquery on 2002-10-23 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Oct/0467.html (W3C-members only))

Decision by: xsl on 2002-10-31 (http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Nov/0004.html (W3C-members only))

It should return the same answer every time. Applies also to input(). We should use the same language as we use for document() and for current-dateTime().

561. normativity-external-internal-mapping: Normativity of External Mappings

Locus: xpath Cluster: conformance Priority: 1 Status: decided
Originator: Jonathan Robie
Normativity of External Mappings

Description

Our specifications describe three mappings between the Query Processing environment and the External Processing environment: (1) the Data Model provides optional mappings from a PSVI or Infoset to a Data Model Instance; (2) the Serialization specification provides optional mappings from a Data Model Instance to serialized XML; (3) the Formal Semantics provides optional mappings from an XML Schema to the In-Scope Schema Definitions.

How normative are these mappings?

The following alternatives seem plausible:

1. The mappings are purely informative.

2. Implementations may choose whether to conform to one or more of these mappings, which will be identified by name.

3. As an aid to conformance testing, implementations are required to support a mode in which these mappings are available as specified.

Are there other alternatives we should consider? What are the relative advantages of these approaches?

Actual Resolution

Decision by: xpath-tf on 2003-07-18 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Jul/0092.html (W3C-members only))

The mappings are non-normative.

546. conformance-levels: Are there more processing model options that could make sense as consistent features and thus as conformance levels?

Locus: xpath Cluster: conformance-levels Priority: 1 Status: active
Originator: Processing Model TF
Are there more processing model options that could make sense as consistent features and thus as conformance levels?

Description

Are there more processing model options that could make sense as consistent features and thus as conformance levels? What types can these "predefine" in the static context? Do these options have the desired/expected interoperability characteristics?

286. element-construction-vs-streaming: Element Construction vs Streaming

Locus: xquery Cluster: constructor-expr Priority: 1 Status: decided
Originator: Michael Rys
Element Construction vs Streaming

Description

The element construction rules in 2.8 make efficient streaming of element construction difficult/impossible. For example, we execute the following expression on a stream and serialize the result in a streaming processing (such as XSLT like applications):

<foo>{"foo", "bar", if (expr) then "baz" else <baz/>}</foo>

If expr is true, then this is serialized:

<foo>foo bar baz</foo>

If expr is false, then this is serialized: <foo>foobar<baz/></foo>

The implementation must cache up the "foo" and "bar" strings, just in case a sub-element node is constructed. If not, then I must insert a space between "foo" and "bar". This seems to contradict one of our explicit use scenarios in the XML Query Requirements (section 2.5).

Interactions and Input

Actual Resolution

Decision by: xquery on 2002-09-04 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Sep/0078.html (W3C-members only))

This issue has been addressed by the recent changes to the element constructor.

290. element-attribute-constructor-name-type: Element Attribute Constructor Name Type

Locus: xquery Cluster: constructor-expr Priority: 1 Status: decided
Originator: Michael Rys
Element Attribute Constructor Name Type

Description

Does the name expression on dynamically computed names in element/attribute constructors be of type QName without implicit cast from string, QName with implicit cast from string, or string?

Proposed Resolution

If the name is constructed by an expression, the expected type is xs:QName. Xs:string is in general implicitly cast to xs:QName (and xs:anyURI).

Proposed Resolution

(1) In Section 3.7.1 ("Direct Element Constructors"), modify the paragraph below the first example as follows:

"Unqualified element names used in a direct element constructor are implicitly qualified by the default namespace for element names. In a direct element constructor, the name used in the end tag must exactly match the name used in the corresponding start tag (including its prefix or absence of a prefix)."

(2) In Section 3.7.2.1 ("Computed Element Constructors"), add a new first paragraph as follows:

"The name expression of a computed element constructor is processed as follows:

1. If the name expression returns a QName, that QName is used as the name of the constructed element. If the QName returned by the name expression is unqualified, the name of the constructed element is in default namespace for element names.

2. If the name expression returns a string, that string is implicitly cast to a QName by using the fn:QName-in-context function with its $use-default parameter set to True. The resulting QName is used as the name of the constructed element.

3. If the name expression does not return a QName or a string, a dynamic error is raised."

(3) In Section 3.7.2.2 ("Computed Attribute Constructors"), add a new first paragraph as follows:

"The name expression of a computed attribute constructor is processed as follows:

1. If the name expression returns a QName, that QName is used as the name of the constructed attribute. If the QName returned by the name expression is unqualified, the name of the constructed attribute is in no namespace.

2. If the name expression returns a string, that string is implicitly cast to a QName by using the fn:QName-in-context function with its $use-default parameter set to True. The resulting QName is used as the name of the constructed attribute.

3. If the name expression does not return a QName or a string, a dynamic error is raised."

Actual Resolution

Decision by: x-editors on 2003-02-05 (http://lists.w3.org/Archives/Member/w3c-query-editors/2003Feb/0010.html (W3C-members only))

Decision by: xquery on 2003-02-12 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Feb/0242.html (W3C-members only))

Recommend Don's proposal as the closure of this issue.

529. node-identity-modeling: Node identity in the formal semantics

Locus: xquery Cluster: constructor-expr Priority: 1 Status: decided
Originator: Phil Wadler
Node identity in the formal semantics

Description

The fs currently does not model node identity. The position of the formal semantics editors is that a formal semantics need not model everything. So it is not absolutely required that we model node identity, though it would be desirable for us to do so, not least because a clear description of node identity may help clarify the semantics of update. The formal semantics should include a mode of node identity if time permits.

Actual Resolution

Decision by: xsl on 2003-03-07 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0269.html (W3C-members only))Joint meeting

Decision by: xquery on 2003-03-07 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0269.html (W3C-members only))Joint meeting

Decided to define node identity in the Formal Semantics. Required some editorial work to be done.

329. duplicate-attribute-constructors: Duplicate attribute constructors

Locus: xquery Cluster: constructors Priority: 1 Status: decided
Originator: Michael Kay
Duplicate attribute constructors

Description

If there are multiple constructors for the same attribute on an element; which one is taken or is it an error?

Actual Resolution

Decision by: xquery on 2002-12-11 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0317.html (W3C-members only))

Decided to make it an error for an element constructor to specify two attributes with the same name. Error to be documented in XQuery Section 3.7.4.1.

258. document-nodes-identity: Identity of Document Nodes

Issue Class: D Locus: xpath Cluster: documents Priority: 2 Status: decided
Originator: Jonathan Robie
Identity of Document Nodes

Description

Consider the following query:

        if (document("foo.com") == document("foo.com"))
                then <yep/>
                else <nope/>

I would like the following output:

        <yep/>

I think we can achieve this if we say that the URI of a resource is used as its identity. However, one resource can be identified by more than one URI. Suppose that "foo.com/here/there/hi.xml" and "file://c:/temp/limerick-tei.xml" refer to the same resource. What does the following return?

if (document("foo.com/here/there/hi.xml") ==
document("file://c:/temp/limerick-tei.xml"))
        then <yep/>
        else <nope/>

Should we simply use the URI of the parameter to establish identity and say that the two do not match? Should we make the result implementation-dependent?

Actual Resolution

Decision by: xpath-tf on 2002-10-16 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Oct/0278.html (W3C-members only))

Decision by: xquery on 2002-10-23 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Oct/0467.html (W3C-members only))

Decision by: xsl on 2002-10-31 (http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Nov/0004.html (W3C-members only))

This is already covered by the existing spec, but we may want to review the language as part of the actions for issue 257.

554. what-is-normative: What is the really normative text?

Locus: xpath Cluster: editorial Priority: 1 Status: active
Originator: XPath TF
What is the really normative text?

Description

Some normative material in XPath/XQuery specifications occurs in more than one location. The specifications need to be clear which of the replicated material is the unique normative definition to ensure ease of implementation and avoid conflicts.

Proposed Resolution

The language book(s) and the Formal Semantics book define together what the semantics of the XQuery 1.0 and XPath 2.0 languages is.

However, there is often duplication (the language book(s) using English while the FS book uses formal notations), and often one document is more specific than the other (for instance the static typing optional feature is mostly described in the FS document). In addition, despite all our hard work some inconsistencies are probably still lurking. Finally, we need to deal with the question about which part of the documents is going to be normative.

Here is a small proposal, laying out a plan to deal with those issues. This plan was discussed at last week's FS editors call, people liked it, and that I was actioned to write it down.

The proposal

(1) For all expressions in the language, the language book should clearly specify in English prose the dynamic semantics of the expression. This English text will serve as the normative version for the dynamic semantics.

(2) For all expressions, the formal semantics book should have dynamic rules which align with (1) above.

(3) For all expressions in the language, the corresponding section in the language book should point to the corresponding FS section which contain the formal rules.

(4) For all expressions, the formal semantics book should have static rules which specify the static semantics of the language. Those formal rules will serve as the normative version for the static semantics.

This plan will obviously require some significant work on our documents, but we believed this would solve all of our alignment/normative problems and improve the quality of our specifications.

Actual Resolution

Decision by: xpath-tf on 2003-05-14 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003May/0037.html (W3C-members only))

Decision by: xsl on 2003-05-16 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0176.html (W3C-members only))Joint F2F

Decision by: xquery on 2003-05-16 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0176.html (W3C-members only))Joint F2F

Accepting this general approach and the details with respect to the Formal Semantics. Similar to be worked out for the

"language books" and Datamodel

"language books" and Functions and Operators

Functions and Operators and Formal Semantics

The links that we will put into the documents need to be bi-directional.

339. element-attribute-construction-order: Error type for attributes constructed too late

Locus: xquery Cluster: errors Priority: 2 Status: decided
Originator: Don Chamberlin
Error type for attributes constructed too late

Description

What kind of error should be raised by an element constructor in which an attribute is encountered after other element content?

Actual Resolution

Decision by: xquery on 2002-12-11 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Dec/0317.html (W3C-members only))

This a type error. Type error to be documented in XQuery Section 3.7.2.

340. errors-unique-identification: How to identify errors?

Locus: xpath Cluster: errors Priority: 1 Status: decided
Originator: XPath TF
How to identify errors?

Description

How should we allocate codes or identifiers to errors defined in the spec? We should not use "explanatory sentences" as these are not appropriate for I18N reasons.

Actual Resolution

Decision by: xpath-tf on 2002-12-17 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Dec/0252.html (W3C-members only))

Decision by: xquery on 2002-12-19 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jan/0167.html (W3C-members only))Joint F2F

Decision by: xsl on 2002-12-19 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jan/0167.html (W3C-members only))Joint F2F

(not really an issue); Ashok and Norm will investigate whether we can editorially markup errors consistently.

Decision by: xpath-tf on 2003-01-07 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Jan/0101.html (W3C-members only))

Issue should remain open pending proposal on: ACTION XPATH-091-11 Mary adds herself to XPATH-091-11.

Decision by: xpath-tf on 2003-04-08 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Apr/0075.html (W3C-members only))

1. All occurrences of static and dynamic errors should be identified in the F&O, DM, language, and FS specs using distinguished error markup.

2. Error markup should include unique alpha-numeric identifier for each error which permits the source to refer to unique error definitions and to include reverse indices on errors.

3. In first cut, alpha-numeric error codes will not be revealed in printed documents, but we can reveal them at a later time if we decide to make error codes part of conformance requirements.

4. Until we consider an API for conveying errors to the evaluation environment, we recommend *not* requiring implementations to return specific error codes (and possibly additional context info such as location of error in query body or name of built-in function, etc.)

Decision by: xquery on 2003-04-16 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Apr/0247.html (W3C-members only)) with amendment: instead of tying the codes to conformance, we are suggesting to publish these in a non-normative appendix so implementers can use them if see fit

Decision by: xquery on 2003-04-30 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0007.html (W3C-members only))

The XML Query WG has agreed that errors be identified with a code and and some English text as recommended by the I18N folks. The XSL WG has not discussed this yet.

The markup suggested for errors:

        <error id="code> English text </error>

seems fine, but we need to decide how to assign the codes.

Jim Melton suggessted 5 or 6 digit fixed length codes partitioned in some manner to indicate the type of error: http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Apr/0259.html

Liam Quin suggested words separated by hyphens: http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Apr/0267.html

Mike Kay would like them to be QNames: unprefixed in the case of codes defined by W3C, namespace-prefixed in the case of implementation-defined or user-defined codes. See http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Apr/0284.html

SUGGESTION ON HOW TO MOVE FORWARD Since the error codes will encompass the language documents, the F&O and possibly the formal semantics we need folks representing all these constituencies to decide on the structure of the error codes and how to partition them. I suggest a small task force to address this. This taskforce would also address the issue of the non-normative appendix and where it should reside.

553. dynamic-errors-reported-statically: Rules for reporting dynamic errors statically

Locus: xpath Cluster: errors Priority: 1 Status: decided
Originator: XSL WG
Rules for reporting dynamic errors statically

Description

Under what circumstances can a dynamic error detected early be reported statically, for example if it occurs in code that might not be executed. A host language may determine this, e.g. an <xsl:if> construct.

Interactions and Input

Actual Resolution

Decision by: xsl on 2003-05-16 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0176.html (W3C-members only))Joint F2F

Decision by: xquery on 2003-05-16 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0176.html (W3C-members only))Joint F2F

As just a minor addition to the doc is needed and the other addition is the raise of the following other error: a constructor function with a constant argument that is not in the lexical space it was decided to close this issue.

Decision by: xpath-tf on 2003-07-08 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Jul/0032.html (W3C-members only))

Adopted the actual text in http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Jun/0087.html.

Decision by: xquery on 2003-07-15 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0122.html (W3C-members only))Joint meeting.

Decision by: xsl on 2003-07-15 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0122.html (W3C-members only))Joint meeting.

Wording reviewed and accepted.

563. static-error-evaluate-dynamically: Is dynamic evaluation performed if error in static analysis?

Locus: xquery Cluster: errors Priority: 1 Status: decided
Originator: Michael Rys
Is dynamic evaluation performed if error in static analysis?

Description

Is the dynamic evaluation phase performed only after successful completion of the static analysis phase or whether it can continue even after a static type error.

Proposed Resolution

Proposed Resolution: allowing to continue after static type error can be considered a dynamic typing implementation with a static typing compiler flag (like C's lint). Reason: You would still need to perform dynamic typing. Such an implementation should be possible but not required or even described by the spec.

Proposed Resolution

Proposed resolution:

In 2.2.3.2 Dynamic Evaluation Phase, change current text:

<current_text> The dynamic evaluation phase is performed only after successful completion of the static analysis phase. </current_text>

to:

<new_text> The dynamic evaluation phase occurs after the static analysis phase only if the static analysis phase does not raise any non-type static errors. <xquery_only> If the Static Typing Feature is in effect, dynamic evaluation occurs only if the static analysis phase does not raise any static (non-type and type) errors. </new_text>

Rationale: In the absence of static typing, all type errors must be detected dynamically. Thus, even if a type error is detected statically, it should not prevent dynamic evaluation. However, when static typing is in effect, *all* type errors are static errors, thus any static error should prevent dynamic evaluation.

This resolution requires that static typing behave as it does in other high-level languages. If an implementor wants to provide a "lint-like" feature, they can do so by optionally reporting type errors during static analysis.

Actual Resolution

Decision by: xquery on 2003-07-15 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0122.html (W3C-members only))

Mary's text adopted.

317. extension-mechanism: XQuery Extension Mechanisms

Locus: xquery Cluster: extensions Priority: 1 Status: decided
Originator: Andrew Eisenberg
XQuery Extension Mechanisms

Description

Issue: XQuery has not determined what extension mechanisms might be supported. XQuery may support the following:

  • implementation-defined extensions to the XQuery grammar
  • an XQuery-flagger that identifies extensions to XQuery 1.0
  • implementation-defined extensions to the functions that are available to
  • an XQuery author. The author would be required to explicitly declare the
  • namespaces of any extension functions that are used

Interactions and Input

Proposed Resolution

This proposal adds the following to the XQuery language document (in
section 2.5 Errors and Conformance):


2.5.5 Extensions

Conforming XQuery implementations are permitted to make two different kinds
of extensions to the specifications: grammar extensions and semantic
extensions. There are two types of grammar extensions: pragmas and
must-understand extensions. While an XQuery implementation may support some
or all of these types of extensions, this does not negate the requirement
to support the XQuery functionality defined in this specification.


2.5.5.1 Pragmas

A pragma may be used to provide additional information to an XQuery
implementation.

[x1]  Pragma            ::=   "(::" "pragma" PragmaQName PragmaContents
"::)"

[x2]  PragmaQName       ::=   ExplicitQName

[x3]  ExplicitQName     ::=   QName

[x4]  PragmaContents    ::=   .*

An ExplicitQName requires that QName contain a Prefix. Pragmas may be used
anywhere that ignorable whitespace is allowed, and within element content.
See A.1 Lexical structure for the exact lexical states where pragmas are
recognized. A pragma is identified by its PragmaQName.

If an implementation does not support a pragma, then that pragma shall be
ignored. If an implementation does support a pragma and the implementation
determines that the PragmaContents are invalid, then a static error is
raised. Otherwise, the effect of the pragma on the result of the Query is
implementation-defined.

The following example shows how a pragma might be used:

   declare namespace exq = "http://example.org/XQueryImplementation"

   (:: pragma exq:timeout 1000 ::)

   count(input()//author)

An implementation that supports the exq:timeout pragma might raise a
dynamic  error if it is unable to count the authors within 1000 seconds. An
implementation that did not support this pragma would execute as long as
necessary to count the authors.


2.5.5.2 Must-Understand Extensions

An implementation may extend the XQuery grammar by supporting
must-understand extensions.

[y1]  MustUnderstandExtension ::=
            "(::" "extension" ExtensionQName ExtensionContents "::)"

[y2]  ExtensionQName          ::=   ExplicitQName

[y3]  ExtensionContents ::=   .*

A MustUnderstandExtension may be used anywhere that ignorable whitespace is
allowed, and within element content. See A.1 Lexical structure for the
exact lexical states where pragmas are recognized. A must-understand
extension is identified by its ExtensionQName.

If an implementation does not support a must-understand extension, then a
static error is raised. If an implementation does support an
must-understand extension and the implementation determines that the
ExtensionContents are invalid, then a static error is raised. Otherwise,
the effect of the must-understand extension on the result of the Query
being executed is implementation-defined.

The following example shows how a must-understand extension might be used:

   declare namespace exq = "http://example.org/XQueryImplementation"

   for $e in doc("employees.xml")//employee
   order by $e/lastname (:: extension exq:RightToLeft ::)
   return $e

An implementation that supports the exq:RightToLeft must-understand
extension might order the last names by examining characters from right to
left instead of left to right. An implementation that did not support this
must-understand extension would raise a static error.


2.5.5.3 Semantic Extensions

An implementation may extend XQuery by supporting semantic extensions. A
semantic extension allows a conforming Query to be processed in a
non-conforming way. The way in which such semantic extensions are enabled
is implementation-defined.

The effect of a semantic extension on the result of a Query is
implementation-defined.

The following example shows how a command line might be used to enable a
semantic extension:

   xquery q12.xquery
   98

   xquery q12.xquery -EmptyIdentity=on
   100

The execution of the query contained in q12.xquery might treat an empty
sequence as 0 when it is being used in addition and subtraction and treat
it as 1 when it is being used in multiplication and division.


2.5.5.4 XQuery Flagger

An XQuery Flagger is a facility that is provided by an implementation that
is able to identify queries that contain extensions other than pragmas. If
an implementation supports extensions other than pragmas, then an XQuery
Flagger must be provided. The XQuery Flagger is disabled by default; the
mechanism by which the XQuery Flagger is enabled is implementation-defined.
When enabled, the XQuery Flagger will raise a static error for an otherwise
valid Query that contains either must-understand extensions or semantic
extensions.

An XQuery Flagger is provided to assist programmers in producing queries
that are portable among multiple conforming XQuery implementations.

The following examples show how an XQuery Flagger might be used:

   xquery q10.xquery
   <employee> ... </employee>

   xquery q10.xquery -Flagger=on
   [static error] A must-understand extension is being used:
   exq:RightToLeft

   xquery q12.xquery -EmptyIdentity=on
   100

   xquery q12.xquery -EmptyIdentity=on -Flagger=on
   [static error] A semantic extension is being used: EmptyIdentity

Updates to proposal:

- Usage of (:: ::) syntax.

- must-understand extension.

Actual Resolution

Decision by: xquery on 2003-03-12 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0232.html (W3C-members only))

#1 PRAGMAS: Adopted Unanimously.

#2 MUST-UNDERSTAND EXTENSIONS: Adopted.

#3 SEMANTIC EXTENSIONS: Rejected.

#4 FLAGGER: Adopted.

538. keyword-extensions: Can (and should) keyword extensions be allowed in XQuery by equipping them with a namespace prefix?

Locus: xquery Cluster: extensions Priority: 1 Status: decided
Originator: Peter Fankhauser
Can (and should) keyword extensions be allowed in XQuery by equipping them with a namespace prefix?

Description

Can (and should) keyword extensions be allowed in XQuery by equipping them with a namespace prefix?

Example:

declare namespace my = http://example.com/myextensions

for $e in document ("employees.xml")//employee
order by $e/lastname my:fastorder
return $e

The advantage of this is that namespaces are a well-established concept for extending vocabularies, and different prefixes may be used for multiple extensions (my:fastorder vs. real:fastorder). The possible disadvantage may be that namespaces are regarded as too clumsy for this purpose.

Note that using namespaces for keyword extensions does not appear to provide a generic mechanism to make the XQuery grammar extensible (one cannot simply allow a sequence of Qnames at arbitrary places without running into ambiguities). An implementation providing some extensions still needs to modify the XQuery grammar accordingly. However this also holds for the other two options, unless "x-" is added to the reserved keywords.

Interactions and Input

Actual Resolution

Decision by: xquery on 2003-03-12 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0232.html (W3C-members only))

The decision for #extension-mechanism also covers this issue.

272. external-functions: External Functions

Locus: xpath Cluster: external-functions Priority: 1 Status: decided
Originator: Michael Kay
External Functions

Description

The ability to call external functions is an established feature of XSLT 1.0, and is retained in XSLT 2.0. The facility is widely used, and some significant libraries of external functions have been developed by third parties. We made an attempt to standardize language bindings for external functions in the XSLT 1.1 working draft, but this proved highly controversial and has been dropped. The facility remains, however, even though the binding mechanisms remain implementation-defined.

The XPath 2.0 specification continues to tolerate external functions, though it doesn't really acknowledge their existence properly. All we say is that the repertoire of functions that can be called is part of the context.

The issue is: should the function function-available() function be transferred from XSLT to XPath?

This function tests whether a named function is available, and returns true if it is, and false if it isn't. A typical call is:

if  (function-available('my:debug')) then my:debug('Hi!') else ()

This has two implications:

(a) a call on my:debug must not be a static error if the function is not available

(b) the names of functions (and the in-scope namespaces needed to resolve their QNames) must be available at run-time.

Logically the function-available() function has no dependencies on XSLT so it should be transferred to XPath.

Actual Resolution

Decision by: xpath-tf on 2002-12-10 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Dec/0164.html (W3C-members only))

Proposed to resolve by stating that the XPath specification to state that at the discretion of the host language, a call to a function that is not in the static context may generate a dynamic error rather than a static error.

Decision by: xquery on 2003-02-26 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Feb/0459.html (W3C-members only))

This issue is also impacted by the following decision:

Decided to adopt 1B and 2A in proposal for issue #xquery-module-syntax.

273. external-objests: External Objects

Locus: xpath Cluster: external-objects Priority: 1 Status: decided
Originator: Michael Kay
External Objects

Description

Part of the strength of external functions is that they can return objects that are outside the scope of the XPath type system. For example, a function library for performing SQL database access may have a function sql:connect() that returns an object representing a database connection. This object may be passed as an argument to calls on other functions in the SQL function library.

The way this is handled in XPath 1.0 is that the XPath specification defines four data-types, and explicitly leaves the host language free to define additional data types. We could probably live with a similar solution for XPath 2.0, but it's a fudge, and I think we ought to try and do better.

Note that the only things you can do with an external object (under the XSLT 1.0 rules) are to assign it to a variable, or pass it as the argument to another function. In practice I think implementations also allow external objects to have additional behavior, for example they might allow conversion to a string when used in a context where a string is required. I think we should leave such behavior implementation-defined rather than saying that it is always an error.

The question arises as to where external objects should fit into the type hierarchy. Should they be a top-level thing at the same level as "sequence", or should they be one level down, along with "node" and "atomic value"? I think it makes most sense to preserve the principle "everything is a sequence", which means that there are now three kinds of item: nodes, atomic values, and external objects.

Handling this rigorously sounds like quite a pervasive change to the spec, but I don't think it's as bad as it seems. I don't think we should add any language features to support external objects, with the possible exception of a keyword "external" in the type syntax so that one can test for it using "instance of". Functions and operators that work on any sequence (for example, count) should treat an external object like any other item in the sequence. Operations that expect nodes will fail if presented with an external object; operations that expect atomic values will also fail, except that implementations may define fallback conversions from external objects to atomic values.

Interactions and Input

Proposed Resolution

Technically, I believe we could close the issue with no change to the documents, on the basis that the definition for the static context (in both XPath and XQuery) states: "Additional type definitions may be added to the in-scope type definitions by the language environment." I think an implementation could take this as sufficient authority to extend the type hierarchy with additional types, including types needed to represent objects returned by extension functions (such as "an SQL database connection").

Editorially, I think it would be a good idea if we state this explicitly in a Note, as follows:

NOTE: an implementation may allow function calls in a Query/Expression to bind to functions written in languages that use a different type system (these are known as "extension functions" in XSLT, "external functions" in XQuery). In this case, the way in which the arguments and results of such functions are mapped between the two type systems is implementation-defined. An implementation may define new types anywhere within the type hierarchy of the [Data Model] that are designed to facilitate interworking with other languages, for example a type that encapsulates an object returned by an external function; or it may provide mechanisms for the user to define such types.

Actual Resolution

Decision by: xpath-tf on 2003-03-11 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Mar/0206.html (W3C-members only))

Decision by: xquery on 2003-03-19 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Mar/0344.html (W3C-members only))

Proposal accepted.

555. module-import-fs: Formal Semantics of Module Import

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: active
Originator: fs editors
Formal Semantics of Module Import

Description

The semantics of Module Import is not formally specified.

556. variable-definitions-fs: Formal Semantics of Variable Definitions

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: active
Originator: fs editors
Formal Semantics of Variable Definitions

Description

The semantics of Variables Definitions in the XQuery prolog is not formally specified.

557. validation-declaration-fs: Formal semantics of Validation Declaration

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: active
Originator: fs editors
Formal semantics of Validation Declaration

Description

The semantics of Validation Declaration in the XQuery prolog is not formally specified.

559. FS-support-new-sequence-type: New Sequence Type needs to be fully implemented in Formal Semantics

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: active
Originator: Michael Rys
New Sequence Type needs to be fully implemented in Formal Semantics

Description

The formal semantics of the new form of sequence types is incomplete and is still under work.

558. FS-allow-PIs-comments: The content of element types should always allow PI's and comment node types

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: decided
Originator: Michael Rys
The content of element types should always allow PI's and comment node types

Description

The content of element types should always allow PI's and comment node types. This is not currently taken into account in the FS document. The best way to deal with that problem is still an open issue. Two possible options are to add PI and comment types during XML Schema import into the XQuery type system (Section 8). Another option is to add PI and comment types during type expansion (judgment expands_to in 7.2.7 Type expansion).

Actual Resolution

Decision by: fs-editors on 2003-05-01 (http://lists.w3.org/Archives/Member/w3c-query-editors/2003May/0007.html (W3C-members only))

Decision by: xquery on 2003-05-07 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003May/0024.html (W3C-members only))

Fix is in [Section 7.2.6 Type adjustment] which now adds pi and comment types when accessing an element type.

560. exactness-type-inference: Exactness of Type Inference

Locus: formal-semantics Cluster: formal semantics Priority: 1 Status: decided
Originator: Micheal Rys
Exactness of Type Inference

Description

We currently have a couple of static type inference rules (child, descendent) that preserve the more complex type consisting of interleaf, union and sequence. The question is whether this complexity is really needed.

In many cases (such as the FLWR expression used to define /) we just change the inferred type into prime x quantifier.

If we could just infer prime x quantifier, often our inference rules could be simplified.

So the question becomes: Do we really need the more complex and precise types for performing static type checking?

Actual Resolution

Decision by: xquery on 2003-07-15 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0122.html (W3C-members only))Joint meeting.

Decision by: xsl on 2003-07-15 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Jul/0122.html (W3C-members only))Joint meeting.

Decided to accept the "Simplified typing" proposal in http://lists.w3.org/Archives/Member/w3c-query-editors/2003Jul/0023.html, which solves this issue.

335. semantics-interfering-with-optimization: XPath/XQuery's current semantics greatly interferes with optimization

Locus: xpath Cluster: formal-semantics Priority: 1 Status: decided
Originator: Michael Rys
XPath/XQuery's current semantics greatly interferes with optimization

Description

Current semantics basically defines the semantics by mapping FLWRs and path expression to go top-down. Errors are normative. Problem is that we can not apply many optimizations. Simple query rewrites such as pushing or pulling filters, etc. Like to be able to push predicates down and evaluate them. Potentially the predicate might raise an error you would not have gotten if you processed top down. Want to allow implementations to do bottom up evaluations.

Suggested resolution:

The formal semantics defines dynamic evaluation in terms of a naive, top-down reduction of a core expression to a data-model value. Implementations may choose alternative evaluation strategies, which, for example, may reduce a core expression bottom-up. If an evaluation of a core expression yields a value (i.e., it does not raise an error), the value must be the same value as would be produced by the dynamic semantics defined in this document. The evaluation of a core expression may raise an error that may not be raised by the dynamic semantics as defined in this document.

Actual Resolution

Decision by: xpath-tf on 2002-10-29 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2002Oct/0449.html (W3C-members only))as part of Agendum 1.

Expressions, with the exception of "if", may be reordered and thus some errors may be raised that using another evaluation strategy may not have occurred.

Decision by: xquery on 2002-10-30 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2002Oct/0511.html (W3C-members only))accepting text for next publication, but keep issue active.

Decision by: xsl on 2002-10-31 (http://lists.w3.org/Archives/Member/w3c-xsl-wg/2002Nov/0004.html (W3C-members only))accepting text for next publication, but keep issue active.

Decision by: xpath-tf on 2003-03-18 (http://lists.w3.org/Archives/Member/w3c-xsl-query/2003Mar/0232.html (W3C-members only))

No adverse public comments received. Close issue with no change.

265. lang-inheritance: How do we determine the xml:lang for a node if it inherits xml:lang from a higher-level node?

Locus: xpath-fulltext Cluster: FTTF-xml:lang Priority: 2 Status: decided
Originator: FTTF
How do we determine the xml:lang for a node if it inherits xml:lang from a higher-level node?

Description

How do we determine the xml:lang for a node if it inherits xml:lang from a higher-level node?

Actual Resolution

Decision by: xquery on 2003-02-12 (http://lists.w3.org/Archives/Member/w3c-xml-query-wg/2003Feb/0242.html (W3C-members only))

Decided to close issue with no change to documents, since user-written expressions or functions can determine the value of xml:lang that a node inherits.

266. lang-sublanguage-support: Do we support the sublanguage portion of xml:lang?

Locus: xpath-fulltext Cluster: FTTF-xml:lang Priority: 2 Status: decided
Originator: FTTF
Do we support the sublanguage portion of xml:lang?