Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/heremaps/com.here.validate.svrl.overrides

Shows how to add, remove or extend the ruleset of the base DITA Validator (com.here.validate.svrl).
https://github.com/heremaps/com.here.validate.svrl.overrides

dita-ot documentation plugin validator xml xslt

Last synced: about 2 months ago
JSON representation

Shows how to add, remove or extend the ruleset of the base DITA Validator (com.here.validate.svrl).

Host: GitHub
URL: https://github.com/heremaps/com.here.validate.svrl.overrides
Owner: heremaps
License: apache-2.0
Created: 2016-08-30T12:46:16.000Z (over 8 years ago)
Default Branch: master
Last Pushed: 2019-03-12T11:54:27.000Z (almost 6 years ago)
Last Synced: 2024-11-06T20:07:41.822Z (3 months ago)
Topics: dita-ot, documentation, plugin, validator, xml, xslt
Language: XSLT
Size: 91.8 KB
Stars: 5
Watchers: 6
Forks: 4
Open Issues: 0
Metadata Files:
- Readme: readme.md
- License: LICENSE

Awesome Lists containing this project

README

Extended DITA Validator for DITA-OT
===================================

See the [LICENSE](LICENSE) file in the root of this project for license details.

Introduction
------------

The [DITA Validator](https://github.com/heremaps/com.here.validate.svrl) plug-in is a structure, style and content checker for DITA documents. The base [DITA Validator](https://github.com/heremaps/com.here.validate.svrl) returns information about the compliance of the document against a modifiable series of validator rules. The plug-in also supports standard XML validation.

This plug-in is an **extension** of the base [DITA Validator](https://github.com/heremaps/com.here.validate.svrl), and shows how to add, remove or extend the ruleset of the base [DITA Validator](https://github.com/heremaps/com.here.validate.svrl). Developers should examine the files structure within the plug-in to see how to do this.

The **Extended** Validator plug-in is a demonstration module. It is assumed that developers will modify the supplied ruleset to suit their individual business case. Like the base [DITA Validator](https://github.com/heremaps/com.here.validate.svrl), it 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](http://www.schematron.com/validators.html)

### What Is Valid XML?

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.
- A single root element contains all the other elements.
- Each `` within document must conform to the `topic.dtd` Document Type Defintion

### Validator compliant DITA

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

- Whether the source files for `` and `` elements exist
- Whether `conref` attributes are linking to missing elements
- Whether every `` or `` element in the document has a meaningful `id`
- Whether every `` element has a title
- If an `` 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 as PDF render due to empty `` elements

The extended plug-in shows how to add additional rules, and includes some extra rules which may or may not be applicable to your documentation set.

Prerequisites
-------------

### Requirements

The Extended 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`

### Installing DITA-OT

The Extended Validator is a plug-in for the DITA open toolkit. Futhermore, it is not a stand alone plug-in as it extends the base validator plug-in.

- install the DITA-OT distribution JAR file dependencies by running `gradle install` from your clone of the [DITA-OT repository](https://github.com/dita-ot/dita-ot).

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:

```bash
./gradlew dist
```

The distribution ZIP file is generated under `build/distributions`.

### Installing the Base Plug-in

- Run the plug-in installation command:

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

Installation
-----------

### Installing the Extended Plug-in

- Run the plug-in installation command:

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

The `dita` command line tool requires no additional configuration.

Usage
-----

### Validating a document from the Command line

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

#### Creating an SVRL file

To create an SVRL file with this **extended** plug-in (where the results will include overriden rules) use the `overrides` transform. This transform is an override of the base SVRL file creation (`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.

```bash
rm -rf ./out
```

- SVRL file creation can be run like any other DITA-OT transform:

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

Once the command has run, an SVRL file is created

```xml

Line 15: section[id="bad"] - [comment-fixme]
Found 'FIXME' comments within the <section> element - fix as requested and delete the comment.
FIXME 61) This comment requires action

```

#### Echoing results to the command line

To echo results to the command line with this **extended** plug-in (where the results will include overriden rules) use the `overrides-echo` transform. This transform is an override of the base DITA document validation (`svrl-echo`) transform.

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

```bash
rm -rf ./out
```

- Extended Document validation (`overrides-echo`) can be run like any other DITA-OT transform:

```bash
PATH_TO_DITA_OT/bin/dita -f overrides-echo -i document.ditamap
```

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

```bash
[echo] [WARN] [/out/temp/dita/topics/comment-fixme.dita]
[echo] Line 15: section[id="bad"] - [comment-fixme]
[echo] Found 'FIXME' comments within the 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

```bash
[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
```

### Validating a document using Ant

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

```xml

... etc..

```

### Parameter Reference

- `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

Adding New Validator Rules
--------------------------

The file `dita2svrl.xsl` within the `com.here.validate.svrl.overrides` overrides the base-rule set, and uses its own Customizations:

```xml

```

If an `xsl:import` is commented out, this means that the base validator ruleset has not been customized. Most customization transforms are usually named after the DITA element they are run against.

Let us assume that we want to add a rule to validate `` elements: validation must fail if a `` has no `id` attribute.
To add the rule, you need to uncomment the line `` and in this case copy over the existing `section.xsl` file from the com.here.validate.svrl plugin.

This transform consists of two separate templates, the active-pattern template at the head of the file which fire style, structure and content rules-sets

```xml

```

and a series of rules fired from within that active-pattern :

```xml

section-title-missing
not(title)

```

To add an additional rule, add a new block containing a call to failed-assert as shown:
New Rule

```xml

section-id-missing
not(title)
id attribute is mandatory

```

The new rule must have a unique id and readable text.
When a validation rule is not satisfied, the Validator prints out an error message. Here is an example:

```bash
[echo] [xslt] [ERROR][map_tile/dev_guide/topics/example-basemap.dita:17]
[echo] [xslt] A {section} requires an 'id' attribute is mandatory
```

### Internationalization

To internationalize your error messages, remove the `human-text` parameter from the test above:

```xml

section-id-missing
not(title)

```

Now add the messages into language files found within the `cfg/common/vars` directory:

```xml

Das <@NAME> Element entspricht nicht dem DITA Dokumentationsstandard. Weitere Informationen finden Sie im Documentation Platform User Guide.
ID-Werte dürfen nicht das Wort 'content' enthalten. Ändern Sie den iD-Wert.
...etc

Geben Sie in <@NAME> Elementen immer einen ID-Wert an.

```

Ignoring Validator Rules
------------------------

#### Removing validator rules globally

This DITA-OT plug-in is an extension of the [base DITA validator](https://github.com/heremaps/com.here.validate.svrl) and includes an example within its XSL files to show how to remove rules globally. Please examine the code to see how to do this.

#### Ignoring a validator rule throughout a document

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:

```bash
/path-to-dita-ot/dita -f svrl-echo -i document.ditamap -Dargs.validate.ignore.rules=table-id-missing
```

#### Ignoring a specific instance of a validator rule

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.

```xml

```

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 addition rule (no FIXMEs allowed in the comments)

```xml

FIXME is usually banned in the running text.

```

Sample Document
---------------

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 `` of the sample document contain a set of test DITA ``, each demonstrating a broken validation rule.

The `` files are sorted as follows:

- The [base plug-in](https://github.com/heremaps/com.here.validate.svrl.overrides) \(`com.here.validate.svrl`\) – this `` contains a set of common validator rules from the base DITA validator applicable to all users. The rules are grouped thematically according to the name of the associated `` 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 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 spelling and grammatical errors.
- The [extended plug-in](https://github.com/heremaps/com.here.validate.svrl.overrides) \(`com.here.validate.svrl.overrides`\) – This `` 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 this plug-in is used.

Validator Error Messages
------------------------

The following tables list the validator error messages by type and message ID. Existing [Base DITA Validator](https://github.com/heremaps/com.here.validate.svrl) are in normal text. Rules in **bold** are only be detected if the `overrides` transform from the [Extended DITA Validator](https://github.com/heremaps/com.here.validate.svrl.overrides) is used.

### Content Validation

|Message ID|Message|Corrective Action/Comment|
|----------|-------|-------------------------|
|comment-fixme|Found 'FIXME' comments within the <\{name\}\> element - fix as requested and delete the comment.|Replace the draft content with the correct information.|
|comment-todo|Found 'TODO' within the following text of the <\{name\}\> element - fix as requested and delete the comment.|Replace the draft content with the correct information.|
|incorrect-spelling|The word '\{word\}' is a spelling mistake in the following text:|The indicated word is not spelled correctly. Fix the spelling. It is assumed that documentation follows US English spelling conventions. |
|incorrect-capitalization|The word '\{word\}' is incorrectly capitalized in the following text:|The indicated word is not capitalized correctly. Fix the capitalization.|
|running-text-fixme|Found 'FIXME' comments in the following text in this <\{name\}\> element - fix as requested and delete the comment.|Replace the draft content with the correct information.|
|running-text-lorem-ipsum|Found dummy text in this <\{name\}\> element, remove or replace with valid content.|Replace the standard lorem ipsum filler text with the correct information.|
|running-text-todo|Found 'TODO' comments in the following text in this <\{name\}\> element - fix as requested and delete the comment.|Replace the draft content with the correct information.|

### Style Validation

|Message ID|Message|Corrective Action/Comment|
|----------|-------|-------------------------|
|codeblock-outputclass-missing|Always provide an outputclass attribute in `` elements \(for example, add outputclass="language-javascript"\).|This `outputclass` attribute is used for decorating the HTML output to make code easier to read. If the content in the `` element is JSON use the key value pair `outputclass="language-javascript"`. For more information on the `` element, see [codeblock](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/codeblock.html).|
|codeblock-scale-missing|Always provide a scale attribute in `` elements \(for example, add `scale="80"`\).|This `scale` attribute reduces the size of the code text in the output to make it easier to read \(the values are percent\). We recommend you set the scale to 80 percent. For more information on the `` element, see [codeblock](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/codeblock.html).|
|conref-not-lower-case|The specification of `conref="..."` is invalid, allowed characters are: lower case, a-z only, words separated by hyphens.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the source file specified in the `conref` attribute references a file with an invalid name. For instance, if you define the `conref` attribute as follows `

` the file name does not comply with the file naming guidelines. - Only use lower case letters in a file name. - If a file name contains multiple words, use a hyphen to separate them, for example, `overview-map.dita` or `request-map-report.dita`. - The file type \(and file extension\) for all DITA XML files in the repository must be *.dita* or *.ditamap*. - Base the file name on the main topic title. If the title is `Naming Conventions` then the topic `id` should be `naming-conventions` and the file name should be `naming-conventions.dita`. - Do not include arbitrary strings to indicate the contents of the chapter, topic type, etc. - Do not include computer-generated text such as `topic-2` or `GUID-1234-5678-1234`. - Do not use non-standard acronyms, for instance, `border-xing` instead of `border-crossing`. |
|**element-blacklisted**|**The `` element is not compliant with our subset of DITA documentation standards.**|**Custom Rule**: While the DITA open standard supports a large number of elements, the extended validator only supports a subset of these elements in order to make the documents more consistent. Replace the rejected element with a supported element.|
|fig-id-invalid|`id` values must start with `'fig-'` in all `` elements.|In order to assist with search engine optimization \(SEO\) of content, all [figure](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/fig.html) elements must have an `id`.|
|fig-id-missing|Always provide an `id` value in `` elements.|In order to assist with search engine optimization \(SEO\) of content, all [figure](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/fig.html) elements must have an `id`.|
|file-not-lower-case|Found file `'...'` with invalid name, allowed characters in file names are: lowercase, a-z only, words separated by hyphens.|In order to assist with search engine optimization \(SEO\) of content, file names must be lower case. Fix the name as appropriate.|
|href-not-lower-case|The value provided in `href="..."` is invalid, allowed characters are: lowercase, a-z only, words separated by hyphens.|The file specified in the `href` attribute does not comply with the file naming conventions. Fix the name as appropriate.|
|**id-blacklisted**|**`id` attribute values must not use the word `'content'`. Change the `id` value.**| **Custom Rule**: Some delivery channels used to deliver content to customers may be configured to already use certain `id` values. Change the word content to another `id`. For more information on `id` attributes, see [id](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/id.html).|
|id-not-lower-case|The id value in `id="..."` is invalid, allowed characters are: lowercase, a-z only, words separated by hyphens.|In order to assist with search engine optimization \(SEO\) of content, `id` attributes must comply with the `id` conventions. Fix the name as appropriate. - Only use lower case letters in a file name. - If a file name contains multiple words, use a hyphen to separate them, for example, `overview-map.dita` or `request-map-report.dita`. - The file type \(and file extension\) for all DITA XML files in the repository must be *.dita* or *.ditamap*. - Base the file name on the main topic title. If the title is `Naming Conventions` then the topic id should be `naming-conventions` and the file name should be `naming-conventions.dita`. - Do not include arbitrary strings to indicate the contents of the chapter, topic type, etc. - Do not include computer-generated text such as `topic-2` or `GUID-1234-5678-1234`. For more information on `id` atrributes, see [id](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/id.html).|
|image-file-type-not-supported|The value provided in `href="..."` specifies an unsupported file format \(only \*.jpg, \*.jpeg or \*.png are allowed\). Change the format of the linked file.|The validator ensures that only \*.jpg, \*.jpeg or \*.png format files are used in online HTML documents. Convert the image format to the correct format.|
|section-id-missing|Always provide an `id` attribute in `` elements.|In order to assist with search engine optimization \(SEO\), all [section](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/section.html) elements must have an `id`.||table-id-invalid|`id` values must start with 'table-' in `` elements.|If you add an `id` to a table, start the `id` with the word 'table-'. For more information on tables, see [table](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/table.html).|
|table-id-missing|Always provide an `id` attribute in `` elements.|In order to assist with search engine optimization \(SEO\), add an `id` to `` elements. For more information on tables, see [table](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/table.html).|
|topic-file-mismatch|The value specified in id="\{name\}" does not match the file name: \{file\_name\}. Make sure the `id` value and the file name are the same.|In order to assist with search engine optimization \(SEO\) of content, the `id` for `` elements must be the same as the file name, which also ends up by the name of the HTML file. For more information on topics, see [topic](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topic.html). For more information on element 'id`s', see [id](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/id.html).|
|xref-no-format|Always provide a format attribute in `` elements, \(for example, format="dita" or format="html"\).|Specify a value for the `format` attribute for `` elements. Examples of valid values include `dita`, `html`, and `pdf`. For more information on `` elements, see [xref](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/xref.html).|

### Structure Validation

|Message ID|Message|Corrective Action/Comment|
|----------|-------|-------------------------|
|chapter-href-missing|Always provide an href attribute in `` elements.|When you add a `` element to a `ditamap`, you must specify a `href="{file_name}"` key/value pair that defines the content that appears on the chapter page in the PDF \(and on the chapter landing page in HTML\). Alternatively, you can define the following two attributes: `navtitle="..." lockitle="yes"`. This approach has the effect of adding a title but not content on the chapter page/node. For more information on the `` element, see [chapter](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/chapter.html).|
|coderef-href-ref-file-not-found|The linked source file does not exist. Check the related folder for the missing file and make sure the file name is correct.|The `` element is generally used for importing a source file when the validator builds the document. When you get this error, the reference cannot be resolved. Note that DITA does not allow you to reference files outside the root folder of the document. By default, these files should be in the `source` folder under the document root folder. For more information on the `` element, see [codeblock](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/codeblock.html).|
|colspec-colnum-not-unique|The key/value pair `colnum="..."` is not unique. Make sure there are no duplicates.|In order for the validator to render table content properly, these key/value pairs must be unique. For instance, the following codeblock illustrates well-formated DITA that complies with this requirement. `` For more information on the `` element, see [table](http://docs.oasis-open.org/dita/v1.2/os/spec/langref/table.html).|
|conref-external-file-not-found|The linked file does not exist. Check the related folder for the missing file and make sure the file name is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced file cannot be resolved. Note that DITA does not allow you to reference files outside the root folder of the document. By default, this kind of content should be in the `includes.dita` file. |
|conref-external-id-mismatch|The conref source `<{name}>` and the destination `<{name}>` are not the same type. Check to make sure the referenced elements are the same.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced `id` in the source file specified in the `conref` attribute is an `id` for an element that is of a different type than the element with the `conref` attribute. DITA requires that `conref` attributes point at the same kind of element. For instance, `

` needs to reference an element in the `includes.dita` file that is formatted as follows `

CONTENT

`. |
|conref-external-id-not-found|The referenced `id` does not exist in the source file. Make sure the id value specified is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced `id` in the source file specified in the `conref` attribute cannot be resolved. For instance, if you define the `conref` attribute as follows `

` and you get this error, then the `includes.dita` file does not have a `

` whose `id` is set to `id="submission-note"`. |
|conref-external-path-not-found|The referenced path does not exist. Make sure the path is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the source file specified in the `conref` attribute cannot be resolved. For instance, if you define the `conref` attribute as follows `

` and you get this error, then the validator cannot find the `includes.dita` file. Note that DITA does not allow you to reference files outside the root folder of the document. |
|conref-external-path-mismatch|The conref source <\{name\}\> and the destination <\{name\}\> are not the same type. Make sure the path is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced `id` in the source file specified in the `conref` attribute is an `id` for an element that is of a different type than the element with the `conref` attribute. DITA requires that `conref` attributes point at the same kind of element. For instance, `

` needs to reference an element in the `includes.dita` file that is formatted as follows `

CONTENT

`. |
|conref-internal-id-not-found|The referenced `id` does not exist in this file. Make sure the `id` value specified is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced `id` specified in the `conref` attribute cannot be resolved. For instance, if you define the `conref` attribute as follows `

` and you get this error, then the source file does not have a `

` whose `id` is set to `id="submission-note"`. |
|conref-internal-path-mismatch|The conref source <\{name\}\> and the destination <\{name\}\> are not the same type. Make sure the path is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the referenced `id` specified in the `conref` attribute is an ID for an element that is of a different type than the element with the `conref` attribute. DITA requires that `conref` attributes point at the same kind of element. For instance, `

` needs to reference an element that is formatted as follows `

CONTENT

`. |
|conref-internal-path-not-found|The referenced path does not exist in this file. Make sure the path is correct.| The `conref` attribute is used for importing documentation segements reused across the document when the validator builds the document. For more information on using the `conref` attribute, see [conref](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html). When you get this error, the value specified in the `conref` attribute cannot be resolved. For instance, if you define the `conref` attribute as follows `

` and you get this error, then the validator cannot resolve the path. |
|href-file-not-found|The file specified in `href="..."` does not exist. Check the related folder for the missing file and make sure the file name is correct.|The validator cannot find the file specified in the `href` attribute. Make sure the file is in the indicated path. Note that DITA does not allow you to reference files outside the root folder of the document.|
|id-not-unique|Found a duplicate 'id' with value '\{name\}', `id` values must be unique within a file. Change the `id` value.|DITA requires that all `id`s within a file must be unique. Change the `id` value. For more information on `id` attributes, see [id](http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/id.html).|
|image-href-ref-file-not-found|The linked image file does not exist. Check the graphics folder for the missing file and make sure the link and file name specified are correct.|The validator cannot find the file specified in the `href` attribute. Check the path to ensure the file is there.|
|**image-product-filtered-not-included**|**Found ``. This results in an empty `` for other variants. Add additional `product` attributes for the missing ditaval filters.**|**Custom Rule**: When skinning a document for various customers it is necessary to filter the images used. By placing all images in a single conref'd file it is easier to ensure that all images will be present for all customers. see [ditavals](http://docs.oasis-open.org/dita/v1.2/os/spec/common/about-ditaval.html).|
|list-all-li-filtered|Found only `

` elements in `