previous   next   contents   index

05 February 2003

1. Validation

Editors:
Ben Chang, Oracle
Joe Kesselman, IBM (until September 2001)
Rezaur Rahman, Intel Corporation (until July 2001)

Table of contents

1.1. Overview

This chapter describes the optional DOM Level 3 Validation feature. This module provides APIs to guide construction and editing of XML documents. Examples of such guided editing are queries of the nature that combine questions like "what does the grammar allow me to insert/delete here" and "if I insert/delete here, will the document still be valid."

Users may also want to know several 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 type, in order to help in editing and creating a XML document. Some of these queries would prompt checks and warn you if you'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. To some, 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 sub-tree on demand; and if needed can also require that the document or sub-tree remain valid during this editing process via the continuousValidityChecking flag.

A DOM application can use the hasFeature(feature, version) method of the DOMImplementation interface to determine with parameter values "VAL-DOC" and "3.0", respectively, whether or not these interfaces are supported by the implementation.

This chapter focuses on the editing aspects used in the XML document editing world and usage of such information.

1.2. Exceptions

This section describes the "VAL-DOC" exceptions.

Exception ExceptionVAL

The Validation operations may throw a ExceptionVAL as described in their descriptions.


IDL Definition
exception ExceptionVAL {
  unsigned short   code;
};
// ExceptionVALCode
const unsigned short      NO_GRAMMAR_AVAILABLE_ERR       = 71;

Definition group ExceptionVALCode

An integer indicating the type of error generated.

Defined Constants
NO_GRAMMAR_AVAILABLE_ERR
If the DocumentEditVAL related to the node does not have any grammar and wfValidityCheckLevel is set to PARTIAL or STRICT_VALIDITY_CHECK.

1.3. Document Editing Interfaces

This section contains "Document Editing" methods as described in the DocumentEditVAL, NodeEditVAL, ElementEditVAL, and CharacterEditVAL interfaces.

Interface DocumentEditVAL

This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement the Document interface.


IDL Definition
interface DocumentEditVAL : NodeEditVAL {
           attribute boolean         continuousValidityChecking;
  NameList           getDefinedElementTypes(in DOMString namespaceURI);
  void               validateDocument()
                                        raises(ExceptionVAL);
};

Attributes
continuousValidityChecking of type boolean
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. When set to true, the implementation if free to raise the VALIDATION_ERR exception on DOM operations that would make the document invalid with respect to "partial validity." If the document is invalid, then this attribute will remain false. This attribute is false by default.
Methods
getDefinedElementTypes
Returns list of all element node names belonging to the element's namespace. Given the names, nodes can be created from them; note that these are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace. For DTDs, this is NULL.
Return Value

NameList

List of all element node names belonging to the element's namespace.
No Exceptions
validateDocument
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, as described in [DOM Level 3 Core] interface.
Exceptions

ExceptionVAL

NO_GRAMMAR_AVAILABLE_ERR: Raised if an error occurs when the grammar is not available for the document.
No Parameters
No Return Value
Interface NodeEditVAL

This interface is similar to the [DOM Level 3 Core] Node interfaces, with methods for guided document editing.


IDL Definition
interface NodeEditVAL {

  // CheckTypeVAL
  const unsigned short      WF_CHECK                       = 1;
  const unsigned short      NS_WF_CHECK                    = 2;
  const unsigned short      PARTIAL_VALIDITY_CHECK         = 3;
  const unsigned short      STRICT_VALIDITY_CHECK          = 4;

  readonly attribute DOMString       defaultValue;
  readonly attribute DOMStringList   enumeratedValues;
  boolean            canInsertBefore(in Node newChild, 
                                     in Node refChild);
  boolean            canRemoveChild(in Node oldChild);
  boolean            canReplaceChild(in Node newChild, 
                                     in Node oldChild);
  boolean            canAppendChild(in Node newChild);
  boolean            isNodeValid(in boolean deep, 
                                 in unsigned short wFValidityCheckLevel)
                                        raises(ExceptionVAL);
};

Definition group CheckTypeVAL

An integer indicating which type of validation this is. Stricter validation for certain XML dialects can be done by extending the NodeEditVAL interface adding a new CheckTypeVAL constant(s).

Defined Constants
NS_WF_CHECK
Check for namespace well-formedness includes WF_CHECK.
PARTIAL_VALIDITY_CHECK
Checks for whether this node is partially valid. It includes NS_WF_CHECK.
STRICT_VALIDITY_CHECK
Checks for strict validity of the node with respect to the grammar which by definition includes NS_WF_CHECK.
WF_CHECK
Check for well-formedness of this node.
Attributes
defaultValue of type DOMString, readonly
The default value specified in an attribute or an element declaration.
enumeratedValues of type DOMStringList, readonly
A DOMStringList of distinct values for an attribute or an element declaration.
Methods
canAppendChild
Has the same arguments as Node.appendChild. Determines whether the Node.replaceChild operation would make this document not partially valid with respect to the grammar.
Parameters
newChild of type Node
Node to be appended.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canInsertBefore
Determines whether the Node.insertBefore operation would make this document not partially valid with respect to the grammar.
Parameters
newChild of type Node
Node to be inserted.
refChild of type Node
Reference Node.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canRemoveChild
Has the same arguments as Node.removeChild. Determines whether the Node.removeChild operation would make this document not partially valid with respect to the grammar.
Parameters
oldChild of type Node
Node to be removed.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canReplaceChild
Has the same arguments as Node.replaceChild. Determines whether the Node.replaceChild operation would make this document not partially valid with respect to the grammar.
Parameters
newChild of type Node
New Node.
oldChild of type Node
Node to be replaced.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
isNodeValid
Determines if the Node is valid relative to the grammar. It doesn't normalize before checking if the document is valid. To do so, one would need to explicitly call a normalize method.
Parameters
deep of type boolean
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 validateDocument method on the DocumentVAL interface, however, checks to determine whether the entire document is valid.
wFValidityCheckLevel of type unsigned short
Flag to tell at what level validity and well-formedness checking is done.
Return Value

boolean

true if the node is valid/well-formed in the grammar and check level defined by wfValidityCheckLevel, false if not.
Exceptions

ExceptionVAL

NO_GRAMMAR_AVAILABLE_ERR: 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.
Interface ElementEditVAL

This interface extends the NodeEditVAL interface with additional methods for guided document editing. An object implementing this interface must also implement Element interface.


IDL Definition
interface ElementEditVAL : NodeEditVAL {
  readonly attribute NameList        allowedChildren;
  readonly attribute NameList        allowedParents;
  readonly attribute NameList        allowedNextSiblings;
  readonly attribute NameList        allowedPreviousSiblings;
  readonly attribute NameList        allowedAttributes;
  readonly attribute NameList        requiredAttributes;
  unsigned short     contentType();
  boolean            canSetAttribute(in DOMString attrname, 
                                     in DOMString attrval);
  boolean            canSetAttributeNode(in Attr attrNode);
  boolean            canSetAttributeNS(in DOMString namespaceURI, 
                                       in DOMString qualifiedName, 
                                       in DOMString value);
  boolean            canRemoveAttribute(in DOMString attrname);
  boolean            canRemoveAttributeNS(in DOMString namespaceURI, 
                                          in DOMString localName);
  boolean            canRemoveAttributeNode(in Node attrNode);
  boolean            isElementDefined(in DOMString name);
  boolean            isElementDefinedNS(in DOMString namespaceURI, 
                                        in DOMString name);
};

Attributes
allowedAttributes of type NameList, readonly
A NameList of possible Attr nodes that can appear with this type of element. Given the names, nodes can be created from them; note that these are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
allowedChildren of type NameList, readonly
A NameList of possible Element nodes that can appear as children of this type of element. Note that if no context of this element exists, then this is NULL; it is an empty list if the element is not in the document tree. Given the names, nodes can be created from them; note that these are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
allowedNextSiblings of type NameList, readonly
A NameList of possible sibling Element nodes that can appear after this element.
allowedParents of type NameList, readonly
A NameList of possible Element nodes that can appear as a parent of this type of element. Note that if no context of this element exists, for example, the parent element of this element, then this is NULL; it is an empty list if the element is not in the document tree. Given the names, nodes can be created from them; note that these are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
allowedPreviousSiblings of type NameList, readonly
A NameList of possible sibling Element nodes that can appear before this element.
requiredAttributes of type NameList, readonly
A NameList of required Attr nodes that must appear with this type of element. Given the names, nodes can be created from them; note that these are not nodes from the instance document, but rather are new nodes that could be inserted in the document.
Methods
canRemoveAttribute
Verifies if an attribute by the given name can be removed.
Parameters
attrname of type DOMString
Name of attribute.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canRemoveAttributeNS
Verifies if an attribute by the given local name and namespace can be removed.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute to remove.
localName of type DOMString
Local name of the attribute to be removed.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canRemoveAttributeNode
Determines if an attribute node can be removed.
Parameters
attrNode of type Node
The Attr node to remove from the attribute list.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canSetAttribute
Determines if the value for specified attribute can be set.
Parameters
attrname of type DOMString
Name of attribute.
attrval of type DOMString
Value to be assigned to the attribute.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canSetAttributeNS
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.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace.
qualifiedName of type DOMString
Qualified name of attribute.
value of type DOMString
Value to be assigned to the attribute.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canSetAttributeNode
Determines if an attribute node can be added with respect to the validity check level.
Parameters
attrNode of type Attr
Node in which the attribute can possibly be set.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
contentType
Determines element content type.
Return Value

unsigned short

Constant for one of EMPTY_CONTENTTYPE - content type of an element which has neither child elements nor character data, ANY_CONTENTTYPE - content type of an element which can contain zero or more child elements as well as character data, MIXED_CONTENTTYPE - content type of an element which contains character data optionally interspersed with child elements, ELEMENTS_CONTENTTYPE - content type of an element which contains only child elements optionally separated by whitespace, SIMPLE_CONTENTTYPE - content type of an element which contains character data with attributes.
No Parameters
No Exceptions
isElementDefined
Determines if name is defined in the grammar.
Parameters
name of type DOMString
Name of element.
Return Value

boolean

A boolean that is true if the element is defined, false otherwise.
No Exceptions
isElementDefinedNS
Determines if name in this namespace is defined in the current context.
Parameters
namespaceURI of type DOMString
namespaceURI of namespace.
name of type DOMString
Name of element.
Return Value

boolean

A boolean that is true if the element is defined, false otherwise.
No Exceptions
Interface CharacterDataEditVAL

This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement CharacterData interface.


IDL Definition
interface CharacterDataEditVAL : NodeEditVAL {
  readonly attribute boolean         isWhitespaceOnly;
  boolean            canSetData(in DOMString arg);
  boolean            canAppendData(in DOMString arg);
  boolean            canReplaceData(in unsigned long offset, 
                                    in unsigned long count, 
                                    in DOMString arg);
  boolean            canInsertData(in unsigned long offset, 
                                   in DOMString arg);
  boolean            canDeleteData(in unsigned long offset, 
                                   in unsigned long count);
};

Attributes
isWhitespaceOnly of type boolean, readonly
true if content only whitespace; false for non-whitespace.
Methods
canAppendData
Determines if data can be appended.
Parameters
arg of type DOMString
Data to be appended.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canDeleteData
Determines if data can be deleted.
Parameters
offset of type unsigned long
Offset.
count of type unsigned long
Number of 16-bit units to delete.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canInsertData
Determines if data can be inserted.
Parameters
offset of type unsigned long
Offset.
arg of type DOMString
Argument to be set.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canReplaceData
Determines if data can be replaced.
Parameters
offset of type unsigned long
Offset.
count of type unsigned long
Replacement.
arg of type DOMString
Argument to be set.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions
canSetData
Determines if data can be set.
Parameters
arg of type DOMString
Argument to be set.
Return Value

boolean

true if no reason it can't be done; false if it can't be done.
No Exceptions

1.4. Range-related Document-Editing Interfaces

This section contains Range-related "Document-editing" methods.

Interface RangeVAL

This interface extends the Range interface with additional methods for guided document editing.


IDL Definition
interface RangeVAL : Range {
  boolean            canSurroundContents(in Node node1, 
                                         in Node node2, 
                                         in Node b);
  NameList           getAlternativeElements(in Node refChild);
};

Methods
canSurroundContents
Determines if a passed-in node can be "surrounded" by two other nodes. For example, this convenience method can: 1) get all children of "x", 2) get all possible parents of "y", and then 3) check if the passed-in node "b" is present in both sets.
Parameters
node1 of type Node
First node to "surround" passed-in node "b".
node2 of type Node
Second node to "surround" passed-in node "b".
b of type Node
Node to be "surrounded" by.
Return Value

boolean

true if it is; false if it is not.
No Exceptions
getAlternativeElements
Returns a list of names of alternative elements, given a reference child as a parameter.
Parameters
refChild of type Node
Reference child.
Return Value

NameList

A list of names of alternative elements.
No Exceptions
previous   next   contents   index