Data Contract Schema Reference

This topic describes the subset of the XML Schema (XSD) used by DataContractSerializer to describe common language runtime (CLR) types for XML serialization.

DataContractSerializer Mappings

The DataContractSerializer maps CLR types to XSD when metadata is exported from a Windows Communication Foundation (WCF) service using a metadata endpoint or the ServiceModel Metadata Utility Tool (Svcutil.exe). For more information, see Data Contract Serializer.

The DataContractSerializer also maps XSD to CLR types when Svcutil.exe is used to access Web Services Description Language (WSDL) or XSD documents and generate data contracts for services or clients.

Only XML Schema instances that conform to requirements stated in this document can be mapped to CLR types using DataContractSerializer.

Support Levels

The DataContractSerializer provides the following levels of support for a given XML Schema feature:

• Supported. There is explicit mapping from this feature to CLR types or attributes (or both) using DataContractSerializer.

• Ignored. The feature is allowed in schemas imported by the DataContractSerializer, but has no effect on code generation.

• Forbidden. The DataContractSerializer does not support importing a schema using the feature. For example, Svcutil.exe, when accessing a WSDL with a schema that uses such a feature, falls back to using the XmlSerializer instead. This is by default.

General Information

• The schema namespace is described at XML Schema. The prefix "xs" is used in this document.

• Any attributes with a non-schema namespace are ignored.

• Any annotations (except for those described in this document) are ignored.

<xs:schema>: attributes

<xs:schema>: contents

Complex Types – <xs:complexType>

General Information

Each complex type <xs:complexType> maps to a data contract.

<xs:complexType>: attributes

<xs:complexType>: contents

<xs:sequence> in a complex type: attributes

<xs:sequence> in a complex type: contents

Elements – <xs:element>

General Information

<xs:element> can occur in the following contexts:

• It can occur within an <xs:sequence>, which describes a data member of a regular (non-collection) data contract. In this case, the maxOccurs attribute must be 1. (A value of 0 is not allowed).

• It can occur within an <xs:sequence>, which describes a data member of a collection data contract. In this case, the maxOccurs attribute must be greater than 1 or "unbounded".

• It can occur within an <xs:schema> as a Global Element Declaration (GED).

<xs:element> with maxOccurs=1 within an <xs:sequence> (Data Members)

<xs:element> with maxOccurs>1 within an <xs:sequence> (Collections)

• Maps to a CollectionDataContractAttribute.

• In collection types, only one xs:element is allowed within an xs:sequence.

Collections can be of the following types:

• Regular collections (for example, arrays).

• Dictionary collections (mapping one value to another; for example, a Hashtable).

• The only difference between a dictionary and an array of a key/value pair type is in the generated programming model. There is a schema annotation mechanism that can be used to indicate that a given type is a dictionary collection.

The rules for the ref, block, default, fixed, form, and id attributes are the same as for the non-collection case. Other attributes include those in the following table.

<xs:element> within an <xs:schema> Global Element Declaration

• A Global Element Declaration (GED) that has the same name and namespace as a type in schema, or that defines an anonymous type inside itself, is said to be associated with the type.

• Schema export: associated GEDs are generated for every generated type, both simple and complex.

• Deserialization/serialization: associated GEDs are used as root elements for the type.

• Schema import: associated GEDs are not required and are ignored if they follow the following rules (unless they define types).

<xs:element>: contents

* When using the simpleType and complexType, mapping for anonymous types is the same as for non-anonymous types, except that there is no anonymous data contracts, and so a named data contract is created, with a generated name derived from the element name. The rules for anonymous types are in the following list:

• WCF implementation detail: If the xs:element name does not contain periods, the anonymous type maps to an inner type of the outer data contract type. If the name contains periods, the resulting data contract type is independent (not an inner type).

• The generated data contract name of the inner type is the data contract name of the outer type followed by a period, the name of the element, and the string "Type".

• If a data contract with such a name already exists, the name is made unique by appending "1", "2", "3", and so on until a unique name is created.

Simple Types - <xs:simpleType>

<xs:simpleType>: attributes

<xs:simpleType>: contents

<xs:restriction>

• Complex type restrictions are supported only for base="xs:anyType".

• Simple type restrictions of xs:string that do not have any restriction facets other than xs:enumeration are mapped to enumeration data contracts.

• All other simple type restrictions are mapped to the types they restrict. For example, a restriction of xs:int maps to an integer, just as xs:int itself does. For more information about primitive type mapping, see Type/primitive mapping.

<xs:restriction>: attributes

<xs:restriction> for all other cases: contents

Enumeration

<xs:restriction> for enumerations: attributes

<xs:restriction> for enumerations: contents

The following code shows a C# enumeration class.

public enum MyEnum
{
  first = 3,
  second = 4,
  third =5
}

This class maps to the following schema by the DataContractSerializer. If enumeration values start from 1, xs:annotation blocks are not generated.

<xs:simpleType name="MyEnum">
  <xs:restriction base="xs:string">
    <xs:enumeration value="first">
      <xs:annotation>
        <xs:appinfo>
          <EnumerationValue xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
          3
          </EnumerationValue>
        </xs:appinfo>
      </xs:annotation>
    </xs:enumeration>
    <xs:enumeration value="second">
      <xs:annotation>
        <xs:appinfo>
          <EnumerationValue xmlns="http://schemas.microsoft.com/2003/10/Serialization/">
          4
          </EnumerationValue>
        </xs:appinfo>
      </xs:annotation>
    </xs:enumeration>
  </xs:restriction>
</xs:simpleType>

<xs:list>

DataContractSerializer maps enumeration types marked with System.FlagsAttribute to xs:list derived from xs:string. No other xs:list variations are supported.

<xs:list>: attributes

<xs:list>: contents

If enumeration value does not follow a power of 2 progression (default for Flags), the value is stored in the xs:annotation/xs:appInfo/ser:EnumerationValue element.

For example, the following code flags an enumeration type.

[Flags]
public enum AuthFlags
{
  AuthAnonymous = 1,
  AuthBasic = 2,
  AuthNTLM = 4,
  AuthMD5 = 16,
  AuthWindowsLiveID = 64,
}

This type maps to the following schema.

<xs:simpleType name="AuthFlags">
    <xs:list>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="AuthAnonymous" />
          <xs:enumeration value="AuthBasic" />
          <xs:enumeration value="AuthNTLM" />
          <xs:enumeration value="AuthMD5">
            <xs:annotation>
              <xs:appinfo>
                <EnumerationValue xmlns="http://schemas.microsoft.com/2003/10/Serialization/">16</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
          <xs:enumeration value="AuthWindowsLiveID">
            <xs:annotation>
              <xs:appinfo>
                <EnumerationValue xmlns="http://schemas.microsoft.com/2003/10/Serialization/">64</EnumerationValue>
              </xs:appinfo>
            </xs:annotation>
          </xs:enumeration>
        </xs:restriction>
      </xs:simpleType>
    </xs:list>
  </xs:simpleType>

Inheritance

General rules

A data contract can inherit from another data contract. Such data contracts map to a base and are derived by extension types using the <xs:extension> XML Schema construct.

A data contract cannot inherit from a collection data contract.

For example, the following code is a data contract.

[DataContract]
public class Person
{
  [DataMember]
  public string Name;
}
[DataContract]
public class Employee : Person
{
  [DataMember]
  public int ID;
}

This data contract maps to the following XML Schema type declaration.

<xs:complexType name="Employee">
 <xs:complexContent mixed="false">
  <xs:extension base="tns:Person">
   <xs:sequence>
    <xs:element minOccurs="0" name="ID" type="xs:int"/>
   </xs:sequence>
  </xs:extension>
 </xs:complexContent>
</xs:complexType>
<xs:complexType name="Person">
 <xs:sequence>
  <xs:element minOccurs="0" name="Name"
    nillable="true" type="xs:string"/>
 </xs:sequence>
</xs:complexType>

<xs:complexContent>: attributes

<xs:complexContent>: contents

<xs:extension> in <xs:complexContent>: attributes

<xs:extension> in <xs:complexContent>: contents

The rules are the same as for <xs:complexType> contents.

If an <xs:sequence> is provided, its member elements map to additional data members that are present in the derived data contract.

If a derived type contains an element with the same name as an element in a base type, the duplicate element declaration maps to a data member with a name that is generated to be unique. Positive integer numbers are added to the data member name ("member1", "member2", and so on) until a unique name is found. Conversely:

• If a derived data contract has a data member with the same name and type as a data member in a base data contract, DataContractSerializer generates this corresponding element in the derived type.

• If a derived data contract has a data member with the same name as a data member in a base data contract but a different type, the DataContractSerializer imports a schema with an element of the type xs:anyType in both base type and derived type declarations. The original type name is preserved in xs:annotations/xs:appInfo/ser:ActualType/@Name.

Both variations may lead to a schema with an ambiguous content model, which depends on the order of the respective data members.

Type/primitive mapping

The DataContractSerializer uses the following mapping for XML Schema primitive types.

ISerializable types mapping

In .NET Framework version 1.0, ISerializable was introduced as a general mechanism to serialize objects for persistence or data transfer. There are many .NET Framework types that implement ISerializable and that can be passed between applications. DataContractSerializer naturally provides support for ISerializable classes. The DataContractSerializer maps ISerializable implementation schema types that differ only by the QName (qualified name) of the type and are effectively property collections. For example, the DataContractSerializer maps Exception to the following XSD type in the http://schemas.datacontract.org/2004/07/System namespace.

<xs:complexType name="Exception">
 <xs:sequence>
  <xs:any minOccurs="0" maxOccurs="unbounded"
      namespace="##local" processContents="skip"/>
 </xs:sequence>
 <xs:attribute ref="ser:FactoryType"/>
</xs:complexType>

The optional attribute ser:FactoryType declared in the Data Contract Serialization schema references a factory class that can deserialize the type. The factory class must be part of the known types collection of the DataContractSerializer instance being used. For more information about known types, see Data Contract Known Types.

DataContract Serialization Schema

A number of schemas exported by the DataContractSerializer use types, elements, and attributes from a special Data Contract Serialization namespace:

http://schemas.microsoft.com/2003/10/Serialization

The following is a complete Data Contract Serialization schema declaration.

<xs:schema attributeFormDefault="qualified"
   elementFormDefault="qualified"
   targetNamespace =
    "http://schemas.microsoft.com/2003/10/Serialization/"
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:tns="http://schemas.microsoft.com/2003/10/Serialization/">

 <!-- Top-level elements for primitive types. -->
 <xs:element name="anyType" nillable="true" type="xs:anyType"/>
 <xs:element name="anyURI" nillable="true" type="xs:anyURI"/>
 <xs:element name="base64Binary"
       nillable="true" type="xs:base64Binary"/>
 <xs:element name="boolean" nillable="true" type="xs:boolean"/>
 <xs:element name="byte" nillable="true" type="xs:byte"/>
 <xs:element name="dateTime" nillable="true" type="xs:dateTime"/>
 <xs:element name="decimal" nillable="true" type="xs:decimal"/>
 <xs:element name="double" nillable="true" type="xs:double"/>
 <xs:element name="float" nillable="true" type="xs:float"/>
 <xs:element name="int" nillable="true" type="xs:int"/>
 <xs:element name="long" nillable="true" type="xs:long"/>
 <xs:element name="QName" nillable="true" type="xs:QName"/>
 <xs:element name="short" nillable="true" type="xs:short"/>
 <xs:element name="string" nillable="true" type="xs:string"/>
 <xs:element name="unsignedByte"
       nillable="true" type="xs:unsignedByte"/>
 <xs:element name="unsignedInt"
       nillable="true" type="xs:unsignedInt"/>
 <xs:element name="unsignedLong"
       nillable="true" type="xs:unsignedLong"/>
 <xs:element name="unsignedShort"
       nillable="true" type="xs:unsignedShort"/>

 <!-- Primitive types introduced for certain .NET simple types. -->
 <xs:element name="char" nillable="true" type="tns:char"/>
 <xs:simpleType name="char">
  <xs:restriction base="xs:int"/>
 </xs:simpleType>

 <!-- xs:duration is restricted to an ordered value space,
    to map to System.TimeSpan -->
 <xs:element name="duration" nillable="true" type="tns:duration"/>
 <xs:simpleType name="duration">
  <xs:restriction base="xs:duration">
   <xs:pattern
     value="\-?P(\d*D)?(T(\d*H)?(\d*M)?(\d*(\.\d*)?S)?)?"/>
   <xs:minInclusive value="-P10675199DT2H48M5.4775808S"/>
   <xs:maxInclusive value="P10675199DT2H48M5.4775807S"/>
  </xs:restriction>
 </xs:simpleType>

 <xs:element name="guid" nillable="true" type="tns:guid"/>
 <xs:simpleType name="guid">
  <xs:restriction base="xs:string">
   <xs:pattern value="[\da-fA-F]{8}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{4}-[\da-fA-F]{12}"/>
  </xs:restriction>
 </xs:simpleType>

 <!-- This is used for schemas exported from ISerializable type. -->
 <xs:attribute name="FactoryType" type="xs:QName"/>
</xs:schema>

The following should be noted:

• ser:char is introduced to represent Unicode characters of type Char.

• The valuespace of xs:duration is reduced to an ordered set so that it can be mapped to a TimeSpan.

• FactoryType is used in schemas exported from types that are derived from ISerializable.

Importing non-DataContract schemas

DataContractSerializer has the ImportXmlTypes option to allow import of schemas that do not conform to the DataContractSerializer XSD profile (see the Options property). Setting this option to true enables acceptance of non-conforming schema types and mapping them to the following implementation, IXmlSerializable wrapping an array of XmlNode (only the class name differs).

[GeneratedCodeAttribute("System.Runtime.Serialization", "3.0.0.0")]
[System.Xml.Serialization.XmlSchemaProviderAttribute("ExportSchema")]
[System.Xml.Serialization.XmlRootAttribute(IsNullable=false)]
public partial class Person : object, IXmlSerializable
{
  private XmlNode[] nodesField;
  private static XmlQualifiedName typeName =
new XmlQualifiedName("Person","http://Microsoft.ServiceModel.Samples");
  public XmlNode[] Nodes
  {
    get {return this.nodesField;}
    set {this.nodesField = value;}
  }
  public void ReadXml(XmlReader reader)
  {
    this.nodesField = XmlSerializableServices.ReadNodes(reader);
  }
  public void WriteXml(XmlWriter writer)
  {
    XmlSerializableServices.WriteNodes(writer, this.Nodes);
  }
  public System.Xml.Schema.XmlSchema GetSchema()
  {
    return null;
  }
  public static XmlQualifiedName ExportSchema(XmlSchemaSet schemas)
  {
    XmlSerializableServices.AddDefaultSchema(schemas, typeName);
    return typeName;
  }
}

DateTimeOffset Serialization

The DateTimeOffset is not treated as a primitive type. Instead, it is serialized as a complex element with two parts. The first part represents the date time, and the second part represents the offset from the date time. An example of a serialized DateTimeOffset value is shown in the following code.

<OffSet xmlns:a="http://schemas.datacontract.org/2004/07/System">
  <DateTime i:type="b:dateTime" xmlns=""
    xmlns:b="http://www.w3.org/2001/XMLSchema">2008-08-28T08:00:00
  </DateTime>
  <OffsetMinutes i:type="b:short" xmlns=""
   xmlns:b="http://www.w3.org/2001/XMLSchema">-480
   </OffsetMinutes>
</OffSet>

The schema is as follows.

<xs:schema targetNamespace="http://schemas.datacontract.org/2004/07/System">
   <xs:complexType name="DateTimeOffset">
      <xs:sequence minOccurs="1" maxOccurs="1">
         <xs:element name="DateTime" type="xs:dateTime"
         minOccurs="1" maxOccurs="1" />
         <xs:element name="OffsetMinutes" type="xs:short"
         minOccurs="1" maxOccurs="1" />
      </xs:sequence>
   </xs:complexType>
</xs:schema>

See also

• DataContractSerializer
• DataContractAttribute
• DataMemberAttribute
• XsdDataContractImporter
• Using Data Contracts