XQuery 1.0: An XML Query Language

2.1.1 Static Context

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

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

Static context consists of the following components:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.1.2 Evaluation Context

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

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

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

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

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

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

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

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

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

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

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

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

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

2.3.1 Document Order

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

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

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

2.3.2 Typed Value and String Value

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2.4.1 Predefined Types

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

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

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

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

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

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

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

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

2.4.2 Type Checking

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

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

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

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

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

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

2.4.3 SequenceType

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

SequenceType

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

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

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

• attribute()? refers to an optional attribute

• element() refers to any element

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

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

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

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

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

2.4.4 Type Conversions

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