xs:element

Purpose

This element allows you to define elements.

If the xs:element element is the child element of an xs:schema element, it defines a global element and the name attribute is required.

If the xs:element element is the descendant element of a xs:complexType element, its name attribute performs a definition of local elements.

Parent element xs:all, xs:choice, xs:group, xs:sequence, xs:schema
Child elements xs:annotation, xs:complexType, xs:key, xs:keyref, xs:simpleType, xs:unique
Attributes abstract (global elements only), default, final (global elements only), fixed, form (only if not below xs:schema), maxOccurs (only if not below xs:schema), minOccurs (only if not below xs:schema), name, nillable, ref (only if not below xs:schema), substitutionGroup (global elements only), type
Attributes
Name Type Description
abstract xs:boolean If "true", this element declaration must not be used for validation. Typically, another element from the substitution group will be used in an XML document.
block xs:boolean

This attribute, in conjunction with the schema's blockDefault attribute (if block is not specified, the blockDefault attribute value takes effect), is used at validation time. It specifies the types that can be used in an xsi:type attribute or the types of a substituting element that can be used in an element that is validated against the current element declaration. The value is a whitespace-separated list of:

restriction

The alternate type definition is not allowed to be derived by restriction from the default type defined by this element declaration.

extension

The alternate type definition is not allowed to be derived by extension from the default type defined by this element declaration.

substitution

Substitution by a member of the substitution group is not allowed.

Alternatively, the value "#all" can be specified. This prevents the substitution of an element that is validated against this element declaration.

default xs:string

Allows you to specify for an element a default value that is inserted if the element occurs with empty content in the XML instance.

Note:
The default attribute may not be used together with the fixed attribute.

final  

This attribute, in conjunction with the schema's finalDefault attribute (if final is not specified, the finalDefault attribute value takes effect), is used when performing schema checks. It specifies the substitutions that are valid for an element that is validated against the current element declaration. The value is a whitespace-separated list of:

substitution

No substitution is allowed.

restriction

Substitution by an element whose datatype is derived from the current element's datatype by restriction is not allowed.

extension

Substitution by an element whose datatype is derived from the current element's datatype by extension is not allowed.

Alternatively, the special value "#all" can be specified. This also means that no substitution is allowed.

fixed xs:string

Specifies the value that the element that must have if present. This has the following consequences for instances of that schema:

  • Element present in instance:
    The value of the element must either match the value of the fixed attribute or be empty. If empty, Tamino inserts the value of the fixed attribute into the element.

  • Element not present in instance:
    Tamino does not insert the element or any value into the XML instance.

Note:
The fixed attribute may not be used together with the default attribute.

form xs:NMTOKEN

Determines whether the occurrence of locally-declared elements in an instance document must be qualified by a namespace specification. It overrides the default that is set by the elementFormDefault attribute of the xs:schema element. It can have the value "qualified" or "unqualified". The default is "unqualified".

maxOccurs xs:nonNegativeInteger or "unbounded"

Together with the minOccurs attribute described above, this attribute expresses multiplicity in TSD (and XML Schema) element definitions. The value of a maxOccurs attribute in an xs:element declaration determines the maximum number of occurrences of a specific element. The value of maxOccurs must be a non-negative integer or the value "unbounded". The default value for maxOccurs is 1.

minOccurs xs:nonNegativeInteger

Together with the maxOccurs attribute described below, this attribute expresses multiplicity in TSD (and XML Schema) element definitions. The value of a minOccurs attribute in an xs:element declaration determines the minimum number of occurrences of a specific element. The value of minOccurs must be a non-negative integer. The default value for minOccurs is 1.

name xs:NCName

Specifies a name for the element.

Note:
The name and ref attributes are mutually exclusive.

nillable xs:boolean

If "true", an instance to be validated against this element may have an additional xsi:nil attribute. If xsi:nil="true", the element must not have any content: neither text nor child nodes. The validation of attributes is not affected. (See section 2.9 Nil Values in the W3C documentation XML Schema Part 0: Primer.) Default value: "false".

Tamino-Specific Constraints

An element or a descendant of an element with nillable="true" must not be referenced in a tsd:unique constraint.

ref xs:QName

A global element can be referenced in other declarations in the same schema using the ref attribute of the xs:element element. The value of the ref attribute must refer to a global element.

Only the minOccurs and maxOccurs attributes are allowed in conjunction with the ref attribute

For more information, refer to the subsection 2.2 Complex Type Definitions, Element & Attribute Declarations in W3C´s document XML Schema Part 0: Primer

Note:
The name and ref attributes are mutually exclusive.

substitutionGroup xs:QName Refers to a global element declaration with a matching QName. The referenced element declaration is called the substitution group head element. This is an element that is valid against the current element declaration (which must be a global declaration), then it is a valid replacement for any element validated against the substitution group head element. See section 4.6 Substitution Groups in the W3C documentation XML Schema Part 0: Primer.
type xs:QName

Indicates the type of the element to be defined.

The type can be any of the predefined types described in section 3 Built-in datatypes of W3C Recommendation, XML Schema Part 2: Datatypes or any user-defined type.

The occurrence of the type attribute and the occurrence of the xs:simpleType and xs:complexType child elements are mutually exclusive.

The type can be either a simple or a complex type. Simple types are defined with the xs:simpleType element; complex types are defined with the xs:complexType element.

Example (using a complex type definition)

This example of an element definition using a complex type definition is taken from an XML Schema for a book store. It describes how an attribute Category is defined that can only have the values:

autobiography
non-fiction
fiction

      <xs:element name="Book">
        <xs:complexType>
          <xs:attribute name="Category" use="required">
            <xs:restriction>
              <xs:simpleType base="xs:string">
                <xs:enumeration value="autobiography"/>
                <xs:enumeration value="non-fiction"/>
                <xs:enumeration value="fiction"/>
              </xs:simpleType>
            </xs:restriction>
          </xs:attribute>
          <xs:attribute name="InStock" type="xs:boolean" use="optional" default="false"/>
          <xs:attribute name="Reviewer" type="xs:string" use="optional" default=""/>
        </xs:complexType>
      </xs:element>