Sharing Schematron Validation Rules

Custom Schematron rules are a great way to ensure consistency for the edited XML structure, especially when there is a large team working on the same set of documents. You can use Schematron for numerous use cases. For example, to make sure that certain elements are not used at all, to impose restrictions on the amount of text for an element, or to impose restrictions on certain elements based on various attribute values or text content set in other elements. Furthermore, you can define quick fixes for each Schematron rule to give the technical writer proposed solutions for the reported problem. In a previous blog post, I described how we use Schematron rules for our Oxygen User's Manual to impose restrictions when editing DITA content: Schematron Checks to help Technical Writing.

Once you define the Schematron rules, they can be shared with the other members of your team via a document type framework configuration: The Oxygen SDK (Part 2: Frameworks).

In this post, I'm going to provide some precise steps to share a set of Schematron rules with a DITA framework extension.

Instead of making changes directly to the DITA framework configuration folder (located in OXYGEN_INSTALL_DIR\frameworks\dita) and distributing it, you can choose to extend the DITA framework and distribute the extension. This way, you will benefit from new functionality added to the base framework in newer versions of Oxygen and you can still use your customizations.

The following steps describe how you can extend a DITA framework that contains an additional Schematron rules file:

1. Create a folder structure (for example, custom_frameworks/dita-extension) somewhere on your local disk, in a place where you have full write access.
2. In that new folder structure, create another folder (custom_frameworks/dita-extension/rules) that will contain all of your custom Schematron files.
3. Create a new ISO Schematron file (for example, additionalRules.sch) that contains the additional rules you want to impose. For example, the following Schematron rule reports an error if the @scale attribute is used on an image:

   <schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"
       xmlns:sqf="http://www.schematron-quickfix.com/validator/process">
       <pattern>
           <rule context="*[contains(@class, ' topic/image ')]">
               <assert test="not(@scale)">
                   Dynamically scaled images are not properly displayed, you
                   should scale the image with an image tool and keep it within
                   the recommended width and height limits.
               </assert>
           </rule>
       </pattern>
   </schema>

4. In the Document Type Association / Locations preferences page, add the path to your custom_frameworks folder in the Additional frameworks directories list. Click OK or Apply in the Preferences dialog to save your changes.
5. In the Document Type Association preferences page, select the DITA document type configuration and use the Extend button to create an extension for it.
6. Give the extension a custom name (for example, DITA - Custom), then change its Storage option to External, and then save it to a path such as: path/to/.../custom_frameworks/dita-extension/dita-extension.framework.
7. Make whatever changes you desire to the extension, go to the Validation tab, edit the default DITA validation scenario, and add an extra validation stage to it (a stage that uses your custom Schematron schema). More details about validation scenarios can be found here: https://www.oxygenxml.com/doc/ug-editor/topics/dg-validation-scenarios.html.
8. Click OK to close the dialog box and then either OK or Apply to save the preferences changes.

After you perform the steps above, in the dita-extension folder you will have a fully functioning framework extension that can be shared with others.

There are several methods for sharing the framework and you can read about them here: https://www.oxygenxml.com/doc/ug-editor/topics/author-document-type-extension-sharing.html.

After your team members install the framework, they can check the Document Type Association preferences page to make sure the framework is present in the list of Document Types and that it appears before the bundled DITA framework (meaning that it has higher priority).

You can use the framework extension mechanism to customize numerous aspects of the DITA functionality in Oxygen. For example, you can remove various elements from the content completion list: Document Type Extension Sharing. Or you can distribute custom new file templates: Sharing New Custom File Templates for a Specific Vocabulary.