From a15cf65c44d5c224169c32ef5495b68c758134b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Sun, 18 May 2014 16:08:14 +0200 Subject: Imported Upstream version 3.3.0.2 --- xsd/documentation/schema-authoring-guide.xhtml | 187 +++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 xsd/documentation/schema-authoring-guide.xhtml (limited to 'xsd/documentation/schema-authoring-guide.xhtml') diff --git a/xsd/documentation/schema-authoring-guide.xhtml b/xsd/documentation/schema-authoring-guide.xhtml new file mode 100644 index 0000000..2eaab14 --- /dev/null +++ b/xsd/documentation/schema-authoring-guide.xhtml @@ -0,0 +1,187 @@ + + + + + + XML Schema Authoring Guide + + + + + + + + + + + + + +
+
+ +

Table of Contents

+ + + +

Introduction

+ +

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.

+ + +

Don't define a global element which is not + a valid document root

+ +

Instead of

+ + 
+<xsd:element name="author" type="Author"/>
+
+<xsd:complexType name="Book">
+  <xsd:sequence>
+    <xsd:element ref="author"/>
+  </xsd:sequence>
+</xsd:complexType>
+
+ +

Write

+ + 
+<xsd:complexType name="Book">
+  <xsd:sequence>
+    <xsd:element name="author" type="Author"/>
+  </xsd:sequence>
+</xsd:complexType>
+
+ +

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 + --root-element-* options to specify which global + element(s) are actual document root(s).

+ + + +

Don't name a type and an element/attribute of + this type with the same name

+ +

Instead of

+ + 
+<xsd:complexType name="name">
+  <xsd:sequence>
+    <xsd:element name="name" type="xsd:string"/>
+  </xsd:sequence>
+  <xsd:attribute name="lang" type="xsd:language"/>
+</xsd:complexType>
+
+ +

Write

+ + 
+<xsd:complexType name="Name">
+  <xsd:sequence>
+    <xsd:element name="name" type="xsd:string"/>
+  </xsd:sequence>
+  <xsd:attribute name="lang" type="xsd:language"/>
+</xsd:complexType>
+
+ +

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:

+ + 
+  class name
+  {
+  public:
+    string
+    name1 () const;
+
+    language
+    lang () const;
+
+    ...
+
+  };
+
+ +

Don't use xsd:integer and + friends

+ +

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

+ +

Use xsd:int/xsd:unsignedInt for 32 bit + integers

+ +

XML Schema built-in types long and + unsignedLong are 64 bit wide so use 32 bit int + and unsignedInt unless you meant 64 bit.

+ +
+ + +
+ + + + -- cgit v1.2.3