Extending HL7 v3 schemas using OASIS CAM and CAMProcessor

Create conformance templates and test messages for healthcare applications consistently and quickly

Traditionally, healthcare implementation projects use W3C XML Schema Definitions (XSDs) to define the Health Level Seven (HL7) messaging standard. By extending these schemas using the OASIS Content Assembly Mechanism (CAM), generating conformance messages becomes quicker and more reliable. The CAMProcessor, which is part of the jCAM open source project, makes this process of extension easy, so you can focus more business effort on the business rules underlying the HL7 schemas.


Piers Michael Hollott, Senior Consultant, Sierra Systems

Piers has worked in the software industry for 15 years, and specializes in Java development, XML technologies, and functional programming. He has contributed to several open source projects and is currently a consultant with Sierra Systems.

22 February 2011

Also available in Chinese Portuguese


Frequently used acronyms

  • IDE: Integrated development environment
  • ISO: International Organization for Standardization
  • OASIS: Organization for the Advancement of Structured Information Standards
  • W3C: World Wide Web Consortium
  • XML: Extensible Markup Language

The HL7 messaging standard seeks to provide an overarching structure to support all areas of the healthcare industry by generating and publishing sample W3C XSDs and models generated from an underlying cross-project object model. Other standardizing frameworks, such as the National Information Exchange Model (NIEM), place more reliance on the concepts of extension and restriction to facilitate adoption of new industries and practices. While I find it useful to effectively extend the published HL7 v3 schemas using the ISO Schematron validation language to supplement the original schema, I find that you can use the OASIS CAM, which relies heavily on extension and restriction, by itself for the same purpose. CAMProcessor (see Download), an open source Java™ implementation of CAM, provides an IDE to ingest, extend, and replace the HL7 release schemas. After you create a CAM template using CAMProcessor, you can easily generate a suite of conformance messages from this template.

Whenever a new HL7 messaging standard is released, implementors must make sense of it by analyzing the released XSDs and the underlying model. One of the products of this analysis is typically a suite of conformance messages, which represent the expected interactions and interoperability of the application that implements these interactions. In addition, it often is necessary to make changes to the XSDs to align them more closely with the underlying object model. This process is greatly simplified if you use the CAMProcessor tool to ingest and extend the release schemas into CAM templates. As I discuss later in this article, two areas that often require particular attention are cardinality and optionality, or conformance strength.

Extending a schema by ingesting an XSD

The tutorials available with the CAMProcessor project are useful in setting up the application and running it. Essentially, you ingest an XSD file by creating a new CAM template file from an existing XSD, then modify the file to exclude unnecessary elements and add attributes that might be absent from the XSD. After you create a CAM template, you can add annotations to supply sample data and export a hints file (or you can add sample data directly to the template). With a CAM template and hints file, you are able to create example files, which you can then use for conformance purposes.

For instance, in an HL7 message such as the ones included as sample files with this article, you might need to exclude value elements for coded items, add root and extension attributes, and exclude attributes that exist as artifacts of the generation process of the original XSD. You can set sample data in the Message Transport and Control Act wrappers (which envelope the message payload) in the template itself, whereas you should set sample data in the message payload using annotations kept in a separate hints file.

First, select a schema to ingest. Because HL7 schemas are composite, you might have many components to choose from. I am selecting a PRPM_IN306050CA schema, which defines a healthcare provider query. After you select a schema, you still need to select a root element within the schema. Typically, HL7 schemas have only a single root element to choose from, which has the same name as the interaction. Again, I select PRPM_IN306050CA, as you can see in Figure 1.

Figure 1. Selecting an XSD to ingest into CAMProcessor
Screen capture of selecting an XSD to ingest into CAMProcessor

For now, I use default settings for the remainder of the options. To do so, click OK, and, after a minute or so, you have created a CAM template from the XSD. You can click the OK link that appears in the Progress tab to open the new template. At this point, I recommend that you save a copy of the unmodified CAM template. After you do so, you can return to this template without needing to re-ingest the original XSD. You can see the unmodified CAM template in Figure 2.

Figure 2. The unmodified CAM template
Screen capture of the unmodified CAM template in the Structure tab

Extending and restricting attributes and elements

The next step in extending the original schema is to remove unnecessary attributes and elements that are artifacts of the generation of the original XSD schedule. For instance, I want to remove realmCode elements and InfraStructureRootAttributes, which I do not want in my final conformance messages.

To remove the realmCode element, select it in the Structure tab, which displays the CAM template, and from the context-sensitive right-click menu, select Add New Rule. In the Add New Constraint Wizard (see Figure 3), select excludeElement in the Action drop-down list, and because you want to exclude every occurrence of this element, clear the Parent check box, so that only the All check box is checked. CAMProcessor makes working with XPath easy.

Figure 3. Excluding a realmCode in the CAM template
Screen capture of excluding a realmCode in the CAM template

In the provider query CAM template, I remove every element from the queryByParameter element except the parameterList element because these elements belong in the response message, which is returned by an application after the query is made. These extraneous elements are present in the query message because common schema components are used for both the query and response XSD schemas. Excluding these elements is similar to excluding the other elements and attributes. I use the full XPath and excludeTree action to entirely exclude a single tree fragment. On the other hand, elements such as the controlActEvent should have optionality removed because they are always required.

Similarly, you can add the excludeAttribute action to exclude all the InfrastructureRootAttributes attributes in the document. Any elements that show %type=II% are instance identifiers—these are typically id or value elements. Unfortunately, while these elements should be identified using a root and extension, these are not present, so you add them by selecting the element in question, right-clicking, and selecting Add Child Attribute to add a root and an extension attribute (as in Figure 4). At the same time, you can edit the text of the id or value element to remove the sample text (%type=II%), leaving the element unpopulated with two attributes.

Figure 4. Adding a child attribute to the CAM template
Screen capture of New Atttribute dialog box to show adding a child attribute named 'root' to the CAM template

Injecting data using a hints file

You can set elements and attributes in the Message Transport and Control Act Wrapper sections directly in the default values set for the CAM template, as these are the same for each conformance message generated. At this point, you can generate a sample message, which contains a fully populated Message Transport and Control Act Wrapper and no data in the parameter list.

To generate a sample message, select Export Examples from the File Export menu. I chose to show none of the optional elements and no hints file (yet). Figure 5 shows the Generate Examples form with no hints file selected.

Figure 5. Exporting an example HL7 message from the CAM template
Screen capture of exporting an example HL7 message from the CAM template

All that remains now is to create a hints file to add some data to your query. To accomplish this task through the IDE, right-click an element or attribute and select Edit Annotations. Add a Value Tab to your annotation, along with a list of data elements, separated by and terminated with a pipe character (|), as in Figure 6. After you add annotations to any elements and attributes that require data in your conformance messages, you can export hints from the File menu. Now, when you export examples, you can supply this hints file, and your data is included in the exported messages.

Figure 6. Editing CAM annotations to add sample data
Screen capture of editing CAM annotations to add sample data

Dealing with HL7 cardinality and optionality

HL7 v3 conformance strengths range from Not Permitted and Optional, which represent elements that must not be present in a message and elements that need not be supported, to Required and Mandatory, which represent elements that must be supported but can be absent in a particular instance, and elements that must be supported and present regardless, respectively. In Canada, a conformance strength of Populated has been adopted to fill a gap between Required and Mandatory, representing an element that must be supported with data (it cannot be empty). Table 1 shows the HL7 v3 conformance strengths and actions that you can use to represent these elements in a CAM template.

Table 1. HL7 v3 conformance strengths
Conformance strengthDescriptionCAM rule
Not permittedThis element must never appear in a message. Applications can raise an error if they receive it.excludeElement
OptionalAn element that can be supported by applications if they choose. If not supported, the element must be ignored if received.either excludeElement or makeOptional, depending on vendor choice
RequiredAn element that must be supported by applications but will not necessarily be present in a particular message.makeOptional
PopulatedA populated element must be supported by applications and must always appear but can appear as an empty element with a null flavor (for example, nullFlavor="UNK" indicating that the required information is unknown).makeMandatory, makeNillable
MandatoryA mandatory element must be supported and must always appear with a non-null value.makeMandatory

The Populated conformance strength was adopted by Infoway, which maintains the HL7 standard in Canada, to differentiate between cardinalities of the form [0..N] and the form [1..N], both of which are Required. These elements are more than Required, but less than Mandatory. This distinction is inherent in the international standard but made more explicit in the pan-Canadian standard.

In the context of a clinical registry, this last conformance strength seems particularly obtuse: Either an element such as an address or middle name is present or not, and elements such as gender, last name, or personal identifier must always be present. The HL7 messaging standard, however, covers many areas outside of clinical registries, and in the context of pharmaceutical or diagnostic lab data, there is, of course, a vast difference between data that is absent because it is withheld for security reasons, data that is absent because it is unknown, and data that is absent because it indicates a diagnostic result of false. HL7 messaging needs to be able to account for all these scenarios, which leads to a proliferation of conformance strengths.

Differentiating conformance data using OASIS CAM

Some of the confusion around HL7 conformance strengths stems from the way they are implemented in the release schemas. It might be difficult to differentiate elements identified as Optional from those identified as Required solely from the XSD schemas, and in this case it becomes necessary to go back to the Model Interchange Format (MIF) file (also part of the release). Because OASIS CAM is more expressive than XSD, it better represents these conformance strengths as they might be applied in a healthcare application, as in Table 1.

Looking forward

After you use an OASIS CAM template to extend an existing XSD and create conformance messages based on this extension, it is possible to compress the CAM template (which removes all excluded items and trees) and create a new XSD from the template. This process is less potentially hazardous than making changes directly to the XSD and should support vendors and implementers who might want to experience some of the conformance benefits of the CAM approach but, at the end of the day, continue to use W3C XSDs.

For healthcare vendors and implementers who want to more fully embrace the CAM approach, however, it should be possible to extract information directly from the MIF depiction of an HL7 interaction (conveniently also stored in XML format) and inject these details into the ingested CAM templates so as to further extend them. This approach aligns the HL7 messaging standard more closely with the extension and restriction approach typified by the NIEM, while still staying true to the cross-disciplinary approach favored by HL7.


HL7 v3 is an evolving standard that can represent a moving target. To support multiple releases, it becomes necessary to recreate suites of conformance messages. By using the approach offered by CAMProcessor, you can find that you spend less time recreating the wheel, so you can spend more time focusing on the business logic underlying the messages you support. Alternatively, if you develop early-adopter functionality, that sort of approach can help you decouple yourself from the moving target, allowing you to adapt to the inevitable changes of working with an evolving standard.


Extended and Modified CAM Templatesdownloads.zip28KB



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into XML on developerWorks

Zone=XML, Industries, Open source
ArticleTitle=Extending HL7 v3 schemas using OASIS CAM and CAMProcessor