previous   next   contents   index

25 October 2001

1. Abstract Schemas Object Model

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 Abstract Schemas (AS) module. This module provides a representation for XML abstract schemas, e.g., DTDs [XML] and XML Schemas [XML Schema Part 0], together with operations on the abstract schemas, and how such information within the abstract schemas could be applied to XML documents used in both the document-editing and AS-editing worlds. A DOM application can use the hasFeature method of the DOMImplementation interface defined in DOM Core to determine whether a given DOM supports these capabilities or not. One feature string for the AS-editing interfaces listed in this section is "AS-EDIT" and another feature string for document-editing interfaces is "AS-DOC".

This chapter interacts strongly with Document Object Model Load and Save. Not only will that code serialize/deserialize abstract schemas, but it may also wind up defining its well-formedness and validity checks in terms of what is defined in this chapter. In addition, the AS and Load/Save functional areas uses the error-reporting mechanism allowing user-registered error callbacks introduced in [DOM Level 3 Core]. Note that this may not imply that the parser actually calls the DOM's validation code -- it may be able to achieve better performance via its own -- but the appearance to the user should probably be "as if" the DOM has been asked to validate the document, and parsers should probably be able to validate newly loaded documents in terms of a previously loaded DOM AS.

Finally, this chapter will have separate sections to address the needs of the document-editing and AS-editing worlds, along with a section that details overlapping areas such as validation. In this manner, the document-editing world's focuses on editing aspects and usage of information in the AS are made distinct from the AS-editing world's focuses on defining and manipulating the information in the AS.

1.1.1. General Characteristics

In the October 9, 1997 DOM requirements document, the following appeared: "There will be a way to determine the presence of a DTD. There will be a way to add, remove, and change declarations in the underlying DTD (if available). There will be a way to test conformance of all or part of the given document against a DTD (if available)." In later discussions, the following was added, "There will be a way to query element/attribute (and maybe other) declarations in the underlying DTD (if available)," supplementing the primitive support for these in Level 1.

That work was deferred past Level 2, in the hope that XML Schemas would be addressed as well. It is anticipated that lowest common denominator general APIs generated in this chapter can support both DTDs and XML Schemas, and other XML abstract schemas down the road.

The kinds of information that an Abstract Schema must make available are mostly self-evident from the definitions of Infoset, DTDs, and XML Schemas. Note that some kinds of information on which the DOM already relies, e.g., default values for attributes, will finally be given a visible representation here.

1.1.2. Use Cases and Requirements

The abstract schema referenced in these use cases/requirements is an abstraction and does not refer solely to DTDs or XML Schemas.

For the AS-editing and document-editing worlds, the following use cases and requirements are common to both and could be labeled as the "Validation and Other Common Functionality" section:

Use Cases:

  1. CU1. Associating an abstract schema with a document, or changing the current association.
  2. CU2. Using the same abstract schema with several documents, without having to reload it.

Requirements:

  1. CR1. Validate against the abstract schema.
  2. CR2. Retrieve information from abstract schema.
  3. CR3. Load an existing abstract schema, perhaps independently from a document.
  4. CR4. Being able to determine if a document has an abstract schema associated with it.
  5. CR5. Associate an AS with a document and make it the active AS.

Specific to the AS-editing world, the following are use cases and requirements and could be labeled as the "AS-editing" section:

Use Cases:

  1. ASU1. Clone/map all or parts of an existing abstract schema to a new or existing abstract schema.
  2. ASU2. Save an abstract schema in a separate file. For example, if a DTD can be broken up into reusable pieces, which are then brought in via entity references, these can then be saved in a separate file. Note that a DTD, which may include both an internal and external subset, would be an example of an abstract schema.
  3. ASU3. Modify an existing abstract schema.
  4. ASU4. Create a new abstract schema.

Requirements:

  1. ASR1. View and modify all parts of the abstract schema.
  2. ASR2. Validate the abstract schema itself.
  3. ASR3. Serialize the abstract schema.
  4. ASR4. Clone all or parts of an existing abstract schema.
  5. ASR5. Create a new abstract schema object.
  6. ASR6. Validate portions of the XML document against the abstract schema.

Specific to the document-editing world, the following are use cases and requirements and could be labeled as the "Document-editing" section:

Use Cases:

  1. DU1. For editing documents with an associated abstract schema, provide the guidance necessary so that valid documents can be modified and remain valid.
  2. DU2. For editing documents with an associated abstract schema, provide the guidance necessary to transform an invalid document into a valid one.

Requirements:

  1. DR1. Be able to determine if the document is well-formed, and if not, be given enough guidance to locate the error.
  2. DR2. Be able to determine if the document is namespace well-formed, and if not, be given enough guidance to locate the error.
  3. DR3. Be able to determine if the document is valid with respect to its associated abstract schema.
  4. DR4. Be able to determine if specific modifications to a document would make it become invalid.
  5. DR5. Retrieve information from all abstract schemas. One example might be getting a list of all the defined element names for document editing purposes.

General Issues:

  1. I1. Some concerns exist regarding whether a single abstract Abstract Schema structure can successfully represent both namespace-unaware, e.g., DTD, and namespace-aware, e.g., XML Schema, models of document's content. For example, when you ask what elements can be inserted in a specific place, the former will report the element's QName, e.g., foo:bar, whereas the latter will report its namespace and local name, e.g., {http://my.namespace}bar. We have added the isNamespaceAware attribute to the generic AS object to help applications determine which of these fields are important, but we are still analyzing this challenge.
  2. I2. RESOLVED: An XML document may be associated with multiple ASs. We have decided that only one of these is "active" (for validation and guidance) at a time. DOM applications may switch which AS is active, remove ASs that are no longer relevant, or add ASs to the list. If it becomes necessary to simultaneously consult more than one AS, it should be possible to write a "union" AS which provides that capability within this framework.
  3. I3. WON'T DEAL W/THIS: Round-trippability for include/ignore statements and other constructs such as parameter entities, e.g., "macro-like" constructs, will not be supported since no data representation exists to support these constructs without having to re-parse them.
  4. I4. RESOLVED: Basic interface for a common error handler for both AS and Load/Save. Agreement has been to utilize user-registered callbacks but other details to be worked out. Moved to a separate chapter by Load/Save team.
  5. I5. RESOLVED: Add the ability to cache/edit an imported abstract schema instead of loading it every time, i.e., don't want to include the abstract schema every time. Implementations can do this without having this formalized though.
  6. I6. Add a read-only feature string AS-QUERY, along with query methods on the abstract schema. In more detail, there are methods that let you *query* the schema as well as those that let you modify the schema and these should be a feature, i.e., AS-QUERY: Abstract Schema objects with query interfaces.
  7. I7. RESOLVED: Have the NodeEditAS.can*(), CharacterDataEditAS.can*() , and ElementEditAS.can*() methods throw exceptions like the isNodeValid() method. Resolution: no exceptions should be thrown; it should be allowed if it's not forbidden. Better descriptions are in order for the true/false returns.
  8. I8. RESOLVED: Rename the document-editing interfaces so they should have uniform names such as NodeEditAS, DocumentEditAS, ElementEditAS, etc.
  9. I9. RESOLVED: Remove the ASDOMStringList interface; create a new interface for document editing, which is a slimmed down version of ElementEditAS; add a slimmed down method to get an ElementEditAS. Elena to examine.
  10. I10. RESOLVED: If another ASModel is activated, will there be cleanup done to remove the previous ASModel's default attributes and entity definitions, if any? AS ET members felt that whatever is done implementation-wise, correct behavior should result.
  11. I11. List of DOMASExceptions in the AS spec thus far: INVALID_CHARACTER_ERR, DUPLICATE_NAME_ERR, VALIDATION_ERR.
  12. I12. Should names/namespaces of the various declarations be mutable during AS editing? AS ET agreed they should and are awaiting action by the XML CORE team.
  13. I13. AS ET thinks the validate method and the error handler should be on Document, in CORE. If this doesn't happen, it needs to be on DocumentAS.
  14. I14. RESOLVED: If entities are changed in the ASModel, the underlying model is unchanged until normalization.
  15. I15. RESOLVED: Add option to control whether DOM CM is built from this document - solution is that the model is loaded (if there is one) and can be retrieved through the DocumentAS interface.
  16. I16. RESOLVED: There is a way to add a new schema file to the existing active compound schema via setASModel().
  17. I17. RESOLVED: Altering the document during error reporting, or mutation during validation terminates validation, and a warning will be produced if this happens.
  18. I18. Proposal needed to rename the asHint, asLocation attributes and tie that into how to describe an ASModel container of other ASModels.
  19. I19. Proposal to revise getElementDeclaration method and introduce other methods on the DocumentAS interface.
  20. I19. If implementation doesn't support AS-editing, need to have each set method throw an unsupported exception.

1.2. Abstract Schemas and AS-Editing Interfaces

A list of the proposed Abstract Schema data structures and functions follow, starting off with the data structures and "AS-editing" methods. Note that operations on the ASModel that could result in its being invalid will be discovered during document validation and not during the AS editing operation, for example, removeNode(). Finally, note that an example element declaration: for (A, (B* | C), D+) can be described by the following:

ASElementDeclaration example = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    tagname               = "example";
    ASContentModel        = exE;
    ASAttributeDecls      = null;
}

ASContentModel exE = {
    listOperator          = AS_SEQUENCE;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASElementDeclaration A),
                             (ASContentModel exBC),
                             (ASContentModel exD)};
}

ASElementDeclaration A = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    tagname               = "A";
    ASContentModel        = null;
    ASAttributeDecls      = null;
}

ASContentModel exBC = {
    listOperator          = AS_CHOICE;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASContentModel exB),
                             (ASElementDeclaration C)};
} 

ASContentModel exB = {
    listOperator          = AS_NONE;
    minOccurs             = 0;
    maxOccurs             = AS_UNBOUNDED;
    subModels             = {(ASElementDeclaration B)};
}
ASElementDeclaration B = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    tagname               = "B";
    ASContentModel        = null;
    ASAttributeDecls      = null;
}

ASElementDeclaration C = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    tagname               = "C";
    ASContentModel        = null;
    ASAttributeDecls      = null;
}

ASContentModel exD = {
    listOperator         = AS_NONE;
    minOccurs            = 1;
    maxOccurs            = AS_UNBOUNDED;
    subModels            = {(ASElementDeclaration D)};
}
ASElementDeclaration D = {
    strictMixedContent   = false;
    elementType          = STRING_DATATYPE;
    isPCDataOnly         = false;
    contentType          = ELEMENTS_CONTENTTYPE;
    tagname              = "D";
    ASContentModel       = null;
    ASAttributeDecls     = null;
}
Exception DOMASException

Abstract Schemas operations may throw a DOMSystemException as described in their descriptions.


IDL Definition
exception DOMASException {
  unsigned short   code;
};
// ASExceptionCode
const unsigned short      DUPLICATE_NAME_ERR             = 1;
const unsigned short      TYPE_ERR                       = 2;
const unsigned short      NO_AS_AVAILABLE                = 3;
const unsigned short      WRONG_MIME_TYPE_ERR            = 4;

Definition group ASExceptionCode

An integer indicating the type of error generated.

Defined Constants
DUPLICATE_NAME_ERR
If an element declaration already exists with the same name within an AS_CHOICE operator.
NO_AS_AVAILABLE
If the DocumentEditAS related to the node does not have any active ASModel and wfValidityCheckLevel is set to PARTIAL or STRICT_VALIDITY_CHECK.
TYPE_ERR
If the type of the ASObject is neither an ASContentModel nor an ASElementDeclaration.
WRONG_MIME_TYPE_ERR
When mimeTypeCheck is true and the input source has an incorrect MIME Type. See the attribute mimeTypeCheck.
Interface ASModel

To begin with, an abstract schema is a generic structure that could contain both internal and external subsets. An ASModel is an abstract object that could map to a DTD [XML], an XML Schema [XML Schema Part 0], a database schema, etc. An ASModel could represent either an internal or an external subset; hence an abstract schema could be composed of an ASModel representing the internal subset and an ASModel representing the external subset. Note that the ASModel representing the external subset could consult the ASModel representing the internal subset. Furthermore, the ASModel representing the internal subset could be set to null by the setInternalAS method as a mechanism for "removal". In addition, only one ASModel representing the external subset can be specified as "active" and it is possible that none are "active". Finally, the ASModel contains the factory methods needed to create a various types of ASObjects like ASElementDeclaration, ASAttributeDeclaration, etc.


IDL Definition
interface ASModel : ASObject {
  readonly attribute boolean          isNamespaceAware;
  readonly attribute unsigned short   usageLocation;
           attribute DOMString        asLocation;
           attribute DOMString        asHint;
  readonly attribute ASNamedObjectMap  elementDeclarations;
  readonly attribute ASNamedObjectMap  attributeDeclarations;
  readonly attribute ASNamedObjectMap  notationDeclarations;
  readonly attribute ASNamedObjectMap  entityDeclarations;
  readonly attribute ASNamedObjectMap  contentModelDeclarations;
  void               setASModel(in ASModel abstractSchema);
  ASObjectList       getASModels();
  void               removeAS(in ASModel as);
  boolean            validate();
  ASElementDeclaration createASElementDeclaration(in DOMString namespaceURI, 
                                                  in DOMString name)
                                        raises(DOMException);
  ASAttributeDeclaration createASAttributeDeclaration(in DOMString namespaceURI, 
                                                      in DOMString name)
                                        raises(DOMException);
  ASNotationDeclaration createASNotationDeclaration(in DOMString namespaceURI, 
                                                    in DOMString name, 
                                                    in DOMString systemId, 
                                                    in DOMString publicId)
                                        raises(DOMException);
  ASEntityDeclaration createASEntityDeclaration(in DOMString name)
                                        raises(DOMException);
  ASContentModel     createASContentModel(in unsigned long minOccurs, 
                                          in unsigned long maxOccurs, 
                                          in unsigned short operator)
                                        raises(DOMASException);
};

Attributes
asHint of type DOMString
The hint to locating an ASModel.
asLocation of type DOMString
The URI reference.
attributeDeclarations of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level/"global" attribute declarations. If one attempts to add, set, or remove a node type other than the intended one, a hierarchy exception (or equivalent is thrown).
contentModelDeclarations of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level/"global content model declarations. If one attempts to add, set, or remove a node type other than the intended one, a hierarchy exception (or equivalent is thrown).
elementDeclarations of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level/"global" element declarations. If one attempts to add, set, or remove a node type other than the intended one, a hierarchy exception (or equivalent is thrown).
entityDeclarations of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level/"global" entity declarations. If one attempts to add, set, or remove a node type other than the intended one, a hierarchy exception (or equivalent is thrown).
isNamespaceAware of type boolean, readonly
true if this ASModel defines the document structure in terms of namespaces and local names [XML Namespaces]; false if the document structure is defined only in terms of QNames.
notationDeclarations of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level/"global" notation declarations. If one attempts to add, set, or remove a node type other than the intended one, a hierarchy exception (or equivalent is thrown).
usageLocation of type unsigned short, readonly
0 if used internally, 1 if used externally, 2 if not all. An exception will be raised if it is incompatibly shared or in use as an internal subset.
Methods
createASAttributeDeclaration
Creates an attribute declaration.
Parameters
namespaceURI of type DOMString
The namespace URI of the attribute being declared.
name of type DOMString
The name of the attribute. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASModel-dependent.
Return Value

ASAttributeDeclaration

A new ASAttributeDeclaration object with appropriate attributes set by input parameters.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the input name parameter contains an illegal character.
createASContentModel
Creates an object which describes part of an ASElementDeclaration's content model.
Parameters
minOccurs of type unsigned long
The minimum occurrence for the subModels of this ASContentModel.
maxOccurs of type unsigned long
The maximum occurrence for the subModels of this ASContentModel.
operator of type unsigned short
operator of type AS_CHOICE, AS_SEQUENCE, AS_ALL or AS_NONE.
Return Value

ASContentModel

A new ASContentModel object.
Exceptions

DOMASException

A DOMASException, e.g., minOccurs > maxOccurs.
createASElementDeclaration
Creates an element declaration for the element type specified.
Parameters
namespaceURI of type DOMString
The namespace URI of the element type being declared.
name of type DOMString
The name of the element. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASModel-dependent.
Return Value

ASElementDeclaration

A new ASElementDeclaration object with name attribute set to tagname and namespaceURI set to systemId. Other attributes of the element declaration are set through ASElementDeclaration interface methods.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
createASEntityDeclaration
Creates an ASEntityDeclaration.
Parameters
name of type DOMString
The name of the entity being declared.
Return Value

ASEntityDeclaration

A new ASEntityDeclaration object with entityName attribute set to name.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
createASNotationDeclaration
Creates a new notation declaration.
Parameters
namespaceURI of type DOMString
The namespace URI of the notation being declared.
name of type DOMString
The name of the notation. The format of the name could be an NCName as defined by XML Namespaces or a Name as defined by XML 1.0; it's ASModel-dependent.
systemId of type DOMString
The system identifier for the notation declaration.
publicId of type DOMString
The public identifier for the notation declaration.
Return Value

ASNotationDeclaration

A new ASNotationDeclaration object with notationName attribute set to name and publicId and systemId set to the corresponding fields.
Exceptions

DOMException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
getASModels
To retrieve a list of nested ASModels without reference to names.
Return Value

ASObjectList

A list of ASModels.
No Parameters
No Exceptions
removeAS
Removes only the specified ASModel from the list of ASModels.
Parameters
as of type ASModel
AS to be removed.
No Return Value
No Exceptions
setASModel
This method will allow the nesting or "importation" of ASModels.
Parameters
abstractSchema of type ASModel
ASModel to be set. Subsequent calls will nest the ASModels within the specified ownerASModel.
No Return Value
No Exceptions
validate
Determines if an ASModel itself is valid, i.e., confirming that it's well-formed and valid per its own formal grammar.
Return Value

boolean

true if the ASModel is valid, false otherwise.
No Parameters
No Exceptions
Interface ASObject

The ASObject interface is analogous to a Node in [DOM Level 3 Core], e.g., an element declaration.

Opaque.


IDL Definition
interface ASObject {

  // ASObjectType
  const unsigned short      AS_ELEMENT_DECLARATION         = 1;
  const unsigned short      AS_ATTRIBUTE_DECLARATION       = 2;
  const unsigned short      AS_NOTATION_DECLARATION        = 3;
  const unsigned short      AS_ENTITY_DECLARATION          = 4;
  const unsigned short      AS_CONTENTMODEL                = 5;
  const unsigned short      AS_MODEL                       = 6;

  readonly attribute unsigned short   asNodeType;
           attribute ASModel          ownerASModel;
           attribute DOMString        nodeName;
           attribute DOMString        prefix;
           attribute DOMString        localName;
           attribute DOMString        namespaceURI;
  ASObject           cloneASObject(in boolean deep);
};

Definition group ASObjectType

An integer indicating which type of ASObject this is.

Defined Constants
AS_ATTRIBUTE_DECLARATION
The node is an ASAttributeDeclaration.
AS_CONTENTMODEL
The node is a ASContentModel.
AS_ELEMENT_DECLARATION
The node is an ASElementDeclaration.
AS_ENTITY_DECLARATION
The node is an ASEntityDeclaration.
AS_MODEL
The node is a ASModel.
AS_NOTATION_DECLARATION
The node is a ASNotationDeclaration.
Attributes
asNodeType of type unsigned short, readonly
A code representing the underlying object as defined above.
localName of type DOMString
Returns the local part of the qualified name of this ASObject.
namespaceURI of type DOMString
The namespace URI of this node, or null if it is unspecified. [XML Schema Part 1] defines how a namespace URI is attached to schema components.
nodeName of type DOMString
The name of this ASObject depending on the ASObject type.
ownerASModel of type ASModel
The ASModel object associated with this ASObject. For a node of type AS_MODEL, this is null.
prefix of type DOMString
The namespace prefix of this node, or null if it is unspecified.
Methods
cloneASObject
Creates a copy of this ASObject. See text for cloneNode off of Node but substitute AS functionality.
Parameters
deep of type boolean
Setting the deep flag on, causes the whole subtree to be duplicated. Setting it to false only duplicates its immediate child nodes.
Return Value

ASObject

Cloned ASObject.
No Exceptions
Interface ASObjectList

The ASObjectList interface provides the abstraction of an ordered collection of AS nodes, without defining or constraining how this collection is implemented. ASObjectList objects in the DOM AS are live.


IDL Definition
interface ASObjectList {
  readonly attribute unsigned long    length;
  ASObject           item(in unsigned long index);
};

Attributes
length of type unsigned long, readonly
The number of ASObjects in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. The index starts at 0. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
index of type unsigned long
index into the collection.
Return Value

ASObject

The ASObject at the indexth position in the ASObjectList, or null if that is not a valid index.
No Exceptions
Interface ASNamedObjectMap

Objects implementing the ASNamedObjectMap interface are used to represent collections of abstract schema nodes that can be accessed by name. Note that ASNamedObjectMap does not inherit from ASObjectList; ASNamedObjectMaps are not maintained in any particular order. Objects contained in an object implementing ASNamedObjectMap may also be accessed by an ordinal index, but this is simply to allow convenient enumeration of the contents of a ASNamedObjectMap, and does not imply that the DOM specifies an order to these ASObjects.

ASNamedObjectMap object in the DOM are live.


IDL Definition
interface ASNamedObjectMap {
  readonly attribute unsigned long    length;
  ASObject           getNamedItem(in DOMString name);
  ASObject           getNamedItemNS(in DOMString namespaceURI, 
                                    in DOMString localName);
  ASObject           item(in unsigned long index);
  ASObject           removeNamedItem(in DOMString name)
                                        raises(DOMException);
  ASObject           removeNamedItemNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
  ASObject           setNamedItem(in ASObject newASObject)
                                        raises(DOMException);
  ASObject           setNamedItemNS(in ASObject newASObject)
                                        raises(DOMException);
};

Attributes
length of type unsigned long, readonly
The number of ASObjects in the ASObjectList. The range of valid child node indices is 0 to length-1 inclusive.
Methods
getNamedItem
Retrieves an ASObject specified by name.
Parameters
name of type DOMString
The nodeName of an ASObject to retrieve.
Return Value

ASObject

An ASObject with specified node name and null if the map does not contain an element with the given name.
No Exceptions
getNamedItemNS
Retrieves an ASObject specified by local name and namespace URI.
Parameters
namespaceURI of type DOMString
The namespace URI of the ASObject to retrieve.
localName of type DOMString
The local name of the ASObject to retrieve.
Return Value

ASObject

A ASObject (of any type) with the specified local name and namespace URI, or null if they do not identify any ASObject in this map.
No Exceptions
item
Returns the indexth item in the map. The index starts at 0. If index is greater than or equal to the number of nodes in the list, this returns null.
Parameters
index of type unsigned long
The position in the map from which the item is to be retrieved.
Return Value

ASObject

The ASObject at the indexth position in the ASNamedObjectMap, or null if that is not a valid index.
No Exceptions
removeNamedItem
Removes an ASObject specified by a nodeName.
Parameters
name of type DOMString
The nodeName of the ASObject to be removed.
Return Value

ASObject

The ASObject removed from this map if an ASObject with such a name exists.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node named name in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
removeNamedItemNS
Removes an ASObject specified by a namespace URI and a local name.
Parameters
namespaceURI of type DOMString
The namespace URI of the ASObject to be removed.
localName of type DOMString
The local name of the ASObject to remove.
Return Value

ASObject

The ASObject removed from this map if an ASObject with such a local name and namespace URI exists.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if there is no node with the specified namespaceURI and localName in this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.
setNamedItem
Adds an ASObject using its nodeName attribute. If an ASObject with that name is already present in this map, it is replaced by the new one.
Parameters
newASObject of type ASObject
The ASObject to be inserted in the map with its nodeName as the key.
Return Value

ASObject

If the new node replaces an existing one, the replaced node is returned, otherwise null.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different ASModel than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this ASNamedObjectMap.
setNamedItemNS
Adds an ASObject using its namespaceURI and localName. If an ASObject with the same namespaceURI and localName is already present in this map, it is replaced by the new one.
Parameters
newASObject of type ASObject
The ASObject to be inserted in the map.The ASObject will later be accessible using the value of its namespaceURI and localName attributes.
Return Value

ASObject

If the new node replaces an existing one, the replaced node is returned, otherwise null.
Exceptions

DOMException

WRONG_DOCUMENT_ERR: Raised if arg was created from a different ASModel than the one that created this map.

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

HIERARCHY_REQUEST_ERR: Raised if an attempt is made to add a node doesn't belong in this ASNamedObjectMap.
Interface ASDataType

The datatypes supported by DOM AS implementations. Further datatypes may be added in the Schema/PSVI spec.


IDL Definition
interface ASDataType {
  readonly attribute unsigned short   dataType;

  // DATA_TYPES
  const unsigned short      STRING_DATATYPE                = 1;
  const unsigned short      NOTATION_DATATYPE              = 10;
  const unsigned short      ID_DATATYPE                    = 11;
  const unsigned short      IDREF_DATATYPE                 = 12;
  const unsigned short      IDREFS_DATATYPE                = 13;
  const unsigned short      ENTITY_DATATYPE                = 14;
  const unsigned short      ENTITIES_DATATYPE              = 15;
  const unsigned short      NMTOKEN_DATATYPE               = 16;
  const unsigned short      NMTOKENS_DATATYPE              = 17;
  const unsigned short      BOOLEAN_DATATYPE               = 100;
  const unsigned short      FLOAT_DATATYPE                 = 101;
  const unsigned short      DOUBLE_DATATYPE                = 102;
  const unsigned short      DECIMAL_DATATYPE               = 103;
  const unsigned short      HEXBINARY_DATATYPE             = 104;
  const unsigned short      BASE64BINARY_DATATYPE          = 105;
  const unsigned short      ANYURI_DATATYPE                = 106;
  const unsigned short      QNAME_DATATYPE                 = 107;
  const unsigned short      DURATION_DATATYPE              = 108;
  const unsigned short      DATETIME_DATATYPE              = 109;
  const unsigned short      DATE_DATATYPE                  = 110;
  const unsigned short      TIME_DATATYPE                  = 111;
  const unsigned short      GYEARMONTH_DATATYPE            = 112;
  const unsigned short      GYEAR_DATATYPE                 = 113;
  const unsigned short      GMONTHDAY_DATATYPE             = 114;
  const unsigned short      GDAY_DATATYPE                  = 115;
  const unsigned short      GMONTH_DATATYPE                = 116;
  const unsigned short      INTEGER                        = 117;
  const unsigned short      NAME_DATATYPE                  = 200;
  const unsigned short      NCNAME_DATATYPE                = 201;
  const unsigned short      NORMALIZEDSTRING_DATATYPE      = 202;
  const unsigned short      TOKEN_DATATYPE                 = 203;
  const unsigned short      LANGUAGE_DATATYPE              = 204;
  const unsigned short      NONPOSITIVEINTEGER_DATATYPE    = 205;
  const unsigned short      NEGATIVEINTEGER_DATATYPE       = 206;
  const unsigned short      LONG_DATATYPE                  = 207;
  const unsigned short      INT_DATATYPE                   = 208;
  const unsigned short      SHORT_DATATYPE                 = 209;
  const unsigned short      BYTE_DATATYPE                  = 210;
  const unsigned short      NONNEGATIVEINTEGER_DATATYPE    = 211;
  const unsigned short      UNSIGNEDLONG_DATATYPE          = 212;
  const unsigned short      UNSIGNEDINT_DATATYPE           = 213;
  const unsigned short      UNSIGNEDSHORT_DATATYPE         = 214;
  const unsigned short      UNSIGNEDBYTE_DATATYPE          = 215;
  const unsigned short      POSITIVEINTEGER_DATATYPE       = 216;
  const unsigned short      OTHER_SIMPLE_DATATYPE          = 1000;
  const unsigned short      COMPLEX_DATATYPE               = 1001;
};

Definition group DATA_TYPES

An integer indicating which datatype this is.

Defined Constants
ANYURI_DATATYPE
Then uri reference data type as defined in [XML Schema Part 2].
BASE64BINARY_DATATYPE
The base64binary data type as defined in [XML Schema Part 2].
BOOLEAN_DATATYPE
A code representing the boolean data type as defined in [XML Schema Part 2].
BYTE_DATATYPE
The byte data type as defined in [XML Schema Part 2].
COMPLEX_DATATYPE
The user-defined complex data type as defined in [XML Schema Part 2].
DATETIME_DATATYPE
The datetime data type as defined in [XML Schema Part 2].
DATE_DATATYPE
The date data type as defined in [XML Schema Part 2].
DECIMAL_DATATYPE
The decimal data type as defined in [XML Schema Part 2].
DOUBLE_DATATYPE
A code representing the double data type as defined in [XML Schema Part 2].
DURATION_DATATYPE
The duration data type as defined in [XML Schema Part 2].
ENTITIES_DATATYPE
The ENTITIES data type as defined in [XML Schema Part 2].
ENTITY_DATATYPE
The ENTITY data type as defined in [XML Schema Part 2].
FLOAT_DATATYPE
A code representing the float data type as defined in [XML Schema Part 2].
GDAY_DATATYPE
The day data type as defined in [XML Schema Part 2].
GMONTHDAY_DATATYPE
The monthday data type as defined in [XML Schema Part 2].
GMONTH_DATATYPE
The month data type as defined in [XML Schema Part 2].
GYEARMONTH_DATATYPE
The yearmonth data type as defined in [XML Schema Part 2].
GYEAR_DATATYPE
The year data type as defined in [XML Schema Part 2].
HEXBINARY_DATATYPE
The hexbinary data type as defined in [XML Schema Part 2].
IDREFS_DATATYPE
The IDREFS data type as defined in [XML Schema Part 2].
IDREF_DATATYPE
The IDREF data type as defined in [XML Schema Part 2].
ID_DATATYPE
The ID data type as defined in [XML Schema Part 2].
INTEGER
The integer data type as defined in [XML Schema Part 2].
INT_DATATYPE
The integer data type as defined in [XML Schema Part 2].
LANGUAGE_DATATYPE
The Language data type as defined in [XML Schema Part 2].
LONG_DATATYPE
Then long data type as defined in [XML Schema Part 2].
NAME_DATATYPE
A code representing the Name data type as defined in [XML Schema Part 2].
NCNAME_DATATYPE
A code representing the NCName data type as defined in [XML Schema Part 2].
NEGATIVEINTEGER_DATATYPE
Then negative integer data type as defined in [XML Schema Part 2].
NMTOKENS_DATATYPE
The NMTOKENS data type as defined in [XML Schema Part 2].
NMTOKEN_DATATYPE
The NMTOKEN data type as defined in [XML Schema Part 2].
NONNEGATIVEINTEGER_DATATYPE
The non-negative integer data type as defined in [XML Schema Part 2].
NONPOSITIVEINTEGER_DATATYPE
The Non-positive integer data type as defined in [XML Schema Part 2].
NORMALIZEDSTRING_DATATYPE
A code representing the Normalized string data type as defined in [XML Schema Part 2].
NOTATION_DATATYPE
The NOTATION data type as defined in [XML Schema Part 2].
OTHER_SIMPLE_DATATYPE
The other simple data type as defined in [XML Schema Part 2].
POSITIVEINTEGER_DATATYPE
The positive integer data type as defined in [XML Schema Part 2].
QNAME_DATATYPE
Then XML qualified name data type as defined in [XML Schema Part 2].
SHORT_DATATYPE
The short data type as defined in [XML Schema Part 2].
STRING_DATATYPE
A code representing the string data type as defined in [XML Schema Part 2].
TIME_DATATYPE
The time data type as defined in [XML Schema Part 2].
TOKEN_DATATYPE
The token data type as defined in [XML Schema Part 2].
UNSIGNEDBYTE_DATATYPE
The unsigned byte data type as defined in [XML Schema Part 2].
UNSIGNEDINT_DATATYPE
The unsigned integer data type as defined in [XML Schema Part 2].
UNSIGNEDLONG_DATATYPE
The unsigned long data type as defined in [XML Schema Part 2].
UNSIGNEDSHORT_DATATYPE
The unsigned short data type as defined in [XML Schema Part 2].
Attributes
dataType of type unsigned short, readonly
One of the enumerated codes representing the data type.
Interface ASElementDeclaration

The element name along with the content specification in the context of an ASObject.


IDL Definition
interface ASElementDeclaration : ASObject {

  // CONTENT_MODEL_TYPES
  const unsigned short      EMPTY_CONTENTTYPE              = 1;
  const unsigned short      ANY_CONTENTTYPE                = 2;
  const unsigned short      MIXED_CONTENTTYPE              = 3;
  const unsigned short      ELEMENTS_CONTENTTYPE           = 4;

           attribute boolean          strictMixedContent;
           attribute ASDataType       elementType;
           attribute boolean          isPCDataOnly;
           attribute unsigned short   contentType;
           attribute DOMString        systemId;
           attribute ASContentModel   asCM;
           attribute ASNamedObjectMap  ASAttributeDecls;
  void               addASAttributeDecl(in ASAttributeDeclaration attributeDecl);
  ASAttributeDeclaration removeASAttributeDecl(in ASAttributeDeclaration attributeDecl);
};

Definition group CONTENT_MODEL_TYPES
Defined Constants
ANY_CONTENTTYPE
Represents an ANY content type for an Element declaration.
ELEMENTS_CONTENTTYPE
Represents an ELEMENTS only content type for an Element declaration.
EMPTY_CONTENTTYPE
Represents an EMPTY content type for an Element declaration.
MIXED_CONTENTTYPE
Represents a MIXED content type for an Element declaration. Note that isPCDataOnly would also need to checked, in addition to this, if an element's content model was simply text, as an example.
Attributes
ASAttributeDecls of type ASNamedObjectMap
TheASNamedObjectMap containing ASAttributeDeclarations for all the attributes that can appear on this type of element.
asCM of type ASContentModel
The content model of element.
contentType of type unsigned short
The content type of the element. One of EMPTY_CONTENTTYPE, ANY_CONTENTTYPE, MIXED_CONTENTTYPE, ELEMENTS_CONTENTTYPE.
elementType of type ASDataType
Datatype of the element.
isPCDataOnly of type boolean
Boolean defining whether the element type contains child elements and PCDATA or PCDATA only for mixed element types. true if the element is of type PCDATA only. Relevant only for mixed content type elements.
strictMixedContent of type boolean
A boolean defining whether the element order and number of the child elements for mixed content type has to be respected or not. For example XML Schema defined mixed content types the order is important and needs to be respected whether for DTD based AS the order and number of child elements are not important.
systemId of type DOMString
the URI reference representing the system identifier for the notation declaration, if present, null otherwise.
Methods
addASAttributeDecl
Adds an ASAttributeDeclaration for the element being declared.
Parameters
attributeDecl of type ASAttributeDeclaration
The new attribute to add. If the attribute declaration already exists for the element, the call does not have any effect.
No Return Value
No Exceptions
removeASAttributeDecl
Removes an ASAttributeDeclaration from the element being declared.
Parameters
attributeDecl of type ASAttributeDeclaration
The attribute declaraition to be removed. If the attribute declaration does not exist for the element, the call does not have any effect.
Return Value

ASAttributeDeclaration

null if the attribute does not exist. Otherwise returns the attribute being removed.
No Exceptions
Interface ASContentModel

The content model of a declared element.


IDL Definition
interface ASContentModel : ASObject {
  const unsigned long       AS_UNBOUNDED                   = MAX_VALUE;

  // ASContentModelType
  const unsigned short      AS_SEQUENCE                    = 0;
  const unsigned short      AS_CHOICE                      = 1;
  const unsigned short      AS_ALL                         = 2;
  const unsigned short      AS_NONE                        = 3;

           attribute unsigned short   listOperator;
           attribute unsigned long    minOccurs;
           attribute unsigned long    maxOccurs;
           attribute ASObjectList     subModels;
  void               removesubModel(in ASObject oldNode);
  void               insertsubModel(in ASObject newNode)
                                        raises(DOMASException);
  unsigned long      appendsubModel(in ASObject newNode)
                                        raises(DOMASException);
};

Constant AS_UNBOUNDED
Signifies unbounded upper limit. The MAX_VALUE value is 0xFFFFFFFF FFFFFFFF.
(ED: This needs to be better defined in the generated bindings.)
Definition group ASContentModelType

An integer indicating which type of ASContentModel this is.

Defined Constants
AS_ALL
All of the above.
AS_CHOICE
This constant value signifies a choice operator. For example, in a DTD, this would be the '|' operator.
AS_NONE
None of the above, i.e., neither a choice nor sequence operator.
AS_SEQUENCE
This constant value signifies a sequence operator. For example, in a DTD, this would be the ',' operator.
Attributes
listOperator of type unsigned short
One of AS_CHOICE, AS_SEQUENCE, AS_ALL or AS_NONE. The operator is applied to all the components(ASObjects) in the subModels. For example, if the list operator is AS_CHOICE and the components in subModels are a, b and c then the abstract schema for the element being declared is (a|b|c).
maxOccurs of type unsigned long
maximum occurrence for this content particle. Its value may be 0, a positive integer, or AS_UNBOUNDED to indicate that no upper limit has been set.
minOccurs of type unsigned long
min occurrence for this content particle. Its value may be 0 or a positive integer.
subModels of type ASObjectList
Pointers to ASObjects such as ASElementDeclarations and further ASContentModels.
Methods
appendsubModel
Appends a new node to the end of the list representing thesubModels.
Parameters
newNode of type ASObject
The new node to be appended.
Return Value

unsigned long

the length of the subModels.
Exceptions

DOMASException

DUPLICATE_NAME_ERR: Raised if a element declaration already exists with the same name within an AS_CHOICE operator.

TYPE_ERR: Raised if type is neither an ASContentModel nor an ASElementDeclaration.
insertsubModel
Inserts a new node in the submodel. Nodes that already exist in the list are moved as needed.
Parameters
newNode of type ASObject
The new node to be inserted.
Exceptions

DOMASException

DUPLICATE_NAME_ERR: Raised if a element declaration already exists with the same name within an AS_CHOICE operator.
No Return Value
removesubModel
Removes the ASObject in the submodel. Nodes that already exist in the list are moved as needed.
Parameters
oldNode of type ASObject
The node to be removed.
No Return Value
No Exceptions
Interface ASAttributeDeclaration

An attribute declaration in the context of a ASObject.

Issue ASAttributeDeclaration-1:
The constant 'REQUIRED' is missing from this interface.

IDL Definition
interface ASAttributeDeclaration : ASObject {

  // VALUE_TYPES
  const unsigned short      VALUE_NONE                     = 0;
  const unsigned short      VALUE_DEFAULT                  = 1;
  const unsigned short      VALUE_FIXED                    = 2;

           attribute ASDataType       dataType;
           attribute DOMString        dataValue;
           attribute DOMString        enumAttr;
           attribute ASObjectList     ownerElements;
           attribute unsigned short   defaultType;
};

Definition group VALUE_TYPES
Defined Constants
VALUE_DEFAULT
Indicates that the there is a default value constraint.
VALUE_FIXED
Indicates that there is a fixed value constraint for this attribute.
VALUE_NONE
Describes that the attribute does not have any value constraint.
Attributes
dataType of type ASDataType
Datatype of the attribute.
dataValue of type DOMString
Default or fixed value.
defaultType of type unsigned short
Constraint type if any for this attribute.
enumAttr of type DOMString
Valid attribute values, separated by commas, in a string.
ownerElements of type ASObjectList
Owner elements ASObject of attribute, meaning that an attribute declaration can be shared by multiple elements.
Interface ASEntityDeclaration

Models a general entity declaration in an abstract schema.

(ED: The abstract schema does not handle any parameter entity. It is assumed that the parameter entities are expanded by the implementation as the abstract schema is built.)

IDL Definition
interface ASEntityDeclaration : ASObject {

  // EntityType
  const unsigned short      INTERNAL_ENTITY                = 1;
  const unsigned short      EXTERNAL_ENTITY                = 2;

           attribute unsigned short   entityType;
           attribute DOMString        entityValue;
           attribute DOMString        systemId;
           attribute DOMString        publicId;
};

Definition group EntityType

An integer indicating which type of entity this is.

Defined Constants
EXTERNAL_ENTITY
constant defining an external entity.
INTERNAL_ENTITY
constant defining an internal entity.
Attributes
entityType of type unsigned short
The type of the entity as defined above.
entityValue of type DOMString
The replacement text for the internal entity. The entity references within the replacement text are kept intact. For an entity of type EXTERNAL_ENTITY, this is null.
publicId of type DOMString
The string representing the public identifier for this notation declaration, if present; null otherwise.
systemId of type DOMString
the URI reference representing the system identifier for the notation declaration, if present, null otherwise.
Interface ASNotationDeclaration

This interface represents a notation declaration.


IDL Definition
interface ASNotationDeclaration : ASObject {
           attribute DOMString        systemId;
           attribute DOMString        publicId;
};

Attributes
publicId of type DOMString
The string representing the public identifier for this notation declaration, if present; null otherwise.
systemId of type DOMString
the URI reference representing the system identifier for the notation declaration, if present, null otherwise.

1.3. Validation and Other Interfaces

This section contains "Validation and Other" methods common to both the document-editing and AS-editing worlds (includes DOMImplementation methods).

Interface DocumentAS

This interface extends the Document interface with additional methods for both document and AS editing.


IDL Definition
interface DocumentAS {
           attribute ASModel          activeASModel;
           attribute ASObjectList     boundASModels;
  ASModel            getInternalAS();
  void               setInternalAS(in ASModel as);
  void               addAS(in ASModel as);
  void               removeAS(in ASModel as);
  ASElementDeclaration getElementDeclaration()
                                        raises(DOMException);
  void               validate()
                                        raises(DOMASException);
};

Attributes
activeASModel of type ASModel
The active external ASModel. Note that the active external ASModel is responsible for consulting the internal ASModel, so if an attribute is declared in the internal ASModel and the corresponding ownerElements points to a ASElementDeclarations defined in the active external ASModel, changing the active external ASModel will cause the ownerElements to be recomputed. If the ownerElements is not defined in the newly active external ASModel, the ownerElements will be an empty node list.
boundASModels of type ASObjectList
A list of ASObjects of type AS_MODELs associated with a document. The addAS method associates a ASModel with a document.
Methods
addAS
Associate a ASModel with a document. Can be invoked multiple times to result in a list of ASModels. Note that only one internal ASModel is associated with the document, however, and that only one of the possible list of ASModels is active at any one time.
Parameters
as of type ASModel
ASModel to be associated with the document.
No Return Value
No Exceptions
getElementDeclaration
Gets the AS editing object describing this element
Issue getElementDeclaration-1:
This method needs to be changed and others added.
Return Value

ASElementDeclaration

ASElementDeclaration object if the implementation supports "AS-EDIT" feature. Otherwise null.
Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is present.
No Parameters
getInternalAS
Retrieve the internal ASModel of a document.
Return Value

ASModel

ASModel.
No Parameters
No Exceptions
removeAS
Removes a ASModel associated with a document. Can be invoked multiple times to remove a number of these in the list of ASModels.
Parameters
as of type ASModel
The ASModel to be removed.
No Return Value
No Exceptions
setInternalAS
Sets the internal subset ASModel of a document. This could be null as a mechanism for "removal".
Parameters
as of type ASModel
ASModel to be the internal subset of the document.
No Return Value
No Exceptions
validate
Validates the document against the ASModel.
Exceptions

DOMASException
No Parameters
No Return Value
Interface DOMImplementationAS

This interface allows creation of an ASModel. The expectation is that an instance of the DOMImplementationAS interface can be obtained by using binding-specific casting methods on an instance of the DOMImplementation interface when the DOM implementation supports the feature "AS-EDIT".


IDL Definition
interface DOMImplementationAS {
  ASModel            createAS(in boolean isNamespaceAware);
  DOMASBuilder       createDOMASBuilder();
  DOMASWriter        createDOMASWriter();
};

Methods
createAS
Creates an ASModel.
Parameters
isNamespaceAware of type boolean
Allow creation of ASModel with this attribute set to a specific value.
Return Value

ASModel

A null return indicates failure.

Issue createAS-1:
what is a failure? Could be a system error.
No Exceptions
createDOMASBuilder
Creates an DOMASBuilder.
Issue createDOMASBuilder-1:
Do we need the method since we already have DOMImplementationLS.createDOMBuilder?
Return Value

DOMASBuilder
No Parameters
No Exceptions
createDOMASWriter
Creates an DOMASWriter.
Return Value

DOMASWriter
No Parameters
No Exceptions

1.4. Document-Editing Interfaces

This section contains "Document-editing" methods (includes Node, Element, Text and Document methods).

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-DOC" and "3.0" (respectively) to determine whether or not the Document-Editing interfaces of the Abstract Schemas module are supported by the implementation.

Interface DocumentEditAS

This interface extends the NodeEditAS interface with additional methods for both document and AS editing.


IDL Definition
interface DocumentEditAS : NodeEditAS {
           attribute boolean          continuousValidityChecking;
};

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. If the document is invalid, then this attribute will remain false. This attribute is false by default.
(ED: Add VALIDATION_ERR code to the list of constants in DOMASException.)
Interface NodeEditAS

This interface extends a Node from [DOM Level 3 Core] with additional methods for guided document editing. The expectation is that an instance of the DOMImplementationAS interface can be obtained by using binding-specific casting methods on an instance of the DOMImplementation interface when the DOM implementation supports the feature "AS-DOC".


IDL Definition
interface NodeEditAS {

  // ASCheckType
  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;

  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(DOMASException);
};

Definition group ASCheckType

An integer indicating which type of validation this is.

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 active AS which by definition includes NS_WF_CHECK.
WF_CHECK
Check for well-formedness of this node.
Methods
canAppendChild
Has the same arguments as AppendChild.
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 insertBefore operation from the Node interface would make this document invalid with respect to the currently active AS.
Issue canInsertBefore-1:
Describe "valid" when referring to partially completed documents.
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 RemoveChild.
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 ReplaceChild.
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 currently active AS. 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 validate method on the DocumentAS 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 current context and check level defined by wfValidityCheckLevel, false if not.
Exceptions

DOMASException

NO_AS_AVAILABLE: Raised if the DocumentEditAS related to this node does not have any active ASModel and wfValidityCheckLevel is set to PARTIAL or STRICT_VALIDITY_CHECK.
Interface ElementEditAS

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


IDL Definition
interface ElementEditAS : NodeEditAS {
  readonly attribute NodeList         definedElementTypes;
  unsigned short     contentType();
  boolean            canSetAttribute(in DOMString attrname, 
                                     in DOMString attrval);
  boolean            canSetAttributeNode(in Attr attrNode);
  boolean            canSetAttributeNS(in DOMString name, 
                                       in DOMString attrval, 
                                       in DOMString namespaceURI);
  boolean            canRemoveAttribute(in DOMString attrname);
  boolean            canRemoveAttributeNS(in DOMString attrname, 
                                          in DOMString namespaceURI);
  boolean            canRemoveAttributeNode(in Node attrNode);
  NodeList           getChildElements();
  NodeList           getParentElements();
  NodeList           getAttributeList();
  boolean            isElementDefined(in DOMString elemTypeName);
  boolean            isElementDefinedNS(in DOMString elemTypeName, 
                                        in DOMString namespaceURI, 
                                        in DOMString name);
};

Attributes
definedElementTypes of type NodeList, readonly
The list of qualified element names defined in the abstract schema.
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
attrname of type DOMString
Local name of the attribute to be removed.
namespaceURI of type DOMString
The namespace URI of the attribute to remove.
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 same qualified name and namespaceURI is already present in the elements attribute list it tests for the value of the attribute and its prefix to the new value. See DOM core setAttributeNS.
Parameters
name of type DOMString
Qualified name of attribute.
attrval of type DOMString
Value to be assigned to the attribute.
namespaceURI of type DOMString
namespaceURI of namespace.
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.
Issue canSetAttributeNode-1:
This is an attribute node, there is no need for canSetAttributreNodeNS!
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, ANY_CONTENTTYPE, MIXED_CONTENTTYPE, ELEMENTS_CONTENTTYPE.
No Parameters
No Exceptions
getAttributeList
Returns an NodeList containing all the possible Attrs that can appear with this type of element.
Return Value

NodeList

List of possible attributes of this element.
No Parameters
No Exceptions
getChildElements
Returns an NodeList containing the possible Element names that can appear as children of this type of element.
Return Value

NodeList

List of possible children element types of this element.
No Parameters
No Exceptions
getParentElements
Returns an NodeList containing the possible Element names that can appear as a parent of this type of element.
Return Value

NodeList

List of possible parent element types of this element.
No Parameters
No Exceptions
isElementDefined
Determines if this element is defined in the currently active AS.
Parameters
elemTypeName 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 this element in this namespace is defined in the currently active AS.
Parameters
elemTypeName of type DOMString
Name of element.
namespaceURI of type DOMString
namespaceURI of namespace.
name of type DOMString
Qualified name of namespace. This is for sub-elements.
Return Value

boolean

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

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


IDL Definition
interface CharacterDataEditAS : NodeEditAS {
  readonly attribute boolean          isWhitespaceOnly;
  boolean            canSetData(in unsigned long offset, 
                                in unsigned long count);
  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
Argument 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
offset of type unsigned long
Offset.
count of type unsigned long
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.5. Editing and Generating an Abstract Schema

Editing and generating an abstract schema falls in the AS-editing world. The most obvious requirement for this set of requirements is for tools that author abstract schemas, either under user control, i.e., explicitly designed document types, or generated from other representations. The latter class includes transcoding tools, e.g., synthesizing an XML representation to match a database schema.

It's important to note here that a DTD's "internal subset" is part of the Abstract Schema, yet is loaded, stored, and maintained as part of the individual document instance. This implies that even tools which do not want to let users change the definition of the Document Type may need to support editing operations upon this portion of the AS. It also means that our representation of the AS must be aware of where each portion of its content resides, so that when the serializer processes this document it can write out just the internal subset. A similar issue may arise with external parsed entities, or if schemas introduce the ability to reference other schemas. Finally, the internal-subset case suggests that we may want at least a two-level representation of abstract schemas, so a single DOM representation of a DTD can be shared among several documents, each potentially also having its own internal subset; it's possible that entity layering may be represented the same way.

The API for altering the abstract schema may also be the AS's official interface with parsers. One of the ongoing problems in the DOM is that there is some information which must currently be created via completely undocumented mechanisms, which limits the ability to mix and match DOMs and parsers. Given that specialized DOMs are going to become more common (sub-classed, or wrappers around other kinds of storage, or optimized for specific tasks), we must avoid that situation and provide a "builder" API. Particular pairs of DOMs and parsers may bypass it, but it's required as a portability mechanism.

Note that several of these applications require that an AS be able to be created, loaded, and manipulated without/before being bound to a specific Document. A related issue is that we'd want to be able to share a single representation of an AS among several documents, both for storage efficiency and so that changes in the AS can quickly be tested by validating it against a set of known-good documents. Similarly, there is a known problem in [DOM Level 3 Core] where we assume that the DocumentType will be created before the Document, which is fine for newly-constructed documents but not a good match for the order in which an XML parser encounters this data; being able to "rebind" a Document to a new AS, after it has been created may be desirable.

As noted earlier, questions about whether one can alter the content of the AS via its syntax, via higher-level abstractions, or both, exist. It's also worth noting that many of the editing concepts from the Document tree still apply; users should probably be able to clone part of an AS, remove and re-insert parts, and so on.

1.6. Abstract Schema-directed Document Manipulation

In addition to using the abstract schema to validate a document instance, applications would like to be able to use it to guide construction and editing of documents, which falls into the document-editing world. Examples of this sort of guided editing already exist, and are becoming more common. The necessary queries can be phrased in several ways, the most useful of which may be a combination of "what does the DTD allow me to insert here" and "if I insert this here, will the document still be valid". The former is better suited to presentation to humans via a user interface, and when taken together with sub-tree validation may subsume the latter.

It has been proposed that in addition to asking questions about specific parts of the abstract schema, there should be a reasonable way to obtain a list of all the defined symbols of a given type (element, attribute, entity) independent of whether they're valid in a given location; that might be useful in building a list in a user-interface, which could then be updated to reflect which of these are relevant for the program's current state.

Remember that namespaces also weigh in on this issue, in the case of attributes, a "can-this-go-there" may prompt a namespace-well-formedness check and warn you if you're about to conflict with or overwrite another attribute with the same namespaceURI/localName but different prefix, or same nodeName but different namespaceURI.

We have to deal with the fact that "the shortest distance between two valid documents may be through an invalid one". Users may want to know several levels of detail (all the possible children, those which would be valid given what precedes this point, those which would be valid given both preceding and following siblings). Also, once XML Schemas introduce context sensitive validity, we may have to consider the effect of children as well as the individual node being inserted.

1.7. Validating a Document Against an Abstract Schema

The most obvious use for an abstract schema (DTD or XML Schema or any Abstract Schema) is to use it to validate that a given XML document is in fact a properly constructed instance of the document type described by this AS. This again falls into the document-editing world. The XML spec only discusses performing this test at the time the document is loaded into the "processor", which most of us have taken to mean that this check should be performed at parse time. But it is obviously desirable to be able to validate again a document -- or selected subtrees -- at other times. One such case would be validating an edited or newly constructed document before serializing it or otherwise passing it to other users. This issue also arises if the "internal subset" is altered -- or if the whole Abstract Schema changes.

In the past, the DOM has allowed users to create invalid documents, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax... or that they would be checked for validity when read back in. We considered adding validity checks to the DOM's existing editing operations to prevent creation of invalid documents, but are currently inclined against this for several reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations, e.g., if the change is occurring in a context where we know the result will be valid. Second, "the shortest distance between two good documents may be through a bad document". Preventing a document from becoming temporarily invalid may impose a considerable amount of additional work on higher-level code and users Hence our current plan is to continue to permit editing to produce invalid DOMs, but provide operations which permit a user to check the validity of a node on demand. If needed one can use continuousValidityChecking flag to ensure that the DOM remains valid during the editing process.

Note that validation includes checking that ID attributes are unique, and that IDREFs point to IDs which actually exist.

1.8. Well-formedness Testing

XML defined the "well-formed" (WF) state for documents which are parsed without reference to their DTDs. Knowing that a document is well-formed may be useful by itself even when a DTD is available. For example, users may wish to deliberately save an invalid document, perhaps as a checkpoint before further editing. Hence, the AS feature will permit both full validity checking (see previous section) and "lightweight" WF checking, as requested by the caller, as well as processing entity declarations in the AS even if validation is not turned on. This falls within the document-editing world.

While the DOM inherently enforces some of XML's well-formedness conditions (proper nesting of elements, constraints on which children may be placed within each node), there are some checks that are not yet performed. These include:

In addition, Namespaces introduce their own concepts of well-formedness. Specifically:

In the past, the DOM has allowed users to create documents which violate these rules, and assumed the serializer would accept the task of detecting problems and announcing/repairing them when the document was written out in XML syntax. We considered adding WF checks to the DOM's existing editing operations to prevent WF violations from arising, but are currently inclined against this for two reasons. First, it would impose a significant amount of computational overhead to the DOM, which might be unnecessary in many situations (for example, if the change is occurring in a context where we know the illegal characters have already been prevented from arising). Second, "the shortest distance between two good documents may be through a bad document" -- preventing a document from becoming temporarily ill-formed may impose a considerable amount of additional work on higher-level code and users. (Note possible issue for Serialization: In some applications, being able to save and reload marginally poorly-formed DOMs might be useful -- editor checkpoint files, for example.) Hence our current plan is to continue to permit editing to produce ill-formed DOMs, but provide operations which permit a user to check the well-formedness of a node on demand, and possibly provide some of the primitive (e.g., string-checking) functions directly.

1.9. Load and Save for Abstract Schemas

The module extends the Document Object Model Load and Save module to permit to load a Document using a specific ASModel and to load an ASModel from an URI or DOMInputSource.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-LS" and "3.0" (respectively) to determine whether or not the Load and Save for Abstract Schemas module is supported by the implementation. In order to fully support this module, an implementation must also support the "AS-EDIT" features defined in this specification.

Interface DOMASBuilder

An Abstract Schema parser interface.

DOMASBuilder provides an API for parsing Abstract Schemas and building the corresponding ASModel tree.


IDL Definition
interface DOMASBuilder : ls::DOMBuilder {
           attribute ASModel          abstractSchema;
  ASModel            parseASURI(in DOMString uri)
                                        raises(DOMASException, 
                                               DOMSystemException);
  ASModel            parseASInputSource(in ls::DOMInputSource is)
                                        raises(DOMASException, 
                                               DOMSystemException);
};

Attributes
abstractSchema of type ASModel
Associate an ASModel with a DOMBuilder. This ASModel will be used by the "validate-if-schema" and "datatype-normalization" options during the load of a new Document.
Methods
parseASInputSource
Parse a Abstract Schema from a location identified by an DOMInputSource.
Parameters
is of type ls::DOMInputSource
The DOMInputSource from which the source Abstract Schema is to be read.
Return Value

ASModel

The newly created ASModel.
Exceptions

DOMASException

Exceptions raised by parseASURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMASException if any form of Abstract Schema inconsistencies or warning occurs during the parse, but application defined errorHandlers are not required to do so.

Raise a WRONG_MIME_TYPE_ERR when mimeTypeCheck is true and the inputsource has an incorrect MIME Type. See attribute mimeTypeCheck.

DOMSystemException

Exceptions raised by parseURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined error handlers are not required to do so.
parseASURI
Parse a Abstract Schema from a location identified by an URI reference.
Parameters
uri of type DOMString
The location of the Abstract Schema to be read.
Return Value

ASModel

The newly created Abstract Schema.
Exceptions

DOMASException

Exceptions raised by parseASURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMASException if any form of Abstract Schema inconsistencies or warning occurs during the parse, but application defined errorHandlers are not required to do so.

WRONG_MIME_TYPE_ERR: Raised when mimeTypeCheck is true and the input source has an incorrect MIME Type. See the attribute mimeTypeCheck.

DOMSystemException

Exceptions raised by parseURI() originate with the installed ErrorHandler, and thus depend on the implementation of the DOMErrorHandler interfaces. The default error handlers will raise a DOMSystemException if any form I/O or other system error occurs during the parse, but application defined error handlers are not required to do so.
Interface DOMASWriter

A Abstract Schema serialization interface.

DOMASWriters provides an API for serializing Abstract Schemas out in the form of a source Abstract Schema. The Abstract Schema is written to an output stream, the type of which depends on the specific language bindings in use.

DOMASWriter is a generic Abstract Schema serialization interface. It can be applied to both an internal Abstract Schema and/or an external Abstract Schema. DOMASWriter is applied to serialize a single Abstract Schema. Serializing a document with an active Internal Abstract Schema will serialize this internal Abstract Schema with the document as it is part of the Document (see DOMWriter).


IDL Definition
interface DOMASWriter : ls::DOMWriter {
  void               writeASModel(in DOMOutputStream destination, 
                                  in ASModel model)
                                        raises(DOMSystemException);
};

Methods
writeASModel
Write out the specified Abstract Schema to the specified destination.
Issue writeASModel-1:
Does it write a DTD or an XML Schema (or something else)? Is it possible to use this method to convert a DTD to an XML Schema?
Parameters
destination of type DOMOutputStream
The destination for the data to be written.
model of type ASModel
The Abstract Schema to serialize.
Exceptions

DOMSystemException

This exception will be raised in response to any sort of IO or system error that occurs while writing to the destination. It may wrap an underlying system exception.
No Return Value
previous   next   contents   index