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

exception ExceptionVAL {
  unsigned short   code;
};
// ExceptionVALCode
const unsigned short      NO_SCHEMA_AVAILABLE_ERR        = 71;

Definition group ExceptionVALCode

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

interface DocumentEditVAL : NodeEditVAL {
           attribute boolean         continuousValidityChecking;
                                        // raises(DOMException, 
                                        //        ExceptionVAL, 
                                        //        DOMException) on setting

  readonly attribute DOMConfiguration domConfig;
  NameList           getDefinedElements(in DOMString namespaceURI);
  unsigned short     validateDocument();
};

Attributes

continuousValidityChecking of type boolean

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.

Exceptions on setting

`DOMException`	NOT_SUPPORTED_ERR: Raised if the implementation does not support setting this attribute to `true`.
`ExceptionVAL`	NO_SCHEMA_AVAILABLE_ERR: Raised if this attribute is set to `true` and a schema is unavailable.
`DOMException`	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`.

domConfig of type DOMConfiguration, readonly

This allows the setting of the error handler, as described in the [DOM Level 3 Core] DOMConfiguration interface. An object implementing this DocumentEditVAL interface and the [DOM Level 3 Core] Document interface, which also has a domConfig attribute, needs to only implement this attribute once.

Methods

getDefinedElements

Returns list of all element information item names of global declaration, belonging to the specified namespace.

Parameters

namespaceURI of type DOMString: namespaceURI of namespace. For DTDs, this is null.

Return Value

NameList

List of all element information item names belonging to the specified namespace or null if no schema is available.

No Exceptions

validateDocument

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 [DOM Level 3 Core] DOMConfiguration interface, with all errors being SEVERITY_ERROR as defined in the DOMError interface.

Return Value

unsigned short

1. Validation

Table of contents

1.1 Overview

1.2 Exceptions

1.3 Document Editing Interfaces