DITA Map Validation and Completeness Check

You should validate your DITA maps regularly to make sure that your maps and topics are valid, and all of the relationships between them are working. Changing one topic, image, or piece of metadata may create errors in references that rely on them. You may not discover these problems all at once. Validate your map to catch all of these kinds of problems. The longer you wait between validating your maps, the more difficult it may be to detect and correct any errors you find.

Validating a DITA Map

To validate a DITA, follow these steps:

In the DITA Maps Manager view, make sure that the tab that holds your root map is selected and that the Context selection is set either to the name of your root map or to <current map>.
It is a good practice to refresh your DITA map before running the validation process. To do so, select the DITA map in the DITA Maps Manager view and click File > Refresh (F5).
Click the Validate and Check for Completeness buttonon the DITA Maps Manager toolbar to open the DITA Map Completeness Check dialog box.
If you are using profiling, check the Use DITAVAL filters box and select the appropriate option.
Select any other options you want to check.
Click Check to run the validation process.

Result: The progress of the operation is shown as a task in the Progress view and the operation can be stopped from there.

Validation Process

The validation process of a DITA map includes the following:

Verifies that the file paths of the topic references are valid. For example, if an @href attribute points to an invalid file path, it is reported as an error in the message panel at the bottom of the editor.
Validates each referenced topic and map. Each topic file is opened and validated against the appropriate DITA DTD. If another DITA map is referenced in the main one, the referenced DITA map is verified recursively, applying the same algorithm as for the main map.
If errors or warnings are found, they are displayed in a separate message pane at the bottom of the editor and clicking them takes you to the location of the error or warning in the file where it was found.

DITA Map Completeness Check Dialog Box

The DITA Map Completeness Check dialog box allows you to configure the DITA map validation.

Figure 1. DITA Map Completeness Check Dialog Box

You can configure the validation process with the following options that are available in the DITA Map Completeness Check dialog box:

Batch validate referenced DITA resources

This option specifies the level of validation that applies to referenced DITA files:

If the checkbox is left unchecked (default setting), the DITA files will be validated using the rules defined in the DTD or XML Schema declared in the document.
If the checkbox is selected, the DITA files will be validated using rules defined in their associated validation scenario.

Check the existence of non-DITA references resources

Extends the validation of referenced resources to non-DITA files.

Include remote resources: Select this option if you want to check that remote referenced binary resources (such as images, movie clips, ZIP archives) exist at the specified location.

Use DITAVAL filters

The content of the map is filtered by applying a profiling condition set before validation.

Note: The validation process also takes branch filtering <ditavalref> elements into account as long as they appear before the referenced topics.

You can choose between the following options:

From the current condition set - The map is filtered using the condition set currently applied in the DITA Maps Manager view. Clicking the Details icon opens a topic in the Oxygen XML Author Eclipse plugin User Guide that explains how to create a profiling condition set.
From all available condition sets - For each available condition set, the map content is filtered using that set before validation.
From the associated transformation scenario - The filtering condition set is specified explicitly as a DITAVAL file in the current transformation scenario associated with the DITA map.
Other DITAVAL files - For each DITAVAL file from this list, the map content is filtered using the DITAVAL file before validation. Use the Add or Remove buttons to configure the list. The Add button opens a dialog box that allows you to select a local or remote path to a DITAVAL file. You can specify the path by using the text field, its history drop-down, the Insert Editor Variables button, or the browsing actions in the Browse drop-down list.

Report references to resources outside of the DITA map folder

If selected, it will report any references to DITA resources that are located outside the main DITA map folder.

Report links to topics not referenced in DITA maps

Checks that all the topics referenced by other topics are also linked in the DITA map. Also reports related links defined in relationship tables whose target topics are not referenced in the DITA Map.

Report multiple references to the same topic

If selected, it will report warnings when a topic is referenced multiple times in the DITA map, unless a unique @copy-to attribute is used on the <topicref> element for any topic that is referenced multiple times.

For example, it will not report a warning if there is a topic referenced twice, but the second <topicref> has a @copy-to attribute set:

<topicref href="topic.dita"/>
.....
 <topicref href="topic.dita" copy-to="topic2.dita"/>

On the other hand, it will report a warning if there is a topic referenced twice and none of the reference-type elements has a @copy-to attribute set or both of them have the @copy-to attribute set to the same value:

<topicref href="topic.dita" copy-to="topic2.dita"/>
......
 <topicref href="topic.dita" copy-to="topic2.dita"/>

Check for duplicate topic IDs within the DITA map context

Checks for multiple topics with the same ID in the context of the entire map.

Report duplicate key definitions

Checks the DITA map for multiple key references with the same key defined for them. This is helpful because if you have two different resources with the same value for the @keys attribute, all references will point to the first one encountered and the other will be ignored.

Note: This option takes key scopes into account. For example, if you have something like this:

<topicref href="t2.dita" keys="k2"/>
    <topicgroup keyscope="ks">
        <topicref href="t2.dita" keys="k2"/>    
    </topicgroup>

it will not report the "k2" key as a duplicate because it is defined in a key scope on the second occurrence.

Report unreferenced key definitions

Checks the entire DITA map and reports any key definitions that are not referenced anywhere. Note that if the Use DITAVAL filters option is selected, this check will search for unreferenced key definitions based upon your selected filter.

Report unreferenced reusable elements

Checks the entire DITA map and reports any detected reusable elements that are not referenced anywhere. It looks for elements that have an ID specified in the following types of topic references:

Any <topicref> that contains a @processing-role attribute set to resource-only.
Any other referenced topic that contains elements that are reused elsewhere through a @conref or @conkeyref.

Report table layout problems

Looks for table layout problems. The types of errors that may be reported include:

If a row has fewer cells than the number of columns detected.
For a CALS table, if a cell has a vertical span greater than the available rows count.
For a CALS table, if the number of <colspecs> is different than the number of columns detected from the table @cols attribute.
For a CALS table, if the number of columns detected from the table @cols attribute is different than the number of columns detected in the table structure.
For a CALS table, if the value of the @cols, @rowsep, or @colsep attributes are not numeric.
For a CALS table, if the @namest, @nameend, or @colname attributes point to an incorrect column name.

Identify possible conflicts in profile attribute values

When the profiling attributes of a topic contain values that are not found in parent topic profiling attributes, the content of the topic is overshadowed when generating profiled output. This option reports these possible conflicts.

Report attributes and values that conflict with profiling preferences

Looks for profiling attributes and values that are not defined in the Profiling / Conditional Text preferences page (you can click the

Profiling Preferences button to open this preferences page). It also checks if profiling attributes defined as single-value have multiple values set in the searched topics.

Additional Schematron checks

Allows you to select a Schematron file that Oxygen XML Author Eclipse plugin will use for the validation of DITA resources. You can specify the path by using the text field, its history drop-down, the

Insert Editor Variables button, or the browsing actions in the

Browse drop-down list.

Advanced Tip: Some APIs are available that retrieve information about DITA keys that are referenced within a topic. The APIs can be called from XSLT Stylesheets (including XML Refactoring operations) or Schematron schemas. For details, see API Documentation: DITAXSLTExtensionFunctionUtil.

Export settings

Allows you to export the settings assigned in this dialog box to an XML file that you can share with other users or use on other systems.

Import settings

Allows you to import settings for this dialog box from an XML file that was created by the Export settings action.

Check

Use the Check button to begin the validation process. The options that you choose in this dialog box are preserved between sessions.

Tip: This function can be executed from an automated command-line script, for more details, see Scripting Oxygen.