Expansion modules

Expansion modules enable the extension of content models and attribute lists for individual elements. Expansion modules are the opposite of constraints. They add elements and attributes to specific content models and attribute lists, rather than removing them.

Overview of expansion modules

Expansion modules enable information architects to include specialized attributes or elements in specific element types, without making the specialized attributes or elements globally available.

An expansion module works in conjunction with an element or attribute specialization. An expansion module can perform the following functions:

Expand content models

Expansion modules can work in conjunction with element-specialization modules to extend the content models of specific elements. When an element-specialization module is combined with an extension module, the specialized elements can be made available only in specific contexts, rather than wherever the specialization bases are allowed.

For example, a DITA architect creates a new element-domain specialization that declares a new element specialized from <p>: <sectionDesc>. Using an extension module, the DITA architect can make <sectionDesc> available only as an optional child of <section>, rather than wherever <p> is permitted.

Expand attribute lists

Expansion modules extend the attribute lists of specific elements by adding attributes specialized from either @base or @props.

For example, an expansion for <entry>, <row>, and <colspec> can make @cell-purpose available only on those elements. The @cell-purpose attribute is specialized from @base.

The additional attribute can be either defined directly within the expansion module, or it can be defined in a separate attribute-specialization module. In either case, the token used as a value for the @specializations attribute must be defined.

Expansion module rules

There are certain rules that apply to the design and implementation of expansion modules. These rules all stem from the requirement that the content model of a specialized element must be consistent with the content model of the specialization base. After generalization, the content model of an element affected by an expansion module must match the original content model for that element.
Specialization base of expanded elements

Elements that are added to content models by expansion models must be specializations of existing elements that are permitted in the original content model.

Content model of expanded elements

Elements that are added to content models by expansion models must be allowed only where their specialization base is allowed.

For example, when creating an expansion model that adds a specialization of <data> to <ol>, the specialization of <data> must only be allowed before any <li> elements, as that is the only place that the <data> element is allowed in the content model for an ordered list.

Ordinality of expanded elements

Elements that are added to content models by expansion modules must not violate the ordinality of the original content model. If the original content model requires a child element to occur at least once, then the expanded content model cannot break this requirement. If the original content model only permits a child element to occur once, then the expanded content model cannot break this requirement.

For example, in the expansion module that adds a specialization of <data> to <ol>, the redefined content model for <ol> cannot make the <li> element optional.

However, an expansion module that adds a specialization of <li> (<listIntro>) to <ol> can redefine the content model of <ol> in the following ways:

  • Make <listIntro> the first child element and be required
  • Make <li> the second child element and optional

When a DITA topic affected by this expansion module is generalized, the resulting markup would be valid; the content model of <ol> would be respected.

Aggregation of constraint modules

The content model of an element can be modified by either of the following element-configuration modules:

  • Constraint module
  • Expansion module

For any document-type shell, the content model of an element can only be modified by a single element-type configuration module. If multiple constraints or extensions need to be applied to a single element, the element configurations must be combined into a single module that reflects all the constraints and expansions that were defined in the original separate modules.