XSD document-type shell: Coding requirements

A shell document type integrates one or more topic type or map type modules, zero or more domain modules, and zero or more constraint modules. A shell XSD is organized into sections, where each section contains a specific type of declaration.

An XSD document type shell must conform to the following coding requirements. XSD document type shells may not directly declare element types or attributes (except for the @domains attribute, which always reflects the details of the domains and structural types integrated by the shell).

DITA XSDs use the XML Schema redefine feature (xs:redefine) to override base group definitions for content models and attribute lists. This facility is analogous to the parameter entities used for DTDs. Unlike DTD parameter entities, an xs:redefine both includes the XSD file it redefines and holds the redefinition applied to the groups in the included XSD file. Thus, for XSD files that define groups, the file may be included via xs:include if it is used without modification or via xs:redefine if any of its groups are redefined.

Shell XSDs are organized into sections. Each section of the shell XSD is introduced by a comment. Shells should use these comments to identify each section of the shell. Each section should be present in the shell XSD, even if the section contains no declarations, and should occur in the order they are presented here. Shell XSDs should have an initial set of comments that describe the shell and indicate the URNs or absolute URLs by which the shell should be referenced from document instances or otherwise associated with documents. Shell XSDs may use the XSD appinfo and documentation elements to contain additional documentation about the shell.

Element domain inclusions

The element domain inclusion section contains includes of each element domain integrated by the shell. This section should use the comment:

<!--  ================ ELEMENT DOMAINS =====================  -->

For each element domain used by the map or topic type, the shell XSD must have an xs:include element that includes the XSD module for that domain. For example:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:programmingDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:softwareDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:uiDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:utilitiesDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:indexingDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:hazardstatementDomain.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:abbreviateDomain.xsd:1.2" />

Attribute domain inclusions

The attribute domain inclusion section contains includes of each attribute domain integrated by the shell. This section should use the comment:

<!--  ================ ATTRIBUTE DOMAINS =====================  -->

For each attribute domain used by the map or topic type, the shell XSD must have an xs:include element that includes the XSD module for that domain. For example:

<xs:include schemaLocation="urn:example.com:dita:domains:newAtt.xsd" />

Group inclusions

The group inclusion section contains includes or redefinitions of the group definitions for the structural types integrated in the shell. Group redefinitions are used to integrate domain-provided element and attribute types into base content models. This section should use the comment:

<!--  ================ GROUP DEFINITIONS =====================  -->

For both map and topic shells, this section must include or redefine the common element group, the metadata declaration group, and the table model group.

For topic shells, this section must include or redefine the group XSD for each topic type used by the shell. For example, from a shell for the task topic type:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:taskGrp.xsd:1.2" />
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:metaDeclGrp.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:tblDeclGrp.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:topicGrp.xsd:1.2"/>

For map shells, this section must include or redefine the group XSD for each map type used by the shell (that is, the module for the specialization of <map> the shell uses, as well as any ancestor map types from which the shell's map element is specialized). For example, from the learningMap shell:

    <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:tblDeclGrp.xsd:1.2"/>
    <xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:mapGrp.xsd:1.2">
      <xs:group name="topicref">
        <xs:choice>
          <xs:group ref="topicref"/>
          <xs:group ref="mapgroup-d-topicref"/>
          <xs:group ref="learningmap-d-topicref"/>
        </xs:choice>
      </xs:group>
    </xs:redefine>
  
    <xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementGrp.xsd:1.2">
      <xs:group name="index-base">
        <xs:choice>
          <xs:group ref="index-base"/>
          <xs:group ref="indexing-d-index-base"/>
        </xs:choice>
      </xs:group>
      
    </xs:redefine>
    
    
    <xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:metaDeclGrp.xsd:1.2">
      <xs:group name="metadata">
        <xs:choice>
          <xs:group ref="metadata"/>
          <xs:group ref="learningmeta-d-metadata"/>
        </xs:choice>
      </xs:group>
      <xs:group name="keywords">
        <xs:choice>
          <xs:group ref="keywords"/>
          <xs:group ref="delay-d-keywords"/>
        </xs:choice>
      </xs:group>
    </xs:redefine>

For each element extended by one or more domains, the document type shell must redefine 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 must redefine 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. 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>

Module inclusions

The module inclusion section includes the module XSD files for the structural types used in the shell. This section should use the comment:

<!-- =================  MODULE INCLUDE DEFINITION  ==================  -->

For each map or topic type used by the shell, this section must include either the module XSD file for that type or a constraint module for that type . It must also include any other module XSD files required by the topic or map types, normally the common element module, meta declaration module, and table declaration module. For example:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementMod.xsd:1.2"/>
<!-- ======== Table elements ======== -->
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:tblDeclMod.xsd:1.2"/>    
<!-- ======= MetaData elements, plus keyword and indexterm ======= -->
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:metaDeclMod.xsd:1.2"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:topicMod.xsd:1.2" />  
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:conceptMod.xsd:1.2" />

Domains attribute declaration

The @domains attribute declaration section contains the declaration of the domains attribute for the shell. This section should use the comment:

<!-- =================  DOMAINS ATTRIBUTE DECLARATION  ==================  -->

The shell must declare the @domains attribute such that the @domains attribute value reflects each vocabulary module and constraint module integrated by the shell. The declaration has the form:

<xs:attributeGroup name="domains-att">
   <xs:attribute name="domains" type="xs:string"
        default="domain usage declarations"
   />
</xs:attributeGroup>

Where domain usage declarations is a sequence of domain usage specifications (see Domain usage declaration (the @domains attribute) for details). For example, from the learningMap shell:

<xs:attributeGroup name="domains-att">
  <xs:attribute name="domains" type="xs:string"
     default="(map mapgroup-d) 
              (topic delay-d)  
              (topic indexing-d) 
              (topic learningmeta-d) 
              (map learningmap-d) "
  />
</xs:attributeGroup>

Info types definition

Each topic type defines an info types group that defines the default set of allowed subordinate topics for that topic type. Topic shells may redefine this group to change the effective set of allowed subordinate topics.

The info types section contains the definition of the effective value of the info types groups for topics used by the shell. This section should use the comment:

<!-- =================  INFO TYPES DEFINITION  ==================  -->

This section must not be included in map shells.

The shell must define a model group with the name info-types. This model group may define a list of allowed subordinate topics. If the topic type should not allow subordinate topics, then the default value for the info-types model group must be defined as an empty group, as follows:

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

The document type shell may control how topics are allowed to nest within specific topic types by redefining the topic-type-specific info types group, named topictype-info-types. The info-types group is declared in the module XSD file for a given topic type. For example, in a shell for the concept topic type, allowing concept or generic topic to nest within concept:

<xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:conceptMod.xsd:1.2" >
  <xs:group name="concept-info-types">
    <xs:choice>
      <xs:group ref="concept-info-types"/>
      <xs:group ref="topic"/>
    </xs:choice>
  </xs:group>
</xs:redefine>

Note that XSD rules require that the redefined group include a reference to itself in addition to any other components specified for the redefined group.