# E. Developing Schema with defined and extended modules

Contents

This appendix is informative.

The primary purpose of defining XHTML modules and a general modularization methodology is to ease the development of document types that are based upon XHTML using XML Schemas. These document types may extend XHTML by integrating additional capabilities (e.g., [SMIL]), or they may define a subset of XHTML for use in a specialized device. This section describes the techniques that document type designers must use in order to take advantage of the XML Schema implementation of this modularization architecture. It does this by applying the XHTML Modularization techniques in progressively more complex ways, culminating in the creation of a complete document type from disparate modules.

Note that in no case do these examples require the modification of the XHTML-provided module file entities themselves. The XHTML module file entities are completely parameterized, so that it is possible through separate module definitions and driver files to customize the definition and the content model of each element and each element's hierarchy.

Finally, remember that most users of XHTML are not expected to be XML Schema authors. XML Schema authors are generally people who are defining specialized markup that will improve the readability, simplify the rendering of a document, or ease machine-processing of documents, or they are client designers that need to define the specialized markup language for their specific client. Consider these cases:

- An organization is providing subscriber's information via a Web interface. The organization stores its subscriber information in an XML-based database. One way to report that information out from the database to the Web is to embed the XML records from the database directly in the XHTML document. While it is possible to merely embed the records, the organization could define a module that describes the records, attach that module to an XHTML implementation, and thereby create a complete markup language for the pages. The organization can then access the data within the new elements via the Document Object Model [DOM], validate the documents, provide style definitions for the elements that cascade using Cascading Style Sheets [CSS2], etc. By taking the time to define the structure of their data and create a markup language using the processes defined in this section, the organization can realize the full benefits of XML.

- An Internet client developer is designing a specialized device. That device will only support a subset of XHTML, and the devices will always access the Internet via a proxy server that validates content before passing it on to the client (to minimize error handling on the client). In order to ensure that the content is valid, the developer creates a markup language that is a subset of XHTML using the processes defined in this section. They then use the new language definition in their proxy server and in their devices, and also make the language definition available to content developers so that developers can validate their content before making it available. By performing a few simple steps, the client developer can use the architecture defined in this document to greatly ease their language development cost and ensure that they are fully supporting the subset of XHTML that they choose to include.

## E.1. Defining additional attributes

In some cases, an extension to XHTML can be as simple as additional attributes. Schema authors should an provide the attribute definitions for each attribute, for example:

    <xs:attributeGroup name="myattrs.attrib">
    	<xs:attribute name="myattribute" type="xs:string"/>
    </xs:attributeGroup>

would declare an attribute "myattr" and attribute group "myattrs.attrib" in the target namespace of the schema ("xs" is the prefix for XML Schema Namespace). Authors should note that the attribute is created as local attribute (as part attribute group). Alternatively, declaring an attribute by placing the attribute declaration as direct child of `schema` element would create a Global attribute (and document instances would have to use qualified attribute name such as xlink:show). For a discussion of qualified names and Namespace prefixes, see Defining the Namespace of a Module.

To add this attribute to the content model of an element, the attribute group (that makes the content model of the element) would need to be redefined (by the document type's driver file) to include the new attribute. for example:

    <xs:redefine schemaLocation="xhtml-basic10.xsd">
    	<xs:attributeGroup name="a.attlist">
    		<xs:attributeGroup ref="a.attlist"/>
    		<xs:attributeGroup ref="myml:myattrs.attrib"/>
    	</xs:attributeGroup>
    </xs:redefine>

The target namespace of the attribute group definition is not XHTML namespace and must be contained in a separate XML schema.

Naturally, adding an attribute to a schema does not mean that any new behavior is defined for arbitrary clients. However, a content developer could use an extra attribute to store information that is accessed by associated scripts via the Document Object Model (for example).

## E.2. Defining additional elements

Defining additional elements is similar to attributes, but a typical XHTML module would define the element as a global element (as a direct child of `schema` element). Schema authors should first provide the element declaration for each element:

    <!-- In the myml-module-1.xsd -->
    <xs:group name="myelement.content">
    	<xs:choice>
    		<xs:element name="otherelement"/>
    	</xs:choice>
    </xs:group>
    <xs:attributeGroup name="myelement.attlist">
    	<xs:attribute name="myattribute" type="xs:string"/>
    </xs:attributeGroup>
    <xs:complexType name="myelement.type" mixed="true">
    	<xs:choice>
    		<xs:group ref="myelement.content" minOccurs="0" maxOccurs="1"/>
    	</xs:choice>
    	<xs:attributeGroup ref="myelement.attlist"/>
    </xs:complexType>
    <xs:element name="myelement" type="myelement.type"/>

The target namespace of "myelement" declared is not XHTML namespace, hence must be contained in a separate XML Schema. "xs" is the prefix for XML Schema Namespace. After the elements are defined, they need to be integrated into the content model. Strategies for integrating new elements or sets of elements into the content model are addressed in the next section.

## E.3. Defining the content model for a collection of modules

Since the content model of XHTML modules is fully parameterized using named content models, Schema authors may modify the content model for every element in every module. The details of the schema module interface are defined in Building Schema Modules. Basically there are two ways to approach this modification:

1. Re-define the named content model, `.content`, for each element.
2. Define one or more of the global named content model entities to include the element in those named model definitions (normally via the named content model, `.extras`).

The strategy taken will depend upon the nature of the modules being combined and the nature of the elements being integrated. The remainder of this section describes techniques for integrating two different classes of modules.

### E.3.1. Integrating a stand-alone module into XHTML

When a module (and remember, a module can be a collection of other modules) contains elements that only reference each other in their content model, it is said to be "internally complete". As such, the module can be used on its own; (for example, you could define a schema that was just that module, and use one of its elements as the root element). Integrating such a module into XHTML is a three step process:

1. Decide what element(s) can be thought of as the root(s) of the new module.
2. Decide where these elements need to attach in the XHTML content tree.
3. Then, for each attachment point in the content tree, add the root element(s) to the content definition for the XHTML elements.

Consider attaching the elements defined above. In that example, the element `myelement` is the root. To attach this element under the `img` element, and only the `img` element, of XHTML, the following redefinition would work:

    <xs:redefine schemaLocation="xhtml-basic10.xsd">
    	<xs:group name="img.content">
    		<xs:choice>
    		    <xs:group ref="img.content"/>
    			<xs:element ref="myml:myelement"/>
    		</xs:choice>
    	</xs:group>
    </xs:redefine>

Such redefinition must not be included in the module implementation, but instead provided as part of the document type's driver implementation. A schema defined with this content model would allow a document like the following fragment:

    <img src="http://examples.com/image" alt="alt-text">
      <myml:myelement >This is content of a locally defined element</myml:myelement>
    </img>

It is important to note that normally the `img` element has a content model of `EMPTY`. By adding myelement to that content model, we are really just replacing `EMPTY` with `myelement`. In the case of other elements that already have content models defined, the addition of an element would require the restating of the existing content model in addition to `myelement`.

### E.3.2. Mixing a new module throughout the modules in XHTML

Extending the example above, to attach this module everywhere that the `%Flow.mix` content model group is permitted, would require something like the following in the schema that defines the document model of the document type:

    <xs:redefine schemaLocation="xhtml11.xsd">
    	<xs:group name="Misc.extra">
    		<xs:choice>
    			<xs:group ref="Misc.extra"/>
    			<xs:element ref="myml:myelement"/>
    		</xs:choice>
    	</xs:group>
    </xs:redefine>

Since the Misc.extra content model class is used in the content model the named model Misc.class, and that named model is used throughout the XHTML modules, the new module would become available throughout an extended XHTML document type.

## E.4. Creating a new Document Type

So far the examples in this section have described the methods of extending XHTML and XHTML's content model. Once this is done, the next step is to collect the modules that comprise the Document Type into a schema driver and schema file that provides the content model redefinitions of included modules, incorporating the new definitions so that they override and augment the basic XHTML definitions as appropriate.

### E.4.1. Creating a simple Document Type

Using the trivial example above, it is possible to define a new schema that uses and extends the XHTML modules pretty easily. First, define the new elements and their content model in a module:

    Module  not found!

Now, define the schema driver for the new language:

    Module  not found!

A schema defined with this content model would allow a document like the following:

    Module  not found!

### E.4.2. Creating a Language by extending XHTML

Next, there is the situation where a complete, additional, and complex module is added to XHTML (or to a subset of XHTML). In essence, this is the same as in the example above, the only difference being that the module being added is incorporated in the schema by creating an new document model schema.

One such complex module is the Schema for [MATHML]. In order to combine MathML and XHTML into a single Schema, an author would just decide where MathML content should be legal in the document, and add the MathML root element to the content model at that point. First, define a new document model that instantiates the MathML Schema and connects it to the content XHTML content model by redefining the XHTML content model. Providing a redefinition of the XHTML content model by implication includes the XHTML content model in the new document content model :

    Module  not found!

Next, define a Schema driver that includes our new document content model with XHTML1.1 modules and MathML module (for example):

    Module  not found!

### E.4.3. Creating a Language by removing and replacing XHTML modules

Another way in which Schema authors may use XHTML modules is to define a Schema that is a subset of an XHTML family document type (because, for example, they are building devices or software that only supports a subset of XHTML). To do this simple create a Schema driver that does not include the relevant modules. Schema author should note that `redefine` in schema by default includes all the content model of the referenced schema, authors should also not include any redefinitions of modules that they do not wish to include. The basic steps to follow are:

1. Take an XHTML family Schema as the basis of the new document type (e.g. XHTML 1.1).
2. Select the modules to remove from that Schema.
3. Physically, remove `include` and `redefine` schema elements that include any non relevant modules from the driver file. Also references to schema components from such modules used in redefinitions of other modules must be deleted.
4. Introduce some new modules

### E.4.4. Creating a the new Document Type

Finally, some Schema authors may wish to start from scratch, using the XHTML Modularization framework as a toolkit for building a new markup language. This language must be made up of the minimal, required modules from XHTML. It may also contain other XHTML-defined modules or any other module that the author wishes to employ. In this example, we will take the XHTML required modules, add some XHTML-defined modules, and also add in the module we defined above.

The first step is to define a module that defines the elements and attributes using the provided template.

    Module  not found!

Now, build a content model description that hooks the new elements and attributes into the other XHTML elements. The following example is patterned after the XHTML Basic content model, but is a complete, free-standing content model module:

    Module  not found!

Finally, build a driver schema. For ease of extensibility this driver schema is split into two XML Schema files. The first file of driver schema collects (includes) all the modules needed for the new document type. This schema also provides the required redefinitions of schema components in included modules.(Note: in XML Schema `redefine` includes the schema referenced.

    Module  not found!

The second file of the driver schema builds new document type based the content model and modules. Also this schema provides the schemaLocation for all imported namespaces (namespaces imported by the included modules)

    Module  not found!

Once a new SCHEMA has been developed, it can be used in any document. Using the Schema is as simple as just referencing it in the schemaLocation attribute of a document root element:

    Module  not found!