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.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.
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.
- 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.
Example A
The following example demonstrates a rule that checks content in paragraph elements.
<pattern name="Grammar Rules">
<rule context="text()[count(ancestor::p) > 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 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>
@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.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>
There was a problem loading this topic