W3C

XML Pointer Language (XPointer) Version 1.0

W3C Candidate Recommendation 7 June 2000

This version:
http://www.w3.org/TR/2000/CR-xptr-20000607 (available in HTML and XML)
Latest version:
http://www.w3.org/TR/xptr
Previous versions:
http://www.w3.org/TR/1999/WD-xptr-19991206
Editors:
Ron Daniel Jr. (Metacode Technologies, Inc.) <rdaniel@metacode.com>
Steve DeRose (Brown University Scholarly Technology Group) <Steven_DeRose@Brown.edu>
Eve Maler (Sun Microsystems) <elm@east.sun.com>

Abstract

This specification defines the XML Pointer Language (XPointer), the language to be used as the basis for a fragment identifier for any URI reference that locates a resource of Internet media type 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 examination of a hierarchical document structure and choice of its internal parts based on various properties, such as element types, attribute values, character content, and relative position.

Status of this document

This document is a Candidate Recommendation of the World Wide Web Consortium. (For background on this work, please see the XML Activity Statement.) This specification is considered stable by the XML Linking Working Group and is available for public review during the Candidate Recommendation stage ending 7 September 2000.

The Working Group invites implementation feedback during this period. Comments on this document should be sent to the public mailing list www-xml-linking-comments@w3.org (archive). While we welcome implementation experience reports, the XML Linking Working Group will not allow early implementation to constrain its ability to make changes to this specification prior to final release.

This document is intended to be taken in conjunction with the IETF XML Media Types Internet Draft [IETF I-D XMT], in order for that document to officially designate XPointer as the fragment identifier language for text/xml or application/xml. However, because of the timing problems associated with publishing two related documents on separate tracks, currently that document refers to this one only non-normatively. It is anticipated that the Internet Draft will be updated to make a normative reference when XPointer reaches the Recommendation stage.

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

For information about the requirements that informed development of this specification, see http://www.w3.org/TR/NOTE-xptr-req.

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

Table of Contents

1 Introduction
    1.1 Origin and Goals
    1.2 Notation and Document Conventions
2 XPointer Terms and Concepts
3 XPointer Processing and Conformance
    3.1 Processing Dependencies
    3.2 String Conformance
    3.3 Application Conformance
    3.4 Specification Conformance
    3.5 Classes of XPointer Errors
4 XPointer Model and Language
    4.1 Character Escaping
        4.1.1 URI Reference Encoding and Escaping
        4.1.2 XML Escaping
        4.1.3 XPointer Escaping
    4.2 Forms of XPointer
        4.2.1 Full XPointers
        4.2.2 Bare Names
        4.2.3 Child Sequences
    4.3 Schemes
5 XPointer Extensions to XPath
    5.1 XPointer Additions to XPath Terms and Concepts
    5.2 Evaluation Context Initialization
    5.3 The point and range Location Types
        5.3.1 Definition of Point Location
        5.3.2 Definition of Range Location
        5.3.3 Covering Ranges for All Location Types
        5.3.4 Tests for point and range Locations
        5.3.5 Document Order
    5.4 XPointer Functions
        5.4.1 range-to Function
        5.4.2 string-range() Function
        5.4.3 Additional Range-Related Functions
        5.4.4 here Function
        5.4.5 origin Function
        5.4.6 unique Predicate Function

Appendices

A References
    A.1 Normative References
    A.2 Non-Normative References
B Working Group Members (Non-Normative)


1 Introduction

This specification defines the XML Pointer Language (XPointer), the language to be used as the basis for a fragment identifier for any URI reference that locates a resource of Internet media type 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, although it provides extension facilities that may be used with other types.

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

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

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

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

Note:

XPointer is intended to be the basis of fragment identifiers only 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. (Note that a recent Internet Draft [IETF I-D XMT] suggests the use of a naming convention for specialized media types based on XML.) XPointer is expected to be useful as a fragment identifier language for the generic XML aspects of those media types. Special schemes (discussed in 4.3 Schemes) can be used to perform special access to the content of those media types.

1.1 Origin and Goals

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

  • HTML [HTML]: This system popularized an important location specifier type, the URL (now URI).

  • HyTime [ISO/IEC 10744]: This ISO standard defines location specifier types for all kinds of data.

  • Text Encoding Initiative Guidelines [TEI]: This application provides a formal syntax for "extended pointers," locators for structured markup that underlie the initial design for XPointer.

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

See the XPointer Requirements Document [XPREQ] for a thorough explanation of requirements for the design of XPointer.

1.2 Notation and Document Conventions

The formal grammar for XPointer is given using a simple Extended Backus-Naur Form (EBNF) notation, as described in the XML Recommendation [XML]. The circumflex (^) metacharacter used in this notation is not to be confused with the circumflex used to escape parenthesis characters in an XPointer.

The prototypes for XPointer functions are given using the same notation used in the [XPath] Recommendation.

This specification contains some explanatory text on the XPath language; however, such text is non-normative. In the case of conflicts, [XPath] is the normative version.

2 XPointer Terms and Concepts

Some special terms are defined here in order to clarify their relationship to similar terms used in the technologies on which XPointer is based. Additional XPointer-specific terms are defined in the flow of the text. Refer to [XPath], [DOM2], [XIS], and [IETF RFC 2396] for definitions of other technical terms used in this specification.

[Definition: sub-resource]

The portion of an XML resource that is identified by an XPointer. For example, the whole resource being referred to is an XML document, but a sub-resource might be a particular element inside the document. Following a link to such a sub-resource might result, for example, in highlighting that element or scrolling to that point in the document.

[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 that is produced by XPath expressions, except for the generalization to include points and ranges.

[Definition: point]

A position in XML information. This notion comes from the DOM Level 2 [DOM2] specification's notion of positions; this specification refers to DOM positions by the term "point" to avoid confusion with XPath positions.

[Definition: range]

An identification of a contiguous selection of all the XML information between a pair of end points. This notion comes from the DOM Level 2 [DOM2] specification.

[Definition: singleton]

A location that consists of a single, contiguous portion of a document. Some XPointers can locate multiple data portions, such as three contiguous item element nodes in a list or six noncontiguous occurrences of a string in a document. When an XPointer instead locates only a single contiguous data portion such as a range, string range, or single node, that location is said to be a singleton. (See 5.4.6 unique Predicate Function for an example.)

3 XPointer Processing and Conformance

This section details processing and conformance requirements on XPointers, the fragment identifiers that are based on them, and the applications that create and process them.

[Definition: The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [IETF RFC 2119].]

3.1 Processing Dependencies

XPointer processing depends on [XPath] and [IETF RFC 2396] (as updated by [IETF RFC 2732]) processing.

3.2 String Conformance

A string conforms to the XPointer specification if it adheres to the syntactic requirements imposed by this specification (including [XPath], whose requirements are imposed by reference). This specification does not require that the string, in association with a URI, actually point to a resource or sub-resource that exists at any given moment.

3.3 Application Conformance

Application software conforms to this specification if it recognizes XPointers that appear (suitably escaped) as the fragment identifier of a URI reference which locates a resource whose Internet media type is text/xml or application/xml, and correctly interprets such fragment identifiers according to the semantics prescribed by this specification. Processing of the results and/or errors arising from evaluation of an XPointer is defined by the application.

3.4 Specification Conformance

Specifications that use URI references in relation to resources whose media type is text/xml or application/xml are required to use XPointer syntax (suitably escaping) and semantics for the fragment identifier.

3.5 Classes of XPointer Errors

The use of XPointers can give rise to several kinds of errors:

  • [Definition: A string that does not match the syntax specified in this document has a syntax error, and applications must not attempt to evaluate it as an XPointer.]

  • [Definition: If a syntactically correct XPointer fragment identifier is appended to a URI that identifies no resource, or a resource that is not well-formed XML, the XPointer has a resource error.]

  • [Definition: If a syntactically correct XPointer fragment identifier fails as discussed in 4.3 Schemes, the XPointer has a sub-resource error.] Note that XPath allows expressions that return empty node-sets as their results and does not regard this situation as an error. Because the XPointer language is intended as a specification of document locations rather than a broader query language, an empty result is an error.

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

4 XPointer Model and Language

XPointers, like XPath expressions, operate on the XML information set [XIS], a data set derived from the elements and other markup constructs of an XML document. Both XPointers and XPath expressions operate by selecting portions of such data sets, often by their structural relationship to other parts (for example, the parent of a node with a certain ID value). XPointers use iterative selections, each operating on what is found by the prior one.

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

4.1 Character Escaping

The XPointer language is designed to be used in the context of URI references, which require encoding and escaping of certain characters. XPointers also often appear in XML documents, and the XML context imposes some escaping requirements of its own. Finally, because some characters are significant to XPointer processing, escaping is needed to use these characters in their ordinary sense.

For convenience, this section describes the escaping necessary for these contexts. However, see [IETF RFC 2396], [IETF RFC 2732], and [XML] for definitive information on characters that must be escaped before use.

4.1.1 URI Reference Encoding and Escaping

This specification governs the syntax of XPointers that have not yet been treated for use in URI references or other contexts.

The set of characters for XPointers is the same as for XML, namely [Unicode]. However, some Unicode characters are disallowed from URI references, and thus XPointers that appear in URI references must encode and escape these characters as appropriate. [Definition: The URI-escaped form of an XPointer is called an XPointer fragment identifier.]

The disallowed characters include all non-ASCII characters, plus the excluded characters listed in Section 2.4 of [IETF RFC 2396], except for the crosshatch (#) and percent sign (%) characters and the square bracket characters re-allowed in [IETF RFC 2732]. Disallowed characters must be escaped as follows:

  1. Each disallowed character is converted to UTF-8 [IETF RFC 2279] as one or more bytes.

  2. Any octets corresponding to a disallowed character are escaped with the URI escaping mechanism (that is, converted to %HH, where HH is the hexadecimal notation of the byte value).

  3. The original character is replaced by the resulting character sequence.

For example, if spaces are used between parts of an XPointer, the spaces need to be escaped in the XPointer fragment identifier. In XPointer, square brackets also appear frequently; while [IETF RFC 2732] allows them to appear untreated, they should be escaped for compatibility with applications that have not implemented the [IETF RFC 2732] update to [IETF RFC 2396].

The following example shows an XPointer containing various characters that might need special treatment: spaces, brackets, and accented characters:

xpointer(id('résumé')) xpointer(//*[@id='résumé'])

The following example shows the resulting XPointer fragment identifier appearing as part of a URI reference, where these characters have been escaped:

doc.xml#xpointer(id('r%C3%A9sum%C3%A9'))%20xpointer(//*%5B@id='r%C3%A9sum%C3%A9'%5D)

Applications that encounter what is intended to be an XPointer fragment identifier must resolve the encoding and escaping in the reverse order of the process described in this section. If the result does not conform to the syntactic rules for XPointers in this specification, a syntax error results.

4.1.2 XML Escaping

When XPointers appear in XML document content, they must escape occurrences of left angle brackets (<), ampersands (&), and other special characters according to the directions in [XML]. One option is to use &lt; and &amp; respectively for left angle brackets and ampersands.

For example, an XPointer that identifies the first five chapter elements of a document would need escaping because of the left angle bracket in its comparison operator.

The unescaped XPointer is as follows:

xpointer(book/chapter position() <= 5)

The XML-escaped XPointer appearing in an XLink link is as follows:

<simpleLink
    xmlns:xlink="http://www.w3.org/2000/xlink"
    xlink:type="simple"
    xlink:href="doc.xml#xpointer(book/chapter position() &lt;= 5)" />

Note that if XML-based languages define elements or attributes containing URI references (such as XLink's href attribute shown above), the relevant element content or attribute values also require the processing defined in 4.1.1 URI Reference Encoding and Escaping.

4.1.3 XPointer Escaping

The parts of an XPointer each contain a balanced pair of parentheses that delimit the XPointer information. In order for the outermost ending parenthesis to be reliably recognized by an XPointer application, parentheses inside it must be balanced as well. Any unbalanced parenthesis character must be escaped. See 4.2 Forms of XPointer for more information.

4.2 Forms of XPointer

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

The full form is described in 4.2.1 Full XPointers. The two short forms are bare names (Name, described in 4.2.2 Bare Names) and child sequences (ChildSeq, described in 4.2.3 Child Sequences). Thus, XPointer offers the following overall options.

XPointer Forms
XPointer   ::=   Name
| ChildSeq
| FullXPtr

The internal structure of an XPointer is as follows.

Internal Structure of XPointer
ChildSeq   ::=   '/1' ('/' [0-9]*)*
| Name ('/' [0-9]*)+
FullXPtr   ::=   XPtrPart (S? XPtrPart)*
XPtrPart   ::=    'xpointer' '(' XPtrExpr ')'
| Scheme '(' SchemeSpecificExpr ')'
Scheme   ::=   NCName - 'xpointer'[VC: Non-XPointer schemes]
SchemeSpecificExpr   ::=   StringWithBalancedParens
StringWithBalancedParens   ::=   [^()]* ('(' StringWithBalancedParens ')' [^()]*)*[VC: Parenthesis escaping]
XPtrExpr   ::=   Expr[VC: Parenthesis escaping]

Validity constraint: Non-XPointer schemes

Currently, no schemes other than xpointer are allowed. See 4.3 Schemes for more information.

Validity constraint: Parenthesis escaping

The end of an XPointer part is signaled by the right parenthesis ")" character that is balanced with the left parenthesis "(" character that began the part. Any unbalanced parenthesis character inside the expression, even within literals, must be escaped with a circumflex (^) character preceding it. If the expression contains any literal occurrences of the circumflex, each must be escaped with an additional circumflex (that is, ^^). If the unescaped parentheses in the expression are not balanced, a syntax error results.

Name and S are as defined in the XML Recommendation [XML]; NCName is as defined in the Namespaces in XML Recommendation [XML-Names]; and Expr is as defined in the XPath Recommendation [XPath], with the XPointer extensions defined in this specification.

4.2.1 Full XPointers

The full form of addressing consists of one or more XPointer parts, optionally separated by whitespace. Each starts with a scheme name and is followed by a parenthesized expression. When the scheme is xpointer (see 4.3 Schemes for more information), the associated expression provides access to nodes in an XML document's information set (except for nodes representing CDATA sections and entities) and access to arbitrary non-node locations.

4.2.2 Bare Names

The appearance of a "bare name" stands for the same name provided as the argument of a location step using the id() function. For example, the first XPointer below is the bare-name equivalent of the second, which uses the full XPointer form:

intro
xpointer(id("intro"))

The bare-name shorthand is provided for two reasons:

  • To encourage use of IDs, which are the form of addressing most likely to survive document change. (See [XPREQ] and [RLocs] for more information on creating robust addresses into resources.)

  • To provide an analog of the HTML fragment identifier behavior for resources with XML media types that use a markup language similar to that of HTML. (Note that the XHTML specification [XHTML] defines some guidelines for anchors that help the bare-name shorthand to work in concert with the HTML fragment identifier in cases of content negotiation.)

4.2.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].

The first segment of the child sequence can be either a name, which locates an element as described for bare names in 4.2.2 Bare Names, or the string /1, which locates the document element. For example, the following two XPointers would locate the same XML information, where intro is the ID attribute value of an element that is the fifth child of the second child of the document element:

intro/14/3
/1/2/5/14/3

4.3 Schemes

In a full-form XPointer, an initial Scheme identifies the particular notation used for each XPtrPart. Having an explicit Scheme allows for possible future versions of the XPointer language to identify themselves, as well as allowing alternative addressing languages for XML-based languages such as SVG or SMIL to identify themselves.

Note:

Because there is no way to avoid conflicts in scheme naming and use, the only scheme allowed in this version of the XPointer specification is xpointer. All other scheme names are reserved. Users who want to define or use new schemes are invited to check the XPointer errata document [ERR] for a possible solution.

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

When multiple XPtrParts are provided, they must be evaluated in left-to-right order. If evaluation of one part fails, the next is evaluated. The following conditions cause XPointer part failure:

  • An unknown scheme

  • A scheme that does not locate any sub-resource present in the resource

  • A scheme that is not applicable to the media type of the resource

The XPointer application must consume a failed XPointer part and attempt to evaluate the next one, if any. The result of the first XPointer part whose evaluation succeeds is taken to be the fragment located by the XPointer as a whole. If all the parts fail, the result for the XPointer as a whole is a sub-resource error.

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

xpointer(id("chap1"))

However, in the absence of the DTD, it is not typically possible to determine if an attribute is of type ID. An XPointer like the following, with two parts, will have its first part fail if no DTD is available, but will have its second part succeed if the desired attribute's name is id; note that the intent of the second XPointer part is just an approximation of the first.

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

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

5 XPointer Extensions to XPath

XPointer extends XPath by adding the following:

5.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 might have different sets of ancestors in the hierarchy, or the region might form only a small part of a node. For example, a range could be a single letter or could extend from the middle of one paragraph to the middle of the next, thus containing only part of the relevant paragraphs and text nodes. Even though such locations are not nodes, XPointer needs to be able to apply XPath operations to them as well as to nodes.

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

Note:

The order of characters displayed on a computer screen might not reflect their order in the underlying XML document, for example, when a portion of a right-to-left language such as Arabic is embedded in a left-to-right language such as French. For XPointers that identify ranges of strings, the document order is used, not the display order. Thus, an XPointer for a single range might be displayed non-contiguously, and conversely a user selection of an apparent single range might correspond to multiple non-contiguous XPointer ranges in the underlying document.

5.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. XPointer applications must initialize the evaluation context as described in this section before evaluating an XPtrExpr.

An XPointer evaluation context contains the following information:

  • A location (the context location), initialized to the root node of an XML document. When the XPointer is a fragment identifier of a URI reference, the document is the one identified by the URI portion. If an application uses XPointers in another context than as a URI reference's fragment identifier, this specification does not constrain how the applicable document is chosen.

  • A non-zero context position, initialized to 1.

  • A non-zero context size, initialized to 1. (At the start, the only location in the current location list is the context location.)

  • A set of variable bindings. No means for initializing these is defined for XPointer applications. Thus, the set of variable bindings used when evaluating an XPointer is empty, and use of a variable reference in an XPointer results in a syntax error.

  • A library of functions. Only functions defined in XPath or XPointer can be used in XPointers. An XPointer that uses other functions results in a syntax error.

  • The set of namespace declarations in scope for the expression. For any XPointer fragment identifier that appears in an XML document, the namespace declarations in the evaluation context of the XPointer must be initialized to the namespace declarations currently in scope for the XPointer.

    For any XPointer fragment identifier that does not occur in an XML document, the namespace declarations must be initialized so that the xml prefix is bound to the URI http:/www.w3.org/XML/1998/namespace. No other namespace declarations shall be in its evaluation context.

    Note:

    If an XPointer subsequently gets used in another document (for example, through a copy-and-paste user interface), the application may need to perform a transformation on the XPointer to ensure that the desired sub-resource is explicitly namespace-qualified, so that additional context is not needed.

    For example, if there is an XML document containing an element ex:y that is in the scope of a namespace declaration xmlns:ex="http://example.com/foo", then the following XPointer will work properly if it appears in the scope of this declaration:

    xpointer(//ex:y)

    If this XPointer is moved or copied to an XML document where such a namespace declaration is not in force or to a non-XML document, it can still address the desired element properly if it is transformed to the following form:

    xpointer(//*[local-name()='y' and namespace-uri()='http://example.com/bar'])

    It is possible that an apparent XPointer (conforming to the syntax defined in this specification) is not a real XPointer because the media type of the target resource turns out not to be text/xml or application/xml; only accessing the target resource can determine this for sure. However, for the purpose of transplanting XPointers to new locations, access is not required; if the fragment identifier merely matches the XPointer syntax and has an xpointer scheme, then it should be expanded as appropriate.

5.3 The point and range Location Types

To address 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 their characteristics required for XPath interoperability.

Note:

Unlike DOM Level 2, which is based on UTF-16 units, XPath and XPointer are based on UCS characters. So while the concepts of points and ranges are based on the DOM 2 notions of positions and ranges, there are differences in detail. For example, a sequence which in DOM counts as two characters might count in XPointer as one character.

Points and ranges can be used as XPointer context locations. This allows the XPointer [] operator to be used to select from sets of ranges. Also, a point as a context location, when followed by a range-to function, selects a range.

5.3.1 Definition of Point Location

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

Note:

This specification does not constrain the implementation of points; applications need not actually represent points using data structures consisting of a node and an index.

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

Note:

The zero-based counting of node-points differs from the one-based counting of string-range and other XPointer and XPath functions.

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

Point locations do not have an expanded-name.

The string-value of a point location is empty.

The axes of a point location are defined as follows:

  • A point location has no children.

  • A character-point has no preceding or following siblings.

  • A node-point's siblings are the children of the container node that are before or after the node-point.

5.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 might be only partly included. The start and end points of a range must be in the same document. The start point must not appear after the end point in document order.

[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 node. For example, it is allowed to specify a range from the start of a processing instruction to the end of an element (encompassing both those nodes, but still a singleton), but not to specify a range from text inside a processing instruction to text outside it.

Range locations do not have an expanded-name.

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

The axes of a range location are the axes of its start point.

Note:

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

5.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:

  • For a range location, the covering range is identical to the range.

  • 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 a point location, the start and end points of the covering range are the point itself.

  • For any other kind of location, the container node of the start point and end point of the covering range is the parent of the location; the index of the start point of the covering range is the number of preceding sibling nodes of the location; and the index of the end point is one greater than the index of the starting point.

    This definition ensures that for a range location, as for every other type of location, the ancestor, preceding, following, descendant, and self axes do not intersect and that they together contain all locations in the document (other than attribute, namespace, and range locations).

5.3.4 Tests 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
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 might include locations of all three types.

5.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 a node-point with a non-zero index, the immediately preceding node is the node immediately preceding the point (that is, the node that is the nth child of the container node, where n is the index).

  • For a node-point with a zero index, the container node is also the immediately preceding node unless it has any attribute or namespace nodes. If the container node does have attribute or namespace nodes, then the immediately preceding node is the last of those nodes.

  • For a character-point the immediately preceding node is the container node of the character-point.

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

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

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

Document order for a point is defined as follows:

  • If the immediately preceding nodes of the two points are the same, then either the points are the same or they are both character-points with the same container node; in the latter case, the order of the indices determines the document order.

  • Otherwise, the document order of the immediately preceding nodes of the points determines the document order of the points.

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

  • the starting point of the one range is before the starting point of the other range, or

  • the starting point of the one range is the same as the starting point of the other range, and the ending point of the one range is before the ending point of the other range.

5.4 XPointer Functions

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

5.4.1 range-to Function

location-set range-to(expression )

For each location in the context, range-to returns a range. The start point of the range is the start of the context location, and the end point of the range is the end of the location found by evaluating the expression argument with respect to that context location.

For example, the following XPointer locates the range from the element with ID "chap1" to the element with ID "chap2".

xpointer(id("chap1")/range-to(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 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/range-to(following::REVEND[1]))

Note:

XPath does not permit functions immediately following the slash as shown here; XPointer does.

5.4.2 string-range() Function

location-set string-range(location-set , string, number?, number? )

[Definition: For each location in the location-set argument, string-range returns a set of string ranges, a set of substrings in a string. Specifically, the string-value of the location is searched for substrings that match the string argument, and the resulting location-set will contain a range location for each non-overlapping match.] An empty string is considered to match before each character of the string-value and after the final character. Whitespace in a string is matched literally, with no normalization except that provided by XML for line ends. The third argument gives the position of the first character to be in the resulting range, relative to the start of the match. The default value is 1, which makes the range start immediately before the first character of the matched string. The fourth argument gives the number of characters in the range; the default is that the range extends to the end of the matched string.

Element boundaries, as well as entire embedded nodes such as processing instructions and comments, are ignored as defined in [XPath].

If the string in the second argument is not found in the string-value of the location, or if a value in the third or fourth argument indicates a string that is beyond the beginning or end of the document, the expression fails.

The points of the range-locations in the returned location-set will all be character points.

For example, the following expression returns a range that selects the 17th occurrence of the string "Thomas Pynchon" occurring in a 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)[17]

Alternatively this could be specified as follows:

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

String-values are "views" into only the string content of a document; they do not retain the structural context of any non-text nodes interspersed with the text. Because the string-range function operates on a string-value, markup that intervenes in the middle of a string does not prevent a match. (Note that for this reason, a string-range match is on the range describing the relevant substring of the string-value, not necessarily on a contiguous string in a single text node in the document.) For example, if the 17th occurrence of "Thomas Pynchon" had some inline markup in it as follows, it would not change the string returned by the XPointer application:

Thomas <em>Pyn</em>chon

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]

Although these examples locate ranges in elements, string-range is useful for locating ranges that are wholly enclosed in other node types as well, such as attributes, processing instructions, and comments.

5.4.3 Additional Range-Related Functions

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.

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.

point start-point(point)

For each location x in the argument location-set, start-point adds a location of type point to the result location-set. That point represents the start point of location x and is determined by the following rules:

  • If x is of type point, the start point is x.

  • If x is of type range, the start point is the start point of x.

  • If x is of type root, element, text, comment, or processing instruction, the container node of the start point is x and the index is 0.

  • If x is of type attribute or namespace, the function must signal a syntax error.

point end-point(point)

For each location x in the argument location-set, end-point adds a location of type point to the result location-set. That point represents the end point of location x and is determined by the following rules:

  • If x is of type point, the resulting point is x.

  • If x is of type range, the resulting point is the end point of x.

  • If x is of type root or element, the container node of the resulting point is x and the index is the number of location children of x.

  • If x is of type text, comment, or processing instruction, the container node of the resulting point is x and the index is the length of the string-value of x.

  • If x is of type attribute or namespace, the function must signal a syntax error.

5.4.4 here Function

location-set here()

The here function returns a location-set with a single member. That location locates the node that directly contains the XPointer being evaluated. This expression results in a syntax error if the resource in which the containing XPointer appears is not XML.

Note:

The type of the node is likely to be text, attribute, or processing-instruction. The returned location for an XPointer appearing in element content does not have a node type of element because the XPointer is in a text node that is itself inside an element.

5.4.5 origin 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 traversal instruction from an XML document. (See [XLink] for information about traversal.)

It is a resource error to use origin in the fragment identifier portion of a URI reference where a URI is also provided and identifies a containing resource different from the resource from which traversal was initiated, or in a situation where traversal is not occurring.

5.4.6 unique Predicate Function

boolean unique()

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

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

The unique function is shorthand for the following XPath expression:

count()=1

Making this its own function might simplify optimization of XPointer evaluation, such as by using methods understood from the treatment of singleton results in database systems.

Note that different XPointers can create different location-sets that cover similar document scopes in the same XML information, but where the sets divide up the scopes differently: retrieving a set of smaller locations, as opposed to the range the covers the same total scope. For example, consider a list element with ID "list37", which contains three item element children, but no other children. The following XPointer returns a location-set that has three members, the item children in that list:

xpointer(id('list37')/item)

The returned location-set will not be a singleton: it has as many members as there are item children. In contrast, the following XPointer returns a singleton location-set:

xpointer(id('list37')/item[1]/range-to(following-sibling(item)[2])

This singleton happens to start at the same point that the first member of the location-set just shown does, and end at the same point that the last member of it does; but it is not the same location-set: It is a singleton location-set whose one member is a range, not a three-member location-set whose members are item element nodes.

A References

A.1 Normative References

IETF RFC 2119
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels. Internet Engineering Task Force, 1997. (See http://www.ietf.org/rfc/rfc2119.txt.)
IETF RFC 2279
RFC 2279: UTF-8, a transformation format of ISO 10646. Internet Engineering Task Force, 1998. (See http://www.ietf.org/rfc/rfc2279.txt.)
IETF RFC 2376
RFC 2376: XML Media Types. Internet Engineering Task Force, 1998. (See http://www.ietf.org/rfc/rfc2376.txt.)
IETF RFC 2396
RFC 2396: Uniform Resource Identifiers. Internet Engineering Task Force, 1995. (See http://www.ietf.org/rfc/rfc2396.txt.)
IETF RFC 2732
RFC 2732: Format for Literal IPv6 Addresses in URL's. Internet Engineering Task Force, 1999. (See http://www.ietf.org/rfc/rfc2732.txt.)
DOM2
Document Object Model (DOM) Level 2 Specification: Version 1.0. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/DOM-Level-2/.)
Unicode
The Unicode Consortium. The Unicode Standard. (See http://www.unicode.org/unicode/standard/standard.html.)
XML
Tim Bray, Jean Paoli, and C.M. Sperberg-McQueen, editors. Extensible Markup Language (XML) 1.0. World Wide Web Consortium, 1998. (See http://www.w3.org/TR/REC-xml.)
XML-Names
Tim Bray, Dave Hollander, and Andrew Layman, editors. Namespaces in XML. Textuality, Hewlett-Packard, and Microsoft. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/REC-xml-names/.)
XPath
James Clark and Steve DeRose, editors. XML Path Language (XPath). World Wide Web Consortium, 1999. (See http://www.w3.org/TR/xpath.)

A.2 Non-Normative References

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.
CMOD
Martin Dürst and François Yergeau, editor. Character Model for the World Wide Web. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/charmod/.)
Dexter
Halasz, Frank. 1994. "The Dexter Hypertext Reference Model." In Communications of the Association for Computing Machinery 37 (2), February 1994: 30-39.
ERR
XPointer Errata. This document will be created when XPointer goes to Recommendation. Until that time, check the public XML Linking page at http://www.w3.org/XML/Linking.html.
FRESS
Steven J. DeRose and Andries van Dam. 1999. "Document structure in the FRESS Hypertext System." Markup Languages 1 (1) Winter. Cambridge: MIT Press: 7-32. (See http://www.stg.brown.edu/~sjd/fress.html.)
HTML
HTML 4.01 Specification. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/html4/.)
IETF I-D XMT
Internet Draft: XML Media Types. Internet Engineering Task Force, 2000. (See http://search.ietf.org/internet-drafts/draft-murata-xml-04.txt.)
Intermedia
Yankelovich, Nicole, Bernard J. Haan, Norman K. Meyrowitz, and Steven M. Drucker. 1988. "Intermedia: The Concept and the Construction of a Seamless Information Environment." IEEE Computer 21 (January, 1988): 81-96.
ISO/IEC 10744
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.)
MicroCosm
Hall, Wendy, Hugh Davis, and Gerard Hutchings. 1996. Rethinking Hypermedia: The Microcosm Approach. Boston: Kluwer Academic Publishers. ISBN 0-7923-9679-0.
OHS
van Ossenbruggen, Jacco, Anton Eliëns and Lloyd Rutledge. "The Role of XML in Open Hypermedia Systems." Position paper for the 4th Workshop on Open Hypermedia Systems, ACM Hypertext '98. (See http://aue.auc.dk/~kock/OHS-HT98/Papers/ossenbruggen.html.)
RLocs
Thomas A Phelps and Robert Wilensky. Robust Intra-document Locations. University of California, Berkeley. (See http://www.cs.berkeley.edu/~phelps/Robust/Locations/RobustLocations.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. (See http://www.uic.edu/orgs/tei/p3/.)
XHTML
XHTML 1.0: The Extensible HyperText Markup Language. World Wide Web Consortium, 2000. (See http://www.w3.org/TR/xhtml1/.)
XIS
John Cowan and David Megginson, editors. XML Information Set. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/xml-infoset.)
XLink
Steve DeRose, Eve Maler, David Orchard, and Ben Trafford, editors. XML Linking Language (XLink). World Wide Web Consortium, 2000. (See http://www.w3.org/TR/xlink/.)
XPREQ
Steve DeRose, editor. XML XPointer Language Requirements Version 1.0. World Wide Web Consortium, 1999. (See http://www.w3.org/TR/NOTE-xptr-req.)

B Working Group Members (Non-Normative)

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.