xs:element(global definition)

Name

xs:element(global definition) — Global element definition that can be referenced within the same schema by other schemas.

Synopsis

<xs:element
           abstract          = xs:boolean : “false”
           block             = ( “#all” | list of ( “extension” | “restriction” |
                                  “substitution” ) )
           default           = xs:string
           final             = ( “#all” | list of ( “extension” | “restriction” ) )
           fixed             = xs:string
           id                = xs:ID
           name              = xs:NCName
           nillable          = xs:boolean : “false”
           substitutionGroup = xs:QName
           type              = xs:QName
           {any attributes with non-schema namespace}
           >
           Content: (xs:annotation?, (xs:simpleType | xs:complexType)?, (xs:unique |
                     xs:key | xs:keyref)*)
</xs:element>

May be included in: xs:schema

Description

All the elements defined at the top level of a schema (i.e., xs:element, which is included directly under the xs:schema document element) are considered globally defined.

Globally defined elements have a global scope: they can be referenced through their qualified name everywhere in the schema in which they are defined, as well as in any schema that imports or includes this schema. They can also be used as document elements in instance documents.

Elements are identified by their qualified name, but the local name is expected in the name attribute. The type definition is performed by assigning a simple or complex datatype to the element.

This assignment can be done either by reference, using the type attribute to refer to a simple or complex datatype by its qualified name, or inline, by embedding the definition of the simple (xs:simpleType) element or the complex (xs:complexType) element that is within the xs:element element.

A default value may be defined using the default attribute, but note that the semantics of default values for elements are different than those of the default values for attributes. An element is not created if it is absent from the instance document; the default value is applied only if the element is present and empty.

Several control attributes are included in element definitions (see the attributes abstract, blocked, final, fixed, and nillable) .

Element definitions are also the place in which substitution groups are defined using the substitutionGroup attribute to refer to the head of the substitution group. Any global element that is not final may be chosen as the head of a substitution group. Any reference to the head of a substitution group may be replaced in the instance documents by any of the members of the substitution group (assuming these substitutions have not been blocked through block attributes). The relation is transitive, and if the head of a substitution “A” is a member of another substitution group “B,” the members of “A” are also considered members of “B.”

Restrictions

There is no feature that allows definition of global elements that cannot be used as document elements. When this is needed, the workaround is to define all the elements, save one, and use simple and complex types or element groups instead of global elements to define reusable content models, and then reference these types from a single globally-defined element.

The identification of the global elements by their qualified names makes it impossible to globally define multiple elements that have the same qualified name. When a schema must include multiple definitions of elements that have the same qualified name (and different datatypes), all the definitions except one must be locally declared. It is possible to use simple and complex types or element groups instead of global elements to define reusable content models.

All globally defined elements must be qualified if a target namespace has been defined for the schema; they must all belong to the target namespace. When no target namespace is defined, all the elements that are globally or locally defined must be unqualified.

The default and fixed values are defined in attributes and, therefore, can only apply to simple type elements.

Elements cannot be directly redefined. To redefine an element, one can either include it in a group and redefine the group, or use a global complex type to define the element and redefine the complex type.

Example

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

Attributes

abstract: Controls whether the element may be used directly in instance documents. When set to true, the element may still be used to define content models, but it must be substituted through a substitution group in the instance document.
block: Controls whether the element can be subject to a type or substitution group substitution. #all blocks any substitution, substitution blocks any substitution through substitution groups, and extension and restriction block any substitution (both through xsi:type and substitution groups) by elements or types, derived respectively by extension or restriction from the type of the element. Its default value is defined by the blockDefault attribute of the parent xs:schema.
default: Default value of the element. Defined in an attribute, element default values must be simple contents. Also note that default values apply only to elements that are present in the document and empty. The fixed and default attributes are mutually exclusive.
final: Controls whether the element can be used as the head of a substitution group for elements whose types are derived by extension or restriction from the type of the element. Its default value is defined by the finalDefault attribute of the parent xs:schema.
fixed: A simple content element may be fixed to a specific value using this attribute. This value is also used as a default value, and if the element is empty, it is supplied to the application. The fixed and default attributes are mutually exclusive.
id: W3C XML Schema’s element ID.
name: Local name of the element (without namespace prefix).
nillable: When this attribute is set to true, the element can be declared as nil using an xsi:nil attribute in the instance documents.
substitutionGroup: Qualified name of the head of the substitution group to which this element belongs.
type