XSD Topic Type Shell Tutorial

XSD Topic Type Shell Tutorial Step 3: Add Reference to a New Domain

To integrate a new domain, we add the following three components:
  • An <xs:include> of the domain's XSD module file (XSD domain modules consist of a single XSD file).
  • A reference to the domain's domain extension groups, one for each different base element type the domain extends.
  • The domain's @domains attribute contribution in the "domains-att" attribute group declaration.
To integrate a domain, you need to know the following:
  • The URN or URL of the module's XSD file. This should be in the entity resolution catalog for the domain. If the domain is packaged using the pattern described here, then the catalog file should be in the same directory as the .xsd file for the domain. If you are integrating a standard DITA domain, you can look in the DITA standard itself or in the catalog_dita.xml file in the Open Toolkit's top-level directory.
  • The set of domain extension groups the module defines. These are defined in the domain's XSD document. For example, the file softwareDomain.xsd has these declarations:
      <xs:group name="sw-d-ph">
    <xs:choice>
      <xs:element ref="msgph" />
      <xs:element ref="filepath" />
      <xs:element ref="userinput" />
      <xs:element ref="systemoutput" />
    </xs:choice>
  </xs:group>

  <xs:group name="sw-d-keyword">
    <xs:choice>
      <xs:element ref="msgnum" />
      <xs:element ref="varname" />
      <xs:element ref="cmdname" />
    </xs:choice>
  </xs:group>

  <xs:group name="sw-d-pre">
    <xs:choice>
      <xs:element ref="msgblock" />
    </xs:choice>
  </xs:group>

    This reflects the fact that the software domain specializes from <pre>, <ph>, and <keyword>.

  • The @domains attribute contribution is "(topic domainShortName-d)" for a domain that specializes directly from topic and not from another domain. The @domains attribute value for the domain should also be documented in an XSD annotation at the start of the domain's XSD file, as in this example from softwareDomain.xsd:
      <xs:annotation>
    <xs:appinfo>
      <dita:domainsModule 
         xmlns:dita="http://dita.oasis-open.org/architecture/2005/"
         >(topic sw-d)</dita:domainsModule>
    </xs:appinfo>
    <xs:documentation> 
    
    </xs:documentation>
  </xs:annotation>
For this tutorial we want to integrate the XML domain defined in the topic element domain tutorial. The information we need for the XML domain is:
.xsd file URN:
"urn:pubid:exmple.org:doctypes:dita:modules:xmlDomain"
domain extension groups
"xml-d-keyword"
domains attribute contribution:
"(topic xml-d)"
Armed with this knowledge, the process of integrating the domain is as follows:
  1. Find the <xs:include> element for the highlight domain. Copy it and paste a new copy into myTopic.xsd immediately after the original:
      ...

  <!--  ================ TOPIC DOMAINS =====================  -->
  <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.2"/>
  <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.2"/>

  ...
  2. Replace the value of @schemaLocation with the URN for the XML domain:
      ...

  <!--  ================ TOPIC DOMAINS =====================  -->
  <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.2"/>
  <xs:include schemaLocation="urn:pubid:exmple.org:doctypes:dita:modules:xmlDomain"/>

  ...
  3. Find the <xs:redefine> for commonElementGrp.xsd and then the group named "keyword." Add a reference to the "xml-d-keyword" group:
    ...

  <xs:redefine schemaLocation="urn:oasis:names:tc:dita:xsd:commonElementGrp.xsd:1.2">
    <xs:group name="keyword">
      <xs:choice>
        <xs:group ref="keyword"/>
        <xs:group ref="xml-d-keyword"/>
      </xs:choice>
    </xs:group>
...
  4. Find the group named "domains-att" and add the string "(topic xml-d) " to the value of the @default attribute:
    ...

  <xs:attributeGroup name="domains-att">
    <xs:attribute name="domains" type="xs:string"       
      default="(topic abbrev-d)
      (topic hi-d)  
      (topic indexing-d) 
      (topic ut-d) 
      (topic xml-d)  
      "/>
  </xs:attributeGroup>

</xs:schema>
  5. Validate your test document. Assuming that the XML domain module is already deployed (you can find it in the materials package for the tutorials), then your document should validate if you haven't made any syntax errors in the shell XSD. As for deleting domains, it is pretty hard to make a syntax error, especially if you are editing the XSD document in an XML editor like OxygenXML.

    If the document validates, see if you can enter any of the element types from the domain into a paragraph, such as <xmlelem> or <xmlatt>. You should be able to.

That's it, you're done. You've successfully created a new topic type shell that removes domains you don't want and adds a new domain you do want.

It should be clear from following this tutorial that creating document type shells is an entirely mechanical process and that once you've done it once or twice it becomes very easy and quick.

This tutorial did not show how to package your new shell as a Toolkit plugin. For that, see Packaging Document Type Shells and Vocabulary Modules as Toolkit Plugins.

This tutorial shows how to create a topic type shell. Creating map type shells is exactly the same.