HL7 V3 Datatypes Implementation Notes

Introduction

This page provides some discussion about the HL7 V3 data types, and their XML representation. It is not constrained to a particular IHE profile, but it is hopefully useful to implementers of any CDA Release 2 based content profile, or any integration profile using HL7 V3 messages.

Background

The HL7 V3 data types are defined as an abstract specification, part of the HL7 V3 standard. The current version is Release 1, with Release 2 being in the final stages of development. This discussion is strictly about Release 1 of the HL7 V3 data types.

The abstract data types specification defines the properties of the data types. The XML Implementable Technology Specification (XML ITS) defines how the data types are represented in XML. HL7 publishes XML schemas for the V3 data types, which express most of the properties defined in the abstract specification, however certain rules are impossible to define using the XML schema language. This is one of the reasons that the schemas published by HL7 are informative artifacts, and are not sufficient to implement the full semantics of the V3 data types.

The schemas provided by HL7 are part of the V3 normative editions. The ones part of the 2008 Normative Edition are at ftp://ftp.ihe.net/TF_Implementation_Material/ITI/schema/HL7V3/NE2008/coreschemas/

Implementation notes

The HL7 V3 Data Types specification is one of the more stable and robust parts of the HL7 V3 standard. For anyone tasked with implementing and supporting HL7 V3 messaging, or CDA Release 2 document creation or processing, it will be quite useful to have a single common reusable implementation of the HL7 V3 data types.

The abstract implementation describes the relationships among the various data types, and the XML ITS tries to follow these relationships as close as possible. The HL7 V3 data types have rich semantics, and this results in a quite complicated schema, and also in a complex object-oriented implementation. Note that HL7 has an additional [UML ITS for the HL7 V3 data types], which may be useful for certain development environments, and the HL7 RIM Based Application Architecture (RIMBAA) workgroup has a [Java-based implementation for V3 data types] as part of its Java API for the V3 RIM.

While all major development platforms have tools to automatically generate code based on XML schema, most are not sophisticated enough to properly handle the recursive definitions and generic type extensions used by the HL7 V3 data types. To illustrate this point the following sections will go through the definition of a particular data type to see how its properties are defined.

The Starting Point

The following question was asked on the 2009 NA Connectathon mailing list:

according to the basic schema datatypes-base.xsd, an element of type EN may have sub-elements 
like given, family, prefix and so on.
 
now,
 - "given" is of type "en.given"
 - "en.given" restricts "ENXP"
 - "ENXP" extends "ST"
 - "ST" restricts "ED"
 - "ED" extends "BIN"
 - "BIN" extends "ANY"
 - "ANY" doesn't restrict or extend anything

question: which XMLSchema simple type has to be used for "given"?

In order to answer the question, let's follow the steps of the definition of an element of type en.given.

Defining an XML Element

The simplest element definition in an XML schema may look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:example:org" targetNamespace="urn:example:org">
<xs:element name="el1"/>
</xs:schema>

This simply defines an element with name el1, which belongs to the urn:example:org namespace. No other restrictions or properties are defined for this element. A minimal XML document, consisting only of this element may look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!--  We can have just the element here -->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample1.xsd"/>

Since there were no restrictions placed on the element in the schema, it can have text content, and any number of attributes or child elements:

<?xml version="1.0" encoding="UTF-8"?>
<!--  We can have the element with content-->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample1.xsd">Some content</el1>

<?xml version="1.0" encoding="UTF-8"?>
<!--  We can have the element with arbitrary attributes-->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample1.xsd" attr1="1"/>

<?xml version="1.0" encoding="UTF-8"?>
<!--  We can have the element even with arbitrary child elements-->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample1.xsd"><el2/></el1>

<?xml version="1.0" encoding="UTF-8"?>
<!--  We can have the element with arbitrary attributes, child elements and mixed content-->
<el1 xmlns="urn:example:org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample1.xsd" attr1="1">
    <el2/>
    Some text
    <el3>some other text</el3>
    more text
    <el4/>
</el1>

All of the above examples are valid with respect to the schema.

Defining a Schema Type

If we take the definition of the ANY data type from the HL7 V3 schema, and remove the abstract attribute, we can see what will happen if we define our element to be of the ANY data type. The schema will be something like this:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:example:org"
    targetNamespace="urn:example:org">
    <xs:element name="el1" type="ANY"/>
     <!-- This definition of the ANY data type is identical to the one in the HL7 datatypes-base.xsd schema,
     except that it is not defined as an abstract data type. This allows the associated examples to illustrate
     the effect of defining a complex data type for an element -->
    <xs:complexType name="ANY">
        <xs:annotation>
            <xs:documentation> Defines the basic properties of every data value. This is an abstract
                type, meaning that no value can be just a data value without belonging to any
                concrete type. Every concrete type is a specialization of this general abstract
                DataValue type. </xs:documentation>
        </xs:annotation>
        <xs:attribute name="nullFlavor" type="NullFlavor" use="optional">
            <xs:annotation>
                <xs:documentation> An exceptional value expressing missing information and possibly
                    the reason why the information is missing. </xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:complexType>
    <xs:simpleType name="cs">
        <xs:annotation>
            <xs:documentation> Coded data in its simplest form, consists of a code. The code system
                and code system version is fixed by the context in which the value occurs. is used
                for coded attributes that have a single HL7-defined value set. </xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:token">
            <xs:pattern value="[^\s]+"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="NullFlavor">
        <xs:annotation>
            <xs:documentation>vocSet: T10609 (C-0-T10609-cpt)</xs:documentation>
        </xs:annotation>
        <xs:union memberTypes="NoInformation"/>
    </xs:simpleType>
    <xs:simpleType name="NoInformation">
        <xs:annotation>
            <xs:documentation>specDomain: S10610 (C-0-T10609-S10610-cpt)</xs:documentation>
        </xs:annotation>
        <xs:union memberTypes="Other Unknown">
            <xs:simpleType>
                <xs:restriction base="cs">
                    <xs:enumeration value="NI"/>
                    <xs:enumeration value="MSK"/>
                    <xs:enumeration value="NA"/>
                    <xs:enumeration value="UNC"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:union>
    </xs:simpleType>
    <xs:simpleType name="Other">
        <xs:annotation>
            <xs:documentation>specDomain: S10616 (C-0-T10609-S10610-S10616-cpt)</xs:documentation>
        </xs:annotation>
        <xs:restriction base="cs">
            <xs:enumeration value="OTH"/>
            <xs:enumeration value="NINF"/>
            <xs:enumeration value="PINF"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="Unknown">
        <xs:annotation>
            <xs:documentation>specDomain: S10612 (C-0-T10609-S10610-S10612-cpt)</xs:documentation>
        </xs:annotation>
        <xs:union memberTypes="AskedButUnknown">
            <xs:simpleType>
                <xs:restriction base="cs">
                    <xs:enumeration value="UNK"/>
                    <xs:enumeration value="QS"/>
                    <xs:enumeration value="NASK"/>
                    <xs:enumeration value="TRC"/>
                </xs:restriction>
            </xs:simpleType>
        </xs:union>
    </xs:simpleType>
    <xs:simpleType name="AskedButUnknown">
        <xs:annotation>
            <xs:documentation>specDomain: S10614
            (C-0-T10609-S10610-S10612-S10614-cpt)</xs:documentation>
        </xs:annotation>
        <xs:restriction base="cs">
            <xs:enumeration value="ASKU"/>
            <xs:enumeration value="NAV"/>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

The bulk of the schema is taken by the vocabulary definitions of the allowable values for the single attribute, nullFlavor, defined by the ANY data type. Besides this new optional attribute, nothing else is defined for this data type, but this actually implies certain things about it.

The first example shows the use of the optional nullFalvor attribute:

<?xml version="1.0" encoding="UTF-8"?>
<!--  el1 is now of type ANY which means that the only valid addition to the element is the nullFlavor attribute -->
<el1 xmlns="urn:example:org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample2.xsd" nullFlavor="OTH"/>

There is nothing in the definition of the ANY data type describing the content of an element of this data type. This lack of description, however, implies that there is no content allowed (i.e. it defines an empty content model). The following examples are invalid for various reasons:

<?xml version="1.0" encoding="UTF-8"?>
<!-- el1 is now of type ANY, which has an empty content type, so no text content is allowed. Therefore this example is invalid -->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample2.xsd">Some content</el1>

<?xml version="1.0" encoding="UTF-8"?>
<!--  el1 is now of type ANY, which has only one defined attribute, "nullFlavor", so no other attributes are allowed. Therefore this example is invalid -->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample2.xsd" attr1="1"/>

<?xml version="1.0" encoding="UTF-8"?>
<!--  el1 is now of type ANY, which has an empty content type, so no chldren are allowed. Therefore this example is invalid -->
<el1 xmlns="urn:example:org"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample2.xsd"><el2/></el1>

<?xml version="1.0" encoding="UTF-8"?>
<!--  el1 is now of type ANY, which has an empty content type, so no chldren, text content, or attributes (other than nullFlavor) are allowed. 
    Therefore none of the additional XML attributes or children are valid -->
<el1 xmlns="urn:example:org" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:example:org sample2.xsd" attr1="1">
    <el2/>
    Some text
    <el3>some other text</el3>
    more text
    <el4/>
</el1>