1.1. Introduction

XPath 1.0 [XPath 1.0] is becoming an important
part of a variety of many specifications including XForms,
XPointer, XSL, XML Query, and so on. It is also a clear advantage
for user applications which use DOM to be able to use XPath
expressions to locate nodes automatically and declaratively. But liveness issues have
plagued each attempt to get a list of DOM nodes matching specific
criteria, as would be expected for an XPath API. There have also
traditionally been model mismatches between DOM
and XPath. This proposal specifies new interfaces and approaches to
resolving these issues.

Issue XPath-2:

There should be a function to generate an XPath expression
which addresses any arbitrary node within the DOM.Resolution: Out of scope.
That is out of scope for the current requirements of this module.
It could be a quite useful feature but probably not as a part of
this module.

1.2. Mapping DOM to XPath

1.2.1. Text Nodes

The XPath model relies on the XML Information Set [XML Information
set] ands represents Character Information Items in a single logical text
node where DOM may have multiple fragmented Text nodes
due to cdata sections, entity references, etc. Instead of returning
multiple nodes where XPath sees a single logical text node, only
the first non-empty DOM Text or
CDATASection node of any logical XPath text will be
returned in the node set. Applications using XPath in an
environment with fragmented text nodes must manually gather the
text of a single logical text node possibly from multiple nodes
beginning with the first Text node or
CDATASection node returned by the implementation.

Note: In an attempt to better implement the XML
Information Set, DOM Level 3 Core [DOM Level 3 Core] adds the
attribute wholeText on the Text interface
for retrieving the whole text for logically-adjacent
Text nodes and the method replaceWholeText
for replacing those nodes.

1.2.2. Namespace Nodes

The XPath model expects namespace nodes for each in-scope
namespace to be attached to each element. DOM and certain
other W3C Information Set conformant implementations only maintain
the declaration of namespaces instead of replicating them on each
Element where they are in-scope. The DOM
implementation of XPath returns a new node of type
XPATH_NAMESPACE_NODE, defined in the XPathNamespace
interface, to properly preserve identity and ordering. This node
type is only visible using the XPath evaluation methods.

1.2.3. Document order

The document
order of nodes in the DOM Core has been defined to be
compatible with the
XPath document order. The XPath DOM is extending the
document order of the DOM Core to include the XPathNamespace nodes.
Element nodes occur before their children. The attribute nodes and
namespace nodes of an element occur before the children of the
element. The namespace nodes are defined to occur before the
attribute nodes. The relative order of namespace nodes is
implementation-dependent. The relative order of attribute nodes is
implementation-dependent. The compareTreePosition
method on the Node interface defined in the DOM Core
must compare the XPathNamespace nodes
using this extending document order if the XPath DOM module is
supported.

1.3. Interfaces

An implementation is DOM Level 3 XPath conformant if it supports
the Core module defined in [DOM Level 2 Core] and the module
defined in this specification. An implementation conforms to a DOM
module if it supports all the interfaces for that module and the
associated semantics.

A DOM application may use the hasFeature(feature,
version) method of the DOMImplementation
interface with parameter values "XPath" and "3.0" (respectively) to
determine whether or not the XPath module is supported by the
implementation. In order to fully support this module, an
implementation must also support the "Core" feature defined in the
DOM Level 2 Core specification [DOM Level 2 Core].

A DOM implementation must not return true to the
hasFeature(feature, version) method of the
DOMImplementation interface for that feature unless the
implementation conforms to that module. The version number for the
feature used in this document is "3.0".

If the expression has a syntax error or otherwise is not a
legal expression according to the rules of the specific XPathEvaluator. If the
XPathEvaluator was
obtained by casting the document, the expression must be XPath 1.0
with no special extension functions.

Issue XPath-4:

A separate exception should be raised if there are problems
resolving namespaces.Resolution: Yes. These now raise DOMException with the code
NAMESPACE_ERR.

The evaluation of XPath expressions is provided by
XPathEvaluator, which will provide evaluation of XPath
1.0 expressions with no specialized extension functions or
variables. It is expected that the XPathEvaluator
interface will be implemented on the same object which implements
the Document interface in an implementation which
supports the XPath DOM module. XPathEvaluator
implementations may be available from other sources that may
provide support for special extension functions or variables which
are not defined in this specification.

Issue XPath-16:

The methods of XPathExpression should be named with more-XPath-
specific names because the interface will often be implemented by
the same object which implements document.Resolution: No change.
The point of interfaces is to localize the implementing namespace.
This would make the method names unnecessarily long and complex
even though there are no conflicts in the interface itself. The new
core method getInterface is designed for discovering interfaces of
additional modules that may not be directly implemented on the
objects to which they are attached. This could be used to implement
XPath on a separate object. The user only refers to the separate
interfaces and not the proprietary aggregate implementation.

Issue XPath-22:

Should entity refs be supported so that queries can be made on
them?Resolution: No change.
We will not do this now. They are not part of the XPath data model.
Note that they may be present in the hierarchy of returned nodes,
but may not directly be requested or returned in the node set.

Issue XPath-24:

What does createResult create when one wants to reuse the
XPath?Resolution: It is not useful.
Removed method.

Issue XPath-27:

Should ordering be a separate flag, or a type of result that
can be requested. As a type of result, it can be better optimized
in implementations.Resolution: It makes sense as a type of result.
Changed.
Removed method.

Issue XPath-37:

Implementing XPathEvaluator on Document can be a problem due to
conflicts in the names of the methods.
The working group finds no better solution. GetInterface in Level 3
permits the object to be implemented separately. We should be
committed to this. We will leave this issue open to see if we get
more feedback on it.

Issue XPath-38:

How does this interface adapt to XPath 2.0 and other query
languages.Resolution: No change.
This interface is not intended to adapt to XPath 2.0 or other
languages. The models of these are likely to be incompatible enough
to require new APIs.
For alternate implementations that can use this API, it can be
obtained from different sources.

Issue XPath-39:

Support for custom variables and functions would be very
useful.Resolution: No change.
It is possible for an implementation to supply alternative sources
of an XPathEvaluator that can be customized with a custom variable
and function context. We do not specify how this is accomplished.
It is too complex to address in this version of the XPath DOM.

Creates a parsed XPath expression with resolved
namespaces. This is useful when an expression will be reused in an
application since it makes it possible to compile the expression
string into a more efficient internal form and preresolve all namespace
prefixes which occur within the expression.

Issue XPath-5:

createExpression should not raise exceptions about type
coercion.Resolution: This was already fixed in the public draft.

The resolver permits translation of prefixes
within the XPath expression into appropriate namespace URIs. If
this is specified as null, any namespace prefix
within the expression will result in DOMException
being thrown with the code NAMESPACE_ERR.

Adapts any DOM node to resolve namespaces so
that an XPath expression can be easily evaluated relative to the
context of the node where it appeared within the document. This
adapter works by calling the method
lookupNamespacePrefix on Node.

Issue XPath-6:

It should be possible to create an XPathNSResolver that does
not rely on a node, but which implements a map of resolutions that
can be added to by the application.Resolution: No change.
The application can easily create this, which was why the interface
was designed as it is. The specification will not require a
specific factory at this time for application populated maps.

Issue XPath-14:

There should be type restrictions on which types of nodes may
be adapted by createNSResolver.Resolution: No change.
The namespace methods on the Node interface of the Level 3 core may
be called without exception on all node types. In some cases no
non-null namespace resolution will ever be returned. That is what
may also be expected of this adapter.

Evaluates an XPath expression string and
returns a result of the specified type if possible.

Issue XPath-17-18:

An exception needs to be raised when an XPath expression is
evaluated on a node such as an EntityReference which cannot serve
as an XPath context node.Resolution: Done: NOT_SUPPORTED_ERR.

Issue XPath-19:

A description is needed of what happens when the node passed to
the evaluation function is a Text or CDATASection in the DOM case
where the text may be fragmented between text nodes.Resolution: Done.

Issue XPath-20:

Eliminate the evaluate method from XPathEvaluator, forcing
everyone to create expressions.Resolution: No change.
Any implementor can easily implement it by creating an expression.
Having it available as a separate routine is a convenience and may
be an optimization as well in some cases.

Issue XPath-21:

Revert to multiple evaluateAs methods instead of passing a type
code.Resolution: No change.
This is an alternative which eliminates a method argument while
adding methods, but the type code is used to designate the type on
returns anyway and using it as an argument to specify any coercion
seems natural to many.

Issue XPath-13:

Error exceptions are needed when there is a mismatch between
the implementation of XPathEvaluator and the context node being
evaluated.Resolution: Done: WRONG_DOCUMENT_ERR

Issue XPath-29:

Concern that the XPath API should only support natural results
of XPath expression, without convenience coercion or alternative
representations. Any special thing such as ordering should be added
later to resultResolution: No change.
We have significant use cases for returning alternative types and
representations by explicit request in advance.

Issue XPath-30:

Eliminate the reusable result argument.Resolution: No change.
No. We have use cases for it, and there is already an
implementation showing there is nothing wrong with it.

Issue XPath-31:

State that the XPathNSResolver argument may be a function in
Javascript.Resolution: Yes.

Issue XPath-32:

There is an exception when there is a problem parsing the
expression, but none when there is a problem evaluating the
expression.Resolution: No change.
If the expression parsing was OK, then the worst that can happen is
an empty result is returned.

Issue XPath-33:

When requesting any type, the implementation should be
permitted to return any type of node set, i.e. ordered or
unordered, it finds convenient.Resolution: No change.
The iterator it returns may contain ordered results, but
identifying it as such produces undesirable results, because it
would create complexity for the user -- requiring checking two
types to see if the result was a node set -- or incompatibility
caused by assuming it was always the one returned by a particular
implementation the developer was using.

Issue XPath-35:

NAMESPACE_ERR description is not appropriate to the way it is
being used here.Resolution: Make the description of NAMESPACE_ERR in the
core specification more general.

Issue XPath-36:

Should the INVALID_EXPRESSION_ERR be INVALID_SYNTAX_ERR?Resolution: No change.
We can improve the description of the error, but the name is
appropriate as-is. It covers not only syntax errors but expression
errors, such as when the implementation has no custom functions or
variables but the expression specifies custom functions or
variables.

Parameters

expression of type
DOMString

The XPath expression string to be parsed and evaluated.

contextNode of type
Node

The context is context node for the evaluation of
this XPath expression. If the XPathEvaluator was obtained by
casting the Document then this must be owned by the
same document and must be a Document,
Element, Attribute, Text,
CDATASection, Comment,
ProcessingInstruction, or XPathNamespace node.
If the context node is a Text or a
CDATASection, then the context is interpreted as the
whole logical text node as seen by XPath, unless the node is empty
in which case it may not serve as the XPath context.

The resolver permits translation of prefixes
within the XPath expression into appropriate namespace URIs. If
this is specified as null, any namespace prefix
within the expression will result in DOMException
being thrown with the code NAMESPACE_ERR.

type of type unsigned
short

If a specific type is specified, then the result
will be coerced to return the specified type relying on
XPath type conversions and fail if the desired coercion is
not possible. This must be one of the type codes of XPathResult.

The result specifies a specific XPathResult which
may be reused and returned by this method. If this is specified as
nullor the implementation cannot reuse the specified
result, a new XPathResult will be
constructed and returned.

The context is context node for the evaluation of
this XPath expression.
If the XPathEvaluator was obtained by casting the
Document then this must be owned by the same document
and must be a Document, Element,
Attribute, Text,
CDATASection, Comment,
ProcessingInstruction, or XPathNamespace
node.
If the context node is a Text or a
CDATASection, then the context is interpreted as the
whole logical text node as seen by XPath, unless the node is empty
in which case it may not serve as the XPath context.

type of type unsigned
short

If a specific type is specified, then the result
will be coerced to return the specified type relying on XPath
conversions and fail if the desired coercion is not possible. This
must be one of the type codes of XPathResult.

The result specifies a specific XPathResult which
may be reused and returned by this method. If this is specified as
nullor the implementation cannot reuse the specified
result, a new XPathResult will be
constructed and returned.

The XPathNSResolver interface permit
prefix strings in the expression to be properly bound
to namespaceURI strings. XPathEvaluator can
construct an implementation of XPathNSResolver from a
node, or the interface may be implemented by any application.

Look up the namespace URI
associated to the given namespace prefix.
The XPath evaluator must never call this with a null
or empty argument, because the result of doing this is undefined.

Issue XPath-9:

Null / empty prefix passed to XPathNSResolver should return
default namespace.Resolution: Do not permit nullto be passed in
invocation, allowing the implementation, if shared, to do anything
it wants with a passed null.
It would be confusing to specify more than this since the
resolution of namespaces for XPath expressions never requires the
default namespace.

Issue XPath-10:

Null returns are problematic.Resolution: No change.
They should be adequately addressed in core. Some implementations
have not properly supported them, but they will be fixed to be
compliant. Bindings are still free to choose alternative
representations of nullwhere required.

The XPathResult interface represents the result of
the evaluation of an XPath expression within the context of a
particular node. Since evaluation of an XPath expression can result
in various result types, this object makes it possible to discover
and manipulate the type and value of the result.

Issue XPath-23:

Should there be a flag on the result to say whether an
iteration has become invalid?Resolution: Yes.
Added the boolean attribute invalidIteratorState

Issue XPath-25:

Should there be a reset method on the result in case someone
wants to iterate the result multiple times?
It may be more trouble than it is worth, because the user can
request a new query. See if there are use cases.

Issue XPath-26:

It might be better to consolidate the interfaces and just move
the snapshot and iterator functions to the result object.Resolution: Yes.
The result of the consolidation looks good and unless there are
great objections, this is how it will be.

Issue XPath-28:

There is concern that the result cannot represent multiple
strings, which is a possible result of XPath 2.0. on them?Resolution: No change.
This is not part of the XPath 1.0 data model. We cannot plan well
for the XPath 2.0 data model at this point. Most likely a new API
will be required for XPath 2.0

This code does not represent a specific type. An evaluation of
an XPath expression will never produce this type. If this type is
requested, then the evaluation returns whatever type naturally
results from evaluation of the expression.
If the natural result is a node set when ANY_TYPE was
requested, then UNORDERED_NODE_ITERATOR_TYPE is always
the resulting type. Any other representation of a node set must be
explicitly requested.

The result is a node
set as defined by [XPath 1.0] and will be accessed as a
single node, which may be nullif the node set is
empty. Document modification does not invalidate the node, but may
mean that the result node no longer corresponds to the current
document. This is a convenience that permits optimization since the
implementation can stop once any node in the in the resulting set
has been found.
If there are more than one node in the actual result, the single
node returned may not be the first in document order.

The result is a node
set as defined by [XPath 1.0] and will be accessed as a
single node, which may be null if the node set is
empty. Document modification does not invalidate the node, but may
mean that the result node no longer corresponds to the current
document. This is a convenience that permits optimization since the
implementation can stop once the first node in document order of
the resulting set has been found.
If there are more than one node in the actual result, the single
node returned will be the first in document order.

The result is a node
set as defined by [XPath 1.0] that will be accessed as a
snapshot list of nodes that will be in original document order.
Document modification does not invalidate the snapshot but may mean
that reevaluation would not yield the same snapshot and nodes in
the snapshot may have been altered, moved, or removed from the
document.

The result is a node
set as defined by [XPath 1.0] that will be accessed
iteratively, which may not produce nodes in a particular order.
Document modification invalidates the iteration.
This is the default type returned if the result is a node set and
ANY_TYPE is requested.

The result is a node
set as defined by [XPath 1.0] that will be accessed as a
snapshot list of nodes that may not be in a particular order.
Document modification does not invalidate the snapshot but may mean
that reevaluation would not yield the same snapshot and nodes in
the snapshot may have been altered, moved, or removed from the
document.

Returns the indexth item in the
snapshot collection. If index is greater than or equal
to the number of nodes in the list, this method returns
null. Unlike the iterator result, the snapshot does
not become invalid, but may not correspond to the current document
if it is mutated.

Parameters

index of type
unsigned long

Index into the snapshot collection.

Return Value

Node

The node at the indexth position in the
NodeList, or null if that is not a valid
index.

The XPathNamespace interface is returned by XPathResult
interfaces to represent the XPath namespace node type that DOM
lacks. There is no public constructor for this node type. Attempts
to place it into a hierarchy or a NamedNodeMap result in a
DOMException with the code
HIERARCHY_REQUEST_ERR. This node is read only, so methods
or setting of attributes that would mutate the node result in a
DOMException with the code
NO_MODIFICATION_ALLOWED_ERR.

The core specification describes attributes of the
Node interface that are different for different node
node types but does not describe XPATH_NAMESPACE_NODE,
so here is a description of those attributes for this node type.
All attributes of Node not described in this section
have a null or false value.

ownerDocument matches the
ownerDocument of the ownerElement even if
the element is later adopted.

prefix is the prefix of the namespace represented
by the node.

nodeName is the same as prefix.

nodeType is equal to
XPATH_NAMESPACE_NODE.

namespaceURI is the namespace URI of the namespace
represented by the node.

adoptNode, cloneNode, and
importNode fail on this node type by raising a
DOMException with the code
NOT_SUPPORTED_ERR.

Issue XPath-12:

importNode should also fail on XPathNamespace nodes.Resolution: This was already fixed in the public draft.

Issue XPath-3:

The Namespace node should be added to DOM Level 3 core and
should be available via a read-only NamedNodeMap on element to
reduce the confusion of adding a special node type for XPath.Resolution: No change.
There are no known problems with this add-on node type and uses
beyond XPath are not anticipated.

Issue XPath-11:

Node.namespaceValue should be identical to
Node.namespaceURI and not null.Resolution: No change.
It is not clear why it should be this way since the infoset does
not dictate it.

The Element on which the namespace was in scope
when it was requested. This does not change on a returned namespace
node even if the document changes such that the namespace goes out
of scope on that element and this node is no
longer found there by XPath.