Document Object Model (DOM) Requirements
W3C Working Draft 12 April, 2000
- This version:
- Latest version:
- Previous version:
- Lauren Wood,
SoftQuad Software Inc., chair
- Philippe Le Hégaret,
W3C, staff contact
- Ben Chang,
- James Davidson,
- Andy Heninger,
- Joe Kesselman,
- Arnaud Le Hors,
- Tom Pixley,
Netscape Communications Corporation
- Jared Sorensen,
Novell, Inc. (until January 1999)
- Ray Whitmer,
© 2000 W3C®
INRIA, Keio), All Rights Reserved. W3C
document use and
software licensing rules
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 email@example.com. An archive is available at
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.
References to XML and HTML documents generally denote the physical
files that contain structural markup.
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.
The Object Model is language neutral and platform independent.
There will be a core DOM that is applicable to HTML, CSS and XML
The Object Model can be used to construct and deconstruct the
The Object Model will not preclude use by either agents external
to the document content, or scripts embedded within the document.
Consistent naming conventions must be used through all levels of
the Object Model.
A visual UI component will not be required for a conforming
implementation of the Object Model.
The specific HTML, CSS or XML document object models will be driven
by the underlying constructs of those languages.
It must be possible to read in a document and write out a
structurally isomorphic document.
The Object Model will not expose the user to problems with
security, validity, or privacy.
The Object Model will not preclude other mechanisms for
Error reporting will be primarily via return values. Exceptions
will be raised on unrecoverable conditions.
The DOM will provide a document-wide reporting mechanism.
[After Level 1]
The DOM error state can be queried. [After Level 1]
DOM Level 1 Requirements
This refers to the navigation around a document, such as finding the
parent of a given element, or what children elements a given parent
All document content, including elements and attributes, will
be programmatically accessible and manipulable.
Navigation from any element to any other element will be
There will be a way to uniquely and reproducibly enumerate the
structure of static documents.
There will be a way to query for elements and
attributes. [After Level 1]
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.
These are specific to HTML document.
All elements that are defined in the HTML 4.0 specification are
exposed. User agents may expose other elements using similar
Unknown tags and attributes are exposed.
Implied elements are exposed even if not explicitly defined in
the document (e.g., HTML, HEAD, BODY).
There will be a way to add, remove and change elements and/or
tags in the document structure.
There will be a way to add, remove and change attributes in the
Operations (or a combination of operations) must restore
consistency before they return.
A valid static document acted upon by the DOM will deliver a
consistent reproducible document structure.
There will be a way to determine the containing element from any
text part of the document.
There will be a way to manipulate (add, change, delete) content.
There will be a way to navigate content.
DOM Level 2 Requirements
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.
All elements will be capable of generating events.
There will be user interface events, mutation events, and logical
The event delivery mechanism will allow for overriding of default
The event model will provide a mechanism by which events for
specific elements may be received by an ancestor in the DOM
Events may be synchronous.
Events will be defined in a platform independent and language
There will be an interface for binding to events.
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.
All style sheets will be represented in the object model.
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.
Selectors, rules and properties of individual style sheets can be
added, removed and changed.
All elements of a CSS style can be added, removed, and changed in
the object model. This includes but is not limited to:
linked style sheets
imported style sheets
alternative style sheets
CSS pseudo-classes and CSS pseudo-elements
all properties as defined in the CSS specification, including
but not limited to font properties, colors, backgrounds, and
- Linear view
- allows querying and editing functionality based on a range of text
rather than a subtree of Nodes.
- 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
The DOM Range API should support the following types of operations on
- Creating a Range object
- Extracting text from a Range (with or without markup)
- Inserting, Deleting text inside the Range
- Inserting, Deleting document structure inside the Range
The DOM Traversal API should be able to see a filtered view without
comments or entity references, and to have an iterator robust under
DOM Level 3 Requirements
Here are the items that will be addressed:
- moving (not copying!) a node from one document to
another. DOM Level 2 provides an importNode method that copies a
node from one document to another, it would be useful to have
a way of simply moving a node, even though in some cases, such as
across implementations, it may fail.
- node ordering. Is this node before that one in document order?
Although this can be done on top of the DOM Level 2, having it as
part of the DOM would provide for possible
- whitespace in element content (aka "ignorable
whitespace"). Does this Text node only contain whitespace in
- exposing the XML and Text declarations.
- exposing the base URI of a node (part of the XML
- bootstrapping a DOM in Java. How does one get a hand on a
Here are other items that will be considered:
- a way to turn off error checking, so that better performance
can be achieved, such as when the DOM is built from a parser which
already performs error checking.
- a way to attach some user data to a node
- node identity. Is this object the same node as that
- node equality and hashcode
- namespace fixup/lookup. DOM Level 2 is based on an early
binding model and the implementation neither fixes the namespace
declarations as nodes are moved around or inserted nor it provides
any lookup mechanism.
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.
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
EventListeners registered using DOM Level 2 Event model
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.
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.
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.
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:
- CU1. Modify an existing content model because it needs to be updated.
- CU2. Associating a content model (external and/or internal) with a document, or changing the current association.
- CU3. Using the same external content model with several documents, without having to reload it.
- CR1. Retrieve information from content model.
- CR2. Load an existing content model, perhaps independently from a document.
- 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:
- CMU1. Create a new content model.
- CMU2. Clone/map all or parts of an existing content model to a new or existing content model.
- 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.
- CMU4. Partial content model checking. For example, only certain portions of the content model need be validated.
- CMR1. Create a new content model object.
- CMR2. View and modify all parts of the content model.
- CMR3. Validate the content model itself. For example, if an element/attribute is inserted incorrectly into the content model.
- CMR4. Serialize the content model.
- CMR5. Clone all or parts of an existing content model.
- CMR6. Validate portions of the XML document against the content model.
Specific to the document-editing world, the following are use cases and requirements:
- DU1. For editing documents with an associated content model, provide the assistance necessary so that valid documents can be modified and remain valid.
- DU2. For editing documents with an associated content model, provide the assistance necessary to transform an invalid document into a valid one.
- DR1. Being able to determine if the document is not well-formed, and if not, be given enough assistance to locate the error.
- DR2. Being able to determine if the document is not namespace well-formed, and if not, be given enough assistance to locate the error.
- 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.
- DR4. Being able to determine if specific modifications to a document would make it become invalid.
- DR5. Retrieve information from the content model. For example, getting a list of all the defined element names for document editing purposes.
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
Requirements that apply to both loading and saving documents.
Documents must be able to be parsed from and saved to the following
- Input and Output Streams
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.
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
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.
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
Loading a document can cause the generation of errors including:
- I/O Errors, such as the inability to find or open the specified
XML well formedness 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
The following requirements apply to loading documents.
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
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.
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.
Content Model Saving
Requirement from the Content Model group.
Other Items Under Consideration
The following items are not committed to, but are under consideration.
Public feedback on these items is especially requested.
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.
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.
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.
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.
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
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
(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.
(ED: More use cases required.)
Selection and Focus
Window.screen Functionality Implemented in Current
- Get information on the dimensions or color depth of the
- Select different graphics depending upon the screen
- Use the browser window as an application window for a web
- Position controls relative to the environment / screen
characteristics of the rendering device .
- Split view in a browser or editor which might have different
- Synchronization of view-specific state (e.g. selection and
focus) between multiple similar or dissimilar views on the same document in an
- 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.