The XML Linking Working Group, with this 1999 December 6 XPointer Last Call working draft, invites comment on this specification. The Last Call period begins 6 December 1999 and ends 27 December 1999.
For background on this work, please see the XML Activity Statement. While we welcome implementation experience reports, the XML Linking Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release.
For information about the XLink language with which XPointer is expected to be used, see http://www.w3.org/TR/WD-xlink.
See http://www.w3.org/TR/NOTE-xptr-req for the specific requirements that informed development of this specification.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
This specification defines the XML Pointer Language (XPointer), the language
to be used as a fragment identifier for any URI-reference that
locates a resource of Internet media type
XPointer, which is based on the XML Path Language (XPath), supports addressing into the internal structures of XML documents. It allows for traversals of a document tree and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position.Introduction
This specification defines the XML Pointer
Language (XPointer), the language
to be used as a fragment identifier
for any URI-reference that
locates a resource of Internet media type
application/xml [IETF RFC 2376]. This specification does not
constrain the syntax or semantics
of URI-references to resources of other media types.
XPointer supports addressing into the internal structures of XML documents. It allows for traversals of a document tree and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position. In particular, it provides for specific reference to elements, character strings, and other parts of XML documents, whether or not they bear an explicit ID attribute.
The structures located with XPointer can be used as link targets or for any other application-specific purpose. This specification does not constrain what uses an application may make of locations identified by XPointers. In particular, implementation of traversal to a resource is not constrained by this specification, and whether user traversal is the purpose of an XPointer at all is application-dependent. A formatted-text browser traversal might scroll to and highlight the designated location; a structure-oriented graphical tree viewer or a document-relationship display might do traversal in quite a different way; and a search application, parser, archival system, or expert agent might use XPointers for other purposes entirely. The construction of linking elements in XML documents that associate arbitrary resources (including XML documents and portions thereof) is defined in a related specification [XLink].
XPointer is built on top of the XML Path Language [XPath], which is an expression language used in the XSL Transformations (XSLT) language. XPointer's extensions to XPath allow it to:
Addressing into the internal structures of DTDs and the XML declaration is out of the scope of this specification.
Note: XPointer is the fragment identifier language for
media types. It is expected that many applications of XML will
define their own media types in order to indicate the particular
usage of XML they define.
(A recent Internet Draft [IETF I-D XMT] suggests
the use of a naming convention,
*/*-xml, for specialized media
types based on XML). XPointer is expected to be useful as a fragment
identifier language for the generic XML aspects of those media types.
Special schemes "2.3 Schemes" can be used to perform special access
to the content of those media types.
The XPointer Requirements Document [XPREQ] contains a thorough explanation of requirements for the design of XPointer. The categories and general nature of the requirements are very briefly summarized here.
In addition to XPath, the following standards have been especially influential in the development of this specification:
The addressing components of many other hypertext systems have also informed the design of XPointer, especially Dexter, OHS, FRESS, MicroCosm, and InterMedia.
The formal grammar for locators is given using a simple Extended Backus-Naur Form (EBNF) notation, as described in the XML Recommendation [XML]. Explanatory text is included here regarding aspects of XPath, to make this specification more accessible; however, such text is not normative. Should there be conflicts, [XPath] is the normative specification of these common constructs.
In addition, XLink may contain non-normative commentary of the following forms:
A recorded issue and something on which the working group is seeking comment.
Notes the editors wish to call to the attention of readers within the WG and IG. To be removed from the HTML version of the released working drafts and final recommendation but remains in the XML version.
Note: General comments the editors wish to call to the attention of the reader
The following terms are used in this specification.
<HTML>...</HTML>for an HTML document), but an abstract node that directly contains the document element. This is because there may be prolog material that resides outside the document element. The
root()function gives direct access to this node.
<A NAME="...">) within the resource.
XPointers, like XPath expressions, operate on the XML Information Set, a tree derived from the elements and other markup constructs of an XML document. Both XPointers and XPath expressions operate by selecting particular parts of such trees, often by their structural relationship to other parts (for example, the parent of a node with a certain ID value). XPointers can express multiple such selections, each operating on what is found by the prior one.
Selection of tree portions is done through axes, predicates, and functions. An axis defines a sequence of candidates that might be located; predicates then test information in the tree relative to such portions; and functions generate new candidates or perform various other tasks. For example, one may select certain elements from among the siblings of some previously located element, based on whether those sibling elements have an attribute with a certain value, or are of a certain type such as FOOTNOTE, or select the point location immediately preceding a certain P.
XPointer fragment identifiers allow one full form of XPointer addressing and two shorthand forms. The shorthand forms are defined as abbreviations of the full form of XPointer addressing, although implementations need not convert an abbreviated form into the full form before evaluation. All error conditions apply as if the full form of the XPointer were specified.
The three forms are defined as follows:
Name is defined in the XML Recommendation [XML],
QName is defined in the
XML Namespaces Recommendation [XML-Names], and
is defined in the XPath Recommendation [XPath]. Note that the
formal syntax in this specification does not represent the general applicability
of escaping, as defined in "2.2 Character Sets and Escaping".
The full form of addressing consists of one or more fragment parts. Each
starts with a scheme name and is followed by a parenthesized expression. When
the scheme is
xpointer, the associated expression provides XPath-compatible
access to nodes in an XML document's information set (except for nodes representing
CDATA marked sections and entities), and adds access to any selection of an
XML document's content. Such locations are specified using a variety of descriptive
The bare name form of addressing is provided for HTML compatibility.
The appearance of the name stands for the same name provided as the argument
of a location step using the
For example, the following URI-reference fragment identifier:
is the bare-name equivalent of the following full-form fragment identifier:
This reserved shorthand is provided for two reasons:
Note that the restriction to name characters is commonly followed, but
not required, in HTML. Also, for the bare-name form to work with an HTML document
target, the document's
NAME attribute must have been declared
to be of type
The child sequence form of addressing locates an element
by stepwise navigation using a sequence of integers separated by slashes (/).
Each integer n locates the nth child element of
the previously located element, equivalent to an XPath location step of the
*[n]. Nodes other than elements, including the document
root (which in any case is not a child of anything), cannot be located by
The beginning element for the navigation may be located either by specifying
a name, which locates an element as described above for bare names, or by
/1, which locates the document element.
The character set for XPointers is the same as for XML, namely Unicode.
XPointers are expected to be used as fragment identifiers in URI-references,
and some Unicode characters are disallowed from URI-references. Thus, if these
characters are needed in an XPointer, they must be encoded specially using
URI escaping mechanisms. The UTF-8 encoding is used for URI-references; any
bytes of the result that are not allowed in URIs must be expressed as
(where HH represents the two hexadecimal digits needed to represent
the byte being encoded).
Similarly, if XPointers appear in XML document content (for example, in
an attribute value, which is where URI-references typically appear), it is
generally necessary to escape occurrences of the left angle bracket (<)
and ampersand (&) as
For example, an XPointer, appearing in an XLink, that identifies the first
chapter elements of a document would look as follows with
the left angle bracket in its comparison operator escaped:
Note: The draft Character Model specification [CMOD] specifies
that XML-handling systems are required to treat any illegal
characters in URIs as if they had been escaped with the
mechanism, whether or not they have been. In other words, this type of escaping
may not be a necessity when XPointers are used in URI-references in XML documents.
However, if the URI-reference is extracted from an XML document and then used,
the escaping must be applied.
Validity Constraint: Additional escaping rule
The end of a
GeneralFragmentPart is signaled by
the right parenthesis [)] character that is balanced with the left parenthesis
[(] character in the LocationSpec. Any unbalanced parentheses in the
even within literals, must be escaped by preceding them with an occurrence
of the circumflex (^) character. If the
SchemeSpecificExpr contains any literal occurrences
of the circumflex, each must be escaped with an additional circumflex (that
^^). If no balancing right parenthesis can be found for a
particular left parenthesis, a syntax error results.
Validity Constraint: Expr Restrictions
Not all legal XPath expressions may be used here. Only those that return a node-set are allowed.
In a full-form XPointer, an initial
the particular notation used. The only scheme defined in this version of the
xpointer (where case is significant); all scheme
names beginning with
xpointer are reserved by this specification.
Having an explicit scheme name allows for possible future versions of the
XPointer language to identify themselves, as well as allowing alternative
addressing languages for XML-based languages such as SVG or SMIL to identify
This specification defines two items related to the scheme. The first is
the general framework for detecting what scheme is in use and the ability
to skip over schemes that are not understood. The second is the behavior when
the Scheme is
More than one
may occur in a single fragment identifier. When multiple fragment parts are
provided, they must be evaluated in left-to-right order. If evaluation of
one part fails, the next is evaluated. A fragment part with an unknown scheme
name fails by definition; the XPointer implementation must consume that fragment
part and attempt to evaluate the next one, if any. The result of the first
fragment part whose evaluation succeeds is taken to be the sub-resource located
by the fragment identifier as a whole. If all the fragment parts fail, the
fragment identifier as a whole results in a sub-resource error.
This approach allows alternative addressing mechanisms to be specified, which can allow for more robust locators in the presence of features such as content negotiation or user-selected limits on network access. For example, the following fragment identifier locates the element with an ID attribute whose value is chap1:
However, in the absence of the DTD, it is not typically possible to determine
if an attribute is of type ID. A fragment identifier like the following, with
two fragment parts, will have its first fragment part fail if no DTD is available,
but will have its second fragment part succeed if the desired attribute's
Because fragment identifiers are specific to the media type of the returned data, XPointer provides an open syntax in which other specifications may choose to participate, and under which users may include alternative fragment identifiers in case the media type of the resource may vary due to content negotiation. For example, a server might return a detailed text description when the user's client does not support graphics; the URI-reference could include an XPointer fragment identifier as well as a media-type-specific identifier for the graphic, perhaps identifying coordinates of a graphical region.
There are several kinds of errors that can arise in using XPointers. They apply to all three types of XPointer as defined above.
[Definition:] A syntactically correct XPointer may, when interpreted, find that it is given no resource to work from (for example, it may be appended to an incorrect URI), or may find itself operating on a resource that is not well-formed XML data. Such an XPointer is said to have a resource error.
[Definition:] A syntactically correct XPointer may, when interpreted, fail to find a sub-resource matching its description. Such an XPointer is said to have a sub-resource error. Note that XPath allows expressions that return empty node-sets as their results and does not regard that as an error. XPointers are not a general query mechanism, they are a specification of document locations. Therefore, an empty result is a sub-resource error.
This specification does not constrain how applications deal with these errors.
This section describes the XPointer extensions to XPath. XPointer defines the following in order to build on and extend XPath:
range, corresponding to DOM positions and ranges, that can appear in location-set results. It also adds tests for these location types.
RangeExpr, which can generate results of the range location type.
XPath provides for locating any subset of the nodes in an XML document, where nodes generally correspond to information set items such as elements, attributes, comments, and processing instructions. XPath functionality, such as filtering an axis output by predicate, is generally defined in terms of operations on nodes and node-sets.
XPointer has a requirement to identify document portions that are not nodes in this sense. One example of such a non-node region is an arbitrary user selection indicated by a drag between two points in a document. The two points may be in different subtrees, or the region may form only a small part of a node. For example, a range could extend from the middle of one paragraph to the middle of the next, thus containing only part of the relevant paragraph and text nodes. Even though such locations are not nodes, XPointer needs to be able to apply XPath operations to them as well as to nodes.
To accomplish this, XPointer defines location as a generalization of XPath's node. Every location is either a point, a range, or an XPath node. Thus, XPointer also defines location-set as a generalization of XPath's node-set. All locations generated by XPath constructs are nodes; XPointer constructs can also generate points and ranges.
Note: In user selections of text, the order of characters on a computer screen may not reflect their order in the underlying XML document. For example, this can occur when a portion of a right-to-left language such as Arabic is embedded in a left-to-right language such as French. In situations where the order of characters is important, such as when indexing into strings, the indices are for the document order of the characters in the string, not the display order.
An XPointer is evaluated to yield an object of type location-set. This
evaluation is carried out within a context identical to the XPath evaluation
context, except for the generalization of nodes to locations. This section
defines how the evaluation context must be initialized by XPointer implementations
prior to evaluating an
An XPointer evaluation context contains the following information:
xmlprefix is bound to the URI
http:/www.w3.org/XML/1998/namespace. No other namespace declarations shall be in its evaluation context. Note: It is possible to address a node by its qualified name, even if the evaluation context has not been initialized with a declaration of the namespace. The XPath language provides the functions
local-name()that can be used to achieve this purpose. For example, the following locates all the
yelements from the namespace whose URI is
The major extension XPointer makes to XPath is to allow the addressing
of locations that do not correspond to XPath nodes. To address these non-node
locations, XPointer defines two new location types,
that can appear in location-sets and can be operated on by XPath node tests
and predicates. Locations of the
type represent positions and ranges as in DOM Level 2 [DOM2].
This section defines the
range types and
the characteristics of them required for XPath interoperability.
Points and ranges can be used as XPointer context locations. This allows
 operator to be used to select from sets of ranges,
and allow the first operand in a
A location of type point is defined by [Definition:] a node, called the container node, and [Definition:] a non-negative integer, called the index. It can represent the location preceding any individual character, or preceding or following any node in an XML document.
Note: This specification does not constrain the implementation of points. In other words, it is not required that implementations actually represent points using data structures consisting of a node and an index.
[Definition:] When the container node of a point is of a node type that can have child nodes (that is, the container node is an element node or a root node), then the index is an index into the child nodes; such a point is called a node-point. The index of a node-point must be greater than or equal to zero and less than or equal to the number of child nodes of the container. An index of zero indicates the point before any child nodes, and a non-zero index n indicates the point immediately after the nth child node.
[Definition:] When the container node of a point is of a node type that cannot have child nodes, then the index is an index into the characters of the string-value of the node; such a point is called a character-point. The index of a character-point must be greater than or equal to zero and less than or equal to the length of the string-value of the node. An index of zero indicates a point immediately before the first character of the string-value, and a non-zero index n indicates an point immediately after the nth character of the string-value.
Point locations do not have an expanded-name.
The string-value of a point location is empty.
The axes of a point location are defined as follows:
A location of type range is defined by two points, a start point and an end point. A range represents all of the XML structure and content between the start point and end point. This is distinct from any list of nodes and/or characters, in part because some nodes may only be partly included. The start and end points of a range must be in the same document. The start point must not appear after the end point in document order.
If the container node of one point of a range is a node of a type other than element, text, or root, the container node of the other point of the range must be the same.
Range locations do not have an expanded-name.
The string-value of a range location is defined as follows. If the points are both character-points and the container nodes of the points are the same, then the string-value consists of the characters between the two points. Otherwise, the string-value consists of the characters that are in text nodes and that are between the two points.
The axes of a range location are the axes of its starting position.
Note: The start-point() and end-point() functions can be used to navigate with respect to the respective boundaries of a range location.
namespacelocation, the container node of the start point and end point of the covering range is the attribute or namespace location; the index of the start point of the covering range is 0; and the index of the end point of the covering range is the length of the string-value of the attribute or namespace location.
rootlocation, the container node of the start point and end point of the covering range is the root node; the index of the start point of the covering range is 0; and the index of the end point of the covering range is the number of children of the root location.
pointlocation, the start and end points of the covering range are the point itself.
XPointer extends the XPath production for NodeType
by adding items for the
types. That production becomes as follows:
This definition allows NodeTests
to select locations of type
a location set that may include locations of all three types.
XPointer extends XPath's concept of document order to cover point and range locations.
For any point, there is an immediately preceding node defined as follows (except that there is no point defined preceding or following the root):
For any point, the immediately following node is the node that is immediately after the immediately preceding node (as just defined).
A node is before a point if the node is before or equal in document order to the immediately preceding node of the point; otherwise, the node is after the point.
The relative order of a node and a range is determined by the relative order of the node and the starting point of the range.
Document order for a point is defined as follows:
One range node is before another range node if and only if
Following is the formal definition of a range expression:
The result of evaluating a
RangeExpr is the
location-set computed as follows. The first operand is evaluated. The evaluation
context for the first operand is the same as the evaluation context for the
RangeExpr. The result of evaluating the first operand
must be a location-set. For each location x in this location-set,
the second operand is evaluated with x as the context location
and 1 as the context position and 1 as the context size; the result in each
case must be a location-set. For each location y in this location-set,
a range is added to the result location-set of the
whose start point is the start point of the covering range of x
and end point is the end point of the covering range of y.
For example, the following XPointer selects everything from the beginning
of the last
P descendant element in a section with ID
through the end of the first
P descendant element in another
section with ID
As another example, imagine a document that uses empty elements ( such
<REVST/> for revision start and
for revision end) to mark the boundaries of edits. The following XPointer
would select, for each revision, a range starting at the beginning of the
element and ending at the end of the next
For each location in the location-set argument, the string-value of the location is searched for substrings that match the string argument, and the resulting location-set will contain a range location for each non-overlapping match. An empty string is considered to match before each character of the string-value. The third argument gives the position of the first character to be in the resulting range, relative to the start of the match. The default value is 1, which makes the range start immediately before the first character of the matched string. The fourth argument gives the number of characters in the range; the default is that the range extends to the end of the matched string.
Multiple adjacent whitespace characters (as defined for
in [XML]) are treated as a single white-space before for the
purposes of matching. That is, a string of whitespace characters in the
argument can match a sequence of whitespace characters in the string being
The points of the range-location in the returned location-set will all be character points, and are not changed by the whitespace-matching rule.
For example, the following expression returns a range that selects the
17th occurrence of the string Thomas Pynchon occurring in a
As another example, the following expression returns a collapsed range
whose points immediately precede the letter P (8 from the start
of the string) in the third occurrence of the string Thomas Pynchon
Alternatively this could be specified as follows:
The following expression selects the fifth exclamation mark in any text node in the document and the character immediately following it:
XPointer also adds the following functions to those in XPath; these functions must be provided by XPointer implementations.FUNCTION: location-set range( location-set )
The range() function returns ranges covering the locations in the argument location-set. For each location x in the argument location-set, a range location representing the covering range of x is added to the result location-set.FUNCTION: location-set range-inside( location-set )
The range-inside() function returns ranges covering the contents of the locations in the argument location-set. For each location x in the argument location-set, a range location is added to the result location-set. If x is a range location, then x is added to the result location-set. If x is not a range location, then x is used as the container location of the start and end points of the range location to be added; the index of the start point of the range is zero; if the end point is a character point then its index is the length of the string-value of x, and otherwise is the number of location children of x.FUNCTION: location-set start-point( location-set )
The result location-set contains zero or more locations of type
For each location in the argument location-set, a point location equal to
the start point of the covering range of the location is added to the result
would locate the point immediately preceding the third chap element in the document.FUNCTION: location-set end-point( location-set )
The result location-set contains zero or more locations of type
For each location in the argument location-set, a
equal to the end point of the covering range of the location is added to the
The here() function returns a location-set with a
single member. That location is of type
element, and locates
the element that directly contains (as text) or bears (as an attribute value)
the XPointer. This expression results in a syntax error if the containing
XPointer does not appear in an XML document.
The origin() function enables addressing relative
to out-of-line links such as defined in XLink. This
allows XPointers to be used in applications to express relative locations
when links do not reside directly at one of their endpoints. The function
returns a location-set with a single member, which locates the element from
which a user or program initiated traversal of the link. The
function thus provides a meaningful location-set only if the XPointer is being
processed by application software in response to a request for traversal (see [XLink] for information about traversal).
It is a resource error to use origin() in a locator where a URI is also provided and identifies a containing resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.
The predicate function unique() returns true if and only if context size is equal to 1.
This is particularly useful in applications where a single location is to be located for automated processing and an XPointer that does not locate exactly one location would be in error.
The unique() function may be considered shorthand for the following XPath expression:
It is included because this is considered a very common need for XPointers. Making it a separate expression may also simplify optimization of XPointer evaluation, such as by using methods understood from the treatment of singleton results in database systems.
A string conforms to the XPointer specification if it adheres to the syntactic requirements imposed by this specification (including that part of [XPath] included by reference). There is no requirement that the string, in association with a URI, actually point to a resource that exists at any given moment.
Application software conforms to XPointer if it interprets all XPointer-conforming
strings according to the semantics prescribed by this specification. The syntax
must be recognized and processed correctly regardless of whether full forms
or abbreviated forms are used. This includes supporting both the general framework
for dealing with schemes, and the specific
xpointer scheme. It
also includes providing implementations of all functions defined in this specification,
in addition to the core functions established by the XPath specification.
Conformant applications must recognize and correctly interpret XPointers
that appear as the fragment identifier of a URI-reference which locates a
resource whose Internet media type is
Processing of the results of evaluating the XPointer is defined by the application.
Processing of errors arising from the evaluation of XPointers is defined by
Conformant specifications that use URI-references in relation to resources
whose media type is
are required to use XPointer syntax and semantics for the fragment identifier.
This appendix provides an overview and explanation of the major features of the XPath specification. This is intended for the reader's convenience in understanding this document, which is vitally dependent upon XPath. This section is sufficient to understand the basics of XPath, but the XPath Recommendation [XPath] is the normative definition for XPath and should be consulted for a more detailed understanding of it.
A full-form XPointer consists of the scheme identifier
with an argument that identifies a location by the methods defined here. This
argument may but need not be a LocationPath
as defined in XPath. The cases where it is not are defined in this specification.
For XPointers, the most important type of XPath Expr is the LocationPath. Although there are a number of syntactic abbreviations possible, in general a LocationPath consists of a slash-separated list of LocationSteps of the form:
For example, the following XPath expression would locate the first child
of the context node whose element type is
while the following would locate all
figure elements that
are children of the
List element selected by the previous expression:
In the examples above,
child is the axis-name. An axis-name
specifies a sequence of candidate locations, relative to the "context node"
which is one of several bindings in the "evaluation context". The context
node is bound to a node in the XML document, and axes locate an ordered set
of other nodes in the tree. In the case of the
child axis, the
located nodes correspond to the immediate child elements of the context node.
In the examples above, the
figure. The node-tests eliminate nodes from the result of
an axis that do not match certain criteria. Typically the node-test filters
nodes by their element type, as in the examples above.
In the examples above, the predicate
 is an abbreviated
form of the test
[position() = 1]. Akin to node-tests, predicates
are evaluated for each candidate node and remove it from the results of the
location step unless the predicate evaluates to true. Predicates are evaluated
for each candidate location along the specified axis, and typically test the
element type, attributes, positions, and/or other properties of nodes. Multiple
predicates may be specified as successive filters.
As an additional example, the following expression would locate all children
of the context node that are of element type
para, and then find
the first following sibling of each of those nodes that is of type
Each location step locates an ordered list of data portions. For all the XPath axes, but not for XPointer's additional axes, each location is a node, and any following location steps are interpreted relative to the nodes located.
Location steps can be used in a sequence, interpreted from left to right.
Such sequences are typically used to express a stepwise refinement of a location.
id("MYNOTE")/ancestor::SEC locates all SEC elements
that contain the element whose ID attribute has value "MYNOTE", while
locates the innermost such SEC (that is, the first one in the sequence located,
not the first one in document order).
XPath's axes, summarized in "B.3 XPath Relative Axes", provide access to nodes that bear significant relationships to a starting node, for example as children, following nodes, attributes, and so on.
The axes that XPointer shares with XPath always locate entire nodes (such
as elements, attributes, whole text portions uninterrupted by markup, etc).
string axes (defined
in a later section) locate ranges that are not necessarily aligned on element
boundaries. A common use case for this is when a user selects a range of text
in a browser or word processor and then performs an operation on that range,
such as annotating it. Such locations are not in fact nodes or
lists of nodes, but are ranges as defined in DOM Level 2 (possibly even lists
of ranges, in application scenarios supporting multiple selection). Location
steps using these two axes may not be used to provide contexts for further
XPath provides absolute addresses as well, using an initial slash to locate
the document root, and
id() to locate the node with a given XML
ID value. These are adopted by XPointer without change. XPointer also adds
special absolute addresses as defined below, to make it more effective and
general in a primary application domain: addressing to support hypertext linking.
The axes described in this section depend on the existence of a context node, and locate other nodes relative to each of its nodes in turn. Very commonly, location steps in an XPointer are for the purpose of navigation within the tree. The fundamental navigation directions inherent for ordered trees, therefore have corresponding relative axes.
The candidate nodes along a given axis are ordered by distance from the
context node. Thus, the
preceding-sibling axes consider nodes in reverse document
order. If no prior context is explicitly provided, the context is the root
element of the containing resource.
[Definition:] Each of the relative axes locates a list of nodes that are candidates for membership in the result. Actual results are selected by the node-test and predicate arguments as described below. The relative axes are:
child, but appearing anywhere within the content of the context node.
descendantaxis except that the context node itself is included as a candidate, preceding all descendants. Note: This is particularly useful when a precise location is specified by an ID, but there are constraints on the maximal unit to retrieve, such as always showing the SUMMARY whether the ID is on the summary or on its containing SECTION.
ancestoraxis except that the context node itself is included as a candidate, preceding all ancestors. This axis is particularly useful when a precise location is specified by an ID, but there are constraints on the minimal unit to be treated as the final location, such as always locating the containing
SECTIONwhether the ID is on the
SECTIONor on some particular descendant. For example,
would return the
which has the element with ID "ref37". "ref37" could be on a small leaf element,
an intermediate container, or the
SEC itself. Using the
axis, in contrast, would fail or get a higher
SEC if "ref37"
were on a
SEC element itself.
This axis can also be used to get the effect of inherited attributes (such
as the xml:lang attribute defined in XML 1.0) by locating the list of all
ancestor elements, selecting the desired attribute for each of them (any not
having it drop out), and then taking the last one. For example,
root()last. Ancestors are included.
NodeTests, like predicates (see below), are applied to each context node. Exactly those for which the NodeTest is true remain in the list. XPath provides three forms of NodeTest.
First, QNames (qualified names) can be used to filter by attribute name or element type.
Second, XPath provides the functions comment(), text(), and processing-instruction() for use as NodeTests. They return true if the context node is of the corresponding type.
Third, a Nodetest can be the asterisk (*) wildcard character. When given
by itself, it returns true for any node that is of the principal type of the
axis. The principal type of the
attribute axis is the attribute
type, the principal type of the other axes is the element type.
All XPath's relative axes may use zero or more predicates to filter their candidates. XPointer's syntax and semantics for predicates include all of XPath's except for variables (there is no way to bind variables within an XPointer at this time). XPointer also adds a small number of predicates needed for its application domain. This section summarizes the predicate language of XPath and XPointer's additions.
What is located by a given location step depends on the axis and the predicate(s) -- a node-test may be considered a special-case of a predicate. The axis defines an ordered list of potential candidates, and the predicates (if any) select actual results from among the candidates. The effect is as described below (no particular processing procedure is required; implementations may use any method that produces the results defined in this specification):
If no predicate or node-test is specified, all candidates become members of the resulting node list.
A node-test is a name or an asterisk (*). A node test that is a QName tests
whether the node is an element or attribute with the specified name. For example,
selects the href attribute of the context node; if the context node has no
attribute, it will select an empty set of nodes. The asterisk locates any
element or attribute node regardless of name (but not other node types). Either
a name or an asterisk may be qualified by a namespace, and if so, matching
requires that the namespace prefixes resolve to the same namespace URI.
Several kinds of tests are provided for use within predicates, and are detailed in following sections. For ease of presentation, this section divides them into Positional tests and Local structure tests. The basic tests can be combined with Boolean, numeric, string and other operators, and parentheses; see XPath for the normative specifications of these features.
XPath provides several ways of testing the position of a node within a given node-set. First, the XPath predicate function position() returns the integer position, counting from 1, of the context node within the node-set being considered. For example,
locates the list of all first element children of all element children of the context node.
Positions within the set of siblings in the actual document structure can
be tested by generating that list. For example, the following locates the
item element that is a sibling occurring after the context
The XPath predicate function "last() returns the context
size. For example, the following locates the last
of the context node:
The XPath predicate function count(LocationPath) evaluates
the LocationPath and returns the number of nodes identified. For example,
the following locates all
customer elements which have more than
car element child:
As described above, tests can be made for the XML node type (such as element vs. processing instruction), for the particular element type name of an element, and for attribute-values. Selection using a named element type is strongly recommended, as it increases the chance that an XPointer will locate no data instead of the wrong data, if re-used after the resource changes.
Also, note that location paths can be embedded in other ones as predicates. Such a location path is evaluated relative to the current context node at that point. An embedded location path that returns a non-empty node list, is considered true. This provides very effective ways of characterizing nodes in terms of their document contexts.
Certain predicates such as tests of attribute values can only be fulfilled by certain node types such as elements. It is not an error to apply such predicates to other nodes; they simply will never come out true.
id("intro")/child::*locates all the child elements of the intro node (that is, the node with an ID attribute whose value is "intro"). That is in contrast to
id("intro")/child::node()which locates all the nodes, of any type, that are children of the intro node.
id("intro")/child::paralocates all the element nodes of whose element type (tag name) is
parathat are direct children of the intro node.
id("intro")/child::text()locates all the text nodes that are direct children of the intro node. XPath defines a number of abbreviations. Perhaps the most important of these allows the axis identifier and parentheses to be omitted from a Step. When omitted, the
childaxis identifier is inferred. Thus,
id("intro")/parais equivalent to
id("intro")/descendant::*locates all the descendant element nodes of the intro node. A more common use of the descendants axis is in AbsoluteLocationPaths. For example,
descendant::paralocates all the
paraelements contained in the context node. This is expected to be used frequently enough that XPath provides the string "//" as a very compact abbreviation for
descendant-or-self::node(). The XPathLocationPath
//parawill also select all the
paraelements in the context node.
id("intro")/ancestor::*locates the parent element of the intro element.
id("intro")/attribute::*locates the attributes of the intro element. If the attribute of type ID was also named ID, then
id("intro")/attribute::IDwould locate it.
The first working drafts of this specification were developed in the XML Working Group, whose members are listed in the XML Recommendation [XML]. The work was completed in the XML Linking Working Group, with the following members active at the completion of this specification:
The editors wish to acknowledge substantial contributions by Tim Bray (of Textuality) who served as co-editor on earlier Working Drafts. We would also like to acknowledge substantial contributions from James Clark, especially on the integration with XPath.