Element Domain Specialization: XSD Version

An XSD element domain module consists of a single XSD document that contains all the declarations for the domain.

Each element type in an element domain module requires the following declaration components:

A group that defines the content model for the element type
A group that defines the attribute list for the element type
A complex type that combines the content model and the attributes for the element type and, where appropriate, defines the content model as mixed.
A element type that uses the complex type and declares the @class attribute for the element type.
A group that includes just the element by which the element type can be referenced in content models.

For the element types in the XML domain these components look like this:

<xs:element name="xmlelem">
  <xs:annotation>
    <xs:documentation>
      The XML element (&lt;<keyword>xmlelem</keyword>&gt;) element represents a 
      mention of an XML element (tag name).
    </xs:documentation>
  </xs:annotation>
  <xs:complexType mixed="true">
    <xs:complexContent>
      <xs:extension base="xmlelem.class">
        <xs:attribute ref="class" default="+ topic/keyword xml-d/xmlelem "/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element> 
<xs:group name="xmlelem.content">
  <xs:sequence/>
</xs:group>
<xs:attributeGroup name="xmlelem.attributes">
  <xs:attribute name="outputclass" type="xs:string"/>
  <xs:attribute name="keyref" type="xs:string"/>
  <xs:attributeGroup ref="global-atts"/>
  <xs:attributeGroup ref="univ-atts"/>
</xs:attributeGroup>
<xs:group name="xmlelem">
  <xs:sequence>
    <xs:choice>
      <xs:element ref="xmlelem"/>
    </xs:choice>
  </xs:sequence>
</xs:group>  
<xs:complexType name="xmlelem.class" mixed="true">
  <xs:sequence>
    <xs:group ref="xmlelem.content"/>
  </xs:sequence>
  <xs:attributeGroup ref="xmlelem.attributes"/>
</xs:complexType>

The individual components can go in any order but it makes sense to put the <xs:element> declaration first as it contains the documentation for the element type.

The only other required components are the groups used to enable integration of the domain on a per-element-type basis. For this domain all the element types specialize from topic/keyword so there is only one group required, which should be named "xml-d-keyword":

  <xs:group name="xml-d-keyword">
    <xs:choice>
      <xs:element ref="xmlelem"/>
      <xs:element ref="xmlatt"/>
      <xs:element ref="numcharref"/>
      <xs:element ref="parment"/>
      <xs:element ref="textent"/>
    </xs:choice>
  </xs:group>

This group can go at the top or bottom of the XSD document. I prefer to put it at the top where it's easy to find.

To implement the XML domain as an XSD vocabulary module, follow these steps:

Create a file named xmlDomain.xsd with this content:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema
  xmlns:xs="http://www.w3.org/2001/XMLSchema"> 

</xs:schema>

Copy the declarations shown above for the <xmlelem> element type and paste them in, one copy for each of the five element types.
Change the base tagname in each copy to the appropriate tag name.
Copy the xml-d-keyword group shown above and paste it at the top of the XSD file.

To test the module in isolation, create a topic document type shell XSD file in a convenient directory relative to where you have saved the domain's XSD file, for example, in the directory above it or in one nearby. This lets you create relative URLs from the shell XSD to the module so you don't have to set up an entity resolution catalog just to test the module. For example, you can just copy the topic.xsd file from the standard DITA schema files.

To integrate the new domain module, edit the shell XSD as follows:

Add a reference to the xmlDomain.xsd module at the top of the schema document
```
  ...
  
  <xs:include schemaLocation="xsd/xmlDomain.xsd" />
  
  <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:uiDomain.xsd:1.2"/>
  <xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:softwareDomain.xsd:1.2"/>
  ...
```
Change the value of the @schemaLocation attribute to reflect the real relative location of the xmlDomain.xsd file. Remember that schema locations are URLs, not filenames, so if you are on Windows, don't use Windows paths (that is, no backslashes).

Within the <xs:redefine> for the common elements module, update the entry for <keyword> to include 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="pr-d-keyword" />
        <xs:group ref="ui-d-keyword" />
        <xs:group ref="sw-d-keyword" />
        <xs:group ref="xml-d-keyword" />
      </xs:choice>
    </xs:group>
    ...
  </xs:redefine>
  ...

Test the domain by creating a topic document that uses the shell you just created. The easiest place to put the document is in the same directory as the shell XSD file. Given that, the document should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<topic xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="topic.xsd" 
  id="topicid">
  <title>Test Topic</title>
  <body>
    <p><xmlelem>xmlelem</xmlelem></p>
    <p><xmlatt>xmlatt</xmlatt></p>
    <p><numcharref>numcharref</numcharref></p>
    <p><parment>parment</parment></p>
    <p><textent>textent</textent></p>
  </body>
</topic>

You should now be able to validate the document or just apply the Toolkit to it, which will have the effect of validating it.

The last step is to create an entity resolution catalog that assigns a URN to the xmlDomain.xsd file. This file should go in the same directory as the module file. The content should be like this:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" prefer="public">
  
  <public publicId="urn:pubid:example.org:doctypes:dita:modules:xmlDomain"
            uri="xmlDomain.xsd"
    />
  <uri name="urn:pubid:example.org:doctypes:dita:modules:xmlDomain"
    uri="xmlDomain.xsd"
  />
  
</catalog>

You would need to adjust your version to replace the parts shown in bold with your own value, which needs to be globally unique (e.g., an appropriate Internet domain name).

To integrate this module with the Open Toolkit, you should package it as a plugin. See Packaging Document Type Shells and Vocabulary Modules as Toolkit Plugins.