This specification defines the Document Object Model Validation Level 3, a platform- and language-neutral interface. This module provides the guidance to programs and scripts to dynamically update the content and the structure of documents while ensuring that the document remains valid, or to ensure that the document becomes valid.
This is the
Comments on this document should be sent to the public mailing
list
An
This is a stable document and has been endorsed by the W3C
Membership and the participants of the DOM working group. The
English version of this specification is the only normative
version. Information about
The
This document has been produced as part of the
Patent disclosures relevant to this specification may be found
on the Working Group's
Created in electronic form.
$Revision: 1.7 $
Copyright © 2004
This document is published under the
This section is a copy of the W3C® Document
Notice and License and could be found at
Copyright © 2004
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
Public documents on the W3C site are provided by the copyright holders under the following license. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to 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 (hypertext is preferred, but a
textual representation is permitted) 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 © 2004
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This work (and included software, documentation such as READMEs, 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 copy, modify, and distribute 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:
The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
Any pre-existing intellectual property disclaimers, notices,
or terms and conditions. If none exist, the
Notice of any changes or modifications to the 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 section is a copy of the W3C® Short Software
Notice and could be found at
Copyright © 2004
Copyright © [$date-of-software]
[1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This chapter describes the optional DOM Level 3 Validation feature. This module provides Application Programming Interfaces (APIs) to guide construction and editing of XML documents. Examples of such guided editing are queries like those that combine questions like "what does the schema allow me to insert/delete here" and "if I insert/delete here, will the document still be valid."
To aid users in the editing and creation of XML documents, other queries may expose different levels of details, e.g., all the possible children, those which would be valid given what precedes this point, lists of defined symbols of a given kind. Some of these queries would prompt checks and warn users if they're about to conflict with or overwrite such data.
Finally, users would like to validate an edited or newly
constructed document before serializing it or passing it to other
users. They may edit, come up with an invalid document,
then edit again to result in a valid document. During this process,
these APIs can allow the user to check the validity of the document
or subtree on demand. If necessary, these APIs can also require that the
document or subtree remain valid during this editing process via
the DocumentEditVal.continuousValidityChecking flag.
A DOM application can use the hasFeature(feature, version)
method of the DOMImplementation interface to determine
with parameter values "Validation" and "3.0",
respectively, whether or not these interfaces are
supported by the implementation. This implementation is dependent
on DOMConfiguration interface.
This chapter focuses on the editing aspects used in the XML document editing world and usage of such information. The appendix describes in detail all the possible outcomes of the validation operations on the different node types.
This section describes the "VAL-DOC-EDIT" exceptions.
Some Validation operations may throw an ExceptionVAL as
described in their descriptions.
An integer indicating the type of error generated.
This error occurs when the operation cannot complete due to an
unavailable
This section contains "Document Editing" methods as described in the
DocumentEditVAL, NodeEditVAL,
ElementEditVAL, and CharacterDataEditVAL
interfaces. References to new DOMStringList and NameList also
exist. With the latter interface, if the schema is a DTD, the
element information item names are simply local names; if the schema
is a W3C XML schema, the names are qualified names, which may contain
namespace prefixes.
This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement the Document interface.
An attribute specifying whether the validity of the document
is continuously enforced. When the attribute is set to
true, the implementation may raise certain
exceptions, depending on the situation (see the following).
This attribute is false by default.
NOT_SUPPORTED_ERR: Raised if the implementation
does not support setting this attribute to
true.
NO_SCHEMA_AVAILABLE_ERR: Raised if this
attribute is set to true
and a schema is unavailable.
VALIDATION_ERR: Raised if an operation makes
this document not compliant with the
VAL_INCOMPLETE validity type
or the document is invalid, and this
attribute is set to true.
This allows the setting of the error handler, as described in the
DOMConfiguration interface.
An object implementing this DocumentEditVAL interface
and the Document interface, which also has a domConfig attribute, needs to only implement this attribute once.
Returns list of all element information item names of
namespaceURI of namespace. For DTDs,
this is null.
List of all element information item names belonging to the
specified namespace or null if no schema is
available.
Validates the document against the schema, e.g., a DTD or an
W3C XML schema or another. Any attempt to modify any part of the
document while validating results in implementation-dependent
behavior. In addition, the validation operation itself cannot
modify the document, e.g., for default attributes.
This method makes use of the error handler, as
described in the DOMConfiguration interface, with all errors
being SEVERITY_ERROR as defined in the
DOMError interface.
A
This interface is similar to the Node interface, with methods for guided document editing.
An integer indicating the validation type.
Other specifications can define stricter
validation types/constants by extending
the NodeEditVAL interface.
Check if the node is
Check if the node is
Check if the node's immediate children are those
expected by the content model. This node's trailing
required children could be missing.
It includes VAL_NS_WF.
Check if the node's entire subtree are those expected
by the content model. It includes VAL_NS_WF.
An integer indicating the validation state, or whether the operation can or cannot be done.
True if the node is valid with regards to the operation, or if the operation can be done.
False if the node is invalid with regards to the operation, or if the operation cannot be done.
The validity of the node is unknown.
The default value specified in an attribute or an element declaration or null if unspecified. If the schema is a W3C XML schema,
this is the canonical lexical representation of the default value.
A DOMStringList, as
described in null
if unspecified. If the schema is a W3C XML schema, this is a
list of strings which are lexical representations corresponding
to the values in the [value] property of the enumeration
component for the type of the attribute or element. It is
recommended that the canonical lexical representations of the
values be used.
Determines whether the Node.insertBefore operation
would make this document not compliant with the VAL_INCOMPLETE
validity type.
Node to be inserted.
Reference Node.
A
Determines whether the Node.removeChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type.
Node to be removed.
A
Determines whether the Node.replaceChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type.
New Node.
Node to be replaced.
A
Determines whether the Node.appendChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type.
Node to be appended.
A
Determines if the node is valid relative to the
valType. This operation
doesn't normalize before checking if it is valid.
To do so, one would need to explicitly call a normalize
method. The difference between this method and the
Flag to indicate the
A
This interface extends the NodeEditVAL interface
with additional methods for guided document editing. An
object implementing this interface must also implement the
Element interface.
This interface also has attributes that are a
NameList of elements or attributes which can
appear in the specified context. Some schema languages,
i.e.,
To expose wildcards, the NameList returns the values
that represent the
{namespaceURI, name}
is {null, ##any} if
{namespaceURI, name}
is {namespace_a, ##other} if
{namespaceURI, name}
is {null, ##other} if
Pairs of {namespaceURI, name} with values
{a_namespaceURI | null, null} if
An integer indicating the content type of an element.
The content model does not allow any
empty content type; and if the schema is a DTD,
this corresponds to the EMPTY content model.
The content model contains unordered child information
item(s), i.e.,
element, processing instruction, unexpanded entity reference,
character, and comment information items as defined in the
ANY content model.
The content model contains a sequence of ordered
mixed
content type.
The content model contains a sequence of
element content content model; and if the schema
is a W3C XML schema, this is the
element-only content type.
The content model contains
VAL_SIMPLE_CONTENTTYPE
if the type of the element is a simple type definition,
or the type of the element is a complexType whose
{content type} is a simple type definition.
A NameList, as described in null
if this element has no context or schema.
Duplicate pairs of {namespaceURI, name} are eliminated.
A NameList, as described in null
if this element has no context or schema.
Duplicate pairs of {namespaceURI, name} are eliminated.
A NameList, as described in null
if this element has no context or schema.
A NameList, as described in null
if this element has no context or schema.
Duplicate pairs of {namespaceURI, name} are eliminated.
A NameList, as described in null
if this element has no context or schema.
A NameList, as described in null
if this element has no context or schema.
Duplicate pairs of {namespaceURI, name} are eliminated.
A NameList, as described in null
if this element has no context or schema.
The content type of an element as defined
Determines if the text content of this node and its descendants can be set to the string passed in.
Possible text content string.
A
Determines if the value for specified attribute can be set.
Name of attribute.
Value to be assigned to the attribute.
A
Determines if an attribute node can be added.
Node in which the attribute can possibly be set.
A
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.
namespaceURI of namespace.
Qualified name of attribute.
Value to be assigned to the attribute.
A
Verifies if an attribute by the given name can be removed.
Name of attribute.
A
Verifies if an attribute by the given local name and namespace can be removed.
The namespace URI of the attribute to remove.
Local name of the attribute to be removed.
A
Determines if an attribute node can be removed.
The Attr node to remove from the attribute list.
A
Determines if name is defined in the schema.
This only applies to
Name of element.
A
Determines if name in this namespace is defined in the
current context. Thus not only does this apply to
namespaceURI of namespace.
Name of element.
A
This interface extends the NodeEditVAL interface with additional methods for document editing. An object
implementing this interface must also implement CharacterData interface.
When validating CharacterData nodes, the
NodeEditVAL.nodeValidity
operation to operate on such nodes, the operation considers all the text and not just some of it.
Determines if character data is only whitespace.
A
Determines if character data can be set.
Argument to be set.
A
Determines if character data can be appended.
Data to be appended.
A
Determines if character data can be replaced.
Offset.
Replacement.
Argument to be set.
A
INDEX_SIZE_ERR: 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.
Determines if character data can be inserted.
Offset.
Argument to be set.
A
INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data.
Determines if character data can be deleted.
Offset.
Number of 16-bit units to delete.
A
INDEX_SIZE_ERR: 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 following table describes all possible validation outcomes of
the NodeEditVAL.nodeValidity(valType) method.
| Validation Type | Validity outcome | ||
|---|---|---|---|
| VAL_TRUE | VAL_FALSE | VAL_UNKNOWN | |
VAL_WF |
The node is well-formed. | The node is not well-formed. | Not applicable. |
VAL_NS_WF |
The node is well-formed. Processor must take into account all the in-scope namespace declarations. | The node is not namespace well-formed. Processor must take into account all the in-scope namespace declarations. | Not applicable. |
VAL_NS_WF |
The node is well-formed. Processor must take into account all namespace declarations in scope. | The node is not namespace well-formed. Processor must take into account all the in-scope namespace declarations. | Not applicable. |
VAL_SCHEMA |
The node is valid: it complies with all the constraints expressed in the schema. | The node fails to comply to all the constraints expressed in the schema. | If the schema is an XML Schema, PSVI [validity] property value is unknown. |
VAL_INCOMPLETE |
The node is valid: it complies with the
VAL_INCOMPLETE definition.
|
The node is invalid with regard to the
VAL_INCOMPLETE definition.
|
If the schema is an XML Schema, PSVI [validity] property value is unknown. |
The following table describes the outcome of the
DocumentEditVAL.validateDocument() and
NodeEditVAL.nodeValidity(valType) methods, with the
latter called on the DocumentEditVAL node with
validationType NodeEditVAL.VAL_SCHEMA.
| Methods | Validity outcome | ||
|---|---|---|---|
| VAL_TRUE | VAL_FALSE | VAL_UNKNOWN | |
validateDocument and nodeValidity,
called on the Document node with validationType
VAL_SCHEMA.
|
If the schema is a DTD, then the document documentElement: PSVI [validity] |
Fails to satisfy the constraints defined. |
If the schema is an XML Schema, then schema is not found or
the declaration for the |
The following table describes outcomes for the
NodeEditVAL.nodeValidity(valType) method called with
the validationType NodeEditVAL.VAL_SCHEMA:
| Node types | Validity outcome | ||
|---|---|---|---|
| VAL_TRUE | VAL_FALSE | VAL_UNKNOWN | |
Element
|
If the schema is a DTD, then |
Fails to satisfy the constraints defined. |
If the schema is an XML Schema, then PSVI [validity]
|
Attr
|
If the schema is a DTD, then all validity constraints
defined in section 3.3.1, " |
Fails to satisfy the constraints defined. |
If the schema is an XML Schema, then PSVI [validity]
|
Text |
The node is well-formed. | The node is not well-formed. | If no parent node is found. |
CDATASection |
The node is well-formed. | The node is not well-formed. | If no parent node is found. |
ProcessingInstruction |
The node is well-formed. | The node is not well-formed. | If no parent node is found. |
Comment |
The node is well-formed. | The node is not well-formed. | If no parent node is found. |
EntityReference |
Entity is
|
Entity is not
|
Not applicable. |
Entity |
Implementation-specific. | Implementation-specific. | Implementation-specific. |
Notation |
Implementation-specific. | Implementation-specific. | Implementation-specific. |
DocumentType |
Implementation-specific. | Implementation-specific. | Implementation-specific. |
DocumentFragment |
Not applicable. | Not applicable. | Not applicable. |
The table below describes validation outcomes from can*
validation operations, such as
NodeEditVAL.canRemoveChild(), or
ElementEditVAL.canSetAttributeNS,
CharacterDataEditVAL.canAppendData(). All these operations
attempt to validate with validityType
NodeEditVAL.VAL_INCOMPLETE.
| VAL_TRUE | VAL_FALSE | VAL_UNKNOWN |
|---|---|---|
If the associated operation is performed, then the node would
be valid with regards to the VAL_INCOMPLETE
definition or if there is no schema found.
|
If the associated operation is performed, then the node would
be invalid with regards to the VAL_INCOMPLETE
definition.
|
Not applicable. |
Note: If the document includes more than one type of DOMConfiguration "NodeEditVAL.VAL_INCOMPLETE and
NodeEditVAL.VAL_SCHEMA is implementation-specific.
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 participants of the DOM Working Group and the DOM Interest Group. We especially thank the following:
Andrew Clover, 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 and invited expert), 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!).
Special thanks to the
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
Some 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
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 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
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 can be visited
sequentially in Element,
Comment, or ProcessingInstruction
nodes.
A
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
A node is a
An
A
A node in a DOM tree is
A
A
The
A
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 node is a
Extensible Markup Language (
See
An
For the latest version of any W3C specification please consult the list of