2.1.4.4 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>.

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.