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.
This section describes the "VAL-DOC-EDIT" exceptions.
Some Validation operations may throw an ExceptionVAL as
described in their descriptions.
exception ExceptionVAL { unsigned short code; }; // ExceptionVALCode const unsigned short NO_SCHEMA_AVAILABLE_ERR = 71;
An integer indicating the type of error generated.
NO_SCHEMA_AVAILABLE_ERRThis 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.
This interface extends the NodeEditVAL interface with additional methods for document editing. An object implementing this interface must also implement the Document interface.
interface DocumentEditVAL : NodeEditVAL { attribute boolean continuousValidityChecking; // raises(DOMException, // ExceptionVAL, // DOMException) on setting readonly attribute DOMConfiguration domConfig; NameList getDefinedElements(in DOMString namespaceURI); unsigned short validateDocument(); };
continuousValidityChecking of type booleantrue, 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
|
|
NO_SCHEMA_AVAILABLE_ERR: Raised if this
attribute is set to | |
|
VALIDATION_ERR: Raised if an operation makes
this document not compliant with the
|
domConfig of type DOMConfiguration, readonlyDOMConfiguration 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.
getDefinedElementsnamespaceURI of type
DOMStringnamespaceURI of namespace. For DTDs,
this is null.
|
List of all element information item names belonging to the
specified namespace or |
validateDocumentDOMConfiguration interface, with all errors
being SEVERITY_ERROR as defined in the
DOMError interface.
|
A validation state constant. |
This interface is similar to the [DOM Level 3 Core] Node interface, with methods for guided document editing.
interface NodeEditVAL { // validationType const unsigned short VAL_WF = 1; const unsigned short VAL_NS_WF = 2; const unsigned short VAL_INCOMPLETE = 3; const unsigned short VAL_SCHEMA = 4; // validationState const unsigned short VAL_TRUE = 5; const unsigned short VAL_FALSE = 6; const unsigned short VAL_UNKNOWN = 7; readonly attribute DOMString defaultValue; readonly attribute DOMStringList enumeratedValues; unsigned short canInsertBefore(in Node newChild, in Node refChild); unsigned short canRemoveChild(in Node oldChild); unsigned short canReplaceChild(in Node newChild, in Node oldChild); unsigned short canAppendChild(in Node newChild); unsigned short nodeValidity(in unsigned short valType); };
An integer indicating the validation type.
Other specifications can define stricter
validation types/constants by extending
the NodeEditVAL interface.
VAL_INCOMPLETEVAL_NS_WF.
VAL_NS_WFVAL_SCHEMAVAL_NS_WF.
VAL_WFAn integer indicating the validation state, or whether the operation can or cannot be done.
VAL_FALSEVAL_TRUEVAL_UNKNOWNdefaultValue of type DOMString, readonlynull if unspecified. If the schema is a W3C XML schema,
this is the canonical lexical representation of the default value.
enumeratedValues of type DOMStringList, readonlyDOMStringList, 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.
canAppendChildNode.appendChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type. newChild of type
NodeNode to be appended.
|
A validation state constant. |
canInsertBeforeNode.insertBefore operation
would make this document not compliant with the VAL_INCOMPLETE
validity type. newChild of type
NodeNode to be inserted.refChild of type
NodeNode.
|
A validation state constant. |
canRemoveChildNode.removeChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type. oldChild of type
NodeNode to be removed.
|
A validation state constant. |
canReplaceChildNode.replaceChild operation
would make this document not compliant with the VAL_INCOMPLETE
validity type. newChild of type
NodeNode.oldChild of type
NodeNode to be replaced.
|
A validation state constant. |
nodeValidityvalType. 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
DocumentEditVAL.validateDocument method
is that the latter method only checks to
determine whether the entire document is valid.
valType of type
unsigned short
|
A validation state constant. |
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;
{namespaceURI, name} with values
{a_namespaceURI | null, null} if
a set whose members are either namespace
names or absent.
interface ElementEditVAL : NodeEditVAL { // ContentTypeVAL const unsigned short VAL_EMPTY_CONTENTTYPE = 1; const unsigned short VAL_ANY_CONTENTTYPE = 2; const unsigned short VAL_MIXED_CONTENTTYPE = 3; const unsigned short VAL_ELEMENTS_CONTENTTYPE = 4; const unsigned short VAL_SIMPLE_CONTENTTYPE = 5; readonly attribute NameList allowedChildren; readonly attribute NameList allowedFirstChildren; readonly attribute NameList allowedParents; readonly attribute NameList allowedNextSiblings; readonly attribute NameList allowedPreviousSiblings; readonly attribute NameList allowedAttributes; readonly attribute NameList requiredAttributes; readonly attribute unsigned short contentType; unsigned short canSetTextContent(in DOMString possibleTextContent); unsigned short canSetAttribute(in DOMString attrname, in DOMString attrval); unsigned short canSetAttributeNode(in Attr attrNode); unsigned short canSetAttributeNS(in DOMString namespaceURI, in DOMString qualifiedName, in DOMString value); unsigned short canRemoveAttribute(in DOMString attrname); unsigned short canRemoveAttributeNS(in DOMString namespaceURI, in DOMString localName); unsigned short canRemoveAttributeNode(in Node attrNode); unsigned short isElementDefined(in DOMString name); unsigned short isElementDefinedNS(in DOMString namespaceURI, in DOMString name); };
An integer indicating the content type of an element.
VAL_ANY_CONTENTTYPEANY content model.
VAL_ELEMENTS_CONTENTTYPEelement content content model; and if the schema
is a W3C XML schema, this is the
element-only content type.
VAL_EMPTY_CONTENTTYPEempty content type; and if the schema is a DTD,
this corresponds to the EMPTY content model.
VAL_MIXED_CONTENTTYPEmixed
content type.
VAL_SIMPLE_CONTENTTYPEVAL_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.
allowedAttributes of type NameList, readonlyNameList, 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, readonlyNameList, 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, readonlyNameList, 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, readonlyNameList, 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, readonlyNameList, 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, readonlyNameList, 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, readonlyrequiredAttributes of type NameList, readonlyNameList, 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.
canRemoveAttributeattrname of type
DOMString
|
A validation state constant. |
canRemoveAttributeNSnamespaceURI of type
DOMStringlocalName of type
DOMString
|
A validation state constant. |
canRemoveAttributeNodeattrNode of type
NodeAttr node to remove from the attribute list.
|
A validation state constant. |
canSetAttributeattrname of type
DOMStringattrval of type
DOMString
|
A validation state constant. |
canSetAttributeNSnamespaceURI of type
DOMStringnamespaceURI of namespace.qualifiedName of type
DOMStringvalue of type
DOMString
|
A validation state constant. |
canSetAttributeNodeattrNode of type
AttrNode in which the attribute can possibly be set.
|
A validation state constant. |
canSetTextContentpossibleTextContent of type
DOMString
|
A validation state constant. |
isElementDefinedname is defined in the schema.
This only applies to global declarations. This method is for non-namespace aware schemas.
name of type
DOMString
|
A validation state constant. |
isElementDefinedNSname in this namespace is defined in the
current context. Thus not only does this apply to global declarations.
but depending on the content, this may also apply to local
definitions. This method is for namespace aware schemas.
namespaceURI of type
DOMStringnamespaceURI of namespace.name of type
DOMString
|
A validation state constant. |
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.
interface CharacterDataEditVAL : NodeEditVAL { unsigned short isWhitespaceOnly(); unsigned short canSetData(in DOMString arg); unsigned short canAppendData(in DOMString arg); unsigned short canReplaceData(in unsigned long offset, in unsigned long count, in DOMString arg) raises(DOMException); unsigned short canInsertData(in unsigned long offset, in DOMString arg) raises(DOMException); unsigned short canDeleteData(in unsigned long offset, in unsigned long count) raises(DOMException); };
canAppendDataarg of type
DOMString
|
A validation state constant. |
canDeleteDataoffset of type
unsigned longcount of type
unsigned long
|
A validation state constant. |
|
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. |
canInsertDataoffset of type
unsigned longarg of type
DOMString
|
A validation state constant. |
|
INDEX_SIZE_ERR: Raised if the specified offset is negative or greater than the number of 16-bit units in data. |
canReplaceDataoffset of type
unsigned longcount of type
unsigned longarg of type
DOMString
|
A validation state constant. |
|
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. |
canSetDataarg of type
DOMString
|
A validation state constant. |
isWhitespaceOnly
|
A validation state constant. |