Copyright © 2003 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
XPath 2.0 is an expression language that allows the processing of values conforming to the data model defined in [XQuery 1.0 and XPath 2.0 Data Model]. The data model provides a tree representation of XML documents as well as atomic values such as integers, strings, and booleans, and sequences that may contain both references to nodes in an XML document and atomic values. The result of an XPath expression may be a selection of nodes from the input documents, or an atomic value, or more generally, any sequence allowed by the data model. The name of the language derives from its most distinctive feature, the path expression, which provides a means of hierarchic addressing of the nodes in an XML tree. XPath 2.0 is a superset of [XPath 1.0], with the added capability to support a richer set of data types, and to take advantage of the type information that becomes available when documents are validated using XML Schema. A backwards compatibility mode is provided to ensure that nearly all XPath 1.0 expressions continue to deliver the same result with XPath 2.0; exceptions to this policy are noted in [H Backwards Compatibility with XPath 1.0].
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.
XPath 2.0 has been defined jointly by the XML Query Working Group and the XSL Working Group (both part of the XML Activity). 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 several changes. The section entitled "SequenceType
Matching" has been rewritten and includes new material on handling of
unrecognized types. A new concrete type, xdt:untypedAny
, has
been introduced, and the isnot
comparison operator has been
removed. Rules for static and dynamic implementations have been clarified. A
complete list of changes can be found in J
Revision Log.
This is a Last Call Working Draft. Comments on this document are due on 15 February 2004. Comments should be sent to the W3C mailing list public-qt-comments@w3.org (archived at http://lists.w3.org/Archives/Public/public-qt-comments/) with [XPath] at the beginning of the subject field.
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.
1 Introduction
2 Basics
2.1 Expression Context
2.1.1 Static Context
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 Documents
2.3.1 Document Order
2.3.2 Atomization
2.3.3 Effective Boolean Value
2.3.4 Input Sources
2.4 Types
2.4.1 Predefined Types
2.4.2 Typed Value and String Value
2.4.3 SequenceType Syntax
2.4.4 SequenceType Matching
2.4.4.1
Matching a SequenceType and a Value
2.4.4.2
Matching an ItemType and an Item
2.4.4.3
Matching an ElementTest and an Element
Node
2.4.4.4
Matching an AttributeTest and an Attribute
Node
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
3 Expressions
3.1 Primary
Expressions
3.1.1 Literals
3.1.2 Variable References
3.1.3 Parenthesized Expressions
3.1.4 Context Item Expression
3.1.5 Function Calls
3.1.6 XPath 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 Node 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.6 Logical
Expressions
3.7 For
Expressions
3.8 Conditional
Expressions
3.9 Quantified
Expressions
3.10 Expressions on SequenceTypes
3.10.1 Instance Of
3.10.2 Cast
3.10.3 Castable
3.10.4 Constructor Functions
3.10.5 Treat
A XPath 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
D References
D.1 Normative
References
D.2 Non-normative References
D.3 Non-normative
Informative Material
E Glossary
F Summary of Error Conditions
G Conformance
H Backwards Compatibility with XPath
1.0 (Non-Normative)
H.1 Incompatibilities when
Compatibility Mode is true
H.2 Incompatibilities when
Compatibility Mode is false
H.3 Incompatibilities when using a
Schema
I XPath 2.0 and XQuery 1.0 Issues
(Non-Normative)
J Revision Log (Non-Normative)
J.1 12 November 2003
The primary purpose of XPath is to address the nodes of [XML 1.0] trees. XPath gets its name from its use of a path notation for navigating through the hierarchical structure of an XML document. XPath uses a compact, non-XML syntax to facilitate use of XPath within URIs and XML attribute values.
[Definition: XPath 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.]
XPath is designed to be embedded in a host language such as [XSLT 2.0] or [XQuery]. XPath has a natural subset that can be used for matching (testing whether or not a node matches a pattern); this use of XPath is described in [XSLT 2.0].
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.
XPath also depends on and is closely related to the following specifications:
[XQuery 1.0 and XPath 2.0 Data Model] defines the data model that underlies all XPath expressions.
[XQuery 1.0 and XPath 2.0 Formal Semantics] defines the static semantics of XPath and also contains a formal but non-normative description of the dynamic semantics that may be useful for implementors and others who require a formal definition.
The type system of XPath is based on [XML Schema].
The default function library and the operators supported by XPath are defined in [XQuery 1.0 and XPath 2.0 Functions and Operators].
This document specifies a grammar for XPath, using the same Basic EBNF notation used in [XML 1.0], 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 XPath Grammar]. The appendix should be regarded as the normative version.
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:
[60] | 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.
Certain aspects of language processing are described in this specification as implementation-defined or implementation-dependent.
[Definition: Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementor for each particular implementation.]
[Definition: 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.]
A language aspect described in this specification as implementation-defined or implementation dependent may be further constrained by the specifications of a host language in which XPath is embedded.
This document normatively defines the dynamic semantics of XPath. The static semantics of XPath are normatively defined in [XQuery 1.0 and XPath 2.0 Formal Semantics]. In this document, examples and material labeled as "Note" are provided for explanatory purposes and are not normative.
The basic building block of XPath is the expression, which is a string of Unicode characters. 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: XPath is a functional language, which means that expressions can be nested with full generality. ] [Definition: XPath is also a strongly-typed language in which the operands of various expressions, operators, and functions must conform to the expected types.]
Like XML, XPath is a case-sensitive language. Keywords in XPath use lower-case characters and are not reserved—that is, names in XPath expressions are allowed to be the same as language keywords—except for the list of reserved function-names in A.3 Reserved Function Names.
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 defined 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.]
Names in XPath conform to the syntax in [XML Names]. This document uses the following namespace prefixes(these prefix bindings are illustrative rather than normative):
xs = http://www.w3.org/2001/XMLSchema
xsi = http://www.w3.org/2001/XMLSchema-instance
fn = http://www.w3.org/2003/11/xpath-functions
xdt = http://www.w3.org/2003/11/xpath-datatypes
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.
[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.
[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 value is true
if
rules for backward compatibility with XPath Version 1.0 are in effect;
otherwise it is 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.]
[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 environment.
[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 environment.]
[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. Each named type definition is identified either by a QName (for a named type) or by an implementation-dependent type identifier (for an anonymous type). The in-scope type definitions include the predefined types as described in 2.4.1 Predefined Types. ]
[Definition: In-scope element declarations. Each element declaration is identified either by a QName (for a top-level element declaration) or by an implementation-dependent element identifier (for a local element declaration). 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 declaration) or by an implementation-dependent attribute identifier (for a local attribute declaration). ]
[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.]
An expression that binds a variable (such as a for
,
some
, or every
expression) extends the in-scope
variables of its subexpressions with the new bound variable and its type.
[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).] [Definition: Each function has a function signature that specifies the name of the function and the static types of its parameters and its result.]
The in-scope functions include constructor functions, which are discussed in 3.10.4 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 and operators when no explicit collation is specified.]
[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 available 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 not a string literal that is present
in statically-known documents, then the static type of fn:doc
is
document-node()?
.
Note:
The purpose of the statically known documents is to provide type
information, not to determine which documents are available. A URI need not
be found in the statically known documents to be accessed using
fn:doc
.
[Definition: Statically-known collections.
This is a mapping from strings onto types. The string represents the absolute
URI of a resource that is potentially available 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 not a string literal that is present in statically-known collections, then
the static type of
fn:collection
is node()?
.
Note:
The purpose of the statically known collections is to provide type
information, not to determine which collections are available. A URI need not
be found in the statically known collections to be accessed using
fn:collection
.
[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 fn: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: Function implementations. Each function in in-scope functions has a function implementation that enables the function to map instances of its parameter types into an instance of its result type. ]
[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 return 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 determined by the host language. See [ISO 8601] for the range of legal values of a timezone.]
[Definition: Available documents. This is a
mapping of strings onto document nodes. The string represents the absolute
URI of a resource. The document node is the root of a tree that represents
that resource using the data
model. The document node is returned by the fn:doc
function
when applied to that URI.] The set of available documents is not constrained
by the set of statically-known documents, and it may be empty.
[Definition: Available 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 available collections is not constrained by the set of
statically-known collections, and it may be empty.
XPath is defined in terms of the data model and in terms of the expression context.
Figure 1: Processing Model Overview
Figure 1 provides a schematic overview of the processing steps that are discussed in detail below. Some of these steps are completely outside the domain of XPath; in Figure 1, these are depicted outside the line that represents the boundaries of the language, an area labeled the external processing domain. The external processing domain 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). The area inside the boundaries of the language is known as the XPath processing domain, which includes the static analysis and dynamic evaluation phases (see 2.2.3 Expression Processing). Consistency constraints on the XPath processing domain are defined in 2.2.5 Consistency Constraints.
Before an expression can be processed, the input documents to be accessed by the expression must be represented in the data model. This process occurs outside the domain of XPath, which is why Figure 1 represents it in the external processing domain. Here are some steps by which an XML document might be converted to the data model:
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.)
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 document in the data model might be constructed. A document or fragment might also be synthesized directly from a relational database, or constructed in some other way (see DM3 in Fig. 1.) XPath is defined in terms of operations on the data model, but it does not place any constraints on how documents and instances in the data model are 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
.
The in-scope schema definitions in the static context are provided by the host language (see step SI1 in Figure 1) and must satisfy the consistency constraints defined in 2.2.5 Consistency Constraints.
XPath defines two phases of processing called the static analysis phase and the dynamic evaluation phase (see Fig. 1). An implementation is free to use any strategy or algorithm whose result conforms to these specifications.
[Definition: The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on input data (other than schemas).]
During the static analysis phase, the XPath expression 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 used to resolve type names, function names, namespace prefixes and variable names.
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].
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 static 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:XP0004] 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 Typing
Feature is in effect and the static type assigned to an expression other than
()
is empty
, a static error is raised.[err:XP0005] 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.
[Definition: The dynamic evaluation phase occurs after completion of the static analysis phase. During the dynamic evaluation phase, the value of the expression is computed.]
The dynamic evaluation phase can occur only if no errors were detected during the static analysis phase. If the Static Typing Feature is in effect, all type errors are detected during static analysis and serve to inhibit the dynamic evaluation phase. If the Static Typing Feature is not in effect, an implementation is allowed to raise type-related warnings during the static analysis phase, but it must proceed with the dynamic evaluation phase despite these warnings. In this case, type errors must be detected and raised during the dynamic evaluation 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.
[Definition: A dynamic type is associated with each value as it is computed. The dynamic type of a value may be either a structural description (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.
When the Static Typing Feature is in effect, 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 static analysis phase might infer the static type of the function parameter to be an optional element. This case is treated as a type error and inhibits evaluation, even though the function call would have been successful for input data in which the optional element is present.
[Definition: Serialization is the process of converting a set of nodes from the 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].
The host language may provide a serialization option based on this framework.
In order for XPath to be well defined, the data model, the static context, and the dynamic context must be mutually consistent. The consistency constraints listed below are prerequisites for correct functioning of an XPath implementation. Enforcement of these consistency constraints is beyond the scope of this specification.
Some of the consistency constraints use the term data model schema. [Definition: For a given node in the data model, the data model schema is defined as the schema from which the type annotation of that node was derived.] For a node that was constructed by some process other than schema validation, the data model schema consists simply of the type definition that is represented by the type annotation of the node.
For every data model node that has a type annotation other than
xs:anyType
, if that type annotation is found in the in-scope schema definitions
(ISSD), then its definition in the ISSD must be the same as its definition in
the data model
schema. Furthermore, all types that are derived by extension from the
given type in the data model schema must also be known by
equivalent definitions in the ISSD.
For every element name EN that is found both in a data model node and in the in-scope schema definitions (ISSD), all elements that are known in the data model schema to be in the same substitution group as EN must also be known in the ISSD to be in the same substitution group as EN.
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.
For each mapping of a string to a document node in available 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.4 SequenceType Matching.
For each mapping of a string to a sequence of nodes in available 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.4 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.4 SequenceType Matching.
XPath is generally used to process documents. The representation of a document is normatively defined in [XQuery 1.0 and XPath 2.0 Data Model]. The functions used to access documents and collections are normatively defined in [XQuery 1.0 and XPath 2.0 Functions and Operators]. Because documents are centrally important in XPath processing, we provide a summary of some key concepts here.
An ordering called document order is defined among all the nodes used during a given query or transformation, which may consist of one or more trees (documents or fragments). Document order is defined in [XQuery 1.0 and XPath 2.0 Data Model], and its definition is repeated here for convenience.
Document order is a total ordering, although the relative order of some nodes is implementation-dependent. Informally, document order is the order returned by an in-order, depth-first traversal of the data model. Document order is stable, which means that the relative order of two nodes will not change during the processing of a given query or transformation, even if this order is implementation-dependent.
Within a tree, document order satisfies the following constraints:
The root node is the first node.
The relative order of siblings is determined by their order in the XML representation of the tree. A node N1 occurs before a node N2 in document order if and only if the start of N1 occurs before the start of N2 in the XML representation.
Namespace nodes immediately follow the element node with which they are associated. The relative order of namespace nodes is stable but implementation-dependent.
Attribute nodes immediately follow the namespace nodes of the element with which they are associated. The relative order of attribute nodes is stable but implementation-dependent.
Element nodes occur before their children; children occur before following-siblings.
The relative order of nodes in distinct trees is stable but implementation-dependent, subject to the following constraint: If any node in tree T1 is before any node in tree T2, then all nodes in tree T1 are before all nodes in tree T2.
The semantics of some XPath operators 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, its typed value is returned.
Atomization is used in processing the following types of expressions:
Arithmetic expressions
Comparison expressions
Function calls and returns
Cast expressions
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 value of type xs:string
or
xdt:untypedAtomic
A numeric value that is equal to zero
The xs:double
or xs: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
Certain types of predicates, such as a[b]
Conditional expressions (if
)
Quantified expressions (some
, every
)
Note:
Note that the definition of effective boolean value is not used when casting a value to the
type xs:boolean
.
XPath 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; they are defined 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 context item.
The input functions supported by XPath 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 takes a string containing a URI,
and returns the data model representation of the collection identified by the
URI. A collection may be any sequence of nodes. 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 arguments that resolve to the same absolute URI during the scope of a single query or transformation, each invocation returns the same result.
XPath is a strongly typed language with a type system based on [XML Schema]. The XPath type system is formally defined in [XQuery 1.0 and XPath 2.0 Formal Semantics].
The in-scope type definitions in the static context are initialized with a set of
predefined types that is determined by the host language. This set may
include some or all of the types defined by [XML
Schema] in the namespace http://www.w3.org/2001/XMLSchema
,
represented in this document by the namespace prefix xs
. It may
also include the types defined in the namespace
http://www.w3.org/2003/11/xpath-datatypes
, represented in this
document by the namespace prefix xdt
. The types in this
namespace are defined in [XQuery 1.0 and
XPath 2.0 Functions and Operators] and are summarized below.
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
.
xdt:untypedAny
is a concrete type used to denote the dynamic
type of an element node that has not been assigned a more specific type. It
has no subtypes. An element that has been validated in skip
mode, or that has a PSVI type property of xs:anyType
, is
represented in the Data Model by an element node with the type
xdt:untypedAny
.
xdt:untypedAtomic
is a concrete type used to denote untyped
atomic data, such as text that has not been assigned a more specific type. It
has no subtypes. An attribute that has been validated in skip
mode, or that has a PSVI property of xs:anySimpleType
, is
represented in the Data Model by an attribute node with the type
xdt:untypedAtomic
.
xdt:dayTimeDuration
is a concrete subtype of
xs:duration
whose lexical representation contains only day,
hour, minute, and second components.
xdt:yearMonthDuration
is a concrete subtype of
xs:duration
whose lexical representation is restricted to
contain only year and month components.
The relationships among the types in the xs
and
xdt
namespaces are illustrated in Figure 2. The abstract types,
represented by ovals in the figure, may be assigned to an expression during
the static
analysis phase if no more specific type can be inferred for the
expression. During the dynamic evaluation phase, each node or value in
the data model is assigned a concrete type, represented by one of the types
listed in the rectangular boxes in Figure 2. A more complete description of
the XPath type hierarchy can be found in [XQuery 1.0 and XPath 2.0 Functions and
Operators].
Figure 2: Summary of XPath Type Hierarchy
In the data model, every
node has a typed value and a string 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]. The string
value of a node is a string and can be extracted by applying 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]. Element and attribute
nodes have a type annotation, which represents (in an implementation-dependent way) the
dynamic (run-time) type
of the node. In the [XQuery 1.0 and XPath 2.0 Data
Model], type annotation is defined by the dm:type
accessor;
however, XPath 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.
For text, document, and namespace nodes, the typed value of the node is
the same as its string value, as an instance of the type
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.)
The typed value of a comment or processing instruction node is the same as
its string value. It is an instance of the type xs:string
.
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 xs:IDREFS
,
which is a list datatype derived from the atomic datatype
xs: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 xs: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
xs:IDREFS
), its typed value is treated as a sequence of the
atomic type from which it is derived (such as xs:IDREF
).
For an element node, the relationship between typed value and string value depends on the node's type annotation, as follows:
If the type annotation is xdt:untypedAtomic
, 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
.
Note:
Since xs:untypedAny
is a complex type with mixed content,
this rule applies to elements whose type is xs:untypedAny
.
Example: E1 is an element node having type annotation
xdt:untypedAny
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
.
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 from the atomic 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
.
If the type annotation denotes a complex type with empty content, then the typed value of the node is the empty sequence.
If the type annotation denotes a complex type with element-only 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
element-only
. 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.
[Definition: When it is necessary to refer to a type in an XPath expression, the SequenceType syntax is used. The name SequenceType suggests that this syntax is used to describe the type of an XPath value, which is always a sequence.]
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 TypeName in an ElementTest or AttributeTest if that name is not found in the in-scope type definitions. It is a static error [err:XP0008] to use an ElementName in an ElementTest if that name is not found in the in-scope element definitions unless a TypeNameOrWildcard is specified. It is a static error [err:XP0008] to use a (SchemaContextPath ElementName) pair in an ElementTest if the ElementName can not be located from the in-scope element definitions using the SchemaContextPath. It is a static error [err:XP0008] to use an AttributeName in an AttributeTest if that name is not found in the in-scope attribute definitions unless a TypeNameOrWildcard is specified. It is a static error [err:XP0008] to use a (SchemaContextPath AttributeName) pair in an AttributeTest if the AttributeName can not be located from the in-scope attribute definitions using the SchemaContextPath. If a QName that is used as an AtomicType is not defined as an atomic type in the in-scope type definitions, a static error is raised. [err:XP0051]
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
[Definition: During evaluation of an
expression, it is sometimes necessary to determine whether a value with a
known type "matches" an expected type, expressed in the SequenceType syntax.
This process is known as SequenceType matching.] For example, an
instance of
expression returns true
if the actual
type of a given value matches a given type, or false
if it does
not.
Note:
In this specification, the word "type", when used without modification, represents a type that can be expressed using the SequenceType production. When we refer specifically to W3C XML Schema simple or complex types, appropriate modifiers are used to make this clear.
The rules for SequenceType matching compare the actual type
of a value with an expected type. These rules are a subset of the static
typing rules defined in [XQuery 1.0 and
XPath 2.0 Formal Semantics], which compare the static type of an
expression with the expected type of the context in which the expression is
used. The static typing rules are a superset of the SequenceType
matching rules because the static type of an expression is typically more
general than the dynamic type of the value produced by evaluating the
expression. For example, the static type of the expression if (expr)
then "true" else 0
is xs:string | xs:integer
, as
described in [XQuery 1.0 and XPath 2.0
Formal Semantics]. However, if expr
evaluates to
true
, then the dynamic type of this expression is
xs:string
.
Some of the rules for SequenceType matching require matching of simple or complex types to determine whether a given type is the same as or derived from an expected type. These types may be "known" types, which are defined in the in-scope schema definitions, or "unknown" types, which are not defined in the in-scope schema definitions. An unknown type might be encountered, for example, if the module in which the given type is encountered does not import the schema in which the given type is defined. In this case, an implementation is allowed (but is not required) to provide an implementation-dependent mechanism for determining whether the unknown type is compatible with the expected type. For example, an implementation might maintain a data dictionary containing information about type hierarchies.
We define the process of matching simple or complex types using a
pseudo-function named type-matches(
ET,
AT)
that takes an expected simple or complex type
ET and an actual simple or complex type AT, and either
returns a boolean value or raises a type error. [err:XP0004][err:XP0006] This pseudo-function type-matches
is defined as follows:
type-matches(
ET, AT)
returns
true
if:
AT is a known type, and is the same as ET, or is derived by one or more steps of restriction or extension from ET, or
AT is an unknown type, and an implementation-dependent mechanism is able to determine that AT is derived by restriction from ET.
type-matches(
ET, AT)
returns
false
if:
AT is a known type, and is not the same as ET, and is not derived by one or more steps of restriction or extension from ET, or
AT is an unknown type, and an implementation-dependent mechanism is able to determine that AT is not derived by restriction from ET.
type-matches(
ET, AT)
raises a
type error [err:XP0004][err:XP0006] if:
ET is an unknown type, or
AT is an unknown type, and the implementation is not able to determine whether AT is derived by restriction from ET.
Note:
The type-matches
pseudo-function can not be written as a real
XQuery function, because types are not valid function parameters.
The rules for SequenceType matching are given below, with examples (the examples are for purposes of illustration, and do not cover all possible cases).
The SequenceType empty()
matches a value that is the empty
sequence.
An ItemType with no OccurrenceIndicator matches any value that contains exactly one item if the ItemType matches that item (see 2.4.4.2 Matching an ItemType and an Item).
An ItemType with an OccurrenceIndicator matches a value if the number of items in the value matches the OccurrenceIndicator and the ItemType matches each of the items in the value.
An OccurrenceIndicator specifies the number of items in a sequence, as follows:
?
matches zero or one items
*
matches zero or more items
+
matches one or more items
As a consequence of these rules, any SequenceType whose
OccurrenceIndicator is *
or ?
matches a value that
is an empty sequence.
An ItemType consisting simply of a QName is interpreted as an
AtomicType. An AtomicType AtomicType matches an atomic value
whose actual type is AT if type-matches(
AtomicType,
AT)
is true
.
Example: The AtomicType xs:decimal
matches the value
12.34
(a decimal literal). xs:decimal
also matches
a value whose type is shoesize
, if shoesize
is an
atomic type derived by restriction from xs:decimal
.
A named atomic type may be a generic type such as
xdt:anyAtomicType
. Note that the 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*
.
item()
matches any single item.
Example: item()
matches the atomic value 1
or
the element <a/>
.
node()
matches any node.
text()
matches any text node.
processing-instruction()
matches any processing-instruction
node.
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 may also be expressed as a string literal, as in this example:
processing-instruction("xml-stylesheet")
.
comment()
matches any comment node.
document-node()
matches any document node.
document-node(
E)
matches any document
node that contains zero or more comments and processing instructions and
contains exactly one element node, if E is an ElementTest that
matches the element node (see 2.4.4.3 Matching
an ElementTest and an Element Node).
Example: document-node(element(book))
matches any document
node containing zero or more comments and processing instructions and exactly
one element node that is matched by the ElementTest
element(book)
.
An ItemType that is an ElementTest or AttributeTest matches an element or attribute node as described in the following sections.
[Definition: An ElementTest is used to match an element node by its name and/or type.]
In the following rules, ElementName and TypeName are
names that match the corresponding productions in the grammar, where
TypeName is optionally followed by the keyword
nillable
. The pair SchemaContextPath ElementName
represents a path that matches the corresponding productions in the grammar.
Note that the SchemaContextPath ElementName pair is just one path;
for instance, the path hospital/staff/person
is an example of
such a pair, where hospital/staff/
is the
SchemaContextPath and person
is the
ElementName. Two QNames "match" if their expanded forms (URIs and
local names) are identical.
An ElementTest may take one of the following forms:
element()
, element(*)
, and
element(*,*)
match any single element node, regardless of its
name or type.
element(
ElementName,
TypeName)
matches a given element node if:
the name of the element node matches ElementName or matches the name of an element in a substitution group headed by an element with the name ElementName, and:
type-matches(
TypeName, AT)
is
true
, where AT is the type of the given element node.
However, if the given element node has the nilled
property, then
this rule is satisfied only if TypeName is followed by the keyword
nillable
.
For this form, there is no requirement that ElementName be defined in the in-scope element declarations.
Example: element(person, surgeon)
matches an non-nilled
element node whose name is person
and whose type annotation is
surgeon
.
Example: element(person, surgeon nillable)
matches an element
node whose name is person
and whose type annotation is
surgeon
, and permits the element node to have the
nilled
property.
element(
ElementName)
matches an element
node if:
the name of the element node matches ElementName or matches the name of an element in a substitution group headed by an element with the name ElementName, and:
type-matches(
ST, AT)
is
true
, where ST is the simple or complex type of element
ElementName in the in-scope element declarations, and AT is the type
of the given element node. However, if the given element node has the
nilled
property, then this rule is satisfied only if ST
includes the nillable
option.
Example: element(person)
matches an element node whose name
is person
and whose type matches the type of the top-level
person
element declaration in the in-scope element
declarations.
element(
ElementName, *)
matches an
element node of any type if the name of the element matches
ElementName or matches the name of an element in a substitution
group headed by an element with the name ElementName.
For this form, there is no requirement that ElementName be defined in the in-scope element declarations.
Example: element(person, *)
matches any element node whose
name is person
, regardless of its type.
element(*,
TypeName)
matches a given
element node regardless of its name, if
type-matches(
TypeName, AT)
is
true
, where AT is the type of the given element node.
However, if the given element node has the nilled
property, then
this rule is satisfied only if TypeName is followed by the keyword
nillable
.
Example: element(*, surgeon)
matches any non-nilled element
node whose type annotation is surgeon
, regardless of its
name.
Example: element(*, surgeon nillable)
matches any element
node whose type annotation is surgeon
, regardless of its name,
and permits the element to have the nilled
property.
element(
SchemaContextPath ElementName)
matches a given element node if:
the name of the given element node matches the ElementName, and:
type-matches(
ST, AT)
is
true
, where ST is the type of the element declaration
that would be associated with an element named ElementName in the
context identified by SchemaContextPath. (This may be either a
locally declared element or a top-level element.) However, if the given
element node has the nilled
property, then this rule is
satisfied only if ST includes the nillable
option. If
SchemaContextPath and ElementName together do not identify
a valid schema path in the in-scope schema definitions, a static error is raised.[err:XP0055]
Example: element(hospital/staff/person)
matches an element
node whose name is person
and whose type matches the type of the
element identified by the schema path hospital/staff/person
.
Example: element(type(schedule)/person)
matches an element
node whose name is person
and whose type matches the type of a
person
element within the named type schedule
.
[Definition: An AttributeTest is used to match an attribute node by its name and/or type.]
In the following rules, AttributeName and TypeName are
names that match the corresponding productions in the grammar. The pair
SchemaContextPath AttributeName represents a path that matches the
corresponding productions in the grammar. Note that the SchemaContextPath
AttributeName pair is just one path; for instance, the path
catalog/product/price
is an example of such a pair, where
catalog/product/
is the SchemaContextPath and
price
is the AttributeName. Two QNames "match" if their
expanded forms (URIs and local names) are identical.
An AttributeTest may take one of the following forms:
attribute()
, attribute(*)
, and
attribute(*,*)
match any single attribute node, regardless of
its name or type.
attribute(
AttributeName,
TypeName)
matches a given attribute node if:
the name of the given attribute node matches AttributeName, and:
type-matches(
TypeName, AT)
is
true
, where AT is the type annotation of the given
attribute node.
For this form, there is no requirement that AttributeName be defined in the in-scope attribute declarations.
Example: attribute(price, currency)
matches an attribute node
whose name is price
and whose type annotation is
currency
.
attribute(
AttributeName)
matches a
given attribute node if:
the name of the given attribute node matches AttributeName, and:
type-matches(
ST, AT)
is
true
, where ST is the simple or complex type of
attribute AttributeName in the in-scope attribute
declarations, and AT is the type of the given attribute
node.
Example: attribute(price)
matches an attribute node whose
name is price
and whose type annotation matches the top-level
attribute declaration for a price
attribute.
attribute(
AttributeName, *)
matches an
attribute node of any type if the name of the node matches
AttributeName.
For this form, there is no requirement that AttributeName be defined in the in-scope attribute declarations.
Example: attribute(price, *)
matches any attribute node whose
name is price
, regardless of its type annotation.
attribute(*,
TypeName)
matches a given
attribute node if type-matches(
TypeName,
AT)
is true
, where AT is the type
annotation of the given attribute node.
Example: attribute(*, currency)
matches any attribute node
whose type annotation is currency
, regardless of its name.
attribute(
SchemaContextPath
AttributeName)
matches a given attribute node if:
the name of the given attribute node matches the AttributeName, and:
type-matches(
ST, AT)
is
true
, where ST is the type of the attribute declaration
that would be associated with an attribute named AttributeName in
the context identified by SchemaContextPath. (This may be either a
locally declared attribute or a top-level attribute.)
Example: attribute(catalog/product/price)
matches an
attribute node whose name is price
and whose type matches the
type of the attribute identified by the schema path
catalog/product/price
.
Example: attribute(type(plan)/price)
matches an attribute
node whose name is price
and whose type matches the type of a
price
attribute within the globally defined type
plan
.
As described in 2.2.3 Expression Processing, XPath 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 outcome 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 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")
In addition to static errors, dynamic errors, and type errors, an XPath implementation may raise 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-dependent.
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. This function
is defined in [XQuery 1.0 and XPath 2.0
Functions and Operators]. 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)))
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.
Similarly, in evaluating an expression, an implementation is not required to search for data whose only possible effect on the result would be to raise an error, as illustrated in the following examples.
If an implementation can find (for example, by using an index) that at
least one item returned by $expr1
in the following example has
the value 47
, it is allowed to return true
as the
result of the some
expression, without searching for another
item returned by $expr1
that would raise an error because it is
not an integer.
some $x in $expr1 satisfies $x = 47
In the following example, if an implementation can find (for example, by
using an index) the product
element-nodes that have an
id
child with the value 47
, it is allowed to return
these nodes as the result of the path expression, without searching for
another product
node that would raise an error because it has an
id
child whose value is not an integer.
//product[id = 47]
In some cases, an optimizer may be able to achieve substantial performance improvements by rearranging an expression so that the underlying operations are performed in a different order than that in which they are written. In such cases, errors may be raised that would not have been raised if the expression were evaluated as written. However, an expression must not be rearranged in a way that changes its result value in the absence of errors.
The expression in the following example 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 expression to raise an error.
$N[@x castable as xs:date][xs:date(@x) gt xs:date("2000-01-01")]
To avoid unexpected errors caused by reordering of expressions, tests that are designed to prevent dynamic errors should be expressed using conditional expressions. Conditional expressions raise only dynamic errors that occur in the branch that is actually selected.
Unlike the previous example, the following example cannot raise a dynamic
error if @x
is not castable into an xs:date
.
$N[if (@x castable as xs:date) then xs:date(@x) gt xs:date("2000-01-01") else false()]
[Definition: XPath 2.0 defines an optional feature called the Static Typing Feature.] An implementation that includes this feature is required to detect type errors during the static 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 static analysis phase.
This section discusses 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
XPath 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 the complete grammar, see Appendix [A XPath Grammar].
[15] | XPath |
::= | Expr? |
[16] | Expr |
::= | ExprSingle ("," ExprSingle)* |
[17] | ExprSingle |
::= | ForExpr |
The highest-level symbol in the XPath grammar is XPath.
The XPath operator that has lowest precedence is the comma operator (described in 3.3.1 Constructing Sequences), 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 ForExpr, QuantifiedExpr, IfExpr, and OrExpr. Each of these expressions is described in a separate section of this document.
[Definition: Primary expressions are the basic primitives of the language. They include literals, variable references, context item expressions, and function calls. A primary expression may also be created by enclosing any expression in parentheses, which is sometimes helpful in controlling the precedence of operators.]
[42] | PrimaryExpr |
::= | Literal | VarRef | ParenthesizedExpr | ContextItemExpr | FunctionCall |
[Definition: A literal is a direct syntactic representation of an atomic value.] XPath supports two kinds of literals: numeric literals and string literals.
[57] | Literal |
::= | NumericLiteral | StringLiteral |
|
[58] | NumericLiteral |
::= | IntegerLiteral | DecimalLiteral | DoubleLiteral |
|
[3] | IntegerLiteral |
::= | Digits |
|
[4] | DecimalLiteral |
::= | ("." Digits) | (Digits "." [0-9]*) |
/* ws: explicit */ |
[5] | DoubleLiteral |
::= | (("." Digits) | (Digits ("." [0-9]*)?)) ("e" | "E") ("+" | "-")?
Digits |
/* ws: explicit */ |
[6] | StringLiteral |
::= | ('"' (('"' '"') | [^"])* '"') | ("'" (("'" "'") | [^'])*
"'") |
/* ws: significant */ |
[10] | Digits |
::= | [0-9]+ |
The value of a numeric literal containing no ".
" and
no e
or E
character is an atomic value of type
xs:integer
. The value of a numeric literal containing
".
" but no e
or E
character is an
atomic value of type xs:decimal
. The value of a numeric literal
containing an e
or E
character is an atomic value
of type xs:double
. Values of numeric literals are interpreted
according to the rules in [XML Schema].
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 XPath expression contained within the value of an XML attribute, the characters used to delimit the literal must be different from the characters that are used to delimit the attribute.
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.
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 atomic 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
.
[43] | VarRef |
::= | "$" VarName |
[12] | VarName |
::= | QName |
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:
A variable may be added to the in-scope variables by the host language environment.
A variable may be bound by an XPath expression. The kinds of expressions that can bind variables
are for
expressions (3.7 For
Expressions) and quantified expressions (3.9 Quantified
Expressions).
Every variable binding has a static scope. The scope defines where references to the variable can validly occur. It is a static error [err:XP0008] 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.
[59] | 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.
[41] | 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[fn:count(./author)>1]
)
or an atomic value (as in the expression (1 to 100)[. mod 5 eq
0]
).
If the context item is undefined, a context item expression raises a dynamic error.[err:XP0002]
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, an error is raised (the host language environment may define this error as either a static or a dynamic error).[err:XP0017]
[60] | FunctionCall |
::= | QName "(" (ExprSingle ("," ExprSingle)*)? ")" |
XPath allows functions to be called. A core library of functions is defined in [XQuery 1.0 and XPath 2.0 Functions and Operators]. Additional functions may be provided in the static context. XPath per se does not provide a way to declare functions, but a host language may provide such a mechanism.
A function call is evaluated as follows:
Argument expressions are evaluated, producing argument values. 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.
Each argument value is converted by applying the function conversion rules listed below.
The function is evaluated using the converted argument values. The result is a value of the function's declared return type.
The function conversion rules are used to convert an argument value to its expected type; that is, to the declared type of the function parameter. The expected type is expressed as a SequenceType. The function conversion rules are applied to a given value as follows:
If XPath 1.0 compatibility mode is true
and the
argument is not of the expected type, then one of the following conversions
is applied:
If the expected type is xs:string
or xs:string?
,
then the given value V
is effectively replaced by
fn:string(V[1])
.
If the expected type is a numeric type, then the given value
V
is effectively replaced by fn:number(V[1])
.
If the expected type is node()
, node()?
,
item()
, or item()?
, then the given value
V
is effectively replaced by V[1]
.
Otherwise, the given value is unchanged and the remaining function conversion rules are applied.
If the expected type is a sequence of an atomic type (possibly with an
occurrence indicator *
, +
, or ?
), the
following conversions are applied:
Atomization is applied to the given value, resulting in a sequence of atomic values.
Each item in the atomic sequence that is of type
xdt:untypedAtomic
is cast to the expected atomic type.
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:XP0004][err:XP0006] If the function call takes place in a module other than the module in which the function is defined, this rule must be satisfied in both the module where the function is called and the module where the function is defined (the test is repeated because the two modules may have different in-scope schema definitions.) Note that the rules for SequenceType Matching permit a value of a derived type to be substituted for a value of its base type.
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:
my:three-argument-function(1, 2, 3)
denotes a function call
with three arguments.
my:two-argument-function((1, 2), 3)
denotes a function call
with two arguments, the first of which is a sequence of two values.
my:two-argument-function(1, ())
denotes a function call with
two arguments, the second of which is an empty sequence.
my:one-argument-function((1, 2, 3))
denotes a function call
with one argument that is a sequence of three values.
my:one-argument-function(( ))
denotes a function call with
one argument that is an empty sequence.
my:zero-argument-function( )
denotes a function call with
zero arguments.
[1] | ExprComment |
::= | "(:" (ExprCommentContent | ExprComment)* ":)" |
/* gn: comments */ |
[2] | ExprCommentContent |
::= | Char |
/* gn: parens */ |
XPath 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 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 :)
A path expression can be used to locate nodes within trees.
[36] | PathExpr |
::= | ("/" RelativePathExpr?) |
/* gn: leading-lone-slash */ |
[37] | 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 (possibly empty) sequence
of nodes; otherwise, a type
error is raised.[err:XP0019]
The sequences of nodes resulting from all the evaluations of E2
are combined, eliminating duplicate nodes based on node identity and sorting
the result 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()
(this is true even if the "/
" is the
entire path expression). 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]
The "/
" character is used, with different meanings, both as
an operator or an operand. This causes lexical difficulties when it appears
in leading position in an expression. For instance, "/*
" is an
expression with a wildcard, and "/*5
" is a parse error. In
general, it is best to use parentheses when "/
" is used as the
first operand of an operator, e.g. (/) * 5
.
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 the root
of the tree in which the context node is found, plus all nodes descended from
this root. This node sequence is used as the input to 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]
Note:
The descendants of a node do not include attribute nodes or namespace nodes.
[38] | StepExpr |
::= | AxisStep | FilterStep |
[39] | AxisStep |
::= | (ForwardStep | ReverseStep) Predicates |
[40] | FilterStep |
::= | PrimaryExpr Predicates |
[48] | ForwardStep |
::= | (ForwardAxis NodeTest) | AbbrevForwardStep |
[49] | 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. XPath provides two kinds of steps, called filter steps and axis steps.
A filter step consists simply of a primary expression followed by zero or more predicates. The result of the filter step 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. Context positions are assigned to items based on their ordinal position in the result sequence. The first context position is 1.
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.
[52] | ForwardAxis |
::= | ("child" "::") |
[53] | ReverseAxis |
::= | "parent" "::" |
XPath defines a set of full set of axes for traversing documents, but a host language may define a subset of these axes. The following axes are defined:
The child
axis contains the children of the context node,
which are the nodes returned by the dm:children
accessor in
[XQuery 1.0 and XPath 2.0 Data Model].
Note:
Only document nodes and element nodes have children. If the context node is any other kind of node, or if the context node is an empty document or element node, then the child axis is an empty sequence. The children of a document node or element node may be element, processing instruction, comment, or text nodes. Attribute, namespace, and document nodes can never appear as children.
the descendant
axis is defined as the transitive closure of
the child axis; it contains the descendants of the context node (the
children, the children of the children, and so on)
the parent
axis contains the sequence returned by the
dm:parent
accessor in [XQuery 1.0 and XPath
2.0 Data Model], which returns the parent of the context node, or an
empty sequence if the context node has no parent
the ancestor
axis is defined as the transitive closure of the
parent axis; it contains the ancestors of the context node (the parent, the
parent of the parent, and so on)
Note:
The ancestor axis includes the root node of the tree in which the context node is found, unless the context node is the root node.
the following-sibling
axis contains the context node's
following siblings, those children of the context node's parent that occur
after the context node in document order; if the context node is an attribute
node or namespace node, the following-sibling
axis is empty
the preceding-sibling
axis contains the context node's
preceding siblings, those children of the context node's parent that occur
before the context node in document order; if the context node is an
attribute node or namespace node, the following-sibling
axis is
empty
the following
axis contains all nodes that are descendants of
the root of the tree in which the context node is found, are not descendants
of the context node, and occur after the context node in document order
the preceding
axis contains all nodes that are descendants of
the root of the tree in which the context node is found, are not ancestors of
the context node, and occur before the context node in document order
the attribute
axis contains the attributes of the context
node, which are the nodes returned by the dm:attributes
accessor
in [XQuery 1.0 and XPath 2.0 Data Model]; 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
the namespace
axis contains the namespace nodes of the
context node, which are the nodes returned by the dm:namespaces
accessor in [XQuery 1.0 and XPath 2.0 Data Model];
this axis is empty unless the context node is an element node. The
namespace
axis is deprecated in XPath 2.0. Whether an
implementation supports the namespace
axis is implementation-defined. An implementation
that does not support the namespace
axis must raise a static error [err:XP0021] if it is used. Applications
needing information about the namespaces of an element should use the
functions fn:get-in-scope-namespaces
and
fn:get-namespace-uri-for-prefix
defined in [XQuery 1.0 and XPath 2.0 Functions and
Operators].
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 an axis step, each node is assigned a context position that corresponds to its position in the sequence. If the axis is a forward axis, context positions are assigned to the nodes in document order, starting with 1. If the axis is a reverse axis, context positions are assigned to the nodes in reverse document order, starting with 1. This makes it possible to select a node from the sequence by specifying its position.
Note:
One example of an expression that uses the context position is a numeric
predicate. The expression child::para[1]
selects the first
paragraph that is a child of the context node.
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, attribute, and document nodes), the type of the node.
[54] | NodeTest |
::= | KindTest | NameTest |
|
[55] | NameTest |
::= | QName | Wildcard |
|
[56] | Wildcard |
::= | "*" |
/* 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 the namespace axis, the principal node kind is namespace.
For all other axes, the principal node kind is element.
A node test that consists only of a QName or a Wildcard 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 namespace URI of the default element/type namespace in the expression context; otherwise, it has no namespace URI.
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 Types. 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
element 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
hospital
element whose declaration is a top-level element
declaration.
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.
[44] | 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 xs: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:
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.
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 that are
elements named "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
child element:
child::employee[secretary]
When using predicates with a sequence of nodes selected using a reverse
axis, it is important to remember that the the context positions for such
a sequence are assigned in reverse document order. For example,
preceding::foo[1]
returns the first foo
element in
reverse document order, because the axis that applies to the [1]
predicate is the preceding
axis. By contrast,
(preceding::foo)[1]
returns the first foo
element
in document order, because the axis that applies to the [1]
predicate is the child
axis. Similarly,
ancestor::*[1]
returns the nearest ancestor element, because the
ancestor
axis is a reverse axis.
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 25:
(21 to 29)[5]
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::node()
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 tree that contains the context
node, but raises a dynamic error if this root is not a document 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 containing the
context node
/child::book/child::chapter[fn:position() =
5]/child::section[fn:position() = 2]
selects the second
section
of the fifth chapter
of the
book
whose parent is the document node that contains the context
node
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 whose typed value is equal to the string
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
[50] | AbbrevForwardStep |
::= | "@"? NodeTest |
[51] | AbbrevReverseStep |
::= | ".." |
The abbreviated syntax permits the following abbreviations:
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.
There is also an abbreviation for the attribute axis:
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
.
//
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 child::div1/descendant-or-self::node()/child::para
and so will select all para
descendants of div1
children.
Note:
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.
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
/book/chapter[5]/section[2]
selects the second
section
of the fifth chapter
of the
book
whose parent is the document node that contains the context
node
chapter//para
selects the para
element
descendants of the chapter
element children of the context
node
//para
selects all the para
descendants of the
root document node and thus selects all para
elements in the
same document as the context node
//@version
selects all the version
attribute
nodes that are 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 type
attribute 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 whose typed value is equal to the string
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.
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.
XPath 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).
[16] | Expr |
::= | ExprSingle ("," ExprSingle)* |
[29] | 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.
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.
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. Empty parentheses can be used to denote an empty sequence.
Here are some examples of expressions that construct sequences:
The result of this expression is a sequence of five integers:
(10, 1, 2, 3, 4)
This expression combines four sequences of length one, two, zero, and two,
respectively, into a single sequence of length five. The result of this
expression is the sequence 10, 1, 2, 3, 4
.
(10, (1, 2), (), (3, 4))
The result of this expression is a sequence containing all
salary
children of the context node followed by all
bonus
children.
(salary, bonus)
Assuming that $price
is bound to the value
10.50
, the result of this expression is the sequence
10.50, 10.50
.
($price, $price)
A range expression 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 either operand cannot be converted
to a single integer. If the integer derived from the first operand is greater
than the integer derived from the second operand, the result of the range
expression is an empty sequence. Otherwise, the result is a sequence
containing the two integer operands and every integer between the two
operands, in increasing order.
This example uses a range expression as one operand in constructing a
sequence. It evaluates to the sequence 10, 1, 2, 3, 4
.
(10, 1 to 4)
This example constructs a sequence of length one containing the single
integer 10
.
10 to 10
The result of this example is a sequence of length zero.
15 to 10
This example uses the fn:reverse
function to construct a
sequence of six integers in decreasing order. It evaluates to the sequence
15, 14, 13, 12, 11, 10
.
fn:reverse(10 to 15)
[33] | UnionExpr |
::= | IntersectExceptExpr (
("union" | "|") IntersectExceptExpr )* |
[34] | IntersectExceptExpr |
::= | ValueExpr ( ("intersect" |
"except") ValueExpr )* |
[35] | ValueExpr |
::= | PathExpr |
XPath 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 the variables $seq1
, $seq2
and $seq3
are bound to the following sequences of these
nodes:
$seq1
is bound to (A, B)
$seq2
is bound to (A, B)
$seq3
is bound to (B, C)
Then:
$seq1 union $seq2
evaluates to the sequence (A, B).
$seq2 union $seq3
evaluates to the sequence (A, B, C).
$seq1 intersect $seq2
evaluates to the sequence (A, B).
$seq2 intersect $seq3
evaluates to the sequence containing B
only.
$seq1 except $seq2
evaluates to the empty sequence.
$seq2 except $seq3
evaluates to the 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.
XPath provides arithmetic operators for addition, subtraction, multiplication, division, and modulus, in their usual binary and unary forms.
[30] | AdditiveExpr |
::= | MultiplicativeExpr (
("+" | "-") MultiplicativeExpr
)* |
[31] | MultiplicativeExpr |
::= | UnaryExpr ( ("*" | "div" |
"idiv" | "mod") UnaryExpr )* |
[32] | UnaryExpr |
::= | ("-" | "+")* UnionExpr |
A 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
and
a -b
will be interpreted as arithmetic operations.
An arithmetic expression is evaluated by applying the following rules, in order, until an error is raised or a value is computed:
Atomization is applied to each operand.
If either operand is now an empty sequence, the result of the operation is an empty sequence.
If either operand is now a sequence of length greater than one, then:
If XPath 1.0 compatibility mode is true
, any items
after the first item in the sequence are discarded.
Otherwise, a type error is raised.[err:XP0006]
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]
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.
If the operand types are not valid for the given operator, and XPath
1.0 compatibility mode is true
, and the operator is not
idiv
, then each operand is further converted according to the
rules in 3.1.5 Function Calls as if
it were a function argument with the expected type xs:double
.
The operator is then applied to the operands, resulting in an atomic value or
a dynamic
error.[err:XP0004][err:XP0006]
If the operand types are still not valid for the given operator, a type error is raised.
XPath supports two division operators named div
and
idiv
. When invoked with two integer operands, div
returns a value of type xs:decimal
, but idiv
returns a value of type xs:integer
.
Here are some examples of arithmetic expressions:
The first expression below returns the xs:decimal
value
-1.5
, and the second expression returns the
xs:integer
value -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. Therefore, the following two examples have different meanings:
-$bellcost + $whistlecost -($bellcost + $whistlecost)
Comparison expressions allow two values to be compared. XPath provides three kinds of comparison expressions, called value comparisons, general comparisons, and node comparisons.
[28] | ComparisonExpr |
::= | RangeExpr ( (ValueComp |
|
[46] | ValueComp |
::= | "eq" | "ne" | "lt" | "le" | "gt" | "ge" |
|
[45] | GeneralComp |
::= | "=" | "!=" | "<" | "<=" | ">" | ">=" |
/* gn: lt */ |
[47] | NodeComp |
::= | "is" | "<<" | ">>" |
Note:
When an XPath expression is written within an XML document,
the XML escaping rules for special characters must be followed; thus
"<
" must be written as "<
".
The value comparison operators are eq
, ne
,
lt
, le
, gt
, and ge
. Value
comparisons are used for comparing single values. The result of a value
comparison is defined by applying the following rules, in order:
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:XP0004][err:XP0006]
Any atomized operand that has the dynamic type
xdt:untypedAtomic
is cast to the type
xs:string
.
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 defines which combinations of atomic types are
comparable, and how the comparison operators are mapped into supporting
functions. 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:XP0004][err:XP0006]
Here are some examples of value comparisons:
The following comparison is true only if $book1
has exactly
one author
subelement and its typed value is "Kennedy" as an
instance of xs:string
or xdt:untypedAtomic
. If
$book1
does not have exactly one author
subelement,
a type error is
raised.[err:XP0004][err:XP0006]
$book1/author eq "Kennedy"
The following comparison is true if my:hatsize
and
my:shoesize
are both user-defined types that are derived by
restriction from a primitive numeric type:
my:hatsize(5) eq my:shoesize(5)
The general comparison operators are =
, !=
,
<
, <=
, >
, and
>=
. 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:
If either atomic value has the dynamic type
xdt:untypedAtomic
, that value is cast to a required type, which
is determined as follows:
If the dynamic type of the other atomic value is a numeric type, the
required type is xs:double
.
If the dynamic type of the other atomic value is
xdt:untypedAtomic
, the required type is
xs:string
.
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]
If XPath 1.0 compatibility mode is true
, and at least
one of the atomic values has a numeric type, then both atomic values are cast
to to the type xs:double
.
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 typed value of any
author
subelement of $book1
is "Kennedy" as an
instance of xs:string
or xdt:untypedAtomic
:
$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.
Node comparisons are used to compare two nodes, by their identity or by their document order. The result of a node comparison is defined by applying the following rules, in order:
Each operand must be either a single node or an empty sequence; otherwise a type error is raised.[err:XP0004][err:XP0006]
If either operand is an empty sequence, the result of the comparison is an empty sequence.
A comparison with the is
operator is true
if the
two operands have the same identity, and are thus the same node; otherwise it
is false
. See [XQuery 1.0 and XPath 2.0
Data Model] for a definition of node identity.
A comparison with the <<
operator returns
true
if the first operand node precedes the second operand node
in document order; otherwise it returns false
.
A comparison with the >>
operator returns
true
if the first operand node follows the second operand node
in document order; otherwise it returns false
.
Here are some examples of node comparisons:
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 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"]
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
.
[22] | OrExpr |
::= | AndExpr ( "or" AndExpr )* |
[23] | 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.3.3 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 described in 2.5.3 Errors and Optimization. This is
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, XPath provides a function named
fn:not
that takes a general sequence as parameter and returns a
boolean value. The fn:not
function is defined in [XQuery 1.0 and XPath 2.0 Functions and
Operators]. The fn: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,
fn:not
raises the same dynamic error.
XPath provides an iteration facility called a for expression.
[18] | ForExpr |
::= | SimpleForClause "return"
ExprSingle |
[19] | SimpleForClause |
::= | "for" "$" VarName "in" ExprSingle ("," "$" VarName "in" ExprSingle)* |
A for
expression is evaluated as follows:
If the for
expression uses multiple variables, it is first
expanded to a set of nested for
expressions, each of which uses
only one variable. For example, the expression for $x in X, $y in Y
return $x + $y
is expanded to for $x in X return for $y in Y
return $x + $y
.
In a single-variable for
expression, the variable is called
the range variable, the value of the expression that follows the
in
keyword is called the input sequence, and the
expression that follows the return
keyword is called the
return expression. The result of the for
expression is
obtained by evaluating the return
expression once for each item
in the input sequence, with the range variable bound to that item. The
resulting sequences are concatenated in the order of the items in the input
sequence from which they were derived.
The following example illustrates the use of a
for
expression in restructuring an input document. 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 example 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. This example assumes that the context item is the
bib
element in the input document.
for $a in fn:distinct-values(//author)
return ($a,
for $b in //book[author = $a]
return $b/title)
The result of the above expression consists of the following sequence of
elements. The titles of books written by a given author are listed after the
name of the author. The ordering of author
elements in the
result is implementation-dependent due to the
semantics of the fn:distinct-values
function.
<author>Stevens</author> <title>TCP/IP Illustrated</title> <title>Advanced Programming in the Unix environment</title> <author>Abiteboul</author> <title>Data on the Web</title> <author>Buneman</author> <title>Data on the Web</title> <author>Suciu</author> <title>Data on the Web</title>
The following example illustrates a for
expression containing
more than one variable:
for $i in (10, 20),
$j in (1, 2)
return ($i + $j)
The result of the above expression, expressed as a sequence of numbers, is
as follows: 11, 12, 21, 22
The scope of a variable bound in a for
expression comprises
all subexpressions of the for
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 a variable binding
may reference another variable bound earlier in the same for
expression:
for $x in $z, $y in f($x)
return g($x, $y)
Note:
The focus for evaluation of the return
clause of a
for
expression is the same as the focus for evaluation of the
for
expression itself. The following example, which attempts to
find the total value of a set of order-items, is therefore incorrect:
fn:sum(for $i in order-item return @price * @qty)
Instead, the expression must be written to use the variable bound in the
for
clause:
fn:sum(for $i in order-item return $i/@price * $i/@qty)
XPath supports a conditional expression based on the keywords
if
, then
, and else
.
[21] | 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.3.3 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
Quantified expressions support existential and universal quantification.
The value of a quantified expression is always true
or
false
.
[20] | QuantifiedExpr |
::= | (("some" "$") | ("every" "$")) VarName "in" ExprSingle ("," "$" VarName "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.3.3 Effective Boolean Value. The
value of the quantified expression is defined by the following rules:
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
.
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.
The order in which test expressions are evaluated for the various binding
tuples is implementation-dependent. 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
SequenceTypes are
used in instance of
, cast
, castable
,
and treat
expressions.
[24] | InstanceofExpr |
::= | TreatExpr ( "instance" "of"
SequenceType )? |
The boolean operator instance of
returns true
if
the value of its first operand matches the SequenceType 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
.
. instance of element()
This example returns true
if the context item is an element
node. If the context item is undefined, a dynamic error is raised.[err:XP0002]
[27] | CastExpr |
::= | ComparisonExpr ( "cast"
"as" SingleType )? |
[61] | SingleType |
::= | AtomicType "?"? |
Occasionally it is necessary to convert a value to a specific datatype.
For this purpose, XPath 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:
Atomization is performed on the input expression.
If the result of atomization is a sequence of more than one atomic value, a type error is raised.[err:XP0004][err:XP0006]
If the result of atomization is an empty sequence:
If ?
is specified after the target type, the result of the
cast
expression is an empty sequence.
If ?
is not specified after the target type, a type error is raised.[err:XP0004][err:XP0006]
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. A summary of the rules are listed below— the normative definition of these rules is given in [XQuery 1.0 and XPath 2.0 Functions and Operators]. 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. An implementation may determine that one type is a subtype of another either by examining the in-scope schema definitions or by using an alternative, implementation-dependent mechanism such as a data dictionary.
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 primitive 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].
cast
is supported if the input type is a non-primitive 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
.
cast
is supported if the target type is a non-primitive
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.
cast
is supported if the target type is a non-primitive
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.
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.
For any combination of input type and target type that is not in the above
list, a cast
expression raises a type error.[err:XP0004][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.
[26] | CastableExpr |
::= | CastExpr ( "castable" "as"
SingleType )? |
XPath 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
Constructor functions provide an alternative syntax for casting.
A built-in constructor function is provided for each atomic type in the static context. 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 defined 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 xdt:dayTimeDuration
value equal to 21
days. It is equivalent to "P21D" cast as
xdt:dayTimeDuration
.
xdt:dayTimeDuration("P21D")
For each user-defined named atomic type definition T in the
in-scope type
definitions that is in a namespace, a constructor function is 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 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
[25] | TreatExpr |
::= | CastableExpr ( "treat" "as"
SequenceType )? |
XPath 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 Types,
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]
The following grammar uses the same Basic Extended Backus-Naur Form (EBNF) notation as [XML 1.0], 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. This appendix should be regarded as the normative version of the EBNF.
Comments on grammar productions are between '/*' and '*/' symbols - please note that these comments are normative. A 'gn:' prefix means a 'Grammar Note', and is meant as a clarification for parsing rules, and is 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
[1] | ExprComment |
::= | "(:" (ExprCommentContent | ExprComment)* ":)" |
/* gn: comments */ |
[2] | ExprCommentContent |
::= | Char |
/* gn: parens */ |
[3] | IntegerLiteral |
::= | Digits |
|
[4] | DecimalLiteral |
::= | ("." Digits) | (Digits "." [0-9]*) |
/* ws: explicit */ |
[5] | DoubleLiteral |
::= | (("." Digits) | (Digits ("." [0-9]*)?)) ("e" | "E") ("+" | "-")?
Digits |
/* ws: explicit */ |
[6] | StringLiteral |
::= | ('"' (('"' '"') | [^"])* '"') | ("'" (("'" "'") | [^'])*
"'") |
/* ws: significant */ |
[7] | SchemaGlobalTypeName |
::= | "type" "(" QName ")" |
|
[8] | SchemaGlobalContext |
::= | QName | SchemaGlobalTypeName |
|
[9] | SchemaContextStep |
::= | QName |
|
[10] | Digits |
::= | [0-9]+ |
|
[11] | NCName |
::= | [http://www.w3.org/TR/REC-xml-names/#NT-NCName]
Names |
/* gn: xml-version */ |
[12] | VarName |
::= | QName |
|
[13] | QName |
::= | [http://www.w3.org/TR/REC-xml-names/#NT-QName]
Names |
/* gn: xml-version */ |
[14] | Char |
::= | [http://www.w3.org/TR/REC-xml#NT-Char]
XML |
/* gn: xml-version */ |
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> */.
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.
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 state. (These states are only a specification tool, and do not mandate an implementation strategy for this same effect.)
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.
Expression comments are allowed inside expressions everywhere that ignorable white space is allowed.
The general rules for [XML 1.1] vs. [XML 1.0], as described in the A.2 Lexical structure section, should be applied to this production.
A host language may choose whether legal characters in an XPath expression are those characters allowed in [XML 1.0] or the larger set of characters allowed in [XML 1.1].
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. Keywords are not reserved—that is, any QName may duplicate a keyword except as noted in A.3 Reserved Function Names.
For readability, white space may be used in most expressions even though not explicitly notated in the EBNF. White space is tolerated before the first token and after the last token. White space is optional 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.
"ws: explicit" means that the EBNF notation explicitly notates where white space is allowed, and whitespace is otherwise not allowed.
"ws: significant" means that white space is significant as value content.
For other usage of white space, one or more white space characters are required to separate "words". Zero or more white space characters may optionally be used around punctuation and non-word symbols.
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 XPath. 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.
This state is for patterns that occur at the beginning of an expression or subexpression.
Pattern | Transition To State | ||
---|---|---|---|
DecimalLiteral, "..", ".", DoubleLiteral, IntegerLiteral, <NCName ":" "*">, QName, "]", ")", <"*" ":" NCName>, "*", StringLiteral |
|
||
"$", <"for" "$">, <"some" "$">, <"every" "$"> |
|
||
<"element" "(">, <"attribute" "(">, <"comment" "(">, <"text" "(">, <"node" "(">, <"document-node" "("> |
|
||
<"processing-instruction" "("> |
|
||
"(:" |
|
||
"@", <"ancestor-or-self" "::">, <"ancestor" "::">, <"attribute" "::">, <"child" "::">, <"descendant-or-self" "::">, <"descendant" "::">, <"following-sibling" "::">, <"following" "::">, <"namespace" "::">, <"parent" "::">, <"preceding-sibling" "::">, <"preceding" "::">, <"self" "::">, ",", <"if" "(">, "[", "(", "-", "+", <QName "(">, "//", "/" |
|
This state is for patterns that are defined for operators.
Pattern | Transition To State | ||
---|---|---|---|
"and", ",", "div", "else", "=", "except", "eq", "ge", "gt", "le", "lt", "ne", ">=", ">>", ">", "idiv", "intersect", "in", "is", "[", "(", "<=", "<<", "<", "-", "mod", "*", "!=", "or", "+", "return", "satisfies", "//", "/", "then", "to", "union", "|", SchemaModeForDeclareValidate |
|
||
<"instance" "of">, <"castable" "as">, <"cast" "as">, <"treat" "as"> |
|
||
"$", <"for" "$">, <"some" "$">, <"every" "$"> |
|
||
"(:" |
|
||
"]", IntegerLiteral, DecimalLiteral, DoubleLiteral, ")", StringLiteral, QName, <NCName ":" "*">, <"*" ":" NCName>, ".", ".." |
|
This state distinguishes tokens that can occur only inside the ItemType production.
Pattern | Transition To State | ||
---|---|---|---|
"$" |
|
||
<"empty" "(" ")"> |
|
||
"(:" |
|
||
<"element" "(">, <"attribute" "(">, <"comment" "(">, <"text" "(">, <"node" "(">, <"document-node" "("> |
|
||
<"processing-instruction" "("> |
|
||
QName, <"item" "(" ")"> |
|
Pattern | Transition To State | ||
---|---|---|---|
<SchemaGlobalContext "/">, SchemaGlobalTypeName |
|
||
")" |
|
||
"*", QName |
|
||
<"element" "("> |
|
||
"@", StringLiteral |
|
Pattern | Transition To State | |
---|---|---|
")" |
|
|
NCName, StringLiteral |
|
Pattern | Transition To State | |
---|---|---|
")" |
|
|
"," |
|
|
"nillable" |
|
Pattern | Transition To State | ||
---|---|---|---|
NotOccurrenceIndicator |
|
||
"?", "*", "+" |
|
This state distinguishes the SchemaContextStep from the SchemaGlobalContext.
Pattern | Transition To State | |
---|---|---|
<SchemaContextStep "/">, "@" |
|
|
QName |
|
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 |
|
||
"(:" |
|
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 | ||
---|---|---|---|
":)" |
|
||
"(:" |
|
||
ExprCommentContent |
|
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
Note:
Although the keyword typeswitch is not used in XPath, it is considered a reserved function name for compatibility with XQuery.
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 | ForExpr, some, every, IfExpr, or |
3 | and |
4 | instance of |
5 | treat |
6 | castable |
7 | cast |
8 | eq, ne, lt, le, gt, ge, =, !=, <, <=, >, >=, is, <<, >> |
9 | to |
10 | +, - |
11 | *, div, idiv, mod |
12 | unary -, unary + |
13 | union, | |
14 | intersect, except |
15 | /, // |
16 | [ ] |
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:
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.
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 of this
promotion is created by casting the original value to the required type.
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
.
The tables in this section list the combinations of types for which the
various operators of XPath are defined in terms of functions that are defined
in [XQuery 1.0 and XPath 2.0 Functions and
Operators]. The and
and or
operators are
defined directly in the main body of this document, and do not occur in this
table. 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. Note that in some cases the function does not implement the full
semantics of the given operator. For the definition 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.
Any operator listed in the tables may be validly applied to an operand of
type AT if the table calls for an operand of type ET and
type-matches(
ET, AT)
is true
(see 2.4.4 SequenceType
Matching). 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 may be validly applied to an operand of type
AT if type-matches(
ET, AT)
is
true where ET is any of the four numeric types. If the result type
of an operator is listed as numeric, it means "the first type in the ordered
list (xs:integer, xs:decimal, xs:float, xs:double)
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
.)
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:double | op:multiply-yearMonthDuration(A, B) | xdt:yearMonthDuration |
A * B | xs:double | xdt:yearMonthDuration | op:multiply-yearMonthDuration(B, A) | xdt:yearMonthDuration |
A * B | xdt:dayTimeDuration | xs:double | op:multiply-dayTimeDuration(A, B) | xdt:dayTimeDuration |
A * B | xs:double | 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:double | op:divide-yearMonthDuration(A, B) | xdt:yearMonthDuration |
A div B | xdt:dayTimeDuration | xs:double | 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:boolean | xs:boolean | fn:not(op:boolean-less-than(A, B)) | |
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:boolean | xs:boolean | fn:not(op:boolean-greater-than(A, B)) | |
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:is-same-node(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()* |
Operator | Operand type | Function | Result type |
---|---|---|---|
+ A | numeric | op:numeric-unary-plus(A) | numeric |
- A | numeric | op:numeric-unary-minus(A) | numeric |
The tables in this section describe the scope (range of applicability) of the various components in the static context and dynamic context.
The following table describes the components of the static context. For each component, "global" indicates that the value of the component applies throughout an XPath expression, whereas "lexical" indicates that the value of the component applies only within the subexpression in which it is defined.
Component | Scope |
---|---|
XPath 1.0 Compatability Mode | global |
In-scope namespaces | global |
Default element/type namespace | global |
Default function namespace | global |
In-scope type definitions | global |
In-scope element declarations | global |
In-scope attribute declarations | global |
In-scope variables | lexical; for-expressions and quantified expressions can bind new variables |
In-scope functions | global |
In-scope collations | global |
Default collation | global |
Base URI | global |
Statically-known documents | global |
Statically-known collections | global |
The following table describes how values are assigned to the various components of the dynamic context. All these components are initialized by mechanisms defined by the host language. For each component, "global" indicates that the value of the component remains constant throughout the XPath expression, whereas "dynamic" indicates that the value of the component can be modified by the evaluation of subexpressions.
Component | Scope |
---|---|
Context item | dynamic; changes during evaluation of path expressions and predicates |
Context position | dynamic; changes during evaluation of path expressions and predicates |
Context size | dynamic; changes during evaluation of path expressions and predicates |
Dynamic variables | dynamic; for-expressions and quantified expressions can bind new variables |
Current date and time | global |
Implicit timezone | global |
Available documents | global |
Available collections | global |
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 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].
An AttributeTest is used to match an attribute node by its name and/or type.
Available 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.
Available documents. This is a mapping of strings onto document
nodes. The string represents the absolute URI of a resource. The document
node is the root of a tree that represents that resource using the data model. The document node is
returned by the fn:doc
function when applied to that 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.)
The context item is the item currently being processed in a path expression. 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 position is the position of the context item within the sequence of items currently being processed in a path expression.
The context size is the number of items in the sequence of items currently being processed in a path expression.
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 return the
same result.
XPath 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.
For a given node in the data model, the data model schema is defined as the schema from which the type annotation of that node was derived.
Default collation. This collation is used by string comparison functions and operators when no explicit collation is specified.
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. 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 environment.
The dynamic context of an expression is defined as information that is available at the time the expression is evaluated.
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.
The dynamic evaluation phase occurs after completion of the static analysis phase. During the dynamic evaluation phase, the value of the expression is computed.
A dynamic type is associated with each value as it is computed. The dynamic type of a value may be either a structural description (such as "sequence of integers") or a named type.
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.
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].
An ElementTest is used to match an element node by its name and/or type.
A sequence containing zero items is called an empty sequence.
An error value is a single item or the empty sequence.
The expression context for a given expression consists of all the information that can affect the result of the expression.
The first three components of the dynamic context (context item, context position, and context size) are called the focus of the expression.
XPath is a functional language, which means that expressions can be nested with full generality.
Function implementations. Each function in in-scope functions has a function implementation that enables the function to map instances of its parameter types into an instance of its result type.
Each function has a function signature that specifies the name of the function and the static types of its parameters and its result.
Implementation-defined indicates an aspect that may differ between implementations, but must be specified by the implementor for each particular implementation.
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. 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 determined by the host language. See [ISO 8601] for the range of legal values of a timezone.
In-scope attribute declarations. Each attribute declaration is identified either by a QName (for a top-level attribute declaration) or by an implementation-dependent attribute identifier (for a local attribute declaration).
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. Each element declaration is identified either by a QName (for a top-level element declaration) or by an implementation-dependent element identifier (for a local element declaration). An element declaration includes information about the substitution groups to which this element belongs.
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).
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. 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. Each named type definition is identified either by a QName (for a named type) or by an implementation-dependent type identifier (for an anonymous type). The in-scope type definitions include the predefined types as described in 2.4.1 Predefined Types.
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.
An item is either an atomic value or a node.
A literal is a direct syntactic representation of an atomic value.
A node is an instance of one of the seven node kinds defined in [XQuery 1.0 and XPath 2.0 Data Model].
Primary expressions are the basic primitives of the language. They include literals, variable references, context item expressions, and function calls. A primary expression may also be created by enclosing any expression in parentheses, which is sometimes helpful in controlling the precedence of operators.
A sequence is an ordered collection of zero or more items.
When it is necessary to refer to a type in an XPath expression, the SequenceType syntax is used. The name SequenceType suggests that this syntax is used to describe the type of an XPath value, which is always a sequence.
During evaluation of an expression, it is sometimes necessary to determine whether a value with a known type "matches" an expected type, expressed in the SequenceType syntax. This process is known as SequenceType matching.
Serialization is the process of converting a set of nodes from the data model into a sequence of octets (step DM4 in Figure 1.)
A sequence containing exactly one item is called a singleton sequence.
Statically-known collections. This is a mapping from strings onto
types. The string represents the absolute URI of a resource that is
potentially available 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. This is a mapping from strings onto
types. The string represents the absolute URI of a resource that is
potentially available 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.
The static analysis phase depends on the expression itself and on the static context. The static analysis phase does not depend on input data (other than schemas).
The static context of an expression is the information that is available during static analysis of the expression, prior to its evaluation.
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.
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].
XPath 2.0 defines an optional feature called the Static Typing Feature.
XPath is also a strongly-typed language in which the operands of various expressions, operators, and functions must conform to the expected types.
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.
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
.
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.
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.
It is a static error if an expression is not a valid instance of the grammar defined in A.1 EBNF.
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.
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.
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.4 SequenceType Matching.
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.
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.
It is It is an error (the host language environment may define this error as either a static or a dynamic 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.
It is a static error for an expression to depend on the focus when the focus is undefined.
It is a type error if the result of a step expression (StepExpr) is not a sequence of nodes.
It is a type error if in an axis expression, the context item is not a node.
It is a dynamic error if a value in a cast expression cannot be cast to the required type.
It is a dynamic error in a cast expression if the input value does not satisfy the facets of the target type.
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.
It is a static error if a QName that is used as an AtomicType in a SequenceType is not defined in the in-scope type definitions as an atomic type.
It is a static error if an ElementTest specifies a schema path that is not found in the in-scope schema definitions.
XPath is intended primarily as a component that can be used by other specifications. Therefore, XPath relies on specifications that use it (such as [XPointer] and [XSLT 2.0]) to specify conformance criteria for XPath in their respective environments. Specifications that set conformance criteria for their use of XPath must not change the syntactic or semantic definitions of XPath as given in this specification, except by subsetting and/or compatible extensions.
This section provides a summary of the main areas of incompatibility between XPath 2.0 and [XPath 1.0].
Three separate cases are considered:
Incompatibilities that exist when source documents have no schema, and when running with XPath 1.0 compatibility mode set to true. This specification has been designed to reduce the number of incompatibilities in this situation to an absolute minumum, but some differences remain and are listed individually.
Incompatibilities that arise when XPath 1.0 compatibility mode is set to false. In this case, the number of expressions where compatibility is lost is rather greater.
Incompatibilities that arise when the source document is processed using a schema (whether or not XPath 1.0 compatibility mode is set to true). Processing the document with a schema changes the way that the values of nodes are interpreted, and this can cause an XPath expression to return different results.
The list below contains all known areas, within the scope of this
specification, where an XPath 2.0 processor running with compatibility mode
set to true will produce different results from an XPath 1.0 processor
evaluating the same expression, assuming that the expression was valid in
XPath 1.0, and that the nodes in the source document have no type annotations
other than xdt:untypedAny
and
xdt:untypedAtomic
.
Incompatibilities in the behavior of individual functions are not listed here, but are included in an appendix of [XQuery 1.0 and XPath 2.0 Functions and Operators].
In the description below, the terms node-set and number are used with their XPath 1.0 meanings, that is, to describe expressions which according to the rules of XPath 1.0 would have generated a node-set or a number respectively.
The rules for comparing a node-set to a boolean have changed. In XPath
1.0, an expression such as $nodeset=true()
was evaluated by
converting the node-set to a boolean and then performing a boolean
comparison: so this expression would return true
if
$nodeset
was non-empty. In XPath 2.0, this expression is handled
in the same way as other comparisons between a sequence and a singleton: it
is true
if $nodeset
contains at least one node
whose value, after casting to a boolean, is true
.
This means that if $nodeset
is empty, the result under XPath
2.0 will be false
regardless of the value of the boolean
operand, and regardless of which operator is used. If $nodeset
is non-empty, then in most cases the cast to a boolean is likely to fail,
giving a dynamic error. But if a node has the value "0", "1", "true", or
"false", evaluation of the expression may succeed.
The rules for comparing an integer to a boolean have changed. In XPath
1.0, the expression (4 = true())
is evaluated by converting the
number 4 to boolean (yielding true
). The expression returns
true
. In XPath 2.0, running in compatibility mode, the same
expression is evaluated by converting both operands to double (yielding
4e0 = 1e0
). The expression returns false
.
The rules for comparing a string to a boolean have changed. In XPath 1.0,
the expression ("x" = true())
is evaluated by converting the
string to a boolean, and performing a boolean comparison. In XPath 2.0 a
comparison between a boolean and a string raises a type error, even when
compatibility mode is true.
Additional numeric types have been introduced, with the effect that
arithmetic may now be done as an integer, decimal, or single- or
double-precision floating point calculation where previously it was always
performed as double-precision floating point. The result of the
div
operator when dividing two integers is now a value of type
decimal rather than double. The expression 10 div 0
raises an
error rather than returning positive infinity.
The rules for converting numbers to strings have changed. These may affect
the way numbers are displayed in the output of a stylesheet. For numbers
whose absolute value is in the range 1E-6 to 1E+6, the result should be the
same, but outside this range, scientific format is used for
xs:float
and xs:double
values.
The rules for converting strings to numbers have changed. The
representation of special values such as Infinity has been aligned with XML
Schema. Strings containing a leading plus sign, or numbers in scientific
notation, may now be converted to ordinary numeric values, whereas in XPath
1.0 they were converted to NaN
.
Many operations in XPath 2.0 produce an empty sequence as their result
when one of the arguments or operands is an empty sequence. With XPath 1.0,
the result of such an operation was typically a zero-length string or the
numeric value NaN
. An example of an expression whose value will
change as a result of this rule is string(@a+0) = "NaN"
, in the
case where @a
returns an empty node-set. With XPath 1.0, this
would produce the value true
. With XPath 2.0, it produces the
value false
.
In XPath 1.0, the <
and >
operators, when
applied to two strings, attempted to convert both the strings to numbers and
then made a numeric comparison between the results. In XPath 2.0, these
operators perform a string comparison using the default collating sequence.
(If either value is numeric, however, the results are compatible with XPath
1.0)
In XPath 1.0, functions and operators that compared strings (for example,
the =
operator) worked on the basis of character-by-character
equality of Unicode codepoints, allowing Unicode normalization at the
discretion of the implementor. In XPath 2.0, these comparisons are done using
the default collating sequence. The host language from which XPath is invoked
may define mechanisms allowing codepoint comparison to be selected as the
default collating sequence, but there is no such mechanism defined in XPath
itself.
In XPath 1.0, it was defined that with an expression of the form A
and B
, B would not be evaluated if A was false. Similarly in the case
of A or B
, B would not be evaluated if A was true. This is no
longer guaranteed with XPath 2.0: the implementation is free to evaluate the
two operands in either order or in parallel. This change has been made to
give more scope for optimization in situations where XPath expressions are
evaluated against large data collections supported by indexes.
Implementations may choose to retain backwards compatibility in this area,
but they are not obliged to do so.
Consecutive comparison operators such as A < B < C
were
supported in XPath 1.0, but are not permitted by the XPath 2.0 grammar. Such
comparisons in XPath 1.0 did not have the intuitive meaning, so it is
unlikely that they have been widely used in practice.
The namespace axis is deprecated in XPath 2.0. Implementations may support the namespace axis for backward compatibility with XPath 1.0, but they are not required to do so.
Even when the setting of the XPath 1.0 compatibility mode is false, many XPath expressions will still produce the same results under XPath 2.0 as under XPath 1.0. However, there are exceptions.
The main additional incompatibilities are as follows:
When a node-set containing more than one node is supplied as an argument
to a function or operator that expects a single node or value, the rule that
all nodes after the first are discarded no longer applies. Instead, a type
error occurs if there is more than one node. The XPath 1.0 behavior can
always be restored by using the predicate [1]
to explicitly
select the first node in the node-set.
When an empty node-set is supplied as an argument to a function or
operator that expects a number, the value is no longer converted implicitly
to NaN. The XPath 1.0 behavior can always be restored by using the
number
function to perform an explicit conversion.
More generally, the supplied arguments to a function or operator are no
longer implicitly converted to the required type, except in the case where
the supplied argument is of type xdt:untypedAtomic
(which will
commonly be the case when a node in a schema-less document is supplied as the
argument). For example, the function call concat("chapter", $nr)
raises a type error if the variable $nr
is numeric, because the
arguments to the concat
function must be strings rather than
numbers. The XPath 1.0 behavior can be restored by performing an explicit
conversion to the required type using a constructor function or cast.
It is not the case that these differences will always result in
XPath 2.0 raising an error. In some cases, XPath 2.0 will return different
results for the same expression. For example, the expression "4" <
"4.0"
. This returns false
in XPath 1.0, and
true
in XPath 2.0.
An XPath expression applied to a document that has been processed against a schema will not always give the same results as the same expression applied to the same document in the absence of a schema. Since schema processing had no effect on the result of an XPath 1.0 expression, this may give rise to further incompatibilities.
Suppose that the context node is an element node derived from the
following markup: <background color="red green blue"/>
. In
XPath 1.0, the predicate [@color="blue"]
would return
false
. In XPath 2.0, if the color
attribute is
defined in a schema to be of type xs:NMTOKENS
, the same
predicate will return true
.
Similarly, consider the expression @birth < @death
applied
to the element <person birth="1901-06-06"
death="1991-05-09"/>
. With XPath 1.0, this expression would return
false, because both attributes are converted to numbers, which returns
NaN
in each case. With XPath 2.0, in the presence of a schema
that annotates these attributes as dates, the expression returns
true
.
The XPath 2.0 and XQuery 1.0 Issues List that records pre-Last Call issues can be found at http://www.w3.org/XML/2003/11/xpath-xquery-issues.
The section entitled "SequenceType Matching" has been rewritten and includes new material on handling of unrecognized types. An implementation is allowed (but is not required) to provide an implementation-dependant mechanism for determining whether an unknown type is compatible with an expected type.
A new concrete type, xdt:untypedAny
, has been introduced and
used as the type annotation of a skip-validated element node. A new figure
has been added to illustrate the relationships among the generic types such
as xdt:untypedAny
and xdt:untypedAtomic
.
The isnot
comparison operator has been removed, and the
sections titled "Node Comparisons" and "Order Comparisons" have been
merged.
Some material has been reorganized, notably in the "Types" and "Documents" (formerly "Important Concepts") sections.
The sequence construction expression M to N
has been modified
to return an empty sequence if M > N
.
Casting an instance of xs:QName
into xs:string
is no longer supported.
Typed values of comments and processing instructions are now considered to
have type xs:string
(formerly
xdt:untypedAtomic
).
The difference between static and dynamic implementation is clarified. If the static typing feature is in effect, type errors must be detected during the static analysis phase and serve to inhibit the evaluation phase. If the static typing feature is not in effect, an implementation may raise type-related warnings during the static analysis phase, but these warnings do not serve to inhibit the evaluation phase.
Several small grammar changes have been made. For example, an "@" symbol is no longer used in a KindTest where the attribute axis is explicitly identified. See the BNF grammar for details.