Migrating from DITA 1.1 to 1.2
Migration of task specializations
DITA 1.2 relaxes the content model for the <taskbody> element in the base <task> topic type. Specializations of <task> that use the <taskbody> element unchanged or use the content-model parameter entities for task body will use the more general DITA 1.2 task model when used with the DITA 1.2 task module.
If a document should use the strict task model instead of the new general task model:
- Documents that use the task topic type included with the OASIS DITA 1.2 specification will not need to migrate. This includes documents that use task inside of the ditabase document type included with the DITA 1.2 specification.
- Documents that use the standard task module inside of a new document type shell, or in a local ditabase document type, will need to migrate in order to preserve the module.
- Documents that use a specialization of task with a specialized element to replace <taskbody> will not need to migrate. Documents that specialize task but reuse the <taskbody> element will need to migrate.
For documents that do not use the standard OASIS DITA doctypes for which the strict task model from DITA 1.0 and 1.1 is desired, the strict task model can be restored by using the strict Taskbody Constraint module, by creating and integrating a constraint module similar to the strict Taskbody Constraint, or by adjusting the specialization's content models to impose the appropriate constraints.
To integrate the strict Taskbody Constraint module in a DTD, add the following content
immediately before the section that imports the "topic.mod" file. The
strictTaskbodyConstraint.mod file must be defined in any catalog used to
locate DTD modules. See the
task.dtd file in the OASIS DITA 1.2 DTD package
<!ENTITY % strictTaskbody-c-def PUBLIC "-//OASIS//ELEMENTS DITA 1.2 Strict Taskbody Constraint//EN" "strictTaskbodyConstraint.mod"> %strictTaskbody-c-def;
To do the same thing for a schema, the
file must be defined in the catalog used to resolve the schema using the following
<xs:include> element should be placed immediately before the <xs:include> for
<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:strictTaskbodyConstraintMod.xsd:1.2" />
Documents which use the task document type from OASIS and wish to make use of the general <taskbody> model must also be migrated. In this case, the documents must be updated to reference the General Task document type instead of the traditional Task document type. For DTD-based documents, this means that the document type declaration must change as follows within each task document:
DITA 1.1: <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> DITA 1.2: <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA General Task//EN" "generalTask.dtd">
For Schema based documents, the xsi:noNamespaceSchemaLocation attribute must change on each task element:
DITA 1.1: <task xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:task.xsd" DITA 1.2: <task xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:oasis:names:tc:dita:xsd:generalTask.xsd"
Use of glossary document type shell and module files
The files named
glossary.ent in DITA 1.1 have been renamed to
glossentry.ent in order to follow the file naming requirements for
vocabulary modules. The XML Schema files
glossaryMod.xsd have been
glossentryMod.xsd.The DITA 1.2 entity resolution catalogs map the public
identifiers for the
glossary.* files to the corresponding
glossentry.* files and URNs for the
files to the corresponding
glossentry*.xsd files, meaning that existing
documents and shell document types that refer to the
glossary.* files will
continue to work with DITA 1.2.
However, shell document types that refer to the
glossary.* files should
be updated to refer to the corresponding
glossentry.* files as it is
convenient to do so.
Migration of specializations to reflect new implementation patterns
DITA 1.2 defines new implementation patterns for specializations. It is not necessary to update existing specialization modules to reflect these new patterns. However, specializations that want to enable the use of constraint modules must be updated to provide per-element-type content model and attribute list parameter entities.
Existing specializations may benefit from the new DITA 1.2 ability to have structural modules that depend on and specialize elements from domains.
Update of domains attributes for specializations
In DITA 1.1 the @domains attribute only listed the domains on which a given map or topic type depended. In DITA 1.2 the @domains attribute should also list structural modules and constraint modules, providing a complete list of the vocabulary modules that a given map or topic type depends on in the context of a given DITA document type.
Existing structural specializations should be updated to include the structural module names in their domains attribute configuration entities. Having a complete declaration of all structural and domains modules in the @domains attribute allows processors to determine the set of required modules for a given topic or map document without also examining all the @class attributes of all the elements in the document.
XML Schema declaration of domains attribute
For XML schema shell document types, the way the domains attribute is declared has changed. In DITA 1.1 the domains attribute was defined using an <xs:redefine> element. For DITA 1.2 the attribute is defined in document type shells and referenced from modules, like so:
<xs:attributeGroup name="domains-att"> <xs:attribute name="domains" type="xs:string" default="(topic ui-d) (topic hi-d) (topic sw-d) (topic pr-d) (topic ut-d) (topic indexing-d) (topic hazard-d) (topic abbrev-d)" /> </xs:attributeGroup>
XML Schema document type shells must be updated to use the new declaration mechanism in order to continue to be valid XSD schemas.