Constraints

Constraint modules restrict content models or attribute lists for specific element types, remove certain extension elements from an integrated domain module, or replace base element types with domain-provided, extension element types.

Overview of constraints

Constraint modules enable information architects to restrict the content models or attributes of DITA elements. A constraint is a simplification of an XML grammar such that any instance that conforms to the constrained grammar also will conform to the original grammar.

A constraint module can perform the following functions:

Restrict the content model for an element

Constraint modules can modify content models by removing optional elements, making optional elements required, or requiring unordered elements to occur in a specific sequence. Constraint modules cannot make required elements optional or change the order of element occurrence for ordered elements.

For example, a constraint for <topic> can require <shortdesc>, can remove <abstract>, and can require that the first child of <body> be <p>. A constraint cannot allow <shortdesc> to follow <prolog>, because the content model for <topic> requires that <shortdesc> precedes <prolog>.

Restrict the attributes that are available on an element

Constraint modules can restrict the attributes that are available on an element. They also can limit the set of permissible values for an attribute.

For example, a constraint for <note> can limit the set of allowed values for the @type attribute to "note" and "tip". It also can omit the @othertype attribute, since it is needed only when the value of the @type attribute is "other".

Restrict the elements that are available in a domain

Constraint modules can restrict the set of extension elements that are provided in a domain. They also can restrict the content models for the extension elements.

For example, a constraint on the programming domain can reduce the list of included extension elements to <codeph> and <codeblock>.

Note (non-normative):

For DITA implementations that use RNG-based grammar files, restricting the set of extension elements that are provided in a domain can be handled simply by document-type configuration.

Replace base elements with domain extensions

Constraint modules can replace base element types with the domain-provided extension elements.

For example, a constraint module can replace the <ph> element with the domain-provided elements, making <ph> unavailable.

Constraint rules

There are certain rules that apply to the design and implementation of constraints.

Content model

The content model for a constrained element must be at least as restrictive as the unconstrained content model for the element.

Domain constraints

When a domain module is integrated into a document-type shell, the base domain element can be omitted from the domain extension group or parameter entity. In such a case, there is no separate constraint declaration, because the content model is configured directly in the document-type shell.

A domain module can be constrained by only one constraint module. This means that all restrictions for the extension elements that are defined in the domain must be contained within that one constraint module.

Structural constraints

Each constraint module can constrain elements from only one vocabulary module. For example, a single constraint module that constrains <refsyn> from reference.mod and constrains <context> from task.mod is not allowed. This rule maintains granularity of reuse at the module level.

Constraint modules that restrict different elements from within the same vocabulary module can be combined with one another. Such combinations of constraints on a single vocabulary module have no meaningful order or precedence.

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.

Constraints, processing, and interoperability

Because constraints can make optional elements required, documents that use the same vocabulary modules might have incompatible constraints. Thus the use of constraints can affect the ability for content from one topic or map to be used in another topic or map.

A constraint does not change basic or inherited element semantics. The constrained instances remain valid instances of the unconstrained element type, and the element type retains the same semantics and @class attribute declaration. Thus, a constraint never creates a new case to which content processing might need to react.

For example, a document type constrained to require the <shortdesc> element allows a subset of the possible instances of the unconstrained document type with an optional <shortdesc> element. Thus, the content processing for topic still works when <topic> is constrained to require a short description. Similarly, an unconstrained task is compatible with an unconstrained topic, because the <task> element can be generalized to <topic>.

However, if a topic document type is constrained to require the <shortdesc> element, a document type with an unconstrained task is not compatible with the constrained topic document type, because some instances of the task might not have a <shortdesc> element. But, if the task document type also has been constrained to require the <shortdesc> element, it is compatible with the constrained topic document type.