Document Object Model (DOM) Requirements

W3C Working Group Note 3 November 2020

This version:
https://www.w3.org/TR/2020/NOTE-DOM-Requirements-20201103/
Latest version:
https://www.w3.org/TR/DOM-Requirements/
Previous version:
https://www.w3.org/TR/2004/NOTE-DOM-Requirements-20040226/
Editors:
Ben Chang, Oracle
Philippe Le Hégaret, W3C
Arnaud Le Hors, IBM
Ray Whitmer, Invited Expert, chair
Mike Champion, Software AG (until 2003)
Tom Pixley, Netscape Communications Corporation (until July 2002)
Joe Kesselman, IBM (until 2001)
Andy Heninger, IBM (until 2001)
Angel Diaz, IBM (until 2001)
James Davidson, Sun (until June 2000)
Lauren Wood, SoftQuad Software Inc. (until November 2000)
Jared Sorensen, Novell, Inc. (until January 1999)

Abstract

This document contains the requirements for the Document Object Model, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents. The Document Object Model provides a standard set of objects for representing HTML and XML documents, a standard model of how these objects can be combined, and a standard interface for accessing and manipulating them. Vendors can support the DOM as an interface to their proprietary data structures and APIs, and content authors can write to the standard DOM interfaces rather than product-specific APIs, thus increasing interoperability on the Web.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

🚩
This document is retired and MUST NOT be used for further technical work.
See the DOM Living Standard instead and raise issues in the whatwg/dom repository.

🚩 Retired document. Do not use.

Publication as a Working Group Note does not imply endorsement by the W3C Membership. This is a retired document and is no longer updated. It is inappropriate to cite this document as other than retired work.

This document was originally produced by a group operating under the W3C Patent Policy.

This document is governed by the 15 September 2020 W3C Process Document.

Table of Contents

1. General requirements

1.1 Basic requirements

  1. References to XML and HTML documents generally denote the physical files that contain structural markup.
  2. Where possible, the Level of the DOM in which the requirements are met is noted.

Listed below are the general requirements of the Document Object Model.

  1. The Object Model is language neutral and platform independent.
  2. There will be a core DOM that is applicable to HTML, CSS and XML documents.
  3. The Object Model can be used to construct and deconstruct the document.
  4. The Object Model will not preclude use by either agents external to the document content, or scripts embedded within the document.
  5. Consistent naming conventions must be used through all levels of the Object Model.
  6. A visual UI component will not be required for a conforming implementation of the Object Model.
  7. The specific HTML, CSS or XML document object models will be driven by the underlying constructs of those languages.
  8. It must be possible to read in a document and write out a structurally isomorphic document.
  9. The Object Model will not expose the user to problems with security, validity, or privacy.
  10. The Object Model will not preclude other mechanisms for manipulating documents.

1.2 Error Reporting

  1. Error reporting will be primarily via return values. Exceptions will be raised on unrecoverable conditions.
  2. The DOM will provide a document-wide reporting mechanism. [After Level 1]
  3. The DOM error state can be queried. [After Level 1]

2. DOM Level 1 Requirements

2.1 Structure Navigation

This refers to the navigation around a document, such as finding the parent of a given element, or what children elements a given parent element contains.

2.1.1 General Requirements

  1. All document content, including elements and attributes, will be programmatically accessible and manipulable.
  2. Navigation from any element to any other element will be possible.
  3. There will be a way to uniquely and reproducibly enumerate the structure of static documents.
  4. There will be a way to query for elements and attributes. [After Level 1]
  5. Basic low-level functions (get first, get next, etc.) will be provided, along with convenience functions that build upon them, but have a consistent access method.

2.1.2 HTML Requirements

These are specific to HTML document.

  1. All elements that are defined in the HTML 4.0 specification are exposed. User agents may expose other elements using similar interfaces.
  2. Unknown tags and attributes are exposed.
  3. Implied elements are exposed even if not explicitly defined in the document (e.g., HTML, HEAD, BODY).

2.2 Document Manipulation

  1. There will be a way to add, remove and change elements and/or tags in the document structure.
  2. There will be a way to add, remove and change attributes in the document structure.
  3. Operations (or a combination of operations) must restore consistency before they return.
  4. A valid static document acted upon by the DOM will deliver a consistent reproducible document structure.

2.3 Content Manipulation

  1. There will be a way to determine the containing element from any text part of the document.
  2. There will be a way to manipulate (add, change, delete) content.
  3. There will be a way to navigate content.

3. DOM Level 2 Requirements

3.1 Event Model

The event model must be rich enough to create completely interactive documents. This requires the ability to respond to any user action that may occur on the document. Therefore, many of these requirements only apply if a UI component is involved.

  1. All elements will be capable of generating events.
  2. There will be user interface events, mutation events, and logical events.
  3. The event delivery mechanism will allow for overriding of default behavior.
  4. The event model will provide a mechanism by which events for specific elements may be received by an ancestor in the DOM hierarchy.
  5. Events may be synchronous.
  6. Events will be defined in a platform independent and language neutral way.
  7. There will be an interface for binding to events.

3.2 Stylesheet Object Model

Cascading Style Sheets (CSS) is one model for manipulating the style of the document. The Stylesheet Object Model exposes the ability to create, modify, and associate CSS style sheets with the document. The stylesheet model will be extensible to other stylesheet formats in the future.

  1. All style sheets will be represented in the object model.
  2. There will be a CSS stylesheet model. The CSS object model will be defined as part of a stylesheet embedding model, where the core part of the model may be applicable to other style languages.
  3. Selectors, rules and properties of individual style sheets can be added, removed and changed.
  4. All elements of a CSS style can be added, removed, and changed in the object model. This includes but is not limited to:
    1. linked style sheets
    2. imported style sheets
    3. alternative style sheets
    4. CSS pseudo-classes and CSS pseudo-elements
    5. contextual selectors
    6. inline styles
    7. all properties as defined in the CSS specification, including but not limited to font properties, colors, backgrounds, and box properties.

3.3 Range model

Linear view
allows querying and editing functionality based on a range of text rather than a subtree of Nodes.
Live
edits on the range modify the underlying tree
Low Level
no parser, no relationship to user agent, no convenience methods or range comparison methods (these would be part of the SmartRange interface)

The DOM Range API should support the following types of operations on ranges:

3.4 Traversal model

The DOM Traversal API should be able to see a filtered view without comments or entity references, and to have an iterator robust under mutation.

4. DOM Level 3 Requirements

4.1 Core Requirements

Here are the items that will be addressed:

Here are other items that will be considered:

4.2 Level 3 Events Requirements

The DOM Level 3 Events specification will attempt to address some of the remaining issues from the DOM Level 2 Event specification as well as a couple or requested enhancements to the model. It will not attempt to redesign the model nor will attempt to define any additional event models.

4.2.1 EventListener grouping

The specification must define a technique for registering EventListeners in groups. These groups will then have specified behavior in which attempts to modify the flow of an event will be restricted and affected only the group to which the EventListener in question belongs.

It is also required that whatever technique is specified to accomplish this purpose be compatible with the existing DOM Level 2 Event model and any EventListeners registered using DOM Level 2 Event model methods.

4.2.2 Key event set

The specification must define a set of key events to handle keyboard input. This key event set must be fully internationalizable. It is hoped that this key event set will be compatible with existing key event sets used in current systems however this is not a requirement.

4.2.3 Input event set

The specification should attempt to define a set of input events to handle IME based keyboard input. It is expected that this requirement will depend heavily on any key event set defined by the specification.

4.2.4 Device independent event set

The specification must define a device independent event set. This event set should allow notification of typical user interaction with a document without requiring the use of either mouse events or key events.

(ED: The following requirements come from the DOM 3 Requirements and View Use Cases (member-only link) from the WAI-PF Working Group. )

Each Document View must provide a Device Independent UI Event Model.

The following events are not present in the DOM Level 2 specification. Those related to selection should be picked up when a selection model is included:

gainselection
The gainselection event occurs when a node or part of it is selected (unlike the HTML event select, it can be applied to any element, not just HTML FORM controls). For each selected node a gainselection event, which can be handled locally or through bubbling by a root node selection handler, is generated.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: range
loseselection
The loseselection event occurs when a node or part of it is deselected, for example because the user selects something else.
  • Bubbles: Yes
  • Cancelable: No
  • Context Info: range
key
Key input may not be keyboard specific.
pointermove
Input may be a stylus rather than a mouse

4.3 Content Models and Validation Use Cases and Requirements

The content model referenced in these use cases/requirements is an abstraction and does not refer to DTDs or XML Schemas or any transformations between the two.

For the CM-editing and document-editing worlds, the following use cases and requirements are common to both and could be labeled as the "Validation and Other Common Functionality" section:

Use Cases:

  1. CU1. Modify an existing content model.
  2. CU2. Associating a content model (external and/or internal) with a document, or changing the current association.
  3. CU3. Using the same external content model with several documents, without having to reload it.
  4. CU4. Create a new content model.

Requirements:

  1. CR1. Validate against the content model.
  2. CR2. Retrieve information from content model.
  3. CR3. Load an existing content model, perhaps independently from a document.
  4. CR4. Being able to determine if a document has a content model associated with it.
  5. CR5. Create a new content model object.
  6. CR6. Associate a CM with a document and make it the active CM.

Specific to the CM-editing world, the following are use cases and requirements and could be labeled as the "CM-editing" section:

Use Cases:

  1. CMU1. Clone/map all or parts of an existing content model to a new or existing content model.
  2. CMU2. Save a content model in a separate file. For example, a DTD can be broken up into reusable pieces, which are then brought in via entity references, these can then be saved in a separate file.
  3. CMU3. Partial content model checking. For example, only certain portions of the content model need be validated.

Requirements:

  1. CMR1. View and modify all parts of the content model.
  2. CMR2. Validate the content model itself. For example, if an element/attribute is inserted incorrectly into the content model.
  3. CMR3. Serialize the content model.
  4. CMR4. Clone all or parts of an existing content model.
  5. CMR5. Validate portions of the XML document against the content model.

Specific to the document-editing world, the following are use cases and requirements and could be labeled as the "Document-editing" section:

Use Cases:

  1. DU1. For editing documents with an associated content model, provide the assistance necessary so that valid documents can be modified and remain valid.
  2. DU2. For editing documents with an associated content model, provide the assistance necessary to transform an invalid document into a valid one.

Requirements:

  1. DR1. Being able to determine if the document is not well-formed, and if not, be given enough assistance to locate the error.
  2. DR2. Being able to determine if the document is not namespace well-formed, and if not, be given enough assistance to locate the error.
  3. DR3. Being able to determine if the document is not valid with respect to its associated content model, and if not, give enough assistance to locate the error.
  4. DR4. Being able to determine if specific modifications to a document would make it become invalid.
  5. DR5. Retrieve information from all content model. For example, getting a list of all the defined element names for document editing purposes.

General Issues:

  1. I1. Namespace issues associated with the content model. To address namespaces, a isNamespaceAware attribute to the generic CM object has been added to help applications determine if qualified names are important. Note that this should not be interpreted as helping identify what the underlying content model is. A MathML example to show how namespaced documents will be validated will be added later.
  2. I2. Multiple CMs being associated with a XML document. For validation, this could: 1) result in an exception; 2) a merged content model for the document to be validated against; 3) each content model for the document to be validated against separately. In this chapter, we have gone for the third choice, allowing the user to specify which content model to be active and allowing them to keep adding content models to a list associated with the document.
  3. I3. Content model being able to handle more datatypes than strings. Currently, this functionality is not available and should be dealt with in the future.
  4. I4. Round-trippability for include/ignore statements and other constructs such as parameter entities, e.g., "macro-like" constructs, will not be supported since no data representation exists to support these constructs without having to re-parse them.
  5. I5. Basic interface for a common error handler both CM and Load/Save. Agreement has been to utilize user-registered callbacks but other details to be worked out.

4.4 Load and Save Requirements

DOM Level 3 will provide an API for loading XML source documents into a DOM representation and for saving a DOM representation as a XML document.

Some environments, such as the Java platform or COM, have their own ways to persist objects to streams and to restore them. There is no direct relationship between these mechanisms and the DOM load/save mechanism. This specification defines how to serialize documents only to and from XML format.

4.4.1 General Requirements

Requirements that apply to both loading and saving documents.

4.4.1.1 Document Sources

Documents must be able to be parsed from and saved to the following sources:

  • Input and Output Streams
  • URIs
  • Files

Note that Input and Output streams take care of the in memory case. One point of caution is that a stream doesn't allow a base URI to be defined against which all relative URIs in the document are resolved.

4.4.1.2 Content Model Loading

While creating a new document using the DOM API, a mechanism must be provided to specify that the new document uses a pre-existing Content Model and to cause that Content Model to be loaded.

Note that while DOM Level 2 creation can specify a Content Model when creating a document (public and system IDs for the external subset, and a string for the subset), DOM Level 2 implementations do not process the Content Model's content. For DOM Level 3, the Content Model's content must be read.

4.4.1.3 Content Model Reuse

When processing a series of documents, all of which use the same Content Model, implementations should be able to reuse the already parsed and loaded Content Model rather than reparsing it again for each new document.

This feature may not have an explicit DOM API associated with it, but it does require that nothing in this section, or the Content Model section, of this specification block it or make it difficult to implement.

4.4.1.4 Entity Resolution

Some means is required to allow applications to map public and system IDs to the correct document. This facility should provide sufficient capability to allow the implementation of catalogs, but providing catalogs themselves is not a requirement. In addition XML Base needs to be addressed.

4.4.1.5 Error Reporting

Loading a document can cause the generation of errors including:

  • I/O Errors, such as the inability to find or open the specified document.
    XML well formedness errors.
    Validity errors

Saving a document can cause the generation of errors including:

  • I/O Errors, such as the inability to write to a specified stream, URL, or file.
    Improper constructs, such as '--' in comments, in the DOM that cannot be represented as well formed XML.

This section, as well as the DOM Level 3 Content Model section should use a common error reporting mechanism. Well-formedness and validity checking are in the domain of the Content Model section, even though they may be commonly generated in response to an application asking that a document be loaded.

4.4.2 Load Requirements

The following requirements apply to loading documents.

4.4.2.1 Parser Properties and Options

Parsers may have properties or options that can be set by applications. Examples include:

  • Expansion of entity references.
  • Creation of entity ref nodes.
  • Handling of white space in element content.
  • Enabling of namespace handling.
  • Enabling of content model validation.

A mechanism to set properties, query the state of properties, and to query the set of properties supported by a particular DOM implementation is required.

4.4.3 XML Writer Requirements

The fundamental requirement is to write a DOM document as XML source. All information to be serialized should be available via the normal DOM API.

4.4.3.1 XML Writer Properties and Options

There are several options that can be defined when saving an XML document. Some of these are:

  • Saving to Canonical XML format.
  • Pretty Printing.
  • Specify the encoding in which a document is written.
  • How and when to use character entities.
  • Namespace prefix handling.
  • Saving of Content Models.
  • Handling of external entities.

4.4.3.2 Content Model Saving

Requirement from the Content Model group.

4.4.4 Other Items Under Consideration

The following items are not committed to, but are under consideration. Public feedback on these items is especially requested.

4.4.4.1 Incremental and/or Concurrent Parsing

Provide the ability for a thread that requested the loading of a document to continue execution without blocking while the document is being loaded. This would require some sort of notification or completion event when the loading process was done.

Provide the ability to examine the partial DOM representation before it has been fully loaded.

In one form, a document may be loaded asynchronously while a DOM based application is accessing the document. In another form, the application may explicitly ask for the next incremental portion of a document to be loaded.

4.4.4.2 Filtered Save

Provide the capability to write out only a part of a document. May be able to leverage TreeWalkers, or the Filters associated with TreeWalkers, or Ranges as a means of specifying the portion of the document to be written.

4.4.4.3 Document Fragments

Document fragments, as specified by the XML Fragment specification, should be able to be loaded. This is useful to applications that only need to process some part of a large document. Because the DOM is typically implemented as an in-memory representation of a document, fully loading large documents can require large amounts of memory.

XPath should also be considered as a way to identify XML Document fragments to load.

4.4.4.4 Document Fragments in Context of Existing DOM

Document fragments, as specified by the XML Fragment specification, should be able to be loaded into the context of an existing document at a point specified by a node position, or perhaps a range. This is a separate feature than simply loading document fragments as a new Node.

4.5 Embedded DOM Requirements

4.5.1 Abstract

This document discusses the requirements and framework for using multiple implementations of DOM or DOM-based APIs designed for a particular markup language within a single standard DOM application. Up until now, the Document Object Model design has been concerned with defining an API to an entire XML document, where all methods and attributes in the API apply equally to the entire document and it is assumed that only one implementation of the DOM is needed by an application.

With the advent of markup languages such as Scalable Vector Graphics and the Mathematical Markup Language, it has become obvious that this simple model no longer applies. It is quite possible to have documents which embed some MathML or SVG markup, where a DOM application might reasonably expect to be able to use the specialized MathML or SVG DOM-based APIs. Similarly, many DOM applications are being designed to "glue" together two systems that both implement the DOM, and need some standard mechanism to assist in making the multiple implementations interoperate.

A module of Level 3 DOM, which we shall refer to by the shorthand name "EDOM", will address this issue.

4.5.2 Introduction

As new XML vocabularies are developed, those defining the vocabularies are beginning to define specialized APIs for manipulating XML instances of those vocabularies by extending the DOM to provide interfaces and methods that perform operations frequently needed their users. For example, the MathML and SVG groups are developing DOM extensions to allow users to manipulate instances of these vocabularies using semantics appropriate to images and mathematics (respectively) as well as the generic DOM "tree" semantics. Instances of SVG or MathML are often embedded in XML documents conforming to a different schema such as XHTML or DocBook. While the XML Namespaces Recommendation provides a mechanism for integrating these documents at the syntax level, it has become clear that the DOM Level 2 Recommendation is not rich enough to cover all the issues that have been encountered in having these different DOM implementations be used together in a single application. The Embedded DOM module deals with the requirements brought about by embedding fragments written according to a specific markup language (the embedded component) in a document where the rest of the markup is not written according to that specific markup language (the host document). It does not deal with fragments embedded by reference or linking.

We are seeing at least two implementation scenarios in which DOM components can be embedded in a host DOM. One extreme might be called the "monolithic" scenario in which a single product (e.g. the Mozilla browser) implements both the generic host DOM and the specialized embedded DOM. The embedded DOM still has a different DOMImplementation object than the host because it will support a different feature set, although it is quite likely that the embedded and host DOMs will use compatible classes or data structures. At the other extreme, the embedded DOM reflects a completely different implementation, perhaps from an entirely different vendor, e.g. an Adobe SVG component plugged into the SoftQuad editor.

The general objective of the EDOM ET is to define whatever mechanisms are required in order to make documents that are actually handled by two or more DOM implementations work together as seamlessly and compatibly as possible under various implementation scenarios. Ideally, a DOM application writer should see the entire document as a coherent unit, with certain Nodes that are actually handled by embedded DOMs simply having more specialized capabilities. It is not clear at this point whether this is achievable for all scenarios, but our goal is to make it seamless for applications that do not care about the differences, and to make it possible for applications that do care about the differences to discover which DOM handles embedded nodes, be informed of where the boundaries are, and to use that implementation to its fullest extent.

Achieving these objective may entail clarifications to the wording of the DOM specification, new interfaces or methods on existing interfaces, revised requirements for the Load/Save module so that the multiple DOMs are built and linked together at parse time, or some combination of these.

4.5.3 Use Cases

We will consider the following use cases when assessing proposed requirements and in designing the DOM extensions to support embedded DOMs. All assume that some DOM Level 3 methods have been called to link the various DOM implementations together so that DOM boundaries can be detected and handled.

4.5.3.1 Navigation from host to embedded DOM

A DOM application running on the host DOM implementation may need to access information controlled by the embedded DOM, e.g. to serialize the entire document.

4.5.3.2 Navigation from embedded DOM to host

A DOM application running on the embedded DOM implementation may need to access information controlled by the host DOM, e.g. to query a style attribute, namespace declaration, etc.

4.5.3.3 Event capture and bubbling across Host DOM/Embedded DOM boundary

A DOM application may need to detect and process events irrespective of whether they occur in a host or embedded DOM.

4.5.3.4 Seamless view of host, embedded DOMs

It may be acceptable for DOM Level 3 applications to use additional APIs to detect host/embedded DOM boundaries and to navigate across them. Nevertheless, it would be far better for users if ordinary node navigation operations, validation, iterators/treewalkers, and event propagation worked seamlessly across DOM boundaries.

4.5.3.5 Notification of document changes across Host/Embedded boundary

A DOM application may need to be aware of changes to the document tree irrespective of whether they were initiated in a host or embedded DOM.

4.5.4 Implementation Scenarios

We have prepared the following grid to clarify the different scenarios under which a standard for defining how an embedded DOM interoperates with a host DOM could be implemented, and what this means for the application programmer using the DOM interfaces.

One axis of the grid reflects the different architectures in which one DOM can be imbedded in another. The alternatives we are considering include:

  • Monolithic - The host DOM and the embedded DOM are implemented by the same code. The host/embedded distinction exists mainly to reflect the different features of nodes at different levels. Examples of this would appear to include Mozilla's support for MathML and SVG, IE5's support for VML, and Amaya's support for MathML.
  • Dynamic Subclass - Some proprietary mechanism such as Microsoft "binary behaviors" or Netscape's XBL is used to construct embedded DOM subtrees trees that appear to be subclasses (for DOM purposes) of the host DOM nodes. In a Java environment, a user could dynamically subclass another implementation.
  • Wrapper - The host and embedded DOMs are completely separate implementations that are woven together to provide support for a different subtrees of a single document. Since there is no subclassing mechanism to redirect implementation-level methods to the proper code, we envision "wrapper" classes that could implement the EDOM functionality by redirecting operations on "foreign" nodes to the standard DOM interfaces rather than the implementation classes.
  • Data Island - Two DOM implementations that are really separate documents, conceptually different and having no hierarchical relationship that can be inferred. An example would be a Microsoft XML data island inside an HTML document. This is essentially a non-use case, presented simply to identify it and contrast it with scenarios that we do envision supporting.

The other axis reflects the properties or features of the DOM API that could be preserved across the host / embedded border. The features under consideration include:

  • Awareness - Can the user query the host DOM about the identity and location of embedded DOMs? This implies that there is some way to get an opaque handle that the DOM doesn't know what to do with, but the application programmer may, at the boundary between a host DOM and embedded DOM.
  • Boundary-aware navigation - Is it possible -- perhaps by calling a new API method -- for an application programmer to navigate from a host DOM node into an embedded DOM node, and from an embedded DOM node into the host DOM that embeds it? In other words, there is a "semi-permeable barrier" between the host and embedded DOMs and an API with which to cross it.
  • Seamlessness- Can an application programmer navigate across the host/embedded boundary without being aware it exists? Do properties such as IDs, unique identifiers, timings, etc. appear to work seamlessly across embedded DOM boundaries?
  • Event propagation - Do DOM events bubble and be captured across embedded DOM boundaries?
  • CSS Inheritance- Do CSS properties on the host DOM pass down to the embedded DOM?

The Embedded DOM plans to support the following use cases derived from this grid:

Monolithic Dynamic Wrappers Data Island
Awareness Yes Yes Yes Maybe
Boundary Navigation Yes Yes Yes Maybe
Seamlessness Yes Yes Maybe No
Event Propagation Yes Yes Maybe No
CSS Inheritance Maybe Maybe Maybe No

4.5.5 Requirements

  1. The EDOM MUST specify an object model that describes the relationship between host DOM nodes and embedded DOM nodes, as well as an API or other mechanism with which those relationships can be specified. This object model MUST co-exist gracefully with the DOM Level 3 Content Model interfaces and work with validation operations.
    The EDOM MAY specify a mechanism -- such as options in the Load/Save interfaces -- so that the association between Elements and embedded DOMs is automatically produced when a document is loaded.
    The EDOM NEED NOT specify the actual mechanism by which the application actually loads a plug-in.
  2. The EDOM MUST clarify the relationship between the ownerDocument property of Nodes in an embedded DOM, the top-level node in an Embedded DOM, and the Document interface. The standard DOM object model and API may need to accommodate or even preclude the situation in which elements inside some embedded markup may have a different "owner document" and "dom implementation" values than those at another level of the hierarchy. So far the DOM WG has recommended that there only ever be one ownerDocument, which is the same for all nodes.
  3. For the "monolithic" and "dynamic subclassing" implementation scenarios, the EDOM MUST specify a mechanism so that an embedded DOM and a host DOM become aware of each other and support all of the use cases described above.
  4. For the "wrapper" implementation scenario, the EDOM MUST specify a mechanism so that an embedded DOM and a host DOM become aware of each other and that the boundary between them can be crossed by an application. It would be desirable for this boundary crossing to be "seamless", and for events and CSS properties to propagate automatically across the boundary.

4.5.6 Known Questions

Ranges are probably out of scope for the EDOM, anyone disagree?

Do we want to support both a procedural mechanism and a non-procedural mechanism (something like the HTML <object> tag) to specify the relationship between the host and embedded DOM?

(ED: The rest of this section is a bit of a grab bag for ideas we will have to consider when it comes time to work on the actual specification that meets these requirements. )

Do we have two DOM trees, one for the generic DOM, and one for the specialized DOM? (The sentiment at the Redwood Shores F2F was "no").

How do you know when to hand control over to embedded DOM? Does getChildNodes() and getParentNode() throw a new exception?

What sort of node should the top-level embedded node be? If it is a special node that is a "document" in some sense but a child of another in other senses, that would help. But it does need to be an element rather than a document, so that the ownerDocument is consistent throughout the complete document, including the embedded fragment.

How do you get a handle to a DOMImplementation object without a Document object ... we may need to solve the bootstrapping problem.

The embedded DOM API needs to add something like a createMyTopLevelElement from a Core DOM element, or maybe from a string. The string method, while not as elegant, is more likely to work across different languages and platforms.

What happens if a node from the embedded DOM tree is moved outside the embedded DOM tree? Is this possible?

What about recursive embedded DOMs? Including the case where XHTML is within SVG is within XHTML.

4.6 XPath DOM Draft Requirements

4.6.1 Abstract

There is a widely-perceived need to offer a vendor-neutral way to use XPath expressions to select matching nodes in a DOM document. A module of DOM, which we shall refer to by the shorthand name "XPATH", will address this issue.

4.6.2 Introduction

Levels 1 and 2 of the DOM has some functionality to allow specific nodes to be located without the user having to navigate through the DOM tree, notably getElementsByTagName and getElementById. The Working Group's intention was to add these very limited APIs as a stop-gap until an XML-aware "query" language was available. While not by any means a complete XML query language, XPath does provide a syntax for locating XML content by value and has been a W3C Recommendation since November, 1999. Various DOM implementations support APIs that allow one or more nodes to be located via an XPath expression, and there have been a number of calls from the user community to incorporate this capability into the DOM Level 3 Recommendation.

A semi-public mailing list was established in early 2000 to solicit input and advice (the archives can be viewed at http://lists.w3.org/Archives/Public/www-dom-xpath). The comments on this list tended to push for a quite complete XPath API rather than the quite limited interfaces provided by existing DOM implementations. Since this is out of scope for the DOM WG, efforts were made to find another W3C Working Group to take on this requirement. Those efforts have not been successful.

Thus, it falls to the DOM WG to define a simple but effective API for DOM that provides a basis for writing interoperable DOM applications that use XPath expressions rather than tree navigation to locate nodes matching simple search criteria.

4.6.3 Requirements

  1. The DOM XPATH module MUST provide one or more methods to allow a set of nodes matching an XPath expression to be identified.
  2. The DOM XPATH module MUST provide a mechanism so that the namespace context of the XPath expression can be specified, that is, so that any namespace prefixes in the XPath expression can be resolved.
  3. The DOM XPATH module MUST use the same data model as XPath itself. There are some subtle differences between the XPath data model and the DOM data model (e.g., the ownerDocument vs parentNode property to describe the Element containing an Attribute, the absence of CDATA marked sections in the XPath model, etc.). Since a combined XPath/XSLT/XQuery data model will be defined in the XPath 2.0 timeframe, it may not be possible to define a DOM XPATH module until the XPath 2.0 data model is reasonably stable. In any event, the XPATH DOM must be defined in close coordination with the other working groups addressing this issue.
  4. The DOM XPATH interfaces SHOULD be based as much as possible on the ideas and experiences of DOM implementers that have added XPath extensions.
  5. The DOM XPATH interfaces SHOULD NOT return a "live" object, but should return a list or iterator that will either reflect a snapshot of the DOM tree at the moment the XPath query was evaluated or will become invalidated if changes to the DOM tree could affect its contents.

4.6.4 Known Questions

  1. It is an open issue whether the DOM WG should wait for the XPath 2.0 data model to emerge, or whether some interim solution for the XPath 1.0 data model (mapped onto the DOM data model) is preferable.
  2. T he obvious place to put an XPath method is on the Node interface, but we presumably do not want to make this required for DOM compliance. (We suspect that the XPath module would be implemented primarily by vendors already implementing XSLT, and could be quite burdensome for other developers to support).
  3. Do we want to put any requirements on the type of object returned by an XPath locator? NodeLists are "live", which could cause problems for implementers. NodeIterators are perhaps more appropriate, but are not supported by existing XPath extensions to the DOM.
  4. What about other contextual factors besides namespaces? Do we want to allow variables and non-standard functions to be defined to the XPath engine?