[Deprecated] CDA Validation using Schematrons

Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation

This page describes how to perform a CDA document validation using the SChematron Validator tool which have been developed for the gazelle project :

Overview

CDA documents validation is performed using Schematrons. A Schematrons defines the requirements to be tested in a CDA document. Note that there are some other ways to perform CDA content validation. For instance on can use the CDA Tools from OHT. More information about the CDA tool can be found here. 

Due to limitation in time, we have not yet used the CDA Tools from OHT, however this tool is in our pipe line and we are investigating its use. 

How to perform a CDA document Validation

There are different ways to validating CDA documents using the :

  1. Using the Gazelle External Validation Service Front End. This tool provide a GUI to access the different validation services configured in the Gazelle plateform. For CDA validation is one of the services proposed by that tool.
  2. Download the Schematrons source code on your computer and perform the validation using an XSLT Processor. The Schematrons used by the External Validation Service Front End can be downloaded from the GUI
  3. Using the Schematron Validation Webservice. This solution might not be the easiest to implement, however it presents the advantage that it can be integrated in an application. 

How to get the current CDA schematrons

The Schematrons used by the EVS are available for download from the External Validation Service Front End GUI, under the menu : schematrons. The rest of this section is of interest for the readers who would like to understand the mechanism of creating a Schematron or reusing the templates that are available on the forge in order to develop validation Schematron for other CDA documents. 

The sources of Schematrons are available on the INRIA forge. Note that 

Importing the Schematron project

Here is the URL pointing the location of the Schematron project repository, you can use svn to import the project into your workspace.

Validation steps

To perform a validation of any of the documents which Schematron is available, you need to execute two actions :

  1. Generate the "dist" folder
  2. Validate the document

Generating the "dist" folder

To generate the "dist" folder you need to run the 'make-dist.sh' script, this shell script is classified under '/workspace/schematron/epSOS/tools'.

To run this script :

 ~/workspace/schematron/epSOS/tools$ ./make_dist.sh

After been generated the "dist" folder will contain the final preprocessed Schematrons which will be used to validate your documents.

You will notice that the CDA Schematrons are divided into two kind 

  • Pivot : The Schematrons in this folder uses epSOS pivot codes listed in the epSOS_MVC_V1_5.xls for the validation 
  • Friendly : The Schematrons in this folder doesn't use epSOS pivot codes for the validation

Validating the CDA document

Now that the Schematrons are available in the "dist", the validation of a document is done thanks to the 'validate.sh' script, this shell script is classified under '/workspace/schematron/epSOS/tools'.

To run this script :

~/workspace/schematron/epSOS/tools$ ./validate.sh ../dist/cda/pivot/ePrescription.sch ../src/cda/samples/ePrescription/ePSample.xml

The first argument of the 'validate.sh' script will be the preprocessed Schematron and the second argument will be the document to validate. The example above shows the command to validate an ePrescription sample with the ePrescription schematron. 

Validation result

The result of the validation will figure in the "test-doc.svrl" file, you'll just need to open that file to see the result.

In order to make the result of the validation more readable, a transformation from 'svrl' to 'html' is done in the 'validate.sh' script which will out come with an html file : 'results.html'.

 

 How does CDA validation works

Architecture

Here below the overall architecture of the project :

global architecture

The main used folders are :

src:Contains the necessary files for the validation of CDA, SAML, ATNA and  PRPA documents.

Source folder

 

Each of these folders (cda, saml, audit...) is organized as follows :

Source folder for CDA

  • samples : Contains valid samples (.xml)
  • sch : Contains the developed Schematrons (.sch)
  • xsd : Contains the used schema (.xsd)

table_data : Contains xml files that list the codes used for the validation.

tools : Contains all the libraries used to perfom the preprocessing of the Schematrons and the validation of the documents.

'Make_dist.sh' script 

This script is placed under '/workspace/schematron/epSOS/tools'.

The main goal of this script is to preprocess the developed Schematrons available under '/workspace/schematron/epSOS/src/*/sch' in order to build a consolidated one and make them available in the "dist" folder under '/workspace/schematron/epSOS/dist/'.

The preprocessing conssist mainly on :

  • Resolving inclusion
  • Reformating and indenting the schematrons
  • Building xsl from schematrons
  • Building the phases of the schematrons
  • Building friendly and pivot Schematrons (just for CDA)

'Validate.sh' script

This script is placed under '/workspace/schematron/epSOS/tools'.

The main goal of this script is to validate an xml documents thanks to a schematron.

Schematron val­i­da­tion takes four XSLT stages :

  • Pro­cess in­clu­sions
  • Pro­cess ab­stract pat­terns
  • Com­pile the schema
  • Val­i­date

The result of the validation is placed in the 'test-doc.svrl' file under '/workspace/schematron/epSOS/tools'.

Inclusion

The main goal of inclusion is to merge a number of XML information sets into a single composite infoset. In this project the inclusion is used to merge all the required schematron for the validation of a document in one Schematron file.

For example : An epSOS ePrescription document like all the CDA documents, contains different set of clinical informations. Every set of informations is represented by a 'templateId'. Every 'templateId' plays the role of a reference for the schematrons.

Almost every set of informations represented by a 'templateId' have a Schematron able of validating it.

Knowing that the ePrescription document (templateId 1.3.6.1.4.1.12559.11.10.1.3.1.1.1) must contain a Prescription Section (templateId 1.3.6.1.4.1.12559.11.10.1.3.1.2.1), and the Prescription Section, for his turn, shall include a Prescription Item Entry Content Module (templateId 1.3.6.1.4.1.12559.11.10.1.3.1.3.2)...The ePrescription Schematron which will be able to validate an ePrescription document, must include the Prescription Section schematron, and that last shall include the Prescription Item Entry Content Module schematron. 

Freemind map

A FreeMind map available in '/workspace/schematron/epSOS/docs' describe all the set up inclusion for the CDA documents. 

How to report a bug on CDA schematrons

Issues on CDA Schematrons can be reported in the Gazelle issue tracker available here.

How to develop / correct a schematron

Schematron is a ...

  • Well-formed XML document
  • Technique to specify and test statements about your XML document
    •  Elements
    • Attributes
    • Content

A Schematron specifies the checks to be performed on the tested CDA document, those tests are in fact a set of declarations for a process, it act like (test this, tell me that!). To perform the schematron's specifications, a Schematron processor is necessary :

  • It reads and interprets your Schematron tests
  • Applies the tests to your documents
  • Reports back with any messages

Schematron development environment

In order to get your Schematron up and running we propose two environments that you can download from Oxygen web site:

  • Oxygen XML plugin for Eclipse
  • Oxygen XML Editor

More informations about the Oxygen XML Editor are here.

Writing Schematron

The basic Schematronbuilding blocks are :

  • Phases : Activate different families called patterns. (ex: There's two phases for the validation of the CDA documents, the "pivot" and the "friendly" ) 
     
  • Patterns : Rules are grouped into families called Patterns. 
     
  • Rules : Tests are collected into rules, which apply to particular XML elements (context)
     
  • Assertions : Conditions to test, and are divided into two kind 
    • assert : If the condition is true, fine! If it is not, you get your message
    • report : If the condition is true, you get your message
  • Messages : the log you get back if the condition fail (assert), or succeed (report). We defined four kind of messages in this project. Messages starting with :
    • "Error:" are interpreted as error messages
    • "Success:" are interpreted as success messages
    • "Note:" are interpreted as note messages
    • "Warning:" are interpreted as warning messages

Using Phases

A phase is used to activate patterns (templates) so that they can perform a validation. To activate a pattern you simply need to declare it in a phase.

ex: Activating the pattern which id = p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-errors.

<phase id="all"> <active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-errors"/></phase>

In our case we create two kind of phases that we called 'all' and 'no-codes'. The phase we called 'all' is intended to perform a global validation, and so we have to declare in this phase all the patterns included by the Schematron (errors + warnings + notes + codes). On the other hand, the phase we called 'no-codes' is intended to perform a validation without using pivot codes, and so we have to declare in this phase all the patterns except the ones validating the pivot codes (errors + warnings + notes).

<phase id="all"> 
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-errors"/>
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-warnings"/>
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-notes"/>
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-codes"/>
</phase>
 <phase id="no-codes">
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-errors"/>
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-warnings"/>
<active pattern="p-1.3.6.1.4.1.12559.11.10.1.3.1.1.2-notes"/>
</phase>

 

The CDA templates performing pivot codes validation are placed under "schematron/epSOS/src/cda/sch/templates/codes".

The default Phase parameter "defaultPhase" defined in the Schematron is the one responsible of choosing which phase to perform while validation. We manipulate this parameter in the 'Make_dist' script in order to generate :

  • Schematrons using pivot codes validation under 'schematron/epSOS/dist/cda/pivot' by setting the "defaultPhase" to "all"
  • Schematrons not using pivot codes validation under 'schematron/epSOS/dist/cda/friendly' by setting the "defaultPhase" to "no-codes"

Using inclusion

The main goal of inclusion is to merge a number of XML information sets into a single composite infoset. 

In our case we use inclusion to merge all included patterns into a one final Schematron.

<xi:include parse="xml" href="templates/errors/1.3.6.1.4.1.12559.11.10.1.3.1.1.1.sch" xpointer="xmlns(x=http://purl.oclc.org/dsdl/schematron) xpointer(//x:pattern)"> 
<xi:fallback> 
<!-- xi:include error : file not found :  templates/errors/1.3.6.1.4.1.12559.11.10.1.3.1.1.1.sch -->   
</xi:fallback> 
</xi:include>

 The example shows the syntaxe we use to include the patterns available in the template "1.3.6.1.4.1.12559.11.10.1.3.1.1.1.sch" into the Schematrons who initiated this command.


PS: In order to use inclusion, you shall declare the following name space : "xmlns:xi="http://www.w3.org/2003/XInclude"