29 September, 2000

Appendix A: Changes

Editors
Philippe Le Hégaret, W3C

This appendix contains the changes from the 1 October 1998 specification.

A.1: Changes in the "What is the Document Object Model?"

Introduction
The link to the CORBA 2.2 specification was broken.
Also, the first item of the list about "DOM Interfaces and DOM Implementations" had text about "read-only functions" which was changed to "read-only attributes".
What the Document Object Model is
The following sentence was missing:
Each document contains zero or one doctype nodes, one root element node, and zero or more comments or processing instructions; the root element serves as the root of the element tree for the document.

The following statement has been modified:
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, with precisely the same objects and relationships.

It now reads:
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 [Infoset].

with the following note:

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


The compliance paragraph has been moved into a specific section (see Compliance).
What the Document Object Model is not
The following statement has been modified:
The Document Object Model does not define "the true inner semantics" of XML or HTML. The semantics of those languages are defined by W3C Recommendations for these languages. The DOM is a programming model designed to respect these semantics. The DOM does not have any ramifications for the way you write XML and HTML documents; any document that can be written in these languages can be represented in the DOM.

It now reads:
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 W3C XML Information Set [Infoset]. The DOM is simply an API to this information set.

A.2: Changes in the Document Object Model Core

Section 1.1.5. The DOMString type
The DOMString type was defined as "a sequence of 16-bit quantities". Instead, it is now defined as "sequence of 16-bit units".
Then, the description contained the following sentences:
Please note that for both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS-4. A single numeric character reference in a source document may therefore in some cases correspond to two array positions in a DOMString (a high surrogate and a low surrogate).

This now reads:
Please note that for both HTML and XML, the document character set (and therefore the notation of numeric character references) is based on UCS [ISO-10646]. A single numeric character reference in a source document may therefore in some cases correspond to two 16-bit units in a DOMString (a high surrogate and a low surrogate).
Section 1.1.6. String comparisons in the DOM
The title of this section, which was Case sensitivity in the DOM, was changed to be more accurate.
The first paragraph ended with the following:
For the purposes of the DOM, string matching takes place on a character code by character code basis, on the 16 bit value of a DOMString. As such, the DOM assumes that any normalizations will take place in the processor, before the DOM structures are built.

This sentence now reads:
For the purposes of the DOM, string matching is performed purely by binary comparison of the 16-bit units of the DOMString. In addition, the DOM assumes that any normalizations take place in the processor, before the DOM structures are built.

With the following note:

Note: Besides case folding, there are additional normalizations that can be applied to text. The W3C I18N Working Group is in the process of defining exactly which normalizations are necessary, and where they should be applied. The W3C I18N Working Group expects to require early normalization, which means that data read into the DOM is assumed to already be normalized. The DOM and applications built on top of it in this case only have to assure that text remains normalized when being changed. For further details, please see [Charmod].

Section 1.2 Interface Attr
The fact that setting the value attribute raises a NO_MODIFICATION_ALLOWED_ERR DOMException when the node is readonly was added.
A sentence has been added at the end of the first paragraph of the description of the value attribute:
See also the method getAttribute on the Element interface.

also at the end of the second paragraph:
I.e. any characters that an XML processor would recognize as markup are instead treated as literal text. See also the method setAttribute on the Element interface.

And on the specified attribute:
If the attribute is not associated to any element (i.e. because it was just created or was obtained from some removal or cloning operation) specified is true.
Section 1.2 Interface CharacterData
The following paragraph has been added:
As explained in the DOMString interface, text strings in the DOM are represented in UTF-16, i.e. as a sequence of 16-bit units. In the following, the term 16-bit units is used whenever necessary to indicate that indexing on CharacterData is done in 16-bit units.

The description of the length attribute read:
The number of characters that are available through data and the substringData method below.

It now reads:
The number of 16-bit units that are available through data and the substringData method below.

The description of the count parameter of the substringData method read:
The number of characters to extract.

It now reads:
The number of 16-bit units to extract.

Then the description of the return value read:
The specified substring. If the sum of offset and count exceeds the length, then all characters to the end of the data are returned.

It now reads:
The specified substring. If the sum of offset and count exceeds the length, then all 16-bit units to the end of the data are returned.

The exception INDEX_SIZE_ERR was said to be:
Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

Instead this now reads:
Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

The description of the insertData method read:
Insert a string at the specified character offset.

Instead it now reads:
Insert a string at the specified 16-bit unit offset.

Then the description of the offset parameter read:
The character offset at which to insert.

when it now reads:
The 16-bit unit offset at which to insert.

The exception INDEX_SIZE_ERR was said to be:
Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

Instead this now reads:
Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.

The description of the deleteData method read:
Remove a range of characters from the node.

Instead it now reads:
Remove a range of 16-bit units from the node.

Then the description of the count parameter read:
The number of characters to delete. If the sum of offset and count exceeds length then all characters from offset to the end of the data are deleted.

when it now reads:
The number of 16-bit units to delete. If the sum of offset and count exceeds length then all 16-bit units from offset to the end of the data are deleted.

The description of the replaceData method read:
Replace the characters starting at the specified character offset with the specified string.

instead it now reads:
Replace the characters starting at the specified 16-bit unit offset with the specified string.

Then the description of the count parameter read:
The number of characters to replace. If the sum of offset and count exceeds length, then all characters to the end of the data are replaced

when it now reads:
The number of 16-bit units to replace. If the sum of offset and count exceeds length, then all 16-bit units to the end of the data are replaced

The exception INDEX_SIZE_ERR was said to be:
Raised if the specified offset is negative or greater than the number of characters in data, or if the specified count is negative.

Instead this now reads:
Raised if the specified offset is negative or greater than the number of 16-bit units in data, or if the specified count is negative.
Section 1.2 Interface DOMImplementation

The definition of the feature parameter read:
The package name of the feature to test. In Level 1, the legal values are "HTML" and "XML" (case-insensitive).

This now reads:
The name of the feature to test (case-insensitive). The values used by DOM features are defined throughout this specification and listed i n the Compliance section. The name must be an XML name. To avoid possible conflicts, as a convention, names referring to features defined outside the DOM specification should be made unique by reversing the name of the Internet domain name of the person (or the organization that the person belongs to) who defines the feature, component by component, and using this as a prefix. For instance, the W3C SYMM Working Group defines the feature "org.w3c.dom.smil".

The definition of the version parameter read:
This is the version number of the package name to test. In Level 1, this is the string "1.0".

This now reads:
This is the version number of the feature to test. In Level 1, this is the string "1.0".
Section 1.2 Interface Document
The description of the createElement method was missing the following piece:
In addition, if there are known attributes with default values, Attr nodes representing them are automatically created and attached to the element.

The description of the createEntityReference method was missing the following piece:
In addition, if the referenced entity is known, the child list of the EntityReference node is made the same as that of the corresponding Entity node.

The description of the doctype attribute was missing the following piece:
The DOM Level 1 does not support editing the Document Type Declaration, therefore docType cannot be altered in any way, including through the use of methods, such as insertNode or removeNode, which are inherited from the Node interface.

The description of the createAttribute method was said to be:
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttribute method.

it is now:
Creates an Attr of the given name. Note that the Attr instance can then be set on an Element using the setAttributeNode method.

The description of the return value was missing:
The value of the attribute is the emtpy string.

The exception INVALID_CHARACTER_ERR for createElement, createAttribute, createEntityReference and createProcessingInstruction methods was said to be:
Raised if the specified name contains an invalid character.

Instead this now reads:
Raised if the specified name contains an illegal character.
Section 1.2 Interface DocumentType
The description of the entities attribute has been modified:
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Duplicates are discarded.

It now reads:
A NamedNodeMap containing the general entities, both external and internal, declared in the DTD. Parameter entities are not contained. Duplicates are discarded.

The example has been modified as follows:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY % baz "baz">
]>
<ex/>
the interface provides access to foo and bar but not baz. [ ...]

It is now:
<!DOCTYPE ex SYSTEM "ex.dtd" [
  <!ENTITY foo "foo">
  <!ENTITY bar "bar">
  <!ENTITY bar "bar2">
  <!ENTITY % baz "baz">
]>
<ex/>
the interface provides access to foo and the first declaration of bar but not the second declaration of bar or baz. [...]
Section 1.2 Interface Element
The following example has been removed:
By far the vast majority of objects (apart from text) that authors encounter when traversing a document are Element nodes. Assume the following XML document:

<elementExample id="demo">
  <subelement1/>
  <subelement2><subsubelement/></subelement2>
</elementExample>  
When represented using DOM, the top node is a Document node containing an Element node for "elementExample" which contains two child Element nodes, one for "subelement1" and one for "subelement2". "subelement1" contains no child nodes.

The following sentence has been added:
The Element interface represents an element in an HTML or XML document.

The description read:
the generic Node interface method getAttributes may be used to retrieve the set of all attributes for an element.

However, there is no getAttributes method per se, although it may exist in some language binding such as the java one. So this section now reads:
the generic Node interface attribute attributes may be used to retrieve the set of all attributes for an element.

The removeAttribute method description read:
If the removed attribute has a default value it is immediately replaced.

This now reads:
If the removed attribute is known to have a default value, an attribute immediately appears containing the default value.

The removeAttributeNode method description read:
Removes the specified attribute.

This now reads:
Removes the specified attribute. If the removed Attr has a default value it is immediately replaced.

The description of the oldAttr has been chagned according to the previous change:
The Attr node to remove from the attribute list. If the removed Attr has a default value it is immediately replaced.

This now reads:
The Attr node to remove from the attribute list.

In addition, the following note was added to the description of the normalize method:

Note: In cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes.


And the following change was made to the description of the same method:
Puts all Text nodes in the full depth of the sub-tree underneath this Element into a "normal" form where only markup (e.g., tags, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are no adjacent Text nodes.

This now reads:
Puts all Text nodes in the full depth of the sub-tree underneath this Element, including attribute nodes, into a "normal" form where only markup (e.g., tags, comments, processing instructions, CDATA sections, and entity references) separates Text nodes, i.e., there are no adjacent Text nodes.

The exception INVALID_CHARACTER_ERR for the setAttribute method was said to be:
Raised if the specified name contains an invalid character.

Instead this now reads:
Raised if the specified name contains an illegal character.

The description for setAttributeNode was said to be:
Adds a new attribute.

Instead this now reads:
Adds a new attribute node.

The description for setAttributeNode return value was said to be:
If the newAttr attribute replaces an existing attribute with the same name, the previously existing Attr node is returned, otherwise null is returned.

Instead this now reads:
If the newAttr attribute replaces an existing attribute, the replaced Attr node is returned, otherwise null is returned.
Section 1.2 Interface DOMException
The following note has been added for the ExceptionCode group:

Note: Other numeric codes are reserved for W3C for possible future use.


The description of the INVALID_CHARACTER_ERR read:
If an invalid character is specified, such as in a name.

Instead it now reads:
If an invalid or illegal character is specified, such as in a name. See production 2 in the XML specification for the definition of a legal character, and production 5 for the definition of a legal name character.
Section 1.2 Interface NamedNodeMap
The description of the setNamedItem was missing (moved from the description of the arg parameter):
If a node with that name is already present in this map, it is replaced by the new one.

The description of the return value of the removeNamedItem method read:
The node removed from the map or null if no node with such a name exists.

But this error case is already handled by having the method to throw a NOT_FOUND_ERR DOMException. So this section now simply reads:
The node removed from the map if a node with such a name exists.

The description of the removeNamedItem method now includes the following note that was missing:
When this map contains the attributes attached to an element, if the removed attribute is known to have a default value, an attribute immediately appears containing the default value.

In addition, it was added that the removeNamedItem method raises a NO_MODIFICATION_ALLOWED_ERR DOMException when the NamedNodeMap is readonly.
Section 1.2 Interface Node
It was added to the description of the nodeValue attribute that setting it, when it is defined to be null, has no effect.
It was also added to the description of the parentNode attribute that Entity and Notation nodes do not have a parent.
It was also added to the description of the NodeType group:
Numeric codes up to 200 are reserved to W3C for possible future use.

The following description has been removed:
The content of the returned NodeList is "live" in the sense that, for instance, changes to the children of the node object that it was created from are immediately reflected in the nodes returned by the NodeList accessors; it is not a static snapshot of the content of the node. This is true for every NodeList, including the ones returned by the getElementsByTagName method.

The description of the NO_MODIFICATION_ALLOWED_ERR exception of the insertBefore method read:
Raised if this node is readonly.

It now reads:
Raised if this node is readonly or if the parent of the node being inserted is readonly.

The description of the replaceChild method was missing:
If newChild is a DocumentFragment object, oldChild is replaced by all of the DocumentFragment children, which are inserted in the same order. If the newChild is already in the tree, it is first removed.

The description of the NO_MODIFICATION_ALLOWED_ERR exception of the replaceChild method read:
Raised if this node is readonly.

It now reads:
Raised if this node or the parent of the new node is readonly.

The description of the cloneNode method was missing:
Note that cloning an immutable subtree results in a mutable copy, but the children of an EntityReference clone are readonly. In addition, clones of unspecified Attr nodes are specified. And, cloning Document, DocumentType, Entity, and Notation nodes is implementation dependent.

and also missing the following exceptions:
NOT_SUPPORTED_ERR: Raised if this node is a of type DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ENTITY_NODE, or NOTATION_NODE and the implementation does not support cloning this type of node.
Section 1.2 Interface NodeList
The description was missing:
NodeList objects in the DOM are live.
Section 1.2 Interface Comment
The first paragraph read:
This represents the content of a comment, i.e., all the characters between the starting '<!--' and ending '-->'.

It now reads "This interface inherits from CharacterData and represents ...".
Section 1.2 Interface Text
The first paragraph read:
The Text interface represents the textual content (termed character data in XML) of an Element or Attr.

It now reads "The Text interface inherits from CharacterData and represents ...".
The first paragraph read:
If there is markup, it is parsed into a list of elements and Text nodes that form the list of children of the element.

It has been clarified, now reads "into the information items (elements, children comments, etc.) and ...".
The last sentence of the second paragraph of the interface description read:
The normalize() method on Element merges any such adjacent Text objects into a single node for each block of text; this is recommended before employing operations that depend on a particular document structure, such as navigation with XPointers.

However, since in cases where the document contains CDATASections, the normalize operation alone may not be sufficient, since XPointers do not differentiate between Text nodes and CDATASection nodes, the last part of the sentence (after the semi-colon) was dropped.
The following sentence was added, for clarification purpose, to the description of the splitText method:
When the offset is equal to the length of this node, the new Text node has no data.

The description of the slitText method has been clarified:
Breaks this Text node into two Text at the specified offset, ...

It now reads "Breaks this node into two nodes ...".
The description offset parameter of the splitText method read:
The offset at which to split, starting from 0.

It now reads:
The 16-bit unit offset at which to split, starting from 0.

The description return value read:
The new Text node.

It now reads:
The new node, of the same type as this node.

The exception INDEX_SIZE_ERR was said to be:
Raised if the specified offset is negative or greater than the number of characters in data.

Instead this now reads:
Raised if the specified offset is negative or greater than the number of 16-bit units in data.
Section 1.3 Extended Interfaces
The following paragraph was missing:
A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether they are supported or not. The feature string for all the interfaces listed in this section is "XML".
Section 1.3 Interface CDATASection
The following note was added to the description:

Note: Because no markup is recognized within a CDATASection, character numeric references cannot be used as an escape mechanism when serializing. Therefore, action needs to be taken when serializing a CDATASection with a character encoding where some of the contained characters cannot be represented. Failure to do so would not produce well-formed XML.
One potential solution in the serialization process is to end the CDATA section before the character, output the character using a character reference or entity reference, and open a new CDATA section for any further characters in the text node. Note, however, that some code conversion libraries at the time of writing do not return an error or exception when a character is missing from the encoding, making the task of ensuring that data is not corrupted on serialization more difficult.

Section 1.3. Interface Notation
The first paragraph read:
they are therefore readonly.

A link to the glossary has been added for readonly.
Section 1.3 Interface Entity
The last sentence of the last paragraph was said to be:
All the descendants of an Entity node are readonly.

Instead, it now reads:
Entity nodes and all their descendants are readonly.
Section 1.3 Interface EntityReference
The following note was added to the description:
As for Entity nodes, EntityReference nodes and all their descendants are readonly.

A.3: Changes in the Document Object Model HTML

Section 2.1 Introduction
The last sentence of the third paragraph was:
Interoperability between implementations is only guaranteed for elements and attributes that are specified in these DTDs.

This seemed to imply interoperability is not guaranteed for the HTML 4.0 strict DTD, so it was changed to:
Interoperability between implementations is only guaranteed for elements and attributes that are specified in the HTML 4.0 DTDs.
Section 2.5.1 Property Attributes
"border" was given as an example of an open-value value list in the table. It was changed to "disabled".
Section 2.5.5 Interface HTMLBlockquoteElement
This interface was an error and was removed. The Interface HTMLQuoteElement is used for both the Q and BLOCKQUOTE HTML elements.
Section 2.5.5 Interface HTMLInputElement
The description of the defaultValue attribute now reads:
value "Text", "File" or "Password", this represents the HTML value attribute of the element. The value of this attribute does not change if the contents of the corresponding form control in an interactive user agent changes. Changing this attribute, however, resets the contents of the form control. See the value attribute definition in HTML 4.0.

The description of the value attribute now reads:
When the type attribute of the element has the value "Text", "File" or "Password", this represents the current contents of the corresponding form control in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the value of the HTML value attribute of the element. When the type attribute of the element has the value "Button", "Hidden", "Submit", "Reset", "Image", "Checkbox" or "Radio", this represents the HTML value attribute of the element. See the value attribute definition in HTML 4.0.

The description of the defaultChecked attribute now reads:
When the type attribute of the element has the value "Checkbox" or "Radio", this represents the HTML checked attribute of the element. The value of this attribute does not change if the state of the corresponding form control in an interactive user agent changes. Changes to this attribute, however, resets the state of the form control. See the checked attribute definition in HTML 4.0.

The description of the checked attribute now reads:
When the type attribute of the element has the value "Checkbox" or "Radio", this represents the current state of the corresponding form control in am interactive user agent. Changes to this attribute changes the state of the form control, but does not change the value of the HTML value attribute of the element.
Section 2.5.5 Interface HTMLOptionElement
The index attribute was changed to readonly and the selected attribute to readwrite. It was also added that the index attribute starts from 0.
The description of the defaultSelected attribute was unclear, it now reads:
Represents the value of the HTML selected attribute. The value of this attribute does not change if the state of the corresponding form control in an interactive user agent changes. Changing defaultSelected, however, resets the state of the form control. See the selected attribute definition in HTML 4.0.

In addition, its description was unclear, it now reads:
Represents the current state of the corresponding form control in an interactive user agent. Changing this attribute changes the state of the form control, but does not change the value of the HTML selected attribute of the element.
Section 2.5.5 Interface HTMLSelectElement
It was added that the value of the type attribute is the string "select-multiple" when the multiple attribute is true and the string "select-one" when false.
It was also added that the index attribute starts from 0.
The description of the before parameter of the add method read:
The element to insert before, or null for the head of the list.

It was changed to:
The element to insert before, or null for the tail of the list.

Finally, it was added that an NOT_FOUND_ERR DOMException is raised when the before given to the add method is not a descendant of the SELECT element.
Section 2.5.5 Interface HTMLTableCellElement
The cellIndex attribute was changed to readonly and it was added that it starts from 0.
Section 2.5.5 Interface HTMLTableElement
The description of the index parameter of the insertRow and deleteRow methods was augmented with the following:
This index starts from 0 and is relative to all the rows contained inside the table, regardless of section parentage.

In addition, the following was added to the description of the insertRow method:
The new row is inserted immediately before and in the same section as the current indexth row in the table. If there is no such row, the row is inserted following the one before in the table. Finally, when the table is empty the row is inserted into a TBODY which is created and inserted into the table.

Finally, it was added that an INDEX_SIZE_ERR DOMException is raised when the index given to the insertRow method is greater than the number of rows, and when the index given to the deleteRow method is greater than or equal to the number of rows. In both case, the exception is also raised if the index is negative.
Section 2.5.5 Interface HTMLTableRowElement
The rowIndex, selectionRowIndex, and cells attributes were changed to readonly. And it was added that these indexes start from 0.
It was added that the index parameter of the insertCell and deleteCell methods starts from 0.
The following sentence was added to the description of the insertCell:
If index is equal to the number of cells, the new cell is appended.

In addition, it was added that an INDEX_SIZE_ERR DOMException is raised when the index given to the insertCell method is greater than the number of cells and when the index given to the deleteCell method is greater than or equal to the number of cells. In both case, the exception is also raised if the index is negative.
Section 2.5.5 Interface HTMLTableSectionElement
The description of the index parameter of the insertRow and deleteRow methods was augmented with the following:
This index starts from 0 and is relative only to the rows contained inside this section, not all the rows in the table.

In addition, it was added that an INDEX_SIZE_ERR DOMException is raised when the index given to the insertRow method is greater than the number of rows, and when the index given to the deleteRow method is greater than or equal to the number of rows. In both case, the exception is also raised if the index is negative.
Section 2.5.5 Interface HTMLTextArea
The value of the type attribute is now defined to be the string "textarea".
The description of the defaultValue attribute was unclear, it now reads:
Represents the contents of the element. The value of this attribute does not change if the contents of the corresponding form control in an interactive user agent changes. Changing this attribute, however, resets the contents of the form control.

The description of the value attribute was unclear, it now reads:
Represents the current contents of the corresponding form control in an interactive user agent. Changing this attribute changes the contents of the form control, but does not change the contents of the element.

A.4: Changes in the Appendices

Appendix D (formerly C): IDL Definition
The list of exception codes appeared twice and several pieces of information, such as the names and prefixes of the modules were missing.
We also added the following paragraph:
"Unfortunately the OMG IDL for the Document Object Model HTML is not compliant because of problems in the validator that was used to validate Level 1. The readOnly attribute on the HTMLInputElement and HTMLTextAreaElement interfaces, as well as the object attribute on the HTMLAppletElement interface, are not compliant with OMG IDL 2.2. The valueType attribute on the HTMLParamElement interface is not compliant with OMG IDL 2.3, which hadn't been released when DOM Level 1 was published."
Appendix E (formerly D): Java Language Binding
The java source files did not contain the copyright notice appropriate for people to use them in their products. A few errors in the javadoc part of them were also fixed.
References
The references were sorted by alphabetical order, severals references were added and updated.