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

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:

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.

Return to main page.

OASIS DITA Version 1.2 -- OASIS Standard, 1 December 2010
Copyright © OASIS Open 2005, 2010. All Rights Reserved.