Element Element Binding Support

The .NET Framework provides binding support for the <element> element.

Explanation

The XML Schema specification states that an element can be declared locally, within a complex type definition, or globally as a child of the root <schema> element. If the element is declared globally, it can be referenced from within one or more complex type definitions via the ref attribute.

The following code example shows an element declared locally:

<xsd:complexType name="UnitType">
  <xsd:sequence>
   <xsd:element name="name" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

The following code example shows the same element declared globally and then referenced:

<xsd:element name="name" type="xsd:string"/>
<xsd:complexType name="UnitType">
  <xsd:sequence>
    <xsd:element ref="name"/>
  </xsd:sequence>
</xsd:complexType>

When generating a .NET Framework type from an XML Schema complex type, Xsd.exe does not differentiate between a locally declared element and a reference to a globally declared element, unless the global element is declared in a namespace other than the schema's target namespace.

Reference within the same namespace

Because Xsd.exe does not differentiate within the same namespace, a round-trip translation from XML schema to classes and back creates local elements that replace any references to global elements.

If the referenced global element's data type already has an automatic binding to a .NET Framework type, Xsd.exe does not generate a new type corresponding to the data type. As a result, not only is the global element declaration no longer referenced in the XML schema generated on the round trip, but it no longer appears there either. See Creation of global element declarations.

Note
All built-in XML Schema data types have automatic bindings to .NET Framework types. In addition, schema-defined simple types, with one exception, bind to .NET Framework types rather than custom types. The single exception involves the enumeration of string-binding types; this exception is explained in more detail in the documentation for the <enumeration> element.

Note
For more information about support for built-in types, see Data Type Support between XML Schema (XSD) Types and .NET Framework Types. For more information about support for schema-defined simple types, see the <restriction> element or any of the elements representing restriction facets.

Reference to another namespace

If a referenced global declaration belongs to a different namespace, then Xsd.exe specifies the namespace using the Namespace property of an XmlElementAttribute attribute that is applied to the generated field. For that particular element, the namespace specified via the Namespace property overrides the namespace specified at the class level using the XmlTypeAttribute attribute and, optionally, the XmlRootAttribute. An example follows:

[System.Xml.Serialization.XmlElementAttribute(Namespace="http://example.org/elem")]
public string Text;

Additional namespaces are imported into an XML Schema definition using the <import> element.

Creation of global element declarations

When generating an XML Schema document from a set of classes in an assembly, Xsd.exe produces a global <element> declaration for every <complexType> or <simpleType> definition it produces from a type defined in the assembly.

Example

This first example shows how Xsd.exe processes a global element when that element is defined in the same target namespace that contains a reference to it.

Input XML Schema document:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      xmlns="http://example.org/" targetNamespace="http://example.org/" elementFormDefault="qualified">
  <xsd:element name="Text" type="xsd:normalizedString"/>
  <xsd:complexType name="Branch">
    <xsd:sequence>
      <xsd:element name="children" type="xsd:token" minOccurs="0" maxOccurs="unbounded" />
      <xsd:element ref="Text" />
    </xsd:sequence>
    <xsd:attribute name="key" type="xsd:token"/>
  </xsd:complexType>
  <xsd:element name="branch" type="Branch"/>
</xsd:schema>

C# class generated from the preceding XML Schema document:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("branch", Namespace="http://example.org/", IsNullable=false)]
public class Branch {
        
    [System.Xml.Serialization.XmlElementAttribute("children", DataType="token")]
    public string[] children;
        
    [System.Xml.Serialization.XmlElementAttribute(DataType="normalizedString")]
    public string Text;
        
    [System.Xml.Serialization.XmlAttributeAttribute(DataType="token")]
    public string key;
}

XML Schema document generated from an assembly compiled from the preceding C# source:

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="branch" type="tns:Branch" />
  <xs:complexType name="Branch">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="children" type="xs:token" />
      <xs:element minOccurs="0" maxOccurs="1" name="Text" type="xs:normalizedString" />
    </xs:sequence>
    <xs:attribute name="key" type="xs:token" />
  </xs:complexType>
</xs:schema>

In the preceding generated XML schema, the Text element, originally declared globally, has been made a local element.

This second example shows how Xsd.exe processes a reference to a global element when that element is defined in a separate namespace. This example uses the <import> element to import a second namespace located in a separate XSD file. (The <import> element's schemaLocation attribute is not used to specify the location of the imported .xsd file. Instead, for Xsd.exe, the file is specified as an additional command-line argument.)

The top-level XML Schema document used as an input:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"
      xmlns="http://example.org/" targetNamespace="http://example.org/" xmlns:elem="http://example.org/elem">
  <xsd:import  namespace="http://example.org/elem" />
  <xsd:complexType name="Branch">
    <xsd:sequence>
      <xsd:element name="children" type="xsd:token" minOccurs="0" maxOccurs="unbounded" />
      <xsd:element ref="elem:Text" />
    </xsd:sequence>
    <xsd:attribute name="key" type="xsd:token"/>
  </xsd:complexType>
  <xsd:element name="branch" type="Branch"/>
</xsd:schema>

The imported XML Schema document used as an input:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" 
      xmlns="http://example.org/elem" targetNamespace="http://example.org/elem">
  <xsd:element name="Text" type="xsd:normalizedString"/>
</xsd:schema>

C# class generated from the preceding two XML Schema documents:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("branch", Namespace="http://example.org/", IsNullable=false)]
public class Branch {
        
    [System.Xml.Serialization.XmlElementAttribute("children", DataType="token")]
    public string[] children;
        
    [System.Xml.Serialization.XmlElementAttribute(Namespace="http://example.org/elem", DataType="normalizedString")]
    public string Text;
        
    [System.Xml.Serialization.XmlAttributeAttribute(DataType="token")]
    public string key;
}

Top-level XML Schema document generated from an assembly compiled from the preceding C# source:

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:import namespace="http://example.org/elem" />
  <xs:element name="branch" type="tns:Branch" />
  <xs:complexType name="Branch">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="children" type="xs:token" />
      <xs:element minOccurs="0" maxOccurs="1" xmlns:q1="http://example.org/elem" ref="q1:Text" />
    </xs:sequence>
    <xs:attribute name="key" type="xs:token" />
  </xs:complexType>
</xs:schema>

Imported XML Schema document generated from an assembly compiled from the preceding C# source:

<xs:schema xmlns:tns="http://example.org/elem" elementFormDefault="qualified" targetNamespace="http://example.org/elem" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="Text" type="xs:normalizedString" />
</xs:schema>

Abstract Attribute

A global element declaration can have an abstract attribute; a local element cannot.

Declare an element abstract (abstract="true") to force its substitution via a substitution group; if the element is not abstract, the substitution is optional.

The global element being substituted is called the head element. Wherever a local element declaration refers to the head element via the ref attribute, you can use any global substitute elements in its place. For more information, see the substitutionGroup attribute.

If the substitute elements belong to derived data types and if the head element itself is declared abstract (rather than the <complexType> definition for its type being declared abstract), you can use the base type elsewhere in an XML instance document, even though you cannot use it in the position where the substitution takes place.

When generating source code from an XML Schema document, Xsd.exe produces a type corresponding to the head element's data type. The type includes a field named Item. Xsd.exe applies to that field one XmlElementAttribute for each of the substitutes. Each attribute identifies the name and, if the substitute element has a derived data type, the type. If the substitute elements use the same data type as the head, an XmlChoiceIdentifierAttribute must also be applied. For more information, see the <choice> element.

The following code example shows a sample field, Item, generated from a reference to an abstract head element, :

[System.Xml.Serialization.XmlElementAttribute("derivedAInstance", typeof(DerivedTypeA))]
[System.Xml.Serialization.XmlElementAttribute("derivedBInstance", typeof(DerivedTypeB))]
public MyBaseType Item;

If you are using substitute elements that belong to derived data types, XML serialization only works when an instance of one of the derived types has been assigned to the field. The XmlSerializer class fails if an instance of the base type corresponding to the head element has been assigned.

On a reverse translation, Xsd.exe produces a <choice> element containing an <element> element for each of the substitute elements, and no <element> representing the head element. The elements are independently defined within the complex type definition; no ref references are employed.

Note
In a local <element> declaration containing a ref attribute specifying an abstract head element, Xsd.exe ignores the maxOccurs attribute.

Note
Consider the following declaration to a head element of type MyBaseType:

Note
<xsd:element ref="baseInstance" minOccurs="0" maxOccurs="unbounded" />

Note
For the preceding declaration, Xsd.exe still produces the following field (attributes omitted):

Note
public MyBaseType Item;

Note
Xsd.exe fails to generate classes if all globally declared elements in the input XML schema are abstract.

Example: Abstract Attribute

Input XML Schema document:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      targetNamespace="http://example.org/" xmlns="http://example.org/" elementFormDefault="qualified">
  <xsd:element name="baseInstance" type="MyBaseType" abstract="true"/>

  <xsd:complexType name="MyBaseType">
    <xsd:sequence>
      <xsd:element name="Field1" type="xsd:string"/>
      <xsd:element name="Field2" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="derivedAInstance" type="DerivedTypeA" substitutionGroup="baseInstance" />
  <xsd:complexType name="DerivedTypeA">
    <xsd:complexContent>
      <xsd:extension base="MyBaseType">
         <xsd:attribute name="ExtraInfoForA" type="xsd:string"/>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>

  <xsd:element name="derivedBInstance" type="DerivedTypeB" substitutionGroup="baseInstance" />
  <xsd:complexType name="DerivedTypeB">
    <xsd:complexContent>
      <xsd:extension base="MyBaseType">
         <xsd:attribute name="ExtraInfoForB" type="xsd:string"/>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>

  <xsd:element name="myThings" type="MyThingsType" />
  <xsd:complexType name="MyThingsType">
    <xsd:sequence>
      <xsd:element ref="baseInstance" />
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

C# classes generated from the preceding XML Schema document:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("derivedAInstance", Namespace="http://example.org/", IsNullable=false)]
public class DerivedTypeA : MyBaseType {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string ExtraInfoForA;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlIncludeAttribute(typeof(DerivedTypeA))]
[System.Xml.Serialization.XmlIncludeAttribute(typeof(DerivedTypeB))]
public class MyBaseType {
    public string Field1;
        
    public string Field2;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("derivedBInstance", Namespace="http://example.org/", IsNullable=false)]
public class DerivedTypeB : MyBaseType {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string ExtraInfoForB;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("myThings", Namespace="http://example.org/", IsNullable=false)]
public class MyThingsType {       
    [System.Xml.Serialization.XmlElementAttribute("derivedAInstance", typeof(DerivedTypeA))]
    [System.Xml.Serialization.XmlElementAttribute("derivedBInstance", typeof(DerivedTypeB))]
    public MyBaseType Item;
}

XML Schema document generated from an assembly compiled from the preceding C# source:

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexType name="MyBaseType">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="1" name="Field1" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Field2" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="DerivedTypeA">
    <xs:complexContent mixed="false">
      <xs:extension base="tns:MyBaseType">
        <xs:attribute name="ExtraInfoForA" type="xs:string" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="DerivedTypeB">
    <xs:complexContent mixed="false">
      <xs:extension base="tns:MyBaseType">
        <xs:attribute name="ExtraInfoForB" type="xs:string" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="derivedAInstance" type="tns:DerivedTypeA" />
  <xs:element name="derivedBInstance" type="tns:DerivedTypeB" />
  <xs:element name="myThings" type="tns:MyThingsType" />
  <xs:complexType name="MyThingsType">
    <xs:sequence>
      <xs:choice minOccurs="1" maxOccurs="1">
        <xs:element minOccurs="0" maxOccurs="1" name="derivedAInstance" type="tns:DerivedTypeA" />
        <xs:element minOccurs="0" maxOccurs="1" name="derivedBInstance" type="tns:DerivedTypeB" />
      </xs:choice>
    </xs:sequence>
  </xs:complexType>
</xs:schema> 

SubstitutionGroup Attribute

The Xsd.exe tool only recognizes substitution groups if the substituted element is declared abstract. (See the preceding section, Abstract Attribute.) Then, on a reverse translation, Xsd.exe produces a <choice> element containing an <element> element for each of the substitutes.

SubstitutionGroup Attribute: Background

The substitutionGroup attribute can appear with a globally declared element to allow it to take the place of another globally declared element in an XML instance document. The attribute value is the name of the element being substituted, called the head. The actual substitution can take place in an <element> element within a complex type definition, where the head element is referred to via the ref attribute. Any elements declared with the substitutionGroup attribute must belong to the same data type as the head element, or a derived type.

A substitution group is used to allow elements of different names, and optionally different types with the same base type, to appear in a specified position in an instance document.

Nested substitution groups are not supported. That is, if an element acts as the head element in one substitution group, it cannot be the substituted element in another substitution group. For example:

<xs:element name="Animal" abstract="true"/>
<xs:element name="Mammal" abstract="true" 
    substitutionGroup="tns:Animal"/>
<xs:element name="Dog" type="xs:string" 
    substitutionGroup="tns:Mammal"/>

This is not supported because Mammal acts as both the head (for Dog) and a substituted element (for Animal). If such a schema is encountered, Xsd.exe will not generate an XmlElementAttribute for Mammal, and Dog will not be where the Animal element is expected. However, you can manually add this to make this case work, as shown in the following example:

public class PetShop 
{
    private object Animal;
    
    // Apply the XmlElementAttribute to the generated property.
    [System.Xml.Serialization.XmlElementAttribute("Mammal"), 
     System.Xml.Serialization.XmlElementAttribute("Dog")]
    public object Animal {
        get {
            return this.Animal;
        }
        set {
            this.Animal = value;
        }
    }
}

SubstitutionGroup Attribute: Concrete head element

If the head element is not abstract, Xsd.exe takes each ref reference to the head and creates a field of the type corresponding to the head's XML data type (or an array of that type, depending on the value of the referring element's maxOccurs attribute). Any reference to the substitution group is lost.

While an object of a derived type could be assigned to that field and the XmlSerializer class would serialize that object, that behavior takes place outside of substitution with derived types. No substitute element name is used.

SubstitutionGroup Attribute: Abstract head element

If the head element is abstract, Xsd.exe produces a field of a type corresponding to the head's data type. The field receives the name Item. Xsd.exe applies to that field one XmlElementAttribute for each of the substitutes. Each attribute identifies the name and, if the substitute element has a derived data type, the type. If the substitute elements use the same data type as the head, an XmlChoiceIdentifierAttribute must also be applied. See the <choice> element.

Following is a sample field generated from a reference to an abstract head element:

[System.Xml.Serialization.XmlElementAttribute("derivedAInstance", typeof(DerivedTypeA))]
[System.Xml.Serialization.XmlElementAttribute("derivedBInstance", typeof(DerivedTypeB))]
public MyBaseType Item;

If derived types are being used, XML serialization only works when an instance of one of the derived types has been assigned to the field. XmlSerializer fails if an instance of the base type corresponding to the head element has been assigned.

On a reverse translation, Xsd.exe produces from this construct a <choice> element containing an <element> element for each of the substitute elements, not for the head element. The elements are independently defined within the complex type definition; no ref references are employed.

maxOccurs attribute. For a local <element> declaration containing a ref attribute specifying an abstract head element, Xsd.exe ignores the maxOccurs attribute.

Consider the following declaration that refers to a head element of type MyBaseType:

<xsd:element ref="baseInstance" minOccurs="0" maxOccurs="unbounded" />

For the preceding declaration, Xsd.exe still produces the following field (attributes omitted):

public MyBaseType Item;

Example: SubstitutionGroup Attribute

Input XML Schema document:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
      targetNamespace="http://example.org/" xmlns="http://example.org/" elementFormDefault="qualified">
  <xsd:element name="baseInstance" type="MyBaseType" abstract="true"/>

  <xsd:complexType name="MyBaseType">
    <xsd:sequence>
      <xsd:element name="Field1" type="xsd:string"/>
      <xsd:element name="Field2" type="xsd:string"/>
    </xsd:sequence>
  </xsd:complexType>

  <xsd:element name="derivedAInstance" type="DerivedTypeA" substitutionGroup="baseInstance" />
  <xsd:complexType name="DerivedTypeA">
    <xsd:complexContent>
      <xsd:extension base="MyBaseType">
         <xsd:attribute name="ExtraInfoForA" type="xsd:string"/>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>

  <xsd:element name="derivedBInstance" type="DerivedTypeB" substitutionGroup="baseInstance" />
  <xsd:complexType name="DerivedTypeB">
    <xsd:complexContent>
      <xsd:extension base="MyBaseType">
         <xsd:attribute name="ExtraInfoForB" type="xsd:string"/>
      </xsd:extension>
    </xsd:complexContent>
  </xsd:complexType>

  <xsd:element name="myThings" type="MyThingsType" />
  <xsd:complexType name="MyThingsType">
    <xsd:sequence>
      <xsd:element ref="baseInstance" />
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

C# classes generated from the preceding XML Schema document:

[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("derivedAInstance", Namespace="http://example.org/", IsNullable=false)]
public class DerivedTypeA : MyBaseType {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string ExtraInfoForA;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlIncludeAttribute(typeof(DerivedTypeA))]
[System.Xml.Serialization.XmlIncludeAttribute(typeof(DerivedTypeB))]
public class MyBaseType {
    public string Field1;
        
    public string Field2;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("derivedBInstance", Namespace="http://example.org/", IsNullable=false)]
public class DerivedTypeB : MyBaseType {
        
    [System.Xml.Serialization.XmlAttributeAttribute()]
    public string ExtraInfoForB;
}
    
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://example.org/")]
[System.Xml.Serialization.XmlRootAttribute("myThings", Namespace="http://example.org/", IsNullable=false)]
public class MyThingsType {       
    [System.Xml.Serialization.XmlElementAttribute("derivedAInstance", typeof(DerivedTypeA))]
    [System.Xml.Serialization.XmlElementAttribute("derivedBInstance", typeof(DerivedTypeB))]
    public MyBaseType Item;
}

XML Schema document generated from an assembly compiled from the preceding C# source:

<xs:schema xmlns:tns="http://example.org/" elementFormDefault="qualified" targetNamespace="http://example.org/" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:complexType name="MyBaseType">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="1" name="Field1" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Field2" type="xs:string" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="DerivedTypeA">
    <xs:complexContent mixed="false">
      <xs:extension base="tns:MyBaseType">
        <xs:attribute name="ExtraInfoForA" type="xs:string" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:complexType name="DerivedTypeB">
    <xs:complexContent mixed="false">
      <xs:extension base="tns:MyBaseType">
        <xs:attribute name="ExtraInfoForB" type="xs:string" />
      </xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="derivedAInstance" type="tns:DerivedTypeA" />
  <xs:element name="derivedBInstance" type="tns:DerivedTypeB" />
  <xs:element name="myThings" type="tns:MyThingsType" />
  <xs:complexType name="MyThingsType">
    <xs:sequence>
      <xs:choice minOccurs="1" maxOccurs="1">
        <xs:element minOccurs="0" maxOccurs="1" name="derivedAInstance" type="tns:DerivedTypeA" />
        <xs:element minOccurs="0" maxOccurs="1" name="derivedBInstance" type="tns:DerivedTypeB" />
      </xs:choice>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

[System.ComponentModel.DefaultValueAttribute(-1)]
public int age = -1;

public int age = -1;

Possible parent elements: <all>, <choice>, <schema>, <sequence>

Possible child elements: <annotation>, <complexType>, <key>, <keyref>, <simpleType>, <unique>

See Also

Reference

XmlSchemaElement