Notes on backwards compatibility
The DITA TC has determined that changes for DITA 1.1 should be
backwards compatible with DITA 1.0. The following items are a
guide to what is or is not considered backwards compatible.
For OASIS DITA 1.1, backwards compatible means that changes must be compatible
with all preexisting documents written under DITA 1.0. Changes for DITA 1.1
do not have to be backwards compatible with vendor implementations of DITA
Backwards compatible changes
The following changes
are all backwards compatible, though the list is not considered exhaustive.
The TC has not announced any preference for one type of change over another.
- Adding a new optional attribute to an existing element.
- Adding to a list of possible attribute values, if that attribute is already
limited to a list. For example, the value "unclear-at-present" could be added
to the importance attribute.
- Adding an optional element to the content model of an existing element.
The new child element can have a fixed position in the content model, as long
as the parent does not have a mixed content model (it cannot already allow
- Changing a required attribute to optional, or changing a required element
- Creating a new element in the base topic module.
- Creating a new specialized element, following the normal rules of specialization.
Backwards incompatible changes
The following changes
are all considered backwards incompatible, and should be avoided for DITA
- Removing an attribute from an existing element.
- Changing an existing attribute to make it required, or adding a new required
- Changing or removing a value in an attribute's enumerated list. For example,
the value "obsolete" cannot be removed from the importance attribute.
- Changing an attribute's content model from CDATA to an enumerated list.
- Removing an existing element from base topic or from a specialization.
- Making an optional element required, or adding a new required element
to any content model.
- Tightening a content model is backwards incompatible. This includes:
- Removing an allowed element. For example, <refsyn> cannot be removed
from the content model of <refbody>.
- Restricting the order of child elements. For example, we cannot require
that titles appear at the start of a section.
- Making an element required. For example, we cannot require that sections
include a title.
Compatibility with the DITA architecture
to backwards compatibility, any change must be tested to ensure it does not
break other aspects of the DITA architecture. Two aspects of the architecture
that should be tested first are conref and generalization. These are picked
not because they are more important, but because they are typically the first
to break due to an incorrect design. Michael Priestley put together a use
case document that describes how to test for compatibility with these; the
document is located here: http://lists.oasis-open.org/archives/dita/200506/msg00024.html