Saxon.Api

 

 

Saxon.Api

Class SchemaValidator

public class SchemaValidator
implements IDestination

A SchemaValidator is an object that is used for validating instance documents against a schema. The schema consists of the collection of schema components that are available within the schema cache maintained by the SchemaManager, together with any additional schema components located during the course of validation by means of an xsl:schemaLocation or xsi:noNamespaceSchemaLocation attribute within the instance document.

The SchemaValidator.Run method can be used either to validate a single document (supplied using SetSource()), or multiple documents (supplied using AddSource.

When validating a single document, if validation succeeds, the validated document can optionally be written to a specified destination. This will be a copy of the original document, augmented with default values for absent elements and attributes, and carrying type annotations derived from the schema processing. Saxon does not deliver the full PSVI as described in the XML schema specifications, only the subset of the PSVI properties featured in the XDM data model.

When validating multiple documents, they are validated in parallel (in multiple threads), and the validated documents are not made available. It is recommended in this case to use SetValidityReporting to capture any validation errors in a single XML report document.

If validation fails, an exception is thrown. This may indicate invalidity against the schema, or it might result from other conditions, such as an input document not being well-formed XML, or not existing.

Property Summary
 QName DocumentElementName

The name of the required top-level element of the document to be validated (that is, the name of the outermost element of the document). If no value is supplied, there is no constraint on the required element name.

 QName DocumentElementTypeName

The name of the required type of the top-level element of the document to be validated. QName of the name of the required type of the document element, or null if no value has been set. If no value is supplied, there is no constraint on the required type

 bool ExpendAttributeDefaults

Ask and set whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted) into the document during validation as if they were present in the instance being validated)

 IInvalidityHandler InvalidityHandler

Set the InvalidityHandler to be used when validating instance documents; the invalidity handler is called once at the start of validation, once for each validation failure, and once at the end.
 Action<ValidationFailure> InvalidityListener

Set the InvalidityListener to be used when validating instance documents; this is a simple delegate callback which is called once for each validation failure.
 bool Lax

The validation mode may be either strict or lax. The default is strict; this property is set to indicate that lax validation is required. With strict validation, validation fails if no element declaration can be located for the outermost element. With lax validation, the absence of an element declaration results in the content being considered valid.

 net.sf.saxon.s9api.Destination UnderlyingDestination

The underlying Saxon.Hej.s9api.Destination object in the Saxon implementation. Note that this property represents the schema validator itself as the destination of some other process (for example, a transformation whose output is to be validated); it must not be confused with the destination to which output is sent after validation, as set using the SetDestination() method.

 bool UseXsiSchemaLocation

This property defines whether the schema processor will recognize, and attempt to dereference, any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in the instance document. The default value is true.

 

Method Summary
 void AddSource (Stream source, Uri baseUri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

 void AddSource (Stream source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments. The base URI is taken as the current working directory.

 void AddSource (TextReader source, Uri baseUri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

 void AddSource (TextReader source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments. The base URI is taken as the current working directory.

 void AddSource (Uri uri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

 void AddSource (XmlReader reader)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

 void AddSource (XdmNode source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

 void Close ()

Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination

 XdmValue GetParameter (QName name)

Get the value that has been set for a schema processor (a parameter defined in the schema using the saxon:param extension)

 void OnClose (Action action)

Define an action to be performed when writing to the Destination is complete.

 void SetDestination (IDestination destination)

Supply the destination to hold the validated document. If no destination is supplied, the validated document is discarded.

 void SetParameter (QName name, XdmValue value)

Set the value of a schema parameter (a parameter defined in the schema using the saxon:param extension)

 void SetValidityReporting (IDestination destination)

Set the validation reporting feature, which saves the validation errors in an XML file
 void Validate (Stream source, Uri baseUri)

Validate an instance document supplied in the form of a Stream

 void Validate (Stream source)

Validate an instance document supplied in the form of a Stream. The base Uri of the document is taken as the current working directory.

 void Validate (TextReader source, Uri baseUri)

Validate an instance document supplied in the form of a TextReader

 void Validate (TextReader source)

Validate an instance document supplied in the form of a TextReader. The base Uri of the document is taken as the current working directory.

 void Validate (Uri uri)

Validate an instance document, supplied in the form of a Uri reference

 void Validate (XmlReader reader)

Validate an instance document, supplied in the form of an XmlReader.

 void Validate (XdmNode source)

Validate an instance document, supplied in the form of an XdmNode.

 void ValidateMultipleDocuments ()

Run the validation of a set of instance documents, previously supplied by calling AddSource.

 

Property Detail

DocumentElementName

public QName DocumentElementName {get; set; }

The name of the required top-level element of the document to be validated (that is, the name of the outermost element of the document). If no value is supplied, there is no constraint on the required element name.

DocumentElementTypeName

public QName DocumentElementTypeName {get; set; }

The name of the required type of the top-level element of the document to be validated. QName of the name of the required type of the document element, or null if no value has been set. If no value is supplied, there is no constraint on the required type

ExpendAttributeDefaults

public bool ExpendAttributeDefaults {get; set; }

Ask and set whether attribute defaults defined in a schema are to be expanded or not (by default, fixed and default attribute values are expanded, that is, they are inserted) into the document during validation as if they were present in the instance being validated)

InvalidityHandler

public IInvalidityHandler InvalidityHandler {set; }

Set the InvalidityHandler to be used when validating instance documents; the invalidity handler is called once at the start of validation, once for each validation failure, and once at the end.

InvalidityListener

public Action<ValidationFailure> InvalidityListener {set; }

Set the InvalidityListener to be used when validating instance documents; this is a simple delegate callback which is called once for each validation failure.

Previous versions of this API allowed validation failures to be gathered in a user-supplied list. This effect can be achieved by declaring List<ValidationFailure> ErrorList and setting the InvalidityListener property to ErrorList.Add.

Lax

public bool Lax {get; set; }

The validation mode may be either strict or lax. The default is strict; this property is set to indicate that lax validation is required. With strict validation, validation fails if no element declaration can be located for the outermost element. With lax validation, the absence of an element declaration results in the content being considered valid.

UnderlyingDestination

public net.sf.saxon.s9api.Destination UnderlyingDestination {get; }

The underlying Saxon.Hej.s9api.Destination object in the Saxon implementation. Note that this property represents the schema validator itself as the destination of some other process (for example, a transformation whose output is to be validated); it must not be confused with the destination to which output is sent after validation, as set using the SetDestination() method.

This property provides access to internal methods in the Saxon engine that are not specifically exposed in the .NET API. In general these methods should be considered to be less stable than the classes in the Saxon.Api namespace.

The internal methods follow Java naming conventions rather than .NET conventions.

Information about the returned net.sf.saxon.s9api.Destination object (and the objects it provides access to) is included in the Saxon JavaDoc documentation.

Value:

The underlying Destination object

UseXsiSchemaLocation

public bool UseXsiSchemaLocation {get; set; }

This property defines whether the schema processor will recognize, and attempt to dereference, any xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes encountered in the instance document. The default value is true.

Method Detail

AddSource

public void AddSource(Stream source,
Uri baseUri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

Parameters:

source - Source document supplied as a Stream
baseUri - Base URI of the source document

AddSource

public void AddSource(Stream source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments. The base URI is taken as the current working directory.

Parameters:

source - Source document supplied as a Stream

AddSource

public void AddSource(TextReader source,
Uri baseUri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

Parameters:

source - Source document supplied as a TextReader
baseUri - Base URI of the source document

AddSource

public void AddSource(TextReader source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments. The base URI is taken as the current working directory.

Parameters:

source - Source document supplied as a TextReader

AddSource

public void AddSource(Uri uri)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

Parameters:

uri - URI of the source document

AddSource

public void AddSource(XmlReader reader)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

Parameters:

reader - Source document supplied as an XmlReader

AddSource

public void AddSource(XdmNode source)

Add an instance document to the list of documents to be validated by a subsequent call on ValidateMultipleDocuments.

Parameters:

source - Source document supplied as an XdmNode value

Close

public void Close()

Close the destination, allowing resources to be released. Saxon calls this method when it has finished writing to the destination

GetParameter

public XdmValue GetParameter(QName name)

Get the value that has been set for a schema processor (a parameter defined in the schema using the saxon:param extension)

Parameters:

name - the parameter whose name is required

Returns:

the value that has been set for the parameter, or the EmptySequence if no value has been set

OnClose

public void OnClose(Action action)

Define an action to be performed when writing to the Destination is complete.

Parameters:

action - The action to be performed.

SetDestination

public void SetDestination(IDestination destination)

Supply the destination to hold the validated document. If no destination is supplied, the validated document is discarded.

The destination differs from the source in that (a) default values of missing elements and attributes are supplied, and (b) the typed values of elements and attributes are available. However, typed values can only be accessed if the result is represented using the XDM data model, that is, if the destination is supplied as an XdmDestination.

Parameters:

destination -  The destination to hold the validated document.

SetParameter

public void SetParameter(QName name,
XdmValue value)

Set the value of a schema parameter (a parameter defined in the schema using the saxon:param extension)

Parameters:

name - the name of the schema parameter, as a QName
value - the value of the schema parameter, or null to clear a previously set value

SetValidityReporting

public void SetValidityReporting(IDestination destination)

Set the validation reporting feature, which saves the validation errors in an XML file

Parameters:

destination -  destination where XML will be sent

Validate

public void Validate(Stream source,
Uri baseUri)

Validate an instance document supplied in the form of a Stream

Parameters:

source - A stream containing the XML document to be parsed and validated. This stream will be consumed by the validation process, but it will not be closed after use: that is the responsibility of the caller.
baseUri - The base URI to be used for resolving any relative references, for example a reference to an xsi:schemaLocation

Validate

public void Validate(Stream source)

Validate an instance document supplied in the form of a Stream. The base Uri of the document is taken as the current working directory.

Parameters:

source - A stream containing the XML document to be parsed and validated. This stream will be consumed by the validation process, but it will not be closed after use: that is the responsibility of the caller.

Validate

public void Validate(TextReader source,
Uri baseUri)

Validate an instance document supplied in the form of a TextReader

Parameters:

source - A TextReader that supplies the XML document to be parsed and validated. This reader will be consumed by the validation process, but it will not be closed after use: that is the responsibility of the caller.
baseUri - The base URI to be used for resolving any relative references, for example a reference to an xsi:schemaLocation

Validate

public void Validate(TextReader source)

Validate an instance document supplied in the form of a TextReader. The base Uri of the document is taken as the current working directory.

Parameters:

source - A TextReader that supplies the XML document to be parsed and validated. This reader will be consumed by the validation process, but it will not be closed after use: that is the responsibility of the caller.

Validate

public void Validate(Uri uri)

Validate an instance document, supplied in the form of a Uri reference

Parameters:

uri - URI of the document to be validated

Validate

public void Validate(XmlReader reader)
throws
SaxonApiException

Validate an instance document, supplied in the form of an XmlReader.

The XmlReader is responsible for parsing the document; this method validates it.

Parameters:

reader - The XmlReader used to read and parse the instance document being validated. This is used as supplied. For conformance, use of a plain XmlTextReader is discouraged, because it does not expand entity references. This may cause validation failures.

Throws:

SaxonApiException - Throws an exception if the document is found to be invalid (and also on other conditions like a failure to read the source document)

Validate

public void Validate(XdmNode source)
throws
SaxonApiException

Validate an instance document, supplied in the form of an XdmNode.

The supplied node must be either a document node or an element node. If an element node is supplied, then the subtree rooted at this element is validated as if it were a complete document: that is, it must not only conform to the structure required of that element, but any referential constraints (keyref, IDREF) must be satisfied within that subtree.

Parameters:

source - The document or element node at the root of the tree to be validated

Throws:

SaxonApiException - Throws an exception if the document is found to be invalid (and also on other conditions like a failure to read the source document)

ValidateMultipleDocuments

public void ValidateMultipleDocuments()

Run the validation of a set of instance documents, previously supplied by calling AddSource.

Unless multithreading has been disabled at Processor level, the instance documents are validated in parallel in multiple threads.

This requires care when deciding how invalidity should be reported: the recommended option is to generate an XML validation report by calling SetValidityReporting.

The validated documents (with type annotations and expanded defaults: that is, the PSVIs) are not made available to the calling application.

The method does not throw an exception if any of the source documents is found to be invalid. It does however throw an exception if any of the source documents cannot be read, or is not well-formed XML. (This method can therefore be useful even when there is only one document to be validated, to avoid the exception condition.)