Starting with Schematron

[ann.jensen]

Hi,
I want to start using Schematron to define and enforce my documentation business rules on my Dita content but have no experience with it.
Can you advise what support Oxygen Author provides to help me to create the Schematron files and how I apply them to my Dita files?
Any advice appreciated,
Regards,
Ann

[Radu]

Hi Ann,

We do not have a Schematron tutorial but if you know XSLT and XPath Schematron is quite easy to learn. I found a tutorial which looks decent enough here:

https://www.xml.com/pub/a/2003/11/12/schematron.html

You should focus on the ISO Schematron part because Schematron 1.5 is deprecated and not really used anymore.

Back to DITA, if you open the Schematron file:

OXYGEN_INSTALL_DIR\frameworks\dita\resources\dita-1.2-for-xslt2-mandatory.sch

it contains a bunch of patterns and rules which are applied by default and used to validate any DITA topic opened in Oxygen.
You can add your own rules to it. For example here is a blog post about some of the rules we use for our user's manual:

http://blog.oxygenxml.com/2015/05/schem ... nical.html

And here is the entire Schematron file that we use to validate our user guide's DITA content:

https://github.com/oxygenxml/userguide/ ... vanced.sch

If you want to create your own Schematron files, use them for DITA editing and maybe share your customization with others in your team the proper way would be this one:

http://blog.oxygenxml.com/2017/02/shari ... rules.html

Regards,
Radu

[ann.jensen]

Hi Radu,
Thank you for your detailed reply.
I have been looking at the Schematron file OXYGEN_INSTALL_DIR\frameworks\dita\resources\dita-1.2-for-xslt2-mandatory.sch but don't understand how this is configured to be applied to my DITA project code e.g. I added 2 Title elements to one of my dita files, and then ran a validation but the only error I see is:

Code: Select all

System ID: C:\DevBranches\DocService_devel\AGS_Documentation\system_documentation\dita_files\AGSSystems\Aspen_iProperty\dashboard\c_dashboard_mod.dita

Main validation file: C:\DevBranches\DocService_devel\AGS_Documentation\system_documentation\dita_files\AGSSystems\Aspen_iProperty\dashboard\c_dashboard_mod.dita

Scenario name: DITA

Schema: C:\Program Files\Oxygen XML Author 19_1\frameworks\dita\DITA-OT2.x\plugins\org.oasis-open.dita.v1_3\dtd\technicalContent\dtd\concept.dtd

Document type: DITA - Extension

Engine name: Xerces

Severity: error

Description: Unexpected element "title". The content of the parent element type must match "(title,titlealts?,(abstract|shortdesc)?,prolog?,conbody?,related-links?,concept*)".

Start location: 5:3

End location: 5:8

which I believe is from the DITA-OT and not from dita-1.2-for-xslt2-mandatory.sch.

Can you advise where dita-1.2-for-xslt2-mandatory.sch is configued to be applied to my DITA project content and what triggers its application?
Thanks in advance,
Ann

[ann.jensen]

I see now that the Schematron pattern I was trying to test is only for <Section> elements not for topics
I have added 2 <title> elements to a <section> and see the pattern from dita-1.2-for-xslt2-mandatory.sch applied.
Ann

[Radu]

Hi Ann,

Exactly. So how this works:
In the Oxygen Preferences->Document Type Associations page you have a "DITA" document type association. If you choose to edit it (or to duplicate it if you are not allowed to edit it), in the "Documen Type" dialog there is a Validation tab which has a default validation scenario. A validation scenario has multiple stages, for example for DITA one stage is the default DTD or schema based validation, the second stage is a DITA specific validation we implemented and the other stages are Schematron-based, some of those stages being applied only for manual validation (using the toolbar Validate button).
So while you modify a DITA document, all these separate validation stages are applied, one of them using that particular Schematron to validate the entire DITA content.
The proper way to do this would be to add a separate Schematron file for validation instead of modifying our own and this blog post shows the steps to have your own DITA framework extension with your custom Schematron file used for validation in addition to ours:

http://blog.oxygenxml.com/2017/02/shari ... rules.html

Regards,
Radu

[ann.jensen]

Hi Radu,
I had tried to follow the instructions in http://blog.oxygenxml.com/2017/02/shari ... rules.html earler but was having problems with step 6. I get the following error on saving the custom framework

The "custom-franework.framework" file must be saved in a subdirectory of one of the configured frameworks directories from "Document Type Association/Locations" preferences page.

.
I have followed all the previous steps. The path is in the Additional frameworks directories.
It is a path to a location on my machine that has full write access i.e. C:\Users\ajensen\Oxygen\custom_frameworks\dita-extension
Any advice appreciated,
Regards,
Ann

[Radu]

Hi Ann,

After step (4), please click OK in the "Preferences" dialog to save your changes, then show it again to proceed to the next steps.

Regards,
Radu

[ann.jensen]

Hi Radu,
I have tried that many times but it makes no difference.
Is it because my Oxygen is installed in a path that does not have full write access?
Regards,
Ann

[Radu]

Hi Ann,

In the Oxygen Preferences->"Document Type Association / Locations" page in the "Additional frameworks directories" list you must have this entry:

C:\Users\ajensen\Oxygen\custom_frameworks\

So you should refer in there to your custom frameworks folder and not directly to the "dita-extensions" framework folder.

Regards,
Radu

[ann.jensen]

Bingo
So as you said In "Oxygen Preferences->Document Type Association / Locations" page in the "Additional frameworks directories" list I have the entry

C:\Users\ajensen\Oxygen\custom_frameworks

and in the extended DITA Document Type Association, Storage is set to External and the path is

C:\Users\ajensen\Oxygen\custom_frameworks\dita-extension\dita-extension.framework

I then updated the Validation scenario and added some rules to the new

C:\Users\ajensen\OneDrive for Business 1\Documents\Aspen Docs\BAU\Product Documenation Project\Oxygen\custom_frameworks\dita-extension\rules\additionalRules.sch

which are being applied automatically in Author.
Thanks for your support,
Regards,
Ann

[ann.jensen]

I thought I could manage a few basic Shematron rules based on yours but cannot manage to enforce the format attribute on topicref elements within maps as follows

Code: Select all

<pattern id="format_attribute_on_topicref">

       <rule context="*[contains(@class,' map/topicref ')]">

            <report test="@format" role="error">Missing format attribute

			</report>            

        </rule>

	</pattern>

Any advice appreciated,
Regards,
Ann

[Radu]

Hi Ann,

That's because the "DITA" framework that you extended and customized is used only when editing "DITA" topics.
There is also a "DITA Map" framework configuration in the "Preferences->Documen Type Associations" page which can be extended and customized just like you did for the "DITA" framework configuration.

Regards,
Radu

[ann.jensen]

Hi,
I am writing some Schematron rules for my custom framework but am getting some strange behaviour with one of them.

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<schema xmlns="http://purl.oclc.org/dsdl/schematron" 

    queryBinding="xslt2" xmlns:sqf="http://www.schematron-quickfix.com/validator/process" 

    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <title>Schematron schema for DITA 1.2</title><p>Version 3.0.0 released 2010-10-17.</p>

    <ns uri="http://dita.oasis-open.org/architecture/2005/" prefix="ditaarch"/>

    <pattern><rule context="/*"><assert test="prolog/metadata/keywords/indexterm" role="warn" sqf:fix="addIndexTerm">

        It is recommended to add an 'indexterm' in the current'<name/>' element.</assert>

        <sqf:fix id="addIndexTerm">

            <sqf:description><sqf:title>Add the 'indexterm' element</sqf:title></sqf:description>

            <sqf:add match="(title | titlealts | abstract | shortdesc)[last()]" position="after" use-when="not(prolog)">

                <prolog><metadata><keywords><indexterm></indexterm></keywords></metadata></prolog></sqf:add></sqf:fix>

    </rule></pattern>

</schema>

When I apply the quickfix from the above rule it adds the following code

Code: Select all

<prolog xmlns="http://purl.oclc.org/dsdl/schematron"><metadata><keywords><indexterm/></keywords></metadata></prolog>

I don't understand why it is inserting

Code: Select all

 xmlns="http://purl.oclc.org/dsdl/schematron"

Any advice appreciated,
Regards,
Ann

[tavy]

Hi Ann,

This happens because the elements that you are inserting using the quick fix are from the Schematron namespace. The Schematron namespace is defined on the schema root as the default namespace for your document (xmlns="http://purl.oclc.org/dsdl/schematron"), and because you did not specify a prefix for the inserted elements they will be from Schematron namespace.
To solve this issue you can set a prefix for the Schematron elements and leave the inserted elements with no prefix. For example you can set the "sch" namespace for all Schematron elements:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<sch:schema xmlns:sch="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2"

    xmlns:sqf="http://www.schematron-quickfix.com/validator/process"

    xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

    <sch:title>Schematron schema for DITA 1.2</sch:title>

    <sch:p>Version 3.0.0 released 2010-10-17.</sch:p>

    <sch:ns uri="http://dita.oasis-open.org/architecture/2005/" prefix="ditaarch"/>

    <sch:pattern>

        <sch:rule context="/*">

            <sch:assert test="prolog/metadata/keywords/indexterm" role="warn" sqf:fix="addIndexTerm"

                > It is recommended to add an 'indexterm' in the current'<sch:name/>'

                element.</sch:assert>

            <sqf:fix id="addIndexTerm">

                <sqf:description>

                    <sqf:title>Add the 'indexterm' element</sqf:title>

                </sqf:description>

                <sqf:add match="(title | titlealts | abstract | shortdesc)[last()]" position="after"

                    use-when="not(prolog)">

                    <prolog><metadata><keywords><indexterm/></keywords></metadata></prolog>

                </sqf:add>

            </sqf:fix>

        </sch:rule>

    </sch:pattern>

</sch:schema>

Best Regards,
Octavian