Modularization in schemas

Structural specialization pattern

For each structural type, the document type shell document collects the schema documents, parent structural type modules, domain type modules, and content models needed to implement new topic type specializations. Each new structural type requires three files. To see an example, look at the concept.xsd document type shell document for the concept topic type.

Each structural type must define a separate module schema document with a name consisting of the root structural element name and Mod.xsd
Each structural type must define a separate model group definition schema document with a name consisting of the root structural element name and Grp.xsd

The module schema document must define an info-type model group that is named with a prefix of the topic element name and a suffix of -info-types. Here is an example of a info-types model group that is defined in conceptMod.xsd:

<xs:group name="concept-info-types">
  <xs:choice>
     <xs:group ref="concept"minOccurs="0"/>
     <xs:group ref="info-types" minOccurs="0"/>
  </xs:choice>
</xs:group>

The module schema document defines every specialized element used as substructure within the structural type. The specialized elements must follow the rules of the architecture in defining content models and attributes. The naming convention for content models must use the root structural element name and.class

As with all specializations, the root element of a structural specialization must have a content model that restricts or conserves the content model of the element it specializes. The root element must also reference the DITAArchVersion attribute and domains attribute. For the schemas, the domains attribute value is set in the document type shell. See Document type shell pattern for more information on how to set the values for the domains attibute. In addition the last position in the content model must be the nested topics entity as in the following example:

<xs:complexType name="concept.class">
   <xs:sequence>
      <xs:group ref="title"/>
      <xs:group ref="titlealts" minOccurs="0"/>
      <xs:choice minOccurs="0">
        <xs:group ref="shortdesc" />
        <xs:group ref="abstract" />
      </xs:choice>
      <xs:group ref="prolog" minOccurs="0"/>
      <xs:group ref="conbody" minOccurs="0"/>
      <xs:group ref="related-links" minOccurs="0"/>
      <xs:group ref="concept-info-types" minOccurs="0" maxOccurs="unbounded"/>
   </xs:sequence>
   ....
</xs:complexType>

These attributes give processes a reliable way to check the architecture version and look up the list of domains available in the document type.

<xs:attribute name="id" type="xs:ID" use="required"/>
<xs:attribute ref="ditaarch:DITAArchVersion" />

The new file topictypeGrp.xsdis needed to mimic substitutionGroups in XML Schema without using the inheritance model in W3C XML Schema 1.0 specification. The process is very similar to the DITA DTD design pattern. For a structural type the name of the schema document consists of the root structural element name and Grp.xsd extension. To see an example of a model group schema document, look at the file conceptGrp.xsd :

<xs:group name="concept">
    <xs:sequence>
      <xs:element ref="concept"/>
    </xs:sequence>  
</xs:group>

The model group schema document defines model groups for each new specialized element in a structural type. Each structural type and domain must have a model group schema document . The model group schema document is an essential part of the specialization.

Parent topic: Specialization in design

Previous topic: Modularization in DTDs

Binding the class attribute to an element

The class attribute must include the value of the class attribute of the base element and append the element name qualified by the root structural element name or domain name with at least one leading and trailing space. The class attribute starts with a ″-″ if it is declared in a structural module, or a ″+″ if it is declared in a domain module.

This attribute provides a mapping between the element’s current name and its more general equivalents. It must be bound the elements declaration, and not in the complexType referenced by the element. To see an example, look at the reference.xsd schema document.

<xs:element name="reference">
  <xs:complexType>
    <xs:complexContent>
      <xs:extension base="reference.class">
        <xs:attribute ref="class" default="- topic/topic reference/reference "/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

Parent topic: Specialization in design

Previous topic: Modularization in DTDs

Domain specialization pattern

A domain type schema document with a name consisting of the domain name and the Domain.xsd extension.

As in a structural module, the domain module must define each specialized element, its attributes and its model groups. As with any specialization, the domain element must restrict the base element. The class attribute of the domain element must start with a plus sign but, otherwise, follows the same rules as the class attribute for an element introduced by a topic specialization.

For each element extended by one or more domains, the domain type schema document defines a model group for the base element to a list of alternatives including the literal name of the element and the element extension entity from each domain that is providing specializations.

The schema document must define an a model group for each element extended by the domain. The contents of the model group must be the list of specialized elements for the extended element. The name of the model group has a prefix of the abbreviation for the domain and an extension of the name of the extended element. In the following example, the user interface domain (abbreviated as ui-d) extends the ph element.

<xs:group name="ui-d-ph">
  <xs:choice>
     <xs:element ref="uicontrol" />
     <xs:element ref="menucascade" />
  </xs:choice> 
</xs:group>

Document type shell pattern

For each document shell type, the following named model group info-typesmust be defined. This model group can define a list of default subordinate topics. If the topic type does not have default subordinate topics, then the default value for theinfo-types model group must be defined as an empty group.

<xs:group name="info-types">
   <xs:sequence/>
</xs:group>

The default values for the domains attributes in the base root structural element and the specialized root structural elements must be defined using the schema <redefine> mechanism to populate the domains attribute. It identifies the domains used in the structural type. This attribute give processes a reliable way to look up the list of domains available in the document type. The list the domains is included in the document type as in the following example:

<xs:redefine schemaLocation="topicMod.xsd" >
  <xs:complexType name="topic.class">
     <xs:complexContent>
      <xs:extension base="topic.class">
          <xs:attribute
name="domains" type="xs:string" default="(topic ui-d)
(topic hi-d) (topic sw-d) (topic pr-d) (topic ut-d) (topic indexing-d)"/>
       </xs:extension>
     </xs:complexContent>
   </xs:complexType> 
</xs:redefine>

For each element extended by one or more domains, the document type shell redefines the model group for the element to a list of alternatives including the literal name of the element and the element extension model group from each domain that is providing specializations. To integrate a new domain in the document type shell use the schema <redefine> mechanism to manage the number of domains used by the document type shell. The model group requires a reference to itself to extend the base model group. To see an example, look at the topic.xsd schema document.

<xs:group name="pre">   
  <xs:choice>       
    <xs:group ref="pre" />
    <xs:group ref="pr-d-pre" />
    <xs:group ref="ui-d-pre" />
    <xs:group ref="sw-d-pre" />
  </xs:choice>
</xs:group>

To add domains to a new structural type you can copy the contents of the parent structural type domains schema document into the document type shell. Add or remove the model group from the new domain to the appropriate named group.

<xs:group name="pre">
 <xs:choice>
   <xs:group ref="pre"/>
   <xs:group ref="pr-d-pre" />
   <xs:group ref="domainName-d-element"/>
 </xs:choice> 
</xs:group>

For each attribute extended by one or more domains, the document type shell redefines the attribute extension model group for the attribute to a list of alternatives including the literal name of the attribute and the attribute extension model group from each domain that is providing specializations. Attributes can only be specialized from props or base in DITA 1.1. To integrate a new attribute domain in the document type shell use the schema <redefine> mechanism to manage the number of attribute domains used by the document type shell.

<xs:attributeGroup name="props-attribute-extensions">
   <xs:attributeGroup ref="props-attribute-extensions"/>
   <xs:attributeGroup ref="newAtt-d-attribute"/>
   <xs:attributeGroup ref="othernewAtt-d-attribute"/>
</xs:attributeGroup>
    
<xs:attributeGroup name="base-attribute-extensions">
    <xs:attributeGroup ref="base-attribute-extensions"/>
    <xs:attributeGroup ref="newfrombaseAtt-d-attribute"/>
    <xs:attributeGroup ref="othernewfrombaseAtt-d-attribute"/>
</xs:attributeGroup>

Attribute domain specialization pattern

The attribute domain pattern is a special case of the domain specialization pattern, which allows the creation of new attributes specialized from the props or base attribute.

Create one module entity file per attribute, for example newAttDomain.xsd. Each module should contain the following:

The entity which holds the actual declaration of the attribute in entity form. This entity can then be used in document type shells to add the new attribute. For example:

<xs:attributeGroup name="newAtt-d-attribute">
    <xs:attribute name="new" type="xs:string"/>
</xs:attributeGroup>

This attribute domain declaration value can then be used in document type shells to signal the availability of the attribute to DITA-aware processes. It uses the same syntax as a regular domain declaration value but with the addition of a leading "a" to signal that it is in attribute domain. For example:

<xs:attribute name="domains" type="xs:string" default="... a(props new)"/>