How to : Make XSD2Code Work With CDA

January 2022

In the field of e-health, the use of exchange standards such as HL7/CDA is essential. CDA records can be used for a variety of purposes, including allowing clinicians to access patient data in an emergency context, biology reports, biomonitoring, patient access to their own data via a personal health record system, and medication or allergy review.

This complex structure imposes to the developers the implementation of complex and sometimes risky code in terms of quality of data processing.

Using XSD2Code++ ensures that the class structure generated reflects the structure of the CDA XML schema. We already introduce Clinical Document Architecture in a previous article. In this part we’ll go through how Xsd2Code’s parameters and flexibility can facilitate the task of handling CDA in your applications.

The first thing to do is to grab a fresh version of this XML Schema here. Then you need to import it in your Visual Studio project. You're now ready to run Xsd2Code++ :

Great, the code with the default settings is generated. You get a CDA_STDC.Designer.cs file containing about 250 classes and more than 20 000 lines of code in a few clicks.

We have now a default generated code, it compiles and everything seems fine 😊 to start processing data streams. But if you run code generation with default parameters, you’ll run inside numerous errors at runtime. Here are the pitfalls to avoid which we will explain to you step by step.

Serialization :

If you go through this guide, you probably want to read and write CDA based XML files. If so, activation of serialization related parameters is required to generate both serialization and deserialization associated methods. Learn more about serialization settings here.

Fine ! Let’s now try to load a file.

This exception occurs because CDA files contain circular dependency due to its conception.

As you can see in the schema above that POCD_MT000040_SDTC.xsd contains an HealthCareFacility element himself containing an Organization element. In this schema an Organization can be a part of an organization, so the OrganizationPartOf is referencing Organization element and enter in an infinite loop.With default parameters Xsd2Code++ will instanciate all the variables of this infinite loop causing this stack overflow exception.

But don’t worry Xsd2Code++ can get rid of this exception easily !

You just need to activate the LazyLoading option. It allows the program to only insatiate objects when they’re using for the first time. Learn more here.

Or you can also choose to not initialize fields automatically. Just set the InitializeFields setting on none. There is other options for this parameter that you can learn more here.

Now everything should work fine. Let’s dive into how make generated code more efficiency. First, we need to activate the CleanupCode option which will for instance reduce attribute names and remove unnecessary blank lines. It is really useful with CDA because generated file contains many characters. Learn more here.

Then for better documentation and comprehension we highly recommend you to activate summary comments. When doing this, all XSD annotations will be converted as commentaries tagged as “<summary>”. Learn more here.

While serializing readability and output flux controlling is an important aspect. A whole section called Should Serialize is dedicated to control if a certain type of data must be serialized or not. There is also parameters allowing you to format your output document as you wish. Here we decided indent with one space but we could have chosen to indent with tabulation, for example. Learn more here.

You can now click the generate button and all should be ready to work !

Example

Let’s go through an example implying a fake result report from an analysis laboratory. In this example we will create a really basic console application which querries some infromation about the laboratory and the patient. All code from this example can be downloaded on GitHub.

namespace CDA;
class Program
{
    static void Main(string[] args)
    {
        //Loading the document
        POCD_MT000040ClinicalDocument file = POCD_MT000040ClinicalDocument.LoadFromFile("XmlSchema\Library\Xsd2Code.XMLSchema.CDASample\xml\CR-BIO_2021.01_CDA-R2-Niveau-1.xml");
        
        //Querry patient name infos
        PN patientName = file.recordTarget[0].patientRole.patient.name.FirstOrDefault();

        //Querry author infos
        POCD_MT000040Person authorInfos = (POCD_MT000040Person) file.author[0].assignedAuthor.Item;
        
        //Querry adocument title
        var documentTitle = file.title.Text[0];

        string authorFullName = "";

        //Loop over author's name infos and assining it to a string
        foreach (var authorNameComponent in authorInfos.name[0].Items)
        {
            authorFullName += authorNameComponent.Text[0] + " ";
        }

        Console.WriteLine($"Document : {documentTitle} written by {authorFullName}");

        //Changing document title
        file.title.Text[0] = "Modified document title";

        //Saving our modified document to a new file
        file.SaveToFile("XmlSchema\Library\Xsd2Code.XMLSchema.CDASample\xml\CR-BIO_2021.01_CDA-R2-Niveau-1-modified.xml");
    } 
}