25 July 2002

1. Abstract Schemas Object Model

Editors:
Ben Chang, Oracle
Elena Litani, IBM
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 abstract schema editing worlds.

A DOM application can use the hasFeature method of the DOMImplementation interface to determine whether a given DOM supports these capabilities or not. This module defines 3 feature strings: "AS-READ" for read only access to abstract schemas, "AS-EDIT" editing of abstract schemas, and "AS-DOC" for document-editing interfaces.

This chapter interacts strongly with [DOM Level 3 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.

1.2. Issue List

1.2.1. Open Issues

Issue AS-Issue-8:
For Abstract Schemas interfaces (AS-READ/AS-EDIT) there should be no dependency on DOM Core. How can we remove inheritance between DOMImplementationAS and DOMImplementation?
Issue AS-Issue-9:
ASDatatype. Can we remove OTHER_SIMPLE_DATATYPE, COMPLEX_DATATYPE?
Issue AS-Issue-10:
ASDatatype. Do we need to add ANY_TYPE, ANY_SIMPLETYPE?
Issue AS-Issue-11:
ASWObjectList is live. What does it mean for ASObjectList to be live?
Issue AS-Issue-12:
Should we rename ASAttributeDecl.defaultType attribute to constraintType?
Issue AS-Issue-13:
Should default value constraint be added to ASDataType? This would include defaultType constraint and defaultValue.
Issue AS-Issue-14:
Clarify what exactly ASWModel represents: does it represent "a schema" as defined in XML Schema or a schema document? If it represents a "document" we should consider removing inheritance between ASModel and ASWModel interfaces (the inheritance between components should be kept).
Issue AS-Issue-15:
Is there any need for ASWModel.insertASObject method? Can we remove this method?
Issue AS-Issue-16:
Since each object carries a namespace do we need setNamedItemNS and removeNamedItemNS methods on ASWObjectList?
Issue AS-Issue-17:
Is there need for separation between ASObject.rawname and ASObject.name? Can "name" be defined as one attribute? If we need to keep ASObject.rawname, can we come up with another name? Qualified name can not be used because it does not include multiple colons. Also, the factory method have parameter name, should those include rawname as well?
Issue AS-Issue-18:
ASDOMBuilder allows to parse a schema document. The return type is ASWModel. This means that implementation that want to implement Loading of schemas must implement AS-EDIT. The return type should be a read-only object.
Issue AS-Issue-19:
ASDOMBuilder.abstractSchema allows to set a schema on a parser instance. How can user set multiple schemas?
Issue AS-Issue-20:
Does ASDOMWriter 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?
Issue AS-Issue-21:
The constants have a common suffix. Would not it easier to find the constants within same group alphabetically? In other words, should constants include common prefix instead?
Issue AS-Issue-22:
DOMImplementationAS.createASModel takes as a parameter schemaType. What happens if user specifies null for the schemaType?

1.2.2. Resolved Issues

Issue AS-Issue-1:
Should we add a constant for a datatype? Should ASDataType inherit from ASObject?
Resolution: ASObject does not need to model datatypes.
Issue AS-Issue-2:
INTERNAL_SUBSET, EXTERNAL_SUBSET, INTERNAL_ENTITY and EXTERNAL_ENTITY seem to carry the same meaning. Should _ENTITY constants be removed?
Resolution: No. The constants are used for different purposes and on different interfaces. It would be confusing for users to have same constant for 2 different purposes.
Issue AS-Issue-3:
Some components in Abstract Schema do not have name. ASObject serves as a base component for the model. Should it include names/namespace fields?
Resolution: Yes. It gives more flexibility to a user while manipulating/accessing objects in a list: no cast to type-specific interface is needed.
Issue AS-Issue-4:
We should remove ASElementDecl.isPCDataOnly and corresponding setPCDataOnly methods. Instead, lets introduce SIMPLE content type that will represent PCDataOnly for DTDs. In general, simple content means that conent consists only of character data (there are no elements in the content).
Resolution: Remove isPCDataOnly methods. Add SIMPLE_CONTENTTYPE constant.
Issue AS-Issue-5:
ASAttributeDecl.enumData is DTD only field. Can we remove this field?
Resolution: No.
Issue AS-Issue-6:
ASAttributeDecl.ownerElements became a readonly field. Implementation are expected to compute this field.
Resolution: Yes, this should be a readonly field.
Issue AS-Issue-7:
For the RW AS editing interfaces, exceptions need to be thrown for such operations if the AS-READ feature string is set.
Resolution: No. The implementation will always support AS-EDIT in this mode, no changing back and forth

1.2.2.1. General Issues

Issue 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 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).
Issue I2:
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.
Issue I3:
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.
Resolution: Won't deal w/this
Issue I4:
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.
Issue I5:
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.
Issue 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.
Resolution: Won't deal w/this for now.
Issue I7:
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.
Issue I8:
Rename the document-editing interfaces so they should have uniform names such as NodeEditAS, DocumentEditAS, ElementEditAS, etc.
Issue I9:
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.
Issue I10:
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.
Issue I11:
List of ASExceptions in the AS spec thus far: INVALID_CHARACTER_ERR, DUPLICATE_NAME_ERR, VALIDATION_ERR.
Issue 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. Will be done in CORE.
Issue 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. It was decided that the validate method be on DocumentAS.
Issue I14:
If entities are changed in the ASWModel, the underlying model is unchanged until normalization.
Issue I15:
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.
Issue I16:
There is a way to add a new schema file to the existing active compound schema via addASWModel().
Issue I17:
Altering the document during error reporting, or mutation during validation terminates validation, and a warning will be produced if this happens.
Issue I18:
Proposal needed to rename the asHint, asLocation attributes and tie that into how to describe an ASWModel container of other ASWModels.
Issue I19:
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 ASWModel to distinguish between where these declarations came from, the internal or external subset. RESOLUTION: added get*Decl methods on DocumentAS.
Issue I20:
If implementation doesn't support AS-editing, need to have each set method throw an unsupported exception. DONE.
Issue I21:
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: addASWModel, removeAS, importASObject, insertASObject, removedNamedItem, setNamedItem, addASWAttributeDecl, removeASWAttributeDecl, 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.
Resolution: The interfaces for Abstract Schema were split into read and read/write. New feature string introduced "AS-READ".
Issue I22:
For developers, need to keep ASWElementDecl in sync for both an ASWModel and ASWContentModel, if operations modify the ASWElementDecl. Documentation was added in the ASWElementDecl editing methods to reflect this.
Issue I23:
Need to clarify the descriptions on the ASWModel 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.
Issue I24:
Is there a need for ElementEditAS.getASWElementDecl()? No longer in existence.
Issue I25:
What happens when a user adds DOCTYPE nodes, when do you create a DOCTYPE after a change in ASWModel 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.
Issue I26:
TO BE DONE: Need to add a table for ASObject that is analogous to the table in DOM CORE for Node.
Issue I27:
TO BE DONE: "Unknown" validity needs to be accounted for validity states.
Issue I28:
Why have both setNamedItemNS and setNamedItem; and removeNameItemNS and removeNamedItem? One set can be eliminated, but CORE has similar functionality.

1.3. Abstract Schema API

This section defines APIs for accessing, manipulating and modifying an abstract schema (database schema, DTD, XML Schema).

1.3.1. Basic Abstract Schema Interfaces

The set of Abstract Schema interfaces that are common for AS-READ and AS-EDIT.

Interface ASConstants

This interface defines a set of constants used in AS model.


IDL Definition
interface ASConstants {

  // ASObject Types
  const unsigned short      ELEMENT_DECLARATION            = 1;
  const unsigned short      ATTRIBUTE_DECLARATION          = 2;
  const unsigned short      NOTATION_DECLARATION           = 3;
  const unsigned short      ENTITY_DECLARATION             = 4;
  const unsigned short      CONTENT_MODEL                  = 5;
  const unsigned short      SCHEMA_MODEL                   = 6;


  // Schema Model types
  const unsigned short      INTERNAL_SUBSET                = 30;
  const unsigned short      EXTERNAL_SUBSET                = 31;
  const unsigned short      NOT_USED                       = 32;


  // Entity Types
  const unsigned short      INTERNAL_ENTITY                = 33;
  const unsigned short      EXTERNAL_ENTITY                = 34;


  // Content Model Types
  const unsigned short      EMPTY_CONTENTTYPE              = 40;
  const unsigned short      SIMPLE_CONTENTTYPE             = 41;
  const unsigned short      ELEMENT_CONTENTTYPE            = 42;
  const unsigned short      MIXED_CONTENTTYPE              = 43;
  const unsigned short      ANY_CONTENTTYPE                = 44;


  // Content model compositors
  const unsigned short      SEQUENCE_CM                    = 50;
  const unsigned short      CHOICE_CM                      = 51;
  const unsigned short      ALL_CM                         = 52;
  const unsigned short      UNDEFINED_CM                   = 53;
  const unsigned short      ATOMIC_CM                      = 54;


  // Value Constraint
  const unsigned short      NONE_VC                        = 0;
  const unsigned short      DEFAULT_VC                     = 60;
  const unsigned short      FIXED_VC                       = 61;
  const unsigned short      REQUIRED_VC                    = 62;


  // Definition of unbounded
  const unsigned long       UNBOUNDED                      = MAX_VALUE;
};

Definition group ASObject Types

An integer indicating which type of ASConstants this is.

Defined Constants
ATTRIBUTE_DECLARATION
The object describes an attribute declaration.
CONTENT_MODEL
The object describes a content model definition.
ELEMENT_DECLARATION
The object describes an element declaration.
ENTITY_DECLARATION
The object describes an entity declaration.
NOTATION_DECLARATION
The object describes a notation declaration.
SCHEMA_MODEL
The object describes a schema model.
Definition group Schema Model 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.
Definition group Entity Types

An integer indicating which type of entity this is.

Defined Constants
EXTERNAL_ENTITY
A constant defining an external entity.
INTERNAL_ENTITY
A constant defining an internal entity.
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.
ELEMENT_CONTENTTYPE
Represents an element-only content type. An element-only content type validates elements with children that conform to the supplied content model.
EMPTY_CONTENTTYPE
Represents an EMPTY content type for an Element declaration. A content type with the distinguished value empty validates elements with no character or element information item children.
MIXED_CONTENTTYPE
Represents a MIXED content type for an Element declaration.
SIMPLE_CONTENTTYPE
The content model type simple. A content type which is a simple validates elements with character-only children.
Definition group Content model compositors

List of content model compositors.

Defined Constants
ALL_CM
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.
ATOMIC_CM
In this content model the subModel includes a single definition.
CHOICE_CM
This constant value signifies a choice operator. For example, in a DTD, this would be the '|' operator.
SEQUENCE_CM
This constant value signifies a sequence operator. For example, in a DTD, this would be the ',' operator.
UNDEFINED_CM
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.
Definition group Value Constraint
Defined Constants
DEFAULT_VC
Indicates that there is a default value constraint.
FIXED_VC
Indicates that there is a fixed value constraint for this attribute.
NONE_VC
Describes that the component does not have any value constraint.
REQUIRED_VC
Indicates that attribute is required.
Definition group Definition of unbounded
Defined Constants
UNBOUNDED
Signifies unbounded upper limit for a content model. The MAX_VALUE value is 0xFFFFFFFF FFFFFFFF.
(ED: This needs to be better defined in the generated bindings.)
Interface ASObject

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


IDL Definition
interface ASObject {
  readonly attribute unsigned short  objectType;
  readonly attribute ASModel         ownerModel;
  readonly attribute DOMString       rawname;
  readonly attribute DOMString       name;
  readonly attribute DOMString       namespace;
  ASObject           cloneASObject(in boolean deep)
                                        raises(ASException);
};

Attributes
name of type DOMString, readonly
The name of type NCName of this declaration as defined in [XML Namespaces].
namespace of type DOMString, readonly
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.
objectType of type unsigned short, readonly
The type of this object, ei. ELEMENT_DECLARATION.
ownerModel of type ASModel, readonly
The ASModel object associated with this ASObject. For a object of type AS_MODEL, this is null.
rawname of type DOMString, readonly
The rawname of this declaration of type Name as defined in [XML 1.0]. This value will be available only for schemas that allow to declare name of type Name.
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.

Exceptions

ASException

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

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      ANYSIMPLETYPE_DATATYPE         = 216;
  const unsigned short      ANYTYPE_DATATYPE               = 216;
};

Definition group DATA_TYPES

An integer indicating which datatype this is.

Defined Constants
ANYSIMPLETYPE_DATATYPE
A code representing a anySimpleType data type as defined in [XML Schema Part 2].
ANYTYPE_DATATYPE
A code representing a anyType data type as defined in [XML Schema Part 2].
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].
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].
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 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 ASObjectat 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.


IDL Definition
interface ASNamedObjectMap {
  readonly attribute unsigned long   length;
  ASObject           item(in unsigned long index);
  ASObject           getNamedItem(in DOMString name);
  ASObject           getNamedItemNS(in DOMString namespaceURI, 
                                    in DOMString localName);
};

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
getNamedItemNS
Retrieves a node specified by local name and namespace URI.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to retrieve.
localName of type DOMString
The local name of the node 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 node in this map.

No Exceptions
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

1.3.2. Read Only Abstract Schemas interfaces

The interfaces in this section provide a read-only access to abstract schemas.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-READ" and "3.0" (respectively) to determine whether or not this module is supported by the implementation.

Interface ASModel

A read-only interface that represents an abstract schema.


IDL Definition
interface ASModel : ASObject {
  readonly attribute boolean         namespaceAware;
  readonly attribute unsigned short  usage;
  readonly attribute DOMString       location;
  readonly attribute DOMString       hint;
  readonly attribute boolean         container;
  ASNamedObjectMap   getComponents(in unsigned short objectType);

  // Convenience method to retrive named top-level declarations

  ASElementDecl      getElementDecl(in DOMString name, 
                                    in DOMString targetNamespace);
  ASAttributeDecl    getAttributeDecl(in DOMString name, 
                                      in DOMString targetNamespace);
  ASEntityDecl       getEntityDecl(in DOMString name);
  ASNotationDecl     getNotationDecl(in DOMString name, 
                                     in DOMString targetNamespace);
};

Definition group Convenience method to retrive named top-level declarations
Attributes
container of type boolean, readonly
If usage is EXTERNAL_SUBSET or NOT_USED, then the ASModel is simply a container of other ASModels.
hint of type DOMString, readonly
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, readonly
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.
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.
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
getAttributeDecl
Returns a top-level attribute declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASAttributeDecl

A top-level attribute declaration or null if such declaration does not exist.

No Exceptions
getComponents
Returns a list of top-level component declarations: ei. element declarations, attribute declarations, etc.
Parameters
objectType of type unsigned short
The type of the declaration: ELEMENT_DECLARATION, ATTRIBUTE_DECLARATION, etc.
The parameter value SCHEMA_MODEL will retrieve a list of nested or imported ASModels if such list is available.
Return Value

ASNamedObjectMap

A list of top-level definition of the specified type in objectType or null.

No Exceptions
getElementDecl
Returns a top-level element declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASElementDecl

A top-level element declaration or null if such declaration does not exist.

No Exceptions
getEntityDecl
Returns an entity declaration.
Parameters
name of type DOMString
The name of the declaration.
Return Value

ASEntityDecl

An entity declaration or null if such declaration does not exist.

No Exceptions
getNotationDecl
Returns a top-level notation declaration.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASNotationDecl

A top-level notation declaration or null if such declaration does not exist.

No Exceptions
Interface ASContentModel

The content model of a declared element.


IDL Definition
interface ASContentModel : ASObject {
  readonly attribute unsigned short  contentModelType;
  readonly attribute unsigned long   minOccurs;
  readonly attribute unsigned long   maxOccurs;
  readonly attribute ASObjectList    subModels;
};

Attributes
contentModelType of type unsigned short, readonly
One of CHOICE_CM, SEQUENCE_CM, ALL_CM or ATOMIC_CM. The operator is applied to all the components(ASObjects) in the the subModels. For example, if the list operator is CHOICE_CM 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, readonly
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, readonly
min occurrence for this content particle. Its value may be 0 or a positive integer.
subModels of type ASObjectList, readonly
Pointers to ASObjects of the following types: ELEMENT_DECLARATION and CONTENT_MODEL.
Interface ASElementDecl

This interface represents an element declararation.


IDL Definition
interface ASElementDecl : ASObject {
  readonly attribute ASDataType      type;
  readonly attribute unsigned short  contentType;
  readonly attribute boolean         strictMixedContent;
  readonly attribute ASContentModel  contentModel;
  readonly attribute boolean         isPCDataOnly;
  readonly attribute ASNamedObjectMap attributeDecls;
  ASAttributeDecl    getAttributeDecl(in DOMString name, 
                                      in DOMString targetNamespace);
};

Attributes
attributeDecls of type ASNamedObjectMap, readonly
TheASNamedObjectMap containing ASAttributeDecls for all the attributes that can appear on this type of element.
contentModel of type ASContentModel, readonly
The content model of element.
contentType of type unsigned short, readonly
The content type of the element. One of EMPTY_CONTENTTYPE, SIMPLE_CONTENTTYPE, ELEMENT_CONTENTTYPE, MIXED_CONTENTTYPE,ANY_CONTENTTYPE.
isPCDataOnly of type boolean, readonly
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, readonly
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.
type of type ASDataType, readonly
Datatype of the element.
Methods
getAttributeDecl
A convenience method to get an attribute declaration by name.
Parameters
name of type DOMString
The name of the declaration.
targetNamespace of type DOMString
The namespace of the declaration, otherwise null.
Return Value

ASAttributeDecl

A top-level attribute declaration or null if such declaration does not exist.

No Exceptions
Interface ASAttributeDecl

An attribute declaration in the context of a ASObject.


IDL Definition
interface ASAttributeDecl : ASObject {
  readonly attribute ASDataType      type;
  readonly attribute DOMString       enumAttr;
  readonly attribute ASObjectList    ownerElementDeclarations;
  readonly attribute unsigned short  defaultType;
  readonly attribute DOMString       value;
};

Attributes
defaultType of type unsigned short, readonly
Constraint type if any for this attribute.
enumAttr of type DOMString, readonly
Valid attribute values, separated by commas, in a string.
ownerElementDeclarations of type ASObjectList, readonly
An ASObjectList of element declarations that use this ASAttributeDeclaration.
type of type ASDataType, readonly
Datatype of the attribute.
value of type DOMString, readonly
Default or fixed value or null if there is none.
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 in built.)

IDL Definition
interface ASEntityDecl : ASObject {
  readonly attribute unsigned short  entityType;
  readonly attribute DOMString       entityValue;
  readonly attribute DOMString       systemId;
  readonly attribute DOMString       publicId;
};

Attributes
entityType of type unsigned short, readonly
One of the INTERNAL_ENTITY or EXTERNAL_ENTITY.
entityValue of type DOMString, readonly
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, readonly
The string representing the public identifier for this entity declaration, if present; null otherwise.
systemId of type DOMString, readonly
The URI reference representing the system identifier for the entity declaration, if present, null otherwise.
Interface ASNotationDecl

This interface represents a notation declaration.


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

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

1.3.3. Abstract Schema Editing Interfaces

A list of the proposed Abstract Schema data structures and functions follow, starting off with the data structures and abstract schema editing methods.

A DOM application may use the hasFeature(feature, version) method of the DOMImplementation interface with parameter values "AS-EDIT" and "3.0" (respectively) to determine whether or not this module is supported by the implementation.

Note that operations on the ASWModel 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:

    ASWElementDecl example = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = exE;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exE = {
    contentModelType      = SEQUENCE_CM;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASWElementDecl A),
    (ASWContentModel exBC),
    (ASWContentModel exD)};
    }

    ASWElementDecl A = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exBC = {
    contentModelType      = CHOICE_CM;
    minOccurs             = 1;
    maxOccurs             = 1;
    subModels             = {(ASWContentModel exB),
    (ASWElementDecl C)};
    } 

    ASWContentModel exB = {
    contentModelType      = ATOMIC_CM;
    minOccurs             = 0;
    maxOccurs             = AS_UNBOUNDED;
    subModels             = {(ASWElementDecl B)};
    }
    ASWElementDecl B = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWElementDecl C = {
    strictMixedContent    = false;
    elementType           = STRING_DATATYPE;
    isPCDataOnly          = false;
    contentType           = ELEMENTS_CONTENTTYPE;
    ASWContentModel        = null;
    ASWAttributeDecls      = null;
    }

    ASWContentModel exD = {
    contentModelType     = ATOMIC_CM;
    minOccurs            = 1;
    maxOccurs            = AS_UNBOUNDED;
    subModels            = {(ASWElementDecl D)};
    }
    ASWElementDecl D = {
    strictMixedContent   = false;
    elementType          = STRING_DATATYPE;
    isPCDataOnly         = false;
    contentType          = ELEMENTS_CONTENTTYPE;
    ASWContentModel       = null;
    ASWAttributeDecls     = null;
    }
     
Interface ASWModel

To begin with, an abstract schema is a generic structure that could contain both internal and external subsets. An ASWModel 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 ASWModel could represent either an internal or an external subset; hence an abstract schema could be composed of an ASWModel representing the internal subset and an ASWModel representing the external subset. Note that the ASWModel representing the external subset could consult the ASWModel representing the internal subset. Furthermore, the ASWModel representing the internal subset could be set to null by the setInternalAS() method as a mechanism for "removal". In addition, only one ASWModel representing the external subset can be specified as "active" and it is possible that none are "active". Finally, the ASWModel contains the factory methods needed to create a various types of ASObjects like ASWElementDecl, ASWAttributeDecl, etc.


IDL Definition
interface ASWModel : ASModel {
  void               setLocation(in DOMString location);
  void               setHint(in DOMString hint);
  void               addComponent(in ASObject declaration);
  void               removeComponent(in ASObject declaration);
  void               addASModel(in ASModel declaration);
  void               removeASModel(in ASModel declaration);
  ASObjectList       getASModels();
  ASObject           importASObject(in ASObject asobject);
  void               insertASObject(in ASObject asobject);
  boolean            validate();
  ASWElementDecl     createASWElementDecl(in DOMString namespaceURI, 
                                          in DOMString name)
                                        raises(ASException);
  ASWAttributeDecl   createASWAttributeDecl(in DOMString namespaceURI, 
                                            in DOMString name)
                                        raises(ASException);
  ASWNotationDecl    createASWNotationDecl(in DOMString namespaceURI, 
                                           in DOMString name, 
                                           in DOMString systemId, 
                                           in DOMString publicId)
                                        raises(ASException);
  ASWEntityDecl      createASWEntityDecl(in DOMString name)
                                        raises(ASException);
  ASWContentModel    createASWContentModel(in DOMString name, 
                                           in DOMString namespaceURI, 
                                           in unsigned long minOccurs, 
                                           in unsigned long maxOccurs, 
                                           in unsigned short operator)
                                        raises(ASException);
};

Methods
addASModel
Adds ASModel to the list of ASModels.
Parameters
declaration of type ASModel
An ASModel to be added
No Return Value
No Exceptions
addComponent
Add top-level component declaration to a list of those definitions.
Parameters
declaration of type ASObject
A component declaration.
No Return Value
No Exceptions
createASWAttributeDecl
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 ASWModel-dependent.
Return Value

ASWAttributeDecl

A new ASWAttributeDecl object with appropriate attributes set by input parameters.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the input name parameter contains an illegal character.

createASWContentModel
Creates an object which describes part of an ASWElementDecl's content model.
Parameters
name of type DOMString
The name of this ASWContentModel.
namespaceURI of type DOMString
The namespace URI of this ASWContentModel.
minOccurs of type unsigned long
The minimum occurrence for the subModels of this ASWContentModel.
maxOccurs of type unsigned long
The maximum occurrence for the subModels of this ASWContentModel.
operator of type unsigned short
operator of type CHOICE_CM, SEQUENCE_CM, ALL_CM or ATOMIC_CM.
Return Value
Exceptions

ASException

A ASException, e.g., minOccurs > maxOccurs.

createASWElementDecl
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 ASWModel-dependent.
Return Value

ASWElementDecl

A new ASWElementDecl object with the ASObject objectName attribute set to name and namespaceURI set to namespaceURI. Other attributes of the element declaration are set through ASWElementDecl 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.

createASWEntityDecl
Creates an ASWEntityDecl.
Parameters
name of type DOMString
The name (of type Name) of the entity being declared.
Return Value

ASWEntityDecl

A new ASWEntityDecl object with entityName attribute set to name.

Exceptions

ASException

INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character.

createASWNotationDecl
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 ASWModel-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

ASWNotationDecl

A new ASWNotationDecl 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
Returns a list of ASModels.
Return Value

ASObjectList

A list of ASModels.

No Parameters
No Exceptions
importASObject
Imports ASObject into ASWModel.
Parameters
asobject of type ASObject
ASObject to be imported.
Return Value

ASObject

The ASObject that is imported.

No Exceptions
insertASObject
Inserts ASObject into ASWModel.
Parameters
asobject of type ASObject
ASObject to be inserted.
No Return Value
No Exceptions
removeASModel
Removes ASModel from the list of ASModels.
Parameters
declaration of type ASModel
An ASModel to be removed
No Return Value
No Exceptions
removeComponent
Removes the specified ASObject from the list of top-level declarations.
Parameters
declaration of type ASObject
A component declaration to be removed
No Return Value
No Exceptions
setHint
Set hint for the ASWModel.
Parameters
hint of type DOMString
The hint to locating an ASWModel. For example, if an ASWModel modeled a DTD, this could represent the public identifier; if an ASWModel modeled a XML schema, this could represent a target namespace of a schema document. This attribute can also be NULL.
No Return Value
No Exceptions
setLocation
Set location of schema model.
Parameters
location of type DOMString
The URI reference. For example, if an ASWModel modeled a DTD, this could represent the system identifier; if an ASWModel 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.
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 ASWNamedObjectMap

Objects implementing the ASWNamedObjectMap 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.

ASWNamedObjectMap object in the DOM are live.

Issue NamedObjectMap-live:
Should named node map be live?

IDL Definition
interface ASWNamedObjectMap : ASNamedObjectMap {
  ASObject           removeNamedItem(in DOMString name)
                                        raises(ASException);
  ASObject           setNamedItem(in ASObject newASObject)
                                        raises(ASException, 
                                               ASException);
  ASObject           setNamedItemNS(in ASObject arg)
                                        raises(ASException);
  ASObject           removeNamedItemNS(in DOMString namespaceURI, 
                                       in DOMString localName)
                                        raises(DOMException);
};

Methods
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

ASException

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 a node specified by local name and namespace URI. A removed attribute may be known to have a default value when this map contains the attributes attached to an element, as returned by the attributes attribute of the ASObject interface. If so, an attribute immediately appears containing the default value as well as the corresponding namespace URI, local name, and prefix when applicable.
Parameters
namespaceURI of type DOMString
The namespace URI of the node to remove.
localName of type DOMString
The local name of the ASObject to remove.
Return Value

ASObject

The node removed from this map if a node with such a local name and namespace URI 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

ASException

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

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

ASException

setNamedItemNS
Adds a node using its namespaceURI and localName. If a node with that namespace URI and that local name is already present in this map, it is replaced by the new one.
Per [XML Namespaces], applications must use the value null as the namespaceURI parameter for methods if they wish to have no namespace.
Parameters
arg of type ASObject
A node to store in this map. The node will later be accessible using the value of its namespaceURI and localName attributes.
Return Value

ASObject

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

Exceptions

ASException

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

NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly.

Interface ASWElementDecl

The element declaration.


IDL Definition
interface ASWElementDecl : ASElementDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespace(in DOMString namespaceURI);
  void               setStrictMixedContent(in boolean mixedContent);
  void               setType(in ASDataType type);
  void               setContentType(in unsigned short contentType);
  void               setContentModel(in ASWContentModel contentModel);
  void               addAttributeDecl(in ASWAttributeDecl attributeDecl);
  ASWAttributeDecl   removeAttributeDecl(in ASWAttributeDecl attributeDecl);
};

Methods
addAttributeDecl
Adds an ASWAttributeDecl for the element being declared.
Parameters
attributeDecl of type ASWAttributeDecl
The new attribute declaration to add. If the attribute declaration already exists for the element, the call does not have any effect.
No Return Value
No Exceptions
removeAttributeDecl
Removes an ASWAttributeDecl from the element being declared.
Parameters
attributeDecl of type ASWAttributeDecl
The attribute declaration to be removed. If the attribute declaration does not exist for the element, the call does not have any effect.
Return Value

ASWAttributeDecl

null if the attribute does not exist. Otherwise returns the attribute being removed.

No Exceptions
setContentModel
Set the content model for this element declaration.
Parameters
contentModel of type ASWContentModel
The content model of element.
No Return Value
No Exceptions
setContentType
Set content type for this element declaration.
Parameters
contentType of type unsigned short
The content type of the element. One of EMPTY_CONTENTTYPE, SIMPLE_CONTENT, ANY_CONTENTTYPE, MIXED_CONTENTTYPE, ELEMENT_CONTENTTYPE .
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespace
Set the namespace for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setStrictMixedContent
Set mixed content.
Parameters
mixedContent 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.
No Return Value
No Exceptions
setType
Set the type for this element declaration.
Parameters
type of type ASDataType
The datatype for this element declaration.
No Return Value
No Exceptions
Interface ASWContentModel

The content model of a declared element.


IDL Definition
interface ASWContentModel : ASContentModel {
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setContentModelType(in unsigned short operator);
  void               setMinOccurs(in unsigned long minOccurs);
  void               setMaxOccurs(in unsigned long maxOccurs);
  void               removeSubModel(in ASObject oldObject);
  ASObject           insertBeforeSubModel(in ASObject newObject, 
                                          in ASObject refObject)
                                        raises(ASException);
  unsigned long      appendSubModel(in ASObject newObject)
                                        raises(ASException);
};

Methods
appendSubModel
Appends a new ASObject 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 ASWContentModel nor an ASWElementDecl.

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 ASWContentModel nor an ASWElementDecl.

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
setContentModelType
Set content model type
Parameters
operator of type unsigned short
One of CHOICE_CM, SEQUENCE_CM, ALL_CM, ATOMIC_CM, or UNDEFINED_CM. The operator is applied to all the components(ASObjects) in the the subModels. For example, if the content model type is CHOICE_CM and the components in subModels are a, b and c then the abstract schema for the element being declared is (a|b|c)
No Return Value
No Exceptions
setMaxOccurs
Set maxOccurs for the content model
Parameters
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.
No Return Value
No Exceptions
setMinOccurs
Set minOccurs for the content model
Parameters
minOccurs of type unsigned long
min occurrence for this content particle. Its value may be 0 or a positive integer.
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
Interface ASWAttributeDecl

An attribute declaration.


IDL Definition
interface ASWAttributeDecl : ASAttributeDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setType(in ASDataType type);
  void               setValue(in DOMString value);
  void               setEnumAttr(in DOMString enumeration);
  void               setDefaultType(in unsigned short constraint);
};

Methods
setDefaultType
Set constraint for the attribute's value
Parameters
constraint of type unsigned short
Constraint type if any for this attribute.
No Return Value
No Exceptions
setEnumAttr
Set enumeration value for this attribute
Parameters
enumeration of type DOMString
Valid attribute values, separated by vertical bars, in a string.
No Return Value
No Exceptions
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setType
Set the type for this attribute declaration.
Parameters
type of type ASDataType
The datatype for this attribute declaration.
No Return Value
No Exceptions
setValue
Set default or fixed value for this attribute
Parameters
value of type DOMString
Default or fixed value or null if there is none.
No Return Value
No Exceptions
Interface ASWEntityDecl

Models a general entity declaration in an abstract schema.

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 ASWEntityDecl : ASEntityDecl {
  void               setRawname(in DOMString rawname);
  void               setEntityType(in unsigned short type);
  void               setEntityValue(in DOMString value);
  void               setSystemId(in DOMString systemId);
  void               setPublicId(in DOMString publicId);
};

Methods
setEntityType
Set the type for this entity declaration
Parameters
type of type unsigned short
One of the INTERNAL_ENTITY or EXTERNAL_ENTITY.
No Return Value
No Exceptions
setEntityValue
Set entity value.
Parameters
value 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.
No Return Value
No Exceptions
setPublicId
Set publicId for this entity
Parameters
publicId of type DOMString
The string representing the public identifier for this entity declaration, if present; null otherwise.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setSystemId
Set systemId for this entity
Parameters
systemId of type DOMString
The URI reference representing the system identifier for the entity declaration, if present, null otherwise.
No Return Value
No Exceptions
Interface ASWNotationDecl

This interface represents a notation declaration.


IDL Definition
interface ASWNotationDecl : ASNotationDecl {
  void               setRawname(in DOMString rawname);
  void               setName(in DOMString name);
  void               setNamespaceURI(in DOMString namespaceURI);
  void               setSystemId(in DOMString systemId);
  void               setPublicId(in DOMString publicId);
};

Methods
setName
Set the name of type NCName for this declaration.
Parameters
name of type DOMString
The name for this declaration.
No Return Value
No Exceptions
setNamespaceURI
Set the namespace URI for this declaration.
Parameters
namespaceURI of type DOMString
The namespace URI for this declaration.
No Return Value
No Exceptions
setPublicId
Set publicId for this entity
Parameters
publicId of type DOMString
The string representing the public identifier for this notation declaration, if present; null otherwise.
No Return Value
No Exceptions
setRawname
Set the rawname for this declaration.
Parameters
rawname of type DOMString
The rawname of type Name for this declaration.
No Return Value
No Exceptions
setSystemId
Set systemId for this entity
Parameters
systemId of type DOMString
The URI reference representing the system identifier for the notation declaration, if present, null otherwise.
No Return Value
No Exceptions

1.4. Validation and Other Interfaces

This section contains "Validation and Other" interfaces common to "AS-READ", "AS-EDIT" and "AS-DOC" parts.

Exception ASException

Abstract Schemas operations may throw a ASException 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;
const unsigned short      ACTIVEAS_DELETION_ERR          = 7;

Definition group ASExceptionCode

An integer indicating the type of error generated.

Defined Constants
ACTIVEAS_DELETION_ERR
Raised if boundASModels is being set or removed and the activeASModel is not one of them.
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 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)
                                        raises(ASException);
  ASElementDecl      getElementDecl(in Element node)
                                        raises(DOMException);
  ASAttributeDecl    getAttributeDecl(in Attr node)
                                        raises(DOMException);
  ASEntityDecl       getEntityDecl(in Entity node)
                                        raises(DOMException);
  ASNotationDecl     getNotationDecl(in Notation node)
                                        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 SCHEMA_MODELs associated with a document. The addAS method associates an ASModel with a document. An exception ACTIVEAS_DELETION_ERR is thrown if the activeASModel is not one of the boundASModels.
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
getAttributeDecl
Gets the abstract schema declaration for the attribute node.
Parameters
node of type Attr
The Attr node for which attribute declaration is to be retrieved.
Return Value

ASAttributeDecl

An attribute declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getElementDecl
Gets the abstract schema declaration for the element node.
Parameters
node of type Element
The Element node for which element declaration is to be retrieved.
Return Value

ASElementDecl

An element declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getEntityDecl
Gets the abstract schema declaration for the entity node.
Parameters
node of type Entity
The Entity node for which notation declaration is to be retrieved.
Return Value

ASEntityDecl

A entity declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

getInternalAS
Retrieve the internal ASModel of a document.
Return Value
No Parameters
No Exceptions
getNotationDecl
Gets the abstract schema declaration for the notation node.
Parameters
node of type Notation
The Notation node for which notation declaration is to be retrieved.
Return Value

ASNotationDecl

A notation declaration if available overwise null.

Exceptions

DOMException

NOT_FOUND_ERR: Raised if no ASModel is attached to the document.

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

ASException

ACTIVEAS_DELETION_ERR: Raised if removing boundASModels and the activeASModel is not one of them.

No Return Value
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 ASWModel. 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 {
  ASWModel           createASWModel(in boolean isNamespaceAware, 
                                    in boolean container, 
                                    in DOMString schemaType);
};

Methods
createASWModel
Creates an ASWModel.
Parameters
isNamespaceAware of type boolean
Allow creation of ASWModel with this attribute set to a specific value.
container of type boolean
Specifies that ASWModel serves as a container for other ASWModels.
schemaType of type DOMString
An absolute URI representing the type of the schema language. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value
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 [DOM Level 3 Load and Save] module to permit to load a Document using a specific ASWModel and to load an ASWModel 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 ASWModel 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 ASWModel        abstractSchema;
  ASWModel           parseASURI(in DOMString uri, 
                                in DOMString schemaType)
                                        raises(ASException, 
                                               DOMSystemException);
  ASWModel           parseASInputSource(in ls::DOMInputSource is, 
                                        in DOMString schemaType)
                                        raises(ASException, 
                                               DOMSystemException);
};

Attributes
abstractSchema of type ASWModel
The one active ASWModel associated with a document instance. Note that the parser should set the one active ASWModel.
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.
schemaType of type DOMString
An absolute URI representing the type of the schema language or null if the implementation can infer a schema type. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value

ASWModel

The newly created ASWModel.

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
An absolute URI representing the type of the schema language or null if the implementation can infer a schema type. Note: For W3C XML Schema [XML Schema Part 1], applications must use the value "http://www.w3.org/2001/XMLSchema". For XML DTD [XML 1.0], applications must use the value "http://www.w3.org/TR/REC-xml". Other Schema languages are outside the scope of the W3C and therefore should recommend an absolute URI in order to use this method.
Return Value

ASWModel

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 ASDOMWriter

A Abstract Schema serialization interface.

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

ASDOMWriter 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 ASDOMWriter : ls::DOMWriter {
  void               writeASModel(in DOMOutputStream destination, 
                                  in ASModel model)
                                        raises(DOMSystemException);
};

Methods
writeASModel
Write out the specified Abstract Schema to the specified destination.
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