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
- 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 .
- 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
- 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.
![](../img/ec_completeness_check.png)
- 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 Editor 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.
- From the current condition set -
The map is filtered using the condition set currently applied in the DITA Maps
Manager view. Clicking the
- 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
.
- Any
- 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 Editor 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.