Ticket 468 - Validation Services Design

---

SYNOPSIS
========

This document describes the CIMreport class that has been implemented
as a solution to Ticket 468 in the MetaFor task tracker, available at:

http://metaforclimate.eu/trac/ticket/468

It should be noted that this information is provisional and refers to
code that is in development.  As such, subsequent versions of the code
may present a different interface to that described here.


BACKGROUND
==========

The purpose of this class is to enable the validation of XML CIM Records
and CIM Record sets.  Two levels of validation are performed:

(i) Syntactic validation, to ensure that the CIM Record is a correctly
structured XML file.

(ii) Schema validation, to ensure that the CIM Record contains meaningful
data which conforms to the specification described in an external XSD.


OPERATION
=========

The two operations of syntactic and schema validation are performed
successively.  In the event that a CIM Record is verified to be valid at
each of these stages, a brief description of the Record file is displayed
along with confirmation of its validity.  The first instance of an error
in either validation step results in the display of a textual description
of the error along with its location in the file.

In addition, syntactic validation alone may be performed on a CIM Record,
without any subsequent application of a schema.

Output from each of these operations can be rendered as either HTML, for
convenient reference, or as XML for subsequent processing.  In each case,
the output includes the hex digest of a SHA-1 hash performed on the CIM
Record's data which serves as a unique identifier of the validated document.


METHOD
======

The CIMreport class provides two constructors...

[1] CIMreport(filename)
[2] CIMreport(filename, schema)

...which are intended for use in syntactic and schema validation,
respectively.  The first parameter is the path to the CIM Record document to
be validated while the second specifies the schema against which validation
will be performed.

Once an instance of XMLreport has been created, the writeXMLParseReport() and
writeHTMLParseReport() methods may be invoked to display a report on the
syntactic validity of the CIM record at the path passed to the object on
construction.  If the specified path is invalid or the user lacks the required
permissions to read this file, the CIMreport object raises an IOError
exception.

Similarly, an CIMreport object constructed with a schema parameter may then be
used to generate schema validation reports using the
writeXMLValidationReport() and writeHTMLValidationReport() methods.  In
addition, a schema may subsequently be passed to an CIMreport object created
with the single parameter constructor using the setSchema() method.

The CIMreport class supports offline schema validation by way of a cache which
substitutes a local path to a schema for the URI of the equivalent schema when
this latter is encountered in the schemaLocation attribute of an XML document.
This local caching significantly speeds up validation in the case where an XML
document has a schema which is in turn dependent on one or more other schema
definitions, as is the case for the CIM schema.  The cache is implemented by
way of the 'schemacache' dictionary in the CIMreport class.  This has as its
keys the URIs of schemas and its values are the local paths that are to be
substituted for the former.  Use of the schema cache is enabled by default but
may disabled by setting the 'enableCache' attribute of an CIMreport object to
False.