In any module, there is a set of in-scope schema definitions (ISSDs) that can be referenced within the query. This includes type definitions, element declarations and attribute declarations. They can describe the input documents, the result XML, or both. You may want to reference schema definitions for a number of reasons, such as:
To write functions that only accept values of a certain user-defined type. For example, a function that queries sleeve length might accept only elements of type
ShirtType.To validate a node that you constructed in your query. For example, you used constructors to create a
productelement and its children, and you want to ensure that it is valid according toProductType.To determine whether a value is an instance of a particular user-defined type in order to decide how to process it. For example, if the
sizevalue is an instance ofShirtSizeType, you want to call one function, whereas if it is a value ofHatSizeType, you want to call a different function.You want to perform static type analysis and you want the schema definitions to be taken into account.
If you don't need to do any of these things, you are not required to include your schemas in the in-scope schema definitions. This is true even if your input document was validated against a schema.
Definitions for the built-in types are automatically included in the ISSD. A processor may include additional schema declarations and definitions in the ISSD according to implementation-defined rules. For example, it may have a set of built-in schemas that are always present. Processors that support schema validation may add definitions from the schema with which an input document is validated. Additionally, some implementations will allow you to specify programmatically or as a parameter—outside the scope of the query—what schemas to import.
A schema import is used in XQuery to add a schema to the ISSD for a module. When a schema is imported, all of its global element and attribute declarations and type definitions are added.
A schema import, which appears in the query prolog, specifies the target namespace and, optionally, the schema location. For example:
import schema "http://datypic.com/prod"
at "http://datypic.com/prod.xsd";imports the schema document at http://datypic.com/prod.xsd whose target namespace is http://datypic.com/prod.
The syntax of a schema import is shown in Figure 13-1. The schema location and namespace must be literal values in quotes (not evaluated expressions), and they should be syntactically valid absolute URIs.
For convenience, it is also possible to include a namespace declaration as part of the schema import. For example:
import schema namespace prod = "http://datypic.com/prod"
at "http://datypic.com/prod.xsd";maps the prod prefix to the namespace, in addition to importing it. Additionally, a default namespace declaration can be included in a schema import, as in:
import schema default element namespace "http://datypic.com/prod"
at "http://datypic.com/prod.xsd";This has the effect of making http://datypic.com/prod the default element namespace, in addition to importing the schema with that target namespace.
If the at keyword and schema location are left off, it is assumed that the processor knows where to locate the schema for the specified namespace. It is also legal for the processor to ignore the location provided if it has another method of locating the schema.
Schema import is an optional feature that is not supported by all implementations.
If the imported schema has no target namespace, a zero-length string should be used for the target namespace, as in:
import schema "" at "http://datypic.com/prod.xsd";
In order to reference any of the element or type names in that schema, you must make the default namespace the zero-length string (""). You can do this using the same syntax described in the previous section:
import schema default element namespace ""
at "http://datypic.com/prod.xsd";Multiple schema imports can appear in the query prolog, but only one per namespace. To specify multiple schema documents with the same target namespace, use a single schema import with multiple schema locations separated by commas, as in:
import schema "http://datypic.com/prod"
at "http://datypic.com/prod.xsd",
"http://datypic.com/prod2.xsd";When importing a library module into your query, it is important to understand that a module import only imports the function and variable declarations of the library module. It does not automatically import the schemas that are imported in the prolog of the library module.
For example, suppose you have a library module called strings.xq that imports a schema named stringtypes.xsd. When the main module imports strings.xq, the stringtypes.xsd definitions are not automatically added to the in-scope schema definitions of the main module. If the main module needs to refer directly to any of the types or declarations of stringtypes.xsd, it must import that schema explicitly in its prolog.
In addition, the main module must import stringtypes.xsd if it uses any variables or functions from strings.xq that depend on a type definition from the schema. For example, suppose strings.xq contains the variable declaration:
declare variable $strings:LetterA as strings:smallString := "A";
where smallString is a user-defined type defined in stringtypes.xsd. The main module must import the stringtypes.xsd schema if it uses the LetterA variable. This does not apply to the built-in types, such as xs:integer or xs:string, whose definitions are always in scope.