W3C

XML Pointer Language (XPointer)

W3C Working Draft 6 December 1999

This version:
http://www.w3.org/TR/1999/WD-xptr-19991206
Latest version:
http://www.w3.org/TR/xptr
Previous versions:
http://www.w3.org/1999/07/WD-xptr-19990709
http://www.w3.org/TR/WD-xml-link-970731
Editors:
Steve DeRose (Brown University Scholarly Technology Group) <Steven_DeRose@Brown.edu>
Ron Daniel Jr. (DATAFUSION, Inc.) <rdaniel@datafusion.net>
Eve Maler (Sun Microsystems) <elm@east.sun.com>

Copyright  ©  1999 W3C® (MIT, INRIA, Keio ), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.

Status of this document

The XML Linking Working Group, with this 1999 December 6 XPointer Last Call working draft, invites comment on this specification. The Last Call period begins 6 December 1999 and ends 27 December 1999.

The W3C Membership and other interested parties are invited to review the specification and report implementation experience. Please send comments to www-xml-linking-comments@w3.org (archive).

For background on this work, please see the XML Activity Statement. While we welcome implementation experience reports, the XML Linking Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release.

For information about the XLink language with which XPointer is expected to be used, see http://www.w3.org/TR/WD-xlink.

See http://www.w3.org/TR/NOTE-xptr-req for the specific requirements that informed development of this specification.

A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.

Abstract

This specification defines the XML Pointer Language (XPointer), the language to be used as a fragment identifier for any URI-reference that locates a resource of Internet media type text/xml or application/xml.

XPointer, which is based on the XML Path Language (XPath), supports addressing into the internal structures of XML documents. It allows for traversals of a document tree and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position.

Table of Contents

1. Introduction
    1.1 Origin and Goals
    1.2 Notation and Document Conventions
    1.3 Terminology
2. The XPointer Model and Language
    2.1 Forms of XPointer Fragment Identifier
        2.1.1 Full XPointers
        2.1.2 Bare Names
        2.1.3 Child Sequences
    2.2 Character Sets and Escaping
    2.3 Schemes
    2.4 XPointer Errors
3. XPointer Extensions to XPath
    3.1 XPointer Additions to XPath Terms and Concepts
    3.2 Evaluation Context Initialization
    3.3 The point and range Location Types
        3.3.1 Definition of Point Location
        3.3.2 Definition of Range Location
        3.3.3 Covering Ranges for All Location Types
        3.3.4 NodeTests for point and range Locations
        3.3.5 Document Order
    3.4 Range Expressions
    3.5 The string-range Function
    3.6 Additional Functions
    3.7 XPointer Predicate Functions
4. Conformance

Appendices

A. References
    A.1 Normative References
    A.2 Non-Normative References
B. Summary of XPath in the Context of XPointer (Non-Normative)
    B.1 XPath Basics
    B.2 XPath Axes
    B.3 XPath Relative Axes
    B.4 XPath Node Tests
    B.5 XPath Predicates
        B.5.1 Introduction to Predicates
        B.5.2 Positional Tests
        B.5.3 Local Structure Tests
    B.6 Examples of Axis Usage
C. Working Group Members (Non-Normative)

1. Introduction

This specification defines the XML Pointer Language (XPointer), the language to be used as a fragment identifier for any URI-reference that locates a resource of Internet media type text/xml or application/xml [IETF RFC 2376]. This specification does not constrain the syntax or semantics of URI-references to resources of other media types.

XPointer supports addressing into the internal structures of XML documents. It allows for traversals of a document tree and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position. In particular, it provides for specific reference to elements, character strings, and other parts of XML documents, whether or not they bear an explicit ID attribute.

The structures located with XPointer can be used as link targets or for any other application-specific purpose. This specification does not constrain what uses an application may make of locations identified by XPointers. In particular, implementation of traversal to a resource is not constrained by this specification, and whether user traversal is the purpose of an XPointer at all is application-dependent. A formatted-text browser traversal might scroll to and highlight the designated location; a structure-oriented graphical tree viewer or a document-relationship display might do traversal in quite a different way; and a search application, parser, archival system, or expert agent might use XPointers for other purposes entirely. The construction of linking elements in XML documents that associate arbitrary resources (including XML documents and portions thereof) is defined in a related specification [XLink].

XPointer is built on top of the XML Path Language [XPath], which is an expression language used in the XSL Transformations (XSLT) language. XPointer's extensions to XPath allow it to:

Addressing into the internal structures of DTDs and the XML declaration is out of the scope of this specification.

Note: XPointer is the fragment identifier language for the text/xml and 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. (A recent Internet Draft [IETF I-D XMT] suggests the use of a naming convention, */*-xml, for specialized media types based on XML). XPointer is expected to be useful as a fragment identifier language for the generic XML aspects of those media types. Special schemes "2.3 Schemes" can be used to perform special access to the content of those media types.

1.1 Origin and Goals

The XPointer Requirements Document [XPREQ] contains a thorough explanation of requirements for the design of XPointer. The categories and general nature of the requirements are very briefly summarized here.

Completeness requirements
XPointers must identify XML information items, rather than syntax. For any single element or other XML construct in a document, it must be possible to create at least one XPointer that specifically identifies it. It must also be possible to create an XPointer that identifies a contiguous selection of content, such as could be clicked or dragged by a user.
Expressiveness requirements
This specification must utilize information structures and relationships that are native to XML, such as elements and containment; offsets and the like are not in scope. XPointers must be unambiguously definable in relation to XML namespaces.
Robustness requirements
It must be possible to create XPointers that can be tested for whether they identify the same target at traversal time as at creation time. This specification must attempt to be internationalized. It must also enumerate any dependencies on the presence of a DTD or schema.
General user requirements
XPointers must be reasonably user-readable and user-writable, particularly for cases likely to be commonly needed by beginning and intermediate users. Syntax must scale smoothly, not abruptly with increasing complexity.
Mechanical and syntactic requirements
XPointers must identify locations, not just data residing at those locations. The needs of escaping both URI-special and XML-special characters must be taken into account. XPointers in URIs must be friendly to Web servers and user agents. The XPointer syntax must be extensible.

In addition to XPath, the following standards have been especially influential in the development of this specification:

The addressing components of many other hypertext systems have also informed the design of XPointer, especially Dexter, OHS, FRESS, MicroCosm, and InterMedia.

1.2 Notation and Document Conventions

The formal grammar for locators is given using a simple Extended Backus-Naur Form (EBNF) notation, as described in the XML Recommendation [XML]. Explanatory text is included here regarding aspects of XPath, to make this specification more accessible; however, such text is not normative. Should there be conflicts, [XPath] is the normative specification of these common constructs.

In addition, XLink may contain non-normative commentary of the following forms:

A recorded issue and something on which the working group is seeking comment.

EDITOR'S NOTE:

Notes the editors wish to call to the attention of readers within the WG and IG. To be removed from the HTML version of the released working drafts and final recommendation but remains in the XML version.

Note: General comments the editors wish to call to the attention of the reader

1.3 Terminology

The following terms are used in this specification.

[Definition:] axis
A reserved name that defines a sequence of data portions. Typically, an XPointer utilizes axes in combination with predicates to select particular data portions. Some axes define their sequence relative to a particular node, such as all children or all attributes of a particular node, the character ranges within a given subtree, etc. Other axes define a sequence that does not depend on context, such as the absolute root of the document.
[Definition:] link
An explicit relationship between two or more resources or portions of resources. This specification facilitates but does not define the representation of links; linking mechanisms for XML are defined in the XLink specification [XLink].
[Definition:] location set
An ordered list of document nodes, points, and/or ranges, such as produced by an XPointer expression. This corresponds to the node set produced by XPath expressions, except for the generalization to include points and ranges.
[Definition:] locator
Link data that identifies a remote resource that is participating in the link, for example, a URI. This specification is concerned with defining the fragment identifier portion of URI-references for use with XML documents, to specify particular sub-resources.
[Definition:] node
An entire information set object from an XML document, such as an element, attribute, processing instruction, comment, or text portion (the last extending all the way to the nearest adjacent non-text object at each end -- a smaller text portion is a range, not a node).
[Definition:] predicate
An expression that, given a sub-resource location, can be evaluated to produce a true or false result. XPointer uses predicates to select sub-resources (for example, elements) relative to other ones in documents.
[Definition:] point
A point is a position in document content. 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.
[Definition:] range
A range identifies a contiguous selection of all the content between a pair of end points. This notion comes from the DOM Level 2 [DOM2] specification.
[Definition:] remote resource
Any participating resource of a link that is pointed to explicitly with a locator.
[Definition:] resource
In the abstract sense, an addressable service or unit of information. Examples include files, images, documents, programs, and query results. Concretely, anything reachable by the use of a locator. Note that this term and its definition are taken from the basic specifications governing the World Wide Web. Note that this term and its definition are taken from the basic specifications governing the World Wide Web, such as IETF RFCs [IETF RFC 2396], [IETF RFC 1738] and [IETF RFC 1808].
[Definition:] root
The unique tree node that has no ancestors. As in XSL, this is not the document element (such as <HTML>...</HTML> for an HTML document), but an abstract node that directly contains the document element. This is because there may be prolog material that resides outside the document element. The root() function gives direct access to this node.
[Definition:] singleton
A location that consists of a single, contiguous portion of a document. Some XPointers can locate multiple data portions, such as all the separate ITEMs in a LIST; when an XPointer instead locates only a single contiguous data portion, such as an element or a range of character data, that location is said to be a singleton.
[Definition:] sub-resource
A portion of a resource, pointed to as the precise destination of a link. As one example, a link might specify that an entire document be retrieved and displayed, but that some specific part or section of it is the specific linked data, to be treated in an application-appropriate manner such as indication by highlighting, scrolling, and so on. A sub-resource is similar to the notion of anchors in HTML, but a sub-resource is not necessarily represented by explicit markup (such as <A NAME="...">) within the resource.
[Definition:] tree
A logical representation of the relevant structure specified by the tags and attributes in an XML document. This notion is related to the XML Information Set [XIS], which describes the abstract data set containing the information available from an XML document. It includes nodes representing elements, text, processing instructions, and other constructs. Some nodes bear additional information such as their element type name, an attribute list, etc.; however, such information items are not considered children of the nodes that bear them.
[Definition:] URI-reference
An optional URI [IETF RFC 2396], [IETF RFC 1738] and [IETF RFC 1808] with an optional fragment identifier separated from the URI by a crosshatch (#) character. Either the URI or the fragment identifier or both must be present for the URI-reference to be valid. URI stands for Uniform Resource Identifier. This specification is concerned with defining the fragment identifier portion of URI-references for use with XML documents.

2. The XPointer Model and Language

XPointers, like XPath expressions, operate on the XML Information Set, a tree derived from the elements and other markup constructs of an XML document. Both XPointers and XPath expressions operate by selecting particular parts of such trees, often by their structural relationship to other parts (for example, the parent of a node with a certain ID value). XPointers can express multiple such selections, each operating on what is found by the prior one.

Selection of tree portions is done through axes, predicates, and functions. An axis defines a sequence of candidates that might be located; predicates then test information in the tree relative to such portions; and functions generate new candidates or perform various other tasks. For example, one may select certain elements from among the siblings of some previously located element, based on whether those sibling elements have an attribute with a certain value, or are of a certain type such as FOOTNOTE, or select the point location immediately preceding a certain P.

2.1 Forms of XPointer Fragment Identifier

XPointer fragment identifiers allow one full form of XPointer addressing and two shorthand forms. The shorthand forms are defined as abbreviations of the full form of XPointer addressing, although implementations need not convert an abbreviated form into the full form before evaluation. All error conditions apply as if the full form of the XPointer were specified.

The three forms are defined as follows:

XPointerFragID
[1] XPointerFragID ::= Name
'|' ChildSeq
'|' GeneralFragmentPart+
[2] ChildSeq ::= '/1' ('/' [0-9]*)*
| Name ('/' [0-9]*)+
[3] GeneralFragmentPart ::= 'xpointer' '(' XPointerExpr ')'
| Scheme '(' SchemeSpecificExpr ')'
[4] Scheme ::= QName - 'xpointer'
[5] SchemeSpecificExpr ::= StringWithBalancedParentheses
[6] StringWithBalancedParentheses ::= [^()]* ('(' StringWithBalancedParentheses ')' [^()]*)* [ VC: Additional escaping rule ]
[7] XPointerExpr ::= Expr | RangeExpr [ VC: Expr Restrictions ]

Name is defined in the XML Recommendation [XML], QName is defined in the XML Namespaces Recommendation [XML-Names], and Expr is defined in the XPath Recommendation [XPath]. Note that the formal syntax in this specification does not represent the general applicability of escaping, as defined in "2.2 Character Sets and Escaping".

2.1.1 Full XPointers

The full form of addressing consists of one or more fragment parts. Each starts with a scheme name and is followed by a parenthesized expression. When the scheme is xpointer, the associated expression provides XPath-compatible access to nodes in an XML document's information set (except for nodes representing CDATA marked sections and entities), and adds access to any selection of an XML document's content. Such locations are specified using a variety of descriptive techniques.

2.1.2 Bare Names

The bare name form of addressing is provided for HTML compatibility. The appearance of the name stands for the same name provided as the argument of a location step using the id() function.

For example, the following URI-reference fragment identifier:

#intro

is the bare-name equivalent of the following full-form fragment identifier:

#xpointer(id("intro"))

This reserved shorthand is provided for two reasons:

Note that the restriction to name characters is commonly followed, but not required, in HTML. Also, for the bare-name form to work with an HTML document target, the document's NAME attribute must have been declared to be of type ID.

2.1.3 Child Sequences

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 *[n]. Nodes other than elements, including the document root (which in any case is not a child of anything), cannot be located by child sequences.

The beginning element for the navigation may be located either by specifying a name, which locates an element as described above for bare names, or by the string /1, which locates the document element.

2.2 Character Sets and Escaping

The character set for XPointers is the same as for XML, namely Unicode. XPointers are expected to be used as fragment identifiers in URI-references, and some Unicode characters are disallowed from URI-references. Thus, if these characters are needed in an XPointer, they must be encoded specially using URI escaping mechanisms. The UTF-8 encoding is used for URI-references; any bytes of the result that are not allowed in URIs must be expressed as %HH (where HH represents the two hexadecimal digits needed to represent the byte being encoded).

Similarly, if XPointers appear in XML document content (for example, in an attribute value, which is where URI-references typically appear), it is generally necessary to escape occurrences of the left angle bracket (<) and ampersand (&) as &lt; and &amp;. For example, an XPointer, appearing in an XLink, that identifies the first five chapter elements of a document would look as follows with the left angle bracket in its comparison operator escaped:

<xlink:simple
href='doc.xml#xpointer(book/chapter[position() &lt;= 5])' />

Note: The draft Character Model specification [CMOD] specifies that XML-handling systems are required to treat any illegal characters in URIs as if they had been escaped with the %HH mechanism, whether or not they have been. In other words, this type of escaping may not be a necessity when XPointers are used in URI-references in XML documents. However, if the URI-reference is extracted from an XML document and then used, the escaping must be applied.

Validity Constraint: Additional escaping rule
The end of a GeneralFragmentPart is signaled by the right parenthesis [)] character that is balanced with the left parenthesis [(] character in the LocationSpec. Any unbalanced parentheses in the SchemeSpecificExpr, even within literals, must be escaped by preceding them with an occurrence of the circumflex (^) character. If the SchemeSpecificExpr contains any literal occurrences of the circumflex, each must be escaped with an additional circumflex (that is, ^^). If no balancing right parenthesis can be found for a particular left parenthesis, a syntax error results.

Validity Constraint: Expr Restrictions
Not all legal XPath expressions may be used here. Only those that return a node-set are allowed.

2.3 Schemes

In a full-form XPointer, an initial Scheme identifies the particular notation used. The only scheme defined in this version of the specification is xpointer (where case is significant); all scheme names beginning with xpointer are reserved by this specification. Having an explicit scheme name allows for possible future versions of the XPointer language to identify themselves, as well as allowing alternative addressing languages for XML-based languages such as SVG or SMIL to identify themselves.

This specification defines two items related to the scheme. The first is the general framework for detecting what scheme is in use and the ability to skip over schemes that are not understood. The second is the behavior when the Scheme is xpointer.

More than one GeneralFragmentPart may occur in a single fragment identifier. When multiple fragment parts are provided, they must be evaluated in left-to-right order. If evaluation of one part fails, the next is evaluated. A fragment part with an unknown scheme name fails by definition; the XPointer implementation must consume that fragment part and attempt to evaluate the next one, if any. The result of the first fragment part whose evaluation succeeds is taken to be the sub-resource located by the fragment identifier as a whole. If all the fragment parts fail, the fragment identifier as a whole results in a sub-resource error.

This approach allows alternative addressing mechanisms to be specified, which can allow for more robust locators in the presence of features such as content negotiation or user-selected limits on network access. For example, the following fragment identifier locates the element with an ID attribute whose value is chap1:

xpointer(id("chap1"))

However, in the absence of the DTD, it is not typically possible to determine if an attribute is of type ID. A fragment identifier like the following, with two fragment parts, will have its first fragment part fail if no DTD is available, but will have its second fragment part succeed if the desired attribute's name is id:

xpointer(id("chap1"))xpointer(//*[@id="chap1"])

Because fragment identifiers are specific to the media type of the returned data, XPointer provides an open syntax in which other specifications may choose to participate, and under which users may include alternative fragment identifiers in case the media type of the resource may vary due to content negotiation. For example, a server might return a detailed text description when the user's client does not support graphics; the URI-reference could include an XPointer fragment identifier as well as a media-type-specific identifier for the graphic, perhaps identifying coordinates of a graphical region.

2.4 XPointer Errors

There are several kinds of errors that can arise in using XPointers. They apply to all three types of XPointer as defined above.

[Definition:] A string that does not match the syntax specifications given here is said to have a syntax error, and applications should not attempt to interpret it as an XPointer.

[Definition:] A syntactically correct XPointer may, when interpreted, find that it is given no resource to work from (for example, it may be appended to an incorrect URI), or may find itself operating on a resource that is not well-formed XML data. Such an XPointer is said to have a resource error.

[Definition:] A syntactically correct XPointer may, when interpreted, fail to find a sub-resource matching its description. Such an XPointer is said to have a sub-resource error. Note that XPath allows expressions that return empty node-sets as their results and does not regard that as an error. XPointers are not a general query mechanism, they are a specification of document locations. Therefore, an empty result is a sub-resource error.

This specification does not constrain how applications deal with these errors.

3. XPointer Extensions to XPath

This section describes the XPointer extensions to XPath. XPointer defines the following in order to build on and extend XPath:

3.1 XPointer Additions to XPath Terms and Concepts

XPath provides for locating any subset of the nodes in an XML document, where nodes generally correspond to information set items such as elements, attributes, comments, and processing instructions. XPath functionality, such as filtering an axis output by predicate, is generally defined in terms of operations on nodes and node-sets.

XPointer has a requirement to identify document portions that are not nodes in this sense. One example of such a non-node region is an arbitrary user selection indicated by a drag between two points in a document. The two points may be in different subtrees, or the region may form only a small part of a node. For example, a range could extend from the middle of one paragraph to the middle of the next, thus containing only part of the relevant paragraph and text nodes. Even though such locations are not nodes, XPointer needs to be able to apply XPath operations to them as well as to nodes.

To accomplish this, XPointer defines location as a generalization of XPath's node. Every location is either a point, a range, or an XPath node. Thus, XPointer also defines location-set as a generalization of XPath's node-set. All locations generated by XPath constructs are nodes; XPointer constructs can also generate points and ranges.

Note: In user selections of text, the order of characters on a computer screen may not reflect their order in the underlying XML document. For example, this can occur when a portion of a right-to-left language such as Arabic is embedded in a left-to-right language such as French. In situations where the order of characters is important, such as when indexing into strings, the indices are for the document order of the characters in the string, not the display order.

3.2 Evaluation Context Initialization

An XPointer is evaluated to yield an object of type location-set. This evaluation is carried out within a context identical to the XPath evaluation context, except for the generalization of nodes to locations. This section defines how the evaluation context must be initialized by XPointer implementations prior to evaluating an XPointerExpr.

An XPointer evaluation context contains the following information:

3.3 The point and range Location Types

The major extension XPointer makes to XPath is to allow the addressing of locations that do not correspond to XPath nodes. To address these non-node locations, XPointer defines two new location types, point and range, that can appear in location-sets and can be operated on by XPath node tests and predicates. Locations of the point and range type represent positions and ranges as in DOM Level 2 [DOM2]. This section defines the point and range types and the characteristics of them required for XPath interoperability.

Points and ranges can be used as XPointer context locations. This allows the XPointer [] operator to be used to select from sets of ranges, and allow the first operand in a RangeExpr to return ranges.

3.3.1 Definition of Point Location

A location of type point is defined by [Definition:] a node, called the container node, and [Definition:] a non-negative integer, called the index. It can represent the location preceding any individual character, or preceding or following any node in an XML document.

Note: This specification does not constrain the implementation of points. In other words, it is not required that implementations actually represent points using data structures consisting of a node and an index.

[Definition:] When the container node of a point is of a node type that can have child nodes (that is, the container node is an element node or a root node), then the index is an index into the child nodes; such a point is called a node-point. The index of a node-point must be greater than or equal to zero and less than or equal to the number of child nodes of the container. An index of zero indicates the point before any child nodes, and a non-zero index n indicates the point immediately after the nth child node.

[Definition:] When the container node of a point is of a node type that cannot have child nodes, then the index is an index into the characters of the string-value of the node; such a point is called a character-point. The index of a character-point must be greater than or equal to zero and less than or equal to the length of the string-value of the node. An index of zero indicates a point immediately before the first character of the string-value, and a non-zero index n indicates an point immediately after the nth character of the string-value.

Point locations do not have an expanded-name.

The string-value of a point location is empty.

The axes of a point location are defined as follows:

3.3.2 Definition of Range Location

A location of type range is defined by two points, a start point and an end point. A range represents all of the XML structure and content between the start point and end point. This is distinct from any list of nodes and/or characters, in part because some nodes may only be partly included. The start and end points of a range must be in the same document. The start point must not appear after the end point in document order.

[Definition:] A range whose start and end points 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.

Range locations do not have an expanded-name.

The string-value of a range location is defined as follows. If the points are both character-points and the container nodes of the points are the same, then the string-value consists of the characters between the two points. Otherwise, the string-value consists of the characters that are in text nodes and that are between the two points.

The axes of a range location are the axes of its starting position.

Note: The start-point() and end-point() functions can be used to navigate with respect to the respective boundaries of a range location.

3.3.3 Covering Ranges for All Location Types

[Definition:] A covering range is a range that wholly encompasses a location. For every location, a covering range is defined as follows:

3.3.4 NodeTests for point and range Locations

XPointer extends the XPath production for NodeType by adding items for the point and range location types. That production becomes as follows:

NodeType
[8] NodeType ::= 'comment'
| 'text'
| 'processing-instruction'
| 'node'
| 'point'
| 'range'

This definition allows NodeTests to select locations of type point and range from a location set that may include locations of all three types.

3.3.5 Document Order

XPointer extends XPath's concept of document order to cover point and range locations.

For any point, there is an immediately preceding node defined as follows (except that there is no point defined preceding or following the root):

For any point, the immediately following node is the node that is immediately after the immediately preceding node (as just defined).

A node is before a point if the node is before or equal in document order to the immediately preceding node of the point; otherwise, the node is after the point.

The relative order of a node and a range is determined by the relative order of the node and the starting point of the range.

Document order for a point is defined as follows:

One range node is before another range node if and only if

3.4 Range Expressions

Following is the formal definition of a range expression:

Range Expressions
[9] RangeExpr ::= Expr 'to' Expr [ VC: Expr Restrictions ]

The result of evaluating a RangeExpr is the location-set computed as follows. The first operand is evaluated. The evaluation context for the first operand is the same as the evaluation context for the RangeExpr. The result of evaluating the first operand must be a location-set. For each location x in this location-set, the second operand is evaluated with x as the context location and 1 as the context position and 1 as the context size; the result in each case must be a location-set. For each location y in this location-set, a range is added to the result location-set of the RangeExpr, whose start point is the start point of the covering range of x and end point is the end point of the covering range of y.

For example, the following XPointer selects everything from the beginning of the last P descendant element in a section with ID sec2.1 through the end of the first P descendant element in another section with ID sec2.2:

xpointer(id("sec2.1")/descendant::P[last()] to
     id("sec2.2")/descendant::P[last()])

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 XPointer 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:

xpointer(descendant::REVST to following::REVEND[1])

3.5 The string-range Function

FUNCTION: location-set string-range( location-set string number? number? )

For each location in the location-set argument, the string-value of the location is searched for substrings that match the string argument, and the resulting location-set will contain a range location for each non-overlapping match. An empty string is considered to match before each character of the string-value. The third argument gives the position of the first character to be in the resulting range, relative to the start of the match. The default value is 1, which makes the range start immediately before the first character of the matched string. The fourth argument gives the number of characters in the range; the default is that the range extends to the end of the matched string.

Multiple adjacent whitespace characters (as defined for S in [XML]) are treated as a single white-space before for the purposes of matching. That is, a string of whitespace characters in the string argument can match a sequence of whitespace characters in the string being examined.

The points of the range-location in the returned location-set will all be character points, and are not changed by the whitespace-matching rule.

For example, the following expression returns a range that selects the 17th occurrence of the string Thomas Pynchon occurring in a title element:

string-range(//title,"Thomas Pynchon")[17]

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 in a P element:

string-range(//P,"Thomas Pynchon",8,0)[3]

Alternatively this could be specified as follows:

string-range(string-range(//P,"Thomas Pynchon")[3],"P",1,0)

The following expression selects the fifth exclamation mark in any text node in the document and the character immediately following it:

string-range(/,"!",1,2)[5]

3.6 Additional Functions

XPointer also adds the following functions to those in XPath; these functions must be provided by XPointer implementations.

FUNCTION: location-set range( location-set )

The range() function returns ranges covering the locations in the argument location-set. For each location x in the argument location-set, a range location representing the covering range of x is added to the result location-set.

FUNCTION: location-set range-inside( location-set )

The range-inside() function returns ranges covering the contents of the locations in the argument location-set. For each location x in the argument location-set, a range location is added to the result location-set. If x is a range location, then x is added to the result location-set. If x is not a range location, then x is used as the container location of the start and end points of the range location to be added; the index of the start point of the range is zero; if the end point is a character point then its index is the length of the string-value of x, and otherwise is the number of location children of x.

FUNCTION: location-set start-point( location-set )

The result location-set contains zero or more locations of type point. For each location in the argument location-set, a point location equal to the start point of the covering range of the location is added to the result location-set.

For example,

start-point(//chap[3])

would locate the point immediately preceding the third chap element in the document.

FUNCTION: location-set end-point( location-set )

The result location-set contains zero or more locations of type point. For each location in the argument location-set, a point location equal to the end point of the covering range of the location is added to the result location-set.

FUNCTION: location-set here( )

The here() function returns a location-set with a single member. That location is of type element, and locates the element that directly contains (as text) or bears (as an attribute value) the XPointer. This expression results in a syntax error if the containing XPointer does not appear in an XML document.

FUNCTION: location-set origin( )

The origin() function enables addressing relative to out-of-line links such as defined in XLink. This allows XPointers to be used in applications to express relative locations when links do not reside directly at one of their endpoints. The function returns a location-set with a single member, which locates the element from which a user or program initiated traversal of the link. The origin() function thus provides a meaningful location-set only if the XPointer is being processed by application software in response to a request for traversal (see [XLink] for information about traversal).

It is a resource error to use origin() in a locator where a URI is also provided and identifies a containing resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.

3.7 XPointer Predicate Functions

The predicate function unique() returns true if and only if context size is equal to 1.

This is particularly useful in applications where a single location is to be located for automated processing and an XPointer that does not locate exactly one location would be in error.

The unique() function may be considered shorthand for the following XPath expression:

count()=1

It is included because this is considered a very common need for XPointers. Making it a separate expression may also simplify optimization of XPointer evaluation, such as by using methods understood from the treatment of singleton results in database systems.

4. Conformance

A string conforms to the XPointer specification if it adheres to the syntactic requirements imposed by this specification (including that part of [XPath] included by reference). There is no requirement that the string, in association with a URI, actually point to a resource that exists at any given moment.

Application software conforms to XPointer if it interprets all XPointer-conforming strings according to the semantics prescribed by this specification. The syntax must be recognized and processed correctly regardless of whether full forms or abbreviated forms are used. This includes supporting both the general framework for dealing with schemes, and the specific xpointer scheme. It also includes providing implementations of all functions defined in this specification, in addition to the core functions established by the XPath specification.

Conformant applications must recognize and correctly interpret XPointers that appear as the fragment identifier of a URI-reference which locates a resource whose Internet media type is text/xml or application/xml. Processing of the results of evaluating the XPointer is defined by the application. Processing of errors arising from the evaluation of XPointers is defined by the application.

Conformant specifications that use URI-references in relation to resources whose media type is text/xml or application/xml are required to use XPointer syntax and semantics for the fragment identifier.

Appendices

A. References

A.1 Normative References

IETF RFC 1738
IETF (Internet Engineering Task Force). RFC 1738: Uniform Resource Locators. 1991. (See http://www.w3.org/Addressing/rfc1738.txt.)
IETF RFC 1808
IETF (Internet Engineering Task Force). RFC 1808: Relative Uniform Resource Locators. 1995. (See http://www.w3.org/Addressing/rfc 1808.txt ).
IETF RFC 2376
IETF (Internet Engineering Task Force). RFC 2376: XML Media Types. 1998. (See http://www.ietf.org/rfc/rfc2376.txt).
DOM
Document Object Model DOM) Level 1 Specification. World Wide Web Consortium, 1997. (See http://www.w3.org/TR/WD-DOM.)
DOM2
Document Object Model (DOM) Level 2 Specification: Version 1.0. World Wide Web Consortium, 1999. See http://www.w3.org/TR/WD-DOM-Level-2
XML
XML World Wide Web Consortium. Extensible Markup Language (XML) 1.0. W3C Recommendation. See http://www.w3.org/TR/REC-xml.
XML-Names
XML Names World Wide Web Consortium. Namespaces in XML. W3C Recommendation. See http://www.w3.org/TR/REC-xml-names
XPath
XML Path Language (XPath) World Wide Web Consortium. XML Path Language (XPath). W3C Proposed Recommendation. See http://www.w3.org/TR/REC-xpath.

A.2 Non-Normative References

IETF RFC 2396
IETF (Internet Engineering Task Force). RFC 2396: Uniform Resource Identifiers. 1995. (See http://www.ics.uci.edu/pub/ietf/uri/rfc2396.txt ).
IETF I-D XMT
IETF (Internet Engineering Task Force). Internet Draft: XML Media Types. 1999. (See http://www.ietf.org/internet-drafts/draft-murata-xml-01.txt).
ISO/IEC 10744
ISO (International Organization for Standardization). ISO/IEC 10744-1992 (E). Information technology --Hypermedia/Time-based Structuring Language (HyTime).[Geneva]: International Organization for Standardization, 1992. Extended Facilities Annex.[Geneva]: International Organization for Standardization, 1996. (See http://www.ornl.gov/sgml/wg8/docs/n1920/html/n1920.html).
TEI
C. M. Sperberg-McQueen and Lou Burnard, editors. Guidelines for Electronic Text Encoding and Interchange. Association for Computers and the Humanities (ACH), Association for Computational Linguistics (ACL), and Association for Literary and Linguistic Computing (ALLC). Chicago, Oxford: Text Encoding Initiative, 1994.
CHUM
Steven J. DeRose and David G. Durand. 1995. The TEI Hypertext Guidelines. In Computing and the Humanities 29(3). Reprinted in Text Encoding Initiative: Background and Context, ed. Nancy Ide and Jean Veronis, ISBN 0-7923-3704-2.
XIS
John Cowan and David Megginson, editors. XML Information Set. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/xml-infoset.)
XLink
XML Linking Language (XLink) World Wide Web Consortium Working Draft 30-June -1999. See http://www.w3.org/TR/xlink. Previous version(s), Eve Maler and Steve DeRose, editors: http://www.w3.org/TR/1998/WD-xlink-19980303; http://www.w3.org/TR/WD-xml-link-970731
XPREQ
Steve DeRose, editor. XML XPointer Requirements Version 1.0. Brown University. Seekonk: World Wide Web Consortium, 1999. (See http://www.w3.org/TR/NOTE-xptr-req)
CMOD
Martin Duerst, editor. Character Model for the World Wide Web. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/WD-charmod.)

B. Summary of XPath in the Context of XPointer (Non-Normative)

This appendix provides an overview and explanation of the major features of the XPath specification. This is intended for the reader's convenience in understanding this document, which is vitally dependent upon XPath. This section is sufficient to understand the basics of XPath, but the XPath Recommendation [XPath] is the normative definition for XPath and should be consulted for a more detailed understanding of it.

A full-form XPointer consists of the scheme identifier xpointer with an argument that identifies a location by the methods defined here. This argument may but need not be a LocationPath as defined in XPath. The cases where it is not are defined in this specification.

B.1 XPath Basics

For XPointers, the most important type of XPath Expr is the LocationPath. Although there are a number of syntactic abbreviations possible, in general a LocationPath consists of a slash-separated list of LocationSteps of the form:

axis-name '::' node-test [predicate]*

For example, the following XPath expression would locate the first child of the context node whose element type is List:

child::List[1]

while the following would locate all figure elements that are children of the List element selected by the previous expression:

child::List[1]/child::figure

In the examples above, child is the axis-name. An axis-name specifies a sequence of candidate locations, relative to the "context node" which is one of several bindings in the "evaluation context". The context node is bound to a node in the XML document, and axes locate an ordered set of other nodes in the tree. In the case of the child axis, the located nodes correspond to the immediate child elements of the context node.

In the examples above, the node-tests are List and figure. The node-tests eliminate nodes from the result of an axis that do not match certain criteria. Typically the node-test filters nodes by their element type, as in the examples above.

In the examples above, the predicate [1] is an abbreviated form of the test [position() = 1]. Akin to node-tests, predicates are evaluated for each candidate node and remove it from the results of the location step unless the predicate evaluates to true. Predicates are evaluated for each candidate location along the specified axis, and typically test the element type, attributes, positions, and/or other properties of nodes. Multiple predicates may be specified as successive filters.

As an additional example, the following expression would locate all children of the context node that are of element type para, and then find the first following sibling of each of those nodes that is of type list:

child::para/following-sibling::list[position()=1]

Each location step locates an ordered list of data portions. For all the XPath axes, but not for XPointer's additional axes, each location is a node, and any following location steps are interpreted relative to the nodes located.

Location steps can be used in a sequence, interpreted from left to right. Such sequences are typically used to express a stepwise refinement of a location. For example, id("MYNOTE")/ancestor::SEC locates all SEC elements that contain the element whose ID attribute has value "MYNOTE", while id("MYNOTE")/ancestor::SEC[position()=1] locates the innermost such SEC (that is, the first one in the sequence located, not the first one in document order).

B.2 XPath Axes

XPath's axes, summarized in "B.3 XPath Relative Axes", provide access to nodes that bear significant relationships to a starting node, for example as children, following nodes, attributes, and so on.

The axes that XPointer shares with XPath always locate entire nodes (such as elements, attributes, whole text portions uninterrupted by markup, etc). However, XPointer's range and string axes (defined in a later section) locate ranges that are not necessarily aligned on element boundaries. A common use case for this is when a user selects a range of text in a browser or word processor and then performs an operation on that range, such as annotating it. Such locations are not in fact nodes or lists of nodes, but are ranges as defined in DOM Level 2 (possibly even lists of ranges, in application scenarios supporting multiple selection). Location steps using these two axes may not be used to provide contexts for further location steps.

XPath provides absolute addresses as well, using an initial slash to locate the document root, and id() to locate the node with a given XML ID value. These are adopted by XPointer without change. XPointer also adds special absolute addresses as defined below, to make it more effective and general in a primary application domain: addressing to support hypertext linking.

B.3 XPath Relative Axes

The axes described in this section depend on the existence of a context node, and locate other nodes relative to each of its nodes in turn. Very commonly, location steps in an XPointer are for the purpose of navigation within the tree. The fundamental navigation directions inherent for ordered trees, therefore have corresponding relative axes.

The candidate nodes along a given axis are ordered by distance from the context node. Thus, the ancestor, ancestor-or-self, preceding, and preceding-sibling axes consider nodes in reverse document order. If no prior context is explicitly provided, the context is the root element of the containing resource.

[Definition:] Each of the relative axes locates a list of nodes that are candidates for membership in the result. Actual results are selected by the node-test and predicate arguments as described below. The relative axes are:

child
Locates direct child nodes of the context node, including element, pi, comment, and text. Attributes are not considered children of the elements that bear them (for locating them, use the attribute axis).
descendant
Locates nodes of the same types as child, but appearing anywhere within the content of the context node.
descendant-or-self
Identical to the descendant axis except that the context node itself is included as a candidate, preceding all descendants. Note: This is particularly useful when a precise location is specified by an ID, but there are constraints on the maximal unit to retrieve, such as always showing the SUMMARY whether the ID is on the summary or on its containing SECTION.
parent
Locates the element node directly containing the context node, or directly bearing it if it is an attribute.
ancestor
Locates element nodes containing the context node (since only elements properly have children as defined here). The first node in the list is the immediate parent of the context node.
ancestor-or-self
Identical to the ancestor axis except that the context node itself is included as a candidate, preceding all ancestors. This axis is particularly useful when a precise location is specified by an ID, but there are constraints on the minimal unit to be treated as the final location, such as always locating the containing SECTION whether the ID is on the SECTION or on some particular descendant. For example,
id("ref37")/ancestor-or-self::SEC

would return the SEC which has the element with ID "ref37". "ref37" could be on a small leaf element, an intermediate container, or the SEC itself. Using the ancestor axis, in contrast, would fail or get a higher SEC if "ref37" were on a SEC element itself. This axis can also be used to get the effect of inherited attributes (such as the xml:lang attribute defined in XML 1.0) by locating the list of all ancestor elements, selecting the desired attribute for each of them (any not having it drop out), and then taking the last one. For example,

id("ref37")/ancestor-or-self::*/attribute::lang[position()=last()]

preceding-sibling
Locates sibling nodes (nodes that share the same parent as the context node) that appear before (preceding) the context node. The nodes are considered in reverse document order, so that the first node in the list is the immediately preceding sibling, and the last node in the list is the first child of the parent.
following-sibling
Locates sibling nodes (nodes that share the same parent as the context node) that appear after (following) the context node. The nodes are considered in document order.
preceding
Locates nodes that begin before (preceding) the entire context node. The list is in reverse document order: the node closest to the context node first, root() last. Ancestors are included.
following
Locates nodes that begin after (following) the entire context node. The list is in document order: the first node in the list is for the first node whose start-tag occurs after the context node's end-tag; no ancestors are included.
self
Locates (for each context node), a singleton nodelist containing that same context node. Note: This is useful for applying multiple predicates to a single axis, particularly when predicates other than the first one must test a context node's position among all those context nodes that were selected by the prior predicates.
attribute
The attributes of the context node. If the context node is not of type element, the list is empty. The order and position of nodes on this axis are undefined. Typically, a single attribute will be selected by name.

B.4 XPath Node Tests

NodeTests, like predicates (see below), are applied to each context node. Exactly those for which the NodeTest is true remain in the list. XPath provides three forms of NodeTest.

First, QNames (qualified names) can be used to filter by attribute name or element type.

child::para
locates the <para> elements that are children of the current node.

child::x:para
locates children of the context node if the element type is "x:para",
where the NCName "x" expands to a URI using the namespace declarations
that are provided in the expression evaluation context.

Second, XPath provides the functions comment(), text(), and processing-instruction() for use as NodeTests. They return true if the context node is of the corresponding type.

child::text()
Locates the text nodes that are children of the context node.

/child::comment()
Locates any comments that are siblings of the document element.

/descendant::processing-instruction()
Locates any processing instructions in the entire document.

Third, a Nodetest can be the asterisk (*) wildcard character. When given by itself, it returns true for any node that is of the principal type of the axis. The principal type of the attribute axis is the attribute type, the principal type of the other axes is the element type.

The asterisk wildcard can also be used as the LocalPart of a QName. This allows filtering that selects any element or attribute from a particular namespace.

id("intro")/child::*
Locates all the elements that are direct children of the
intro node. The elements are given in document order.

id("intro")//x:para
Locates only the <para> elements that come from the namespace currently
mapped to the NCName "x". The namespace declarations to use are supplied by
the expression evaluation context.

id("intro")//x:*
Locates any element that is a descendant of the intro node and
comes from the namespace currently mapped to the "x" NCName.

B.5 XPath Predicates

All XPath's relative axes may use zero or more predicates to filter their candidates. XPointer's syntax and semantics for predicates include all of XPath's except for variables (there is no way to bind variables within an XPointer at this time). XPointer also adds a small number of predicates needed for its application domain. This section summarizes the predicate language of XPath and XPointer's additions.

B.5.1 Introduction to Predicates

What is located by a given location step depends on the axis and the predicate(s) -- a node-test may be considered a special-case of a predicate. The axis defines an ordered list of potential candidates, and the predicates (if any) select actual results from among the candidates. The effect is as described below (no particular processing procedure is required; implementations may use any method that produces the results defined in this specification):

  1. The axis defines an ordered list of candidate locations, such as all children of the context node, all following siblings, etc.
  2. The node-test and predicates (if any) are evaluated in order, with each candidate in turn serving as the context node. This eliminates all candidates for which the node-test and predicates do not evaluate to true. In effect, each candidate is tested against the constraints, and only those which fulfill them remain.
  3. Any exact duplicates are removed.

If no predicate or node-test is specified, all candidates become members of the resulting node list.

A node-test is a name or an asterisk (*). A node test that is a QName tests whether the node is an element or attribute with the specified name. For example, attribute::href selects the href attribute of the context node; if the context node has no href attribute, it will select an empty set of nodes. The asterisk locates any element or attribute node regardless of name (but not other node types). Either a name or an asterisk may be qualified by a namespace, and if so, matching requires that the namespace prefixes resolve to the same namespace URI.

Several kinds of tests are provided for use within predicates, and are detailed in following sections. For ease of presentation, this section divides them into Positional tests and Local structure tests. The basic tests can be combined with Boolean, numeric, string and other operators, and parentheses; see XPath for the normative specifications of these features.

B.5.2 Positional Tests

XPath provides several ways of testing the position of a node within a given node-set. First, the XPath predicate function position() returns the integer position, counting from 1, of the context node within the node-set being considered. For example,

child::*/child::*[position()=1]

locates the list of all first element children of all element children of the context node.

Positions within the set of siblings in the actual document structure can be tested by generating that list. For example, the following locates the first item element that is a sibling occurring after the context node:

 following-sibling::item[position()=1] 

The XPath predicate function "last() returns the context size. For example, the following locates the last chapter child of the context node:

 child::chapter[position()=last()] 

The XPath predicate function count(LocationPath) evaluates the LocationPath and returns the number of nodes identified. For example, the following locates all customer elements which have more than one car element child:

 child::customer[count(child::car) > 1]

B.5.3 Local Structure Tests

As described above, tests can be made for the XML node type (such as element vs. processing instruction), for the particular element type name of an element, and for attribute-values. Selection using a named element type is strongly recommended, as it increases the chance that an XPointer will locate no data instead of the wrong data, if re-used after the resource changes.

Also, note that location paths can be embedded in other ones as predicates. Such a location path is evaluated relative to the current context node at that point. An embedded location path that returns a non-empty node list, is considered true. This provides very effective ways of characterizing nodes in terms of their document contexts.

Certain predicates such as tests of attribute values can only be fulfilled by certain node types such as elements. It is not an error to apply such predicates to other nodes; they simply will never come out true.

B.6 Examples of Axis Usage

child
id("intro")/child::* locates all the child elements of the intro node (that is, the node with an ID attribute whose value is "intro"). That is in contrast to id("intro")/child::node() which locates all the nodes, of any type, that are children of the intro node. id("intro")/child::para locates all the element nodes of whose element type (tag name) is para that are direct children of the intro node. id("intro")/child::text() locates all the text nodes that are direct children of the intro node. XPath defines a number of abbreviations. Perhaps the most important of these allows the axis identifier and parentheses to be omitted from a Step. When omitted, the child axis identifier is inferred. Thus, id("intro")/para is equivalent to id("intro")/child::para.
descendant
id("intro")/descendant::* locates all the descendant element nodes of the intro node. A more common use of the descendants axis is in AbsoluteLocationPaths. For example, descendant::para locates all the para elements contained in the context node. This is expected to be used frequently enough that XPath provides the string "//" as a very compact abbreviation for descendant-or-self::node(). The XPathLocationPath //para will also select all the para elements in the context node.
ancestor
This axis is typically used to obtain the parent node of one identified by other means. For example id("intro")/ancestor::*[1] locates the parent element of the intro element.
attribute
id("intro")/attribute::* locates the attributes of the intro element. If the attribute of type ID was also named ID, then id("intro")/attribute::ID would locate it.

C. Working Group Members (Non-Normative)

The first working drafts of this specification were developed in the XML Working Group, whose members are listed in the XML Recommendation [XML]. The work was completed in the XML Linking Working Group, with the following members active at the completion of this specification:

The editors wish to acknowledge substantial contributions by Tim Bray (of Textuality) who served as co-editor on earlier Working Drafts. We would also like to acknowledge substantial contributions from James Clark, especially on the integration with XPath.