XML Schema: Coding requirements for document-type shells

Darwin Information Typing Architecture (DITA) Version 1.3 Part 3: All-Inclusive Edition

version
1.3
author
OASIS DITA Technical Committee

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>