summaryrefslogtreecommitdiff
path: root/documentation/schema-authoring-guide.xhtml
blob: 69a808214132c49f82625996da043c6821e4f873 (plain)
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
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">

<head>
  <title>XML Schema Authoring Guide</title>

  <meta name="copyright" content="&copy; 2005-2011 Code Synthesis Tools CC"/>
  <meta name="keywords" content="xsd,xml,schema,c++,mapping,data,binding,authoring,guide"/>
  <meta name="description" content="XML Schema Authoring Guide"/>

  <link rel="stylesheet" type="text/css" href="default.css" />

<style type="text/css">
  pre {
    background : #cde8f6;

    padding    : 0 0 0 1em;
    margin     : 2em 0em 2em 0;

    font-size  : 95%
  }

  body {
    min-width: 46em;
  }

  ul.toc li {
    padding    : .4em 0em 0em 0em;
    list-style : none;
  }

</style>


</head>

<body>
<div id="container">
  <div id="content">

  <h1>Table of Contents</h1>

  <ul class="toc">
    <li>1. <a href="#intro">Introduction</a></li>

    <li>2. <a href="#global_element">Don't define a global element which
        is not a valid document root</a></li>

    <li>3. <a href="#same_local">Don't name a type and an element/attribute
        of this type with the same name</a></li>

    <li>3. <a href="#integer">Don't use <code>xsd:integer</code> and
        friends</a></li>

    <li>4. <a href="#int">Use <code>xsd:int/xsd:unsignedInt</code> for 32 bit
        integers</a></li>
  </ul>

  <h1><a name="intro">Introduction</a></h1>

  <p>Making it possible to cleanly map W3C XML Schema to programming languages
     was never a goal of the XML Schema Working Group. As a result there
     is a number of Schema constructs, techniques, and styles that don't
     have appropriate counterparts in C++. This document presents a list
     of do's and don'ts that will help ensure your schemas, when translated
     by XSD, result in C++ code that is enjoyable to work with.</p>


  <h1><a name="global_element">Don't define a global element which is not
      a valid document root</a></h1>

  <p>Instead of</p>

  <pre>
&lt;xsd:element name="author" type="Author"/>

&lt;xsd:complexType name="Book">
  &lt;xsd:sequence>
    &lt;xsd:element ref="author"/>
  &lt;/xsd:sequence>
&lt;/xsd:complexType>
  </pre>

  <p>Write</p>

  <pre>
&lt;xsd:complexType name="Book">
  &lt;xsd:sequence>
    &lt;xsd:element name="author" type="Author"/>
  &lt;/xsd:sequence>
&lt;/xsd:complexType>
  </pre>

  <p>Any globally-defined element is a potential document root. For every
     such element XSD generates a set of overloaded parsing
     functions. If you cannot change your schema, consider using the
     <code>--root-element-*</code> options to specify which global
     element(s) are actual document root(s).</p>



  <h1><a name="same_local">Don't name a type and an element/attribute of
      this type with the same name</a></h1>

  <p>Instead of</p>

  <pre>
&lt;xsd:complexType name="name">
  &lt;xsd:sequence>
    &lt;xsd:element name="name" type="xsd:string"/>
  &lt;/xsd:sequence>
  &lt;xsd:attribute name="lang" type="xsd:language"/>
&lt;/xsd:complexType>
  </pre>

  <p>Write</p>

  <pre>
&lt;xsd:complexType name="Name">
  &lt;xsd:sequence>
    &lt;xsd:element name="name" type="xsd:string"/>
  &lt;/xsd:sequence>
  &lt;xsd:attribute name="lang" type="xsd:language"/>
&lt;/xsd:complexType>
  </pre>

  <p>Use of a class name as a member function name within this class is
     illegal in C++. XSD will resolve such conflicts by renaming
     the conflicting member function. In the example above, you will end
     up with the following generated code:</p>

  <pre>
  class name
  {
  public:
    string
    name1 () const;

    language
    lang () const;

    ...

  };
  </pre>

  <h1><a name="integer">Don't use <code>xsd:integer</code> and
      friends</a></h1>

  <p>XML Schema built-in types <code>integer</code>,
     <code>nonPositiveInteger</code>, <code>nonNegativeInteger</code>,
     <code>positiveInteger</code>, and <code>negativeInteger</code>
     are arbitrary-length integral types. XSD maps them to the
     <code>long long</code> and <code>unsigned long long</code> C++
     types. In most cases you would prefer to use either
     <code>xsd:int/xsd:unsignedInt</code> (32 bit, maps to C++
     <code>int/unsigned int</code>) or
     <code>xsd:long/xsd:unsignedLong</code> (64 bit, maps to C++
     <code>long long/unsigned long long</code>).
     </p>

  <h1><a name="int">Use <code>xsd:int/xsd:unsignedInt</code> for 32 bit
      integers</a></h1>

  <p>XML Schema built-in types <code>long</code> and
     <code>unsignedLong</code> are 64 bit wide so use 32 bit <code>int</code>
     and <code>unsignedInt</code> unless you meant 64 bit.</p>

  </div>
  <div id="footer">
    &copy;2005-2011 <a href="http://codesynthesis.com">CODE SYNTHESIS TOOLS CC</a>

    <div id="terms">
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the
      <a href="http://codesynthesis.com/licenses/fdl-1.2.txt">GNU Free
      Documentation License, version 1.2</a>; with no Invariant Sections,
      no Front-Cover Texts and no Back-Cover Texts.
    </div>
  </div>

</div>


</body>
</html>