Document Object Model (DOM) Level 3 Core Specification

What is the Document Object Model?

/Editors/:
Philippe Le Hégaret, W3C
Lauren Wood, SoftQuad Software Inc. (for DOM Level 2)
Jonathan Robie, Texcel (for DOM Level 1)

Introduction

The Document Object Model (DOM) is an application programming interface
(API <#glossary-dt-API>) for valid HTML <#glossary-dt-HTML> and
well-formed XML <#glossary-dt-XML> documents. It defines the logical
structure of documents and the way a document is accessed and
manipulated. In the DOM specification, the term "document" is used in
the broad sense - increasingly, XML is being used as a way of
representing many different kinds of information that may be stored in
diverse systems, and much of this would traditionally be seen as data
rather than as documents. Nevertheless, XML presents this data as
documents, and the DOM may be used to manage this data.

With the Document Object Model, programmers can build documents,
navigate their structure, and add, modify, or delete elements and
content. Anything found in an HTML or XML document can be accessed,
changed, deleted, or added using the Document Object Model, with a few
exceptions - in particular, the DOM interfaces <#glossary-dt-interface>
for the XML internal and external subsets have not yet been specified.

As a W3C specification, one important objective for the Document Object
Model is to provide a standard programming interface that can be used in
a wide variety of environments and applications
<#glossary-dt-application>. The DOM is designed to be used with any
programming language. In order to provide a precise,
language-independent specification of the DOM interfaces, we have chosen
to define the specifications in Object Management Group (OMG) IDL [OMG
IDL <#references-OMGIDL>], as defined in the CORBA 2.3.1 specification
[CORBA <#references-CORBA>]. In addition to the OMG IDL specification,
we provide language bindings <#glossary-dt-lang-binding> for Java [Java
<#references-Java>] and ECMAScript [ECMAScript <#references-ECMAScript>]
(an industry-standard scripting language based on JavaScript [JavaScript
<#references-JavaScript>] and JScript [JScript <#references-JScript>]).
Because of language binding restrictions, a mapping has to be applied
between the OMG IDL and the programming language in used. For example,
while the DOM uses IDL attributes in the definition of interfaces, Java
does not allow interfaces to contain attributes:

// example 1: removing the first child of an element using ECMAScript
mySecondTrElement.removeChild(mySecondTrElement.firstChild);

// example 2: removing the first child of an element using Java
mySecondTrElement.removeChild(mySecondTrElement.getFirstChild());

*Note:* OMG IDL is used only as a language-independent and
implementation-neutral way to specify interfaces
<#glossary-dt-interface>. Various other IDLs could have been used ([COM
<#references-COM>], [Java IDL <#references-JavaIDL>], [MIDL
<#references-MSIDL>], ...). In general, IDLs are designed for specific
computing environments. The Document Object Model can be implemented in
any computing environment, and does not require the object binding
runtimes generally associated with such IDLs.

What the Document Object Model is

The DOM is a programming API <#glossary-dt-API> for documents. It is
based on an object structure that closely resembles the structure of the
documents it models <#glossary-dt-model>. For instance, consider this
table, taken from an XHTML document:

<table>
<tbody>
<tr>
<td>Shady Grove</td>
<td>Aeolian</td>
</tr>
<tr>
<td>Over the River, Charlie</td>
<td>Dorian</td>
</tr>
</tbody>
</table>

A graphical representation of the DOM of the example table, with
whitespaces in element content (often abusively called "ignorable
whitespace") removed, is:

graphical representation of the DOM of the example table

/Figure: graphical representation of the DOM of the example table/ [SVG
1.0 version <./images/table>]

An example of DOM manipulation using ECMAScript would be:

// access the tbody element from the table element
var myTbodyElement = myTableElement.firstChild;

// access its second tr element
// The list of children starts at 0 (and not 1).
var mySecondTrElement = myTbodyElement.childNodes[1];

// remove its first td element
mySecondTrElement.removeChild(mySecondTrElement.firstChild);

// change the text content of the remaining td element
mySecondTrElement.firstChild.firstChild.data = "Peter";

In the DOM, documents have a logical structure which is very much like a
tree; to be more precise, which is like a "forest" or "grove", which can
contain more than one tree. Each document contains zero or one doctype
nodes, one document element node, and zero or more comments or
processing instructions; the document element serves as the root of the
element tree for the document. However, the DOM does not specify that
documents must be /implemented/ as a tree or a grove, nor does it
specify how the relationships among objects be implemented. The DOM is a
logical model that may be implemented in any convenient manner. In this
specification, we use the term /structure model/ to describe the
tree-like representation of a document. We also use the term "tree" when
referring to the arrangement of those information items which can be
reached by using "tree-walking" methods; (this does not include
attributes). One important property of DOM structure models is
/structural isomorphism/: if any two Document Object Model
implementations are used to create a representation of the same
document, they will create the same structure model, in accordance with
the XML Information Set [XML Information Set <#references-InfoSet>].

*Note:* There may be some variations depending on the parser being used
to build the DOM. For instance, the DOM may not contain white spaces in
element content if the parser discards them.

The name "Document Object Model" was chosen because it is an "object
model <#glossary-dt-object-model>" in the traditional object oriented
design sense: documents are modeled using objects, and the model
encompasses not only the structure of a document, but also the behavior
of a document and the objects of which it is composed. In other words,
the nodes in the above diagram do not represent a data structure, they
represent objects, which have functions and identity. As an object
model, the DOM identifies:

* the interfaces and objects used to represent and manipulate a document
* the semantics of these interfaces and objects - including both
behavior and attributes
* the relationships and collaborations among these interfaces and
objects

The structure of SGML documents has traditionally been represented by an
abstract data model <#glossary-dt-datamodel>, not by an object model. In
an abstract data model <#glossary-dt-datamodel>, the model is centered
around the data. In object oriented programming languages, the data
itself is encapsulated in objects that hide the data, protecting it from
direct external manipulation. The functions associated with these
objects determine how the objects may be manipulated, and they are part
of the object model.

What the Document Object Model is not

This section is designed to give a more precise understanding of the DOM
by distinguishing it from other systems that may seem to be like it.

* The Document Object Model is not a binary specification. DOM
programs written in the same language binding will be source code
compatible across platforms, but the DOM does not define any form
of binary interoperability.
* The Document Object Model is not a way of persisting objects to
XML or HTML. Instead of specifying how objects may be represented
in XML, the DOM specifies how XML and HTML documents are
represented as objects, so that they may be used in object
oriented programs.
* The Document Object Model is not a set of data structures; it is
an object model <#glossary-dt-object-model> that specifies
interfaces. Although this document contains diagrams showing
parent/child relationships, these are logical relationships
defined by the programming interfaces, not representations of any
particular internal data structures.
* The Document Object Model does not define what information in a
document is relevant or how information in a document is
structured. For XML, this is specified by the XML Information Set
[XML Information Set <#references-InfoSet>]. The DOM is simply an
API <#glossary-dt-API> to this information set.
* The Document Object Model, despite its name, is not a competitor
to the Component Object Model [COM <#references-COM>]. COM, like
CORBA, is a language independent way to specify interfaces and
objects; the DOM is a set of interfaces and objects designed for
managing HTML and XML documents. The DOM may be implemented using
language-independent systems like COM or CORBA; it may also be
implemented using language-specific bindings like the Java or
ECMAScript bindings specified in this document.

Where the Document Object Model came from

The DOM originated as a specification to allow JavaScript scripts and
Java programs to be portable among Web browsers. "Dynamic HTML" was the
immediate ancestor of the Document Object Model, and it was originally
thought of largely in terms of browsers. However, when the DOM Working
Group was formed at W3C, it was also joined by vendors in other domains,
including HTML or XML editors and document repositories. Several of
these vendors had worked with SGML before XML was developed; as a
result, the DOM has been influenced by SGML Groves and the HyTime
standard. Some of these vendors had also developed their own object
models for documents in order to provide an API for SGML/XML editors or
document repositories, and these object models have also influenced the DOM.

Entities and the DOM Core

In the fundamental DOM interfaces, there are no objects representing
entities. Numeric character references, and references to the
pre-defined entities in HTML and XML, are replaced by the single
character that makes up the entity's replacement. For example, in:

<p>This is a dog &amp; a cat</p>

the "&amp;" will be replaced by the character "&", and the text in the P
element will form a single continuous sequence of characters. Since
numeric character references and pre-defined entities are not recognized
as such in CDATA sections, or in the SCRIPT and STYLE elements in HTML,
they are not replaced by the single character they appear to refer to.
If the example above were enclosed in a CDATA section, the "&amp;" would
not be replaced by "&"; neither would the <p> be recognized as a start
tag. The representation of general entities, both internal and external,
are defined within the extended (XML) interfaces of Document Object
Model Core <#core-Core>.

Note: When a DOM representation of a document is serialized as XML or
HTML text, applications will need to check each character in text data
to see if it needs to be escaped using a numeric or pre-defined entity.
Failing to do so could result in invalid HTML or XML. Also,
implementations <#glossary-dt-implementation> should be aware of the
fact that serialization into a character encoding ("charset") that does
not fully cover ISO 10646 may fail if there are characters in markup or
CDATA sections that are not present in the encoding.

DOM Architecture

The DOM specifications provide a set of APIs that forms the DOM API.
Each DOM specification defines one or more modules and each module is
associated with one feature name. For example, the DOM Core
specification (this specification) defines two modules:

* The Core module, which contains the fundamental interfaces that
must be implemented by all DOM conformant implementations, is
associated with the feature name "Core";
* The XML module, which contains the interfaces that must be
implemented by all conformant XML 1.0 [XML 1.0 <#references-XML>]
(and higher) DOM implementations, is associated with the feature
name "XML".

The following representation contains all DOM modules, represented using
their feature names, defined along the DOM specifications:

A view of the DOM Architecture

/Figure: A view of the DOM Architecture/ [SVG 1.0 version
<./images/dom-architecture>]

A DOM implementation can then implement one (i.e. only the Core module)
or more modules depending on the host application. A Web user agent is
very likely to implement the "MouseEvents" module, while a server-side
application will have no use of this module and will probably not
implement it.

Conformance

This section explains the different levels of conformance to DOM Level
3. DOM Level 3 consists of 16 modules. It is possible to conform to DOM
Level 3, or to a DOM Level 3 module.

An implementation is DOM Level 3 conformant if it supports the Core
module defined in this document (see Fundamental Interfaces: Core Module
<#core-ID-BBACDC08>). An implementation conforms to a DOM Level 3 module
if it supports all the interfaces for that module and the associated
semantics.

Here is the complete list of DOM Level 3.0 modules and the features used
by them. Feature names are case-insensitive.

Core module
defines the feature /"Core"/ <#core-ID-BBACDC08>.
XML module
Defines the feature /"XML"/ <#core-ID-E067D597>.
Events module
defines the feature /"Events"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
User interface Events module
defines the feature /"UIEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Mouse Events module
defines the feature /"MouseEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Text Events module
defines the feature /"TextEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Keyboard Events module
defines the feature /"KeyboardEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Mutation Events module
defines the feature /"MutationEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Mutation name Events module
defines the feature /"MutationNameEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
HTML Events module
defines the feature /"HTMLEvents"/
<http://www.w3.org/TR/DOM-Level-3-Events/events.html> in [DOM Level
3 Events <#references-DOMEvents>].
Load and Save module
defines the feature /"LS"/
<http://www.w3.org/TR/DOM-Level-3-LS/load-save.html> in [DOM Level 3
Load and Save <#references-DOMLS>].
Asynchronous load module
defines the feature /"LS-Async"/
<http://www.w3.org/TR/DOM-Level-3-LS/load-save.html> in [DOM Level 3
Load and Save <#references-DOMLS>].
Validation module
defines the feature /"Validation"/
<http://www.w3.org/TR/DOM-Level-3-Val/validation.html> in [DOM Level
3 Validation <#references-DOMVal>].
XPath module
defines the feature /"XPath"/
<http://www.w3.org/TR/DOM-Level-3-XPath/xpath.html> in [DOM Level 3
XPath <#references-DOMXPath>].

A DOM implementation must not return |true| to the
|DOMImplementation.hasFeature(feature, version)| <#core-ID-5CED94D7>
method <#glossary-dt-method> of the |DOMImplementation|
<#core-ID-102161490> interface for that feature unless the
implementation conforms to that module. The |version| number for all
features used in DOM Level 3.0 is |"3.0"|.

DOM Interfaces and DOM Implementations

The DOM specifies interfaces which may be used to manage XML or HTML
documents. It is important to realize that these interfaces are an
abstraction - much like "abstract base classes" in C++, they are a means
of specifying a way to access and manipulate an application's internal
representation of a document. Interfaces do not imply a particular
concrete implementation. Each DOM application is free to maintain
documents in any convenient representation, as long as the interfaces
shown in this specification are supported. Some DOM implementations will
be existing programs that use the DOM interfaces to access software
written long before the DOM specification existed. Therefore, the DOM is
designed to avoid implementation dependencies; in particular,

1. Attributes defined in the IDL do not imply concrete objects which
must have specific data members - in the language bindings, they
are translated to a pair of get()/set() functions, not to a data
member. Read-only attributes have only a get() function in the
language bindings.
2. DOM applications may provide additional interfaces and objects not
found in this specification and still be considered DOM conformant.
3. Because we specify interfaces and not the actual objects that are
to be created, the DOM cannot know what constructors to call for
an implementation. In general, DOM users call the createX()
methods on the Document class to create document structures, and
DOM implementations create their own internal representations of
these structures in their implementations of the createX() functions.

The Level 2 interfaces were extended to provide both Level 2 and Level 3
functionality.

DOM implementations in languages other than Java or ECMAScript may
choose bindings that are appropriate and natural for their language and
run time environment. For example, some systems may need to create a
Document3 class which inherits from a Document class and contains the
new methods and attributes.

DOM Level 3 does not specify multithreading mechanisms.

07 April 2004

1. Document Object Model Core

/Editors/:
Arnaud Le Hors, IBM
Philippe Le Hégaret, W3C
Gavin Nicol, Inso EPS (for DOM Level 1)
Lauren Wood, SoftQuad, Inc. (for DOM Level 1)
Mike Champion, Arbortext and Software AG (for DOM Level 1 from
November 20, 1997)
Steve Byrne, JavaSoft (for DOM Level 1 until November 19, 1997)

Table of contents

* 1.1 Overview of the DOM Core Interfaces <#core-ID-1590626201>
o 1.1.1 The DOM Structure Model <#core-ID-1590626202>
o 1.1.2 Memory Management <#core-ID-249F15BA>
o 1.1.3 Naming Conventions <#core-ID-45A944CB>
o 1.1.4 Inheritance vs. Flattened Views of the API
<#core-ID-1CED5498>
* 1.2 Basic Types <#core-BasicTypes>
o 1.2.1 The DOMString Type <#core-ID-C74D1578>
+ DOMString <#core-DOMString>
o 1.2.2 The DOMTimeStamp Type <#core-Core-DOMTimeStamp>
+ DOMTimeStamp <#core-DOMTimeStamp>
o 1.2.3 The DOMUserData Type <#core-Core-DOMUserData>
+ DOMUserData <#core-DOMUserData>
o 1.2.4 The DOMObject Type <#core-Core-DOMObject>
+ DOMObject <#core-DOMObject>
* 1.3 General Considerations <#core-Consideration>
o 1.3.1 String Comparisons in the DOM <#core-ID-5DFED1F0>
o 1.3.2 DOM URIs <#core-domURIs>
o 1.3.3 XML Namespaces <#core-Namespaces-Considerations>
o 1.3.4 Base URIs <#core-baseURIs-Considerations>
o 1.3.5 Mixed DOM Implementations <#core-Embedded-DOM>
o 1.3.6 DOM Features <#core-DOMFeatures>
o 1.3.7 Bootstrapping <#core-Bootstrap>
* 1.4 Fundamental Interfaces: Core Module <#core-ID-BBACDC08>
o DOMException <#core-ID-17189187>, ExceptionCode
<#core-ID-258A00AF>, DOMStringList <#core-DOMStringList>,
NameList <#core-NameList>, DOMImplementationList
<#core-DOMImplementationList>, DOMImplementationSource
<#core-DOMImplementationSource>, DOMImplementation
<#core-ID-102161490>, DocumentFragment <#core-ID-B63ED1A3>,
Document <#core-i-Document>, Node <#core-ID-1950641247>,
NodeList <#core-ID-536297177>, NamedNodeMap
<#core-ID-1780488922>, CharacterData <#core-ID-FF21A306>,
Attr <#core-ID-637646024>, Element <#core-ID-745549614>,
Text <#core-ID-1312295772>, Comment <#core-ID-1728279322>,
TypeInfo <#core-TypeInfo>, UserDataHandler
<#core-UserDataHandler>, DOMError
<#core-ERROR-Interfaces-DOMError>, DOMErrorHandler
<#core-ERROR-Interfaces-DOMErrorHandler>, DOMLocator
<#core-Interfaces-DOMLocator>, DOMConfiguration
<#core-DOMConfiguration>
* 1.5 Extended Interfaces: XML Module <#core-ID-E067D597>
o CDATASection <#core-ID-667469212>, DocumentType
<#core-ID-412266927>, Notation <#core-ID-5431D1B9>, Entity
<#core-ID-527DCFF2>, EntityReference <#core-ID-11C98490>,
ProcessingInstruction <#core-ID-1004215813>

This specification defines a set of objects and interfaces for accessing
and manipulating document objects. The functionality specified (the
/Core/ functionality) is sufficient to allow software developers and Web
script authors to access and manipulate parsed HTML [HTML 4.01
<#references-HTML40>] and XML [XML 1.0 <#references-XML>] content inside
conforming products. The DOM Core API <#glossary-dt-API> also allows
creation and population of a |Document| <#core-i-Document> object using
only DOM API calls. A solution for loading a |Document|
<#core-i-Document> and saving it persistently is proposed in [DOM Level
3 Load and Save <#references-DOMLS>].

1.1 Overview of the DOM Core Interfaces

1.1.1 The DOM Structure Model

The DOM presents documents as a hierarchy of |Node|
<#core-ID-1950641247> objects that also implement other, more
specialized interfaces. Some types of nodes may have child
<#glossary-dt-child> nodes of various types, and others are leaf nodes
that cannot have anything below them in the document structure. For XML
and HTML, the node types, and which node types they may have as
children, are as follows:

* |Document| <#core-i-Document> -- |Element| <#core-ID-745549614>
(maximum of one), |ProcessingInstruction| <#core-ID-1004215813>,
|Comment| <#core-ID-1728279322>, |DocumentType|
<#core-ID-412266927> (maximum of one)
* |DocumentFragment| <#core-ID-B63ED1A3> -- |Element|
<#core-ID-745549614>, |ProcessingInstruction|
<#core-ID-1004215813>, |Comment| <#core-ID-1728279322>, |Text|
<#core-ID-1312295772>, |CDATASection| <#core-ID-667469212>,
|EntityReference| <#core-ID-11C98490>
* |DocumentType| <#core-ID-412266927> -- no children
* |EntityReference| <#core-ID-11C98490> -- |Element|
<#core-ID-745549614>, |ProcessingInstruction|
<#core-ID-1004215813>, |Comment| <#core-ID-1728279322>, |Text|
<#core-ID-1312295772>, |CDATASection| <#core-ID-667469212>,
|EntityReference| <#core-ID-11C98490>
* |Element| <#core-ID-745549614> -- |Element| <#core-ID-745549614>,
|Text| <#core-ID-1312295772>, |Comment| <#core-ID-1728279322>,
|ProcessingInstruction| <#core-ID-1004215813>, |CDATASection|
<#core-ID-667469212>, |EntityReference| <#core-ID-11C98490>
* |Attr| <#core-ID-637646024> -- |Text| <#core-ID-1312295772>,
|EntityReference| <#core-ID-11C98490>
* |ProcessingInstruction| <#core-ID-1004215813> -- no children
* |Comment| <#core-ID-1728279322> -- no children
* |Text| <#core-ID-1312295772> -- no children
* |CDATASection| <#core-ID-667469212> -- no children
* |Entity| <#core-ID-527DCFF2> -- |Element| <#core-ID-745549614>,
|ProcessingInstruction| <#core-ID-1004215813>, |Comment|
<#core-ID-1728279322>, |Text| <#core-ID-1312295772>,
|CDATASection| <#core-ID-667469212>, |EntityReference|
<#core-ID-11C98490>
* |Notation| <#core-ID-5431D1B9> -- no children

The DOM also specifies a |NodeList| <#core-ID-536297177> interface to
handle ordered lists of |Nodes| <#core-ID-1950641247>, such as the
children of a |Node| <#core-ID-1950641247>, or the elements
<#glossary-dt-element> returned by the
|Element.getElementsByTagNameNS(namespaceURI, localName)|
<#core-ID-A6C90942> method, and also a |NamedNodeMap|
<#core-ID-1780488922> interface to handle unordered sets of nodes
referenced by their name attribute, such as the attributes of an
|Element| <#core-ID-745549614>. |NodeList| <#core-ID-536297177> and
|NamedNodeMap| <#core-ID-1780488922> objects in the DOM are /live/; that
is, changes to the underlying document structure are reflected in all
relevant |NodeList| <#core-ID-536297177> and |NamedNodeMap|
<#core-ID-1780488922> objects. For example, if a DOM user gets a
|NodeList| <#core-ID-536297177> object containing the children of an
|Element| <#core-ID-745549614>, then subsequently adds more children to
that element <#glossary-dt-element> (or removes children, or modifies
them), those changes are automatically reflected in the |NodeList|
<#core-ID-536297177>, without further action on the user's part.
Likewise, changes to a |Node| <#core-ID-1950641247> in the tree are
reflected in all references to that |Node| <#core-ID-1950641247> in
|NodeList| <#core-ID-536297177> and |NamedNodeMap| <#core-ID-1780488922>
objects.

Finally, the interfaces |Text| <#core-ID-1312295772>, |Comment|
<#core-ID-1728279322>, and |CDATASection| <#core-ID-667469212> all
inherit from the |CharacterData| <#core-ID-FF21A306> interface.

1.1.2 Memory Management

Most of the APIs defined by this specification are /interfaces/ rather
than classes. That means that an implementation need only expose methods
with the defined names and specified operation, not implement classes
that correspond directly to the interfaces. This allows the DOM APIs to
be implemented as a thin veneer on top of legacy applications with their
own data structures, or on top of newer applications with different
class hierarchies. This also means that ordinary constructors (in the
Java or C++ sense) cannot be used to create DOM objects, since the
underlying objects to be constructed may have little relationship to the
DOM interfaces. The conventional solution to this in object-oriented
design is to define /factory/ methods that create instances of objects
that implement the various interfaces. Objects implementing some
interface "X" are created by a "createX()" method on the |Document|
<#core-i-Document> interface; this is because all DOM objects live in
the context of a specific Document.

The Core DOM APIs are designed to be compatible with a wide range of
languages, including both general-user scripting languages and the more
challenging languages used mostly by professional programmers. Thus, the
DOM APIs need to operate across a variety of memory management
philosophies, from language bindings that do not expose memory
management to the user at all, through those (notably Java) that provide
explicit constructors but provide an automatic garbage collection
mechanism to automatically reclaim unused memory, to those (especially
C/C++) that generally require the programmer to explicitly allocate
object memory, track where it is used, and explicitly free it for
re-use. To ensure a consistent API across these platforms, the DOM does
not address memory management issues at all, but instead leaves these
for the implementation. Neither of the explicit language bindings
defined by the DOM API (for ECMAScript <#glossary-dt-ECMAScript> and
Java) require any memory management methods, but DOM bindings for other
languages (especially C or C++) may require such support. These
extensions will be the responsibility of those adapting the DOM API to a
specific language, not the DOM Working Group.

1.1.3 Naming Conventions

While it would be nice to have attribute and method names that are
short, informative, internally consistent, and familiar to users of
similar APIs, the names also should not clash with the names in legacy
APIs supported by DOM implementations. Furthermore, both OMG IDL [OMG
IDL <#references-OMGIDL>] and ECMAScript [ECMAScript
<#references-ECMAScript>] have significant limitations in their ability
to disambiguate names from different namespaces that make it difficult
to avoid naming conflicts with short, familiar names. So, DOM names tend
to be long and descriptive in order to be unique across all environments.

The Working Group has also attempted to be internally consistent in its
use of various terms, even though these may not be common distinctions
in other APIs. For example, the DOM API uses the method name "remove"
when the method changes the structural model, and the method name
"delete" when the method gets rid of something inside the structure
model. The thing that is deleted is not returned. The thing that is
removed may be returned, when it makes sense to return it.

1.1.4 Inheritance vs. Flattened Views of the API

The DOM Core APIs <#glossary-dt-API> present two somewhat different sets
of interfaces to an XML/HTML document: one presenting an "object
oriented" approach with a hierarchy of inheritance
<#glossary-dt-inheritance>, and a "simplified" view that allows all
manipulation to be done via the |Node| <#core-ID-1950641247> interface
without requiring casts (in Java and other C-like languages) or query
interface calls in COM <#glossary-dt-COM> environments. These operations
are fairly expensive in Java and COM, and the DOM may be used in
performance-critical environments, so we allow significant functionality
using just the |Node| <#core-ID-1950641247> interface. Because many
other users will find the inheritance <#glossary-dt-inheritance>
hierarchy easier to understand than the "everything is a |Node|
<#core-ID-1950641247>" approach to the DOM, we also support the full
higher-level interfaces for those who prefer a more object-oriented API
<#glossary-dt-API>.

In practice, this means that there is a certain amount of redundancy in
the API <#glossary-dt-API>. The Working Group considers the "inheritance
<#glossary-dt-inheritance>" approach the primary view of the API, and
the full set of functionality on |Node| <#core-ID-1950641247> to be
"extra" functionality that users may employ, but that does not eliminate
the need for methods on other interfaces that an object-oriented
analysis would dictate. (Of course, when the O-O analysis yields an
attribute or method that is identical to one on the |Node|
<#core-ID-1950641247> interface, we don't specify a completely redundant
one.) Thus, even though there is a generic |Node.nodeName|
<#core-ID-F68D095> attribute on the |Node| <#core-ID-1950641247>
interface, there is still a |Element.tagName| <#core-ID-104682815>
attribute on the |Element| <#core-ID-745549614> interface; these two
attributes must contain the same value, but the it is worthwhile to
support both, given the different constituencies the DOM API
<#glossary-dt-API> must satisfy.

1.2 Basic Types

To ensure interoperability, this specification specifies the following
basic types used in various DOM modules. Even though the DOM uses the
basic types in the interfaces, bindings may use different types and
normative bindings are only given for Java and ECMAScript in this
specification.

1.2.1 The |DOMString| <#core-DOMString> Type

The |DOMString| <#core-DOMString> type is used to store [Unicode
<#references-Unicode>] characters as a sequence of 16-bit units
<#glossary-dt-16-bit-unit> using UTF-16 as defined in [Unicode
<#references-Unicode>] and Amendment 1 of [ISO/IEC 10646
<#references-ISO10646>].

Characters are fully normalized
<http://www.w3.org/TR/2004/REC-xml11-20040204/#dt-fullnorm> as defined
in appendix B of [XML 1.1 <#references-XML11>] if:

* the parameter "normalize-characters
<#core-parameter-normalize-characters>" was set to |true| while
loading the document or the document was certified as defined in
[XML 1.1 <#references-XML11>];
* the parameter "normalize-characters
<#core-parameter-normalize-characters>" was set to |true| while
using the method |Document.normalizeDocument()|
<#core-Document3-normalizeDocument>, or while using the method
|Node.normalize()| <#core-ID-normalize>;

Note that, with the exceptions of |Document.normalizeDocument()|
<#core-Document3-normalizeDocument> and |Node.normalize()|
<#core-ID-normalize>, manipulating characters using DOM methods does not
guarantee to preserve a /fully-normalized/ text.

*Type Definition /DOMString/*

A |DOMString| <#core-DOMString> is a sequence of 16-bit units
<#glossary-dt-16-bit-unit>.

*IDL Definition*

valuetype DOMString <#core-DOMString> sequence<unsigned short>;

The UTF-16 encoding was chosen because of its widespread industry
practice. Note that for both HTML and XML, the document character set
(and therefore the notation of numeric character references) is based on
UCS [ISO/IEC 10646 <#references-ISO10646>]. A single numeric character
reference in a source document may therefore in some cases correspond to
two 16-bit units in a |DOMString| <#core-DOMString> (a high surrogate
and a low surrogate). For issues related to string comparisons, refer to
String Comparisons in the DOM <#core-ID-5DFED1F0>.

For Java and ECMAScript, |DOMString| <#core-DOMString> is bound to the
|String| type because both languages also use UTF-16 as their encoding.

*Note:* As of August 2000, the OMG IDL specification ([OMG IDL
<#references-OMGIDL>]) included a |wstring| type. However, that
definition did not meet the interoperability criteria of the DOM API
<#glossary-dt-API> since it relied on negotiation to decide the width
and encoding of a character.

1.2.2 The |DOMTimeStamp| <#core-DOMTimeStamp> Type

The |DOMTimeStamp| <#core-DOMTimeStamp> type is used to store an
absolute or relative time.

*Type Definition /DOMTimeStamp/*

A |DOMTimeStamp| <#core-DOMTimeStamp> represents a number of
milliseconds.

*IDL Definition*

typedef unsigned long long DOMTimeStamp <#core-DOMTimeStamp>;

For Java, |DOMTimeStamp| <#core-DOMTimeStamp> is bound to the |long|
type. For ECMAScript, |DOMTimeStamp| <#core-DOMTimeStamp> is bound to
the |Date| type because the range of the |integer| type is too small.

1.2.3 The |DOMUserData| <#core-DOMUserData> Type

The |DOMUserData| <#core-DOMUserData> type is used to store application
data.

*Type Definition /DOMUserData/*

A |DOMUserData| <#core-DOMUserData> represents a reference to
application data.