XML Schema: Coding requirements for document-type shells

XSD-based document-type shells are organized into sections; each section contains a specific type of declaration.

XSD-based document-type shells 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 that are used for DTD-based document-type shells. Unlike DTD parameter entities, an <xs:redefine> both includes the XSD file that it redefines and holds the redefinition that is applied to the groups in the included XSD file. Thus, for XSD files that define groups, the file can be included using <xs:include> if it is used without modification or using <xs:redefine> if any of its groups are redefined.

XSD-based document-type shells contain the following sections.

Topic or map domains

For each element or attribute domain that is integrated into the document-type shell, this section uses an <xs:include> element to include the XSD module for that domain.

For example:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:deliveryTargetAttDomain.xsd:1.3"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.3"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:indexingDomain.xsd:1.3"/>

Group definitions

The group inclusion section contains <xs:include> or <xs:redefine> references for element groups. The group files define named groups that are used to integrate domain-provided element and attribute types into base content models. There is one group file for each structural type; domain files can also have group files.

For both map and topic shells, this section also must include or redefine the following groups; it must also include the module file for each group:

Common element group (commonElementGrp.xsd and commonElementMod.xsd)
Metadata declaration group (metaDeclGrp.xsd and metaDeclMod.xsd)
Table model group (tblDeclGrp.xsd and tblDeclMod.xsd)

The group files and the module files for base groups can be specified in any order.

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 <xs:redefine> mechanism to import a group definition file while redefining and extending an element from that group. The model group requires a reference to itself to extend the base model 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 <xs:redefine> mechanism to import the commonElementGrp.xsd group file while redefining and extending the base attribute.

For example, the following portion of a document-type shell includes the common metadata module and then adds a domain extension of the <metadata> element from the metadata group. It also extends the @props attribute from the common element module to add the specialized attribute @deliveryTarget.

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:metaDeclMod.xsd:1.3"/>
<!-- ... -->
<xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementGrp.xsd:1.3">
  <!-- ...Redefinition of any elements in common module -->
  <xs:attributeGroup name="props-attribute-extensions">
    <xs:attributeGroup ref="props-attribute-extensions"/>
    <xs:attributeGroup ref="deliveryTargetAtt-d-attribute"/>
  </xs:attributeGroup>
</xs:redefine>
<xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:metaDeclGrp.xsd:1.3">
  <xs:group name="metadata">
    <xs:choice>
      <xs:group ref="metadata"/>
      <xs:group ref="relmgmt-d-metadata"/>
    </xs:choice>
  </xs:group>
</xs:redefine>>

Module inclusions

The module inclusion section includes the module XSD files for structural types used in the shell. These must be placed after the group and files and redefinitions.

This section must also include any other module XSD files required by the topic or map types. For example, if a troubleshooting specialization is specialized from topic but includes elements from task, then the task structural module must be included in the document shell.

If a structural type is constrained, that constraint will be included rather than the module itself; for example, in a document-type shell that constrains the task specialization, the task constraint module will be included rather than the task module.

For example, the following portion of a document-type shell includes the structural modules for topic and concept:.

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:topicMod.xsd:1.3"/>
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:conceptMod.xsd:1.3"/>

Domains attribute declaration

The @domains attribute declaration section declares the @domains attribute for the shell. It does this by redefining the domains-att group, adding one token for each vocabulary and constraint module integrated by the shell. See domains attribute rules and syntax for details on the syntax for domains tokens.

For example, the following sample defines the domains-att to include the OASIS domains for map group, indexing, and @deliveryTarget:

<xs:attributeGroup name="domains-att">
  <xs:attribute name="domains" type="xs:string"
     default="(map mapgroup-d) (topic indexing-d) a(props deliveryTarget)"/>
</xs:attributeGroup>

Info-types definition

This section defines whether and how topics can nest by redefining the info-types group. That group is referenced but undefined in the module files, so it must be defined in the shell. Topic testing can be disallowed by setting the info-types group to reference the <no-topic-nesting> element, with the @maxOccurs and @minOccurs attributes each set to "0".

Optionally, topictype-info-types groups can be redefined to provide more fine grained control of nesting with specialized topic types. As with domain extensions, this is done by redefining the group while importing the module that defines the group.

For example, in the concept vocabulary module delivered by OASIS, the concept-info-types group controls which topics can nest inside the <concept> element. That group is defined as including <concept> plus the info-types group. The following examples demonstrate how to control topic nesting within <concept> using a document-type shell.

To have <concept> only nest itself, the info-types group must be defined so that it does not add any additional topics:
```
<xs:group name="info-types">
  <xs:choice>
    <xs:element ref="no-topic-nesting" maxOccurs="0" minOccurs="0"/>
  </xs:choice>
</xs:group>
```

In order to turn off topic nesting entirely within <concept>, the concept-info-types group must be redefined to remove <concept>, and the info-types group must be defined as above:

<xs:group name="info-types">
  <xs:choice>
    <xs:element ref="no-topic-nesting" maxOccurs="0" minOccurs="0"/>
  </xs:choice>
</xs:group>

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

In order to add <topic> as a nesting topic within <concept>, define info-types to allow any number of <topic> elements:

<xs:group name="info-types">
  <xs:choice>
    <xs:element ref="topic" maxOccurs="unbounded" minOccurs="0"/>
  </xs:choice>
</xs:group>

With the preceding example, <concept> is allowed to nest either <concept> or <topic>. In order to make <topic> the only valid child topic, the concept-info-types must be redefined as follows:
```
<xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:conceptMod.xsd:1.3" >
  <xs:group name="concept-info-types">
    <xs:choice>
      <xs:group ref="info-types"/>
    </xs:choice>
  </xs:group>
</xs:redefine>
```