saxon:validate

The saxon:validate extension function performs validation of a node against schema definitions, providing more control over the validation process than is available with standard XSLT and XQuery interfaces. For example, it allows validation parameters to be supplied, and it returns detailed information about the validation errors that were found (if any).

The first argument must be a document, element, or attribute node (the node to be validated). If an empty sequence is supplied, the function returns the empty sequence.

If the second and/or third arguments are omitted, the effect is the same as if empty maps were supplied for these arguments.

The second argument, $options, gives options for how the validation is to be performed. The entries that are recognized in this map are:

1. buildTree: which if present must have the value true() or false() or () (default is ()). The value () means that the tree that results from validation is returned if validation succeeds, and is not returned if validation fails. Setting this option to false() means that it will not be returned in either case. Setting it to true() means that the tree will be returned even if validation is unsuccessful. Note that in this case type annotations in the returned tree are unreliable. Note also that references to nodes in the returned error list relate to node in the input tree, not the result tree.

2. processContents: which must have the value strict or lax (default is strict). Indicates whether validation is strict or lax, according to the element name of the root element. The value is ignored if the type option is present.

3. type: whose value must be an xs:QName, being the name of a simple or complex type that is present in the schema at run-time; if present, this provides the name of the type against which the supplied node should be validated.

4. expandDefaults: which must have the value true() or false() (default is true()). Indicates whether the expansions of absent attributes and empty elements that have a schema-defined default value will be present in the returned tree.

The third argument, $params, gives values of schema parameters declared using the saxon:param XSD extension (see Parameterizing Schemas). The keys must be xs:QName values corresponding to the names of declared parameters, and the corresponding values are the values to be used for the parameters.

The schema used for validation consists of all the schema components already present in the configuration, plus any additional schema components loaded using the xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the instance being validated. The schema components present in the configuration include the following:

• Schema documents loaded using <xsl:import-schema> declarations in the stylesheet.

• Schema documents loaded using the -xsd option on the command line.

• Schema documents loaded during the validation of previous instance documents, by virtue of their xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes.

• Schema documents loaded using explicit API calls, for example to the s9api SchemaManager class.

The result of the function is a map. If validation succeeds, the map will contain two entries: "node" is the validated node, and "valid" is the boolean value true. If validation fails, the map will contain two entries: "valid" is the boolean value false, and "errors" is a list of error objects representing the validation errors that were found. Each error object is itself a map, with the following optional entries (all entries except message are optional, and will be present only if information is available):

1. message: A human-readable error message, as a string.

2. code: An error code, as an xs:QName.

3. specPart, constraint, clause: references to the XSD constraint that was violated, in the form of the XSD specification part number (1 or 2), the name of the constraint (e.g. "cvc-identity-constraint"), and the clause number within the constraint (e.g. "4.2.1").

4. node, path, lineNumber, columnNumber, systemId, publicId: information about the location of the error within the document or subtree being validated.