previous   next   contents   index

14 January 2002

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) feature. This module provides a representation for XML abstract schemas, e.g., DTDs [XML 1.0] 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. RESOLVED: 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 NamespaceAware attribute to the generic AS object to help applications determine which of these fields are important, but we are still analyzing this challenge. Nonetheless, after much discussion, we have made the decision that only 1 active ASModel is allowed, even on ASDOMBuilder (the parser would set the 1 active schema).
  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. WON'T DEAL W/THIS FOR NOW: 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. RESOLVED: List of ASExceptions in the AS spec thus far: INVALID_CHARACTER_ERR, DUPLICATE_NAME_ERR, VALIDATION_ERR.
  12. I12. RESOLVED: 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. Will be done in CORE.
  13. I13. RESOLVED: 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. It was decided that the validate method 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 AS 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 addASModel().
  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. RESOLVED: Proposal needed to rename the asHint, asLocation attributes and tie that into how to describe an ASModel container of other ASModels.
  19. I19. TO BE DISCUSSED: Proposal to revise getElementDecl method and introduce other methods on the DocumentAS interface, such as getAttributeDecl, getNotationDecl, getEntityDecl. Some have mentioned that that these methods should better be added on ASModel to distinguish between where these declarations came from, the internal or external subset.
  20. I20. RESOLVED: If implementation doesn't support AS-editing, need to have each set method throw an unsupported exception. DONE.
  21. I21. TO BE DISCUSSED: Notion of read-only AS to be discussed. Currently, the activeASModel is read/write. Need to see where appropriate exceptions need to be thrown in a read-only AS. The methods affected are the following: addASModel, removeAS, importASObject, insertASObject, removedNamedItem, setNamedItem, addASAttributeDecl, removeASAttributeDecl, removesubModel, insertBeforesubModel, appendsubModel, setInternalAS, addAS, removeAS. For a read-only AS, the NO_MODIFICATION exception would be thrown when the feature string AS-READ is set.
  22. I22. RESOLVED: For developers, need to keep ASElementDecl in sync for both an ASModel and ASContentModel, if operations modify the ASElementDecl. Documentation was added in the ASElementDecl editing methods to reflect this.
  23. I23. RESOLVED: Need to clarify the descriptions on the ASModel internal/external subset and "global" attributes. Need to also introduce the concept of a dummy element declaration and dummy constant for element types not yet declared but appearing in the content model of another element type.
  24. I24. RESOLVED: Is there a need for ElementEditAS.getASElementDecl()? No longer in existence.
  25. I25. CAN BE RESOLVED: What happens when a user adds DOCTYPE nodes, when do you create a DOCTYPE after a change in ASModel or after the document has been created? The "can be resolved" is done via the "normalizeDocument" method since it will be able to update the DOCTYPE node according to the abstractschema.
  26. I26. TO BE DONE: Need to add a table for ASObject that is analogous to the table in DOM CORE for Node.

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:

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

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

ASElementDecl A = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASContentModel        = null;
    ASAttributeDecls      = null;
}

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

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

ASElementDecl C = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASContentModel        = null;
    ASAttributeDecls      = null;
}

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

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


IDL Definition
exception ASException {
  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;
const unsigned short      INVALID_CHARACTER_ERR          = 5;
const unsigned short      VALIDATION_ERR                 = 6;

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.
INVALID_CHARACTER_ERR
Raised if specified name contains an illegal character.
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 ASElementDecl.
VALIDATION_ERR
Raised if document is invalid.
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 1.0], 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 ASElementDecl, ASAttributeDecl, etc.


IDL Definition
interface ASModel : ASObject {

  // ASMODEL_TYPES
  const unsigned short      INTERNAL_SUBSET                = 1;
  const unsigned short      EXTERNAL_SUBSET                = 2;
  const unsigned short      NOT_USED                       = 3;

  readonly attribute boolean         NamespaceAware;
  readonly attribute unsigned short  usage;
           attribute DOMString       location;
           attribute DOMString       hint;
  readonly attribute boolean         container;
  readonly attribute ASNamedObjectMap elementDecls;
  readonly attribute ASNamedObjectMap attributeDecls;
  readonly attribute ASNamedObjectMap notationDecls;
  readonly attribute ASNamedObjectMap entityDecls;
  readonly attribute ASNamedObjectMap contentModelDecls;
  void               addASModel(in ASModel abstractSchema);
  ASObjectList       getASModels();
  void               removeAS(in ASModel as);
  boolean            validate();
  void               importASObject(in ASObject asobject);
  void               insertASObject(in ASObject asobject);
  ASElementDecl      createASElementDecl(in DOMString namespaceURI, 
                                         in DOMString name)
                                        raises(ASException);
  ASAttributeDecl    createASAttributeDecl(in DOMString namespaceURI, 
                                           in DOMString name)
                                        raises(ASException);
  ASNotationDecl     createASNotationDecl(in DOMString namespaceURI, 
                                          in DOMString name, 
                                          in DOMString systemId, 
                                          in DOMString publicId)
                                        raises(ASException);
  ASEntityDecl       createASEntityDecl(in DOMString name)
                                        raises(ASException);
  ASContentModel     createASContentModel(in DOMString name, 
                                          in DOMString namespaceURI, 
                                          in unsigned long minOccurs, 
                                          in unsigned long maxOccurs, 
                                          in unsigned short operator)
                                        raises(ASException);
};

Definition group ASMODEL_TYPES

A code representing how the ASModel is used.

Defined Constants
EXTERNAL_SUBSET
The ASModel is used as an external subset.
INTERNAL_SUBSET
The ASModel is used as an internal subset.
NOT_USED
The ASModel is neither used as an internal or external subset.
Attributes
NamespaceAware of type boolean, readonly
true if this ASModel defines the document structure is namespace-aware [XML Namespaces]; false if the document structure is non-namespace-aware.
attributeDecls of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level attribute declarations, i.e., not bound to sepecific element types but bound to the ASModel. If one attempts to add, set, or remove a object type other than the intended one, a hierarchy exception (or equivalent) is thrown. In addition, these attribute declarations can be associated with an incomplete element declaration, essentially an element with an undefined content model, indicated by the AS_UNDEFINED constant.
container of type boolean, readonly
If usage is EXTERNAL_SUBSET or NOT_USED, and the ASModel is simply a container of other ASModels.
contentModelDecls of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level content model declarations. If one attempts to add, set, or remove a object type other than the intended one, a hierarchy exception (or equivalent) is thrown.
elementDecls of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level (appearing directly on the ASModel) element declarations. If one attempts to add, set, or remove a object type other than the intended one, a hierarchy exception (or equivalent) is thrown. In addition, these element declarations can be incomplete, meaning that elements declared through an attribute list but without any corresponding element declarations can be represented and their content models undefined, as noted by the AS_UNDEFINED constant.
entityDecls of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level entity declarations. If one attempts to add, set, or remove a object type other than the intended one, a hierarchy exception (or equivalent) is thrown.
hint of type DOMString
The hint to locating an ASModel. For example, if an ASModel modeled a DTD, this could represent the public identifier; if an ASModel modeled a XML schema, this could represent a target namespace of a schema document. This attribute can also be NULL.
location of type DOMString
The URI reference. For example, if an ASModel modeled a DTD, this could represent the system identifier; if an ASModel modeled a XML schema, this could act as a hint to the location of a schema document. In addition, if a system identifier doesn't exist for an internet subset, then this attribute can be NULL.
notationDecls of type ASNamedObjectMap, readonly
Instead of returning an all-in-one ASObject with ASModel methods, have discernible top-level notation declarations. If one attempts to add, set, or remove a object type other than the intended one, a hierarchy exception (or equivalent) is thrown.
usage of type unsigned short, readonly
Uses INTERNAL_SUBSET, EXTERNAL_SUBSET, or NOT_USED. An exception will be raised if it is incompatibly shared or in use as an internal subset.
Methods
addASModel
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
createASAttributeDecl
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

ASAttributeDecl

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

ASException

INVALID_CHARACTER_ERR: Raised if the input name parameter contains an illegal character.
createASContentModel
Creates an object which describes part of an ASElementDecl's content model.
Parameters
name of type DOMString
The name of this ASContentModel.
namespaceURI of type DOMString
The namespace URI of this ASContentModel.
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

ASException

A ASException, e.g., minOccurs > maxOccurs.
createASElementDecl
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

ASElementDecl

A new ASElementDecl object with the ASObject objectName attribute set to name and namespaceURI set to namespaceURI. Other attributes of the element declaration are set through ASElementDecl and ASObject interface methods. Depending on the value of NamespaceAware, this method will take into account the namespaceURI parameter.
Exceptions

ASException

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

ASEntityDecl

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

ASException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.
createASNotationDecl
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 URI reference for the notation declaration.
publicId of type DOMString
The public identifier for the notation declaration.
Return Value

ASNotationDecl

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

ASException

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

ASObjectList

A list of ASModels.
No Parameters
No Exceptions
importASObject
Imports ASObject into ASModel.
Parameters
asobject of type ASObject
ASObject to be imported.
No Return Value
No Exceptions
insertASObject
Inserts ASObject into ASModel.
Parameters
asobject of type ASObject
ASObject to be inserted.
No Return Value
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
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.


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  ASObjectType;
  readonly attribute ASModel         ownerASModel;
           attribute DOMString       objectName;
           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 object is an ASAttributeDecl.
AS_CONTENTMODEL
The object is a ASContentModel.
AS_ELEMENT_DECLARATION
The object is an ASElementDecl.
AS_ENTITY_DECLARATION
The object is an ASEntityDecl.
AS_MODEL
The object is a ASModel.
AS_NOTATION_DECLARATION
The object is a ASNotationDecl.
Attributes
ASObjectType 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 object, or null if it is unspecified. [XML Schema Part 1] defines how a namespace URI is attached to schema components.
objectName of type DOMString
The name of this ASObject depending on the ASObject type.
ownerASModel of type ASModel, readonly
The ASModel object associated with this ASObject. For a object of type AS_MODEL, this is null.
prefix of type DOMString
The namespace prefix of this object, 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 objects, 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 object 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 objects 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 objects 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           item(in unsigned long index);
  ASObject           removeNamedItem(in DOMString name)
                                        raises(DOMException);
  ASObject           setNamedItem(in ASObject newASObject)
                                        raises(DOMException, 
                                               ASException);
};

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

ASObject

An ASObject with specified object name and null if the map does not contain an element with the given name.
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 objects 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 objectName.
Parameters
name of type DOMString
The objectName 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.
setNamedItem
Adds an ASObject using its objectName 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 objectName as the key.
Return Value

ASObject

If the new object replaces an existing one, the replaced object 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.

NOT_SUPPORTED_ERR: Raised if implementation doesn't support AS-editing.

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

ASException
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
A code representing an uri reference data type as defined in [XML Schema Part 2].
BASE64BINARY_DATATYPE
A code representing a 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
A code representing a byte data type as defined in [XML Schema Part 2].
COMPLEX_DATATYPE
A code representing a user-defined complex data type as defined in [XML Schema Part 2].
DATETIME_DATATYPE
A code representing a datetime data type as defined in [XML Schema Part 2].
DATE_DATATYPE
A code representing a date data type as defined in [XML Schema Part 2].
DECIMAL_DATATYPE
A code representing a 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
A code representing a duration data type as defined in [XML Schema Part 2].
ENTITIES_DATATYPE
A code representing a ENTITIES data type as defined in [XML Schema Part 2].
ENTITY_DATATYPE
A code representing a 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
A code representing a day data type as defined in [XML Schema Part 2].
GMONTHDAY_DATATYPE
A code representing a monthday data type as defined in [XML Schema Part 2].
GMONTH_DATATYPE
A code representing a month data type as defined in [XML Schema Part 2].
GYEARMONTH_DATATYPE
A code representing a yearmonth data type as defined in [XML Schema Part 2].
GYEAR_DATATYPE
A code representing a year data type as defined in [XML Schema Part 2].
HEXBINARY_DATATYPE
A code representing a hexbinary data type as defined in [XML Schema Part 2].
IDREFS_DATATYPE
A code representing a IDREFS data type as defined in [XML Schema Part 2].
IDREF_DATATYPE
A code representing a IDREF data type as defined in [XML Schema Part 2].
ID_DATATYPE
A code representing a ID data type as defined in [XML Schema Part 2].
INTEGER
A code representing a integer data type as defined in [XML Schema Part 2].
INT_DATATYPE
A code representing a integer data type as defined in [XML Schema Part 2].
LANGUAGE_DATATYPE
A code representing a Language data type as defined in [XML Schema Part 2].
LONG_DATATYPE
A code representing an 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
A code representing an negative integer data type as defined in [XML Schema Part 2].
NMTOKENS_DATATYPE
A code representing a NMTOKENS data type as defined in [XML Schema Part 2].
NMTOKEN_DATATYPE
A code representing a NMTOKEN data type as defined in [XML Schema Part 2].
NONNEGATIVEINTEGER_DATATYPE
A code representing a non-negative integer data type as defined in [XML Schema Part 2].
NONPOSITIVEINTEGER_DATATYPE
A code representing a 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
A code representing a NOTATION data type as defined in [XML Schema Part 2].
OTHER_SIMPLE_DATATYPE
A code representing a other simple data type as defined in [XML Schema Part 2].
POSITIVEINTEGER_DATATYPE
A code representing a positive integer data type as defined in [XML Schema Part 2].
QNAME_DATATYPE
A code representing an XML qualified name data type as defined in [XML Schema Part 2].
SHORT_DATATYPE
A code representing a 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
A code representing a time data type as defined in [XML Schema Part 2].
TOKEN_DATATYPE
A code representing a token data type as defined in [XML Schema Part 2].
UNSIGNEDBYTE_DATATYPE
A code representing a unsigned byte data type as defined in [XML Schema Part 2].
UNSIGNEDINT_DATATYPE
A code representing a unsigned integer data type as defined in [XML Schema Part 2].
UNSIGNEDLONG_DATATYPE
A code representing a unsigned long data type as defined in [XML Schema Part 2].
UNSIGNEDSHORT_DATATYPE
A code representing a 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 ASElementDecl

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


IDL Definition
interface ASElementDecl : 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 ASContentModel  ASContentModel;
           attribute ASNamedObjectMap ASAttributeDecls;
  void               addASAttributeDecl(in ASAttributeDecl attributeDecl);
  ASAttributeDecl    removeASAttributeDecl(in ASAttributeDecl attributeDecl);
};

Definition group CONTENT_MODEL_TYPES

A code representing the type of content model.

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 ASAttributeDecls for all the attributes that can appear on this type of element.
ASContentModel 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.
Methods
addASAttributeDecl
Adds an ASAttributeDecl for the element being declared.
Parameters
attributeDecl of type ASAttributeDecl
The new attribute to add. If the attribute declaration already exists for the element, the call does not have any effect. In addition, both ASModel and ASContentModel should be kept in sync after this operation.
No Return Value
No Exceptions
removeASAttributeDecl
Removes an ASAttributeDecl from the element being declared.
Parameters
attributeDecl of type ASAttributeDecl
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

ASAttributeDecl

null if the attribute does not exist. Otherwise returns the attribute being removed. In addition, both ASModel and ASContentModel should be kept in sync after this operation.
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;
  const unsigned short      AS_UNDEFINED                   = 4;

           attribute unsigned short  listOperator;
           attribute unsigned long   minOccurs;
           attribute unsigned long   maxOccurs;
           attribute ASObjectList    subModels;
  void               removesubModel(in ASObject oldObject);
  ASObject           insertBeforeSubModel(in ASObject newObject, 
                                          in ASObject refObject)
                                        raises(ASException);
  unsigned long      appendsubModel(in ASObject newObject)
                                        raises(ASException);
};

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
This content model represents a simplified version of the SGML &-Connector and is limited to the top-level of any content model. No element in the content model may appear more than once. Please refer to the definition element-all.
AS_CHOICE
This constant value signifies a choice operator. For example, in a DTD, this would be the '|' operator.
AS_NONE
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.
AS_UNDEFINED
This content model is undefined, and is associated with incomplete element declarations in the ASModel, meaning elements implicitly declared through an attribute list but without any corresponding element declarations.
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 the subModels. For example, if the list operator is 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 ASElementDecls and further ASContentModels.
Methods
appendsubModel
Appends a new object to the end of the list representing thesubModels.
Parameters
newObject of type ASObject
The new object to be appended.
Return Value

unsigned long

the length of the subModels.
Exceptions

ASException

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 ASElementDecl.
insertBeforeSubModel
Inserts a new object in the submodel before the existing reference object. Objects that already exist in the list are moved as needed.
Parameters
newObject of type ASObject
The new object to be inserted.
refObject of type ASObject
The reference object before which the new object is to be inserted.
Return Value

ASObject

The object being inserted.
Exceptions

ASException

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 ASElementDecl.
removesubModel
Removes the ASObject in the submodel. Objects that already exist in the list are moved as needed.
Parameters
oldObject of type ASObject
The object to be removed.
No Return Value
No Exceptions
Interface ASAttributeDecl

An attribute declaration in the context of a ASObject.


IDL Definition
interface ASAttributeDecl : ASObject {

  // VALUE_TYPES
  const unsigned short      NONE                           = 0;
  const unsigned short      DEFAULT                        = 1;
  const unsigned short      FIXED                          = 2;
  const unsigned short      REQUIRED                       = 3;

           attribute ASDataType      DataType;
           attribute DOMString       DataValue;
           attribute DOMString       enumAttr;
           attribute ASObjectList    ownerElements;
           attribute unsigned short  defaultType;
};

Definition group VALUE_TYPES
Defined Constants
DEFAULT
Indicates that there is a default value constraint.
FIXED
Indicates that there is a fixed value constraint for this attribute.
NONE
Describes that the attribute does not have any value constraint.
REQUIRED
Indicates that attribute is required.
Attributes
DataType of type ASDataType
Datatype of the attribute.
DataValue of type DOMString
Default or fixed value or null if there is none.
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 ASEntityDecl

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 ASEntityDecl : 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
One of the INTERNAL_ENTITY or EXTERNAL_ENTITY.
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 ASNotationDecl

This interface represents a notation declaration.


IDL Definition
interface ASNotationDecl : 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 (DOMImplementation methods).

Interface DocumentAS

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


IDL Definition
interface DocumentAS : Document {
           attribute ASModel         activeASModel;
           attribute ASObjectList    boundASModels;
  ASModel            getInternalAS();
  void               setInternalAS(in ASModel as)
                                        raises(DOMException);
  void               addAS(in ASModel as);
  void               removeAS(in ASModel as);
  ASElementDecl      getElementDecl()
                                        raises(DOMException);
  void               validate()
                                        raises(ASException);
};

Attributes
activeASModel of type ASModel
The active external ASModel. Validation is responsible for not only validating the document instance against the active external ASModel but also for consulting the internal ASModel, so if an attribute is declared in the internal ASModel and the corresponding ownerElements points to a ASElementDecls defined in the active external ASModel, changing the active external ASModel will cause the ownerElements to be recomputed during the validation of the document instance. If the ownerElements is not defined in the newly active external ASModel, the ownerElements will be an empty object list.
boundASModels of type ASObjectList
A list of ASObjects of type AS_MODELs associated with a document. The addAS method associates an ASModel with a document.
Methods
addAS
Associate an 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
getElementDecl
Gets the AS editing object describing this element
Issue getElementDecl-1:
This method needs to be changed and others added.
Return Value

ASElementDecl

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

DOMException

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

ASModel

ASModel.
No Parameters
No Exceptions
removeAS
Removes an 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.
Exceptions

DOMException

NOT_SUPPORTED_ERR: Raised if implementation doesn't support AS-editing.
No Return Value
validate
Validates the document against the ASModel. If the document is mutated during validation, a warning will be issued.
Exceptions

ASException

VALIDATION_ERR: Raised if an error occurs when the document is being validated against the abstract schema.
No Parameters
No Return Value
Interface DOMImplementationAS

This interface allows creation of an ASModel. It extends the DOMImplementation interface. An object that implements DOMImplementationAS is obtained by doing a binding specific cast from DOMImplementation to DOMImplementationAS.


IDL Definition
interface DOMImplementationAS : DOMImplementation {
  readonly attribute boolean         container;
           attribute DOMString       schemaType;
  ASModel            createAS(in boolean NamespaceAware, 
                              in DOMString schemaType);
};

Attributes
container of type boolean, readonly
To indicate if the ASModel is simply a container of other ASModels.
schemaType of type DOMString
This can specify a schema type or may be null if the implementation can infer the schema type.
Methods
createAS
Creates an ASModel.
Parameters
NamespaceAware of type boolean
Allow creation of ASModel with this attribute set to a specific value.
schemaType of type DOMString
This can specify a schema type or may be null if the implementation can infer the schema type.
Return Value

ASModel

An ASModel.
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.
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 : Node {

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

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 Node::insertBefore operation would make this document not partially valid with respect to the currently active AS.
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

ASException

NO_AS_AVAILABLE: Exception is 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.
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 nodes 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 nodes 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 elemTypeName 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 elemTypeName 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 "LS-AS" 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 ASDOMBuilder

An Abstract Schema parser interface.

ASDOMBuilder provides an API for parsing Abstract Schemas and building the corresponding ASModel tree. The actual ASDOMBuilder can be created by appropriately casting the object created by an implementation that supports AS.


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

Attributes
abstractSchema of type ASModel
The one active ASModel associated with a document instance. Note that the parser should set the one active ASModel.
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

ASException

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 ASException 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 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.
Parameters
uri of type DOMString
The location of the Abstract Schema to be read.
schemaType of type DOMString
This can specify a schema type or may be null if the implementation can infer a schema type.
Return Value

ASModel

The newly created Abstract Schema.
Exceptions

ASException

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 ASException 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.
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