Constraints

Constraint modules define additional constraints for corresponding vocabulary modules in order to restrict content models or attribute lists for specific element types, remove extension elements from an integrated domain module, or replace base element types with domain-provided extension element types. Constraint modules do not and cannot change element semantics, only the details of how element types can be used in the context of a specific concrete document type. Because constraints can make optional elements required, documents that use the same vocabulary modules may still have incompatible constraints. Thus the use of constraints can affect the ability for content from one topic or map to be used directly in another topic or map.

Each constraint integrated into a DITA document type must be declared in the @domains attribute for each structural type integrated into the document type.

A constraint module may define any of the following types of constraint:

Restriction of content model or attributes for an element

Constraint modules may modify base content models by removing optional elements, making optional elements required, or requiring unordered elements to occur is 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> could require <shortdesc>, could remove <abstract> altogether, and could require that the first child of <body> be <p>. A constraint cannot allow <shortdesc> to follow <prolog>, because the base content model for <topic> declares <shortdec> to precede <prolog>.

Restriction of extension elements from a domain

Constraint modules for element domains may define a subset of the base set of extension elements provided by the element domain.

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

Replacement of base elements by domain extensions

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

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

In a shell document type, when integrating a domain, the base domain element may be omitted from the domain extension group or parameter entity. While there is no separate content model constraint declaration in this case (because the content model is configured directly in the shell document type) the constraint should be declared in the @domains attribute and therefore there must be a domains module file that provides the constraint's contribution to the @domains attribute.

There may be at most one constraint module that defines the content model for a given element type included in a given concrete document type. This means that constraints for the same element type defined in two different constraint modules cannot be aggregated together. In that case, a new constraint module must be created that reflects the aggregation of the two original constraints.

Constraint rules

Constraint modules must conform to the following requirements:

Designers must implement constrained content models for element types that are more restrictive than the unconstrained content models for the same element types.
The content model and attributes of one element type can be constrained only by one constraint module included in a document type shell.
The list of extension element types provided by a domain module can be constrained only by one constraint module included in a document type shell.
Each constraint module may constrain element types from only one vocabulary module. This rule maintains granularity of reuse at the module level.
Constraint modules that restrict different element types within the same vocabulary module can be combined with one another or with a constraint module that selects a subset of the extension element types for the vocabulary. Such combinations of constraints on a single vocabulary module have no meaningful order or precedence.
Designers have the option to declare a constraint module or combination of constraint modules to be more restrictive than another constraint module or combination of constraint modules on the same vocabulary module or a base vocabulary module. This option is particularly useful when a designer wants to constrain base and specialized element types in a consistent way. The advantage of declaring the consistency is that processors can take advantage of the consistency when converting document instances.

For example, a constraint module for <topic> that requires both <shortdesc> and <body> is more restrictive than a similar constraint module that only requires <body>. By declaring this relationship, a designer may indicate that documents which use the first constraint also comply with the looser constraint.

Content processing

A document type with constraints allows a subset of the possible instances of a document type for the same vocabularies without constraints. To put it another way, all instances of the constrained document type are guaranteed to be valid instances of the unconstrained document type.

As a result, a constraint does not and cannot 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 may 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.

Content interoperability

DITA document instances declare (by means of the @domains attribute and the @class attribute for the topic or map elements) the vocabularies available in its document type. A processor may examine these declarations to determine whether or not a document instance uses a subset of the vocabularies in another DITA document type and is thus compatible with the other DITA document type.

A constrained document type allows only a subset of the possible instances of the unconstrained document type. Thus, for a processor to determine whether a document instance is compatible with another document type, the document instance must declare any constraints on the document type.

For instance, an unconstrained task is compatible with an unconstrained topic because the task can be generalized to topic. If, however, the topic is constrained to require the <shortdesc> element, a document type with an unconstrained task is not compatible with the constrained document type because some instances of the task might not have a <shortdesc> element. If, however, the task document type has also been constrained to require the <shortdesc> element, it is compatible with the constrained topic document type.