This specification defines the Document Object Model Validation Level 3, a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents.
This is a W3C Working Draft for review by W3C members and other interested parties. This DOM module has been dissociated from the Abstract Schema DOM module since the modules were independent and the latter is no longer a work in progress.
It is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them 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.
Comments on this document are invited and are to be sent to the
This document has been produced as part of the
Patent disclosures relevant to this specification may be found
on the Working Group's
A list of
Created in electronic form.
$Revision: 1.2 $
Copyright © 2002
This document is published under the
This section is a copy of the W3C Document Notice and License and could
be found at
Copyright © 1994-2002
http://www.w3.org/Consortium/Legal/
Public documents on the W3C site are provided by the copyright holders
under the following license. The software or Document Type Definitions
(DTDs) associated with W3C specifications are governed by the
Permission to use, copy, and distribute the contents of this document, or
the W3C document from which this statement is linked, in any medium for
any purpose and without fee or royalty is hereby granted, provided that
you include the following on
A link or URL to the original W3C document.
The pre-existing copyright notice of the original author, or if it
doesn't exist, a notice of the form: "Copyright ©
[$date-of-document]
When space permits, inclusion of the full text of this
No right to create modifications or derivatives of W3C documents is
granted pursuant to this license. However, if additional requirements
(documented in the
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.
This section is a copy of the W3C Software Copyright Notice and License
and could be found at
Copyright © 1994-2002
http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:
The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
Any pre-existing intellectual property disclaimers. If none exist,
then a notice of the following form: "Copyright ©
[$date-of-software]
Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
This chapter describes the optional DOM Level 3 Validation feature. This module provides APIs to query information about the XML document and its associated grammar.
A DOM
application can use the hasFeature method of the
DOMImplementation interface to determine whether a given DOM supports these capabilities
or not. This module defines 1 feature string: "VAL-DOC" for document-editing interfaces.
This chapter focuses on the editing aspects used in the XML document-editing world and usage of such information.
In the October 9, 1997 DOM requirements document, the following appeared: "There will be a way to determine the presence of a DTD. There will be a way to add, remove, and change declarations in the underlying DTD (if available). There will be a way to test conformance of all or part of the given document against a DTD (if available)." In later discussions, the following was added, "There will be a way to query element/attribute (and maybe other) declarations in the underlying DTD (if available)," supplementing the primitive support for these in Level 1.
That work was deferred past Level 2, in the hope that XML Schemas would be addressed as well. Work was deferred on lowest common denominator general grammar APIs due to heightened interest in XML Schema- specific APIs; however, work on querying information on the grammar was only done for DOM Level 3.
Here are the following use cases and requirements that prompted the functionality in this document:
Use Cases:
DU1. For editing documents with an associated grammar, provide the guidance necessary so that valid documents can be modified and remain valid.
DU2. For editing documents with an associated grammar, provide the guidance necessary to transform an invalid document into a valid one.
Requirements:
DR1. Be able to determine if the document is well-formed, and if not, be given enough guidance to locate the error.
DR2. Be able to determine if the document is namespace well-formed, and if not, be given enough guidance to locate the error.
DR3. Be able to determine if the document is valid with respect to its associated grammar.
DR4. Be able to determine if specific modifications to a document would make it become invalid.
DR5. Retrieve information from all grammars. One example might be getting a list of all the defined element names for document editing purposes.
For Validation interfaces there should be no dependency on DOM Core.
The NodeEditVAL interface will not extend DOM Core. It is simply an object that expresses similar interfaces.
This section describes the "VAL-DOC" exceptions.
These operations may throw a ExceptionVAL as
described in their descriptions.
An integer indicating the type of error generated.
If the DocumentEditVAL related to the node
does not have any grammars and
wfValidityCheckLevel is set to
PARTIAL or
STRICT_VALIDITY_CHECK.
Raised if document is invalid.
This section contains "Document-editing" methods (includes Node, Element, Text and Document methods).
A DOM application may use the hasFeature(feature,
version) method of the DOMImplementation
interface with parameter values "VAL-DOC" and "3.0" (respectively)
to determine whether or not the Document-Editing interfaces are
supported by the implementation.
This interface extends the NodeEditVAL interface with additional methods for document editing.
An attribute specifying whether continuous checking for the
validity of the document is enforced or not.
Setting this to true will result in an exception being
thrown, i.e., VALIDATION_ERR, for documents
that are invalid at the time of the call. If the document
is invalid, then this attribute will remain false.
This attribute is false by default.
Validates the document against the grammar. If the document is mutated during validation, a warning will be issued. In addition, the validation cannot modify the document, e.g., for default attributes. This method makes use of the passed-in error handler.
VALIDATION_ERR: Raised if an error occurs when the document is being validated against the grammar.
NO_GRAMMAR_AVAILABLE: Raised if an error occurs when the grammar is not available for the document.
This interface is similar to the Node interfaces, with methods for guided document editing.
An integer indicating which type of validation this is.
Check for well-formedness of this node.
Check for namespace well-formedness includes WF_CHECK.
Checks for whether this node is NS_WF_CHECK.
Checks for strict validity of the node with respect to active grammar
which by definition includes NS_WF_CHECK.
Determines whether the Node::insertBefore operation
would make this document not partially valid
with respect to the currently active grammar.
Node to be inserted.
Reference Node.
true if no reason it can't be done; false if it
can't be done.
Has the same arguments as RemoveChild.
Node to be removed.
true if no reason it can't be done; false if it
can't be done.
Has the same arguments as ReplaceChild.
New Node.
Node to be replaced.
true if no reason it can't be done; false if it
can't be done.
Has the same arguments as AppendChild.
Node to be appended.
true if no reason it can't be done; false if it
can't be done.
Determines if the Node is valid relative to currently active grammar. It doesn't normalize before checking if the document is valid. To do so, one would need to explicitly call a normalize method.
Setting the deep flag on causes the isNodeValid method to check for the whole subtree of the
current node for validity. Setting it to false only checks the current node and
its immediate child nodes. The validateInDocument method on the DocumentVAL interface, however, checks to determine whether the entire document is valid.
Flag to tell at what level validity and well-formedness checking is done.
true if the node is valid/well-formed in the current context and check level
defined by wfValidityCheckLevel, false if not.
NO_GRAMMAR_AVAILABLE: Exception is raised if the DocumentEditVAL
related to this node does not have any grammar associated with it
and wfValidityCheckLevel is set
to PARTIAL or STRICT_VALIDITY_CHECK.
This interface extends the Element interface with additional methods for guided document editing. An
object implementing this interface must also implement NodeEditVAL interface.
The list of qualified element names defined in the grammar.
Determines element content type.
Constant for one of EMPTY_CONTENTTYPE,
ANY_CONTENTTYPE, MIXED_CONTENTTYPE, ELEMENTS_CONTENTTYPE.
Determines if the value for specified attribute can be set.
Name of attribute.
Value to be assigned to the attribute.
true if no reason it can't be done; false if it
can't be done.
Determines if an attribute node can be added with respect to the validity check level.
Node in which the attribute can possibly be set.
true if no reason it can't be done; false if it
can't be done.
Determines if the attribute with given namespace and qualified name
can be created if not already present in the attribute list of the element. If
the attribute with the same qualified name and namespaceURI is already present in the
element's attribute list, it tests whether the value of the attribute and its prefix can be set to
the new value. See DOM core setAttributeNS.
Qualified name of attribute.
Value to be assigned to the attribute.
namespaceURI of namespace.
true if no reason it can't be done; false if it
can't be done.
Verifies if an attribute by the given name can be removed.
Name of attribute.
true if no reason it can't be done; false if it
can't be done.
Verifies if an attribute by the given local name and namespace can be removed.
Local name of the attribute to be removed.
The namespace URI of the attribute to remove.
true if no reason it can't be done; false if it
can't be done.
Determines if an attribute node can be removed.
The Attr node to remove from the attribute list.
true if no reason it can't be done; false if it
can't be done.
Returns a NodeList containing the possible Element nodes that can appear as children of this type of element. These are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
List of possible children element types of this element.
Returns a NodeList containing the possible Element nodes that can appear as a parent of this type of element. These are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
List of possible parent element types of this element.
Returns a NodeList containing all the possible Attrs that can appear with this type of element. These are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
List of possible attributes of this element.
Determines if elemTypeName is defined in the currently active
grammar.
Name of element.
A boolean that is true if the element is defined, false
otherwise.
Determines if elemTypeName in this namespace is defined in the
currently active grammar.
Name of element.
namespaceURI of namespace.
Qualified name of namespace. This is for sub-elements.
A boolean that is true if the element is defined, false
otherwise.
This interface extends the NodeEditVAL interface with additional methods for document editing. An object
implementing this interface must also implement NodeEditVAL interface.
true if content only whitespace; false for non-whitespace.
Determines if data can be set.
Offset.
Argument to be set.
true if no reason it can't be done; false if it
can't be done.
Determines if data can be appended.
Data to be appended.
true if no reason it can't be done; false if it
can't be done.
Determines if data can be replaced.
Offset.
Replacement.
Argument to be set.
true if no reason it can't be done; false if it
can't be done.
Determines if data can be inserted.
Offset.
Argument to be set.
true if no reason it can't be done; false if it
can't be done.
Determines if data can be deleted.
Offset.
Number of 16-bit units to delete.
true if no reason it can't be done; false if it
can't be done.
Applications would like to be able to use functionality to guide construction and editing of documents, which falls into the document-editing world. Examples of this sort of guided editing already exist, and are becoming more common. The necessary queries can be phrased in several ways, the most useful of which may be a combination of "what does the DTD allow me to insert here" and "if I insert this here, will the document still be valid". The former is better suited to presentation to humans via a user interface, and when taken together with sub-tree validation may subsume the latter.
It has been proposed that in addition to asking questions about specific parts of the grammar, there should be a reasonable way to obtain a list of all the defined symbols of a given type (element, attribute, entity) independent of whether they're valid in a given location; that might be useful in building a list in a user-interface, which could then be updated to reflect which of these are relevant for the program's current state.
Remember that namespaces also weigh in on this issue, in the case of attributes, a "can-this-go-there" may prompt a namespace-well-formedness check and warn you if you're about to conflict with or overwrite another attribute with the same namespaceURI/localName but different prefix, or same nodeName but different namespaceURI.
We have to deal with the fact that "the shortest distance between two valid documents may be through an invalid one". Users may want to know several levels of detail (all the possible children, those which would be valid given what precedes this point, those which would be valid given both preceding and following siblings). Also, once XML Schemas introduce context sensitive validity, we may have to consider the effect of children as well as the individual node being inserted.
The most obvious use for a DTD or XML Schema or any grammar is to use it to validate a given XML document. This again falls into the document-editing world. The XML spec only discusses performing this test at the time the document is loaded into the "processor", which most of us have taken to mean that this check should be performed at parse time. But it is obviously desirable to be able to validate again a document -- or selected subtrees -- at other times. One such case would be validating an edited or newly constructed document before serializing it or otherwise passing it to other users. This issue also arises if the "internal subset" is altered -- or if the grammar changes.
In the past, the DOM has allowed users to create invalid documents, and
assumed the serializer would accept the task of detecting problems and
announcing/repairing them when the document was written out in XML syntax... or
that they would be checked for validity when read back in. We considered adding
validity checks to the DOM's existing editing operations to prevent creation of
invalid documents, but are currently inclined against this for several reasons.
First, it would impose a significant amount of computational overhead to the
DOM, which might be unnecessary in many situations, e.g., if the change is
occurring in a context where we know the result will be valid. Second, "the
shortest distance between two good documents may be through a bad document".
Preventing a document from becoming temporarily invalid may impose a
considerable amount of additional work on higher-level code and users Hence our
current plan is to continue to permit editing to produce invalid DOMs, but
provide operations which permit a user to check the validity of a node on
demand. If needed one can use continuousValidityChecking flag to ensure that the DOM remains valid during the editing
process.
Note that validation includes checking that ID attributes are unique, and that IDREFs point to IDs which actually exist.
XML defined the "well-formed" (
While the DOM inherently enforces some of XML's well-formedness conditions (proper nesting of elements, constraints on which children may be placed within each node), there are some checks that are not yet performed. These include:
Character restrictions for text content and attribute values. Some characters aren't permitted even when expressed as numeric character entities
The three-character sequence "]]>" in CDATASections.
The two-character sequence "--" in comments. (Which, be it noted, some XML validators don't currently remember to test...)
In addition, Namespaces introduce their own concepts of well-formedness. Specifically:
No two attributes on a single Element may have the same combination of namespaceURI and localName, even if their prefixes are different and hence they don't conflict under XML 1.0 rules.
NamespaceURIs must be legal URI syntax. (Note that once we have this code, it may be reusable for the URI "datatype" in document content; see discussion of datatypes.)
The mapping of namespace prefixes to their URIs must be declared and
consistent. That isn't required during normal DOM operation, since we perform
"early binding" and thereafter refer to nodes primarily via their namespaceURIs
and localName. But it does become an issue when we want to serialize the DOM to
XML syntax, and may be an issue if an application is assuming that all the
declarations are present and correct. This may imply that we should provide a namespaceNormalize operation, which would create the implied declarations and reconcile
conflicts in some reasonably standardized manner. This may be a major
undertaking, since some DOMs may be using the namespace to direct subclassing
of the nodes or similar special treatment; as with the existing normalize method, you may be left with a different-but-equivalent set of node
objects.
In the past, the DOM has allowed users to create documents which violate these rules, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax. We considered adding WF checks to the DOM's existing editing operations to prevent WF violations from arising, but are currently inclined against this for two reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations (for example, if the change is occurring in a context where we know the illegal characters have already been prevented from arising). Second, "the shortest distance between two good documents may be through a bad document" -- preventing a document from becoming temporarily ill-formed may impose a considerable amount of additional work on higher-level code and users. (Note possible issue for Serialization: In some applications, being able to save and reload marginally poorly-formed DOMs might be useful -- editor checkpoint files, for example.) Hence our current plan is to continue to permit editing to produce ill-formed DOMs, but provide operations which permit a user to check the well-formedness of a node on demand, and possibly provide some of the primitive (e.g., string-checking) functions directly.
This appendix contains the complete OMG IDL
The IDL files are also available as:
This appendix contains the complete Java
The Java files are also available as
This appendix contains the complete ECMAScript
Many people contributed to the DOM specifications (Level 1, 2 or 3), including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:
Andrew Watson (Object Management Group), Andy Heninger (IBM), Angel
Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and
Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill
Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson
(Microsoft), David Brownell (Sun), David Ezell (Hewlett Packard
Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB), Don
Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin
Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James
Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam
(X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods),
Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon
Ferraiolo (Adobe), Jonathan Marsh (Microsoft), Jonathan Robie
(Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad
Software Inc.), Lauren Wood (SoftQuad Software Inc.,
Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).
This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript bindings were all produced automatically.
Thanks to Joe English, author of
After DOM Level 1, we used
Thanks also to Jan Kärrman, author of
Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.
The base unit of a DOMString. This indicates that
indexing on a DOMString occurs in units of 16 bits.
This must not be misunderstood to mean that a DOMString
can store arbitrary 16-bit units. A DOMString is a
character string encoded in UTF-16; this means that the restrictions
of UTF-16 as well as the other relevant restrictions on character strings
must be maintained. A single character, for example in the form of a
numeric character reference, may correspond to one or two 16-bit units.
An
An
The process by which an
The process by which an
A
A [client] application is any software that uses the Document Object Model programming interfaces provided by the hosting implementation to accomplish useful work. Some examples of client applications are scripts within an HTML or XML document.
The
A
A
A model for a document that represents the document
after it has been manipulated in some way. For example, any
combination of any of the following transformations would
create a cooked model:
Expansion of internal text entities. Expansion of external entities. Model augmentation with style-specified generated
text. Execution of style-specified
reordering. Execution of scripts.
A
A
When new releases of specifications are released, some older
features may be marked as being
A
There is only one document element in a Document. This
element node is a child of the Document node. See
There is an ordering,
The term "DOM Level 0" refers to a mix (not formally specified) of HTML document functionalities offered by Netscape Navigator version 3.0 and Microsoft Internet Explorer version 3.0. In some cases, attributes or methods have been included for reasons of backward compatibility with "DOM Level 0".
The programming language defined by the ECMA-262 standard
Each document contains one or more elements, the
boundaries of which are either delimited by start-tags and
end-tags, or, for empty elements by an empty-element tag.
Each element has a type, identified by name, and may have a
set of attributes. Each attribute has a name and a value.
See
An event is the representation of some asynchronous occurrence
(such as a mouse click on the presentation of the element, or
the removal of child node from an element, or any of
unthinkably many other possibilities) that gets associated
with an
An
The object to which an
Two nodes are
Two nodes are NodeList objects, and the pairs of
equivalent attributes must in fact be deeply equivalent.
Two NodeList objects are
Two NamedNodeMap objects are
Two DocumentType nodes are NamedNodeMap
objects.
An information item is an abstract representation of some
component of an XML document. See the
Text or
CDataSection nodes that may be visited sequentially in
Element,
Comment, or ProcessingInstruction nodes.
A [hosting] implementation is a software module that provides an implementation of the DOM interfaces so that a client application can use them. Some examples of hosting implementations are browsers, editors and document repositories.
The HyperText Markup Language (
An Interface Definition Language (
Companies, organizations, and individuals that claim to support the Document Object Model as an API for their products.
In object-oriented programming, the ability to create new
classes (or interfaces) that contain all the methods and properties
of another class (or interface), plus additional methods and
properties. If class (or interface) D inherits from class (or
interface) B, then D is said to be
Also known as the
An
A programming
An object is
A
A
A
A
A
An
A
A node in a DOM tree is
A
A
The
Two nodes are
When string matching is required, it is to occur as
though the comparison was between 2 sequences of code points
from
A document is
The target node is the node representing the
The process by which an
An information item such as an
The description given to various information items (for example,
attribute values of various types, but not including the StringType
CDATA) after having been processed by the XML processor. The process
includes stripping leading and trailing white space, and replacing
multiple space characters by one. See the definition of
A document is
See initial structure model.
A document is
Extensible Markup Language (
See
An
For the latest version of any W3C specification please consult the list of
DOM Requirements for DOM Level 3in
OMG IDL Syntax and Semanticsdefined in