&abstract;
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
This document has been produced by the
There are patent disclosures and license commitments associated with
this working draft, which may be found on the
This specification is one of four into which the prior XPointer specification has been divided. This version addresses comments received on the
xpointer() scheme it defines. Except for responding to the relevant Last Call comments, and incorporating non-substantive editorial improvements, this documents is substantially identical to that part of the Last Call XPointer specification which is not covered by
A list of current W3C Recommendations and other technical documents can be
found at
&abstract; 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 portions 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.
The &scheme-phrase; is built on top of the XML Path Language
The &scheme-phrase; does not cover addressing into the internal structures of DTDs or the XML declaration.
In addition to XPath, a number of prior systems and standards have helped guide the development of this specification; these are listed in the non-normative references section.
The terms pointer, pointer part, scheme, XPointer processor, application, error, failure, and namespace binding context are used in this specification as
The formal grammar for the &scheme-phrase; is given using simple Extended Backus-Naur Form (EBNF) notation, as described in the XML Recommendation
The prototypes for &scheme-phrase; functions are given using the same notation used in the
This specification explicitly extends some aspects of the syntax and semantics of XPath (mainly in relation to support for locations other than whole nodes). Except in such cases,
Some special terms are defined here in order to clarify their relationship
to similar terms used in the technologies on which the &scheme-phrase; is
based. Additional terms specific to the &scheme-phrase; are defined in the
flow of the text. Refer to
A location in an XML Information Set with no content or children. For example, the location between two adjacent nodes, or after a particular character within a text node.
This notion is defined fully later (see point
to avoid confusion with XPath positions.
An identification of all the XML Information Set content between a pair of points.
This notion is defined fully later (see
A generalization of XPath's
An unordered list of locations, such as produced by an &scheme-phrase; expression.
This corresponds to the
Conforming XPointer processors claiming to support the &scheme-phrase; must conform to the behavior defined in this specification and may conform to additional XPointer scheme specifications.
This specification is intended for use with the XPointer Framework
This specification normatively refers to the XPath
This specification also normatively uses the XPointer xmlns() scheme specification xmlns() specification.
Scheme data for the &scheme-phrase; conforms to this specification if it does not cause an error as described in this specification.
Should need arise to refer to the namespace for objects defined by this
specification, the normative namespace URI for the &scheme-phrase; is http://www.w3.org/2001/05/XPointer.
XPath expressions work with a data set that is derived from the elements
and other markup constructs of an XML document. The &scheme-phrase; model
augments this data set. Both &schemename;() 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). The &schemename;(), like XPath, uses iterative
selections, each operating on what is found by the prior one.
Selection of portions of the information hierarchy is done through three main constructs: axes,
predicates, and functions (constructs defined in XPath footnote
. Another expression could
identify the point location immediately preceding a certain element (which in turn was identified by ID or other tests).
This section describes the syntax and semantics of the &scheme-phrase; and the behavior of XPointer processors with respect to this scheme.
The scheme name is &schemename;
.
If scheme data in a pointer part with the &scheme-phrase; does
not conform to the syntax defined in this section, it is an error and the
pointer part fails.
The &scheme-phrase; extends XPath by adding the following:
A generalization of the XPath
Two new location types, point and range,
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.
Allowance (as in
The functions
The functions
The function
The function
The functions
XPath provides for locating any subset of the
The order of a location's characters as displayed on a computer screen might not reflect their order in the underlying XML document. For example, this may occur 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.
An &scheme-phrase; expression in a pointer part (as defined in the XPointer Framework
A location (the
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 &scheme-phrase; 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 &scheme-phrase; 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 any pointer parts having the xmlns() scheme to the left of the
current pointer part.
When applicable, properties for the locations that the
For non-node locations,
Unlike DOM Level 2, which is based on UTF-16 units, XPath and the &scheme-phrase; are based on UCS characters. So while the concepts of points and ranges are based on the notions of positions and ranges, there are differences in detail. For example, a sequence which in DOM counts as two characters might count in the &scheme-phrase; as one character.
Points and ranges can be used as context locations in the &scheme-phrase;.
This allows the [] operator to be used to select locations from location sets in general.
The
The
The zero-based counting of node-points is compatible with that of DOM 2
As defined, points are sufficient to identify 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.
Given this definition, two points are necessarily identical if they have the same container node and index.
This specification does not constrain the implementation of points; XPointer processors need not actually represent points using data structures consisting of a node and an index.
Also note that while some nodes 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 points that might not be distinguished in the user interface, such as the points just inside and just outside the closing boundary of a text node inside an element, are in fact distinct.
A point location does not have an
The
The
The
The
The
The
The
The
A location of type
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
A range location does not have an
The
The axes of a range location are identical to the axes of its start point.
For example, the
For a range location, the covering range is identical to the range (note that
as in DOM
For a point location, the start and end points of the covering range are the point itself.
For a node location that is an element, text, comment, or processing instruction node, the container node of the start point and of the end point of the covering range are both the parent of the identified node; 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.
For a node location that is the root node, the container node of the start point and end point of the covering range are both 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 a node location that is an attribute or namespace node, the container node of
the start point and end point of the covering range is the attribute or namespace
node itself; 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
point and range Locations
The &scheme-phrase; extends the XPath production for point and range location types.
The production (
This definition allows point and range from
a location-set that might include locations of many types.
XPointer must be able to represent locations that are entire element nodes, like XPath; but also locations that are not. For example, an edit insertion point does not correspond to any whole node, but rather to a zero-size location, such as the point immediately preceding a character of text within a text node or between two adjacent element nodes. Similarly, typical drag-selections in various applications correspond to
As in DOM 2: Range
The appendix "On points and ranges" provides a simple notation that is similar in syntax to the XPointer
The diagram below shows the numbering of nodes and points in a graphic representation of an XML Information Set.
Figure 1: Numbering of nodes and points
For example,
point(1.0) is just inside the beginning of the p element.
point(1.2) is between the end of the em element and the following text
node (which contains "world.").
point(.0) immediately precedes the root node.
point(1/2/1.1) immediately following the "b" in the middle text node.
Intuitively, points are ordered largely as one would expect from a pre-order traversal of the document, or the XML stream order.
More formally, any two document locations that are comparable, regardless of which type(s) they are, can be compared by comparing their
Because text nodes are not explicitly represented in XML documents, the point immediately before (or after) a text node occurs at the same place in an XML source document as the point immediately before (or after) that text node's first (or last) character. This specification defines those locations as distinct; they do not compare as equal. For example, point(1.2) is not equal to point(1/3.0).
Because the attribute and namespace nodes of a given element node are unordered, it is illegal to compare them in certain ways, and the result of such an attempted comparison is undefined. Specifically:
Points within different attribute and/or namespace nodes of the same container node may not be compared.
A point within an attribute or namespace node may not be compared to the location of its container node.
A point within an attribute or namespace node, however, may be compared to any node other than its parent node or to any point within any node other than its parent node. In such comparisons, the point is ordered as its parent node would be.
Two points within the
Points within the same container node compare as do the values of their respective offsets.
Points within different nodes
To compare any comparable points P1 and P2:
point(.0) compares as before any other point; point(.1) compares as after any other point.
Define Node1 as the child sequence of the node directly containing point P1, and Node2 as the child sequence of the node directly containing point P2.
Define Offset1 as the offset of point P1 within the node identified by Node1, and Offset2 as the offset of point P2 within the node identified by Node2.
Beginning at the uppermost end of Node1 and Node2 (typically both 1 for the XML document element), compare corresponding components of the two paths and discard all such pairs that are equal.
If a further component(s) is available from
If a further component(s) is available from
If a further component(s) is available for only Node1, then P1 is within some descendant of the node in which P2 directly occurs. Thus it is necessary to determine the position of Offset2 relative to the ancestor of P1 that is at the same level (that is a child of Node2). To do this, compare Offset2 to the first of the further components for Node1. If Offset2 is greater than or equal, then P2 follows P1 in document order; otherwise it precedes P1.
If a further component(s) is available for only Node2, compare Offset1 to the first of the further components for Node2. If Offset1 is greater than or equal, then P1 follows P2 in document order; otherwise it precedes P2.
As of this writing, the ordering algorithm in DOM 2: Range
Two ranges R1 and R2 are ordered using the following sequence of comparisons of their starting and ending points (these definitions avoid circularity because the definition of point ordering given above does not involve casting the compared points to their equivalent collapsed ranges):
If the start point of R1 is not equal to the start point of R2, then the ranges are ordered as their respective start points are ordered. That is, if R1 starts before R2 it is before R2, and if R1 starts after R2 it is after R2.
If the start point of R1 is equal to the start point of R2, then the ranges are ordered as their respective end points are ordered. That is, if R1 and R2 start at the same point, then: if R1 ends before R2 it is before R2; if R1 and R2 end at the same point R1 is equal to R2; and if R1 ends after R2 it is after R2.
Thus, R1 and R2 are equal if and only if their respective start points and end points are equal.
Comparisons between any two types of locations (point vs. node, etc.) must produce the same results as obtained through converting all comparands to their equivalent ranges and comparing those ranges.
This algorithm yields the correct results; however, implementations need not use this specific algorithm to compare point locations. They may use any algorithm that produces the same results.
The &scheme-phrase; adds the following functions to those in XPath.
For each location in the context,
The change made to the XPath syntax to support the
The version in the &scheme-phrase; is as follows:
This change is a single exception for the
As an example of using the chap1
to the end point of the element with ID chap2
.
As another example, imagine a document that uses empty elements (such as <REVST/> for
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 REVEND element:
For each location in the location-set argument,
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 sub-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
Element boundaries, as well as entire embedded nodes such as processing
instructions and comments, are ignored as specified by the definition of
For any particular location,
if the string argument is not found
in the
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 title element:
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 P element:
Alternatively this could be specified as follows:
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 Thomas Pynchon
had some inline markup
in it as follows, it would not change the string identified by the XPointer
processor:
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
The following functions are related to ranges.
The
The
For each location
If
If
If
If
For each location x in the argument location-set,
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
If
The
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
The type of the node in which the text, attribute, or processing-instruction.
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.
The origin() function is meaningful only when the expression
is being processed in response to traversal of a link expressed in an XML
document. The
It is an error to use
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 documents, the &scheme-phrase; 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 TEI Hypertext Guidelines.In
The Dexter Hypertext Reference Model.In
Document structure in the FRESS Hypertext System.
The Role of XML in Open Hypermedia Systems.Position paper for the 4th Workshop on Open Hypermedia Systems, ACM Hypertext '98.
The notation defined here builds on the XPointer element() scheme. However, where element() can only identify a whole element node in an XML Infoset, the notation defined here can also identify any point or range. This notation is intended to be easy to understand and to provide a clear way to explicate the sometimes-complex ordering relationships of document locations. It also has advantageous properties such as that many useful properties of document locations can be determined merely by examining their representation in this notation, and without having to resort to the actual document or Infoset.
The initial portion of the notation is identical to
element(): a list of child numbers separated by
the slash character ("/"). Such a list is called a element() scheme's child sequence number above each node:
Figure 2: Structure diagram with child sequences for all
"ROOT" here indicates the root node, "txt" indicates text nodes, "_" indicates the space character, and "p" and "emph" indicate element nodes.
For example:
element(1) identifies the p element (the document element; note that the root node has no number).
element(1/2/1) identifies the (only) text node within the emph element, which contains the text "big ".
Points, ranges, and non-element nodes cannot be identified by the numbering mechanism. However, the DOM 2: Range
For the exact same structure shown above, those
Figure 3: Structure diagram with
For example:
the point just before the first text node is offset 0 within the p element
the point after the "r" of "world" is offset 3 within the last text node.
the point between the emph element and the following text node is offset 2 within the p element
Implementors must take care regarding a difference in how
XPath
A point is always within some node, but a point cannot have children as a node can. Thus, a point can always be identified by the child sequence of the node it is in, plus the offset of the point within that node.
This specification therefore defines the element() scheme syntax except that:
the slash-separated numbers are determined not by counting only element nodes, but by counting nodes of all types
an integer is appended when representing a point, to represent the point's offset within the node specified by the preceding child sequence
the final integer is separated from the preceding ones by "." instead of "/", to distinguish its different meaning
the child sequence may be empty, meaning that the point is directly within the root node
the notation is not named "element", but "point"
For example:
the point sequence to identify the point immediately following the period within the last text node above is point(1/3.6). "1/3" identifies the last text node, while ".6" indicates the offset with that node.
the point immediately preceding the p element has point sequence point(.0).
The last component must be delimited by "." instead of "/" in order to distinguish specifying a point from specifying a node at the same level. For example, point(1/2) is a child sequence that identifies the emph element above, but point(1.2) identifies the point immediately following it. Thus the XPointer startpoint() and endpoint() functions can be easily implemented in terms of this representation.
The point preceding the root node itself is identified as ".0"; the point after the root node itself is identified as ".1". The sequence "/" refers to the root node itself and may optionally be written before the first numeric component.
For an expression range(S, E) in which S and E are both points: If S precedes E in document order the expression represents the range beginning at S and ending at E; if S is equal to E in document order, the expression represents the collapsed range (equivalent to the point) at S (and equally at E); if S follows E in documents order, the expression is in error and results are undefined.
An expression point(P) in which P is not a point, is treated as point(start-point(P)). An expression range(S) is treated as range(S,S). An expression range(S, E) in which either S or E is not a point, is equivalent to range(start-point(S),end-point(E)).
The name of the point notation is "point", and its formal grammar is:
The name of the range notation is "range", and its formal grammar is:
The diagram in the section "Document Ordering" above, shows the point sequences to all points in its example, omitting the "point(" and ")" to save space.
As noted earlier, the point immediately before (or after) a text node occurs at the same place in an XML source document as the point immediately before (or after) that text node's first (or last) character. This specification defines those locations as distinct; they do not compare as equal. For example, the point at offset 2 within the p element above is not equal to the point at offset 0 within the text node containing "world." It is beyond the scope of this specification to define editing operations such as insertion, but we note that the permissible operations at such points may differ. For example, an interface might reject inserting a node within a text node even at offset 0, or inserting characters at the corresponding offset within the containing element.
Since a range is defined in terms of a starting point and an ending point, a range is uniquely identified by two point sequences. For example, the range extending from before the 2nd "l" of "hello", to immediately after the emph element, is from point(1/1.3) to point(1.2) and is here written range(1/1.3, 1.2).
The
the point just described following "l" is equivalent to range(1/1.3, 1/1.3).
the "i" itself is equivalent to range(1/2/1.1, 1/2/1.2).
the emph element above is equivalent to range(1.1, 1.2).
the entire content of the root node (but not the root node itself) is equivalent to range(.0,.1) or range(/.0, /.1)..
the entire root node is equivalent to range(/,/).
The node representation just shown is analogous to the "outerHTML" property in some scripting languages, as it contains the entire node as a whole, not merely its children or contents. The "inner" aspect of a node is also representable. For example, the complete content of the p element above, but not the p element itself, is range(1.0, 1.3). The 3 represents offset 3 within the p element, the position following its 3rd child (which is the text node containing 'world.').
Several useful operations can be done using solely the point sequence representation of ranges. For example, order comparisons, tests of containment and equivalence, tests of whether a range could form a well-formed XML entity, and measures of nesting depth can all be trivially constructed based on this representation. However, this specification does not mandate implementation of this or any other internal representation, so long as the results specified here are obtained.
The first working drafts of this specification were developed in the XML
Working Group, whose members are listed in
The editors wish to acknowledge substantial contributions from Tim Bray, who previously served as co-editor and co-chair; from James Clark on integration with XPath; from Gavin Nicol and Martin Dürst on passages related to internationalization; and from Jeni Tennison on the formal definition of document ordering. Finally, we would like to thank the XML Linking Interest Group and Working Group for their support and input.