General element type declaration coding requirements

Module names

Each vocabulary module has a short name that is used to construct file names, entity names, and other names used in associated declarations.

For structural modules, the module name must be the element type name of the top-level topic or map type defined by the module, such as "concept", "bookmap".

For element domain modules, the module name must be a name that reflects the subject domain to which the domain applies, such as "highlight", "software". Domain module names should be sufficiently unique that they are unlikely to conflict with any other domains.

For attribute domain modules, the module name must be the name of the attribute defined by the module plus "Att" (to avoid conflict with similarly-named structural types or element domains).

Element definitions

A structural or domain vocabulary module must contain a declaration for each specialized element type named by the module. While the XSD standard allows content models to refer to undeclared element types, all element types named in content models within a vocabulary module must have an xs:element declaration, either in the vocabulary module, in a base module of which the vocabulary module is a direct or indirect specialization, or, for structural modules, in a required domain module. The specialized elements must follow the rules of the architecture in defining content models and attributes.

Domain modules must consist of a single XSD document named modulenameMod.xsd. Structural modules must consist of two modules, modulenameGrp.xsd, which contains all element name groups, and modulenameMod.xsd, which contains all other declarations for the module.

For each element type declared in the vocabulary module there must be an xs:group whose name is the element type name and whose one member is a reference to the element type, e.g.:

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

The element name group provides a layer of abstraction that facilitates redefinition. A document type shell can redefine an element group to add domain-specialized elements or replace a base element type with one or more specializations of that type.

For domain modules, the group definitions should be grouped together at the start of the domain's XSD document. The definitions may occur in any order.

Each element type must have a corresponding content model group named tagname.content. The value of the group must be the complete content model definition. For example:

<xs:group name="codeph.content">
  <xs:sequence>
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:group ref="basic.ph.notm" minOccurs="0"/>
      <xs:group ref="data.elements.incl" minOccurs="0"/>
      <xs:group ref="foreign.unknown.incl" minOccurs="0"/>
    </xs:choice>
  </xs:sequence>
</xs:group>

The content model group may be overridden in constraint modules to further constrain the content model for the element type.

Each element type must have a corresponding attribute group named tagname.attributes. The group must declare all attributes used by the element type except for the @class attribute. For example:

<xs:attributeGroup name="codeph.attributes">
  <xs:attribute name="outputclass" type="xs:string"/>
  <xs:attributeGroup ref="global-atts"/>
  <xs:attributeGroup ref="univ-atts"/>
</xs:attributeGroup>

Each element type must have a complex type definition named tagname.class, which references the tagname.content and tagname.attributes groups. For example:

<xs:complexType name="codeph.class" mixed="true">
  <xs:sequence>  
    <xs:group ref="codeph.content"/>
  </xs:sequence>        
  <xs:attributeGroup ref="codeph.attributes"/>
</xs:complexType>

Each element type must have an xs:element declaration named tagname, that uses as its type the tagname.class complex type and extends that complex type to add the class attribute for the element. For example:

<xs:element name="codeph">
  <xs:annotation>
    <xs:documentation>
      The code phrase (&lt;<keyword>codeph</keyword>&gt;) element represents a snippet
      of code within the main flow of text. The code phrase may be displayed in
      a monospaced font for emphasis. This element is part of the DITA programming
      domain, a special set of DITA elements designed to document programming tasks,
      concepts and reference information.
    </xs:documentation>
  </xs:annotation>
  <xs:complexType mixed="true">
    <xs:complexContent>
      <xs:extension base="codeph.class">
        <xs:attribute ref="class" default="+ topic/ph pr-d/codeph "/>
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
</xs:element>

The content model group, attribute group, complex type, and element type definition for an element should be grouped together within the module. Each such group of declarations may occur in any order within the module. It is recommended to sort the element type definitions alphabetically or group them into categories. Here is an example declaration for the <codeblock> element:

  <xs:element name="codeblock">
    <xs:annotation>
      <xs:documentation>
        The &lt;<keyword>codeblock</keyword>&gt; element represents lines of
        program code. Like the <ph>
          <xref href="xref.xml">&lt;<keyword>pre</keyword>&gt;</xref>
        </ph> element,
        content of this element has preserved line endings and is output in a monospaced
        font. This element is part of the DITA programming domain, a special set of
        DITA elements designed to document programming tasks, concepts and reference
        information.
      </xs:documentation>
    </xs:annotation>
    <xs:complexType mixed="true">
      <xs:complexContent>
        <xs:extension base="codeblock.class">
          <xs:attribute ref="class" default="+ topic/pre pr-d/codeblock "/>
        </xs:extension>
      </xs:complexContent>
    </xs:complexType>
  </xs:element>
  
  <xs:complexType name="codeblock.class" mixed="true">
        <xs:sequence>
          <xs:group ref="codeblock.content"/>
        </xs:sequence>
        <xs:attributeGroup ref="codeblock.attributes"/>
  </xs:complexType>
  
  <xs:group name="codeblock.content">
    <xs:sequence>
      <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:group ref="basic.ph.notm" minOccurs="0"/>
          <xs:group ref="coderef" minOccurs="0"/>
          <xs:group ref="txt.incl" minOccurs="0"/>
          <xs:group ref="data.elements.incl" minOccurs="0"/>
          <xs:group ref="foreign.unknown.incl" minOccurs="0"/>
        </xs:choice>
    </xs:sequence>
  </xs:group>
  
  <xs:attributeGroup name="codeblock.attributes">
    <xs:attribute name="outputclass" type="xs:string"/>
        <xs:attribute name="spectitle" type="xs:string"/>
        <xs:attributeGroup ref="display-atts"/>
        <xs:attributeGroup ref="univ-atts"/>
        <xs:attribute ref="xml:space" fixed="preserve"/>
        <xs:attributeGroup ref="global-atts"/>
  </xs:attributeGroup>

Each xs:element declaration should include descriptive documentation as in the examples above.