This specification defines the XML Pointer Language (XPointer), the language
to be used as the basis for 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 examination of a hierarchical document structure and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position.
This document is a Candidate Recommendation of the World Wide Web Consortium. (For background on this work, please see the XML Activity Statement.) This specification is considered stable by the XML Linking Working Group and is available for public review during the Candidate Recommendation stage ending 7 September 2000.
The Working Group invites implementation feedback during this period. Comments on this document should be sent to the public mailing list email@example.com (archive). 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.
This document is intended to be taken in conjunction with the IETF XML
Media Types Internet Draft [IETF I-D XMT], in order for
that document to officially designate XPointer as the fragment identifier
because of the timing problems associated with publishing two related documents
on separate tracks, currently that document refers to this one only non-normatively.
It is anticipated that the Internet Draft will be updated to make a normative
reference when XPointer reaches the Recommendation stage.
The W3C Director has been informed of a Patent (U.S. Patent 5659729, issued 19 Aug 1997 to Sun Microsystems) that may cover parts of XPointer. As of June 7 2000, W3C did not receive an official answer from the patent owner on this issue; any update will be sent to the public mailing list firstname.lastname@example.org for archival.
For information about the XLink language with which XPointer is expected to be used, see http://www.w3.org/TR/xlink/.
For information about the requirements that informed development of this specification, see http://www.w3.org/TR/NOTE-xptr-req.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/.
1.1 Origin and Goals
1.2 Notation and Document Conventions
2 XPointer Terms and Concepts
3 XPointer Processing and Conformance
3.1 Processing Dependencies
3.2 String Conformance
3.3 Application Conformance
3.4 Specification Conformance
3.5 Classes of XPointer Errors
4 XPointer Model and Language
4.1 Character Escaping
4.1.1 URI Reference Encoding and Escaping
4.1.2 XML Escaping
4.1.3 XPointer Escaping
4.2 Forms of XPointer
4.2.1 Full XPointers
4.2.2 Bare Names
4.2.3 Child Sequences
5 XPointer Extensions to XPath
5.1 XPointer Additions to XPath Terms and Concepts
5.2 Evaluation Context Initialization
5.3 The point and range Location Types
5.3.1 Definition of Point Location
5.3.2 Definition of Range Location
5.3.3 Covering Ranges for All Location Types
5.3.4 Tests for point and range Locations
5.3.5 Document Order
5.4 XPointer Functions
5.4.1 range-to Function
5.4.2 string-range() Function
5.4.3 Additional Range-Related Functions
5.4.4 here Function
5.4.5 origin Function
5.4.6 unique Predicate Function
This specification defines the XML Pointer Language (XPointer), the language
to be used as the basis for 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, although it provides
extension facilities that may be used with
XPointer supports addressing into the internal structures of XML documents. It allows for examination of a document's hierarchical structure 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 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 underlying the XSL Transformations (XSLT) language. XPointer's extensions to XPath allow it to:
Address points and ranges as well as whole nodes
Locate information by string matching
Use addressing expressions in URI references as fragment identifiers (after URI-escaping)
Addressing into the internal structures of DTDs and the XML declaration is outside the scope of this specification.
XPointer is intended to be the basis of fragment identifiers only for the
application/xml 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. (Note that a recent Internet Draft [IETF I-D XMT]
suggests the use of a naming convention 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 (discussed
in 4.3 Schemes) can be used to perform special access to the
content of those media types.
In addition to XPath, the following standards have been especially influential in the development of this specification:
HTML [HTML]: This system popularized an important location specifier type, the URL (now URI).
HyTime [ISO/IEC 10744]: This ISO standard defines location specifier types for all kinds of data.
Text Encoding Initiative Guidelines [TEI]: This application provides a formal syntax for "extended pointers," locators for structured markup that underlie the initial design for XPointer.
See the XPointer Requirements Document [XPREQ] for a thorough explanation of requirements for the design of XPointer.
The formal grammar for XPointer is given using a simple Extended Backus-Naur
Form (EBNF) notation, as described in the XML Recommendation [XML].
The circumflex (
^) metacharacter used in this notation is not
to be confused with the circumflex used to escape parenthesis characters in
The prototypes for XPointer functions are given using the same notation used in the [XPath] Recommendation.
This specification contains some explanatory text on the XPath language; however, such text is non-normative. In the case of conflicts, [XPath] is the normative version.
Some special terms are defined here in order to clarify their relationship to similar terms used in the technologies on which XPointer is based. Additional XPointer-specific terms are defined in the flow of the text. Refer to [XPath], [DOM2], [XIS], and [IETF RFC 2396] for definitions of other technical terms used in this specification.
The portion of an XML resource that is identified by an XPointer. For example, the whole resource being referred to is an XML document, but a sub-resource might be a particular element inside the document. Following a link to such a sub-resource might result, for example, in highlighting that element or scrolling to that point in the document.
An ordered list of document nodes, points, and/or ranges, such as produced by an XPointer expression. This corresponds to the node-set that is produced by XPath expressions, except for the generalization to include points and ranges.
A position in XML information. This notion comes from the DOM Level 2 [DOM2] specification's notion of positions; this specification refers to DOM positions by the term "point" to avoid confusion with XPath positions.
An identification of a contiguous selection of all the XML information between a pair of end points. This notion comes from the DOM Level 2 [DOM2] specification.
A location that consists of a single, contiguous portion of a document.
Some XPointers can locate multiple data portions, such as three contiguous
element nodes in a
list or six noncontiguous occurrences of a string
in a document. When an XPointer instead locates only a single contiguous data
portion such as a range, string range,
or single node, that location is said to be a singleton. (See 5.4.6 unique Predicate Function
for an example.)
This section details processing and conformance requirements on XPointers, the fragment identifiers that are based on them, and the applications that create and process them.
A string conforms to the XPointer specification if it adheres to the syntactic requirements imposed by this specification (including [XPath], whose requirements are imposed by reference). This specification does not require that the string, in association with a URI, actually point to a resource or sub-resource that exists at any given moment.
Application software conforms to this specification if it recognizes XPointers
that appear (suitably escaped) as the fragment identifier of a URI reference
which locates a resource whose Internet media type is
application/xml, and correctly interprets such fragment identifiers
according to the semantics prescribed by this specification. Processing of
the results and/or errors arising from evaluation of an XPointer is defined
by the application.
Specifications that use URI references in relation to resources whose media
application/xml are required
to use XPointer syntax (suitably escaping) and semantics for the fragment
The use of XPointers can give rise to several kinds of errors:
[Definition: A string that does not match the syntax specified in this document has a syntax error, and applications must not attempt to evaluate it as an XPointer.]
[Definition: If a syntactically correct XPointer fragment identifier is appended to a URI that identifies no resource, or a resource that is not well-formed XML, the XPointer has a resource error.]
[Definition: If a syntactically correct XPointer fragment identifier fails as discussed in 4.3 Schemes, the XPointer has a sub-resource error.] Note that XPath allows expressions that return empty node-sets as their results and does not regard this situation as an error. Because the XPointer language is intended as a specification of document locations rather than a broader query language, an empty result is an error.
This specification does not constrain how applications deal with these errors.
XPointers, like XPath expressions, operate on the XML information set [XIS], a data set derived from the elements and other markup constructs of an XML document. Both XPointers and XPath expressions operate by selecting portions of such data sets, often by their structural relationship to other parts (for example, the parent of a node with a certain ID value). XPointers use iterative selections, each operating on what is found by the prior one.
Selection of portions of the information hierarchy is done through axes, predicates, and functions. An axis defines a sequence of candidates that might be located; predicates then test for various criteria relative to such portions; and functions generate new candidates or perform various other tasks. For example, one can 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 "para".
The XPointer language is designed to be used in the context of URI references, which require encoding and escaping of certain characters. XPointers also often appear in XML documents, and the XML context imposes some escaping requirements of its own. Finally, because some characters are significant to XPointer processing, escaping is needed to use these characters in their ordinary sense.
For convenience, this section describes the escaping necessary for these contexts. However, see [IETF RFC 2396], [IETF RFC 2732], and [XML] for definitive information on characters that must be escaped before use.
This specification governs the syntax of XPointers that have not yet been treated for use in URI references or other contexts.
The set of characters for XPointers is the same as for XML, namely [Unicode]. However, some Unicode characters are disallowed from URI references, and thus XPointers that appear in URI references must encode and escape these characters as appropriate. [Definition: The URI-escaped form of an XPointer is called an XPointer fragment identifier.]
The disallowed characters include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of [IETF RFC 2396], except for the crosshatch (#) and percent sign (%) characters and the square bracket characters re-allowed in [IETF RFC 2732]. Disallowed characters must be escaped as follows:
Each disallowed character is converted to UTF-8 [IETF RFC 2279] as one or more bytes.
Any octets corresponding to a disallowed character are escaped with
the URI escaping mechanism (that is, converted to
where HH is the hexadecimal notation of the byte value).
The original character is replaced by the resulting character sequence.
For example, if spaces are used between parts of an XPointer, the spaces need to be escaped in the XPointer fragment identifier. In XPointer, square brackets also appear frequently; while [IETF RFC 2732] allows them to appear untreated, they should be escaped for compatibility with applications that have not implemented the [IETF RFC 2732] update to [IETF RFC 2396].
The following example shows an XPointer containing various characters that might need special treatment: spaces, brackets, and accented characters:
The following example shows the resulting XPointer fragment identifier appearing as part of a URI reference, where these characters have been escaped:
Applications that encounter what is intended to be an XPointer fragment identifier must resolve the encoding and escaping in the reverse order of the process described in this section. If the result does not conform to the syntactic rules for XPointers in this specification, a syntax error results.
When XPointers appear in XML document content, they must
escape occurrences of left angle brackets (<), ampersands (&), and
other special characters according to the directions in [XML].
One option is to use
for left angle brackets and ampersands.
For example, an XPointer that identifies the first five
elements of a document would need escaping because of the left angle bracket
in its comparison operator.
The unescaped XPointer is as follows:
xpointer(book/chapter position() <= 5)
The XML-escaped XPointer appearing in an XLink link is as follows:
<simpleLink xmlns:xlink="http://www.w3.org/2000/xlink" xlink:type="simple" xlink:href="doc.xml#xpointer(book/chapter position() <= 5)" />
Note that if XML-based languages define elements or attributes containing
URI references (such as XLink's
href attribute shown above), the
relevant element content or attribute values also require the processing defined
in 4.1.1 URI Reference Encoding and Escaping.
The parts of an XPointer each contain a balanced pair of parentheses that delimit the XPointer information. In order for the outermost ending parenthesis to be reliably recognized by an XPointer application, parentheses inside it must be balanced as well. Any unbalanced parenthesis character must be escaped. See 4.2 Forms of XPointer for more information.
This specification defines one full form of XPointer addressing and two shorthand forms. The shorthand forms are defined as abbreviations of the full form, although applications 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 full form is described in 4.2.1 Full XPointers. The two short forms are bare names (Name, described in 4.2.2 Bare Names) and child sequences (ChildSeq, described in 4.2.3 Child Sequences). Thus, XPointer offers the following overall options.
The internal structure of an XPointer is as follows.
|ChildSeq||::=||'/1' ('/' [0-9]*)*|
|| Name ('/' [0-9]*)+|
|FullXPtr||::=||XPtrPart (S? XPtrPart)*|
|XPtrPart||::=||'xpointer' '(' XPtrExpr ')'|
|| Scheme '(' SchemeSpecificExpr ')'|
|Scheme||::=||NCName - 'xpointer'||[VC: Non-XPointer schemes]|
|StringWithBalancedParens||::=||[^()]* ('(' StringWithBalancedParens ')' [^()]*)*||[VC: Parenthesis escaping]|
|XPtrExpr||::=||Expr||[VC: Parenthesis escaping]|
no schemes other than
xpointer are allowed. See 4.3 Schemes
for more information.
The end of an
XPointer part is signaled by the right parenthesis ")" character
that is balanced with the left parenthesis "(" character that
began the part. Any unbalanced parenthesis character inside the expression,
even within literals, must be escaped with
a circumflex (^) character preceding it. If the expression contains any literal
occurrences of the circumflex, each must
be escaped with an additional circumflex (that is,
^^). If the
unescaped parentheses in the expression are not balanced, a syntax
Name and S are as defined in the XML Recommendation [XML]; NCName is as defined in the Namespaces in XML Recommendation [XML-Names]; and Expr is as defined in the XPath Recommendation [XPath], with the XPointer extensions defined in this specification.
The full form of addressing consists of one or more XPointer parts, optionally
separated by whitespace. Each starts with a scheme name and is followed by
a parenthesized expression. When the scheme is
xpointer (see 4.3 Schemes for more information), the associated expression provides
access to nodes in an XML document's information set (except for nodes representing
CDATA sections and entities) and access to arbitrary non-node locations.
The appearance of a "bare name" stands for the same name provided
as the argument of a location step using the
id() function. For
example, the first XPointer below is the bare-name equivalent of the second,
which uses the full XPointer form:
The bare-name shorthand is provided for two reasons:
To provide an analog of the HTML fragment identifier behavior for resources with XML media types that use a markup language similar to that of HTML. (Note that the XHTML specification [XHTML] defines some guidelines for anchors that help the bare-name shorthand to work in concert with the HTML fragment identifier in cases of content negotiation.)
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 form
The first segment of the child sequence can be either a name, which locates
an element as described for bare names in 4.2.2 Bare Names, or
/1, which locates the document element. For example,
the following two XPointers would locate the same XML information, where
is the ID attribute value of an element that is the fifth child of the second
child of the document element:
In a full-form XPointer, an initial Scheme identifies the particular notation used for each XPtrPart. Having an explicit Scheme 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 themselves.
Because there is no way to avoid conflicts in scheme naming and use, the
only scheme allowed in this version of the XPointer specification is
All other scheme names are reserved. Users who want to define or use new schemes
are invited to check the XPointer errata document [ERR]
for a possible solution.
This specification defines two items related to the Scheme.
The first is the general framework for identifying the scheme and the ability
to skip over schemes that are not understood. The second is the behavior when
the Scheme is
An unknown scheme
A scheme that does not locate any sub-resource present in the resource
A scheme that is not applicable to the media type of the resource
The XPointer application must consume a failed XPointer part and attempt to evaluate the next one, if any. The result of the first XPointer part whose evaluation succeeds is taken to be the fragment located by the XPointer as a whole. If all the parts fail, the result for the XPointer as a whole is a sub-resource error.
This approach allows alternative addressing mechanisms to be specified, which can allow for more robust addresses in the presence of features such as content negotiation or user-selected limits on network access. For example, the following XPointer 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. An XPointer like the following, with
two parts, will have its first part fail if no DTD is available, but will
have its second part succeed if the desired attribute's name
id; note that the intent of the second XPointer part is just
an approximation of the first.
Because fragment identifiers are specific to the media type of the accessed 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 varies due to content negotiation. For example, a server might return a detailed text description when the user's client does not support graphics; the fragment identifier could contain both an xpointer-scheme XPointer part as well as (eventually) a media-type-specific scheme for the graphic, perhaps identifying coordinates of a graphical region.
XPointer extends XPath by adding the following:
Two new location types,
corresponding to DOM positions and ranges, that can appear in location-set
results; also tests (akin to node tests) for these location types.
Rules for establishing the XPath evaluation context.
which return the range location type for selections that are not single XML
information set nodes.
to provide for addressing relative to the location of an XPointer expression
itself, and to the point of origin for hypertext traversal when XPointers
are used in that (very common) application domain.
to address the beginning and ending locations which bound another location
such as a node or range.
The predicate function
unique, to enable testing
whether an XPointer expression or sub-expression locates a singleton rather
than multiple locations or no locations.
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 might have different sets of ancestors in the hierarchy, or the region might form only a small part of a node. For example, a range could be a single letter or could extend from the middle of one paragraph to the middle of the next, thus containing only part of the relevant paragraphs 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.
The order of characters displayed on a computer screen might not reflect their order in the underlying XML document, for example, when a portion of a right-to-left language such as Arabic is embedded in a left-to-right language such as French. For XPointers that identify ranges of strings, the document order is used, not the display order. Thus, an XPointer for a single range might be displayed non-contiguously, and conversely a user selection of an apparent single range might correspond to multiple non-contiguous XPointer ranges in the underlying document.
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. XPointer applications must initialize the evaluation context as described in this section before evaluating an XPtrExpr.
An XPointer evaluation context contains the following information:
A location (the context location), initialized to the root node of an XML document. When the XPointer is a fragment identifier of a URI reference, the document is the one identified by the URI portion. If an application uses XPointers in another context than as a URI reference's fragment identifier, this specification does not constrain how the applicable document is chosen.
A non-zero context position, initialized to 1.
A non-zero context size, initialized to 1. (At the start, the only location in the current location list is the context location.)
A set of variable bindings. No means for initializing these is defined for XPointer applications. Thus, the set of variable bindings used when evaluating an XPointer is empty, and use of a variable reference in an XPointer results in a syntax error.
A library of functions. Only functions defined in XPath or XPointer can be used in XPointers. An XPointer that uses other functions results in a syntax error.
The set of namespace declarations in scope for the expression. For any XPointer fragment identifier that appears in an XML document, the namespace declarations in the evaluation context of the XPointer must be initialized to the namespace declarations currently in scope for the XPointer.
For any XPointer fragment identifier
that does not occur in an XML document, the namespace declarations must be initialized so that the
is bound to the URI
http://www.w3.org/XML/1998/namespace. No other
namespace declarations shall be in its evaluation
If an XPointer subsequently gets used in another document (for example, through a copy-and-paste user interface), the application may need to perform a transformation on the XPointer to ensure that the desired sub-resource is explicitly namespace-qualified, so that additional context is not needed.
For example, if there is an XML document containing an element
that is in the scope of a namespace declaration
then the following XPointer will work properly if it appears in the scope
of this declaration:
If this XPointer is moved or copied to an XML document where such a namespace declaration is not in force or to a non-XML document, it can still address the desired element properly if it is transformed to the following form:
xpointer(//*[local-name()='y' and namespace-uri()='http://example.com/bar'])
It is possible that an apparent XPointer (conforming to the syntax defined
in this specification) is not a real XPointer because the media type of the
target resource turns out not to be
only accessing the target resource can determine this for sure. However, for
the purpose of transplanting XPointers to new locations, access is not required;
if the fragment identifier merely matches the XPointer syntax and has an
scheme, then it should be expanded as appropriate.
To address non-node locations, XPointer defines two new location types,
range, that can appear in location-sets and can be operated
on by XPath node tests and predicates. Locations of the
range type represent positions and ranges as in DOM Level
2 [DOM2]. This section defines the
types and their characteristics required for XPath interoperability.
Unlike DOM Level 2, which is based on UTF-16 units, XPath and XPointer are based on UCS characters. So while the concepts of points and ranges are based on the DOM 2 notions of positions and ranges, there are differences in detail. For example, a sequence which in DOM counts as two characters might count in XPointer as one character.
Points and ranges can be used as XPointer context locations. This allows
 operator to be used to select from sets of ranges.
Also, a point as a context location, when followed by a
function, selects a range.
[Definition: A location of type point is defined by a node, called the container node, and 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.
This specification does not constrain the implementation of points; applications need not 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, when 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.
The zero-based counting of node-points differs from the one-based counting
string-range and other XPointer and XPath functions.
[Definition: When the container node of a point is of a node type that cannot have child nodes (such as text nodes, comments, and processing instructions), 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 point location has no children.
A character-point has no preceding or following siblings.
A node-point's siblings are the children of the container node that are before or after the node-point.
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 might be only 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 node. For example, it is allowed to specify a range from the start of a processing instruction to the end of an element (encompassing both those nodes, but still a singleton), but not to specify a range from text inside a processing instruction to text outside it.
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 start point.
functions can be used to navigate with respect to the respective boundaries
of a range location.
[Definition: A covering range is a range that wholly encompasses a location.] For every location, a covering range is defined as follows:
For a range location, the covering range is identical to the range.
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.
root location, 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.
point location, the start and end points of the
covering range are the point itself.
For any other kind of location, the container node of the start point and end point of the covering range is the parent of the location; the index of the start point of the covering range is the number of preceding sibling nodes of the location; and the index of the end point is one greater than the index of the starting point.
This definition ensures that for a range location, as for every other type of location, the ancestor, preceding, following, descendant, and self axes do not intersect and that they together contain all locations in the document (other than attribute, namespace, and range locations).
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 might 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 a node-point with a non-zero index, the immediately preceding node is the node immediately preceding the point (that is, the node that is the nth child of the container node, where n is the index).
For a node-point with a zero index, the container node is also the immediately preceding node unless it has any attribute or namespace nodes. If the container node does have attribute or namespace nodes, then the immediately preceding node is the last of those nodes.
For a character-point the immediately preceding node is the container node of the character-point.
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:
If the immediately preceding nodes of the two points are the same, then either the points are the same or they are both character-points with the same container node; in the latter case, the order of the indices determines the document order.
Otherwise, the document order of the immediately preceding nodes of the points determines the document order of the points.
One range node is before another range node if and only if
the starting point of the one range is before the starting point of the other range, or
the starting point of the one range is the same as the starting point of the other range, and the ending point of the one range is before the ending point of the other range.
XPointer adds the following functions to those in XPath; these functions must be provided by XPointer applications.
location-set range-to(expression )
For each location in the context,
a range. The start point of the range is the start of the context location,
and the end point of the range is the end of the location found by evaluating
the expression argument with respect to
that context location.
For example, the following XPointer locates the range from the element with ID "chap1" to the element with ID "chap2".
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
XPath does not permit functions immediately following the slash as shown here; XPointer does.
location-set string-range(location-set , string, number?, number? )
[Definition: For each location in
the location-set argument,
string-range returns a set
of string ranges, a set of substrings in a string. Specifically,
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 and after the final character. Whitespace in a string
is matched literally, with no normalization except that provided by XML for
line ends. 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
Element boundaries, as well as entire embedded nodes such as processing instructions and comments, are ignored as defined in [XPath].
If the string in the second argument is not found in the string-value of the location, or if a value in the third or fourth argument indicates a string that is beyond the beginning or end of the document, the expression fails.
The points of the range-locations in the returned location-set will all be character points.
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:
String-values are "views" into only the string content of
a document; they do not retain the structural context of any non-text nodes
interspersed with the text. Because the
function operates on a string-value, markup that intervenes in the middle
of a string does not prevent a match. (Note that for this reason, a
match is on the range describing the relevant substring of the string-value,
not necessarily on a contiguous string in a single text node in the document.)
For example, if the 17th occurrence of "Thomas Pynchon" had some
inline markup in it as follows, it would not change the string returned by
the XPointer application:
The following expression selects the fifth exclamation mark in any text node in the document and the character immediately following it:
Although these examples locate ranges in elements,
is useful for locating ranges that are wholly enclosed in other node types
as well, such as attributes, processing instructions, and comments.
location-set range(location-set )
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.
location-set range-inside(location-set )
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.
For each location x in the argument location-set,
adds a location of type point to the result location-set. That point represents
the start point of location x and is determined by the following
If x is of type point, the start point is x.
If x is of type range, the start point is the start point of x.
If x is of type root, element, text, comment, or processing instruction, the container node of the start point is x and the index is 0.
For each location x in the argument location-set,
adds a location of type point to the result location-set. That point represents
the end point of location x and is determined by the following
If x is of type point, the resulting point is x.
If x is of type range, the resulting point is the end point of x.
If x is of type root or element, the container node of the resulting point is x and the index is the number of location children of x.
If x is of type text, comment, or processing instruction, the container node of the resulting point is x and the index is the length of the string-value of x.
here function returns a location-set with a single
member. That location locates the node that directly contains the XPointer
being evaluated. This expression results in a syntax
error if the resource in which the containing XPointer appears is
The type of the node is likely to be
processing-instruction. The returned location for an XPointer
appearing in element content does not have a node type of
because the XPointer is in a text node that is itself inside an element.
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 traversal instruction from
an XML document. (See [XLink] for information about traversal.)
It is a resource error to use
in the fragment identifier portion of a URI reference 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
The predicate function
unique returns true if and
only if context size is equal to 1.
This is particularly useful in applications where a singleton location is to be located for automated processing and an XPointer that does not locate exactly one location would be in error.
unique function is shorthand for the following
Making this its own function might simplify optimization of XPointer evaluation, such as by using methods understood from the treatment of singleton results in database systems.
Note that different XPointers can create different location-sets that cover
similar document scopes in the same XML information, but where the sets divide
up the scopes differently: retrieving a set of smaller locations, as opposed
to the range the covers the same total scope. For example, consider a
element with ID "list37", which contains three
element children, but no other children. The following XPointer returns a
location-set that has three members, the
item children in that
The returned location-set will not be a singleton: it has as many members
as there are
item children. In contrast, the following XPointer returns
a singleton location-set:
This singleton happens to start at the same point that the first member
of the location-set just shown does, and end at the same point that the last
member of it does; but it is not the same location-set: It is a singleton
location-set whose one member is a range, not a three-member location-set
whose members are
item element nodes.
The first working drafts of this specification were developed in the XML Working Group, whose members are listed in [XML]. The work was completed in the XML Linking Working Group, with the following members active at the completion of this specification:
Peter Chen (LSU, Bootstrap Alliance)
Ron Daniel (Metacode Technologies, Inc.), XPointer co-editor
Steve DeRose (invited expert), XPointer co-editor
David Durand (University of Southhampton, Boston University, Dynamic Diagrams)
Masatomo Goto (Fujitsu Laboratories)
Paul Grosso (Arbortext)
Chris Maden (Yomu)
Eve Maler (Sun Microsystems), co-chair and XPointer co-editor
Murray Maloney (Commerce One)
Jonathan Marsh (Microsoft)
David Orchard (invited expert)
Ben Trafford (invited expert)
Daniel Veillard (W3C staff contact), co-chair
The editors wish to acknowledge substantial contributions from Tim Bray, who previously served as co-editor and co-chair. We would also like to acknowledge substantial contributions from James Clark, especially on the integration with XPath. We would like to thank Gavin Nicol and Martin Dürst for help with passages related to internationalization. Finally, we would like to thank the XML Linking Interest Group and Working Group for their support and input.