xpointer() scheme is intended to be used with the XPointer Framework [XPtrFrame] to provide full XML addressing functionality.
This is a W3C Working Draft for review by W3C members and other interested parties. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress." Comments on this document should be sent to the public mailing list firstname.lastname@example.org (archive).
This specification is being published as an interim Working Draft in order
to show how the
xpointer() scheme portion of the XPointer
Candidate Recommendation published on 11 September 2001 fits into the
current XPointer Framework. This draft does not include any work on disposition
of comments that were reported on the Candidate Recommendation draft.
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 Terms and Concepts
4 Language and Processing
4.2 Additions to XPath Terms and Concepts
4.3 Evaluation Context Initialization
4.4 The point and range Location Types
4.4.1 Definition of Point Location
4.4.2 Definition of Range Location
4.4.3 Covering Ranges for All Location Types
4.4.4 Tests for point and range Locations
4.4.5 Document Order
4.5 Functions Added by the xpointer() Scheme
4.5.1 range-to Function
4.5.2 string-range() Function
4.5.3 Additional Range-Related Functions
22.214.171.124 range Function
126.96.36.199 range-inside Function
188.8.131.52 start-point Function
184.108.40.206 end-point Function
4.5.4 here Function
4.5.5 origin Function
4.6 Root Node Children
xpointer() scheme is intended to be used with the XPointer Framework [XPtrFrame] to provide full XML addressing functionality. This scheme supports addressing into the internal structures
of XML documents and external parsed entities. 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 XML information, whether or not
they bear an explicit ID attribute.
xpointer() scheme is built on top of the XML Path Language [XPath],
which is an expression language underlying the XSL Transformations (XSLT)
xpointer() scheme's extensions to XPath allow it to address points
and ranges as well as whole nodes, and to locate information by string matching.
xpointer() scheme does not cover addressing into the internal structures
of DTDs or the XML declaration.
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 the
See the XPointer Requirements Document [XPREQ] for a thorough
explanation of requirements for the design of the
The terms pointer, pointer part, scheme, XPointer processor, application, error, failure, and namespace binding context are used in this specification as defined in the XPointer Framework specification. Note that errors defined by this specification are distinct from XPointer Framework errors.
The formal grammar for the
xpointer() scheme is given using simple Extended
Backus-Naur Form (EBNF) notation, as described in the XML Recommendation [XML].
The prototypes for
xpointer() scheme 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 normative.
Some special terms are defined here in order to clarify their relationship
to similar terms used in the technologies on which the
xpointer() scheme is
based. Additional terms specific to the
xpointer() scheme are defined in the
flow of the text. Refer to [XPath], [DOM2], [Infoset], and [RFC 2396] for definitions of other technical
terms used in this specification.
A position in XML information. This notion is defined fully later (see point), and 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.
A generalization of XPath's node that includes points and ranges in addition to nodes.
An unordered list of locations, such as produced by an
xpointer() scheme expression.
This corresponds to the node-set that is produced by XPath expressions,
except for the generalization to include points and ranges. Just as for a
node-set, a location-set is treated as having a specific order depending on
the axis that is operating on it. However, this ordering depends on the
extended notion of document order as defined in 4.4.5 Document Order,
rather than XPath's original notion of document order.
This specification normatively depends on the XPointer Framework [XPtrFrame] specification and the XPath [XPath] Recommendation.
It also normatively depends on the XPointer
xmlns() scheme specification [XPtr-xmlns]; XPointer processors claiming to conform to this specification
must also conform to the
Scheme data for the
xpointer() scheme conforms to this specification if it
does not cause an error as described in this specification.
Conforming XPointer processors claiming to support the
xpointer() scheme must
conform to the behavior defined in this specification and may conform to additional
XPointer scheme specifications.
Should need arise to refer to the namespace for objects defined by this
specification, the normative namespace URI for the
xpointer() scheme is
XPath expressions work with a data set that is derived from the elements
and other markup constructs of an XML document. The
xpointer() scheme model
augments this data set. Both
xpointer() expressions 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). Expressions in
xpointer() 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".
This section describes the syntax and semantics of the
xpointer() scheme and
the behavior of XPointer processors with respect to this scheme.
The scheme name is "xpointer". The scheme data syntax
is as follows; if scheme data in a pointer part with the
xpointer() scheme does
not conform to the syntax defined in this section, it is an error and the
pointer part fails.
xpointer() scheme 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.
A generalization of the XPath concepts of nodes, node types, and
node-sets to the
xpointer() scheme concepts of locations (which
subsume nodes, points, and ranges),
and corresponding location types and location-sets.
Rules for establishing the XPath evaluation context.
which return the range location type for selections that are not single XML
to provide for addressing relative to the location of an
xpointer() scheme expression
itself, and to the point of origin for hypertext traversal when expressions
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.
Allowance (as in [XSLT]) for the root node to have multiple child elements, to allow expressions to address into arbitrary external parsed entities as well as well-formed documents.
to address the covering range of location sets.
XPath provides for locating any subset of the nodes in an XML document or external parsed entities. XPath functionality, such as filtering an axis output by predicate, is generally defined in terms of operations on nodes and node-sets.
xpointer() scheme has a requirement to identify document and entity 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, the
xpointer() scheme needs
to be able to apply XPath operations to them as well as to nodes.
To accomplish this, the
xpointer() scheme defines location as
a generalization of XPath's node. Every location is either a point, a range,
or an XPath node. Thus, the
xpointer() scheme also defines location-set as
a generalization of XPath's node-set. All locations generated by XPath constructs
are nodes; constructs defined by the
xpointer() scheme can also identify points
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 expressions that identify ranges of strings, the document order is used, not the display order. Thus, an expression 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 ranges in the underlying document.
xpointer() scheme expression in a pointer part 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 processors must initialize
the evaluation context as described in this section before evaluating an expression:
The evaluation context contains the following information:
A location (the context location), initialized to the root node of an XML document or external parsed entity.
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 processors. Thus, the set of variable bindings used when evaluating an expression is empty, and use of a variable reference in an expression results in failure of the pointer part.
A library of functions. Only functions defined in XPath or this specification can be used in expressions. An expression that uses other functions results in failure of the pointer part.
A namespace binding context consisting of the initial context defined
in the XPointer Framework specification and additional contributions made
by pointer parts having the
xmlns() scheme to the left of the
current pointer part.
When applicable, properties for the locations that the
To address non-node locations, the
xpointer() scheme defines two new location
range, that can appear in location-sets
and can be operated on by XPath node tests and predicates. Locations of the
represent positions and ranges as in DOM Level 2 [DOM2]. This
section defines the
range types and their
characteristics required for XPath interoperability.
Unlike DOM Level 2, which is based on UTF-16 units, XPath and the
xpointer() scheme 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
xpointer() scheme as one character.
Points and ranges can be used as context locations in the
This allows the
 operator to be used to select from sets of
ranges. Also, a point as a context location, when followed by a
selects a range.
[Definition: A location of type point is defined by] [Definition: a node, called the container node, and a non-negative integer, called the index.] It can represent the location preceding or following any individual character, or preceding or following any node in the data set constructed from an XML document or external parsed entity. Two points are identical if they have the same container node and index.
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.
Also note that, while some nodes containing points have explicit boundaries (such as element start-tags and end-tags), the boundaries of text nodes are implicit. Applications that present a graphical user interface for the selection or rendering of points and ranges need to take into consideration the fact that some seemingly identical points, such as the points just inside and just outside the closing boundary of a text node inside an element, are in fact distinguished.
[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 XPath and
xpointer() scheme functions.
[Definition: When the container node of a point is of a node type that cannot have child nodes (i.e., text nodes, comments, processing instructions, attribute nodes, and namespace 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 the point immediately after the nth character of the string-value.
A point location does not have an expanded-name.
The string-value of a point location is empty.
The axes of a point location are defined as follows:
The child, descendant, preceding-sibling, following-sibling, preceding, following, attribute, and namespace axes are empty.
The descendant-or-self axis contains the point itself.
The self axis contains the point itself.
The parent axis contains the point's container node.
The ancestor axis contains the point's container node and its ancestors.
The ancestor-or-self axis contains the point itself, the point's container node, and its ancestors.
A location of type [Definition: 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 point and end point of a range must be in the same document or external parsed entity. The start point must not appear after the end point in document order (see 4.4.5 Document Order).
[Definition: A range whose start point and end point are equal is a collapsed range.]
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, but not to specify a range from text inside a processing instruction to text outside it.
A range location does not have an expanded-name.
The string-value of a range location consists of the characters that are in text nodes and that are between the start point and end point of the range.
The axes of a range location are identical to the axes of its start point. For example, the parent axis of a range contains the parent of the start point of the range.
can be used to navigate with respect to the 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.
For a point location, the start and end points of the covering range are the point itself.
For an attribute or namespace location, 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.
For the 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.
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 start point.
xpointer() scheme extends the XPath production for NodeType... by
adding items for the
range location types.
The production (number 38 in XPath) becomes as follows:
This definition allows NodeTests
to select locations of type
a location-set that might include locations of many types.
xpointer() scheme extends XPath's concept of document order to
cover point and range locations. The concept applies equally in external parsed
A point can be either a node point or a character point. Conceptually, node points label gaps between nodes, while character points occur within a node, between the node points to the right and left of the node.
Thus, an element P has a node point before and after it. If the P element contains sub-elements and/or text nodes, there are node points for the gap before the first child node, between each successive pair of child nodes, and after the last child node; they are numbered in order from 0.
Within any text node, there are character points preceding the first character of the text, between each successive pair of characters, as well as after the last character; they are numbered in order from 0.
For any point, there is an [Definition: 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 n, the immediately preceding node is the nth child of the node-point's container node.
For a node-point with a zero index, the immediately preceding node is the container 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 attribute or namespace nodes (note that the order of attribute and namespace nodes is implementation-dependent).
For a character-point, the immediately preceding node is the container node of the character-point.
The document order of locations is specified here according to the location types to be compared:
As defined by XPath.
A node and point can never be equal in document order. 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.
A node and range can never be equal in document order. A node is before a range if the node is before the start point of the range; otherwise the node is after the range.
Two points P1 and P2 are equal if their immediately preceding nodes are equal and the indexes of the points are equal. P1 is before P2 if P1's immediately preceding node is before P2's, or if their immediately preceding nodes are equal and P1's index is less than P2's. Otherwise P2 is after P1.
A point P is equal to a range R if R's start and end points are both equal to P; otherwise P is before R if P is before or equal to the start point of R; otherwise P is after R.
Two ranges R1 and R2 are equal in document order if their start points are equal and their end points are equal. R1 is before R2 if R1's start point is before R2's start point or if R1's start point is equal to R2's and R1's end point is before R2's; otherwise R2 is after R1.
Note that one consequence of these rules is that a point can be treated the same as the equivalent collapsed range.
xpointer() scheme adds the following functions to those in XPath.
For each location in the context,
a range. The start point of the range is the start point of the context location
(as determined by the
start-point function), and the
end point of the range is the end point (as determined by the
of the location found by evaluating the expression argument
with respect to that context location.
 Step ::= AxisSpecifier NodeTest Predicate* | AbbreviatedStep
The version in the
xpointer() scheme is as follows:
[4xptr] Step ::= AxisSpecifier NodeTest Predicate* | AbbreviatedStep | 'range-to' '(' Expr ')' Predicate*
This change is a single exception for the
It is not a generic change and is not extensible to other functions. The modified
production expresses that a range computation must be made for each of the
locations in the current location list.
As an example of using the
range-to function, the
following pointer part locates the range from the start point of the element
with ID "chap1" to the end point of the element with ID "chap2".
As another example, imagine a document that uses empty elements (such as
revision start and
<REVEND/> for revision end) to mark the
boundaries of edits. The following pointer part would select, for each revision,
a range starting at the beginning of the
REVST element and ending
at the end of the next
location-set string-range(location-set, string, number?, number?)
For each location in the location-set argument,
a set of ranges determined by searching the string-value of
the location for substrings that match the string argument. An
empty string is defined to match before each character of the string-value
and after the final character.White space in a string is matched literally,
with no normalization except that provided by XML for line ends and attribute
values. Each non-overlapping match can contribute a range to the resulting
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.
Thus, both the start point and end point of each range returned by the
will be character points.
For any particular match, if the string argument is not found in the string-value of the location, or if the third and fourth argument indicates a range that is wholly beyond the beginning or end of the document or entity, then no range is added to the result for that match.
The start and end 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 of those "Thomas Pynchon" strings appearing 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 of those "Thomas Pynchon" strings
appearing in a
Alternatively this could be specified as follows:
String-values are "views" into only the string content of
a document or entity; they do not retain the structural context of any non-text
nodes interspersed with the text. Because the
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
is a range describing the relevant substring of the string-value, not necessarily
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 identified by the XPointer
The following expression selects the fifth of those exclamation marks appearing in any text node in the document and the character immediately following that exclamation mark:
Although these examples locate ranges via text in the string-values of
string-range is useful for locating ranges
that are wholly enclosed in other node types as well, such as attributes,
processing instructions, and comments.
The following functions are related to ranges.
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.
range-inside function returns locations covering
the contents of the locations in the argument location-set. For each location x in
the argument location-set, a location is added to the result location-set.
If x is a range location or a point, then x is added
to the result location-set. Otherwise x is used as the container
node of the start and end points of the range location to be added, which
is defined in this way: 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; otherwise its index is the number of children
For each location x in the argument location-set,
a location of type point to the resulting location-set. That point represents
the start 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 start point of x.
If x is of type root, element, text, comment, or processing instruction, the container node of the resulting point is x and the index is 0.
If x is of type attribute or namespace, the pointer part in which the function appears fails.
For each location x in the argument location-set,
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 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.
If x is of type attribute or namespace, the pointer part in which the function appears fails.
here function is meaningful only when the expression
being interpreted occurs in an XML document or external parsed entity; otherwise
the pointer part in which the
here function appears fails.
When in an XML context, the
here function returns a location-set
with a single member. There are two possibilities for the location returned:
If the expression being evaluated appears in a text node inside an element node, the location returned is the element node.
Otherwise, the location returned is the node that directly contains the expression being evaluated.
In the following example, the
here function appears
inside an expression that is in an attribute node. The expression as a whole,
then, returns the
slide element just preceding the
that most directly contains the attribute node in question.
<button xlink:type="simple" xlink:href="#xpointer(here()/ancestor::slide/preceding::slide)"> Previous </button>
The type of the node in which the
here function appears
is likely to be
The returned location for an expression appearing in element content does
not have a node type of
element because the expression is in
a text node that is itself inside an element.
origin() function is meaningful only when the expression
is being processed in response to traversal of a link expressed in an XML
origin function enables addressing relative
to third-party and inbound links such as defined in the XLink Recommendation.
This allows expressions 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. (See [XLink] for information about traversal.)
It is an error to use
origin in the fragment identifier
portion of a URI reference where a URI is also provided and identifies a resource
different from the resource from which traversal was initiated, or in a situation
where traversal is not occurring.
The XML Recommendation requires well-formed documents to contain a single
element at the top level. Thus, the XPath data model of a well-formed document
will have a root node with a single child node of type element. In order to
address locations in arbitrary external parsed entities, along with well-formed
xpointer() scheme extends the XPath data model to allow the root
node to have any sequence of nodes as children that would be possible of an
element node. This extension is identical to the one made by XSLT. Thus, the
root node may contain child nodes of type text, and any number of child nodes
of type element.
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:
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.