Schema-Aware XQuery from the Command Line
To run a schema-aware query from the command line, use the usual command net.sf.saxon.Query. This has an option
-val:strict
to request strict validation of the source document, or
-val:lax
to request lax validation. This applies not only to the principal
source document loaded using the -s
option on the command line, but to all
documents loaded via the doc()
functions, or supplied as additional command line parameters in the form
+param=doc.xml
.
The schemas to be used to validate these source documents can be specified either by using
the import schema
declaration in the query prolog, or using
xsi:schemaLocation
(or xsi:noNamespaceSchemaLocation
)
attributes within the source documents themselves, or by using the -xsd
option
on the command line.
Validating the source document has several effects. Most obviously, it will cause the query
to fail if the document is invalid. It will also cause default values for attributes and
elements to be expanded, so they will appear to the query as if they were present on the
source document. In addition, element and attribute nodes that have been validated will be
annotated with a type. This enables operations to be performed in a type-safe way. This may
cause error messages, for example if you try to use an xs:decimal
value as an
argument to a function that expects a string. It may also cause some operations to produce
different results: for example when using elements or attributes that have been given a
list type in the schema, the typed value of the node will appear in the stylesheet as a
sequence rather than as a single string value.
The Enterprise Edition of Saxon also allows you to validate result documents (both final
result documents and intermediate results). By default, elements constructed by the query
are validated in lax mode, which means that they are validated if a schema declaration is
available, and are not validated otherwise. You can set a different initial validation mode
either using the declare validation
declaration in the Query Prolog, or by
issuing a call such as staticQueryContext.pushValidationMode(Validation.SKIP)
in the calling API.
The -outval:recover
option on the command line causes validation errors encountered in
processing a final result tree to be treated as warnings, allowing processing to continue.
This allows more than one error to be reported in a single run. The result document is
serialized as if validation were successful, but with XML comments inserted to show where
the validation errors were found. This option does not necessarily recover from all
validation errors, for example at present it does not recover from errors in uniqueness or
referential constraints.
By default, the validation context for element constructors in the query depends on the
textual nesting of the element constructors as written in the query. You can change the
validation context (and the validation mode) if you need to, by using a
validate{}
expression within the query. For details of this expression,
refer to the XQuery 1.0 specification. Validation of result documents is done on-the-fly,
so if the query attempts to produce invalid output, you will usually get an error message
that identifies the approximate location in the query where the error occurred.
With the Enterprise Edition of Saxon, declarations of functions and variables can refer to
schema-defined types, for example you can write let $a as
schema-element(ipo:invoice)* := //inv
. You can also use the
element()
and attribute()
tests to select nodes by their
schema type in path expressions.
Saxon-EE does a certain amount of static analysis of the XQuery code based on schema
information. For example, if a function argument is defined with a type such as
as="schema-element(invoice)"
, then it will check any path expressions used
in the function body to ensure that they are valid against the schema when starting from
invoice
as the context node. Similarly, if the result type of a function is
declared using an as
attribute, then Saxon will check any direct element
constructors in the body of the function to ensure that they are consistent with this
declared type. This analysis can reveal many simple user errors at compile time that would
otherwise result in run-time errors or simply in incorrect output. But this is only
possible if the source code explicitly declares the types of variables and of function
arguments and results.