XQuery 1.0: An XML Query Language

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

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

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.

• For each item type (i.e., element, attribute, or type name) referenced in an instance of the data model whose expanded name matches a name in the in-scope schema definitions (ISSD), the corresponding element, attribute, or type definition in the ISSD must be equivalent to the definition originally provided in the PSVI from which the data model instance was created.

• Every item type (i.e., every element, attribute, or type name) referenced in in-scope variables or in-scope functions must be in the in-scope schema definitions.

• Every name used in a SequenceType must be in the in-scope schema definitions.

• The element declaration for every element name referenced in a SequenceType or KindTest must be in the in-scope element declarations.

• The attribute declaration for every attribute name referenced in a SequenceType or KindTest must be in the in-scope attribute declarations.

• For each mapping of a string to a document node in accessible documents, if there exists a mapping of the same string to a document type in statically-known documents, the document node must match the document type, using the matching rules in 2.4.1.1 SequenceType Matching.

• For each mapping of a string to a sequence of nodes in accessible collections, if there exists a mapping of the same string to a type in statically-known collections, the sequence of nodes must match the type, using the matching rules in 2.4.1.1 SequenceType Matching.

• The dynamic variables in the dynamic context and the in-scope variables in the static context must correspond as follows:

  • All variables defined in in-scope variables must be defined in dynamic variables.

  • For each (variable, type) pair in in-scope variables and the corresponding (variable, value) pair in dynamic variables such that the variable names are equal, the value must match the type, using the matching rules in 2.4.1.1 SequenceType Matching.

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

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