Copyright (c) 2016 HERE Europe B.V.

See the LICENSE file in the root of this project for license details.

The DITA Validator plug-in for DITA-OT is a structure, style and content checker for DITA documents. The plug-in returns information about the compliance of the document against a modifiable series of validator rules. The plug-in also supports standard XML validation

The plug-in supports two transtypes - it can either echo results to the command line or return a report in Schematron Validation Report Language (SVRL) format. More information about SVRL can be found at www.schematron.com

For any DITA publication to build successfully, all its files must contain valid DITA markup.

General XML validation rules require that:

• Documents are well formed.
• Documents contain only correctly encoded legal Unicode characters.
• None of the special syntax characters such as "<" and "&" appear except as markup delineators.
• The beginning and end tags must match exactly, unless tags are self-closing.
• A single root element such as <topic>, contains all the other elements.
• <topic> within a DITA document must conform to the topic.dtd Document Type Defintion

The DITA Validator extends the concept of XML validation to run a series of structure and style compliance rules. Sample rules include:

• Whether the source files for <image> and <codeblock> elements exist
• Whether conref attributes are linking to missing elements
• Whether every <section> or <fig> element in the document has a meaningful id
• Whether every <section> element has a title
• If an <xref> refers to a location on the web, both the scope="external" and format="html" attributes must be set
• Whether all id attributes are lower case and dash separated
• Whether any blacklisted words are found within the document.
• Whether the document will be unable to render as PDF due to empty <table> elements

The validator has been tested against DITA-OT 2.2.x. It is recommended that you upgrade to the latest version. Running the validator plug-in against earlier versions of DITA-OT will not work as it uses the newer getVariable template. To work with DITA-OT 1.8.5 this would need to be refactored to use getMessage

The DITA Validator is a plug-in for the DITA Open Toolkit.

• Install the DITA-OT distribution JAR file dependencies by running gradle install from your clone of the DITA-OT repository.

The required dependencies are installed to a local Maven repository in your home directory under .m2/repository/org/dita-ot/dost/.

• Run the Gradle distribution task to generate the plug-in distribution package:

./gradlew dist

The distribution ZIP file is generated under build/distributions.

• Run the plug-in installation command:

dita -install https://github.com/heremaps/com.here.validate.svrl/archive/v1.0.0.zip

The dita command line tool requires no additional configuration.

A test document can be found within the plug-in at PATH_TO_DITA_OT/plugins/com.here.validate.svrl/sample

To create an SVRL file use the svrl transform.

• From a terminal prompt move to the directory holding the document to validate

• Clean the output directory (named "out" in the examples below), to ensure that the result from an old validation run is not present.

rm -rf ./out

• SVRL file creation (svrl) can be run like any other DITA-OT transform:

PATH_TO_DITA_OT/bin/dita -f svrl -o out -i document.ditamap

Once the command has run, an SVRL file is created

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<svrl:schematron-output>
	<active-pattern name="common-content-rules" role="content">
		<fired-rule context="title"/>
		<fired-rule context="p"/>
		<fired-rule context="section[id=&#34;good&#34;]"/>
		<fired-rule context="title"/>
		<fired-rule context="section[id=&#34;bad&#34;]"/>
		<fired-rule context="title"/>
		<failed-assert location="/topics/comment-fixme.dita" role="warning">
			<diagnostic-reference diagnostic="comment-fixme">Line 15: section[id="bad"] - [comment-fixme]
				Found 'FIXME' comments within the &lt;section&gt; element - fix as requested and delete the comment.
				FIXME 61) This comment requires action
			</diagnostic-reference>
		</failed-assert>
	</active-pattern>
</svrl:schematron-output>

To echo results to the command line use the svrl-echo transform.

• Clean the output directory, to ensure that the result from an old validation run is not present.

rm -rf ./out

• Document validation (svrl-echo) can be run like any other DITA-OT transform:

PATH_TO_DITA_OT/bin/dita -f svrl-echo -i document.ditamap

Once the command has run, all errors and warnings are echoed to the command line

[echo] [WARN]	 [/out/temp/dita/topics/comment-fixme.dita]
[echo]	 Line 15: section[id="bad"] - [comment-fixme]
[echo] Found 'FIXME' comments within the <section> element - fix as requested and delete the comment.
[echo]
[echo]	FIXME 61) This comment requires action
[echo]
[echo] Found 0 Errors 1 Warnings

Additionally, if an error occurs, the command will fail

[echo] [ERROR]	[/document.ditamap]
[echo]	 Line 89: topicref - [href-not-lower-case]
[echo] The value provided in href="topics/FILE-NOT-LOWER-CASE.dita" is invalid, allowed characters are: lowercase, a-z only, words separated by hyphens.
[echo]
[echo] Found 1 Errors 0 Warnings
Error: Errors detected during validation

An Ant build file is supplied in the same directory as the sample document. The main target can be seen below:

<dirname property="dita.dir" file="PATH_TO_DITA_OT"/>
<property name="args.input" value="PATH_TO_DITA_DOCUMENT/document.ditamap"/>
<path id="dita.ot.classpath">
	... etc..
</path>
<target name="validate">
	<java classname="org.apache.tools.ant.launch.Launcher" fork="true" failonerror="true" classpathref="dita.ot.classpath">
		<arg value="-Dargs.input=${args.input}"/>
		<arg value="-Ddita.dir=${dita.dir}"/>
		<arg value="-buildfile"/>
		<arg value="${dita.dir}/build.xml"/>
		<arg value="-Dgenerate-debug-attributes=false"/>
		<arg value="-Doutput.dir=out/svrl"/>
		<arg value="-Dtranstype=svrl-echo"/>
		<arg value="-Dargs.validate.blacklist=(kilo)?metre|colour|teh|seperate"/>
		<arg value="-Dargs.validate.check.case=Bluetooth|HTTP[S]? |ID|IoT|JSON|Java|Javadoc|JavaScript|XML"/>
		<arg value="-Dargs.validate.mode=default" />
		<arg value="-S"/>
		<arg value="-q"/>
	</java>
</target>

• args.validate.ignore.rules - Comma separated list of rules not to be enforced
• args.validate.blacklist - Comma separated list of words not to be present in the running text
• args.validate.check.case - Comma separated list of words which have a specified capitalization
• args.validate.mode - Validation reporting mode. The following values are supported:
  • strict - Outputs both warnings and errors. Fails on errors and warnings.
  • default - Outputs both warnings and errors. Fails on errors only
  • lax - Ignores all warnings and outputs errors only. Fails on Errors only
• svrl.customization.dir - Specifies the customization directory
• svrl.filter.file - Specifies the location of the XSL file used to filter the echo output

This DITA-OT plug-in contains a common ruleset of general validator rules. The ruleset has been designed to be applicable to all documents created by all users. To add new custom rules (which only apply to your specific use case) you should create a separate custom validator plug-in which extends the base validator. See the sample Extended DITA Validator as an example of how to do this.

The severity of a validator rule can be altered by amending entries in the cfg/rulesset/default.xml file The plug-in supports four severity levels:

• FATAL - Fatal rules will fail validation and cannot be overridden.
• ERROR - Error rules will fail validation. Errors can be overridden as described above.
• WARNING - Warning rules will display a warning on validation, but do not fail the validation. Warnings can also be individually overridden.
• INACTIVE - Inactive rules are not applied.

Rules can be made inactive by altering the severity (see above). Alternatively a rule can be commented out in the XSL.

To completely remove rules which do not apply to your document set, you can create a customized DITA-OT plug-in which extends the base validator. See the Extended DITA Validator as an example of how to do this.

Individual rules can be ignored by adding the args.validate.ignore.rules parameter to the command line. The value of the parameter should be a comma-delimited list of each rule-id to ignore.

For example to ignore the table-id-missing validation rule within a document you would run:

PATH_TO_DITA_OT/dita -f svrl-echo -i document.ditamap -Dargs.validate.ignore.rules=table-id-missing

Specific instances of a rule can be ignored by adding a comment within the *.dita file. The comment should start with ignore-rule, and needs to be added at the location where the error is flagged.

...
<table platform="pdfonly" frame="none" >
	<!-- ignore-rule:table-id-missing -->
	<tgroup cols="1">
		<colspec colname="c1" colnum="1" colwidth="336pt"/>
		<tbody>
			<row>
				<entry>&#xA0;</entry>
			</row>
		</tbody>
	</tgroup>
</table>

Some rules such as FIXME and TODO in the running text need to be double escaped as shown below:

• Add a comment line with the text ignore-rule:running-text-* to ignore the issue flagged in the text below (no FIXMEs allowed in the running text)
• Add the comment-* to the list of ignored rules to ignore the fact that the comment itself fails an additional rule (no FIXMEs allowed in the comments)

<!--
	We want to display the text below which would usually
	result in a warning
-->
<p>
	<!-- ignore-rule:running-text-fixme,comment-fixme -->
	FIXME is usually banned in the running text.
</p>

A sample document can be found within the plug-in which can used to test validator rules. The document covers with positive and negative test cases. The sample document contains "broken" DITA which cannot be built as a PDF document - please use the html transform to read the contents or examine the *.dita files directly.

A complete list of rules covered by the DITA validator can be found below. The final <chapters> of the sample document contain a set of test DITA <topics>, each demonstrating a broken validation rule.

The <topic> files are sorted as follows:

• The base plug-in (com.here.validate.svrl) – this <chapter> contains a set of common validator rules applicable to all users. The rules are grouped thematically according to the name of the associated <active-pattern> within the XSL stylesheets of the plug-in and then are listed alphabetically by rule-id within the group. The following types of validation rules are supported: - style – Style rules enforce a standardized look and feel across DITA elements and ensure a better SEO and consistency. Alteration or removal of these rules should not affect the ability of DITA-OT to create a valid document. - structure – Structure rules offer an error reporting mechanism against fatal changes which would result in an invalid DITA document. If these rules are altered or removed, errors will not be caught up-front and DITA-OT will not be able to build a valid document. Examples include a conref link to a non-existent topic or an attempt to create a table containing no row elements. - content – These rules check the text within the DITA elements themselves, for example blacklisted words.
• The extended plug-in (com.here.validate.svrl.overrides) – This <chapter> shows how to modify, relax or remove existing validator rules and create additional custom validator rules. The custom rules are listed alphabetically by rule-id.

Note that extended rules will only be detected if the overrides transform from the Extended DITA Validator is used.

The following tables list the validator error messages by type and message ID. Base DITA validator rules are in normal text. Rules in bold are examples of custom rules which can be detected if the overrides transform from the Extended DITA Validator is used.