Schema module update

[Eric Sirois <esirois@ca.ibm.com>]

Hello,

Based on comments regarding the use of hyphens and files names for the
schemas I made some changes
to the schema module of the spec that will hopefully clarify

1. Remove reference to _domains_grp.xsd.  The file is not needed for DITA
1.0 specification.
2. Merge the contents of  _domains.xsd into the document shell type schema
document.

If you would rather not read the gory details below here is an HTML version
and the DITA version of the doc for you inspection.
(See attached file: schemamod.dita)(See attached file: schemamod.html)

Here are the highlights of the changes.
In the topic Structural Specialization Pattern
  1. Removed the following sentence from the list of required documents for
a specialization
           3.  Each structural type must define a separate domains schema
document with a name consisting of the root structural element name and
                _domains.xsd
  2.  Added the following example and sentence to the bottom of the
paragraph of the second paragraph starting with "The default values for the
domains attribute"
            The list the domains is included in the document type as in the
following example:
           <xs:redefine schemaLocation="topic_mod.xsd" >
      <xs:complexType name="topic.class">
            <xs:complexContent>
                  <xs:extension base="topic.class">
                        <xs:attribute name="domains" type="xs:string"
default="(topic ui-d) (topic hi-d) (topic sw-d) (topic pr-d) (topic ut-d)
"/>
                  </xs:extension>
            </xs:complexContent>
      </xs:complexType>
          </xs:redefine>
  3. In the paragraph starting with "The new file is needed to mimic
substitutionGroups"(last paragraph in this topic). I removed the references
     to -domain_grp.xsd.
         -Removed the sentence
              "For a domain, a name consisting of the domain name and the
-domain_grp.xsd extension.
          -Trimmed the next sentence to remove the reference to
-domain_grp.xsd.
             To see an example of a model group schema document, look at
the file <filepath>concept_grp.xsd</filepath>:

In the topic Domain Specialization Design Pattern
  1. Remove design from the title...consistent with other DTD and Schema
topic titles
  2. Removed second paragraph
          Each domain must define a separate model group type schema
document with a name consisting of the domain name and
          <filepath>-domain_grp.xsd</filepath>
  3. Moved paragraph starting with "For each element extended by one or
more domains" after first example/
  4. Added paragraph from DTD module..changed entity to model group before
first example.
     The schema document must define an a model group for each element
extended by the domain. The contents of the model group must be the list of
specialized elements for the extended element. The name of the model
group has a prefix of the abbreviation for the domain and an extension of
the name of the extended element. In the following example, the user
interface domain (abbreviated as <codeph>ui-d</codeph>) extends the
codeph>ph</codeph> element.
  5. Removed the paragraph starting with  "The domains schema document"
  6. Merged the paragraph starting with "For each element extended by one
or more domains" and "To integrate a new domain" before 2nd example.
  7. Removed 3rd example  reference ui-domain_grp.xsd
  8. Removed last paragraph and example staring with "Otherwise, copy the
content"


Kind regards,
Eric


Eric A. Sirois
Staff Software Developer
DB2 Universal Database - DBA XML Tools Development
IBM Canada Ltd. - Toronto Software Lab
Email: esirois@ca.ibm.com
Phone:(905) 413-2841
Blue Pages (Internal)

"Transparency and accessibility requirements dictate that public
information and government
transactions avoid depending on technologies that imply or impose a
specific product or
platform on businesses or citizens" - EU on XML-based office document
formats.

schemamod.dita

Title: Modularization in schemas

Modularization in schemas

To support extensibility and pluggability, DITA requires that an XML schema implementation of structural and domain specialization modules conform to well-defined design patterns.

This section describes those design patterns. These design patterns realize the specialization architecture with the capabilities and within the limitations of the XML schema grammar.

Structural specialization pattern

For each structural type, the document type shell document collects the schema documents, parent structural type modules, domain type modules, and content models needed to implement new topic type specializations. Each new structural type requires three files. To see an example, look at the concept_shell.xsd document type shell document for the concept topic type.

1. Each structural type must define a separate module schema document with a name consisting of the root structural element name and _mod.xsd
2. Each structural type must define a separate model group definition schema document with a name consisting of the root structural element name and _grp.xsd

The default values for the domains attributes in the base root structural element and the specialized root structural elements must be defined using the XML Schema redefine to populate the domains attribute. It identifies the domains used in the structural type. This attribute give processes a reliable way to look up the list of domains available in the document type. The list the domains isincluded in the document type as in the following example:

<xs:redefine schemaLocation="topic_mod.xsd" >
  <xs:complexType name="topic.class">
    <xs:complexContent>
      <xs:extension base="topic.class">
         <xs:attribute name="domains" type="xs:string" default="(topic ui-d) (topic hi-d) (topic sw-d) (topic pr-d) (topic ut-d)"/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:redefine> 

In the case of topic types, the head schema document can control nesting of subtopics by redefining the nested topics to the literal element names the document type author wishes to allow nested in the document type.

<xs:group name="info-types">
  <xs:choice>
    <xs:group ref="concept-info-types"/>
  </xs:choice>
</xs:group>

The module schema document must define an info-type model group that is named with a prefix of the topic element name and a suffix of -info-types. Here is an example of a info-types model group that is defined in concept_mod.xsd:

<xs:group name="concept-info-types">
  <xs:choice>
     <xs:group ref="concept"/>
  </xs:choice>
</xs:group>

The module schema document defines every specialized element used as substructure within the structural type. The specialized elements must follow the rules of the architecture in defining content models and attributes. The naming convention for content models must use the root structural element name and.class.

In particular, the module schema document defines a class attribute for every specialized element. The class attribute must include the value of the class attribute of the base element and append the element name qualified by the root structural element name or domain name with at least one leading and trailing space. The class attribute for an element introduced by structural specialization must start with a minus sign.

The model group schema document defines model groups for each new specialized element in a structural type. Each structural type and domain must have a model group schema document . The model group schema document is an essential part of the specialization.

The new file is needed to mimic substitutionGroups in XML Schema without using the inheritance model in W3C XML Schema 1.0 specification. The process is very similar to the DITA DTD design pattern. For a structural type the name of the schema document consists of the root structural element name and_grp.xsd extension. To see an example of a model group schema document, look at the file concept_grp.xsd :

 <xs:group name="concept">
   <xs:sequence>
     <xs:element ref="concept" />
   </xs:sequence>
 </xs:group>

Domain specialization design pattern

A domain type schema document with a name consisting of the domain name and the -domain.xsd extension.

As in a structural module, the domain module must define each specialized element, its attributes and its model groups. As with any specialization, the domain element must restrict the base element. The class attribute of the domain element must start with a plus sign but, otherwise, follows the same rules as the class attribute for an element introduced by a topic specialization.

For each element extended by one or more domains, the domain type schema document defines a model group for the base element to a list of alternatives including the literal name of the element and the element extension entity from each domain that is providing specializations.

The schema dcument must define an a model group for each element extended by the domain. The contents of the model group must be the list of specialized elements for the extended element. The name of the model group has a prefix of the abbreviation for the domain and an extension of the name of the extended element. In the following example, the user interface domain (abbreviated as ui-d) extends the ph element.

<xs:group name="ui-d-ph">
  <xs:choice>
    <xs:element ref="uicontrol" />
    <xs:element ref="menucascade" />
  </xs:choice>
</xs:group>

For each element extended by one or more domains, the document type shell redefines the model group for the element to a list of alternatives including the literal name of the element and the element extension entity 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:groupt ref="pr-d-pre" />
      <xs:group ref="domainName-d-element" />
  </xs:choice>
</xs:group>