Schematron Rules Development Guidelines

Keep the following guidelines in mind when developing Schematron rules.

Performance Guidelines

  • Be as specific as possible when you define tests and contexts for your rules
    <!-- Prerequisites, Postrequisites, Step Example, Step Result, Example, Result, and Context elements should not contain introductory text. The text is generated automatically (Specific to: jorsek_pdf, color_pdf, gray_pdf publishing scenarios) -->
    <pattern id="JORSEK_STRUCTURE_10">        
        <rule context="prereq/p[1]">
            <report test="matches(., '^[Bb]before\s*you\s*[Bb]egin')">Remove the introductory text. The
                text is generated automatically.</report>
            <report test="matches(., '^[Bb]efore\s*you\s*[Ss]tart')">Remove the introductory text. The
                text is generated automatically.</report>
            <report test="matches(., '^[Pp]rerequisites')">Remove the introductory text. The text is
                generated automatically.</report>
        </rule>
    
        <!-- ... -->
    
        <rule context="context/p[1]">
            <report test="matches(., '^[Cc]ontext')">Remove the introductory text. The text is
                generated automatically.</report>
        </rule>
    </pattern>
  • If you decide to develop a rule that validates the language layer of your content, specify the regular expression matches in the rule context rather than in the report or assert test
    <!-- Replace "display" with "show" or "appear". -->
    <pattern id="JORSEK_STYLE_07">
        <rule context="text()[matches(.,'[Dd]isplay(s|ing)?\W')]">
            <report test=".">Replace "display" with "show" or "appear". </report>
        </rule>
    </pattern>
  • If you need to implement a significant number of rules (50 or more) that validate the language layer of your content, consider integrating your easyDITA instance with a dedicated language-validation tool (for example, HyperSTE)

Stylistic Guidelines

  • Be consistent with your assert or report warnings
    <!-- Each topic root element should have an @xml:lang attribute assigned -->
    <pattern id="JORSEK_STRUCTURE_02">
        <rule context="concept|task|reference|topic|troubleshooting">
            <assert test="@xml:lang">Each root topic element should have an @xml:lang attribute
                assigned.</assert>
        </rule>
    </pattern>
    
    <!-- Each topic should contain a Short Description element -->
    <pattern id="JORSEK_STRUCTURE_03">
        <rule context="concept|task|reference|topic|troubleshooting">
            <assert test="shortdesc|abstract/shortdesc">Each topic should contain a Short
                Description element.</assert>
        </rule>
    </pattern>
    
  • For rules that validate the language layer of your content, ensure to mention the word or phrase that needs to be replaced in a specific node
    <!-- Replace "desire" with "want" -->
    <pattern id="JORSEK_STYLE_19">
        <rule context="text()[matches(.,'[Dd]esire(s)?\W')]">
            <report test=".">Replace "desire" with "want".</report>
        </rule>
    </pattern>
  • Categorize your rules and apply consistent ID values to patterns

    For example, you can use the following categories or come up with your own:

    • Structure
    • Style
    • Grammar
    • Branding
    • Length
    • Numbers

Implementation Guidelines

  • Develop a map with topics that provide tests to trigger each rule
  • Thoroughly test your rules before implementing them into your production instance
  • To maintain a version history of your SCH file with Schematron rules, store the file in a source control repository