Table of contents

Appendices

4.2 Layer 2: Schema Documents, Namespaces and Composition

The sub-sections of [Schema Component Details] define an XML representation for type definitions and element declarations and so on, specifying their target namespace and collecting them into schema documents. The two following sections relate to assembling a complete schema for assessment from multiple sources. They should not be understood as a form of text substitution, but rather as providing mechanisms for distributed definition of schema components, with appropriate schema-specific semantics.

NOTE: 

The core assessment architecture requires that a complete schema with all the necessary declarations and definitions be available. This may involve resolving both instance->schema and schema->schema references. As observed earlier in [Conformance], the precise mechanisms for resolving such references are expected to evolve over time. In support of such evolution, this specification observes the design principle that references from one schema document to a schema use mechanisms that directly parallel those used to reference a schema from an instance document.

NOTE: 

In the sections below, "schemaLocation" really belongs at layer 3. For convenience, it is documented with the layer 2 mechanisms of import and include, with which it is closely associated.

Assembling a schema for a single target namespace from multiple schema definition documents[top]

Schema components for a single target namespace can be assembled from several schema document, that is several [schema] element information items:

A [schema] information item may contain any number of [include] elements. Their schemaLocation attributes, consisting of a URI reference, identify other schema document, that is [schema] information items.

The XML Schema corresponding to [schema] contains not only the components corresponding to its definition and declaration [children], but also all the components of all the XML Schema corresponding to any [include]d schema documents. Such included schema documents must either (a) have the same targetNamespace as the [include]ing schema document, or (b) no targetNamespace at all, in which case the [include]d schema document is converted to the [include]ing schema document's targetNamespace.

In addition to the conditions imposed on [include] element information items by the schema for schemas,

1. If the actual value of the schemaLocation [attribute] successfully resolves

   1. It resolves to (a fragment of) a resource which is an XML document (of type application/xml or text/xml with an XML declaration for preference, but this is not required), which in turn corresponds to a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   2. It resolves to a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   In either case call the [include]d [schema] item SII, the valid schema I and the [include]ing item's parent [schema] item SII’.

2. 1. SII has a targetNamespace [attribute], and its actual value is identical to the actual value of the targetNamespace [attribute] of SII’ (which must have such an [attribute]).

   2. Neither SII nor SII’ have a targetNamespace [attribute].

   3. SII has no targetNamespace [attribute] (but SII’ does).

3. 1. if[c-normi] or [c-normi2] above is satisfied

      thenthe schema corresponding to SII’ must include not only definitions or declarations corresponding to the appropriate members of its own [children], but also components identical to all the schema component of I.

   2. if[c-chami] above is satisfied

      thenthe schema corresponding to the [include]d item's parent [schema] must include not only definitions or declarations corresponding to the appropriate members of its own [children], but also components identical to all the schema component of I, except that anywhere the absent target namespace name would have appeared, the actual value of the targetNamespace [attribute] of SII’ is used. In particular, it replaces absent in the following places:

      1. The [target namespace] of named schema components, both at the top level and (in the case of nested type definitions and nested attribute and element declarations whose code was qualified) nested within definitions;

      2. The [namespace_constraint] of a wildcard, whether negated or not;

It is not an error for the actual value of the schemaLocation [attribute] to fail to resolve it all, in which case no corresponding inclusion is performed. It is an error for it to resolve but the rest of clause 1 above to fail to be satisfied. Failure to resolve may well cause less than complete assessment outcomes, of course.

NOTE: 

As discussed in [Missing Sub-components], QNames in XML representations may fail to resolve, rendering components incomplete and unusable because of missing subcomponents. During schema construction, implementations are likely to retain QName values for such references, in case subsequent processing provides a referent. absent target namespace names of such as-yet unresolved reference QNames in [include]d components should also be converted if [c-docham] is satisfied.

NOTE: 

The above is carefully worded so that multiple [include]ing of the same schema document will not constitute a violation of [c-nmd] of [Schema Properties Correct], but applications are allowed, indeed encouraged, to avoid [include]ing the same schema document more than once to forestall the necessity of establishing identity component by component.

Including modified component definitions[top]

In order to provide some support for evolution and versioning, it is possible to incorporate components corresponding to a schema document with modifications. The modifications have a pervasive impact, that is, only the redefined components are used, even when referenced from other incorporated components, whether redefined themselves or not.

A [schema] information item may contain any number of [redefine] elements. Their schemaLocation attributes, consisting of a URI reference, identify other schema document, that is [schema] information items.

The XML Schema corresponding to [schema] contains not only the components corresponding to its definition and declaration [children], but also all the components of all the XML Schema corresponding to any [redefine]d schema documents. Such schema documents must either (a) have the same targetNamespace as the [redefine]ing schema document, or (b) no targetNamespace at all, in which case the [redefine]d schema document is converted to the [redefine]ing schema document's targetNamespace.

The definitions within the [redefine] element itself are restricted to be redefinitions of components from the [redefine]d schema document, in terms of themselves. That is,

• Type definitions must use themselves as their base type definition;

• Attribute group definitions and model group definitions must be supersets or subsets of their original definitions, either by including exactly one reference to themselves or by containing only (possibly restricted) components which appear in a corresponding way in their [redefine]d selves.

This mechanism is intended to provide a declarative and modular approach to schema modification, with functionality no different except in scope from what would be achieved by wholesale text copying and redefinition by editing. In particular redefining a type is not guaranteed to be side-effect free: it may have unexpected impacts on other type definitions which are based on the redefined one, even to the extent that some such definitions become ill-formed.

NOTE: 

The pervasive impact of redefinition reinforces the need for implementations to adopt some form of lazy or 'just-in-time' approach to component construction, which is also called for in order to avoid inappropriate dependencies on the order in which definitions and references appear in (collections of) schema documents.

NOTE: 

v1.xsd:
 <xs:complexType name="personName">
  <xs:sequence>
   <xs:element name="title" minOccurs="0"/>
   <xs:element name="forename" minOccurs="0" maxOccurs="unbounded"/>
  </xs:sequence>
 </xs:complexType>

 <xs:element name="addressee" type="personName"/>

v2.xsd:
 <xs:redefine schemaLocation="v1.xsd">
  <xs:complexType name="personName">
   <xs:complexContent>
    <xs:extension base="personName">
     <xs:sequence>
      <xs:element name="generation" minOccurs="0"/>
     </xs:sequence>
    </xs:extension>
   </xs:complexContent>
  </xs:complexType>
 </xs:redefine>

 <xs:element name="author" type="personName"/>
  

The schema corresponding to v2.xsd has everything specified by v1.xsd, with the personName type redefined, as well as everything it specifies itself. According to this schema, elements constrained by the personName type may end with a generation element. This includes not only the author element, but also the addressee element.

In addition to the conditions imposed on [redefine] element information items by the schema for schemas

1. If there are any element information items among the [children] other than [annotation] then the actual value of the schemaLocation [attribute] must successfully resolve.

2. If the actual value of the schemaLocation [attribute] successfully resolves

   1. it resolves to (a fragment of) a resource which is an XML document (see [c-vxd]), which in turn corresponds to a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   2. It resolves to a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   In either case call the [redefine]d [schema] item SII, the valid schema I and the [redefine]ing item's parent [schema] item SII’.

3. 1. SII has a targetNamespace [attribute], and its actual value is identical to the actual value of the targetNamespace [attribute] of SII’ (which must have such an [attribute]).

   2. Neither SII nor SII’ have a targetNamespace [attribute].

   3. SII has no targetNamespace [attribute] (but SII’ does).

4. 1. if[c-normir] or [c-normi2r] above is satisfied

      thenthe schema corresponding to SII’ must include not only definitions or declarations corresponding to the appropriate members of its own [children], but also components identical to all the schema component of I, with the exception of those explicitly redefined (see [Individual Component Redefinition] below).

   2. if[c-chamir] above is satisfied

      thenthe schema corresponding to SII’ must include not only definitions or declarations corresponding to the appropriate members of its own [children], but also components identical to all the schema component of I, with the exception of those explicitly redefined (see [Individual Component Redefinition] below), except that anywhere the absent target namespace name would have appeared, the actual value of the targetNamespace [attribute] of SII’ is used (see [c-docham] in [Inclusion Constraints and Semantics] for details).

5. Within the [children], each [simpleType] must have a [restriction] among its [children] and each [complexType] must have a restriction or extension among its grand-[children] the actual value of whose base [attribute] must be the same as the actual value of its own name attribute plus target namespace;

6. Within the [children], for each [group]

   1. ifit has a [group] among its contents at some level the actual value of whose ref [attribute] is the same as the actual value of its own name attribute plus target namespace

      then

      1. It must have exactly one such group.

      2. The actual value of both that group's minOccurs and maxOccurs [attribute] must be 1 (or absent).

   2. ifit has no such self-reference

      then

      1. The actual value of its own name attribute plus target namespace must successfully resolve to a model group definition in I.

      2. The [model_group] of the model group definition which corresponds to it per [XML Representation of Model Group Definition Schema Components] must be a valid restriction of the [model_group] of that model group definition in I, as defined in [Particle Valid (Restriction)].

7. Within the [children], for each [attributeGroup]

   1. ifit has an [attributeGroup] among its contents the actual value of whose ref [attribute] is the same as the actual value of its own name attribute plus target namespace

      thenit must have exactly one such group.

   2. ifit has no such self-reference

      then

      1. The actual value of its own name attribute plus target namespace must successfully resolve to an attribute group definition in I.

      2. The [ag-attribute_declarations] and [ag-attribute_wildcard] of the attribute group definition which corresponds to it per [XML Representation of Attribute Group Definition Schema Components] must be valid restriction of the [ag-attribute_declarations] and [ag-attribute_wildcard] of that attribute group definition in I, as defined in [c-rad], [c-rad2] and [c-raw] of [Derivation Valid (Restriction, Complex)] (where references to the base type definition are understood as references to the attribute group definition in I).

   NOTE: 

   An attribute group restrictively redefined per [c-agrere] corresponds to an attribute group whose [ag-attribute_declarations] consist all and only of those attribute uses corresponding to [attribute]s explicitly present among the [children] of the [redefine]ing [attributeGroup]. No inheritance from the [redefine]d attribute group occurs. Its [ag-attribute_wildcard] is similarly based purely on an explicit [anyAttribute], if present.

Corresponding to each non-[annotation] member of the [children] of a [redefine] there are one or two schema components in the [redefine]ing schema:

1. The [simpleType] and [complexType] [children] information items each correspond to two components:

   1. One component which corresponds to the top-level definition item with the same name in the [redefine]d schema document, as defined in [Schema Component Details], except that its [name] is absent;

   2. One component which corresponds to the information item itself, as defined in [Schema Component Details], except that its [base type definition] is the component defined in 1.1 above.

   This pairing ensures the coherence constraints on type definitions are respected, while at the same time achieving the desired effect, namely that references to names of redefined components in both the [redefine]ing and [redefine]d schema documents resolve to the redefined component as specified in 1.2 above.

2. The [group] and [attributeGroup] [children] each correspond to a single component, as defined in [Schema Component Details], except that if and when a self-reference based on a ref [attribute] whose actual value is the same as the item's name plus target namespace is resolved, a component which corresponds to the top-level definition item of that name and the appropriate kind in I is used.

In all cases there must be a top-level definition item of the appropriate name and kind in the [redefine]d schema document.

NOTE: 

The above is carefully worded so that multiple equivalent [redefine]ing of the same schema document will not constitute a violation of [c-nmd] of [Schema Properties Correct], but applications are allowed, indeed encouraged, to avoid [redefine]ing the same schema document in the same way more than once to forestall the necessity of establishing identity component by component (although this will have to be done for the individual redefinitions themselves).

References to schema components across namespaces[top]

As described in [XML Schema Abstract Data Model], every top-level schema component is associated with a target namespace (or, explicitly, with none). This section sets out the exact mechanism and syntax in the XML form of schema definition by which a reference to a foreign component is made, that is, a component with a different target namespace from that of the referring component.

Two things are required: not only a means of addressing such foreign components but also a signal to schema-aware processors that a schema document contains such references:

The [import] element information item identifies namespaces used in external references, i.e. those whose QName identifies them as coming from a different namespace (or none) than the enclosing schema document's targetNamespace. The actual value of its namespace [attribute] indicates that the containing schema document may contain qualified references to schema components in that namespace (via one or more prefixes declared with namespace declarations in the normal way). If that attribute is absent, then the import allows unqualified reference to components with no target namespace. Note that components to be imported need not be in the form of a schema document; the processor is free to access or construct components using means of its own choosing.

The actual value of the schemaLocation, if present, gives a hint as to where a serialization of a schema document with declarations and definitions for that namespace (or none) may be found. When no schemaLocation [attribute] is present, the schema author is leaving the identification of that schema to the instance, application or user, via the mechanisms described below in [Layer 3: Schema Document Access and Web-interoperability]. When a schemaLocation is present, it must contain a single URI reference which the schema author warrants will resolve to a serialization of a schema document containing the component(s) in the [import]ed namespace referred to elsewhere in the containing schema document.

NOTE: 

Since both the namespace and schemaLocation [attribute] are optional, a bare <import/> information item is allowed. This simply allows unqualified reference to foreign components with no target namespace without giving any hints as to where to find them.

NOTE: 

The same namespace may be used both for real work, and in the course of defining schema components in terms of foreign components:

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:html="http://www.w3.org/1999/xhtml"
        targetNamespace="uri:mywork" xmlns:my="uri:mywork">

 <import namespace="http://www.w3.org/1999/xhtml"/>

 <annotation>
  <documentation>
   <html:p>[Some documentation for my schema]</html:p>
  </documentation>
 </annotation>

 . . .

 <complexType name="myType">
  <sequence>
   <element ref="html:p" minOccurs="0"/>
  </sequence>
  . . .
 </complexType>

 <element name="myElt" type="my:myType"/>
</schema>

The treatment of references as QName implies that since (with the exception of the schema for schemas) the target namespace and the XML Schema namespace differ, without massive redeclaration of the default namespace either internal references to the names being defined in a schema document or the schema declaration and definition elements themselves must be explicitly qualified. This example takes the first option -- most other examples in this specification have taken the second.

In addition to the conditions imposed on [import] element information items by the schema for schemas

1. 1. ifthe namespace [attribute] is present

      thenits actual value must not match the actual value of the enclosing [schema]'s targetNamespace [attribute].

   2. ifthe namespace [attribute] is not present

      thenthe enclosing [schema] must have a targetNamespace [attribute]

2. If the application schema reference strategy using the actual values of the schemaLocation and namespace [attributes], provides a referent, as defined by [Schema Document Location Strategy],

   1. The referent is (a fragment of) a resource which is an XML document (see [c-vxd]), which in turn corresponds to a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   2. The referent is a [schema] element information item in a well-formed information set, which in turn corresponds to a valid schema.

   In either case call the [schema] item SII and the valid schema I.

3. 1. ifthere is a namespace [attribute]

      thenits actual value must be identical to the actual value of the targetNamespace [attribute] of SII.

   2. ifthere is no namespace [attribute]

      thenSII must have no targetNamespace [attribute]

It is not an error for the application schema reference strategy to fail. It is an error for it to resolve but the rest of [c-ims] above to fail to be satisfied. Failure to find a referent may well cause less than complete assessment outcomes, of course.

The schema component (that is [type_definitions], [attribute_declarations], [element_declarations], [attribute_group_definitions], [model_group_definitions], [notation_declarations]) of a schema corresponding to a [schema] element information item with one or more [import] element information items must include not only definitions or declarations corresponding to the appropriate members of its [children], but also, for each of those [import] element information items for which [c-ims] above is satisfied, a set of schema component identical to all the schema component of I.

NOTE: 

The above is carefully worded so that multiple [import]ing of the same schema document will not constitute a violation of [c-nmd] of [Schema Properties Correct], but applications are allowed, indeed encouraged, to avoid [import]ing the same schema document more than once to forestall the necessity of establishing identity component by component. Given that the schemaLocation [attribute] is only a hint, it is open to applications to ignore all but the first [import] for a given namespace, regardless of the actual value of schemaLocation, but such a strategy risks missing useful information when new schemaLocations are offered.