forked from kayhadrin/google-code-styleguide
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathxmlstyle.html
More file actions
1127 lines (960 loc) · 37 KB
/
xmlstyle.html
File metadata and controls
1127 lines (960 loc) · 37 KB
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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf8">
<meta http-equiv="content-type" content="text/html;charset=utf-8">
<style>
/* default css */
table {
font-size: 1em;
line-height: inherit;
}
tr {
text-align: left;
}
div, address, ol, ul, li, option, select {
margin-top: 0px;
margin-bottom: 0px;
}
p {
margin: 0px;
}
body {
margin: 6px;
padding: 0px;
font-family: Verdana, sans-serif;
font-size: 10pt;
background-color: #ffffff;
}
img {
-moz-force-broken-image-icon: 1;
}
@media screen {
html.pageview {
background-color: #f3f3f3 !important;
}
body {
min-height: 1100px;
counter-reset: __goog_page__;
}
* html body {
height: 1100px;
}
.pageview body {
border-top: 1px solid #ccc;
border-left: 1px solid #ccc;
border-right: 2px solid #bbb;
border-bottom: 2px solid #bbb;
width: 648px !important;
margin: 15px auto 25px;
padding: 40px 50px;
}
/* IE6 */
* html {
overflow-y: scroll;
}
* html.pageview body {
overflow-x: auto;
}
/* Prevent repaint errors when scrolling in Safari. This "Star-7" css hack
targets Safari 3.1, but not WebKit nightlies and presumably Safari 4.
That's OK because this bug is fixed in WebKit nightlies/Safari 4 :-). */
html*#wys_frame::before {
content: '\A0';
position: fixed;
overflow: hidden;
width: 0;
height: 0;
top: 0;
left: 0;
}
.writely-callout-data {
display: none;
*display: inline-block;
*width: 0;
*height: 0;
*overflow: hidden;
}
.writely-footnote-marker {
background-image: url('images/footnote_doc_icon.gif');
background-color: transparent;
background-repeat: no-repeat;
width: 7px;
overflow: hidden;
height: 16px;
vertical-align: top;
-moz-user-select: none;
}
.editor .writely-footnote-marker {
cursor: move;
}
.writely-footnote-marker-highlight {
background-position: -15px 0;
-moz-user-select: text;
}
.writely-footnote-hide-selection ::-moz-selection, .writely-footnote-hide-selection::-moz-selection {
background: transparent;
}
.writely-footnote-hide-selection ::selection, .writely-footnote-hide-selection::selection {
background: transparent;
}
.writely-footnote-hide-selection {
cursor: move;
}
.editor .writely-comment-yellow {
background-color: #FF9;
background-position: -240px 0;
}
.editor .writely-comment-yellow-hover {
background-color: #FF0;
background-position: -224px 0;
}
.editor .writely-comment-blue {
background-color: #C0D3FF;
background-position: -16px 0;
}
.editor .writely-comment-blue-hover {
background-color: #6292FE;
background-position: 0 0;
}
.editor .writely-comment-orange {
background-color: #FFDEAD;
background-position: -80px 0;
}
.editor .writely-comment-orange-hover {
background-color: #F90;
background-position: -64px 0;
}
.editor .writely-comment-green {
background-color: #99FBB3;
background-position: -48px 0;
}
.editor .writely-comment-green-hover {
background-color: #00F442;
background-position: -32px 0;
}
.editor .writely-comment-cyan {
background-color: #CFF;
background-position: -208px 0;
}
.editor .writely-comment-cyan-hover {
background-color: #0FF;
background-position: -192px 0;
}
.editor .writely-comment-purple {
background-color: #EBCCFF;
background-position: -144px 0;
}
.editor .writely-comment-purple-hover {
background-color: #90F;
background-position: -128px 0;
}
.editor .writely-comment-magenta {
background-color: #FCF;
background-position: -112px 0;
}
.editor .writely-comment-magenta-hover {
background-color: #F0F;
background-position: -96px 0;
}
.editor .writely-comment-red {
background-color: #FFCACA;
background-position: -176px 0;
}
.editor .writely-comment-red-hover {
background-color: #FF7A7A;
background-position: -160px 0;
}
.editor .writely-comment-marker {
background-image: url('images/markericons_horiz.gif');
background-color: transparent;
padding-right: 11px;
background-repeat: no-repeat;
width: 16px;
height: 16px;
-moz-user-select: none;
}
.editor .writely-comment-hidden {
padding: 0;
background: none;
}
.editor .writely-comment-marker-hidden {
background: none;
padding: 0;
width: 0;
}
.editor .writely-comment-none {
opacity: .2;
filter: progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.editor .writely-comment-none-hover {
opacity: .2;
filter: progid:DXImageTransform.Microsoft.Alpha(opacity=20);
-moz-opacity: .2;
}
.br_fix br:not(:-moz-last-node):not(:-moz-first-node) {
position: relative;
left: -1ex
}
.br_fix br+br {
position: static !important
}
}
h6 {
font-size: 8pt
}
h5 {
font-size: 8pt
}
h4 {
font-size: 10pt
}
h3 {
font-size: 12pt
}
h2 {
font-size: 14pt
}
h1 {
font-size: 18pt
}
blockquote {
padding: 10px;
border: 1px #DDD dashed
}
a img {
border: 0
}
.pb {
border-width: 0;
page-break-after: always;
/* We don't want this to be resizeable, so enforce a width and height
using !important */
height: 1px !important;
width: 100% !important;
}
.editor .pb {
border-top: 1px dashed #C0C0C0;
border-bottom: 1px dashed #C0C0C0;
}
div.google_header, div.google_footer {
position: relative;
margin-top: 1em;
margin-bottom: 1em;
}
/* Table of contents */
.editor div.writely-toc {
background-color: #f3f3f3;
border: 1px solid #ccc;
}
.writely-toc > ol {
padding-left: 3em;
font-weight: bold;
}
ol.writely-toc-subheading {
padding-left: 1em;
font-weight: normal;
}
/* IE6 only */
* html writely-toc ol {
list-style-position: inside;
}
.writely-toc-none {
list-style-type: none;
}
.writely-toc-decimal {
list-style-type: decimal;
}
.writely-toc-upper-alpha {
list-style-type: upper-alpha;
}
.writely-toc-lower-alpha {
list-style-type: lower-alpha;
}
.writely-toc-upper-roman {
list-style-type: upper-roman;
}
.writely-toc-lower-roman {
list-style-type: lower-roman;
}
.writely-toc-disc {
list-style-type: disc;
}
/* Ordered lists converted to numbered lists can preserve ordered types, and
vice versa. This is confusing, so disallow it */
ul[type="i"], ul[type="I"], ul[type="1"], ul[type="a"], ul[type="A"] {
list-style-type: disc;
}
ol[type="disc"], ol[type="circle"], ol[type="square"] {
list-style-type: decimal;
}
/* end default css */
/* custom css */
/* end custom css */
/* ui edited css */
body {
font-family: Verdana;
font-size: 10.0pt;
line-height: normal;
background-color: #ffffff;
}
/* end ui edited css */
/* editor CSS */
.editor a:visited {
color: #551A8B
}
.editor table.zeroBorder {
border: 1px dotted gray
}
.editor table.zeroBorder td {
border: 1px dotted gray
}
.editor table.zeroBorder th {
border: 1px dotted gray
}
.editor div.google_header, .editor div.google_footer {
border: 2px #DDDDDD dashed;
position: static;
width: 100%;
min-height: 2em;
}
.editor .misspell {
background-color: yellow
}
.editor .writely-comment {
font-size: 9pt;
line-height: 1.4;
padding: 1px;
border: 1px dashed #C0C0C0
}
/* end editor CSS */
</style>
<style>
body {
margin: 0px;
}
#doc-contents {
margin: 6px;
}
#google-view-footer {
clear: both;
border-top: thin solid;
padding-top: 0.3em;
padding-bottom: 0.3em;
}
a.google-small-link:link, a.google-small-link:visited {
color: #112ABB;
font-family: Arial, Sans-serif;
font-size: 11px !important;
}
body, p, div, td {
direction: inherit;
}
@media print {
#google-view-footer {
display: none;
}
}
</style>
<script>
function viewOnLoad () {
if (document.location.href.indexOf('spi=1') != -1) {
if (navigator.userAgent.toLowerCase().indexOf('msie') != -1) {
window.print();
} else {
window.setTimeout(window.print, 10);
}
}
if (document.location.href.indexOf('hgd=1') != -1) {
var footer = document.getElementById("google-view-footer");
if (footer) {
footer.style.display = 'none';
}
}
}
</script>
</head>
<body>
<div id="doc-contents">
<div>
<h1 style="text-align: center;">
Google XML Document Format Style Guide</h1>
<div style="text-align: center;">Version 1.0<br>Copyright Google 2008<br><br></div>
<h2>Introduction</h2>This document provides a set of guidelines for general use when designing new XML document
formats (and to some extent XML documents as well; see Section 11). Document formats usually include both formal
parts (DTDs, schemas) and parts expressed in normative English prose.<br><br>These guidelines apply to new designs,
and are not intended to force retroactive changes in existing designs. When participating in the creation of
public or private document format designs, the guidelines may be helpful but should not control the group
consensus.<br><br>This guide is meant for the design of XML that is to be generated and consumed by machines rather
than human beings. Its rules are <i>not applicable</i> to formats such as XHTML (which should be formatted as
much like HTML as possible) or ODF which are meant to express rich text. A document that includes embedded
content in XHTML or some other rich-text format, but also contains purely machine-interpretable portions, SHOULD
follow this style guide for the machine-interpretable portions. It also does not affect XML document formats
that are created by translations from proto buffers or through some other type of format.<br><br>Brief rationales have
been added to most of the guidelines. They are maintained in the same document in hopes that they won't get out
of date, but they are not considered normative.<br><br>The terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are used
in this document in the sense of <a title="RFC 2119" href="http://www.ietf.org/rfc/rfc2119.txt" id="iecm">RFC
2119.</a><br> <br>
<h2>1. To design or not to design, that is the question<br></h2>
<ol>
<li>Attempt to reuse existing XML formats whenever possible, especially those which allow extensions. Creating
an entirely new format should be done only with care and consideration; read <a title="Tim Bray's warnings"
href="http://www.tbray.org/ongoing/When/200x/2006/01/08/No-New-XML-Languages"
id="d3cy">Tim Bray's warnings</a>
first. Try to get wide review of your format, from outside your organization as well, if possible.
[<i>Rationale:</i> New document formats have a cost: they must be reviewed, documented, and learned by users.]<br><br>
</li>
<li>If you are reusing or extending an existing format, make <i>sensible</i>
use of the prescribed elements and attributes, especially any that are
required. Don't completely repurpose them, but do try to see how they
might be used in creative ways if the vanilla semantics aren't
suitable. As a last resort when an element or attribute is required by the format but is not appropriate for
your use case, use some
fixed string as its value. [<i>Rationale:</i> Markup reuse is good, markup abuse is bad.]<br><br></li>
<li>When extending formats, use the implicit style of the existing format, even if it contradicts this guide.
[<i>Rationale: </i>Consistency.]<br></li>
</ol>
<br>
<h2>2. Schemas</h2>
<ol>
<li>Document formats SHOULD be expressed using a schema language. [<i>Rationale: </i>Clarity and
machine-checkability.]<br><br></li>
<li>The schema language SHOULD be <a title="RELAX NG" href="http://www.relaxng.org/" id="p1s7">RELAX NG</a> <a
title="compact syntax" href="http://www.relaxng.org/compact-tutorial-20030326.html" id="ulci">compact syntax</a>.
Embedded <a title="Schematron" href="http://www.schematron.com/" id="ymh-">Schematron</a> rules MAY be added to
the schema for additional fine control. [<i>Rationale:</i>
RELAX NG is the most flexible schema language, with very few arbitrary
restrictions on designs. The compact syntax is quite easy to read and
learn, and can be converted one-to-one to and from the XML syntax when
necessary. Schematron handles arbitrary cross-element and
cross-attribute constraints nicely.]<br><br></li>
<li>Schemas SHOULD use the <a title=""Salami Slice" style"
href="http://www.xfront.com/GlobalVersusLocal.html#SecondDesign" id="r:fj">"Salami
Slice" style</a> (one rule per element). Schemas MAY use the <a title=""Russian Doll" style"
href="http://www.xfront.com/GlobalVersusLocal.html#FirstDesign"
id="h14y">"Russian Doll" style</a> (schema
resembles document) if they are short and simple. The <a title=""Venetian Blind" style"
href="http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign"
id="dr_g">"Venetian Blind" style</a> (one rule per
element type) is unsuited to RELAX NG and SHOULD NOT be used.<br><br></li>
<li>Regular expressions SHOULD be provided to assist in validating complex values.<br><br></li>
<li>DTDs and/or W3C XML Schemas MAY be provided for compatibility with existing products, tools, or users.
[<i>Rationale:</i> We can't change the world all at once.]<br></li>
</ol>
</div>
<div><br>
<h2>3. Namespaces</h2>
<ol>
<li>Element names MUST be in a namespace, except
when extending pre-existing document types that do not use namespaces.
A default namespace SHOULD be used. [<i>Rationale:</i> Namespace-free
documents are obsolete; every set of names should be in some
namespace. Using a default namespace improves readability.]<br><br></li>
<li>Attribute
names SHOULD NOT be in a namespace unless they are drawn from a foreign
document type or are meant to be used in foreign document types. [<i>Rationale:</i> Attribute names in a
namespace must always have a prefix, which is annoying to type and hard to read.]<br><br>
</li>
<li>Namespace names are HTTP URIs. Namespace names SHOULD take the form <span style="font-family: Courier New;">http://example.com/</span><i
style="font-family: Courier New;">whatever</i><span style="font-family: Courier New;">/</span><i><span
style="font-family: Courier New;">year</span>, </i>where <i>whatever</i> is a unique value based on the name of
the document type, and <i>year</i>
is the year the namespace was created. There may be additional URI-path parts
before the <i>year.</i> [<i>Rationale:</i> Existing convention. Providing the year allows for the
possible recycling of code names.]<br><br></li>
<li>Namespaces MUST NOT be changed unless the semantics of particular elements or attributes has changed in
drastically incompatible ways. [<i>Rationale:</i> Changing the namespace requires changing all client
code.]<br><br></li>
<li>Namespace prefixes SHOULD be short (but not so short that they are likely to be conflict with another project).
Single-letter prefixes MUST NOT be used. Prefixes SHOULD contain only lower-case ASCII letters.
[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]
</li>
</ol>
<br>
<h2>4. Names and enumerated values</h2><b>Note: </b>"Names" refers to the names of elements, attributes, and enumerated
values.<br><br>
<ol>
<li>All names MUST use lowerCamelCase. That is, they start with an initial lower-case letter, then each new word
within the name starts with an initial capital letter. [<i>Rationale:</i> Adopting a single style provides
consistency, which helps when referring to names since the capitalization is known and so does not have to be
remembered. It matches Java style, and other languages can be dealt with using automated name conversion.]<br><br>
</li>
<li>Names MUST contain only ASCII letters and digits.
[<i>Rationale:</i> Ease of typing and absence of encoding compatibility problems.]<br> <br></li>
<li>Names SHOULD NOT exceed 25 characters. Longer names SHOULD be
avoided by devising concise and informative names. If a name can only remain within this limit by becoming
obscure, the limit SHOULD be ignored. [<i>Rationale: </i>Longer names are awkward to use and require
additional bandwidth.]<br><br></li>
<li>Published standard abbreviations, if sufficiently well-known, MAY be employed in constructing names. Ad hoc
abbreviations MUST NOT be used. Acronyms MUST be treated as words for camel-casing purposes: informationUri,
not informationURI. [<i>Rationale:</i> An abbreviation that is well known
to one community is often incomprehensible to others who need to use
the same document format (and who do understand the full name); treating an acronym as a word makes it easier to see
where the word boundaries are.] <br></li>
</ol>
<p><br></p>
<p>
</p>
<h2>
5. Elements</h2>
<ol>
<li>All elements MUST contain either nothing, character content, or child elements. Mixed content MUST NOT be
used. [<i>Rationale:</i> Many XML data models don't handle mixed content properly, and its use makes the
element order-dependent. As always, textual formats are not covered by this rule.]<br><br></li>
<li>XML elements that merely wrap repeating child elements SHOULD NOT be used. [<i>Rationale:</i> They are not
used in Atom and add nothing.]
</li>
</ol>
<p><br></p>
<h2>6. Attributes</h2>
<ol>
<li>Document formats MUST NOT depend on the order of attributes in a start-tag. [<i>Rationale:</i> Few XML
parsers report the order, and it is not part of the XML Infoset.]<br><br></li>
<li>Elements SHOULD NOT be overloaded with too many attributes (no more
than 10 as a rule of thumb). Instead, use child elements to
encapsulate closely related attributes. [<i>Rationale:</i> This
approach maintains the built-in extensibility that XML provides with
elements, and is useful for providing forward compatibility as a
specification evolves.]<br><br></li>
<li>Attributes MUST NOT be used to hold values in which line breaks are significant. [<i>Rationale:</i> Such
line breaks are converted to spaces by conformant XML parsers.]<br><br></li>
<li>Document formats MUST allow either single or double quotation marks around attribute values.
[<i>Rationale:</i> XML parsers don't report the difference.]<br></li>
</ol>
<p><br></p>
<p>
</p>
<h2>
7. Values</h2>
<ol>
<li>Numeric values SHOULD be 32-bit signed integers, 64-bit signed integers, or 64-bit IEEE doubles, all expressed in
base 10. These correspond to the XML Schema types <span style="font-family: Courier New;">xsd:int</span>,
<span style="font-family: Courier New;">xsd:long</span>, and <span
style="font-family: Courier New;">xsd:double</span> respectively. If required in particular cases, <span
style="font-family: Courier New;">xsd:integer</span> (unlimited-precision integer) values MAY also be used.
[<i>Rationale:</i> There are far too many numeric types in XML Schema: these provide a reasonable subset.]
<br><br></li>
<li>
Boolean values SHOULD NOT be used (use enumerations instead). If they must be used, they MUST be expressed as
<span style="font-family: Courier New;">true</span> or <span style="font-family: Courier New;">false</span>,
corresponding to a subset of the XML Schema type <span style="font-family: Courier New;">xsd:boolean</span>.
The alternative <span style="font-family: Courier New;">xsd:boolean</span> values <span
style="font-family: Courier New;">1</span> and <span style="font-family: Courier New;">0</span> MUST NOT be used.
[<i>Rationale:</i> Boolean arguments are not extensible. The additional flexibility of allowing numeric values
is not abstracted away by any parser.]<br><br></li>
<li>Dates should be represented using <a title="RFC 3339" href="http://www.ietf.org/rfc/rfc3339.txt" id="sk98">RFC
3339</a> format, a subset of both
ISO 8601 format and XML Schema <span style="font-family: Courier New;">xsd:dateTime</span> format. UTC times
SHOULD be used rather than local times.
[<i>Rationale:</i> There are far too many date formats and time zones, although it is recognized that sometimes
local time preserves important information.]<br><br></li>
<li>Embedded syntax in character content and attribute values SHOULD NOT be
used. Syntax in values means XML tools are largely useless. Syntaxes such as dates, URIs, and
XPath expressions are exceptions. [<i>Rationale:</i>
Users should be able to process XML documents using only an XML parser
without requiring additional special-purpose parsers, which are easy to
get wrong.]<br><br></li>
<li>Be careful with whitespace in values. XML parsers don't strip whitespace in elements, but do convert
newlines to spaces in attributes. However, application frameworks may do more aggressive whitespace stripping.
Your document format SHOULD give rules for whitespace stripping.<br></li>
</ol>
<p><br>
</p>
<p>
</p>
<h2>8. Key-value pairs<br></h2>
<ol>
<li>
Simple key-value pairs SHOULD be represented with an empty element whose name represents the key, with the <span
style="font-family: Courier New;">value</span> attribute containing the value. Elements that have a <span
style="font-family: Courier New;">value</span> attribute MAY also have a <span style="font-family: Courier New;">unit</span>
attribute to specify the unit of a measured value. For physical measurements, the <a title="SI system"
href="http://en.wikipedia.org/wiki/International_System_of_Units"
id="rhxg">SI system</a>
SHOULD be used. [<i>Rationale:</i>
Simplicity and design consistency. Keeping the value in an attribute
hides it from the user, since displaying just the value without the key is not useful.]<br><br></li>
<li>If the number of possible keys is very large or unbounded, key-value pairs MAY be represented by a single generic
element with <span style="font-family: Courier New;">key</span>, <span
style="font-family: Courier New;">value</span>, and optional <span style="font-family: Courier New;">unit</span>
and <span style="font-family: Courier New;">scheme</span>
attributes (which serve to discriminate keys from different domains).
In that case, also provide (not necessarily in the same document) a
list of keys with human-readable explanations.
</li>
</ol>
<br>
<h2>9. Binary data</h2>
<p><b>Note: </b>There are no hard and fast rules about whether binary data should be included as part of an XML document
or not. If it's too large, it's probably better to link to it.</p>
<p><br></p>
<ol>
<li>Binary data MUST NOT be included directly as-is in XML documents, but MUST be encoded using Base64 encoding.
[<i>Rationale:</i> XML does not allow arbitrary binary bytes.]<br><br></li>
<li>
The line breaks required by Base64 MAY be omitted. [<i>Rationale:</i> The line breaks are meant to keep plain
text lines short, but XML is not really plain text.]<br><br></li>
<li>An attribute named <span style="font-family: Courier New;">xsi:type</span> with value <span
style="font-family: Courier New;">xs:base64Binary</span> MAY be attached to this element to signal that the Base64
format is in use. [Rationale: Opaque blobs should have decoding instructions attached.]<br><br></li>
</ol>
<h2>10. Processing instructions</h2>
<ol>
<li>New processing instructions MUST NOT be created except in order to specify purely local processing conventions,
and SHOULD be avoided altogether. Existing standardized processing instructions MAY be used. [<i>Rationale:</i>
Processing instructions fit awkwardly into XML data models and can always be replaced by elements; they exist
primarily to avoid breaking backward compatibility.]
</li>
</ol>
<p> </p>
<p>
</p>
<p> </p>
<h2>11. Representation of XML document instances<br></h2>
<p><b>Note:</b> These points are only guidelines, as the format of program-created instances will often be outside
the programmer's control (for example, when an XML serialization library is being used). <i>In no case</i>
should XML parsers rely on these guidelines being followed. Use standard XML parsers, not hand-rolled hacks.<br>
</p>
<p><br></p>
<ol>
<li>The character encoding used SHOULD be UTF-8. Exceptions should require extremely compelling circumstances.
[<i>Rationale:</i> UTF-8 is universal and in common use.]<br><br></li>
<li>Namespaces SHOULD be declared in the root element of a document wherever possible. [<i>Rationale: </i>Clarity
and consistency.]<br><br></li>
<li>The mapping of namespace URIs to prefixes SHOULD remain constant throughout the document, and SHOULD also be used
in documentation of the design. [<i>Rationale: </i>Clarity and consistency.]<br><br></li>
<li>Well-known prefixes such as html: (for XHTML), dc: (for Dublin Core metadata), and xs: (for XML Schema) should be
used for standard namespaces. [<i>Rationale:</i> Human readability.]<br><br></li>
<li>Redundant whitespace in a tag SHOULD NOT be
used. Use one space before each attribute in a start-tag; if the start
tag is too long, the space MAY be replaced by a newline. [<i>Rationale:</i> Consistency and
conciseness.]<br><br></li>
<li>Empty elements MAY be expressed as empty tags or a start-tag
immediately followed by an end-tag. No distinction should be made
between these two formats by any application. [<i>Rationale:</i> They are not distinguished by XML
parsers.]<br><br></li>
<li>Documents MAY be pretty-printed using 2-space indentation for child
elements. Elements that contain character content SHOULD NOT be
wrapped. Long start-tags MAY be broken using newlines (possibly with extra indentation) after any attribute
value except the last. [<i>Rationale:</i> General compatibility with our style. Wrapping character
content affects its value.]<br><br></li>
<li>Attribute values MAY be surrounded with either quotation marks or apostrophes.
Specifications MUST NOT require or forbid the use of either form. <span style="font-family: Courier New;">&apos;</span>
and <span style="font-family: Courier New;">&quot;</span> may be freely used to escape each type of quote.
[<i>Rationale:</i> No XML parsers report the distinction.]<br><br>
</li>
<li>Comments MUST NOT be used to carry real data. Comments MAY be used to contain TODOs in hand-written XML.
Comments SHOULD NOT be used at all in publicly transmitted documents. [<i>Rationale: </i>Comments are often
discarded by parsers.]<br><br></li>
<li>If comments are nevertheless used, they SHOULD appear only in the document prolog or in elements that
contain child elements. If pretty-printing is required, pretty-print
comments like elements, but with line wrapping. Comments SHOULD NOT
appear in elements that contain character content. [<i>Rationale: </i>Whitespace in and around comments
improves readability, but embedding a
comment in character content can lead to confusion about what
whitespace is or is not in the content.]<br><br></li>
<li>Comments SHOULD have whitespace following <span style="font-family: Courier New;"><!--</span> and preceding
<span style="font-family: Courier New;">--></span>. [<i>Rationale:</i> Readability.]<br><br></li>
<li>CDATA sections MAY be used; they are equivalent to the use of <span
style="font-family: Courier New;">&amp;</span> and <span style="font-family: Courier New;">&lt;</span>.
Specifications MUST NOT require or forbid the use of CDATA sections. [<i>Rationale:</i> Few XML parsers report
the distinction, and combinations of CDATA and text are often reported as single objects anyway.]<br><br></li>
<li>Entity references other than the XML standard entity references <span
style="font-family: Courier New;">&amp;</span>, <span style="font-family: Courier New;">&lt;</span>, <span
style="font-family: Courier New;">&gt;</span>, <span style="font-family: Courier New;">&quot;</span>, and
<span style="font-family: Courier New;">&apos;</span> MUST NOT be used. Character references MAY be used,
but actual characters are preferred, unless the character encoding is not UTF-8. As usual, textual formats are
exempt from this rule.<br></li>
</ol>
<br>
<p> </p>
<p>
</p>
<p>
</p><br><br>
<h2>
12. Elements vs. Attributes
</h2>
<p>
<b>Note:</b> There are no hard and fast rules for deciding when to use attributes and when to use elements.
Here are some of the considerations that designers should take into account; no rationales are given.
</p>
<h3>
12.1. General points:<br>
</h3>
<ol>
<li>
<p>
Attributes are more restrictive than elements, and all designs have some elements, so an all-element design is
simplest -- which is not the same as best.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In a tree-style data model, elements are typically represented internally as nodes, which use more memory than the
strings used to represent attributes. Sometimes the nodes are of different application-specific classes,
which in many languages also takes up memory to represent the classes.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
When streaming, elements are processed one at a time (possibly even piece by piece, depending on the XML parser
you are using), whereas all the attributes of an element and their values are reported at once, which costs
memory, particularly if some attribute values are very long.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Both element content and attribute values need to be escaped appropriately, so escaping should not be a
consideration in the design.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
In some programming languages and libraries, processing elements is easier; in others, processing attributes is
easier. Beware of using ease of processing as a criterion. In particular, XSLT can handle either with
equal facility.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data should usually be shown to the user, consider using an element; if not, consider using an
attribute. (This rule is often violated for one reason or another.)
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If you are extending an existing schema, do things by analogy to how things are done in that schema.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Sensible schema languages, meaning RELAX NG and Schematron, treat elements and attributes symmetrically.
Older and cruder<a href="http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/" id="h2c3" title="XML Schema"> </a>schema
languages such as DTDs and XML Schema, tend to have better support for elements.
</p>
</li>
</ol>
<p>
</p>
<h3>
12.2 Using elements<br>
</h3>
<ol>
<li>
<p>
If something might appear more than once in a data model, use an element rather than introducing attributes with
names like <span style="font-family: Courier New;">foo1, foo2, foo3</span> ....
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements to represent a piece of information that can be considered an independent object and when the
information is related via a parent/child relationship to another piece of information.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
Use elements when data incorporates strict typing or relationship rules.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If order matters between two pieces of data, use elements for them: attributes are inherently unordered.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data has, or might have, its own substructure, use it in an element: getting substructure into an
attribute is always messy. Similarly, if the data is a constituent part of some larger piece of data, put it
in an element.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
An exception to the previous rule: multiple whitespace-separated tokens can safely be put in an attribute.
In principle, the separator can be anything, but schema-language validators are currently only able to handle
whitespace, so it's best to stick with that.
</p>
<p>
<br>
</p>
</li>
<li>
<p>
If a piece of data extends across multiple lines, use an element: XML parsers will change newlines in attribute
values into spaces.
<br><br></p></li>
<li>If a piece of data is very large, use an element so that its content can be streamed.<br><br></li>
<li>
<p>
If a piece of data is in a natural language, put it in an element so you can use the <span
style="font-family: Courier New;">xml:lang</span> attribute to label the language being used. Some kinds
of natural-language text, like Japanese, often make use <a href="http://www.w3.org/TR/2001/REC-ruby-20010531"
id="pa2f" title="annotations">annotations</a> that are
conventionally represented using child elements; right-to-left languages like Hebrew and Arabic may similarly
require child elements to manage <a href="http://www.w3.org/TR/2001/REC-ruby-20010531" id="ehyv"
title="bidirectionality">bidirectionality</a> properly.
</p>
<p>
</p>
</li>
</ol>
<h3>
12.3 Using attributes<br>
</h3>
<ol>
<li>
<p>
If the data is a code from an enumeration, code list, or controlled vocabulary, put it in an attribute if
possible. For example, language tags, currency codes, medical diagnostic codes, etc. are best handled as
attributes.
</p>
<p>
<br>
</p>
</li>
<li>