XPath is a language for addressing parts of an XML
document, designed to be used by both XSLT and
XPointer.
This document has been reviewed by W3C Members and other interested
parties and has been endorsed by the Director as a W3C Recommendation. It
is a stable document and may be used as reference material or cited as
a normative reference from other documents. W3C's role in making the
Recommendation is to draw attention to the specification and to
promote its widespread deployment. This enhances the functionality and
interoperability of the Web.
The list of known errors in this specification is available at
http://www.w3.org/1999/11/REC-xpath-19991116-errata.
Comments on this specification may be sent to www-xpath-comments@w3.org; archives
of the comments are available.
The English version of this specification is the only normative
version. However, for translations of this document, see http://www.w3.org/Style/XSL/translations.html.
A list of current W3C Recommendations and other technical documents
can be found at http://www.w3.org/TR.
This specification is joint work of the XSL Working Group and the
XML Linking Working Group and so is part of the W3C Style activity and
of the W3C XML
activity.
1 Introduction
2 Location Paths
2.1 Location Steps
2.2 Axes
2.3 Node Tests
2.4 Predicates
2.5 Abbreviated Syntax
3 Expressions
3.1 Basics
3.2 Function Calls
3.3 Node-sets
3.4 Booleans
3.5 Numbers
3.6 Strings
3.7 Lexical Structure
4 Core Function Library
4.1 Node Set Functions
4.2 String Functions
4.3 Boolean Functions
4.4 Number Functions
5 Data Model
5.1 Root Node
5.2 Element Nodes
5.2.1 Unique IDs
5.3 Attribute Nodes
5.4 Namespace Nodes
5.5 Processing Instruction Nodes
5.6 Comment Nodes
5.7 Text Nodes
6 Conformance
Appendices
A References
A.1 Normative References
A.2 Other References
B XML Information Set Mapping (Non-Normative)
XPath is the result of an effort to provide a common syntax and
semantics for functionality shared between XSL Transformations [XSLT] and XPointer [XPointer]. The primary purpose
of XPath is to address parts of an XML [XML] document.
In support of this primary purpose, it also provides basic facilities
for manipulation of strings, numbers and booleans. XPath uses a
compact, non-XML syntax to facilitate use of XPath within URIs and XML
attribute values. XPath operates on the abstract, logical structure
of an XML document, rather than its surface syntax. XPath gets its
name from its use of a path notation as in URLs for navigating through
the hierarchical structure of an XML document.
In addition to its use for addressing, XPath is also designed so
that it 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.
XPath models an XML document as a tree of nodes. There are
different types of nodes, including element nodes, attribute nodes and
text nodes. XPath defines a way to compute a string-value for each type of node.
Some types of nodes also have names. XPath fully supports XML
Namespaces [XML Names]. Thus, the name of a node is
modeled as a pair consisting of a local part and a possibly null
namespace URI; this is called an expanded-name. The data model is
described in detail in [5 Data Model].
The primary syntactic construct in XPath is the expression. An
expression matches the production Expr. An
expression is evaluated to yield an object, which has one of the
following four basic types:
Expression evaluation occurs with respect to a context. XSLT and
XPointer specify how the context is determined for XPath expressions
used in XSLT and XPointer respectively. The context consists of:
The context position is always less than or equal to the
context size.
The variable bindings consist of a mapping from variable names to
variable values. The value of a variable is an object, which can be of
any of the types that are possible for the value of an expression,
and may also be of additional types not specified here.
The function library consists of a mapping from function names to
functions. Each function takes zero or more arguments and returns a
single result. This document defines a core function library that all
XPath implementations must support (see [4 Core Function Library]).
For a function in the core function library, arguments and result are
of the four basic types. Both XSLT and XPointer extend XPath by
defining additional functions; some of these functions operate on the
four basic types; others operate on additional data types defined by
XSLT and XPointer.
The namespace declarations consist of a mapping from prefixes to
namespace URIs.
The variable bindings, function library and namespace declarations
used to evaluate a subexpression are always the same as those used to
evaluate the containing expression. The context node, context
position, and context size used to evaluate a subexpression are
sometimes different from those used to evaluate the containing
expression. Several kinds of expressions change the context node; only
predicates change the context position and context size (see [2.4 Predicates]). When the evaluation of a kind of expression is
described, it will always be explicitly stated if the context node,
context position, and context size change for the evaluation of
subexpressions; if nothing is said about the context node, context
position, and context size, they remain unchanged for the
evaluation of subexpressions of that kind of expression.
XPath expressions often occur in XML attributes. The grammar
specified in this section applies to the attribute value after XML 1.0
normalization. So, for example, if the grammar uses the character
<, this must not appear in the XML source as
< but must be quoted according to XML 1.0 rules by,
for example, entering it as <. Within expressions,
literal strings are delimited by single or double quotation marks,
which are also used to delimit XML attributes. To avoid a quotation
mark in an expression being interpreted by the XML processor as
terminating the attribute value the quotation mark can be entered as a
character reference (" or
'). Alternatively, the expression can use single
quotation marks if the XML attribute is delimited with double
quotation marks or vice-versa.
One important kind of expression is a location path. A location
path selects a set of nodes relative to the context node. The result
of evaluating an expression that is a location path is the node-set
containing the nodes selected by the location path. Location paths
can recursively contain expressions that are used to filter sets of
nodes. A location path matches the production LocationPath.
In the following grammar, the non-terminals QName and NCName are defined in [XML Names], and S is defined in
[XML]. The grammar uses the same EBNF notation as
[XML] (except that grammar symbols always have initial
capital letters).
Expressions are parsed by first dividing the character string to be
parsed into tokens and then parsing the resulting sequence of tokens.
Whitespace can be freely used between tokens. The tokenization
process is described in [3.7 Lexical Structure].
Although location paths are not the most general grammatical
construct in the language (a LocationPath is a special case of an Expr), they are the most important construct and
will therefore be described first.
Every location path can be expressed using a straightforward but
rather verbose syntax. There are also a number of syntactic
abbreviations that allow common cases to be expressed concisely. This
section will explain the semantics of location paths using the
unabbreviated syntax. The abbreviated syntax will then be explained
by showing how it expands into the unabbreviated syntax (see [2.5 Abbreviated Syntax]).
Here are some examples of location paths using the unabbreviated
syntax:
There are two kinds of location path: relative location paths
and absolute location paths.
A relative location path consists of a sequence of one or more
location steps separated by /. The steps in a relative
location path are composed together from left to right. Each step in
turn selects a set of nodes relative to a context node. An initial
sequence of steps is composed together with a following step as
follows. The initial sequence of steps selects a set of nodes
relative to a context node. Each node in that set is used as a
context node for the following step. The sets of nodes identified by
that step are unioned together. The set of nodes identified by
the composition of the steps is this union. For example,
child::div/child::para selects the
para element children of the div element
children of the context node, or, in other words, the
para element grandchildren that have div
parents.
An absolute location path consists of / optionally
followed by a relative location path. A / by itself
selects the root node of the document containing the context node. If
it is followed by a relative location path, then the location path
selects the set of nodes that would be selected by the relative
location path relative to the root node of the document containing the
context node.
Location Paths
A location step has three parts:
The syntax for a location step is the axis name and node test
separated by a double colon, followed by zero or more expressions each
in square brackets. For example, in
child::para[position()=1], child is the name
of the axis, para is the node test and
[position()=1] is a predicate.
The node-set selected by the location step is the node-set that
results from generating an initial node-set from the axis and
node-test, and then filtering that node-set by each of the predicates
in turn.
The initial node-set consists of the nodes having the relationship
to the context node specified by the axis, and having the node type
and expanded-name specified
by the node test. For example, a location step
descendant::para selects the para element
descendants of the context node: descendant specifies
that each node in the initial node-set must be a descendant of the
context; para specifies that each node in the initial
node-set must be an element named para. The available
axes are described in [2.2 Axes]. The available node tests
are described in [2.3 Node Tests]. The meaning of some
node tests is dependent on the axis.
The initial node-set is filtered by the first predicate to generate
a new node-set; this new node-set is then filtered using the second
predicate, and so on. The final node-set is the node-set selected by
the location step. The axis affects how the expression in each
predicate is evaluated and so the semantics of a predicate is defined
with respect to an axis. See [2.4 Predicates].
Location Steps
The following axes are available:
NOTE: 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.
Axes
Every axis has a principal node type. If an axis
can contain elements, then the principal node type is element;
otherwise, it is the type of the nodes that the axis can
contain. Thus,
A node test that is a QName
is true if and only if the type of the node (see [5 Data Model])
is the principal node type and has
an expanded-name equal to
the expanded-name specified
by the QName. For example,
child::para selects the para element
children of the context node; if the context node has no
para children, it will select an empty set of nodes.
attribute::href selects the href attribute
of the context node; if the context node has no href
attribute, it will select an empty set of nodes.
A QName in the node test is
expanded into an expanded-name using the namespace
declarations from the expression context. This is the same way
expansion is done for element type names in start and end-tags except
that the default namespace declared with xmlns is not
used: if the QName does not have
a prefix, then the namespace URI is null (this is the same way
attribute names are expanded). It is an error if the QName has a prefix for which there is
no namespace declaration in the expression context.
A node test * is true for any node of the principal
node type. 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 context namespace
declarations. It is an error if there is no namespace declaration for
the prefix in the expression context. The node test will be true for
any node of the principal type whose expanded-name has the namespace URI
to which the prefix expands, regardless of the local part of the
name.
The node test text() is true for any text node. For
example, child::text() will select the text node
children of the context node. Similarly, the node test
comment() is true for any comment node, and the node test
processing-instruction() is true for any processing
instruction. The processing-instruction() test may have
an argument that is Literal; in this case, it
is true for any processing instruction that has a name equal to the
value of the Literal.
A node test node() is true for any node of any type
whatsoever.
An axis is either a forward axis or a reverse axis. 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.
Thus, the ancestor, ancestor-or-self, preceding, and preceding-sibling
axes are reverse axes; all other axes are forward axes. Since the self
axis always contains at most one node, it makes no difference whether
it is a forward or reverse axis. The proximity position of a
member of a node-set with respect to an axis is defined to be the
position of the node in the node-set ordered in document order if the
axis is a forward axis and ordered in reverse document order if the
axis is a reverse axis. The first position is 1.
A predicate filters a node-set with respect to an axis to produce a
new node-set. For each node in the node-set to be filtered, the PredicateExpr is evaluated with that node
as the context node, with the number of nodes in the node-set as the
context size, and with the proximity position of the node
in the node-set with respect to the axis as the context position; if
PredicateExpr evaluates to true for
that node, the node is included in the new node-set; otherwise, it is
not included.
A PredicateExpr is evaluated by
evaluating the Expr and converting the result
to a boolean. If the result is a number, the result will be converted
to true if the number is equal to the context position and will be
converted to false otherwise; if the result is not a number, then the
result will be converted as if by a call to the
boolean function. Thus a location path
para[3] is equivalent to
para[position()=3].
Predicates
Here are some examples of location paths using abbreviated
syntax:
The most important abbreviation is that child:: can be
omitted from a location step. In effect, child is the
default axis. For example, a location path div/para is
short for child::div/child::para.
There is also an abbreviation for attributes:
attribute:: can be abbreviated to @. For
example, a location path 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 short for
/descendant-or-self::node()/. For example,
//para is short 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); div//para is short for
div/descendant-or-self::node()/child::para and so
will select all para descendants of div
children.
NOTE: The location path //para[1] does
not mean the same as the location path
/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 location step of . is short for
self::node(). This is particularly useful in
conjunction with //. For example, the location path
.//para is short for
self::node()/descendant-or-self::node()/child::para
and so will select all para descendant elements of the
context node.
Similarly, a location step 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.
Abbreviations
A VariableReference evaluates
to the value to which the variable name is bound in the set of
variable bindings in the context. It is an error if the variable name
is not bound to any value in the set of variable bindings in the
expression context.
Parentheses may be used for grouping.
A FunctionCall expression is
evaluated by using the FunctionName to
identify a function in the expression evaluation context function
library, evaluating each of the Arguments,
converting each argument to the type required by the function, and
finally calling the function, passing it the converted arguments. It
is an error if the number of arguments is wrong or if an argument
cannot be converted to the required type. The result of the FunctionCall expression is the result
returned by the function.
An argument is converted to type string as if by calling the
string function. An argument is converted to
type number as if by calling the number function.
An argument is converted to type boolean as if by calling the
boolean function. An argument that is not of
type node-set cannot be converted to a node-set.
A location path can be used as an expression. The expression
returns the set of nodes selected by the path.
The | operator computes the union of its operands,
which must be node-sets.
Predicates are used to filter
expressions in the same way that they are used in location paths. It
is an error if the expression to be filtered does not evaluate to a
node-set. The Predicate filters the
node-set with respect to the child axis.
NOTE: The meaning of a Predicate
depends crucially on which axis applies. 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.
The / and // operators compose an
expression and a relative location path. It is an error if the
expression does not evaluate to a node-set. The /
operator does composition in the same way as when / is
used in a location path. As in location paths, // is
short for /descendant-or-self::node()/.
There are no types of objects that can be converted to node-sets.
An object of type boolean can have one of two values, true and
false.
An or expression is evaluated by evaluating each
operand and converting its value to a boolean as if by a call to the
boolean function. The result is true if either
value is true and false otherwise. The right operand is not evaluated
if the left operand evaluates to true.
An and expression is evaluated by evaluating each
operand and converting its value to a boolean as if by a call to the
boolean function. The result is true if both
values are true and false otherwise. The right operand is not
evaluated if the left operand evaluates to false.
An EqualityExpr (that is not just
a RelationalExpr) or a RelationalExpr (that is not just an AdditiveExpr) is evaluated by comparing the
objects that result from evaluating the two operands. Comparison of
the resulting objects is defined in the following three paragraphs.
First, comparisons that involve node-sets are defined in terms of
comparisons that do not involve node-sets; this is defined uniformly
for =, !=, <=,
<, >= and >. Second,
comparisons that do not involve node-sets are defined for
= and !=. Third, comparisons that do not
involve node-sets are defined for <=,
<, >= and >.
If both objects to be compared are node-sets, then the comparison
will be true if and only if there is a node in the first node-set and
a node in the second node-set such that the result of performing the
comparison on the string-values of the two nodes is
true. If one object to be compared is a node-set and the other is a
number, then the comparison will be true if and only if there is a
node in the node-set such that the result of performing the comparison
on the number to be compared and on the result of converting the
string-value of that node to
a number using the number function is true. If
one object to be compared is a node-set and the other is a string,
then the comparison will be true if and only if there is a node in the
node-set such that the result of performing the comparison on the
string-value of the node and
the other string is true. If one object to be compared is a node-set
and the other is a boolean, then the comparison will be true if and
only if the result of performing the comparison on the boolean and on
the result of converting the node-set to a boolean using the
boolean function is true.
When neither object to be compared is a node-set and the operator
is = or !=, then the objects are compared by
converting them to a common type as follows and then comparing them.
If at least one object to be compared is a boolean, then each object
to be compared is converted to a boolean as if by applying the
boolean function. Otherwise, if at least one
object to be compared is a number, then each object to be compared is
converted to a number as if by applying the
number function. Otherwise, both objects to be
compared are converted to strings as if by applying the
string function. The = comparison
will be true if and only if the objects are equal; the !=
comparison will be true if and only if the objects are not equal.
Numbers are compared for equality according to IEEE 754 [IEEE 754]. Two booleans are equal if either both are true or
both are false. Two strings are equal if and only if they consist of
the same sequence of UCS characters.
NOTE: If $x is bound to a node-set, then
$x="foo" does not mean the same as
not($x!="foo"): the former is true if and only if
some node in $x has the string-value
foo; the latter is true if and only if all
nodes in $x have the string-value
foo.
When neither object to be compared is a node-set and the operator
is <=, <, >= or
>, then the objects are compared by converting both
objects to numbers and comparing the numbers according to IEEE 754.
The < comparison will be true if and only if the first
number is less than the second number. The <=
comparison will be true if and only if the first number is less than
or equal to the second number. The > comparison will
be true if and only if the first number is greater than the second
number. The >= comparison will be true if and only if
the first number is greater than or equal to the second number.
NOTE:
When an XPath expression occurs in an XML document, any
< and <= operators must be quoted
according to XML 1.0 rules by using, for example,
< and <=. In the following
example the value of the test attribute is an XPath
expression:
<xsl:if test="@value < 10">...</xsl:if>
NOTE: The effect of the above grammar is that the order of
precedence is (lowest precedence first):
and the operators are all left associative.
For example, 3 > 2 > 1 is equivalent to (3
> 2) > 1, which evaluates to false.
A number represents a floating-point number. A number can have any
double-precision 64-bit format IEEE 754 value [IEEE 754].
These include a special "Not-a-Number" (NaN) value,
positive and negative infinity, and positive and negative zero. See
Section 4.2.3 of [JLS] for a summary of the key
rules of the IEEE 754 standard.
The numeric operators convert their operands to numbers as if by
calling the number function.
The + operator performs addition.
The - operator performs subtraction.
NOTE: Since XML allows - in names, the -
operator typically needs to be preceded by whitespace. For example,
foo-bar evaluates to a node-set containing the child
elements named foo-bar; foo - bar evaluates
to the difference of the result of converting the string-value of the first
foo child element to a number and the result of
converting the string-value
of the first bar child to a number.
The div operator performs floating-point division
according to IEEE 754.
The mod operator returns the remainder from a
truncating division. For example,
NOTE: This is the same as the % operator in Java and
ECMAScript.
NOTE: This is not the same as the IEEE 754 remainder operation, which
returns the remainder from a rounding division.
Numeric Expressions
Strings consist of a sequence of zero or more characters, where a
character is defined as in the XML Recommendation [XML].
A single character in XPath thus corresponds to a single Unicode
abstract character with a single corresponding Unicode scalar value
(see [Unicode]); this is not the same thing as a 16-bit
Unicode code value: the Unicode coded character representation for an
abstract character with Unicode scalar value greater that U+FFFF is a
pair of 16-bit Unicode code values (a surrogate pair). In many
programming languages, a string is represented by a sequence of 16-bit
Unicode code values; implementations of XPath in such languages must
take care to ensure that a surrogate pair is correctly treated as a
single XPath character.
NOTE: It is possible in Unicode for there to be two strings that
should be treated as identical even though they consist of the
distinct sequences of Unicode abstract characters. For example, some
accented characters may be represented in either a precomposed or
decomposed form. Therefore, XPath expressions may return unexpected
results unless both the characters in the XPath expression and in the
XML document have been normalized into a canonical form. See [Character Model].
When tokenizing, the longest possible token is always returned.
For readability, whitespace may be used in expressions even though not
explicitly allowed by the grammar: ExprWhitespace may be freely added within
patterns before or after any ExprToken.
The following special tokenization rules must be applied in the
order specified to disambiguate the ExprToken grammar:
-
If there is a preceding token and the preceding token is not
one of @, ::, (,
[, , or an Operator, then a * must be
recognized as a MultiplyOperator
and an NCName must be
recognized as an OperatorName.
-
If the character following an NCName (possibly after intervening
ExprWhitespace) is (,
then the token must be recognized as a NodeType or a FunctionName.
-
If the two characters following an NCName (possibly after intervening
ExprWhitespace) are ::,
then the token must be recognized as an AxisName.
-
Otherwise, the token must not be recognized as a MultiplyOperator, an OperatorName, a NodeType, a FunctionName, or an AxisName.
Expression Lexical Structure
This section describes functions that XPath implementations must
always include in the function library that is used to evaluate
expressions.
Each function in the function library is specified using a function
prototype, which gives the return type, the name of the function, and
the type of the arguments. If an argument type is followed by a
question mark, then the argument is optional; otherwise, the argument
is required.
Function: number last()
The last function returns a number equal to
the context size from the
expression evaluation context.
Function: number position()
The position function returns a number equal to
the context position from
the expression evaluation context.
Function: number count(node-set)
The count function returns the number of nodes in the
argument node-set.
Function: node-set id(object)