1. Validation

1.1 Overview

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 [DOM Level 2 Core] and the [DOM Level 3 Core] 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.

1.2 Exceptions

This section describes the "VAL-DOC-EDIT" exceptions. Exception ExceptionVAL

Some Validation operations may throw an ExceptionVAL as described in their descriptions.
IDL Definition

An integer indicating the type of error generated. Defined Constants NO_SCHEMA_AVAILABLE_ERR This error occurs when the operation cannot complete due to an unavailable schema.

1.3 Document Editing Interfaces

This section contains "Document Editing" methods as described in the DocumentEditVAL, NodeEditVAL, ElementEditVAL, and CharacterDataEditVAL interfaces. References to new [DOM Level 3 Core] interfaces such as 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. 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

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

An integer indicating the validation type. Other specifications can define stricter validation types/constants by extending the NodeEditVAL interface. Defined Constants VAL_INCOMPLETE 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. VAL_NS_WF Check if the node is namespace well-formed. VAL_SCHEMA Check if the node's entire subtree are those expected by the content model. It includes VAL_NS_WF. VAL_WF Check if the node is well-formed. Definition group validationState

An integer indicating the validation state, or whether the operation can or cannot be done. Defined Constants VAL_FALSE False if the node is invalid with regards to the operation, or if the operation cannot be done. VAL_TRUE True if the node is valid with regards to the operation, or if the operation can be done. VAL_UNKNOWN The validity of the node is unknown. Attributes defaultValue of type DOMString, readonly 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.
enumeratedValues of type DOMStringList, readonly A DOMStringList, as described in [DOM Level 3 Core], of distinct values for an attribute or an element declaration or 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.
Methods canAppendChild

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., W3C XML schema, define wildcards which provide for validation of attribute and element information items dependent on their namespace names but independent of their local names.

To expose wildcards, the NameList returns the values that represent the namespace constraint:

• {namespaceURI, name} is {null, ##any} if any;
• {namespaceURI, name} is {namespace_a, ##other} if not and a namespace name (namespace_a);
• {namespaceURI, name} is {null, ##other} if not and absent;
• Pairs of {namespaceURI, name} with values {a_namespaceURI | null, null} if a set whose members are either namespace names or absent.

An integer indicating the content type of an element. Defined Constants VAL_ANY_CONTENTTYPE 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 XML Information Set. If the schema is a DTD, this corresponds to the ANY content model. VAL_ELEMENTS_CONTENTTYPE The content model contains a sequence of element information items optionally separated by whitespace. If the schema is a DTD, this is the element content content model; and if the schema is a W3C XML schema, this is the element-only content type. VAL_EMPTY_CONTENTTYPE The content model does not allow any content. If the schema is a W3C XML schema, this corresponds to the empty content type; and if the schema is a DTD, this corresponds to the EMPTY content model. VAL_MIXED_CONTENTTYPE The content model contains a sequence of ordered element information items optionally interspersed with character data. If the schema is a W3C XML schema, this corresponds to the mixed content type. VAL_SIMPLE_CONTENTTYPE The content model contains character information items. If the schema is a W3C XML schema, then the element has a content type of 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. Attributes allowedAttributes of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all possible attribute information items or wildcards that can appear as attributes of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedChildren of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all possible element information items or wildcards that can appear as children of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedFirstChildren of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all possible element information items or wildcards that can appear as a first child of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedNextSiblings of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all element information items or wildcards that can be inserted as a next sibling of this element, or null if this element has no context or schema. Duplicate pairs of {namespaceURI, name} are eliminated.
allowedParents of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all possible element information items that can appear as a parent this element, or null if this element has no context or schema.
allowedPreviousSiblings of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of all element information items or wildcards that can be inserted as a previous sibling of this element, or null if this element has no context or schema.
contentType of type unsigned short, readonly The content type of an element as defined above.
requiredAttributes of type NameList, readonly A NameList, as described in [DOM Level 3 Core], of required attribute information items that must appear on this element, or null if this element has no context or schema.
Methods canRemoveAttribute

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 must find the nearest parent node in order to do this; if no parent node is found, VAL_UNKNOWN is returned. In addition, when VAL_INCOMPLETE is passed in as an argument to the NodeEditVAL.nodeValidity operation to operate on such nodes, the operation considers all the text and not just some of it.
IDL Definition