-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathtutorial-20030326.html
1754 lines (1677 loc) · 96.9 KB
/
tutorial-20030326.html
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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>RELAX NG Tutorial</title><link rel="stylesheet" href="tr.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.60.1"><meta name="description" content="RELAX NG is a simple schema language for XML, based on and . A RELAX NG schema
specifies a pattern for the structure and content of an XML
document. A RELAX NG schema thus identifies a class of XML documents
consisting of those documents that match the pattern. Two syntaxes have been defined for RELAX NG. The original
syntax uses XML; with this syntax an RELAX NG schema is itself an XML
document. Subsequently, a compact non-XML syntax has been
defined. This document is a tutorial for RELAX NG version 1.0 using the
XML
syntax."><meta http-equiv="content-style-type" content="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><p class="logo"><a href="http://www.oasis-open.org/"><img src="oasis.png" alt="OASIS" border="0"></a></p><div><h1 class="title"><a name="id2811955"></a>RELAX NG Tutorial</h1></div><div><h2>Working Draft 26 March 2003</h2></div><div><dl><dt>This version:</dt><dd>Working Draft: 26 March 2003</dd></dl><dl><dt>Previous versions:</dt><dd>Committee Specification: 3 December 2001<br>Committee Specification: 10 August 2001</dd></dl></div><div><dl><dt>Editors:</dt><dd>James Clark <tt class="email"><<a href="mailto:[email protected]">[email protected]</a>></tt>, MURATA Makoto <tt class="email"><<a href="mailto:[email protected]">[email protected]</a>></tt></dd></dl></div><div></div><div><div class="legalnotice"><p>Copyright © The Organization for the Advancement of
Structured Information Standards [OASIS] 2001, 2003. All Rights
Reserved.</p><p>This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise explain
it or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any kind,
provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to OASIS, except as needed for the
purpose of developing OASIS specifications, in which case the
procedures for copyrights defined in the OASIS Intellectual Property
Rights document must be followed, or as required to translate it into
languages other than English.</p><p>The limited permissions granted above are perpetual and will not
be revoked by OASIS or its successors or assigns.</p><p>This document and the information contained herein is provided
on an "<span class="quote">AS IS</span>" basis and OASIS DISCLAIMS ALL WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE
USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY
IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.</p></div></div><div><hr><div class="abstract"><h2><a name="id2811725"></a>Abstract</h2><p>RELAX NG is a simple schema language for XML, based on [<a href="#relax"><span class="abbrev">RELAX</span></a>] and [<a href="#trex"><span class="abbrev">TREX</span></a>]. A RELAX NG schema
specifies a pattern for the structure and content of an XML
document. A RELAX NG schema thus identifies a class of XML documents
consisting of those documents that match the pattern.</p><p>Two syntaxes have been defined for RELAX NG. The original
syntax uses XML; with this syntax an RELAX NG schema is itself an XML
document. Subsequently, a compact non-XML syntax has been
defined.</p><p>This document is a tutorial for RELAX NG version 1.0 using the
XML
syntax.</p></div></div><div><div class="legalnotice"><h2>Status of this Document</h2><p>This is a working draft constructed by the editors. It is not an
official committee work product and may not reflect the consensus
opinion of the committee. Comments on this document may be sent to
<a href="mailto:[email protected]" target="_top">[email protected]</a>.</p></div></div></div><div class="toc"><h2>Table of Contents</h2><dl><dt>1. <a href="#id2814004">Getting started</a></dt><dt>2. <a href="#id2814145">Choice</a></dt><dt>3. <a href="#id2814190">Attributes</a></dt><dt>4. <a href="#id2814574">Named patterns</a></dt><dt>5. <a href="#id2814728">Datatyping</a></dt><dt>6. <a href="#id2814985">Enumerations</a></dt><dt>7. <a href="#id2815195">Lists</a></dt><dt>8. <a href="#id2815274">Interleaving</a></dt><dt>9. <a href="#id2815519">Modularity</a></dt><dd><dl><dt>9.1. <a href="#id2815526">Referencing external patterns</a></dt><dt>9.2. <a href="#id2815624">Combining definitions</a></dt><dt>9.3. <a href="#id2813894">Merging grammars</a></dt><dt>9.4. <a href="#id2816167">Replacing definitions</a></dt></dl></dd><dt>10. <a href="#id2816290">Namespaces</a></dt><dd><dl><dt>10.1. <a href="#id2816305">Using the ns attribute</a></dt><dt>10.2. <a href="#id2816564">Qualified names</a></dt></dl></dd><dt>11. <a href="#id2816679">Name classes</a></dt><dt>12. <a href="#id2816970">Annotations</a></dt><dt>13. <a href="#id2817066">Nested grammars</a></dt><dt>14. <a href="#id2817179">Non-restrictions</a></dt><dt>15. <a href="#id2817227">Further information</a></dt></dl><h3>Appendixes</h3><dl><dt>A. <a href="#id2817313">Comparison with XML DTDs</a></dt><dt>B. <a href="#id2817433">Comparison with RELAX Core</a></dt><dd><dl><dt>1. <a href="#id2817447">Mapping RELAX NG to RELAX Core</a></dt><dd><dl><dt>1.1. <a href="#id2817454">elementRule-tag pairs</a></dt><dt>1.2. <a href="#id2817543">hedgeRule</a></dt><dt>1.3. <a href="#id2817597">attPool</a></dt><dt>1.4. <a href="#id2817638">Hedge models</a></dt><dt>1.5. <a href="#id2817748">Attribute declarations</a></dt></dl></dd><dt>2. <a href="#id2817827">Examples</a></dt><dd><dl><dt>2.1. <a href="#id2817835">Ancestor-and-sibling-sensitive content models</a></dt><dt>2.2. <a href="#id2817896">Attribute-sensitive content model</a></dt></dl></dd><dt>3. <a href="#id2817974">Features of RELAX NG beyond RELAX Core</a></dt></dl></dd><dt>C. <a href="#id2818092">Comparison with TREX</a></dt><dt>D. <a href="#id2818380">Changes from 12 June 2001 version</a></dt><dt><a href="#id2818456">References</a></dt></dl></div><hr><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814004"></a>1. Getting started</h2></div></div><p>Consider a simple XML representation of an email address book:</p><pre class="programlisting"><addressBook>
<card>
<name>John Smith</name>
<email>[email protected]</email>
</card>
<card>
<name>Fred Bloggs</name>
<email>[email protected]</email>
</card>
</addressBook></pre><p>The DTD (as an internal subset) would be as follows:</p><pre class="programlisting"><!DOCTYPE addressBook [
<!ELEMENT addressBook (card*)>
<!ELEMENT card (name, email)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT email (#PCDATA)>
]></pre><p>A RELAX NG pattern for this could be written as follows:</p><pre class="programlisting"><element name="addressBook" xmlns="http://relaxng.org/ns/structure/1.0">
<zeroOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</element>
</zeroOrMore>
</element></pre><p>If the <tt class="literal">addressBook</tt> is required to be non-empty, then
we can use <tt class="literal">oneOrMore</tt> instead of
<tt class="literal">zeroOrMore</tt>:</p><pre class="programlisting"><element name="addressBook" xmlns="http://relaxng.org/ns/structure/1.0">
<oneOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</element>
</oneOrMore>
</element></pre><p>Now let's change it to allow each <tt class="literal">card</tt> to have an
optional <tt class="literal">note</tt> element:</p><pre class="programlisting"><element name="addressBook" xmlns="http://relaxng.org/ns/structure/1.0">
<zeroOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
<optional>
<element name="note">
<text/>
</element>
</optional>
</element>
</zeroOrMore>
</element></pre><p>Note that the <tt class="literal">text</tt> pattern matches arbitrary text,
including empty text. Note also that whitespace separating tags is
ignored when matching against a pattern.</p><p>All the elements specifying the pattern must be namespace qualified
by the namespace URI:</p><pre class="programlisting">http://relaxng.org/ns/structure/1.0</pre><p>The examples above use a default namespace declaration
<tt class="literal">xmlns="http://relaxng.org/ns/structure/1.0"</tt> for this. A
namespace prefix is equally acceptable:</p><pre class="programlisting"><rng:element name="addressBook" xmlns:rng="http://relaxng.org/ns/structure/1.0">
<rng:zeroOrMore>
<rng:element name="card">
<rng:element name="name">
<rng:text/>
</rng:element>
<rng:element name="email">
<rng:text/>
</rng:element>
</rng:element>
</rng:zeroOrMore>
</rng:element></pre><p>For the remainder of this document, the default namespace
declaration will be left out of examples.</p></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814145"></a>2. Choice</h2></div></div><p>Now suppose we want to allow the <tt class="literal">name</tt> to be broken
down into a <tt class="literal">givenName</tt> and a <tt class="literal">familyName</tt>,
allowing an <tt class="literal">addressBook</tt> like this:</p><pre class="programlisting"><addressBook>
<card>
<givenName>John</givenName>
<familyName>Smith</familyName>
<email>[email protected]</email>
</card>
<card>
<name>Fred Bloggs</name>
<email>[email protected]</email>
</card>
</addressBook></pre><p>We can use the following pattern:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<choice>
<element name="name">
<text/>
</element>
<group>
<element name="givenName">
<text/>
</element>
<element name="familyName">
<text/>
</element>
</group>
</choice>
<element name="email">
<text/>
</element>
<optional>
<element name="note">
<text/>
</element>
</optional>
</element>
</zeroOrMore>
</element></pre><p>This corresponds to the following DTD:</p><pre class="programlisting"><!DOCTYPE addressBook [
<!ELEMENT addressBook (card*)>
<!ELEMENT card ((name | (givenName, familyName)), email, note?)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT email (#PCDATA)>
<!ELEMENT givenName (#PCDATA)>
<!ELEMENT familyName (#PCDATA)>
<!ELEMENT note (#PCDATA)>
]></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814190"></a>3. Attributes</h2></div></div><p>Suppose we want the <tt class="literal">card</tt> element to have attributes
rather than child elements. The DTD might look like this:</p><pre class="programlisting"><!DOCTYPE addressBook [
<!ELEMENT addressBook (card*)>
<!ELEMENT card EMPTY>
<!ATTLIST card
name CDATA #REQUIRED
email CDATA #REQUIRED>
]></pre><p>Just change each <tt class="literal">element</tt> pattern to an
<tt class="literal">attribute</tt> pattern:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<attribute name="name">
<text/>
</attribute>
<attribute name="email">
<text/>
</attribute>
</element>
</zeroOrMore>
</element></pre><p>In XML, the order of attributes is traditionally not significant.
RELAX NG follows this tradition. The above pattern would match both</p><pre class="programlisting"><card name="John Smith" email="[email protected]"/></pre><p>and</p><pre class="programlisting"><card email="[email protected]" name="John Smith"/></pre><p>In contrast, the order of elements is significant. The pattern</p><pre class="programlisting"><element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</element></pre><p>would <span class="strong">not</span> match</p><pre class="programlisting"><card><email>[email protected]</email><name>John Smith</name></card></pre><p>Note that an <tt class="literal">attribute</tt> pattern by itself indicates a
required attribute, just as an <tt class="literal">element</tt> pattern by itself
indicates a required element. To specify an optional attribute, use
<tt class="literal">optional</tt> just as with <tt class="literal">element</tt>:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<attribute name="name">
<text/>
</attribute>
<attribute name="email">
<text/>
</attribute>
<optional>
<attribute name="note">
<text/>
</attribute>
</optional>
</element>
</zeroOrMore>
</element></pre><p>The <tt class="literal">group</tt> and <tt class="literal">choice</tt> patterns can be
applied to <tt class="literal">attribute</tt> patterns in the same way they are
applied to <tt class="literal">element</tt> patterns. For example, if we wanted
to allow either a <tt class="literal">name</tt> attribute or both a
<tt class="literal">givenName</tt> and a <tt class="literal">familyName</tt> attribute, we can
specify this in the same way that we would if we were using
elements:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<choice>
<attribute name="name">
<text/>
</attribute>
<group>
<attribute name="givenName">
<text/>
</attribute>
<attribute name="familyName">
<text/>
</attribute>
</group>
</choice>
<attribute name="email">
<text/>
</attribute>
</element>
</zeroOrMore>
</element></pre><p>The <tt class="literal">group</tt> and <tt class="literal">choice</tt>
patterns can combine <tt class="literal">element</tt> and
<tt class="literal">attribute</tt> patterns without restriction. For
example, the following pattern would allow a choice of elements and
attributes independently for both the <tt class="literal">name</tt> and the
<tt class="literal">email</tt> part of a <tt class="literal">card</tt>:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<choice>
<element name="name">
<text/>
</element>
<attribute name="name">
<text/>
</attribute>
</choice>
<choice>
<element name="email">
<text/>
</element>
<attribute name="email">
<text/>
</attribute>
</choice>
</element>
</zeroOrMore>
</element></pre><p>As usual, the relative order of elements is significant, but the
relative order of attributes is not. Thus the above would match any
of:</p><pre class="programlisting"><card name="John Smith" email="[email protected]"/>
<card email="[email protected]" name="John Smith"/>
<card email="[email protected]"><name>John Smith</name></card>
<card name="John Smith"><email>[email protected]</email></card>
<card><name>John Smith</name><email>[email protected]</email></card></pre><p>However, it would not match</p><pre class="programlisting"><card><email>[email protected]</email><name>John Smith</name></card></pre><p>because the pattern for <tt class="literal">card</tt> requires any
<tt class="literal">email</tt> child element to follow any <tt class="literal">name</tt> child
element.</p><p>There is one difference between <tt class="literal">attribute</tt> and
<tt class="literal">element</tt> patterns: <tt class="literal"><text/></tt>
is the default for the content of an <tt class="literal">attribute</tt> pattern,
whereas an <tt class="literal">element</tt> pattern is not allowed to be
empty. For example,</p><pre class="programlisting"><attribute name="email"/></pre><p>is short for</p><pre class="programlisting"><attribute name="email">
<text/>
</attribute></pre><p>It might seem natural that</p><pre class="programlisting"><element name="x"/></pre><p>matched an <tt class="literal">x</tt> element with no attributes and no
content. However, this would make the meaning of empty content
inconsistent between the <tt class="literal">element</tt> pattern and the
<tt class="literal">attribute</tt> pattern, so RELAX NG does not allow the
<tt class="literal">element</tt> pattern to be empty. A pattern that matches an
element with no attributes and no children must use
<tt class="literal"><empty/></tt> explicitly:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
<optional>
<element name="prefersHTML">
<empty/>
</element>
</optional>
</element>
</zeroOrMore>
</element></pre><p>Even if the pattern in an <tt class="literal">element</tt> pattern
matches attributes only, there is no need to use
<tt class="literal">empty</tt>. For example,</p><pre class="programlisting"><element name="card">
<attribute name="email">
<text/>
</attribute>
</element></pre><p>is equivalent to</p><pre class="programlisting"><element name="card">
<attribute name="email">
<text/>
</attribute>
<empty/>
</element></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814574"></a>4. Named patterns</h2></div></div><p>For a non-trivial RELAX NG pattern, it is often convenient to be able
to give names to parts of the pattern. Instead of</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</element>
</zeroOrMore>
</element></pre><p>we can write</p><pre class="programlisting"><grammar>
<start>
<element name="addressBook">
<zeroOrMore>
<element name="card">
<ref name="cardContent"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="cardContent">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</define>
</grammar></pre><p>A <tt class="literal">grammar</tt> element has a single <tt class="literal">start</tt>
child element, and zero or more <tt class="literal">define</tt> child elements.
The <tt class="literal">start</tt> and <tt class="literal">define</tt> elements contain
patterns. These patterns can contain <tt class="literal">ref</tt> elements that
refer to patterns defined by any of the <tt class="literal">define</tt> elements
in that <tt class="literal">grammar</tt> element. A <tt class="literal">grammar</tt> pattern
is matched by matching the pattern contained in the <tt class="literal">start</tt>
element.</p><p>We can use the <tt class="literal">grammar</tt> pattern to write RELAX NG in a
style similar to DTDs:</p><pre class="programlisting"><grammar>
<start>
<ref name="AddressBook"/>
</start>
<define name="AddressBook">
<element name="addressBook">
<zeroOrMore>
<ref name="Card"/>
</zeroOrMore>
</element>
</define>
<define name="Card">
<element name="card">
<ref name="Name"/>
<ref name="Email"/>
</element>
</define>
<define name="Name">
<element name="name">
<text/>
</element>
</define>
<define name="Email">
<element name="email">
<text/>
</element>
</define>
</grammar></pre><p>Recursive references are allowed. For example,</p><pre class="programlisting"><define name="inline">
<zeroOrMore>
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
<element name="span">
<optional>
<attribute name="style"/>
</optional>
<ref name="inline"/>
</element>
</choice>
</zeroOrMore>
</define></pre><p>However, recursive references must be within an
<tt class="literal">element</tt> pattern. Thus, the following is <span class="strong">not</span>
allowed:</p><pre class="programlisting"><define name="inline">
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
<element name="span">
<optional>
<attribute name="style"/>
</optional>
<ref name="inline"/>
</element>
</choice>
<optional>
<ref name="inline"/>
</optional>
</define></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814728"></a>5. Datatyping</h2></div></div><p>RELAX NG allows patterns to reference externally-defined
datatypes. RELAX NG implementations may differ in what datatypes they
support. You can only use datatypes that are supported by the
implementation you plan to use. The most commonly used datatypes are
those defined by [<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>].</p><p>The <tt class="literal">data</tt> pattern matches a string that
represents a value of a named datatype. The
<tt class="literal">datatypeLibrary</tt> attribute contains a URI
identifying the library of datatypes being used. The datatype
library defined by [<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>] is identified by the
URI <tt class="literal">http://www.w3.org/2001/XMLSchema-datatypes</tt>.
The <tt class="literal">type</tt> attribute specifies the name of the
datatype in the library identified by the
<tt class="literal">datatypeLibrary</tt> attribute. For example, assuming the
RELAX NG implementation supported the datatypes of
[<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>], you could use:</p><pre class="programlisting"><element name="number">
<data type="integer" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"/>
</element></pre><p>It is inconvenient to specify the
<tt class="literal">datatypeLibrary</tt> attribute on every
<tt class="literal">data</tt> element, so RELAX NG allows the
<tt class="literal">datatypeLibrary</tt> attribute to be inherited. The
<tt class="literal">datatypeLibrary</tt> attribute can be specified on any
RELAX NG element. If a <tt class="literal">data</tt> element does not have
a <tt class="literal">datatypeLibrary</tt> attribute, it will use the
value from the closest ancestor that has a
<tt class="literal">datatypeLibrary</tt> attribute. Typically, the
<tt class="literal">datatypeLibrary</tt> attribute is specified on the
root element of the RELAX NG pattern. For example,</p><pre class="programlisting"><element name="point" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
<element name="x">
<data type="double"/>
</element>
<element name="y">
<data type="double"/>
</element>
</element></pre><p>If the children of an element or an attribute match a
<tt class="literal">data</tt> pattern, then the complete content of the element or
attribute must match that <tt class="literal">data</tt> pattern. It is not
permitted to have a pattern which allows part of the content to match
a <tt class="literal">data</tt> pattern, and another part to match another
pattern. For example, the following pattern is <span class="strong">not</span>
allowed:</p><pre class="programlisting"><element name="bad">
<data type="int"/>
<element name="note">
<text/>
</element>
</element></pre><p>However, this would be fine:</p><pre class="programlisting"><element name="ok">
<data type="int"/>
<attribute name="note">
<text/>
</attribute>
</element></pre><p>Note that this restriction does not apply to the
<tt class="literal">text</tt> pattern.</p><p>Datatypes may have parameters. For example, a string datatype may
have a parameter controlling the length of the string. The parameters
applicable to any particular datatype are determined by the datatyping
vocabulary. In the case of [<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>], the
applicable parameters correspond to the facets defined in
[<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>] with the exception of the
<tt class="literal">enumeration</tt> and <tt class="literal">whiteSpace</tt>
facets. Parameters are specified by adding one or more
<tt class="literal">param</tt> elements as children of the <tt class="literal">data</tt>
element. For example, the following
constrains the <tt class="literal">email</tt> element to contain a string at
least 6 characters long and at most 127 characters long:</p><pre class="programlisting"><element name="email">
<data type="string">
<param name="minLength">6</param>
<param name="maxLength">127</param>
</data>
</element></pre><p>A companion document, [<a href="#guidelines"><span class="abbrev">Guidelines</span></a>], describes
exactly how the datatypes defined in [<a href="#xmlschema-2"><span class="abbrev">W3C XML Schema Datatypes</span></a>] can
be used as a RELAX NG datatype library.</p></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2814985"></a>6. Enumerations</h2></div></div><p>Many markup vocabularies have attributes whose value is constrained
to be one of a set of specified values. The <tt class="literal">value</tt> pattern
matches a string that has a specified value. For example,</p><pre class="programlisting"><element name="card">
<attribute name="name"/>
<attribute name="email"/>
<attribute name="preferredFormat">
<choice>
<value>html</value>
<value>text</value>
</choice>
</attribute>
</element></pre><p>allows the <tt class="literal">preferredFormat</tt> attribute to have the value
<tt class="literal">html</tt> or <tt class="literal">text</tt>. This corresponds to the
DTD:</p><pre class="programlisting"><!DOCTYPE card [
<!ELEMENT card EMPTY>
<!ATTLIST card
name CDATA #REQUIRED
email CDATA #REQUIRED
preferredFormat (html|text) #REQUIRED>
]></pre><p>The <tt class="literal">value</tt> pattern is not restricted to attribute
values. For example, the following is allowed:</p><pre class="programlisting"><element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
<element name="preferredFormat">
<choice>
<value>html</value>
<value>text</value>
</choice>
</element>
</element></pre><p>The prohibition against a <tt class="literal">data</tt> pattern's matching
only part of the content of an element also applies to
<tt class="literal">value</tt> patterns.</p><p>By default, the <tt class="literal">value</tt> pattern will consider the string
in the pattern to match the string in the document if the two strings
are the same after the whitespace in both strings is normalized.
Whitespace normalization strips leading and trailing whitespace
characters, and collapses sequences of one or more whitespace
characters to a single space character. This corresponds to the
behaviour of an XML parser for an attribute that is declared as other
than CDATA. Thus the above pattern will match any of:</p><pre class="programlisting"><card name="John Smith" email="[email protected]" preferredFormat="html"/>
<card name="John Smith" email="[email protected]" preferredFormat=" html "/></pre><p>The way that the <tt class="literal">value</tt> pattern compares the
pattern string with the document string can be controlled by
specifying a <tt class="literal">type</tt> attribute and optionally a
<tt class="literal">datatypeLibrary</tt> attribute, which identify a
datatype in the same way as for the <tt class="literal">data</tt> pattern.
The pattern string matches the document string if they both represent
the same value of the specified datatype. Thus, whereas the
<tt class="literal">data</tt> pattern matches an arbitrary value of a
datatype, the <tt class="literal">value</tt> pattern matches a specific
value of a datatype.</p><p>If there is no ancestor element with a
<tt class="literal">datatypeLibrary</tt> element, the datatype library
defaults to a built-in RELAX NG datatype library. This provides two
datatypes, <tt class="literal">string</tt> and <tt class="literal">token</tt>:
<tt class="literal">token</tt> corresponds to the
default comparison behavior of the <tt class="literal">value</tt> pattern;
<tt class="literal">string</tt> compares strings
without any whitespace normalization (other than the end-of-line and
attribute value normalization automatically performed by an XML processor). For
example,</p><pre class="programlisting"><element name="card">
<attribute name="name"/>
<attribute name="email"/>
<attribute name="preferredFormat">
<choice>
<value type="string">html</value>
<value type="string">text</value>
</choice>
</attribute>
</element></pre><p>will <span class="strong">not</span> match</p><pre class="programlisting"><card name="John Smith" email="[email protected]" preferredFormat=" html "/></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2815195"></a>7. Lists</h2></div></div><p>The <tt class="literal">list</tt> pattern matches a whitespace-separated
sequence of tokens; it contains a pattern that the sequence of
individual tokens must match. The <tt class="literal">list</tt> pattern
splits a string into a list of strings, and then matches the resulting
list of strings against the pattern inside the <tt class="literal">list</tt>
pattern.</p><p>For example, suppose we want to have a <tt class="literal">vector</tt>
element that contains two floating point numbers separated by
whitespace. We could use <tt class="literal">list</tt> as follows:</p><pre class="programlisting"><element name="vector">
<list>
<data type="float"/>
<data type="float"/>
</list>
</element></pre><p>Or suppose we want the <tt class="literal">vector</tt> element to
contain a list of one or more floating point numbers separated by
whitespace:</p><pre class="programlisting"><element name="vector">
<list>
<oneOrMore>
<data type="double"/>
</oneOrMore>
</list>
</element></pre><p>Or suppose we want a <tt class="literal">path</tt> element containing
an even number of floating point numbers:</p><pre class="programlisting"><element name="path">
<list>
<oneOrMore>
<data type="double"/>
<data type="double"/>
</oneOrMore>
</list>
</element></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2815274"></a>8. Interleaving</h2></div></div><p>The <tt class="literal">interleave</tt> pattern allows child elements to occur
in any order. For example, the following would allow the
<tt class="literal">card</tt> element to contain the <tt class="literal">name</tt> and
<tt class="literal">email</tt> elements in any order:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<interleave>
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
</interleave>
</element>
</zeroOrMore>
</element></pre><p>The pattern is called <tt class="literal">interleave</tt> because of how it
works with patterns that match more than one element. Suppose we want
to write a pattern for the HTML <tt class="literal">head</tt> element which
requires exactly one <tt class="literal">title</tt> element, at most one
<tt class="literal">base</tt> element and zero or more <tt class="literal">style</tt>,
<tt class="literal">script</tt>, <tt class="literal">link</tt> and <tt class="literal">meta</tt> elements
and suppose we are writing a <tt class="literal">grammar</tt> pattern that has one
definition for each element. Then we could define the pattern for
<tt class="literal">head</tt> as follows:</p><pre class="programlisting"><define name="head">
<element name="head">
<interleave>
<ref name="title"/>
<optional>
<ref name="base"/>
</optional>
<zeroOrMore>
<ref name="style"/>
</zeroOrMore>
<zeroOrMore>
<ref name="script"/>
</zeroOrMore>
<zeroOrMore>
<ref name="link"/>
</zeroOrMore>
<zeroOrMore>
<ref name="meta"/>
</zeroOrMore>
</interleave>
</element>
</define></pre><p>Suppose we had a <tt class="literal">head</tt> element that contained a
<tt class="literal">meta</tt> element, followed by a <tt class="literal">title</tt> element,
followed by a <tt class="literal">meta</tt> element. This would match the pattern
because it is an interleaving of a sequence of two <tt class="literal">meta</tt>
elements, which match the child pattern</p><pre class="programlisting"> <zeroOrMore>
<ref name="meta"/>
</zeroOrMore></pre><p>and a sequence of one <tt class="literal">title</tt> element, which matches
the child pattern</p><pre class="programlisting"> <ref name="title"/></pre><p>The semantics of the <tt class="literal">interleave</tt> pattern are that a
sequence of elements matches an <tt class="literal">interleave</tt> pattern if it
is an interleaving of sequences that match the child patterns of the
<tt class="literal">interleave</tt> pattern. Note that this is different from the
<tt class="literal">&</tt> connector in SGML: <tt class="literal">A* & B</tt> matches
the sequence of elements <tt class="literal">A A B</tt> or the sequence of
elements <tt class="literal">B A A</tt> but not the sequence of elements <tt class="literal">A B
A</tt>.</p><p>One special case of interleaving is very common:
interleaving <tt class="literal"><text/></tt> with a pattern
<i class="replaceable"><tt>p</tt></i> represents a pattern that matches what <i class="replaceable"><tt>p</tt></i>
matches but also allows characters to occur as children. The
<tt class="literal">mixed</tt> pattern is a shorthand for this.</p><pre class="programlisting"><mixed> <i class="replaceable"><tt>p</tt></i> </mixed></pre><p>is short for</p><pre class="programlisting"><interleave> <text/> <i class="replaceable"><tt>p</tt></i> </interleave></pre></div><div class="section" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2815519"></a>9. Modularity</h2></div></div><div class="section" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2815526"></a>9.1. Referencing external patterns</h3></div></div><p>The <tt class="literal">externalRef</tt> pattern can be used to
reference a pattern defined in a separate file. The
<tt class="literal">externalRef</tt> element has a required
<tt class="literal">href</tt> attribute that specifies the URL of a file
containing the pattern. The <tt class="literal">externalRef</tt> pattern matches if
the pattern contained in the specified URL matches. Suppose for
example, you have a RELAX NG pattern that matches HTML inline content
stored in <tt class="literal">inline.rng</tt>:</p><pre class="programlisting"><grammar>
<start>
<ref name="inline"/>
</start>
<define name="inline">
<zeroOrMore>
<choice>
<text/>
<element name="code">
<ref name="inline"/>
</element>
<element name="em">
<ref name="inline"/>
</element>
<!-- etc -->
</choice>
</zeroOrMore>
</define>
</grammar></pre><p>Then we could allow the <tt class="literal">note</tt> element to contain
inline HTML markup by using <tt class="literal">externalRef</tt> as follows:</p><pre class="programlisting"><element name="addressBook">
<zeroOrMore>
<element name="card">
<element name="name">
<text/>
</element>
<element name="email">
<text/>
</element>
<optional>
<element name="note">
<externalRef href="inline.rng"/>
</element>
</optional>
</element>
</zeroOrMore>
</element></pre><p>For another example, suppose you have two RELAX NG patterns stored in
files <tt class="literal">pattern1.rng</tt> and <tt class="literal">pattern2.rng</tt>. Then
the following is a pattern that matches anything matched
by either of those patterns:</p><pre class="programlisting"><choice>
<externalRef href="pattern1.rng"/>
<externalRef href="pattern2.rng"/>
</choice></pre></div><div class="section" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2815624"></a>9.2. Combining definitions</h3></div></div><p>If a grammar contains multiple definitions with the same name,
then the definitions must specify how they are to be combined into a
single definition by using the <tt class="literal">combine</tt> attribute.
The <tt class="literal">combine</tt> attribute may have the value
<tt class="literal">choice</tt> or <tt class="literal">interleave</tt>. For
example,</p><pre class="programlisting"><define name="inline.class" combine="choice">
<element name="bold">
<ref name="inline"/>
</element>
</define>
<define name="inline.class" combine="choice">
<element name="italic">
<ref name="inline"/>
</element>
</define></pre><p>is equivalent to</p><pre class="programlisting"><define name="inline.class">
<choice>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
</choice>
</define></pre><p>When combining attributes, <tt class="literal">combine="interleave"</tt>
is typically used. For example,</p><pre class="programlisting"><grammar>
<start>
<element name="addressBook">
<zeroOrMore>
<element name="card">
<ref name="card.attlist"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="card.attlist" combine="interleave">
<attribute name="name">
<text/>
</attribute>
</define>
<define name="card.attlist" combine="interleave">
<attribute name="email">
<text/>
</attribute>
</define>
</grammar></pre><p>is equivalent to</p><pre class="programlisting"><grammar>
<start>
<element name="addressBook">
<zeroOrMore>
<element name="card">
<ref name="card.attlist"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="card.attlist">
<interleave>
<attribute name="name">
<text/>
</attribute>
<attribute name="email">
<text/>
</attribute>
</interleave>
</define>
</grammar></pre><p>which is equivalent to</p><pre class="programlisting"><grammar>
<start>
<element name="addressBook">
<zeroOrMore>
<element name="card">
<ref name="card.attlist"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="card.attlist">
<group>
<attribute name="name">
<text/>
</attribute>
<attribute name="email">
<text/>
</attribute>
</group>
</define>
</grammar></pre><p>since combining attributes with <tt class="literal">interleave</tt>
has the same effect as combining them with
<tt class="literal">group</tt>.</p><p>It is an error for two definitions of the same name to specify
different values for <tt class="literal">combine</tt>. Note that the order
of definitions within a grammar is not significant.</p><p>Multiple <tt class="literal">start</tt> elements can be combined in
the same way as multiple definitions.</p></div><div class="section" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2813894"></a>9.3. Merging grammars</h3></div></div><p>The <tt class="literal">include</tt> element allows grammars to be
merged together. A <tt class="literal">grammar</tt> pattern may have
<tt class="literal">include</tt> elements as children. An
<tt class="literal">include</tt> element has a required
<tt class="literal">href</tt> attribute that specifies the URL of a file
containing a <tt class="literal">grammar</tt> pattern. The definitions in
the referenced <tt class="literal">grammar</tt> pattern will be included in
<tt class="literal">grammar</tt> pattern containing the
<tt class="literal">include</tt> element.</p><p>The <tt class="literal">combine</tt> attribute is particularly useful
in conjunction with <tt class="literal">include</tt>. For example, suppose
a RELAX NG pattern <tt class="literal">inline.rng</tt> provides a pattern
for inline content, which allows <tt class="literal">bold</tt> and
<tt class="literal">italic</tt> elements arbitrarily nested:</p><pre class="programlisting"><grammar>
<define name="inline">
<zeroOrMore>
<ref name="inline.class"/>
</zeroOrMore>
</define>
<define name="inline.class">
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
</choice>
</define>
</grammar></pre><p>Another RELAX NG pattern could use <tt class="literal">inline.rng</tt>
and add <tt class="literal">code</tt> and <tt class="literal">em</tt> to the set
of inline elements as follows:</p><pre class="programlisting"><grammar>
<include href="inline.rng"/>
<start>
<element name="doc">
<zeroOrMore>
<element name="p">
<ref name="inline"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="inline.class" combine="choice">
<choice>
<element name="code">
<ref name="inline"/>
</element>
<element name="em">
<ref name="inline"/>
</element>
</choice>
</define>
</grammar></pre><p>This would be equivalent to</p><pre class="programlisting"><grammar>
<define name="inline">
<zeroOrMore>
<ref name="inline.class"/>
</zeroOrMore>
</define>
<define name="inline.class">
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
</choice>
</define>
<start>
<element name="doc">
<zeroOrMore>
<element name="p">
<ref name="inline"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="inline.class" combine="choice">
<choice>
<element name="code">
<ref name="inline"/>
</element>
<element name="em">
<ref name="inline"/>
</element>
</choice>
</define>
</grammar></pre><p>which is equivalent to</p><pre class="programlisting"><grammar>
<define name="inline">
<zeroOrMore>
<ref name="inline.class"/>
</zeroOrMore>
</define>
<define name="inline.class">
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
<element name="code">
<ref name="inline"/>
</element>
<element name="em">
<ref name="inline"/>
</element>
</choice>
</define>
<start>
<element name="doc">
<zeroOrMore>
<element name="p">
<ref name="inline"/>
</element>
</zeroOrMore>
</element>
</start>
</grammar></pre><p>Note that it is allowed for one of the definitions of a name to
omit the <tt class="literal">combine</tt> attribute. However, it is an
error if there is more than one definition that does so.</p><p>The <tt class="literal">notAllowed</tt> pattern is useful when merging
grammars. The <tt class="literal">notAllowed</tt> pattern never matches
anything. Just as adding <tt class="literal">empty</tt> to a
<tt class="literal">group</tt> makes no difference, so adding
<tt class="literal">notAllowed</tt> to a <tt class="literal">choice</tt> makes no
difference. It is typically used to allow an including pattern to
specify additional choices with <tt class="literal">combine="choice"</tt>.
For example, if <tt class="literal">inline.rng</tt> were written like
this:</p><pre class="programlisting"><grammar>
<define name="inline">
<zeroOrMore>
<choice>
<text/>
<element name="bold">
<ref name="inline"/>
</element>
<element name="italic">
<ref name="inline"/>
</element>
<ref name="inline.extra"/>
</choice>
</zeroOrMore>
</define>
<define name="inline.extra">
<notAllowed/>
</define>
</grammar></pre><p>then it could be customized to allow inline
<tt class="literal">code</tt> and <tt class="literal">em</tt> elements as
follows:</p><pre class="programlisting"><grammar>
<include href="inline.rng"/>
<start>
<element name="doc">
<zeroOrMore>
<element name="p">
<ref name="inline"/>
</element>
</zeroOrMore>
</element>
</start>
<define name="inline.extra" combine="choice">
<choice>
<element name="code">
<ref name="inline"/>
</element>
<element name="em">
<ref name="inline"/>
</element>
</choice>
</define>
</grammar></pre></div><div class="section" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2816167"></a>9.4. Replacing definitions</h3></div></div><p>RELAX NG allows <tt class="literal">define</tt> elements to be put
inside the <tt class="literal">include</tt> element to indicate that they
are to replace definitions in the included <tt class="literal">grammar</tt>
pattern.</p><p>Suppose the file <tt class="literal">addressBook.rng</tt>
contains:</p><pre class="programlisting"><grammar>
<start>
<element name="addressBook">
<zeroOrMore>
<element name="card">
<ref name="cardContent"/>
</element>
</zeroOrMore>