Schematron Configuration Guide

Leverage Schematron validation to enforce your style guide rules.

Schematron validation is similar to XML validation, but the rules that are applied and validated are unique to your organization's content development needs.

Note: Contact your easyDITA representative to customize the default configuration or upgrade your subscription to include customization.

Schematron Overview

Schematron enables you to enforce content production rules that your authoring team needs to follow.

Schematron applies individual tests on different patterns of your DITA content. Given the rules you want to enforce, either your content passes or fails the tests. If your content fails a test, easyDITA alerts you about the problem and informs you how to resolve the issue.

Schematron Rules Structure

Schematron is based on the XPath language.

Structure Example

<pattern name="[NAME]">
	<rule context="[CONTAINS()]">
		<report test="">DON'T DO THAT!</report>
	</rule>
</pattern>
                                                            

The phrase “DON'T DO THAT!” is a plain text warning that easyDITA shows in a pop-up when you break a particular rule. For examples on how to define rules, see Schematron Rules Examples.

Elements and Attributes

Schematron rules use operators, functions, and syntax from the XPath language. For detailed information, see XPath.

Table 1. Schematron Elements and Attributes

easyDITA applies predefined schemas and runs tests that consist of the following elements and attributes.

Element or Attribute	Role	Description
<pattern>	Functions as the grouping mechanism for similar Schematron rules, such as grammar rules	Contains one or more Schematron <rule> elements
<rule>	Defines a context in which to apply a test on the content	Contains a @context attribute that is unique for each <rule> element
@context	Defines the location in the content for the application of the Schematron rule	The description of the unique location in the content to be searched and to have the rule applied
<report>	Defines the actual test or rule to apply to the content	The actual rule or test that applies what's defined in the @test attribute
@test	Defines the condition to test in the content in relation to the location to test, defined in the @context attribute	Description of the condition that the content either satisfies or fails to satisfy

Schematron Rules Guidelines

Keep these guidelines in mind when creating Schematron rules.

Tip: If you are new to writing Schematron rules or don't know the XPath language, we recommend modifying the provided rules examples. See Schematron Rules Examples.

• The simpler the rules, the more reliable they are
• Each rule must have a defined context, be a child of a <pattern> element, and must have a <report> element that states the specific test to apply to your content
• Since you cannot test your custom rules in advance, your easyDITA representative can work with you to test the rules and make any necessary adjustments

Schematron Rules Examples

You can use and modify the following examples to build your own Schematron rules.

Tip: Contact your easyDITA representative if you have any questions about writing your organization's easyDITA rules.

Example A

The following example demonstrates a rule that checks content in paragraph elements.

<pattern name="Grammar Rules">
        <rule context="text()[count(ancestor::p) &gt; 0]">
            <report test="contains(., '; ')">Don't use semicolons; you don't know how. They also
                don't localize well.</report>
            <report test="contains(., '#8212')">Use a hyphen instead of an en dash.</report>
            <report test="contains(., 'displays')">Use "shows", "appears", or a variant of one of
                them.</report>
            <report test="contains(., 'displayed')">Use "shows", "appears", or a variant of one of
                them.</report>
            <report test="contains(., 'display')">Use "shows", "appears", or a variant of one of
                them.</report>
        </rule>
    </pattern>
                                                            

The rules in the example are specifically checking content contained in paragraph elements by using the XPath syntax.

.

The abbreviated syntax for the self node, telling the system to test the content of the element called out in the @context.

count

Defines the set of DITA structures to check for rule violations.

ancestor

An XPath axis specifier that requires a value and which tells the system which direction, “up” or “down” the element structure, to check for the presence of the value listed.

The rule context defines the location to apply the rule. Specifically, the context is saying to check the paragraph elements. Additionally, the > 0 restricts the context to only paragraph elements that have content. In other words, this phrase tells the test to ignore placeholder paragraph elements.

Example B

The following example demonstrates a rule that checks if a particular width attribute value is applied to image elements.

<pattern name="Image Rules">
	<rule context="image">
		<report test="string(@width) = ''">Please apply a value to the width attribute.</report>
	</rule>
</pattern>
                                                            

The rule runs the test on the image elements, checking for the existence of an @width attribute in the DITA markup. The two single quotes with no value cause the easyDITA violation to show only if there is no attribute applied to an image element. Any value entered for the image element width attribute would satisfy the easyDITA rule.

Tip: If necessary, you can write more complex rules that trigger a violation if a specific value isn't applied. Writing more complex rules requires knowledge of the XPath syntax, functions, and their relations to one another.

Example C

The following example demonstrates a rule that shows a pop-up if you enter “1” instead of “one”.

<pattern name="Numbers">
        <rule context="text()[count(ancestor::mathml) = 0][count(ancestor::table) = 0]">
            <report test="starts-with(., '1 ') or contains(., ' 1 ') or substring(., string-length(.) - 1) = ' 1'">Use "one" instead</report>
	</rule>
</pattern>