Parameterizing schemas

Saxon provides an extension to the standard XSD syntax that allows a schema to be parameterized. This is only useful if XSD 1.1 is enabled. The facility allows a parameter to be declared in a top-level annotation in the schema document, for example:

This declaration allows the variable $accepted-currencies to appear in any XPath expression appearing in the remainder of the same schema document. Typically it will be used in an assertion or in an expression controlling conditional type assignment, for example:

As with stylesheet parameters in XSLT, the as attribute defines the required type of the value (defaulting to item()*), and the select attribute supplies a default value. The expression determining the default value is evaluated during schema processing (that is, at "compile time"). The name of the parameter is a QName following the XSLT convention that no prefix means no namespace. The supplied value is converted to the required type using the function conversion rules, and validation fails if this is not possible.

It is important to supply a sensible default value since it will not always be possible to supply a value for the parameter. For example, if the variable is used in the assertion facet of a simple type, then a cast expression initiated from XSLT or XQuery will always use the default value for the parameter.

The scope of the declared variable is all XPath expressions appearing after the saxon:param element within the same schema document. All parameters within a schema must have distinct names. It is not at present possible to use one parameter across multiple schema documents (as a workaround, all types using the variable should appear in the same schema document).

On the Validate command line the parameters can be supplied in the form keyword=value, for example currency=EUR; more complex values can be supplied as XPath expressions, for example ?accepted-currencies=('USD','GBP','EUR') or +lookup-table=lookup-doc.xml.

Using the s9api interface from Java, parameter values can be supplied using the setParameter() method on the SchemaValidator object.

Using the Saxon.Api interface from C#, parameter values can be supplied using the SetParameter() method on the SchemaValidator object.

It is not currently possible to supply parameter values when using the JAXP interfaces to run a validation episode, or when invoking validation using the standard mechanisms in XSLT or XQuery. In this situation the default value will always be used. In the absence of the select attribute the default value is an empty sequence (whether or not this is a legal value according to the required type).

An extension function saxon:validate() is available to allow parameterized validation to be invoked from XSLT or XQuery. The first argument is the document or element node to be validated; the second argument is a map giving validation options, and the third argument is a set of values for any validation parameters, also supplied as a map (the keys will be of type xs:QName). If the second and/or third arguments are omitted, the effect is the same as if empty maps were supplied for these arguments.