contents

W3C

Document Object Model (DOM) Requirements

W3C Working Draft 12 April, 2000

This version:
http://www.w3.org/TR/2000/WD-DOM-Requirements-20000412
Latest version:
http://www.w3.org/TR/DOM-Requirements
Previous version:
http://www.w3.org/TR/2000/WD-DOM-Requirements-20000208
Editors:
Lauren Wood, SoftQuad Software Inc., chair
Philippe Le Hégaret, W3C, staff contact
Ben Chang, Oracle
James Davidson, Sun
Andy Heninger, IBM
Joe Kesselman, IBM
Arnaud Le Hors, IBM
Tom Pixley, Netscape Communications Corporation
Jared Sorensen, Novell, Inc. (until January 1999)
Ray Whitmer, Excite@Home

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

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. The latest status of this document series is maintained at the W3C.

This document is a Working Draft of the requirements of the Document Object Model. Comments on this document are invited and are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.

This is still a draft document and may be updated, replaced or obsoleted by other documents at any time. It is therefore inappropriate to use it as reference material or to cite it as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the DOM Working Group.

This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM WG members.

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

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.

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:

Use Cases:

  1. CU1. Modify an existing content model because it needs to be updated.
  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.

Requirements:

  1. CR1. Retrieve information from content model.
  2. CR2. Load an existing content model, perhaps independently from a document.
  3. CR3. Being able to determine if a document has a content model associated with it.

Specific to the CM-editing world, the following are use cases and requirements:

Use Cases:

  1. CMU1. Create a new content model.
  2. CMU2. Clone/map all or parts of an existing content model to a new or existing content model.
  3. CMU3. 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.
  4. CMU4. Partial content model checking. For example, only certain portions of the content model need be validated.

Requirements:

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

Specific to the document-editing world, the following are use cases and requirements:

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 the content model. For example, getting a list of all the defined element names for document editing purposes.

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 internal subset), DOM Level 2 implementations do not process the Content Model's content. For DOM Level 3, the Content Model's content must be 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. Views and Formatting Requirements

An important aspect of the DOM is the strong separation between the structure of a document and its presentations or views. The abstract structure and value of the document content is modelled by the DOM core. The physical characteristics and state of the presentation will be modelled by the views and formatting module.

While the abstract model is persistent, the presentation is active and temporary, responding to user and environment events as well as document mutation. The state of the presentation can not generally be manipulated as directly as the DOM core nodes. The API must allow querying and responding to changes in the physical characteristics of the presentation and its environment.

(ED: We need a FAQ entry elaborating on why the presentation characteristics are generally not mutable.)

The physical characteristics of the presentation are very tied to the medium and style system being used. An abstract layer must exist to allow for generalization of common properties of presentations on arbitrary media and style systems. Concrete mappings must also be available for prevalent presentation media and style systems.

The API must support multiple simultaneous dissimilar presentations of a document. The API must permit enumeration of current views. The API may permit creation new views of the document. The API must provide access to the values of characteristics of the presentation of individual nodes within the document. These are the actual values that have been derived from the style system that are used to render the document. The API may also provide the ability to listen for events fired as a result of presentational changes. Properties of the presentation of DOM nodes in a visual medium may include actual position, dimensions, visibility, colors, fonts, generated text, and so on.

The API must make it possible to find the document nodes being presented by a particular part or location within the presentation.

The API must make it possible to request user selection and focus.

4.5.1. Use Cases

(ED: More use cases required.)

4.5.1.1. Selection and Focus

4.5.1.2. Window.screen Functionality Implemented in Current Browsers

  • Get information on the dimensions or color depth of the screen.
  • Select different graphics depending upon the screen capabilities.
  • Use the browser window as an application window for a web application.
  • Position controls relative to the environment / screen characteristics of the rendering device .

4.5.1.3. Multiple Views

  • Split view in a browser or editor which might have different formatting characteristics.
  • Synchronization of view-specific state (e.g. selection and focus) between multiple similar or dissimilar views on the same document in an editing environment.

4.5.1.4. Formatting Information

  • Tool tips, annotations or other visual enhancements that need to be positioned relative to the rendering of a specific element.
  • Hit testing for an application in a visual medium where feedback is provided in response to user events.
  • Color picker application that displays actual color used for element or area.
contents