RELAX NG: Coding requirements for element type declarations

Element definitions

A structural or element-domain vocabulary module must contain a declaration for each specialized element type that is named in the module. While the XML standard allows content models to refer to undeclared element types, all element types that are named in content models or attribute list declarations within a vocabulary module must have a RELAX NG element declaration. The RELAX NG element declaration can occur in one of the following:

• The vocabulary module
• A base module of which the vocabulary module is a direct or indirect specialization
• (If the vocabulary module is a structural module) A required domain or structural module

The element type patterns are organized into the following sections:

Element type name patterns

For each element type that is declared in the vocabulary module, there must be a pattern whose name is the element type name and whose content is a reference to the element type tagname.element pattern. For example:

<div>
  <a:documentation>ELEMENT TYPE NAME PATTERNS</a:documentation>
  <define name="b">
    <ref name="b.element"/>
  </define>
  <!-- ... -->
</div>

The element-type name pattern provides a layer of abstraction that facilitates redefinition. The element-type name patterns are referenced from content model and domain extension patterns. Specialization modules can re-declare the patterns to include specializations of the type, allowing the specialized types in all contexts where the base type is allowed.

The declarations can occur in any order.

Common content-model patterns

Structural and element-domain modules can include a section that defines the patterns that contribute to the content models of the element types that are defined in the module.

Common attribute sets

Structural and element-domain modules can include a section that defines patterns for attribute sets that are common to one or more of the element types that are defined in the module.

Element type declarations

For each element type that is declared in the vocabulary module, the following set of patterns must be used to define the content model and attributes for the element type. Each set of patterns is typically grouped within a <div> element for clarity.

• tagname.content defines the complete content model for the element tagname. The content model pattern can be overridden in constraint modules to further constrain the content model for the element type.
• tagname.attributes defines the complete attribute list for the element tagname, except for @class and the attributes provided by the global-atts pattern. The attribute list declaration can be overridden in constraint modules to further constrain the attribute list for the element type.
• tagname.attlist is an additional attribute list pattern with a @combine attribute set to the value "interleave". This pattern contains only a reference to the tagname.attributes pattern.
• tagname.element is the actual element type definition. It contains an <element> element whose @name value is the element type name and whose content is a reference to the tagname.content and tagname.attlist patterns. In OASIS grammar files, the @longName attribute in the DITA architecture namespace is also used to help enable generation of DTD and XSD grammar files.

The following example shows the declaration for the <topichead> element, including the definition for each pattern described above.

<div>
  <a:documentation>LONG NAME: Topic Head</a:documentation>
  <define name="topichead.content">
    <optional>
      <ref name="topicmeta"/>
    </optional>
    <zeroOrMore>
      <choice>
        <ref name="anchor"/>
        <ref name="data.elements.incl"/>
        <ref name="navref"/>
        <ref name="topicref"/>
      </choice>
    </zeroOrMore>
  </define>
  <define name="topichead.attributes">
    <optional>
      <attribute name="navtitle"/>
    </optional>
    <optional>
      <attribute name="outputclass"/>
    </optional>
    <optional>
      <attribute name="keys"/>
    </optional>
    <optional>
      <attribute name="copy-to"/>
    </optional>
    <ref name="topicref-atts"/>
    <ref name="univ-atts"/>
  </define>
  <define name="topichead.element">
    <element name="topichead" ditaarch:longName="Topic head">
      <a:documentation>The &lt;topichead> element provides a title-only entry in a navigation map,
        as an alternative to the fully-linked title provided by the &lt;topicref> element. 
        Category: Mapgroup elements</a:documentation>
      <ref name="topichead.attlist"/>
      <ref name="topichead.content"/>
    </element>
  </define>
  <define name="topichead.attlist" combine="interleave">
    <ref name="topichead.attributes"/>
  </define>
</div>

idElements pattern contribution

Element types that declare the @id attribute as type "ID", including all topic and map element types, must provide a declaration for the idElements pattern. This is needed to correctly configure the "any" pattern override in document-type shells and avoid errors from RELAX NG parsers. The declaration is specified with a @combine attribute set to the value "choice". For example:

<div>
  <a:documentation>LONG NAME: Map</a:documentation>
  <!-- ... -->
  <define name="idElements" combine="choice">
    <ref name="map.element"/>
  </define>
</div>

Specialization attribute declarations

A vocabulary module must define a @class attribute for every specialized element. This is done in a section at the end of each module that includes a tagname.attlist pattern for each element type that is defined in the module. The declarations can occur in any order.

The tagname.attlist pattern for each element defines that element's @class attribute, and also includes a reference to the global-atts attribute list pattern. @class is declared as an optional attribute; the default value is declared using the @a:defaultValue attribute, and the value of the attribute is constructed according to the rules in @class attribute rules and syntax.

For example:

<define name="anchorref.attlist" combine="interleave">
  <ref name="global-atts"/>
  <optional>
    <attribute name="class" 
        a:defaultValue="+ map/topicref mapgroup-d/anchorref "
    />
  </optional>
</define>