XSLT 2.0 and XPath 2.0 Programmer's Reference, 4th Edition (183 page)

This use of

to customize the presentation produced by a stylesheet is very common. The rules in the importing stylesheet, which vary the standard presentation, are sometimes referred to as a
customization layer
. Another term used is
stylesheet overlay
. Sometimes the customization layer corresponds directly to an additional module in the schema or DTD: For example, if the schema that you use for press releases is an extended version of the schema used for general company documents, then you will want to write a customization layer over the general-purpose stylesheet to handle the additional features found in press releases.

See Also

on page 372

on page 237

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

If the

contains an inline schema (

element), then the
schema-location
attribute must be omitted.

Position

is a top-level declaration, which means that it must appear as a child of the

element. There are no constraints on its ordering relative to other declarations in the stylesheet.

Attributes

Content

The

element may contain an inline schema document, represented by an

element (whose content in turn is as defined in the XML Schema specification).

Effect

If the stylesheet contains references to user-defined types, then the namespace in which these types are defined must be imported using an

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.)

As with

, the

declaration states an intention to use schema components in a particular namespace, and it optionally gives a “hint” to the processor to indicate where definitions of those schema components may be found. You should explicitly import a schema document for every namespace that contains a definition that you want to refer to in the stylesheet. Importing a schema does not implicitly import other namespaces that are referenced from that schema using

.

The XSLT specification defines the way that schema import works in terms of the way that the XML Schema specification defines

. 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 “hint” in the
schema-location
attribute is used is therefore very open-ended.

Using an inline schema document is exactly the same as putting the schema in a separate XML document and referencing it in the
schema-location
attribute. It's convenient to have the schema inline, however, if it contains definitions that are used only within this stylesheet, perhaps to define the structure of some working data or some constraints on a particular function parameter. If an

declaration contains an inline schema document, then the
schema-location
attribute must be omitted. You can also omit the
namespace
attribute (if you don't, then it must match the
targetNamespace
of the inline schema).

In other cases, omitting the
namespace
attribute indicates that you want 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, and if there is no inline schema document, then it is assumed that the implementation will be able to locate a schema from knowledge of the target namespace alone.

It's not technically an error if no schema for the requested namespace can be found. But in practice this will usually trigger an error because the stylesheet will then contain references to schema definitions that haven't been imported.

It is a fatal error, however, if a schema can be found and it isn't valid according to the XML Schema specifications.

If there are multiple

declarations for the same target namespace (or for the “null namespace”), then the one with highest import precedence is used. Import precedence is explained under

on page 357. 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

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. Use of

can potentially cause problems if you use the base definitions to compile the stylesheet and then use a redefined version to validate the source document. The details, however, are left to the implementation.

If a processor that is not schema-aware encounters an

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

declaration itself, and any element that uses a
type
or
validation
attribute, or references a schema-defined type). Of course, you will also have to provide an alternative element for use in this case.