xsl:import-schema

<xsl:import-schema> is a top-level declaration used to identify a schema containing definitions of types that are referred to in the stylesheet. This declaration is available only in a schema-aware processor.

Changes in 2.0

This element is new in XSLT 2.0.

Format

 <xsl:import-schema   namespace? = uri-reference   schema-location? = uri-reference /> 

Position

<xsl:import-schema> is a top-level declaration, which means that it must appear as a child of the <xsl:stylesheet> element. There are no constraints on its ordering relative to other declarations in the stylesheet.

Attributes

Name	Value	Meaning
namespace optional	URI	The namespace URI of the schema to be imported
schema-location optional	URI	A URI identifying the location of the schema to be imported

Content

None; the element is always empty.

Effect

If the stylesheet contains references to user -defined types, then the schema in which these types are defined must be imported using an <xsl:import-schema> declaration. The same applies to user-defined element and attribute declarations.

Importing a schema makes the schema definitions available throughout the stylesheet, not only in the module where they are imported. (This differs from XQuery 1.0, where different modules may import different schemas.)

Importing a schema does not implicitly import other schemas that are referenced from that schema using <xs:import> , <xs:include> , or <xs:redefine> . You should explicitly import every schema document that contains a definition that you want to refer to in the stylesheet.

The XSLT specification defines the way that schema import works in terms of the way that the XML Schema specification defines <xs:import> . This leaves a great deal of discretion to the implementation. It is quite likely that an XSLT processor will want to cache schemas somewhere in a compiled form, to avoid analyzing them afresh every time a stylesheet is processed ; many systems may also use catalogs or data dictionaries of some kind so that a local copy of a schema can be accessed rather than retrieving it over the internet. The exact way in which the namespace and schema-location attributes are used is therefore very open -ended. In principle you can specify either or both of these attributes to identify a schema: The namespace attribute identifies it according to the namespace that the schema is defining (the targetNamespace attribute of the <xs:schema> element), while the schema-location attribute gives a "hint" as to where a copy of the schema might be found.

Although the terminology differs, this is not actually any different from the way the href attribute in <xsl:include> and <xsl:import> is handled. Reflecting common practice established with XSLT 1.0, the XSLT specification now recognizes that implementations can provide URI resolvers or catalogs to interpret these URIs, and that it is therefore impossible to be completely prescriptive about their interpretation.

If the namespace attribute is omitted, this acts as a request to import a schema that has no target namespace (that is, a schema for elements that are in no namespace). The namespace attribute should not be set to a zero-length string, since this is not a valid namespace URI.

If the schema-location attribute is omitted, then it is assumed that the implementation will be able to locate a schema from the knowledge of the target namespace alone.

Any failure that occurs during schema import (for example, failure to locate the requested schema, or an error in the schema itself) is treated as a compile-time error.

If there are multiple <xsl:import-schema> declarations for the same target namespace, then the one with highest import precedence is used. Import precedence is explained under <xsl:import> on page 314. If this leaves more than one, then the behavior is defined by reference to the XML Schema specification: It's defined to be the same as when a schema document contains more than one <xs:import> element for the same namespace. In practice, the schema specification leaves a lot of discretion to implementations on how to handle this. Some implementations may load multiple schema modules and check them for consistency; others (including Saxon) simply take the first one and assume that the others are equivalent.

Consistency rules for schemas extend beyond the question of multiple imports from a single stylesheet. The schema that's imported into the stylesheet must be consistent with the schema used to validate the source document. Since many systems will allow compiled schemas to be cached, probably sharing the cache between many different stylesheets, there is likely to be a more global consistency requirement. In general, it's probably not possible to have two different versions of the same schema (or to put it another way, two different schemas with the same target namespace, or with no target namespace) in use at the same time. The details, however, are left to the implementation.

If a processor that is not schema-aware encounters an <xsl:import-schema> declaration, it will report an error. If you want to write stylesheets that work with both schema-aware and non-schema-aware processors, you can achieve this by attaching the attribute «use-when=" system-property ('xsl:schema-aware')='yes')" » to any element that should be ignored by a non-schema-aware processor (that is, the <xsl:import-schema> declaration itself, and any element that uses a «type » or «validation » attribute, or references a schema-defined type).

Usage

It's not necessary to import every schema that has been used to validate an input document. You only need to import the schema if there is code in the stylesheet that actually references the names whose meaning is defined in the schema.

The places where such references may occur are as follows :

• In the type attribute of <xsl:element> , <xsl:attribute> , <xsl:copy> , <xsl:copy-of> , <xsl:document> , <xsl:result-document> , and the xsl:type attribute of literal result elements. This is always a QName identifying a top-level type definition, and unless it is one of the built-in types such as xs:integer , the schema in which the type is defined must be imported.

• In the as attribute of <xsl:variable> , <xsl:param> , <xsl: with-param > , <xsl:function> , and <xsl:template> . The value of this attribute is a description of an XPath type, and is expressed using the SequenceType syntax outlined in Chapter 4 (and described more fully in Chapter 9 of XPath 2.0 Programmer's Reference ). If the SequenceType references the name of an atomic type, this will be a QName identifying either a built-in type such as xs:date , or a top-level simple type definition in a schema. If the latter is the case, the schema must be imported. If the SequenceType uses the constructs «element (N, T) » or «attribute (N, T) » then the rules are slightly more complicated, and are described below.

• In an XPath expression anywhere in the stylesheet that uses a SequenceType . This construct is used in expressions such as «$x instance of T » or «$x treat as T » . The rules here are the same as for a SequenceType appearing in an as attribute, as described in the previous item.

• In an XPath expression that uses a constructor function for a user-defined atomic type (for example «mf:part-number ('PXW5792') » ) or a cast to a user-defined atomic type (for example «'PXW5792'cast as mf:part-number » ). In both these cases, the type name must be the name of a top-level simple type definition, and the schema containing this type definition must be imported.

• If you use the option «validation="strict" » or «validation="lax" » (or invoke this implicitly using the default-validation attribute on the <xsl:stylesheet> element), then you may be required to import the schema used to perform this validation, even if there are no explicit references in the stylesheet to the names defined in this schema. The XSLT specification leaves it open to the implementation to use other mechanisms to locate a schema at runtime to perform this validation, but if you import the schema explicitly, then you avoid any dependence on such mechanisms.

When the construct «schema-element (N) » or «schema-attribute (N) » is used in a SequenceType , then N must be the name of a global element or attribute declaration defined in an imported schema. Similarly, when the constructs «element (N, T) » or «attribute (N, T) » are used, then T must be the name of a simple or complex type defined in an imported schema, unless it is the name of a built-in type. But in these constructs the name N does not need to be present in the schema: this allows reference to local elements and attributes provided they have a global type definition.

For example, if you create an element like this:

  <temp xsl:type="xs:date">   <xsl:value-of select="current-date()    "/>    </temp>  

you will later be able to match this using:

  <xsl:if test="$p instance of element(temp, xs:date)">  

even though there is no imported schema defining the element name «temp » .

Examples

This example imports the schema for namespace « http://ns.megacorp.com/hr » from the location « http://schema.megacorp.com/hr/schema.xsd »:

  <xsl:import-schema   namespace = "http://ns.megacorp.com/hr"   schema-location = "http://schema.megacorp.com/hr/schema.xsd"/>  

The following example imports a no-namespace schema from the file «schema.xsd » in the same directory as the stylesheet:

  <xsl:import-schema   schema-location = "schema.xsd"/>  

The following example imports the schema that defines the structure of XSLT stylesheets. The XSLT processor is expected to know where to find this schema.

  <xsl:import-schema   namespace = "http://www.w3.org/1999/XSL/Transform"/>  

(This import would be useful only in a stylesheet that is designed to process XSLT stylesheets as its input and/or result documents.)