-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.dita
150 lines (150 loc) · 10.7 KB
/
README.dita
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="step_by_step_guide_to_developing_schematron_rules">
<title>Step-By-Step Guide to Developing Schematron Rules</title>
<body>
<p>Octavian Nadolu, Syncro Soft</p>
<object data="https://www.youtube.com/watch?v=w4jtBsSIiyw" outputclass="video"/>
<p>Schematron is a very simple and powerful language. It is used in various domains
(financial, insurance, government, and technical publishing sectors) for quality
assurance, validating business rules, constraint checking, or data reporting. During the
presentation, I will show you how to create Schematron rules step-by-step, apply the
rules over one or multiple documents, and also how to integrate Schematron rules in your
development process.</p>
<p>Schematron is a rule-based validation language for making assertions about presence or
absence of certain patterns in XML documents. With Schematron, you can express
constraints in a way that you cannot perform with other schemas (like XSD, RNG, or DTD).
XSD, RNG, and DTD schemas define structural aspects and data types of the XML documents
and can be used to check big things, such as if an element is allowed in a specific
context, or if an attribute is allowed for an element. But with Schematron, you can
create your custom rules specific to your project, and check things such as if the text
from an element respects a particular constraint, or verify data inter-dependencies such
as if a start date from an attribute value is set before the end date attribute
value.</p>
<p>In a Schematron document, you can add a collection of rules that contain tests. The
Schematron content is written as an XML document using a small number of elements, and
this makes it easy to understand and write, even for people that are not
programmers.</p>
<p>When a document is validated with a Schematron schema, for each rule from the schema, the
following steps are performed:</p>
<ul>
<li>First, it is determined the context on which the rule is applied. That can be an
element, or an attribute, or maybe a text fragment. The context is expressed using
an XPath expression.</li>
<li>Next, it checks if the assertions from the rule are evaluated to true or false.
Depending on the evaluation result, the assertion message is displayed. The
assertions are also expressed using XPath expressions that are evaluated to
<i>true</i> or <i>false</i>.</li>
</ul>
</body>
<topic id="schematron_structure">
<title>Schematron Structure</title>
<body>
<p>Basically, the most important components of a Schematron schema are the tests. The
tests are defined in the <b>assert</b> and <b>report</b> elements. An <b>assert</b>
generates a message when a test statement evaluates to <b>false</b>. A <b>report</b>
generates a message when a test statement evaluate to <b>true</b>. The generated
messages are defined in the <b>assert</b> and <b>report</b> elements. Actually, the
Schematron developer writes his own messages, making them understandable to anyone
who needs to see the messages.</p>
<p><i>Example 1: An assert that tests if the price is greater that 10</i></p>
<codeblock xml:space="preserve"> <assert test="@price > 10">The price is too small</assert></codeblock>
<p>Tests that are executed in the same context can be grouped in a <b>rule</b> element.
A <b>rule</b> defines a context on which a list of assertions will be tested, and is
comprised of one or more <b>assert</b> or <b>report</b> elements.</p>
<p><i>Example 2: A set of tests for the book element</i></p>
<codeblock xml:space="preserve"><rule context="book">
<assert test="@price > 10">The price is too small</assert>
<assert test="@isbn">The book ISBN is missing</assert>
</rule></codeblock>
<p>A set of rules that are related in some way can be grouped in a <b>pattern</b>
element. The <b>pattern</b> elements are added in a <b>schema</b> element, that is
the top-level element of a Schematron schema <b>.</b></p>
<p><i>Example 3: A sample ISO Schematron schema</i></p>
<codeblock xml:space="preserve"><schema xmlns="http://purl.oclc.org/dsdl/schematron">
<pattern>
<rule context="book">
<assert test="@price > 10">The price is too small</assert>
<assert test="@isbn">The book isbn is missing</assert>
</rule>
</pattern>
</schema></codeblock>
<p>The Schematron is saved in a file that has the suffix ".sch". Also the prefix for the
Schematron elements is by convention "sch:".</p>
</body>
</topic>
<topic id="validate_with_schematron_schema">
<title>Validate with Schematron Schema</title>
<body>
<p>A Schematron schema can be associated with an XML document using an <b>xml-model</b>
processing instruction. You can also use tool-specific association options like:
associate a set al XML files that have a specific namespace with a Schematron, or
associate all XML files from a project or from a directory.</p>
<p>To validate an XML file with a Schematron schema, you can use an editing framework
that will allow you to run the validation on the currently edited XML file and will
present the problems directly in the editor. You can also run the validation over
multiple XML files and check all the reported problems from a user interface.
Another solution is to use Apache Ant, and run the validation from a bat/shell
script. You can also use pipelining languages, like W3C&#39;s XProc.</p>
<p>The result of the validation can be presented in the editor in case you are using an
editing framework, and you will have the content that does not satisfy the
assertions highlighted and the messages displayed in the user interface. In case you
are using bat/shell script, you can get the validation errors in an XML file,
normally the format of the XML file is a Schematron Validation Reporting Language
(SVRL).</p>
<p>Schematron assertion messages can be presented in different languages. The Schematron
developer can create a message for each language using the diagnostics elements. For
each translated message, a diagnostic element need to be created and referenced from
the assert or report element. Depending on the application language or on the
Schematron file language, a message in a specific language can be presented to the
user.</p>
</body>
</topic>
<topic id="schematron_quick_fixes">
<title>Schematron Quick Fixes</title>
<body>
<p>Schematron allows the schema author to define and control the messages that are
presented to the user. The messages can also include hints to the user on how to
solve the problem, but they will need to manually correct the issue. This wastes
valuable time since the user needs to correct the problem manually and additional
errors can be created when they fix the reported problem. An action that will
automatically correct the reported problem for Schematron validation errors will
bridge this gap, saving time and avoiding the potential for causing other
issues.</p>
<p>Schematron Quick Fix (SQF) it is a simple language that allows the Schematron
developer to define actions that will correct the reported problems. SQF was created
as an extension of the Schematron language. It was developed within the W3C
community group "Quick-Fix Support for XML Community Group". First draft of the
Schematron Quick Fix specification was published in April 2015, second draft in
March 2018, and it is now available on the <xref
href="https://www.w3.org/community/quickfix/" format="html" scope="external">W3C
Quick-Fix Support for XML community group</xref> page.</p>
<p><i>Example 4: A Schematron Quick Fix that removes a bold element keeping its text
content</i></p>
<codeblock xml:space="preserve"><sch:rule context="title">
<sch:report test="b" sqf:fix="resolveBold">Bold element is not allowed in title.</sch:report>

<sqf:fix id="resolveBold">
<sqf:description>
<sqf:title>Change the bold element into text</sqf:title>
</sqf:description>
<sqf:replace match="b" select="node()"/>
</sqf:fix>
</sch:rule></codeblock>
<p>An SQF fix consists of a set of operations that can be performed on an XML document.
These are basic operations (add, delete, replace, and string replace) that need to
make precise changes in the document. This means that when a fix is applied, only
the affected part of the XML document should be changed and the DOCTYPE declaration,
entities, etc. must be preserved.</p>
<p>Conclusion</p>
<p>It is important to have a quality control over the XML documents from your project.
To achieve this you can use Schematron schema in combination with an XSD, RNG, or
DTD schema. Schematron solves the limitation that other types of schema have when
validating XML documents because it allows the schema author to define the tests and
control the messages that are presented to the user. The validation problems are
more accessible to users and it ensures that they understand the problem.</p>
<p>Contact: octavian_<xref href="mailto:nadolu@oxygenxml.com" format="com"
scope="external"/></p>
</body>
</topic>
</topic>