# 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 use anonymous types

Instead of

    <xsd:element name="author">
      <xsd:complexType>
        <xsd:sequence>
          <xsd:element name="first-name" type="xsd:string"/>
          <xsd:element name="last-name" type="xsd:string"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:element>

Write

    <xsd:complexType name="Author">
      <xsd:sequence>
        <xsd:element name="first-name" type="xsd:string"/>
        <xsd:element name="last-name" type="xsd:string"/>
      </xsd:sequence>
    </xsd:complexType>

    <xsd:element name="author" type="Author"/>

xsd maps XML Schema anonymous types to C++ nested classes. Sometimes this may result in excessive code duplication. If you cannot change your schema, consider using the `--morph-anonymous` option to automatically name anonymous types.

# 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.

# Don't name a type and a global element with the same name

Instead of

    <xsd:complexType name="author">
      ...
    </xsd:complexType>

    <xsd:element name="author" type="author"/>

Write

    <xsd:complexType name="author_type">
      ...
    </xsd:complexType>

    <xsd:element name="author" type="author_type"/>

For every globally-defined element xsd generates a set of parsing functions with the same name. If you have a type and a global element share a name, then you will have to use `class` specifier when you refer to the type, e.g., `auto_ptr<class author>`.

# 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.