XML Schema Authoring Guide
Keywords: xsd,xml,schema,c++,mapping,data,binding,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.