Information about migrating to DITA 2.0

This section is non-normative.

This topic includes information on required steps to migrate content from DITA 1.x to DITA 2.0.

Markup to migrate for DITA 2.0

The following elements and attributes have been removed from the grammar as obsolete. They have been replaced by alternate markup or approaches.

  • The @navtitle attribute on the <topicref> element is replaced by the <navtitle> or <titlehint> element within <topicmeta>. Use <navtitle> if you wish to preserve the title in any table of contents; use <titlehint> if you only used this attribute as a hint about the topic purpose.
  • The @locktitle attribute is removed from <topicref> element. To preserve the title locking behavior, ensure you use the
  • In maps, the @title attribute on <map> is replaced by the <title> element inside of the map.
  • In maps, the @title attribute on <reltable> elements is replaced by the <title> element inside of the relationshipt table.
  • In maps, all existing values for the @chunk attribute are removed. In the attribute, the DITA 1.x token to-content is replaced by the token combine, and the by-topic token is replaced by the token split. Other tokens from 1.x are no longer supported.
  • The @alt attribute on images is removed in favor of the <alt> element within the image.
  • The @longdescref attribute on images is removed in favor of the <longdescref> element within the image.
  • The @print attribute is removed in favor of the specialized @deliveryTarget attribute.
  • The @copy-to attribute is removed in favor of an updated <resourceid> element that can specify the copy target.
  • The <substeps> and <substep> elements are removed in favor of directly nesting the <steps> element.
  • The <topicset> and <topicsetref> elements are removed in favor of the generic <topicref> element.
  • The <index-sort-as> element is removed in favor of the <sort-as> element.
  • The <titlealts> element is removed. Alternate titles are now stored within the topic <prolog>.
  • The <linktext> element in maps is removed in favor of the new <linktitle> element.
  • The <itemgroup> element is removed in favor of the <div> element.
  • The <sectiondiv> element is removed in favor of the <div> element.
  • The <state> element is removed. It can be migrated to the <data> element (if used for metadata) or to <keyword> (if used as a content element).
  • The <unknown> element is removed in favor of the <required-cleanup> element.
  • The @otherjob and @othertype attributes are removed from the <audience> element in favor of the @job and @type attributes.
  • In the @type attribute on the <hazardstatement> element, the values attention, fastpath, important, note, other, remember, restriction, and tip are removed. The @type attribute on this element is now required. Valid values are now caution, danger, notice, and warning.
  • The location of <hazardsymbol> within a hazard statement has moved. It is now located directly within the <consequence>, <howtoavoid>, <messagepanel>, or <typeofhazard> elements.
  • The &nbsp; entity is removed from the grammar files in favor of using the character or a hexidecimal entity.

Obsolete markup to remove

The following elements and attributes have been removed from the grammar as obsolete. They can be removed.

  • The <boolean> element is removed.
  • The <indextermref> element is removed.
  • The <index-base> element is removed.
  • The <data-about> element is removed.
  • The <longquoteref> element is removed.
  • The <anchor> element is removed from maps.
  • The <anchorref> element is removed from the map group domain.
  • The <hasInstance>, <hasKind>, <hasNarrower>, <hasPart>, <hasRelated>, <relatedSubjects>, <subjectRel>, <subjectRelTable>, <subjectRelHeader>, and <subjectRole> elements are removed from the subject scheme specialization.
  • The <glossAbbreviation>, <glossAlternateFor>, <glossPartOfSpeech>, <glossProperty>, <glossScopeNote>, <glossShortForm>, and <glossStatus> elements are removed from the glossentry specialization module.
  • The @collection-type attribute is removed from the <reltable> and <relcolspec> elements.
  • The @keyref attribute is removed from the <navref> element.
  • The @mapkeyref attribute is removed from all elements.
  • The @xtrc and @xtrf attributes are removed from all elements.
  • In the @collection-type attribute, the value tree is removed.
  • In the @role attribute, the values sample and external are removed.
  • In the @type attribute on the <lq> element, the values internal and external are removed.
  • In the @type attribute on the <note> element, the value fastpath is removed.
  • The @lockmeta attribute is removed from <topicmeta> in maps.
  • The @query attribute is removed from all elements.
  • The @specentry attribute is removed from all elements.
  • The @spectitle attribute is removed from all elements.
  • The @anchorref attribute is removed from the <map> element.
  • The @refcols attribute is removed from <simpletable>.
  • The @archive, @archivekeyrefs, @classid, @classidkeyref, @codebase, @codebasekeyref, @declare, and @standby attributes are removed from the <object> element.

Removed specialization modules

The following specialization modules are no longer maintained as part of the OASIS DITA specification. Although they are no longer defined within the specification, updated versions of these modules can still be used with DITA 2.0.

  • Machinery task domain
  • Classification map domain
  • Delayed conref domain
  • XNAL domain

Removed document type configurations

The following configurted shells are no longer maintained as part of the OASIS DITA specification.

  • Machinery task doctype configuration
  • Classification map doctype configuration
  • The "glossary.dtd" is removed in favor of the equivalent "glossentry.dtd" doctype configuration.

Other migration concerns

The following markup may require migration, depending on how you make use of your content.

  • If you are using @navtitle or <navtitle> in maps as a hint, without using the @locktitle attribute, you might need to switch to the new <titlehint> element.
  • The <syntaxdiagram> and <synph> elements have moved from the programming domain into a new syntax diagram domain. If you use these elements within your own configured shells, you will need to update the shells to include the new domain.
  • The @domains attribute is replaced by @specializations. This attribute is typically set to a default inside of configured doctype shells; migration will typically be required for shells but not for content.