6.5. Constraining Elements

Perhaps the most important goal of the XML Schema Recommendation is to provide a language for constraining XML instances. A large part of this effort is constraining elements. An element type broadly specifies either simple content or complex content. An element type bound by simple content contains only a text value. This value may be constrained by built-in datatypes or other simple types derived from those datatypes. An element type whose content is complex might specify attribute types or nested element types (or both).

6.5.1. Simple Content

An element type that constrains an element to contain simple content places restrictions on the text value of the element. An element type that specifies simple content may specify attribute types as well.

6.5.1.1. Lexically Constrained Values

An element type lexically constrains the value of a corresponding element instance by specifying a simple type as its content type. The following two examples are elements whose structure types could be the built-in datatypes token and decimal, respectively:

<basicTokenElement>Element Value</basicTokenElement> 

and

<sixToOneHundred>50</sixToOneHundred> 

An element type representation may specify a built-in datatype or another global simple type with a type attribute:

<xsd:element name="basicTokenElement" type="xsd:token"/> 

Alternatively, an element type representation may specify a local simple type with a simpleType element:

<xsd:element name="sixToOneHundred" 
                   minOccurs="0" 
                   maxOccurs="unbounded"> 
    <xsd:simpleType> 
        <xsd:restriction base="xsd:positiveInteger"> 
            <xsd:minExclusive value="5"/> 
            <xsd:maxInclusive value="100"/>  
        </xsd:restriction> 
    </xsd:simpleType> 
</xsd:element> 

6.5.1.2. Simple Content and Attribute Types

An element type that specifies simple content may also permit attribute types by specifying a complex type with simple content. The following example is a tokenElement with a tokenAttribute attribute.

<tokenElement tokenAttribute="aValue">eValue</tokenElement> 

The corresponding element type must specify a complex type constrained to simple content:

<xsd:element name="tokenElement"> 
    <xsd:complexType> 
        <xsd:simpleContent> 
            <xsd:restriction base="xsd:token"> 
                <xsd:attribute name="tokenAttribute" 
                               type="xsd:token"/> 
            </xsd:restriction> 
        </xsd:simpleContent> 
    </xsd:complexType> 
</xsd:element> 

The XML representation of an element type can nest a local complex type, as in the previous example, or the element type can reference a global complex type using the type attribute.

6.5.2. Complex Content

An element type that constrains an element instance to contain complex content may specify subelements, empty content, mixed content, element wildcards, or attributes.

6.5.2.1. Nested Elements

Many XML instances require nested elements. Nested elements provide a mechanism for describing a hierarchy of data. An element type must specify a complex type that specifies a model group. The model group specifies the nested elements. Listing 6.2 is an example of an encompassingElement, which contains the nested elements basicTokenElement, sixToOneHundred, elementWithAttribute, and emptyContentWithAttribute.

6.5.2.2. Empty Content

An element that has no value—as distinct from having a value that is an empty string—has empty content. Typically, although not necessarily, an element type that specifies empty content also specifies one or more attribute types. The following example is an element emptyContentWithAttribute with a single attribute, decimalAttribute:

<emptyContentWithAttribute decimalAttribute="1000"/> 

The corresponding element type specifies a complex type that does not provide content:

<xsd:element name="emptyContentWithAttribute"> 
    <xsd:complexType> 
        <xsd:attribute name="decimalAttribute" 
                       type="xsd:decimal"/> 
    </xsd:complexType> 
</xsd:element> 

Element types that would otherwise require a value may specify that the corresponding element is nillable. The complete XML representation of phoneNumber, from address.xsd, permits a phone number to have empty content:

<xsd:element name="phoneNumber" 
             type="xsd:string" 
             nillable="true"/> 

The corresponding element explicitly has empty content:

<phoneNumber xsi:nil="true"/> 

6.5.2.3. Mixed Content

An element may have mixed content. An element with mixed content may contains text, usually interspersed with nested elements. (The text it not constrained by a simple type.) The compact example (Listing 6.1) does not demonstrate mixed content. However, the thematic catalog example specifies mixed content for an instance of description:

<description> 
    This is made up of both 
    <partList>UX002 UX003</partList> 
    pieces which makes it 
    better than 
    <partList>ASM2000</partList> 
    and better than the competition. 
</description> 

An element type must specify a complex type that permits mixed content. Either the complexType or the enclosed complexContent must specify a mixed attribute. The structure type that corresponds to the description element type specifies mixed content:

<xsd:complexType name="catalogEntryDescriptionType" 
                 mixed="true" 
                 id="catalogEntryDescriptionType.catalog.cType"> 
    <xsd:annotation> 
        <xsd:documentation xml:lang="en"> 
            Allow the description of a part 
            to include part number references. 
            The "catalogEntryDescriptionType"  
            is a good example of a complex type 
            with "mixed" content. 
                -- Shorthand Notation --
        </xsd:documentation> 
    </xsd:annotation> 
    <xsd:sequence minOccurs="0" maxOccurs="unbounded"> 
        <xsd:element name="partList" type="partNumberListType"/> 
    </xsd:sequence> 
</xsd:complexType> 

For completeness, the following is the description element type:

<xsd:element name="description" 
             type="catalogEntryDescriptionType"/> 

Chapter 11 discusses how to implement mixed content.

6.5.2.4. Element Wildcards

An XML schema may specify element wildcards with the any element. An element wildcard is a mechanism for specifying a set of namespaces from which the corresponding XML instance selects element types. The compact example does not demonstrate element wildcards. Chapters 8 and 15 covers element wildcards.

6.5.2.5. Complex Content and Attribute Types

Like simple content, complex content may optionally specify attribute types.