Enabling Architecture Definition Requirements (EADR)

This annex states the requirements for the formal definition of the architectural forms by which an enabling document architecture governs the SGML representation of its documents. The formal definitions of the HyTime architectural forms satisfy these requirements and (without loss of generality) are used to illustrate them.

Architectural forms

A document architecture, as that term is defined in ISO 8879, can be "encompassing", governing every aspect of its documents' representation and processing. The document representation requirements for an encompassing architecture are expressed formally -- at least insofar as SGML is capable of expressing them -- in a document type definition (DTD).

A document architecture can also be "enabling", in which case it does not specify complete document types. Instead, an enabling architecture defines rules, known as "architectural forms", that application designers can apply in their document type definitions. The set of architectural forms and related declarations for an enabling architecture comprises a "meta-DTD".

Architectural forms are rules for creating and processing elements (just as document architectures are rules for creating and processing documents). Architectural forms are specified principally by attribute definitions, one of which is the "ArcForm" attribute, whose value identifies the form. However, an architectural form can also include rules for constructing the content models of element types conforming to the form.

There are two kinds of architectural form: element type form This is defined by an element type declaration in conjunction with an attribute definition list declaration. attribute list form This is defined solely by an attribute definition list declaration. Its attribute definitions can be used only with designated element type forms or data content notations.

An element type that conforms to an element type form defined by, say, the "ArcName" architecture, is informally called an "ArcName element type", even though the element type itself is not defined by the ArcName architecture, but by an application. An instance of such an ArcName element type is called an "ArcName element". An element, notation, data string, or attribute that does not conform to an architectural form is termed "non-architectural".

An application DTD can include element types of different enabling architectures, element types that conform to no formally-defined architecture (other than the encompassing architecture of the DTD itself), and element types that conform to several enabling architectures at once. Where multiple architectures govern a document, the rules of each are enforced without regard to objects that are non-architectural with respect to it.

An element cannot conform to more than one element type form of a given architecture. It can, however, conform to multiple attribute list forms unless prohibited by the rules of the particular architecture.

The architectures that govern a DTD are called its "base" architectures and the DTD is their client. An architecture can itself be governed by one or more base architectures; it is termed a "derived" architecture.

SGML conventions

The syntax and structure of architectural forms and element types are specified rigorously using SGML markup declarations. The declarations include comments, called "conventional comments", that follow conventions established in this sub-clause to specify architectural constructs and constraints that are enforced by an architecture implementation (called an "engine") and an SGML parser. The declarations conform to valid SGML syntax in every respect. This practice permits the declarations to be copied for use as models when creating DTDs conforming to the architecture. The conventional comments do not extend SGML in any way. They are used in the architecture definitions only, as a notation for the documentation of the architecture. They need not be included in application DTDs and, if they are included, the SGML parser will treat them as it would any other comment. An architecture engine must be aware of the information the comments convey. Although some if it could be interpreted automatically, the rest must be read by programmers creating engines, not by the engines themselves. .******* FIX UP to distinguish stuff from this annex, meta-DTD, and DTD .******* Cover entities and notations also; and Templates

Declarations that define architectural forms are presented with the declaration names in lower-case. Those that define element types (that is, not element type forms) follow the normal SGML convention; their declaration names are presented in upper-case. Note that the names of architectural forms, unlike those of element types, are not necessarily meant to be used in DTDs. Although element type form names can be used when the application requires only one element type that conforms to the form, the names of attribute list forms never are, as they have no counterparts in a DTD. .****

Element type forms

An element type form is defined by an element type declaration in conjunction with an attribute list declaration.

Element type declaration

The structure of an element type form is defined by a "meta" content model in the element type declaration. The model is "meta" in the sense that its "element types" are really architectural forms and mean "any element conforming to that form". An application DTD could therefore define several element types conforming to a given architectural form. Moreover, each could have a different content model as long as it allowed content that satisfies the meta-model.

The text of the architecture definition document states whether the architecture associates any semantics with the content of an element type form. If the text is silent, the elements have no special semantics in their role as content of their containing element. However, they still have their normal architectural semantics as individual elements. For example, no special HyTime semantics are defined for the content of an activity tracking policy element, but a contextual link element occurring in the content would retain its normal HyTime semantics.

As with a normal content model, a meta-model can incorporate inclusion exceptions. Use of inclusions in this way means that elements of the named forms can occur anywhere in the content in the document instance, including the content of subordinate elements. The application designer can choose, in his DTD, to require the elements to be proper subelements, inclusions, or both. An example of a content meta-model with an inclusion is: ]]> The construct "(a | b | c)*" is a model group while "+(x | y)" is called an "inclusion exception" in SGML. It means that the element types in parentheses can occur at any level of the element structure. In contrast, element types in the model group can occur only as "proper subelements", in the immediate content.

Character data content can be further qualified (beyond the normal SGML tokens) by means of the "HyLex" notation and "reftype" conventional comments, which are described in connection with their use in documenting attribute values in . Use of HyLex and reftype in architectural form definitions does not mean that an architecture must support their use by its applications.

Meta-DTD

The set of declarations defined in an architecture definition collectively represent a meta-DTD. The occurrence of an architectural object in a document instance is checked against the meta-DTD to see if it is allowed. Other objects are not checked. Data is considered architectural only when it occurs at a point where the meta-DTD requires data; otherwise it does not affect the checking against the meta-DTD.

Any failure of a document instance to conform to the meta-DTD is a reportable architecture error (RAE). In particular:

An application DTD can impose constraints on the meta-DTD by prohibiting the occurrence of some architectural forms in specific contexts. For example, the HyTime meta-DTD allows hyperlink elements as inclusions. A HyTime application, though, could allow elements conforming to hyperlink forms to occur only as proper subelements, only as inclusions, or not at all.

An architecture does not constrain the construction of document type definitions, only document instances. For example, any valid document type definition can declare HyTime as a base architecture, as long as its document instance conforms to HyTime. A validating architecture engine can optionally report DTD constructs (such as poorly designed content models) that would prevent the creation of a valid conforming instance, or that would allow the creation of a nonconforming instance.

A meta-DTD is flexible and does not necessarily clarify all issues of contextual relevance; some elements may be meaningful only in the context of other elements from which they are referenced, or only as resources for the processing of other elements.

The meta-DTD comprising all of the SGML definitions of an architecture necessarily includes all of the architecture's optional facilities (if any). In contrast, for any given architecture implementation's system declaration (see ) there will be a single meta-DTD that permits only the optional facilities supported by that system. Moreover, the actual meta-DTD applicable to a given document could be different from either of those, depending on the facilities required by that document (see ). The constraints of a more restrictive meta-DTD that is required by a document's architecture support declarations can also be enforced by the document's DTD. The declared content or content model of an application's element type can differ from the meta-model of the architectural form as long as it allows instances that conform to the architectural form meta-model. For example, a meta-model might be "(a|b|c)". An application designer could legally exclude the possibility of "c" by using the content model "(a|b)" (or even "(a|x)", except that if an "x" occurred in the instance it would be an RAE).

As with normal DTDs, parameter entities can be used in the construction of meta-DTDs. The parameter entity declarations are primarily an aid for tailoring the meta-DTD to correspond to any modularization of facilities supported by the architecture. They also serve to document relationships among the architectural forms, but otherwise have no semantic significance. For example, the facilities in HyTime are grouped into "modules" that correspond to clauses of the HyTime International Standard. If the "pathloc" option of the location address module is not supported by an implementation, the meta-DTD can be modified easily by deleting the string "pathloc|" (which corresponds to the option) from the entity declaration for "loc" (which corresponds to the module).

The meta-DTD of a derived architecture is a "derived meta-DTD". The meta-DTDs of its base architectures are its "base meta-DTDs". The meta-DTDs of base architectures of application DTDs are the application's base meta-DTDs.

Attribute list declaration

An element type form's attribute definition list includes the mandatory ArcForm attribute, which identifies the architectural form. The ArcForm attribute is unique in that it must be defined for every element type that is to be processed in a manner defined by the architecture (i.e., that has attributes defined by the architecture). Normally, every element of the same type has the same architectural form, which allows the ArcForm value to be fixed in the DTD. However, this is not a requirement: an element type definition, could, for example, allow its instances to be one of a choice of architectural forms.

The other attribute definitions follow the conventions described in .

The specification of an element type form's attribute list can include common attributes (explained below) or non-architecture-specific SGML attribute types (such as ID and NOTATION) when they are required for the element type, or when they are important enough to the element type to warrant the emphasis. For example, in HyTime, the ID attribute is included for a form if there are HyTime elements that are required to reference instances of that form.

The attribute definition list for an element type form can incorporate by reference attributes defined in attribute list forms. An attribute list form is referenced by including its name in a conventional comment in the attribute definition list declaration. The comment consists of the word "Attributes:" followed by the name of the attribute list form.

Attribute list forms

An attribute list form defines attributes that can be used in the attribute definition lists of element types conforming to one or more element type forms, including SGML processing link attribute lists. The element types with which the attributes can be used are indicated in the following manner:

Attribute list forms can also be defined for use with data content notations ("data attribute forms"). They differ from other attribute list forms in that they include an ArcForm attribute to identify the notation form. The notations with which data attribute forms can be used are identified by the same conventions employed for element attributes. Common data attributes can be used with all of the architecture's notations.

Attribute list conventions

All attributes but the ArcForm attribute, whether part of an element type form or an attribute list form, are specified using the conventions in this sub-clause.

Attribute definition

An SGML attribute definition parameter consists of an attribute name, a declared value prescription, and a default value prescription. The components of the definition can be separated by comments, as can the individual definitions in a declaration. For a given element type, an application can replace an attribute's architecture-defined name by using the "ArcNamer" attribute (see ).

Declared value prescription

Lexical types of attributes (and data content) defined by an architecture are specified by conventional comments containing the word "lextype" or "ulextype", followed by a lexical model in the "HyTime lexical model notation" (HyLex) (see ). The comments occur within the attribute definition parameter or element type declaration. The word "lextype" signifies a normalized lexical model, while "ulextype" signifies an unnormalized one. HyLex is not only used to document architectures. It is a facility of HyTime and can therefore be used by application designers as well. However, use of HyLex in an architecture definition does not require the architecture to support its use for applications.

Semantic constraints on the value of an attribute are defined in a conventional comment beginning with the word "Constraints:". Either the comment is self-explanatory, and/or there is sufficient additional information in the accompanying text of the architecture definition document to explain the constraint.

Declared value prescriptions that require ID references are specified with either the SGML IDREF or IDREFS keywords, or with ID references indicated by a lextype conventional comment. If the attribute definition contains a conventional comment containing the word "reftype" followed by an SGML OR group, the target of the ID references must be an element that conforms to an element type form whose name occurs in the OR group. Note that the OR group is meta: the names are architectural forms rather than element types. The reftype conventional comment should not be confused with the more powerful reftype facility of HyTime, which is for use by application designers. Use of the reftype comment in an architecture definition does not require the architecture to support the Hytime reftype facility.

An application DTD can use any declared value prescription whose values could satisfy the declared value prescription in the architecture definition. This requirement can be satisfied by an application declared value prescription that allows ID references, as long as the targets of the references can be objects that satisfy the declared value prescription of the architecture definition.

It is a reportable architecture error if a document instance contains a value for an attribute that fails to satisfy the declared value prescription defined for it in the architecture definition document.

Default value prescription

An architecture's attributes are categorized as being "mandatory" or "non-mandatory", and also as being "fixed" or "variable", as follows:

The following list gives examples of the forms of declared value and default value prescriptions used to document each combination of attribute categories:
  • Mandatory/fixed
  • Mandatory/variable
  • Non-mandatory/fixed
  • Non-mandatory/variable
.*********

Identification facilities

A document indicates conformance to architectures by using the APPINFO parameter of the SGML declaration and the other facilities described in this sub-clause.

APPINFO parameter of SGML declaration

Conformance of a document to one or more architectures defined in accordance with these requirements is indicated by specifying the keyword "ArcBase" as a sub-parameter of the APPINFO parameter of the SGML declaration. The keyword indicates the potential presence in one or more DTDs of an architecture base (ArcBase) declaration that identifies the "architecture support declarations" for the architectures on which the DTD is based.

The format of the sub-parameter is: The sub-parameter can also specify the name of the ArcBase declarations in the document's DTDs if it is other than "ArcBase". The format is: where "ArcUsed" is replaced by the declaration name. .*

Architecture base declaration

An ArcBase declaration identifies one or more base architectures of a DTD or a derived meta-DTD. It cannot be used in a meta-DTD that is not derived. It should precede the architecture support declarations pertaining to the base architectures that it identifies. There can be more than one ArcBase declaration in a DTD or meta-DTD.

Syntactically, the ArcBase declaration is a processing instruction (PI), not an SGML markup declaration. In the template below, it is shown in the reference concrete syntax. In use, the ArcName-list parameter must be replaced by one or more architecture names (ArcName) declared as notation names, separated by SGML ts separators (white space). It is an RAE if the DTD or meta-DTD does not declare a notation for each ArcName specified.

The declaration name is the initial character string, up to the first ts separator. The name is always "ArcBase" in meta-DTDs. It should also be "ArcBase" in DTDs, but provision is made for changing it in the APPINFO parameter of the SGML declaration, if necessary, to avoid the (admittedly unlikely) possibility of conflicts when retro-fitting an architecture to a document that already has PIs that begin with "ArcBase ". ]]> .*

Architecture support declarations

A DTD contains architecture support declarations for each architecture on which its instances are based. They consist of a notation declaration that identifies the architecture definition document and a general entity declaration that identifies the meta-DTD. Associated with the notation declaration is an attribute definition list declaration for "architecture support attributes". It is not necessarily an error if the definition document and/or meta-DTD cannot be accessed, as an implementation might not require access to these objects. The primary purpose of the declarations is to declare and specify architecture support attributes.

To the extent permitted by SGML, architecture support declarations should precede other declarations. .****

Architecture notation declaration

Each base architecture name (ArcName) specified in an ArcBase declaration must be declared as a notation name in a notation declaration that identifies the architecture definition document.

The template for such a declaration is shown below. In use, ArcName is replaced by the actual notation name for the architecture, as specified in the ArcBase declaration. The conformance statement shows that the architecture claims conformance to the requirements of this annex. (It does not indicate conformance to HyTime.) ]]> .****

Architecture support attributes

There must be an attribute definition list declaration for each architecture notation declaration to define mandatory architecture support attributes. An individual architecture can define additional architecture support attributes of its own.

The template for such a declaration is shown below. In use, ArcName is replaced by the actual notation name for the architecture. The architecture designer can also add application-defined attribute definitions.

The attribute architectural form attribute name (ArcFormA) specifies the name of an attribute that the architecture must define for every element type form and notation to identify its architectural form (see ). The ArcName can be used as the name of the ArcForm attribute. For example, "HyTime" is both an architecture name and the name of that architecture's ArcForm attribute.

The attribute architecture bridge name (ArcBridA) specifies the name of an all-architecture common attribute that describes the bridging between the architecture and a non-architectural element or notation (see ).

The attribute architecture attribute renamer name (ArcNamrA) specifies the name of an all-architecture common attribute that allows an application to substitute its own names for architecture attribute names (see ).

The attribute architecture document element form name (ArcDocF) specifies the name of the document element type form (see ).

The attribute architecture version identifier (ArcVer) identifies the version of the architecture to which the document instance conforms.

The attribute architecture SGML declaration (ArcSGML) names an entity that contains the SGML declaration that governs the meta-DTD entity (see ).

The attribute architecture facility attribute names (ArcFacA) specifies the names of architecture-defined attributes that collectively identify all of the facilities for which support may be required by the document.

It is an error if a document requires an architecture facility that is not identified in the support declarations, but a system is not required to report such an error as it may not be able to do so. However, it is not an RAE if the declarations identify facilities that are not actually required by the document.

If a system attempts to process a document whose support declarations identify facilities that the system does not support (see ), the system must report an error even if the document does not actually use those facilities. In other words, a system can give the user the option of ignoring an "unsupported facility" error, but it must report the error in the first instance.

Identification of a facility implies automatic identification of any facilities on which it is dependent. If an optional facility has mandatory components, such as mandatory attributes, they are required only if the optional facility is supported.

The DerArc support attributes, for use in derived architecture definitions, are described in . ]]> .****

Architecture entity declaration

Each base architecture name (ArcName) specified in an ArcBase declaration must be declared as an entity name in an entity declaration that identifies an architecture meta-DTD to which the document instance conforms. The entity must be declared as CDATA with the ArcName specified as the NOTATION. It can have an attribute specification list for architecture-defined support attributes.

The template for such a declaration is shown below. In use, ArcName is replaced by the actual notation name for the architecture. The sample attribute specification list is replaced by specifications of architecture-defined attributes.

If the architecture has facility attributes, it is not an error if they are more or less restrictive than the meta-DTD. The document instance must conform to both.

No entity reference is specified for the architecture entity as it is only accessed directly by the architecture engine (if at all), outside the parsing context of the document. However, the entity must conform to the SGML declaration that is named by the ArcSGML attribute. If none is named, the SGML declaration applicable to the architecture entity declaration itself is used.

It is possible (though not required) for meta-DTDs to be processable by a universal "architectural form engine". Such an engine behaves similarly to an SGML parser validating conformance to a DTD, except that:

  1. Element type form names, rather than GIs, are checked against the meta-content models.
  2. The "attributes" conventional comment is recognized and treated like an entity reference to the definitions in the specified attribute list architectural form.
  3. The "lextype" and "reftype" conventional comments could be recognized and processed to provide validation beyond that supported by SGML alone.
The semantics of the "constraints" conventional comment is supported by the individual architecture implementation, as are "lextype" and "reftype" if they are not processed by the architectural form engine. Such individual architecture support is normally "built-in"; that is, the conventional comments are not read by the program -- they are read by the programmers. ]]> .*

Architectural form attribute

The attribute architectural form (ArcForm) identifies the architectural form of an element or notation. Its value is the name of the architectural form to which the element or notation conforms.

The actual name of the attribute should not be ArcForm; it must be unique for each base architecture and should ideally be unique among all the attribute names in client documents. The actual name is specified by the ArcFormA attribute of the architecture notation declaration.

An architecture must declare the ArcForm attribute for each element type form and notation form that it defines. An architecture engine uses this attribute to determine the architecture-specific processing to perform, and to know which architecture-defined attributes to examine. The application processor supplements this processing by using the application-defined element type and other attributes to determine the application-specific processing to perform. In object-oriented programming /erms, an application-defined derived class (the element type) inherits the properties of its base class (the architectural form). It is an RAE if a document instance contains a value for the architectural form attribute other than one specified in the architecture definition document. In other words, an architecture's set of architectural forms cannot be extended by an application (but see ). .*

Architectural document element

The document element of a DTD, or the document element type form of a derived meta-DTD must conform to, and each base architecture must provide, the element type form architectural document element (ArcDoc).

The ArcDoc form allows an architecture to define attributes for the document element, and to specify the "architectural context-free content" (ArcCFC). The ArcCFC is the set of element type forms that can occur independently at the highest level of a document. In HyTime, for example, a finite coordinate space is part of ArcCFC but an event schedule is not because it is only permitted to occur within a finite coordinate space. As not all architectural elements have constrained content models, there could be many forms for which ArcCFC is the permitted content. A useful convention is to declare an ArcCFC parameter entity for reference in element type form declarations.

The actual name of the architectural form need not be ArcDoc; it could reflect the name of the architecture. The actual name is specified by the ArcDocF attribute of the architecture notation declaration.

A template for declaring a document element type form is shown below. In use, ArcDoc is replaced by its actual name and a name other than ArcCFC could be used for the content entity. The architecture designer could add the architecture's own attribute definitions for the document element. Designers may choose to have meta-inclusions in %ArcCFC as well as a model group. Alternatively, they may choose not to have an ArcCFC entity at all. ]]> .*

All-architecture common attributes

The attribute list form all-arc consists of common attributes that are automatically defined for all architectures. When defined, the architecture's own choice of names for the ArcNamer and ArcBrid attributes is substituted (see ). An application can use the common attributes individually in attribute list definitions.

The attribute architecture attribute renamer (ArcNamer) is an attribute that defines user substitutes for architecture attribute names. The substitute is treated as if it were the correspondingly-named architecture-defined attribute. If the substitute name is "#CONTENT", the value of the attribute is the syntactic content of the element. An attribute bearing an architecture-defined attribute name for which a substitute is defined will be ignored by the architecture engine.

The common attribute architectural bridge (ArcBrid) can be defined for non-architectural element types and notations only. It describes the bridge between the element or notation and architectural processing. One, two, or all of three different keywords can be specified as the attribute value (except for notations, where only "ArcAtts" can be specified): ArcAtts Architectural attributes will be processed for this element or notation. sArcForm Suppress architectural processing of nested subelements with ArcForm attribute (i.e., architectural elements). sArcBrid Suppress architectural processing of nested subelements with ArcBrid attribute. If no keywords are specified, no architectural attributes are processed for this element and architectural subelements will be processed normally. For example, "sArcForm sArcBrid" suppresses all architectural processing at any level of the element's content, while "sArcForm" allows the possibility that a nested ArcBrid element could restore processing within its own content. The suppression of architectural processing can be useful if architectural elements are to be used for other purposes; for example, to display or edit HyTime resource elements within a HyTime document. When sArcForm is specified, meta-model checking is suspended. The element can therefore contain any of an architecture's elements, even those that normally are not part of the ArcCFC (i.e., that can occur only in the content of some other architectural element). This freedom is possible because the architectural processing is suppressed, and therefore does not require the processing context that would have been established by the omitted containing element.

The attribute unique identifier (id) uniquely identifies an element in the name space of the document. This is the normal SGML usage; there are no special architectural semantics. As the attribute has a declared value prescription of "ID", it will be recognized even if no "ArcForm" attribute is defined for the element. SGML subdocuments have their own ID name spaces.

The attribute data content notation (notation) identifies the notation in which the data content of the element is represented. The attribute is processed in the same way that an SGML parser treats a notation attribute. If the attribute is defined with a declared value prescription of "NOTATION" (rather than "NAME"), it will be recognized even if no "ArcForm" attribute is defined for the element. ]]> .****

Derived architectures

An architecture can be derived from one or more base architectures by the same means that a DTD is derived from one or more base architectures. That is, an ArcBase declaration and support declarations for the specified base architectures are present in the meta-DTD. A derived architecture can also serve as a base architecture for DTDs and for other derived architectures. This facility provides designers the tools for subclassing and scaling SGML information bases without compromising the accuracy and consistency obtained from SGML's rigorous document type conformance checking. It brings to document data modeling OOPS benefits like multiple inheritance and encapsulation, while preserving SGML's ability to control a document's properties through a single coherent document type definition. A derived architecture and its base architecture can both be (peer) base architectures of another derived architecture or DTD. A conforming instance of a derived architecture is, by definition, a conforming instance of each of its base architectures. Therefore, if a system does not support the semantics of a derived architecture, it could, as an error-recovery fallback, treat the document as an instance of the base architectures instead.

In the meta-DTD of a derived architecture, the attribute list form DerArc can augment the architecture support declarations by providing two architecture support attributes that are not provided in a normal DTD. (See for a discussion of support attributes.)

The attribute architecture copied forms (ArcCopy) identifies base architectural form declarations that are treated as though they were copied into the derived architecture meta-DTD. Forms for subelements of copied forms, and referenced notation and attribute list forms, are copied automatically, except for those objects (including individual attributes) whose names are declared explicitly in the derived architecture.

It is an RAE to specify an object for copying explicitly if an object of that type is declared with the same name in the derived architecture.

It is an RAE to specify identically named objects of the same type for copying explicitly or automatically from two or more base architectures.

Objects that these requirements cause to exist automatically in all architectures (such as all-architecture common attributes) are never copied. It is an RAE to specify them for copying.

To eliminate name conflicts, the attribute architecture copy aliases (ArcAlias) can be used to specify unique names for objects copied from the base architecture. ]]>

Conformance

An architecture that conforms to these Architectural Form Definition Requirements shall so indicate by including the following statement in its architecture definition document and in its meta-DTDs:

DTDs and meta-DTDs derived from a conforming architecture should include the statement in the architecture support notation declaration.