element

Declares an element.

<element
  abstract = Boolean : false
  block = (#all | List of (extension | restriction | substitution))
  default = string
  final = (#all | List of (extension | restriction))
  fixed = string
  form = (qualified | unqualified)
  id = ID
  maxOccurs = (nonNegativeInteger | unbounded) : 1
  minOccurs = nonNegativeInteger : 1
  name = NCName
  nillable = Boolean : false
  ref = QName
  substitutionGroup = QName
  type = QName
  {any attributes with non-schema Namespace}…>
Content: (annotation?, ((simpleType | complexType)?, (unique | key | 
keyref)*))
</element>

Attributes

abstract

An indicator of whether the element can be used in an instance document. If this value is true, the element cannot appear in the instance document. Instead, another element whose substitutionGroup attribute contains the qualified name (QName) of this element must appear in this element's place. More than one element can reference this element in its substitutionGroup attribute.

The default is false.

Optional.

block

The type of derivation. The block attribute prevents an element that has the specified type of derivation from being used in place of this element. This value can contain #all or a list that is a subset of extension, restriction, or substitution.

extension	Prevents elements derived by extension from being used in place of this element.
restriction	Prevents elements derived by restriction from being used in place of this element.
substitution	Prevents elements derived by substitution from being used in place of this element.
#all	Prevents all derived elements from being used in place of this element.

Optional.

default

The default value of the element if its content is a simple type or its content is textOnly.

The fixed and default attributes are mutually exclusive.

If the element contains a simple type, this value must be a valid value of that type.

Optional.

substitutionGroup

The name of an element for which this element can be substituted. This element must have the same type or a type derived from the type of the specified element.

This attribute can be used on any element if the referring element is declared at the global level (parent is <schema> element).

This value must be a QName.

Optional.

final

The type of derivation. The final attribute sets the default value of the final attribute on the <element> element. This value can contain #all or a list that is a subset of extension or restriction.

extension	Prevents elements derived by extension from being used in place of this element.
restriction	Prevents elements derived by restriction from being used in place of this element.
#all	Prevents all derived elements from being used in place of this element.

Prohibited if the containing element is not the <schema> element.

Optional.

fixed

The predetermined, unchangeable value of the element if its content is a simple type or its content is textOnly.

The fixed and default attributes are mutually exclusive.

Optional.

form

The form for the element. The default value is the value of the elementFormDefault attribute of the <schema> element containing the attribute. The value must be one of the following strings: "qualified" or "unqualified".

If the value is unqualified, this element is not required to be qualified with the namespace prefix.

If the value is qualified, this element must be qualified with the namespace prefix.

Optional.

id

The ID of this element. The id value must be of type ID and be unique within the document containing this element.

Optional.

maxOccurs

The maximum number of times the element can occur within the containing element. The value can be an integer greater than or equal to zero. To set no limit on the maximum number, use the string "unbounded".

Prohibited if the containing element is the <schema> element.

Optional.

minOccurs

The minimum number of times the element can occur within the containing element. The value can be an integer greater than or equal to zero. To specify that this element is optional, set this attribute to zero.

Prohibited if the containing element is the <schema> element.

Optional.

name

The name of the element. The name must be a no-colon-name (NCName) as defined in the XML Namespaces specification. The name and ref attributes cannot both be present.

Required if the containing element is the <schema> element.

Optional.

nillable

The indicator of whether an explicit nil value can be assigned to the element. This applies to element content and not the attributes of the element. The default is false.

If nillable is true, this enables an instance of the element to have the nil attribute set to true. The nil attribute is defined as part of the XML Schema namespace for instances.

For example, the following fragment defines a single element with nillable set to true.

<xs:element name="myDate" type="xs:date" nillable="true"/>

The following fragment uses that element and has an explicit nil value (nil attribute set to true).

<myDate xsi:nil="true"></myDate>

Optional.

ref

The name of an element declared in this schema (or another schema indicated by the specified namespace). The ref value must be a QName. The ref can include a namespace prefix.

Prohibited if the containing element is the <schema> element.

If the ref attribute is present, <complexType>, <simpleType>, <key>, <keyref>, and <unique> elements and nillable, default, fixed, form, block, and type attributes cannot be present.

<xs:element ref="comment"/>

Optional.

type

Either the name of a built-in data type, or the name of a simpleType or complexType element defined in this schema (or another schema indicated by the specified namespace). The supplied value must correspond to the name attribute on the <simpleType> or <complexType> element that is referenced.

The type and ref attributes are mutually exclusive.

To declare an element using an existing simple type or complex type definition, use the type attribute to specify the existing type.

<xs:element name="name" type="xs:string"/>

Optional.

Element Information

Remarks

An element declaration associates a name with a type definition, which can be a built-in data type, a simple type, or a complex type.

Element declarations can be present as child elements of the <schema> element (having global scope) or within complex type definitions. Within complex types, element declarations can be present as local declarations or references to elements with global scope.

Global element declarations must directly define complex types.

A <simpleType> or <complexType> element can be present as a child only if both the ref and type attributes are not present.

In addition, elements can appear by reference within <choice>, <all>, <sequence>, and <complexType> elements.

Examples

The following example contains two elements that can serve as substitutes for another element.

<xs:element name="cat" type="xs:string"/>
<xs:element name="dog" type="xs:string"/>
<xs:element name="redDog" type="xs:string"
    substitutionGroup="dog" />
<xs:element name="brownDog" type="xs:string"
    substitutionGroup ="dog" />

<xs:element name="pets">
  <xs:complexType>
    <xs:choice minOccurs="0" maxOccurs="unbounded">
      <xs:element ref="cat"/>
      <xs:element ref="dog"/>
    </xs:choice>
  </xs:complexType>
</xs:element>

See Also

XML Schema Reference (XSD) | XML Schema Elements

For more information, see the W3C XML Schema Part 1: Structures Recommendation at http://www.w3.org/TR/2001/REC-xmlschema-1-20010502/#element-element.

Other Resources

W3C Namespaces in XML Recommendation | XML Schema Namespace for Instances