XML Path Language (XPath) 2.0

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.

Any component of the static context that is not assigned a default value in the XPath specification, and is not assigned a value by the host language, 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:

• XPath 1.0 compatibility mode. This value is true if rules for backward compatibility with XPath Version 1.0 are in effect; otherwise it is false.

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

• 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. Additional type definitions may be added to the in-scope type definitions by the host language.

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

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

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

Any component of the evaluation context that is not assigned a default value in the XPath specification, and is not assigned a value by the host language, 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, 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 by the host language.

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. XPath 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 XPath. These built-in types are in the namespace http://www.w3.org/2001/XMLSchema, which is represented in this document by the prefix xs. Some examples of built-in schema types include xs:integer, xs:string, and xs:date.

In addition, XPath recognizes the predefined types listed below. All these predefined types are in the namespace http://www.w3.org/2003/05/xpath-datatypes, which is represented in this document by the 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].

Additional type definitions may be added by the host language environment via the in-scope type definitions.

2.4.2 Type Checking

XPath 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 XPath expression, the syntax shown below is used. This syntax production is called "SequenceType", since it describes the type of an XPath 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 XPath 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.

2.5.1 Kinds of Errors

As described in 2.4.2 Type Checking, XPath defines an analysis phase, which does not depend on input data, and an evaluation phase, which does depend on input data.

The result of the analysis phase is either success or one or more type errors and/or static errors. Type errors reported by the analysis phase occur when the static type of an expression is not correct for the context in which it appears. Static errors are non-type-related errors such as syntax errors. The means by which errors are reported during the analysis phase is implementation-defined.

The result of the evaluation phase is either a result value, a type error, or a dynamic error. Type errors are raised during the evaluation phase when the dynamic type of an expression is not correct for the context in which it appears. Dynamic errors are non-type-related errors such as numeric overflow. 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 Formal Semantics].

If an implementation can determine by static analysis that an expression will necessarily raise a dynamic error (for example, because it attempts to construct a decimal value from a constant string that is not in the lexical space of xs:decimal), the implementation is allowed to report this error during the analysis phase (as well as during the evaluation phase).

[XQuery 1.0 Formal Semantics] defines the set of static, dynamic, and type errors. In addition to these errors, an XPath 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 ($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, which may be a single item or an 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 input function raises an error if the input sequence is not defined in the evaluation context.

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 used as 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 Formal Semantics]. In such cases, dynamic errors may occur that could not have occurred 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 fail with a casting error if it is evaluated exactly as written. 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 fail. However, an expression must not be rearranged in a way that causes it to return a non-error result that is different from the result defined by [XQuery 1.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 expressions are the only kinds of expressions that provide guaranteed conditions under which a particular subexpression will not be evaluated.

2.6.1 Basic XPath

A Basic XPath implementation must implement the full XPath language as described in this specification, subject to the following limitations:

1. In a Basic XPath implementation, the in-scope type definitions consist only of the built-in types defined in [XML Schema] and the additional predefined types in the http://www.w3.org/2003/05/xpath-datatypes namespace.

2. A mapping from a Post-Schema Validation Infoset (PSVI) to the Data Model is specified in [XQuery 1.0 and XPath 2.0 Data Model]. In a Basic XPath implementation, this mapping maps each datatype that is not one of the predefined types listed above into its nearest supertype that belongs to this list. As a result of this mapping, all complex types are mapped into xs:anyType. (Of course, mapping from a PSVI is only one way in which a Data Model instance might be constructed--other ways are also possible.)

3. If any SequenceType contains a typename that is not one of the predefined types listed above, a Basic XPath implementation raises a static error.

4. If any SequenceType contains an ElementTest or AttributeTest that contains a TypeName or a SchemaContextPath, a Basic XPath implementation raises a static error.

5. If the processing of an expression depends on the type of some value, and that type is not one of the predefined types listed above, a Basic XPath implementation raises a dynamic error.

6. A Basic XPath implementation is not required to raise type errors during the analysis phase. If an expression contains one or more non-type-related static errors, then a Basic XPath implementation must raise at least one of these static errors during the analysis phase. If the analysis phase is successful but one or more dynamic errors are encountered during the evaluation phase, then a Basic XPath implementation must raise at least one of these dynamic errors.

2.6.2 Static Typing Feature

The Static Typing Feature removes the limitation specified by Rule 6 of Basic XPath. An implementation that includes this feature is required to detect type errors during the analysis phase. If an expression contains one or more static errors or type errors, then a Static Typing implementation must raise at least one of these errors during the analysis phase.