W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures

1.3.1.1 The Schema Namespace (xs)

The XML representation of schema components uses a vocabulary identified by the namespace name http://www.w3.org/2001/XMLSchema. For brevity, the text and examples in this specification use the prefix xs: to stand for this namespace; in practice, any prefix can be used.

Users of the namespaces defined here should be aware, as a matter of namespace policy, that more names in this namespace may be given definitions in future versions of this or other specifications.

1.3.1.2 The Schema Instance Namespace (xsi)

This specification defines several attributes for direct use in any XML documents, as described in Schema-Related Markup in Documents Being Validated (§2.7). These attributes are in the namespace whose name is http://www.w3.org/2001/XMLSchema-instance. For brevity, the text and examples in this specification use the prefix xsi: to stand for this namespace; in practice, any prefix can be used.

Users of the namespaces defined here should be aware, as a matter of namespace policy, that more names in this namespace may be given definitions in future versions of this or other specifications.

1.3.1.3 The Schema Versioning Namespace (vc)

The pre-processing of schema documents described in Conditional inclusion (§4.2.2) uses attributes in the namespace http://www.w3.org/2007/XMLSchema-versioning. For brevity, the text and examples in this specification use the prefix vc: to stand for this namespace; in practice, any prefix can be used.

Users of the namespaces defined here should be aware, as a matter of namespace policy, that more names in this namespace may be given definitions in future versions of this or other specifications.

2.2.1.1 Type Definition Hierarchy

[Definition:]  Except for ·xs:anyType·, every ·type definition· is, by construction, either a ·restriction· or an ·extension· of some other type definition. The exception ·xs:anyType· is a ·restriction· of itself. With the exception of the loop on ·xs:anyType·, the graph of these relationships forms a tree known as the Type Definition Hierarchy with ·xs:anyType· as its root.

[Definition:]  The type definition used as the basis for an ·extension· or ·restriction· is known as the base type definition of that definition. [Definition:]   If a type definition D can reach a type definition B by following its base type definition chain, then D is said to be derived from B. In most cases, a type definition is derived from other type definitions. The only exception is ·xs:anyType·, which is derived from itself.

[Definition:]  A type defined with the same constraints as its ·base type definition·, or with more, is said to be a restriction. The added constraints might include narrowed ranges or reduced alternatives. Given two types A and B, if the definition of A is a ·restriction· of the definition of B, then members of type A are always locally valid against type B as well.

[Definition:]  A complex type definition which allows element or attribute content in addition to that allowed by another specified type definition is said to be an extension.

[Definition:]  A special complex type definition, (referred to in earlier versions of this specification as 'the ur-type definition') whose name is anyType in the XSD namespace, is present in each ·XSD schema·. The definition of anyType serves as default type definition for element declarations whose XML representation does not specify one.

[Definition:]  A special simple type definition, whose name is error in the XSD namespace, is also present in each ·XSD schema·. The XSD error type has no valid instances. It can be used in any place where other types are normally used; in particular, it can be used in conditional type assignment to cause elements which satisfy certain conditions to be invalid.

For brevity, the text and examples in this specification often use the qualified names xs:anyType and xs:error for these type definitions. (In practice, any appropriately declared prefix can be used, as described in Schema-Related Markup in Documents Being Validated (§2.7).)

2.2.1.2 Simple Type Definition

A simple type definition is a set of constraints on strings and information about the values they encode, applicable to the ·normalized value· of an attribute information item or of an element information item with no element children. Informally, it applies to the values of attributes and the text-only content of elements.

Each simple type definition, whether built-in (that is, defined in [XML Schema: Datatypes]) or user-defined, is a ·restriction· of its ·base type definition·. [Definition:]  A special ·restriction· of ·xs:anyType·, whose name is anySimpleType in the XSD namespace, is the root of the ·Type Definition Hierarchy· for all simple type definitions. ·xs:anySimpleType· has a lexical space containing all sequences of characters in the Universal Character Set (UCS) and a value space containing all atomic values and all finite-length lists of atomic values. As with ·xs:anyType·, this specification sometimes uses the qualified name xs:anySimpleType to designate this type definition. The built-in list datatypes all have ·xs:anySimpleType· as their ·base type definition·.

[Definition:]  There is a further special datatype called anyAtomicType, a ·restriction· of ·xs:anySimpleType·, which is the ·base type definition· of all the primitive datatypes. This type definition is often referred to simply as "xs:anyAtomicType". It too is considered to have an unconstrained lexical space. Its value space consists of the union of the value spaces of all the primitive datatypes.

[Definition:]   Datatypes can be constructed from other datatypes by restricting the value space or lexical space of a {base type definition} using zero or more Constraining Facets, by specifying the new datatype as a list of items of some {item type definition}, or by defining it as a union of some specified sequence of {member type definitions}.

The mapping from lexical space to value space is unspecified for items whose type definition is ·xs:anySimpleType· or ·xs:anyAtomicType·. Accordingly this specification does not constrain processors' behavior in areas where this mapping is implicated, for example checking such items against enumerations, constructing default attributes or elements whose declared type definition is ·xs:anySimpleType· or ·xs:anyAtomicType·, checking identity constraints involving such items.

[XML Schema: Datatypes] provides mechanisms for defining new simple type definitions by ·restricting· some primitive or ordinary datatype. It also provides mechanisms for constructing new simple type definitions whose members are lists of items themselves constrained by some other simple type definition, or whose membership is the union of the memberships of some other simple type definitions. Such list and union simple type definitions are also ·restrictions· of ·xs:anySimpleType·.

For detailed information on simple type definitions, see Simple Type Definitions (§3.16) and [XML Schema: Datatypes]. The latter also defines an extensive inventory of pre-defined simple types.

2.2.1.3 Complex Type Definition

A complex type definition is a set of attribute declarations and a content type, applicable to the [attributes] and [children] of an element information item respectively. The content type may require the [children] to contain neither element nor character information items (that is, to be empty), or to be a string which belongs to a particular simple type, or to contain a sequence of element information items which conforms to a particular model group, with or without character information items as well.

For detailed information on complex type definitions, see Complex Type Definitions (§3.4).

2.2.2.1 Element Declaration

An element declaration is an association of a name with a type definition, either simple or complex, an (optional) default value and a (possibly empty) set of identity-constraint definitions. The association is either global or scoped to a containing complex type definition. A top-level element declaration with name 'A' is broadly comparable to a pair of DTD declarations as follows, where the associated type definition fills in the ellipses:

<!ELEMENT A . . .>
<!ATTLIST A . . .>

Element declarations contribute to ·validation· as part of model group ·validation·, when their defaults and type components are checked against an element information item with a matching name and namespace, and by triggering identity-constraint definition ·validation·.

For detailed information on element declarations, see Element Declarations (§3.3). For an overview of identity constraints, see Identity-constraint Definition (§2.2.4.1).

2.2.2.2 Element Substitution Group

[Definition:]  Through the mechanism of element substitution groups, XSD provides a more powerful model than DTDs do supporting substitution of one named element for another. Any top-level element declaration can serve as the defining member, or head, for an element ·substitution group·. Other top-level element declarations, regardless of target namespace, can be designated as members of the ·substitution group· headed by this element. In a suitably enabled content model, a reference to the head ·validates· not just the head itself, but elements corresponding to any other member of the ·substitution group· as well.

All such members must have type definitions which are either the same as the head's type definition or derived from it. Therefore, although the names of elements can vary widely as new namespaces and members of the ·substitution group· are defined, the content of member elements is constrained by the type definition of the ·substitution group· head.

Note that element substitution groups are not represented as separate components. They are specified in the property values for element declarations (see Element Declarations (§3.3)).

2.2.2.3 Attribute Declaration

An attribute declaration is an association between a name and a simple type definition, together with occurrence information and (optionally) a default value. The association is either global, or local to its containing complex type definition. Attribute declarations contribute to ·validation· as part of complex type definition ·validation·, when their occurrence, defaults and type components are checked against an attribute information item with a matching name and namespace.

For detailed information on attribute declarations, see Attribute Declarations (§3.2).

2.2.2.4 Notation Declaration

A notation declaration is an association between a name and an identifier for a notation. For an attribute or element information item to be ·valid· with respect to a NOTATION simple type definition, its value must have been declared with a notation declaration.

For detailed information on notation declarations, see Notation Declarations (§3.14).

2.2.3.1 Model Group

A model group is a constraint in the form of a grammar fragment that applies to lists of element information items. It consists of a list of particles, i.e. element declarations, wildcards and model groups. There are three varieties of model group:

• Sequence (the element information items match the particles in sequential order);
• Conjunction (the element information items match the particles, in any order);
• Disjunction (the element information items match one or more of the particles).

Each model group denotes a set of sequences of element information items. Regarding that set of sequences as a language, the set of sequences recognized by a group G may be written L(G). [Definition:]  A model group G is said to accept or recognize the members of L(G).

For detailed information on model groups, see Model Groups (§3.8).

2.2.3.2 Particle

A particle is a term in the grammar for element content, consisting of either an element declaration, a wildcard or a model group, together with occurrence constraints. Particles contribute to ·validation· as part of complex type definition ·validation·, when they allow anywhere from zero to many element information items or sequences thereof, depending on their contents and occurrence constraints.

The name [Definition:]  Term is used to refer to any of the three kinds of components which can appear in particles. All ·Terms· are themselves ·Annotated Components·. [Definition:]  A basic term is an Element Declaration or a Wildcard. [Definition:]  A basic particle is a Particle whose {term} is a ·basic term·.

Each content model, indeed each particle and each term, denotes a set of sequences of element information items. Regarding that set of sequences as a language, the set of sequences recognized by a particle P may be written L(P). [Definition:]  A particle P is said to accept or recognize the members of L(P). Similarly, a term T accepts or recognizes the members of L(T).

If a sequence S is a member of L(P), then it is necessarily possible to trace a path through the ·basic particles· within P, with each item within S corresponding to a matching particle within P. The sequence of particles within P corresponding to S is called the ·path· of S in P.

For detailed information on particles, see Particles (§3.9).

2.2.3.3 Attribute Use

An attribute use plays a role similar to that of a particle, but for attribute declarations: an attribute declaration used by a complex type definition is embedded within an attribute use, which specifies whether the declaration requires or merely allows its attribute, and whether it has a default or fixed value.

2.2.3.4 Wildcard

A wildcard is a special kind of particle which matches element and attribute information items dependent on their namespace names and optionally on their local names.

For detailed information on wildcards, see Wildcards (§3.10).

2.2.4.1 Identity-constraint Definition

An identity-constraint definition is an association between a name and one of several varieties of identity-constraint related to uniqueness and reference. All the varieties use [XPath 2.0] expressions to pick out sets of information items relative to particular target element information items which are unique, or a key, or a ·valid· reference, within a specified scope. An element information item is only ·valid· with respect to an element declaration with identity-constraint definitions if those definitions are all satisfied for all the descendants of that element information item which they pick out.

For detailed information on identity-constraint definitions, see Identity-constraint Definitions (§3.11).

2.2.4.2 Type Alternative

A Type Alternative component (type alternative for short) associates a type definition with a predicate. Type alternatives are used in conditional type assignment, in which the choice of ·governing type definition· for elements governed by a particular element declaration depends on properties of the document instance. An element declaration may have a {type table} which contains a sequence of type alternatives; the predicates on the alternatives are tested, and when a predicate is satisfied, the type definition paired with it is chosen as the element instance's ·governing type definition·.

For detailed information on Type Alternatives, see Type Alternatives (§3.12).

2.2.4.3 Assertion

An assertion is a predicate associated with a type, which is checked for each instance of the type. If an element or attribute information item fails to satisfy an assertion associated with a given type, then that information item is not locally ·valid· with respect to that type.

For detailed information on Assertions, see Assertions (§3.13).

2.2.4.4 Overlapping Functionality of Constraint Components

Many rules that can be enforced by identity constraints and conditional type assignment can also be formulated in terms of assertions. That is, the various constructs have overlapping functionality. The three forms of constraint differ from each other in various ways which may affect the schema author's choice of formulation.

Most obviously, the ·post-schema-validation infoset· will differ somewhat, depending on which form of constraint is chosen.

Less obviously, identity constraints are associated with element declarations, while assertions are associated with type definitions. If it is desired to enforce a particular property of uniqueness or referential integrity associated with a particular element declaration E, of type T, the schema author may often choose either an identity constraint associated with E, or an assertion associated with T. One obvious difference is that elements substitutable for E are required to have types derived from T, but are not required to enforce the identity constraints (or the nillability) of E. If the constraint applicable to E should be enforced by elements substitutable for E, it is often most convenient to formulate the constraint as an assertion on T; conversely, if only some elements of type T are intended to be subject to the constraint, or if elements substitutable for E need not enforce the constraint, then it will be more convenient to formulate the rule as an identity constraint on E.

Similar considerations sometimes apply to the choice between assertions and conditional type assignment.

Because identity constraints and conditional type assignment are simpler and less variable than assertions, it may be easier for software to exploit or optimize them. Assertions have greater expressive power, which means they are often convenient. The "rule of least power" applies here; it is often preferable to use a less expressive notation in preference to a more expressive one, when either will suffice. See [Rule of Least Power].

2.2.5.1 Model Group Definition

A model group definition is an association between a name and a model group, enabling re-use of the same model group in several complex type definitions.

For detailed information on model group definitions, see Model Group Definitions (§3.7).

2.2.5.2 Attribute Group Definition

An attribute group definition is an association between a name and a set of attribute declarations, enabling re-use of the same set in several complex type definitions.

For detailed information on attribute group definitions, see Attribute Group Definitions (§3.6).

3.2.2.1 Mapping Rules for Global Attribute Declarations

If the <attribute> element information item has <schema> as its parent, the corresponding schema component is as follows:

3.2.2.2 Mapping Rules for Local Attribute Declarations

If the <attribute> element information item has <complexType> or <attributeGroup> as an ancestor and the ref [attribute] is absent, it maps both to an attribute declaration (see below) and to an attribute use with properties as follows (unless use='prohibited', in which case the item corresponds to nothing at all):

The <attribute> element also maps to the {attribute declaration} of the attribute use, as follows:

3.2.2.3 Mapping Rules for References to Top-level Attribute Declarations

If the <attribute> element information item has <complexType> or <attributeGroup> as an ancestor and the ref [attribute] is present, it maps to an attribute use with properties as follows (unless use='prohibited', in which case the item corresponds to nothing at all):

3.2.4.1 Attribute Locally Valid

Informally, an attribute in an XML instance is locally ·valid· against an attribute declaration if and only if (a) the name of the attribute matches the name of the declaration, (b) after whitespace normalization its ·normalized value· is locally valid against the type declared for the attribute, and (c) the attribute obeys any relevant value constraint. Additionally, for xsi:type, it is required that the type named by the attribute be present in the schema. A logical prerequisite for checking the local validity of an attribute against an attribute declaration is that the attribute declaration itself and the type definition it identifies both be present in the schema.

Local validity of attributes is tested as part of schema-validity ·assessment· of attributes (and of the elements on which they occur), and the result of the test is exposed in the [validity] property of the ·post-schema-validation infoset·.

A more formal statement is given in the following constraint.

3.2.4.2 Governing Attribute Declaration and Governing Type Definition

3.2.4.3 Schema-Validity Assessment (Attribute)

Schema-validity assessment of an attribute information item involves identifying its ·governing attribute declaration· and checking its local validity against the declaration. If the ·governing type definition· is not present in the schema, then assessment is necessarily incomplete.

[Definition:]  For attribute information items, there is no difference between assessment and strict assessment, so the attribute information item has been strictly assessed if and only if its schema-validity has been assessed.

3.2.5.1 Assessment Outcome (Attribute)

3.2.5.2 Validation Failure (Attribute)

3.2.5.3 Attribute Declaration

3.2.5.4 Attribute Validated by Type

See also Attribute Default Value (§3.4.5.1), Match Information (§3.4.5.2) and Schema Information (§3.17.5.1), which describe other information set contributions related to attribute information items.

3.2.6.1 Attribute Declaration Properties Correct

3.2.6.2 Simple Default Valid

3.2.6.3 xmlns Not Allowed

3.2.6.4 xsi: Not Allowed

3.2.7.1 xsi:type

The xsi:type attribute is used to signal use of a type other than the declared type of an element. See xsi:type (§2.7.1).

3.2.7.2 xsi:nil

The xsi:nil attribute is used to signal that an element's content is "nil" (or "null"). See xsi:nil (§2.7.2).

3.2.7.3 xsi:schemaLocation

The xsi:schemaLocation attribute is used to signal possible locations of relevant schema documents. See xsi:schemaLocation, xsi:noNamespaceSchemaLocation (§2.7.3).

3.2.7.4 xsi:noNamespaceSchemaLocation

The xsi:noNamespaceSchemaLocation attribute is used to signal possible locations of relevant schema documents. See xsi:schemaLocation, xsi:noNamespaceSchemaLocation (§2.7.3).

3.3.2.1 Common Mapping Rules for Element Declarations

The following mapping rules apply in all cases where an <element> element maps to an Element Declaration component.

3.3.2.2 Mapping Rules for Top-Level Element Declarations

If the <element> element information item has <schema> as its parent, it maps to a global Element Declaration, using the mapping given in Common Mapping Rules for Element Declarations (§3.3.2.1), supplemented by the following.

3.3.2.3 Mapping Rules for Local Element Declarations

If the <element> element information item has <complexType> or <group> as an ancestor, and the ref [attribute] is absent, and it does not have minOccurs=maxOccurs=0, then it maps both to a Particle and to a local Element Declaration which is the {term} of that Particle. The Particle is as follows:

The <element> element also maps to an element declaration using the mapping rules given in Common Mapping Rules for Element Declarations (§3.3.2.1), supplemented by those below:

3.3.2.4 References to Top-Level Element Declarations

If the <element> element information item has <complexType> or <group> as an ancestor, and the ref [attribute] is present, and it does not have minOccurs=maxOccurs=0, then it maps to a Particle as follows.

3.3.2.5 Examples of Element Declarations

<xs:element name="unconstrained"/>

<xs:element name="emptyElt">
 <xs:complexType>
  <xs:attribute ...>. . .</xs:attribute>
 </xs:complexType>
</xs:element>

<xs:element name="contextOne">
 <xs:complexType>
  <xs:sequence>
   <xs:element name="myLocalElement" type="myFirstType"/>
   <xs:element ref="globalElement"/>
  </xs:sequence>
 </xs:complexType>
</xs:element>

<xs:element name="contextTwo">
 <xs:complexType>
  <xs:sequence>
   <xs:element name="myLocalElement" type="mySecondType"/>
   <xs:element ref="globalElement"/>
  </xs:sequence>
 </xs:complexType>
</xs:element>

 <xs:complexType name="facet">
  <xs:complexContent>
   <xs:extension base="xs:annotated">
    <xs:attribute name="value" use="required"/>
   </xs:extension>
  </xs:complexContent>
 </xs:complexType>

 <xs:element name="facet" type="xs:facet" abstract="true"/>

 <xs:element name="encoding" substitutionGroup="xs:facet">
  <xs:complexType>
   <xs:complexContent>
    <xs:restriction base="xs:facet">
     <xs:sequence>
      <xs:element ref="annotation" minOccurs="0"/>
     </xs:sequence>
     <xs:attribute name="value" type="xs:encodings"/>
    </xs:restriction>
   </xs:complexContent>
  </xs:complexType>
 </xs:element>

 <xs:element name="period" substitutionGroup="xs:facet">
  <xs:complexType>
   <xs:complexContent>
    <xs:restriction base="xs:facet">
     <xs:sequence>
      <xs:element ref="annotation" minOccurs="0"/>
     </xs:sequence>
     <xs:attribute name="value" type="xs:duration"/>
    </xs:restriction>
   </xs:complexContent>
  </xs:complexType>
 </xs:element>

 <xs:complexType name="datatype">
  <xs:sequence>
   <xs:element ref="facet" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
  <xs:attribute name="name" type="xs:NCName" use="optional"/>
  . . .
 </xs:complexType>

<xs:complexType name="messageType" mixed="true">
 <xs:sequence>
  <xs:any processContents="skip" minOccurs="0" maxOccurs="unbounded"/>
 </xs:sequence>
 <xs:attribute name="kind">
  <xs:simpleType>
   <xs:union>
    <xs:simpleType>
     <xs:restriction base="xs:string">
      <xs:enumeration value="string"/>
      <xs:enumeration value="base64"/>
      <xs:enumeration value="binary"/>
      <xs:enumeration value="xml"/>
      <xs:enumeration value="XML"/>
     </xs:restriction>
    </xs:simpleType>
    <xs:simpleType>
     <xs:restriction base="xs:string"/>
    </xs:simpleType>
   </xs:union>
  </xs:simpleType>
 </xs:attribute>
 <xs:anyAttribute processContents="skip"/>
</xs:complexType>

<xs:complexType name="messageTypeString">
 <xs:simpleContent>
  <xs:restriction base="messageType">
   <xs:simpleType>
    <xs:restriction base="xs:string"/>
   </xs:simpleType>
  </xs:restriction>
 </xs:simpleContent>
</xs:complexType>

<xs:complexType name="messageTypeBase64">
 <xs:simpleContent>
  <xs:restriction base="messageType">
   <xs:simpleType>
    <xs:restriction base="xs:base64Binary"/>
   </xs:simpleType>
  </xs:restriction>
 </xs:simpleContent>
</xs:complexType>

<xs:complexType name="messageTypeXML">
 <xs:complexContent>
  <xs:restriction base="messageType">
   <xs:sequence>
    <xs:any processContents="strict"/>
   </xs:sequence>
  </xs:restriction>
 </xs:complexContent>
</xs:complexType>

<xs:element name="message" type="messageType">
  <xs:alternative test="@kind='string'" type="messageTypeString"/>
  <xs:alternative test="@kind='base64'" type="messageTypeBase64"/>
  <xs:alternative test="@kind='binary'" type="messageTypeBase64"/>
  <xs:alternative test="@kind='xml'"    type="messageTypeXML"/>
  <xs:alternative test="@kind='XML'"    type="messageTypeXML"/> 
  <xs:alternative                       type="messageType"/>
</xs:element>

3.3.4.1 Selected and Instance-specified Type Definitions

The ·governing type definition· of an element is normally the declared {type definition} associated with the ·governing element declaration·, but this may be ·overridden· using conditional type assignment in the Element Declaration or using an ·instance-specified type definition·, or both. When the element is declared with conditional type assignment, the ·selected type definition· is used as the ·governing type definition· unless ·overridden· by an ·instance-specified type definition·.

3.3.4.2 Type Override and Valid Substitutability

[Definition:]  If the set of keywords controlling whether a type S is ·validly substitutable· for another type T is the empty set, then S is said to be validly substitutable for T without limitation or absolutely. The phrase validly substitutable, without mention of any set of blocking keywords, means "validly substitutable without limitation".

Sometimes one type S is ·validly substitutable· for another type T only if S is derived from T by a chain of restrictions, or if T is a union type and S a member type of the union. The concept of ·valid substitutability· is appealed to often enough in such contexts that it is convenient to define a term to cover this specific case. [Definition:]  A type definition S is validly substitutable as a restriction for another type T if and only if S is ·validly substitutable· for T, subject to the blocking keywords {extension, list, union}.

3.3.4.3 Element Locally Valid (Element)

The concept of local validity of an element information item against an element declaration is an important part of the schema-validity ·assessment· of elements. (The other important part is the recursive ·assessment· of attributes and descendant elements.) Local validity partially determines the element information item's [validity] property, and fully determines the [local element validity] property, in the ·post-schema-validation infoset·.

The following validation rule gives the normative formal definition of local validity of an element against an element declaration.

3.3.4.4 Element Locally Valid (Type)

The following validation rule specifies formally what it means for an element to be locally valid against a type definition. This concept is appealed to in the course of checking an element's local validity against its ·governing type definition·. It is also part of schema-validity ·assessment· of an element when the element is ·laxly assessed·, by checking its local validity against xs:anyType.

Informally, local validity against a type requires first that the type definition be present in the schema and not declared abstract. For a simple type definition, the element must lack attributes (except for namespace declarations and the special attributes in the xsi namespace) and child elements, and must be type-valid against that simple type definition. For a complex type definition, the element must be locally valid against that complex type definition.

3.3.4.5 Validation Root Valid (ID/IDREF)

The following validation rule specifies document-level ID/IDREF constraints checked on the ·validation root· if it is an element; this rule is not checked on other elements. Informally, the requirement is that each ID identifies a single element within the ·validation root·, and that each IDREF value matches one ID.

3.3.4.6 Schema-Validity Assessment (Element)

3.3.5.1 Assessment Outcome (Element)

3.3.5.2 Validation Failure (Element)

3.3.5.3 Element Declaration

3.3.5.4 Element Validated by Type