CDA Implementation Guides

Editing tips and notes

Return to master table of contents

1 CDA Overview

(content on separate page)

2 Introduction to CDA Technical Artifacts

(content on separate page)

3 CDA Document Exchange in HL7 Messages

(content on separate page)

4 CDA Implementation Guides

The Clinical Document Architecture defines a single logical schema, which may be used to instantiate any clinical document for exchange. CDA can be used, by itself, to create such documents, which then can be shared and read by recipients with no problem. However the true utility of CDA to improve interoperability, is only realized when the base CDA standard is further constrained to define specific types of documents, their expected sections and their associated processable clinical statements.

4.1 Benefits of Constraining CDA

There are a number of benefits derived from constraining CDA documents:

1. Specific types of documents can be defined, instantiated, exchanged and used (E.g. Consult Note, Procedure Note, Continuity of Care Document, ...)
2. Required and optional sections of a clinical document can be identified (E.g. Reason for Visit, Family History, ...)
3. Realm specific constraints and conventions can be identified (E.g. US Realm Header, US Address and Patient Naming, ...)
4. Required and optional entries (machine processable content) can be identified (E.g. Medication Entries, Problem Entries, ...)

In addition to serving as a useful guides for originators of CDA documents, CDA Implementation Guides with their associated templates can:

1. Be used to create new document types, by using reusable sections and clinical statement models from previously defined IGs.
2. Be used to improve consistency across documents, by reusing sections and clinical statement models from previous Implementation Guides.
3. Be used to validate document instance conformance to constraints and best practices (Machine Processable Conformance Testing)
4. Be used by consumers of CDA documents to aid in their processing of complex clinical content, thereby improving semantic interoperability.

The Architecture of CDA is demonstrated in the system of reusable constraint models (templates) which have been created, used and reused in various CDA Implementation Guides. Implementation Guides contain the constraints or expected additional conformance rules to be applied to document instances beyond those already defined within the CDA standard itself. As such, every CDA document expressing conformance to a template is still a CDA document, it simply asserts additional conformance to the constraints defined within a template.

4.2 CDA Implementation Guide Design

A typical CDA Implementation Guide will define the constraints used for one or more types of Clinical Documents. Some implementation Guides are for a single document type, while others are used to define sets of documents that share common features or use cases. Over time, a structure has been established for CDA Implementation Guides.

CDA Implementation Guides generally contain:

1. Introduction
2. Background Information
3. Header Templates
4. Document Templates
5. Section Templates
6. Entry Templates
7. Reusable Templates (Address, Name conventions, etc.)
8. Listing of all Templates
9. Listing of all Value Sets
10. Listing of All Code Systems
11. Appendices

Note that generally each element in the CDA Schema supports a templateId, therefore templates can be defined, as needed, anywhere they are required. An example exception is in the case of the "US Realm Address" template, where the <addr> element does not contain a templateId.

4.3 Templates on CDA

As can be seen, there are many kinds of templates that might be created. Among them, the most common are:

• Header-level templates: These templates constrain fields for parts of the CDA header, like the patient, the author, the service event or variants of participants. They are typically reused in multiple document templates, and enable greater consistency across document types.

• Document-level templates: These templates constrain fields in the CDA header, and define containment relationships to CDA sections. For example, a History and Physical document-level template might require that the patient’s name be present, and that the document contain a Physical Exam section.

• Section-level templates: These templates constrain fields in the CDA section, and define containment relationships to CDA entries. For example, a Physical Exam section-level template might require that the section/code be fixed to a particular LOINC code, and that the section contains a Systolic Blood Pressure observation. As defined by the templates standard containment constraints between a section and its entry are indirect in this standard,meaning that where a section asserts containment of an entry, that entry can either be a direct child or a further descendent of that section.

• Entry-level templates: These templates constrain the CDA clinical statement model in accordance with real-world observations and acts. For example, a Systolic Blood Pressure entry-level template defines how the CDA Observation class is constrained (how to populate observation/code, how to populate observation/value, etc.) to represent the notion of a systolic blood pressure.

• Other templates: Templates that exist to establish a set of constraints that are reused in the CDA document. These other templates are only used within another template, rather than on their own as a complete clinical statement. For example, US Realm Date and Time (DTM.US.FIELDED) includes a set of common constraints for recording time. This template is referenced several times with other templates used in the implementation guide. They reduce the need to repeat constraints in templates that use the common set.

4.3.1 Template Identifiers

Each template specified in a CDA Implementation Guide will have an associated template identifier. Those identifiers can be placed in a CDA instance via the "templateId" to indicate where it wants to assert conformance to a given template version. On the receiving side, the recipient can then not only test the instance for conformance against the CDA Extensible Markup Language (XML) schema, but also test the instance for conformance against asserted templates.

4.3.2 Template Versioning

A new version of an existing implementation guide, typically reuses templates from the previous version. During the ballot phase or update phase, templates carry the designation “Published” to indicate the template is unchanged from the previous version or “Draft” to indicate a new or revised template. Substantial revisions to previously published templates are indicated by the version number (V2, V3, etc.) in all phases: ballot, update, and published guides.

If there are no substantive changes to a template that has been successfully published, the template will carry the same templateId/@root (identifier oid) and templateId/@extension as in the previous implementation guide. (In the case of older templates, where the @extension attribute was not present, developers of new/updated Implementation Guides are encouraged to add an @extension attribute to these templates with an appropriate date.) During a new ballot or update phase, “Published” is appended to the main heading for the template to indicate that the template cannot be commented on in the ballot or update. The “Published” designation is removed in the final publication versions.

A revised version of a previously published template keeps the same templateId/@root as the previous version but is assigned a new templateId/@extension. In the US Realm, the @extension is populated with an common acknowledged creation date for all new and revised templates contained within the associated Implementation Guide. The accepted format is "YYYY-MM-DD". The notation “(Vn)” (V2, V3, etc.) is also added to the template name to assist human recognition of the template's version.

Versions are not necessarily forward or backward compatible. A versioning may be due to substantive changes in the template or because a contained template has changed. The “(Vn)” designation is persistent; it appears with that template when it is used in subsequent guides. During a new ballot or update phase, “Draft” is appended to the main heading for the template to indicate that it may be voted on in the ballot or commented on in the update; the “Draft” designation is removed in the final publication versions.

Structured Documents Working Group collaborated with Templates Working Group to establish template versioning recommendations, recently published in the following specification: HL7 Templates Standard: Specification and Use of Reusable Information Constraint Templates, Release 1. SDWG will leverage that specification to create guidance for template IDs and template versioning for future CDA implementation guides, including future versions of C-CDA, but that work is still in progress. The versioning approach described here is likely to be close to the final guidance, but has not been formally approved by SDWG for all implementation guides at this time.

Each version of a template has a status. For example, a template version can be draft, active, or deprecated, etc. The HL7 Templates DSTU describes the various status states that may apply to a template version over the course of its lifecycle. Each version of a template has an associated status. Thus, one version of a template may be deprecated, while a newer version of that template may be draft or active.

4.3.3 Open and Closed Templates

In open templates, all of the features of the CDA R2.1 base specification are allowed except as constrained by the templates. By contrast, a closed template specifies everything that is allowed and nothing further may be included.

Estimated Date of Delivery (templateId 2.16.840.1.113883.10.20.15.3.1) as defined in C-CDA R2.1 is an example of a closed template. Open templates allow implementers to specify additional content not specifically precluded by a given template's definition. HL7 encourages implementers to bring their use cases forward as candidate requirements to be formalized in a subsequent versions of a template to maximize the use of shared semantics.

4.4 Conformance Statements

Each template defined within a CDA Implementation Guide, will contain one or more conformance statements. The following represents an example of one way conformance constraints could be documented. Each conformance statement will have a conformance identifier, (CONF:####), identify a conformance verb, SHALL, SHOULD, MAY, etc.), identify the element or attribute that is the subject or context of the conformance constraint and define one or more constraint(s) to be imposed on that item. Constraints can specify cardinality, allowed use of nullFlavors, various types of attribute binding, inclusive of single code, value set and concept domain binding for code types and allowed specializations on data type usage. In general constrains can be used to ensure that implementers and receivers of CDA documents can share rich semantically processable information.

4.4.1 Conformance Verbs (Keywords)

The keywords SHALL, SHOULD, MAY, NEED NOT, SHOULD NOT, and SHALL NOT represent the set of conformance verbs that can be asserted on conformance statements. They are to be interpreted as described in the HL7 Version 3 Publishing Facilitator's Guide.

• SHALL: an absolute requirement
• SHALL NOT: an absolute prohibition against inclusion
• SHOULD/SHOULD NOT: best practice or recommendation. There may be valid reasons to ignore an item, but the full implications must be understood and carefully weighed before choosing a different course
• MAY/NEED NOT: truly optional; can be included or omitted as the author decides with no implications

The keyword "SHALL" allows the use of nullFlavor unless the requirement is on an attribute or the use of nullFlavor is explicitly precluded. When conformance statements are nested (or have subordinate clauses) the conformance statements are to be read and interpreted in hierarchical order. These hierarchical clauses can be interpreted as "if then, else" clauses. Thus...

a. This structuredBody SHOULD contain zero or one [0..1] component (CONF:1098-29066) such that it
  i. SHALL contain exactly one [1..1] Plan of Treatment Section (V2) 
  (identifier: urn:hl7ii:2.16.840.1.113883.10.20.22.2.10:2014-06-09) (CONF:1098-29067).

...is understood as:

a. It is recommended (SHOULD) that the structureBody contains a component.
  i. If the component exists, then it must contain a Plan of Treatment Section (V2),
  ii. else the component does not exist, and the conformance statement about the Plan of Treatment Section (V2)
      should be skipped.

In the case where the higher level conformance statement is a SHALL, there is no conditional clause. Thus...

b. This structuredBody SHALL contain exactly one [1..1] component (CONF:1098-29086) such that it
  i. SHALL contain exactly one [1..1] Problem Section (entries required) (V2)
    (identifier: urn:hl7ii:2.16.840.1.113883.10.20.22.2.5.1:2014-06-09) (CONF:1098-29087).

...means that the structuredbody is always required to have a Problem Section component.

4.4.2 Cardinality Constraints

The cardinality indicator (0..1, 1..1, 1..*, etc.) specifies the allowable occurrences within a document instance. The cardinality indicators are interpreted with the following format “m…n” where m represents the least and n the most:

• 0..1 zero or one
• 1..1 exactly one
• 1..* at least one
• 0..* zero or more
• 1..n at least one and not more than n

When a constraint has subordinate clauses, the scope of the cardinality of the parent constraint must be clear. In the next figure, the constraint says exactly one, participant is to be present, i.e., no less or more than one. The subordinate constraint specifies some additional characteristics of that participant.

1. SHALL contain exactly one [1..1] participant (CONF:2777).
    a. This participant SHALL contain exactly one [1..1] @typeCode="LOC" 
       (CodeSystem: 2.16.840.1.113883.5.90 HL7ParticipationType) (CONF:2230).

In the next figure, the constraint says only one participant “like this” is to be present. Other participant elements are not precluded by this constraint.

1. SHALL contain exactly one [1..1] participant (CONF:2777) such that it
   a. SHALL contain exactly one [1..1] @typeCode="LOC" 
      (CodeSystem: 2.16.840.1.113883.5.90 HL7ParticipationType) (CONF:2230).

4.4.2.1 Optional and Required with Cardinality

The terms optional and required describe the lower bound of cardinality as follows:

Optional means that the number of allowable occurrences of an element may be 0; the cardinality will be expressed as [0..1] or [0..*] or similar. In these cases, the element may not be present in the instance. Conformances formulated with MAY or SHOULD are both considered "optional" conformances.

Required means that the number of allowable occurrences of an element must be at least 1; the cardinality will be expressed as [m..n], where m >=1 and n >=1 (for example, [1..1] or [1..*]). In these cases, the element must be present in the instance. Conformance statements formulated with SHALL are required conformances. If an element is required but it is not known, the @nullFlavor attribute must be used.

4.4.2.2 Conformance using SHALL NOT and Cardinality

It is important to note that the expressions of cardinality in CDA conformance statements when associated with "SHALL NOT contain" will be expressed with a cardinality of [0..0] which represents a restatement of the constraint.

Diagnostic Imaging Report Example:

SHALL NOT contain [0..0] informant (CONF:1198-8410).

As noted in this example, no informant element shall be present in the header.

It is important to note, that not all SHALL NOT conformance statements are about whether an element is disallowed in a given context. Sometimes it is used to indicate other restrictions:

MethodCode SHALL NOT conflict with the method inherent in Observation / code (CONF:1098-8249).

In the following case, a Observation / Method Code used for Procedure Activity must not conflict with the method inherent in the Observation / Code used in the same observation instance.

4.4.3 Data Types

All data types used in a CDA document are defined in the "ITS: XML Data Types, Release 1", with the exception of ClinicalDocument.versionNumber which is modeled after "ITS:XML:Data Types, Release 2.1b", which enables backwards compatability with CDA R2. All attributes of a data type are allowed unless explicitly prohibited by implementation guides.

4.4.4 Vocabulary Binding

The templates in a CDA Implementation Guide can use terms from several code systems. These vocabularies are defined in various supporting specifications and may be maintained by other bodies, as is the case for the LOINC® and SNOMED CT® vocabularies.

4.4.4.1 Code Binding

Example: Single Code Binding

2. SHALL contain exactly one [1..1] code (CONF:15403).
   a) This code SHALL contain exactly one [1..1] @code="11450-4" Problem List (CONF:15408).
   b) This code SHALL contain exactly one [1..1] @codeSystem="2.16.840.1.113883.6.1"
       (CodeSystem: LOINC 2.16.840.1.113883.6.1 STATIC) (CONF: 31141).

The notation conveys the actual code (11450-4), the code’s displayName (Problem List), the OID of the codeSystem from which the code is drawn (2.16.840.1.113883.6.1), and the codeSystemName (LOINC).

HL7 Data Types Release 1 requires the codeSystem attribute unless the underlying data type is “Coded Simple” or “CS”, in which case it is prohibited. The displayName and the codeSystemName are optional, but recommended.

The above example would be properly expressed as follows.

Figure: XML Expression of a Single-Code Binding

or best practice recommendation:

4.4.4.2 Value Set Binding

Value set bindings should adhere to HL7 Vocabulary Working Group best practices, and include both an indication of stability and of coding strength for the binding. Value set bindings can be STATIC, meaning that they bind to a specified version of a value set, or DYNAMIC, meaning that they bind to the most current version of the value set. If a STATIC binding is specified, both the value set definition and the code system versions need to be specified. If a DYNAMIC binding is specified, the value set authority i.e. a URL for a service or page specifying the current values of the set SHALL be included, so implementers can access the current version of the value set. When a vocabulary binding binds to a single code, as previously depicted, the stability of the binding is implicitly STATIC.

 9. SHALL contain exactly one [1..1] value with @xsi:type="CD", where the code SHOULD be selected 
     from ValueSet Problem urn:oid:2.16.840.1.113883.3.88.12.3221.7.4 DYNAMIC (CONF:1198-9058).

Figure: XML Expression of a Value-Set Binding

   <value xsi:type="CD"  code="233604007"  codeSystem="2.16.840.1.113883.6.96"  displayName="Pneumonia" />

Note that value set identifiers (e.g., ValueSet Problem urn:oid:2.16.840.1.113883.3.88.12.3221.7.4 DYNAMIC) used in the binding definitions of template conformance statements do not appear in the XML instance of a CDA document. The definition of the template must be referenced to determine or validate the vocabulary conformance requirements of the template.

4.4.4.3 Concept Domains

Note: Concept domains are not directly implementable. They declare the conceptual semantic space to be used. Bindings to value sets or single codes must be specified in Implementation Guides to identify codes to be used.

A full discussion of the representation of vocabulary is outside the scope of this document; for more information, see the HL7 V3 Normative Edition 2010 sections on Abstract Data Types and XML Data Types R1.

4.4.5 Readable Conformance

The presentation of the conformance statements within a CDA Implementation Guide has slowly evolved over time. As all conformance requirements are typically captured using one of a number the profiling tools available, two patterns have established themselves within the industry. Tabular and narrative presentation models of representation are both currently in use. The HL7 Templates Standard: Specification and Use of Reusable Information Constraint Templates, Release 1 (DSTU) provides an excellent resource for those wanting to know more about templating and the current best practices.

4.5 Machine Processsable Conformance

When a CDA document instance is validated against the CDA R2.1 schema, it has demonstrated conformance to the CDA standard in its usage of XML proper elements and attributes as defined in the schema. There are additional conformance requirements, but in essence the document instance would likely be viewable using any one of a number of CDA stylesheet that are available for viewing CDA documents.

However, when a document instance is created which declares conformance to templates, it does so, by the inclusion of templateId identifiers. Thus, when a CDA document is received it can potentially be validated against the additional conformance claims defined within the identified templates. The ability to express conformance constraints in machine processable formats continues to evolve as more CDA tooling becomes available.

4.5.1 Benefits of Processable Conformance

One of the obvious benefits of having machine processable conformance with CDA documents, is the ability to perform automatic validation of the secondary conformance claims asserted in a given CDA document instance. This ability also enables the exchange of CDA documents which both can be read and processed to extract clinical statements as needed. Without additional conformance claims, and automated testing of those claims, receivers of CDA documents would have significant difficultly attempting to process discrete data.

4.5.2 Machine Processable Strategies

A number of different strategies have been employed in the automated validation of secondary conformance claims found in CDA Implementation Guides. In general, the choice of tool used to create an Implementation Guide will determine the means by which conformance will be validated. The typical strategies are:

1. Schematron - conformance statements are converted into a set of processable X-Path expressions which test conformance in a CDA instance using XSLT processing.
2. Java code - conformance statements are used to generate Java code which is used to read and validate the document instance into an object model.

5 CDA R-MIM

(content on separate page)

6 CDA Hierarchical Description

(content on separate page)

7 CDA XML Implementation

(content on separate page)

8 Appendix

(content on separate page)