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.
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.
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:
Requirements:
Specific to the AS-editing world, the following are use cases and requirements and could be labeled as the "AS-editing" section:
Use Cases:
Requirements:
Specific to the document-editing world, the following are use cases and requirements and could be labeled as the "Document-editing" section:
Use Cases:
Requirements:
DOMImplementationAS
and DOMImplementation?ASAttributeDecl.defaultType
attribute to constraintType
?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).
ASWModel.insertASObject
method? Can we remove this
method?ASWObjectList
?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?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.ASDOMBuilder.abstractSchema
allows to set a schema
on a parser instance. How can user set multiple schemas?DOMImplementationAS.createASModel
takes as a
parameter schemaType. What happens if user specifies
null
for the schemaType?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).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.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.ASWModel
container of other ASWModels.ASWModel
and ASWContentModel, if operations modify the ASWElementDecl.
Documentation was added in the ASWElementDecl editing methods to
reflect this.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.This section defines APIs for accessing, manipulating and modifying an abstract schema (database schema, DTD, XML Schema).
The set of Abstract Schema interfaces that are common for AS-READ and AS-EDIT.
This interface defines a set of constants used in AS model.
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; };
An integer indicating which type of ASConstants
this is.
ATTRIBUTE_DECLARATION
CONTENT_MODEL
ELEMENT_DECLARATION
ENTITY_DECLARATION
NOTATION_DECLARATION
SCHEMA_MODEL
A code representing how the ASModel
is used.
EXTERNAL_SUBSET
ASModel
is used as an external subset.INTERNAL_SUBSET
ASModel
is used as an internal subset.NOT_USED
ASModel
is neither used as an internal or external subset.An integer indicating which type of entity this is.
EXTERNAL_ENTITY
INTERNAL_ENTITY
A code representing the type of content model.
ANY_CONTENTTYPE
ELEMENT_CONTENTTYPE
EMPTY_CONTENTTYPE
MIXED_CONTENTTYPE
SIMPLE_CONTENTTYPE
List of content model compositors.
ALL_CM
ATOMIC_CM
subModel
includes a
single definition.CHOICE_CM
SEQUENCE_CM
UNDEFINED_CM
DEFAULT_VC
FIXED_VC
NONE_VC
REQUIRED_VC
UNBOUNDED
MAX_VALUE
value is 0xFFFFFFFF FFFFFFFF
.
The ASObject
interface is analogous to a
Node
in [DOM Level 3 Core], e.g., an element
declaration.
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); };
name
of type
DOMString
, readonlyNCName
of this declaration as
defined in [XML Namespaces].namespace
of type
DOMString
, readonlynull
if it is
unspecified. [XML Schema Part 1]defines how a namespace URI is
attached to schema components.objectType
of type unsigned
short
, readonlytype
of this object, ei.
ELEMENT_DECLARATION
.ownerModel
of type ASModel
,
readonlyASModel
object associated with this ASObject
. For a object of
type AS_MODEL
, this is null
.rawname
of type
DOMString
, readonlyrawname
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
.cloneASObject
ASObject
.
See text for cloneNode
off of Node
but
substitute AS functionality.
deep
of type
boolean
deep
flag on, causes the whole subtree
to be duplicated. Setting it to false
only duplicates
its immediate child nodes.
Cloned |
NOT_SUPPORTED_ERR: Raised if implementation doesn't support AS-EDIT. |
The datatypes supported by DOM AS implementations. Further datatypes may be added in the Schema/PSVI spec.
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; };
An integer indicating which datatype this is.
ANYSIMPLETYPE_DATATYPE
ANYTYPE_DATATYPE
ANYURI_DATATYPE
BASE64BINARY_DATATYPE
BOOLEAN_DATATYPE
BYTE_DATATYPE
DATETIME_DATATYPE
DATE_DATATYPE
DECIMAL_DATATYPE
DOUBLE_DATATYPE
DURATION_DATATYPE
ENTITIES_DATATYPE
ENTITY_DATATYPE
FLOAT_DATATYPE
GDAY_DATATYPE
GMONTHDAY_DATATYPE
GMONTH_DATATYPE
GYEARMONTH_DATATYPE
GYEAR_DATATYPE
HEXBINARY_DATATYPE
IDREFS_DATATYPE
IDREF_DATATYPE
ID_DATATYPE
INTEGER
INT_DATATYPE
LANGUAGE_DATATYPE
LONG_DATATYPE
NAME_DATATYPE
NCNAME_DATATYPE
NEGATIVEINTEGER_DATATYPE
NMTOKENS_DATATYPE
NMTOKEN_DATATYPE
NONNEGATIVEINTEGER_DATATYPE
NONPOSITIVEINTEGER_DATATYPE
NORMALIZEDSTRING_DATATYPE
NOTATION_DATATYPE
POSITIVEINTEGER_DATATYPE
QNAME_DATATYPE
SHORT_DATATYPE
STRING_DATATYPE
TIME_DATATYPE
TOKEN_DATATYPE
UNSIGNEDBYTE_DATATYPE
UNSIGNEDINT_DATATYPE
UNSIGNEDLONG_DATATYPE
UNSIGNEDSHORT_DATATYPE
dataType
of type unsigned
short
, readonlyThe 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.
interface ASObjectList { readonly attribute unsigned long length; ASObject item(in unsigned long index); };
item
index
th 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
.
index
of type
unsigned long
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.
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); };
length
of type
unsigned long
, readonlyASObjects
in the ASObjectList
.
The range of valid child object indices is 0 to
length-1
inclusive.getNamedItem
getNamedItemNS
namespaceURI
of type
DOMString
localName
of type
DOMString
item
index
th 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
.
index
of type
unsigned long
The |
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.
A read-only interface that represents an abstract schema.
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); };
container
of type
boolean
, readonlyusage
is EXTERNAL_SUBSET or NOT_USED, then the
ASModel
is simply a container of other ASModels.hint
of type DOMString
,
readonlyASModel
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
, readonlyASModel
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
, readonlytrue
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
, readonlygetAttributeDecl
name
of type
DOMString
targetNamespace
of type
DOMString
A top-level attribute declaration or null if such declaration does not exist. |
getComponents
objectType
of type
unsigned short
A list of top-level definition of the specified type in
|
getElementDecl
name
of type
DOMString
targetNamespace
of type
DOMString
A top-level element declaration or null if such declaration does not exist. |
getEntityDecl
name
of type
DOMString
An entity declaration or null if such declaration does not exist. |
getNotationDecl
name
of type
DOMString
targetNamespace
of type
DOMString
A top-level notation declaration or null if such declaration does not exist. |
The content model of a declared element.
interface ASContentModel : ASObject { readonly attribute unsigned short contentModelType; readonly attribute unsigned long minOccurs; readonly attribute unsigned long maxOccurs; readonly attribute ASObjectList subModels; };
contentModelType
of type unsigned short
, readonlyCHOICE_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
, readonly0
, a positive integer, or AS_UNBOUNDED
to
indicate that no upper limit has been set.minOccurs
of type
unsigned long
, readonlysubModels
of type
ASObjectList
,
readonlyASObject
s
of the following types: ELEMENT_DECLARATION
and
CONTENT_MODEL
.This interface represents an element declararation.
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); };
attributeDecls
of type
ASNamedObjectMap
,
readonlyASNamedObjectMap
containing ASAttributeDecls
for all the attributes that can appear on this type of
element.contentModel
of type ASContentModel
,
readonlycontentType
of type
unsigned short
, readonlyEMPTY_CONTENTTYPE
, SIMPLE_CONTENTTYPE
,
ELEMENT_CONTENTTYPE
,
MIXED_CONTENTTYPE
,ANY_CONTENTTYPE
.isPCDataOnly
of type
boolean
, readonlytrue
if the element is of type PCDATA only. Relevant
only for mixed content type elements.strictMixedContent
of type boolean
, readonlytype
of type
ASDataType
, readonlygetAttributeDecl
name
of type
DOMString
targetNamespace
of type
DOMString
A top-level attribute declaration or null if such declaration does not exist. |
An attribute declaration in the context of a ASObject
.
interface ASAttributeDecl : ASObject { readonly attribute ASDataType type; readonly attribute DOMString enumAttr; readonly attribute ASObjectList ownerElementDeclarations; readonly attribute unsigned short defaultType; readonly attribute DOMString value; };
defaultType
of type
unsigned short
, readonlyenumAttr
of type
DOMString
, readonlyownerElementDeclarations
of type ASObjectList
,
readonlyASObjectList
of element declarations that use this
ASAttributeDeclaration
.type
of type
ASDataType
, readonlyvalue
of type
DOMString
, readonlynull
if there is
none.Models a general entity declaration in an abstract schema.
interface ASEntityDecl : ASObject { readonly attribute unsigned short entityType; readonly attribute DOMString entityValue; readonly attribute DOMString systemId; readonly attribute DOMString publicId; };
entityType
of type
unsigned short
, readonlyINTERNAL_ENTITY
or
EXTERNAL_ENTITY
.entityValue
of type
DOMString
, readonlyEXTERNAL_ENTITY
this is
null
.publicId
of type
DOMString
, readonlynull
otherwise.systemId
of type
DOMString
, readonlynull
otherwise.This interface represents a notation declaration.
interface ASNotationDecl : ASObject { readonly attribute DOMString systemId; readonly attribute DOMString publicId; };
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; }
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.
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); };
addASModel
declaration
of type ASModel
addComponent
declaration
of type ASObject
createASWAttributeDecl
namespaceURI
of type
DOMString
name
of type
DOMString
A new |
INVALID_CHARACTER_ERR: Raised if the input |
createASWContentModel
ASWElementDecl
's
content model.
name
of type
DOMString
ASWContentModel
.namespaceURI
of type
DOMString
ASWContentModel
.minOccurs
of type
unsigned long
ASWContentModel
.maxOccurs
of type
unsigned long
ASWContentModel
.operator
of type
unsigned short
CHOICE_CM
,
SEQUENCE_CM
, ALL_CM
or
ATOMIC_CM
.
A new |
A |
createASWElementDecl
namespaceURI
of type
DOMString
namespace URI
of the element type being
declared.name
of type
DOMString
A new |
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
createASWEntityDecl
name
of type
DOMString
Name
) of the entity being
declared.
A new |
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
createASWNotationDecl
namespaceURI
of type
DOMString
name
of type
DOMString
systemId
of type
DOMString
publicId
of type
DOMString
A new |
INVALID_CHARACTER_ERR: Raised if the specified name contains an illegal character. |
getASModels
A list of ASModels. |
importASObject
insertASObject
removeASModel
declaration
of type ASModel
removeComponent
setHint
hint
of type
DOMString
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.setLocation
location
of type
DOMString
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.validate
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.
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); };
removeNamedItem
removeNamedItemNS
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.
namespaceURI
of type
DOMString
localName
of type
DOMString
ASObject
to remove.
The node removed from this map if a node with such a local name and namespace URI exists. |
|
NOT_FOUND_ERR: Raised if there is no node named
NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. |
setNamedItem
ASObject
using its objectName
attribute. If an ASObject
with that name is already present in this map, it is replaced by
the new one.
If the new object replaces an existing one, the replaced object
is returned, otherwise |
WRONG_MODEL_ERR: Raised if NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. |
|
setNamedItemNS
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.arg
of type ASObject
namespaceURI
and
localName
attributes.
WRONG_MODEL_ERR: Raised if NO_MODIFICATION_ALLOWED_ERR: Raised if this map is readonly. |
The element declaration.
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); };
addAttributeDecl
ASWAttributeDecl
for the element being declared.
attributeDecl
of type
ASWAttributeDecl
removeAttributeDecl
ASWAttributeDecl
from the element being declared.
attributeDecl
of type
ASWAttributeDecl
|
setContentModel
contentModel
of type
ASWContentModel
setContentType
contentType
of type
unsigned short
EMPTY_CONTENTTYPE, SIMPLE_CONTENT, ANY_CONTENTTYPE,
MIXED_CONTENTTYPE, ELEMENT_CONTENTTYPE
.setName
NCName
for
this declaration.
name
of type
DOMString
setNamespace
namespaceURI
of type
DOMString
setRawname
rawname
of type
DOMString
Name
for this
declaration.setStrictMixedContent
mixedContent
of type
boolean
setType
type
of type
ASDataType
The content model of a declared element.
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); };
appendSubModel
subModels
.
newObject
of type ASObject
|
the length of the |
DUPLICATE_NAME_ERR:Raised if a element declaration already
exists with the same name within an TYPE_ERR:Raised if type is neither an
|
insertBeforeSubModel
The object being inserted. |
DUPLICATE_NAME_ERR:Raised if a element declaration already
exists with the same name within an TYPE_ERR:Raised if type is neither an
|
removeSubModel
setContentModelType
operator
of type
unsigned short
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)
setMaxOccurs
maxOccurs
of type
unsigned long
0
, a positive integer, or AS_UNBOUNDED
to
indicate that no upper limit has been set.setMinOccurs
minOccurs
of type
unsigned long
setName
NCName
for
this declaration.
name
of type
DOMString
setNamespaceURI
namespaceURI
of type
DOMString
An attribute declaration.
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); };
setDefaultType
constraint
of type
unsigned short
setEnumAttr
enumeration
of type
DOMString
setName
NCName
for
this declaration.
name
of type
DOMString
setNamespaceURI
namespaceURI
of type
DOMString
setRawname
rawname
of type
DOMString
Name
for this
declaration.setType
type
of type
ASDataType
setValue
value
of type
DOMString
null
if there is
none.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.
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); };
setEntityType
type
of type unsigned
short
INTERNAL_ENTITY
or
EXTERNAL_ENTITY
.setEntityValue
value
of type
DOMString
EXTERNAL_ENTITY
this is
null
.setPublicId
publicId
of type
DOMString
null
otherwise.setRawname
rawname
of type
DOMString
Name
for this
declaration.setSystemId
systemId
of type
DOMString
null
otherwise.This interface represents a notation declaration.
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); };
setName
NCName
for
this declaration.
name
of type
DOMString
setNamespaceURI
namespaceURI
of type
DOMString
setPublicId
publicId
of type
DOMString
null
otherwise.setRawname
rawname
of type
DOMString
Name
for this
declaration.setSystemId
systemId
of type
DOMString
null
otherwise.This section contains "Validation and Other" interfaces common to "AS-READ", "AS-EDIT" and "AS-DOC" parts.
Abstract Schemas operations may throw a ASException
as
described in their descriptions.
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;
An integer indicating the type of error generated.
ACTIVEAS_DELETION_ERR
DUPLICATE_NAME_ERR
AS_CHOICE
operator.INVALID_CHARACTER_ERR
NO_AS_AVAILABLE
DocumentEditAS
related to the node does not
have any active ASModel
and wfValidityCheckLevel
is set to
PARTIAL
or STRICT_VALIDITY_CHECK
.TYPE_ERR
ASObject
is neither an ASContentModel
nor an ASElementDecl
.VALIDATION_ERR
WRONG_MIME_TYPE_ERR
mimeTypeCheck
is true
and the
input source has an incorrect MIME Type. See the attribute
mimeTypeCheck
.This interface extends the Document
interface with
additional methods for both document and AS editing.
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); };
activeASModel
of type ASModel
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 ASElementDecl
s
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
ASObject
s
of type SCHEMA_MODEL
s 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
.addAS
getAttributeDecl
node
of type
Attr
Attr
node for which attribute declaration is
to be retrieved.
An attribute declaration if available overwise
|
|
NOT_FOUND_ERR: Raised if no |
getElementDecl
node
of type
Element
Element
node for which element declaration is
to be retrieved.
An element declaration if available overwise
|
|
NOT_FOUND_ERR: Raised if no |
getEntityDecl
node
of type
Entity
Entity
node for which notation declaration is
to be retrieved.
A entity declaration if available overwise
|
|
NOT_FOUND_ERR: Raised if no |
getInternalAS
getNotationDecl
node
of type
Notation
Notation
node for which notation declaration
is to be retrieved.
A notation declaration if available overwise
|
|
NOT_FOUND_ERR: Raised if no |
removeAS
setInternalAS
validate
ASModel
.
If the document is mutated during validation, a warning will be
issued.
VALIDATION_ERR: Raised if an error occurs when the document is being validated against the abstract schema. |
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
.
interface DOMImplementationAS : DOMImplementation { ASWModel createASWModel(in boolean isNamespaceAware, in boolean container, in DOMString schemaType); };
createASWModel
ASWModel
.
isNamespaceAware
of type
boolean
ASWModel
with this attribute set to a specific value.container
of type
boolean
ASWModel
serves as a container for other ASWModels
.schemaType
of type
DOMString
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.
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.
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.
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:
namespaceNormalize
operation, which would
create the implied declarations and reconcile conflicts in some
reasonably standardized manner. This may be a major undertaking,
since some DOMs may be using the namespace to direct subclassing of
the nodes or similar special treatment; as with the existing
normalize
method, you may be left with a
different-but-equivalent set of node objects.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.
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.
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.
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); };
abstractSchema
of type ASWModel
ASWModel
associated with a document instance. Note that the parser should
set the one active ASWModel
.parseASInputSource
DOMInputSource
.
is
of type
ls::DOMInputSource
DOMInputSource
from which the source Abstract
Schema is to be read.schemaType
of type
DOMString
Exceptions raised by WRONG_MIME_TYPE_ERR: Raised when |
|
|
Exceptions raised by |
parseASURI
uri
of type
DOMString
schemaType
of type
DOMString
The newly created |
Exceptions raised by Raise a WRONG_MIME_TYPE_ERR when |
|
|
Exceptions raised by |
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
).
interface ASDOMWriter : ls::DOMWriter { void writeASModel(in DOMOutputStream destination, in ASModel model) raises(DOMSystemException); };
writeASModel
destination
of type
DOMOutputStream
model
of type ASModel
|
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. |