Brian Weiss

About Brian Weiss

CDA PRO Founder

Intervals in CDA

Throughout the XML hierarchy of a CDA document, there are XML elements that capture an interval or range of something. For example, some elements capture time intervals, others capture ranges of physical quantities, and some just capture a numeric range.

The XML syntax for such “interval elements” in CDA is based on the use of sub-elements that describe the range. A simple example of a numeric range might be:

<repeatNumber>
   <low value="1"/>
   <high value="3"/>
</repeatNumber>

to represent the range of values from 1 to 3.

Interval Sub-Elements
There are four sub-elements that can be used with an XML element that represents a range: low, high, width, and center. They can be combined as follows:

  • low and high
  • low and width
  • width and high
  • center and width

Unbound Intervals
If a sub-element is left out, it is equivalent to using it with the attribute nullFlavor set to “NI”. Refer to The nullFlavor attribute, for additional information. The missing element is assumed to be “unbounded”. So, either of the following can be used to indicate a range “greater than 1″ with no upper limit:

<repeatNumber>
   <low value="1"/>
</repeatNumber>

or

<repeatNumber>
   <low value="1"/>
   <high nullFlavor="NI"/>
</repeatNumber>


Any of the four sub-elements can be used alone in this way to represent an unbound range. Note that if center or width are used alone, neither the low or high bound of the range is known, only the total size of the range (if width is used alone) or the midpoint of the range (if center is used alone).

The inclusive Attribute
The inclusive attribute can be used with either the low or high sub-element, to indicate that the endpoint is inclusive of the stated value in the value attribute. For integer ranges, this works rather intuitively. In this example:

<repeatNumber>
   <low value="1" inclusive="false"/>
   <high value="3" inclusive="false"/>
</repeatNumber>

only the number 2 would be included, whereas in this example:

<repeatNumber>
   <low value="1" inclusive="true"/>
   <high value="3" inclusive="true"/>
</repeatNumber>

the numbers 1, 2, and 3 are all included.

The default value for inclusive is “true”.

Refer to The inclusive attribute for additional information and refer also to A very common mistake with date ranges for a subtle aspect of how the inclusive attribute is used with date ranges.

Explicit Use of the xsi:type Attribute
The article What is the role of the xsi:type attribute in CDA?, explains how the special xsi:type attribute is used to make it clear which XML Schema datatype is intended, when it would otherwise be ambiguous.

In some contexts in CDA, the datatype of an XML element that represents a range or interval, is explicitly set. For example, the repeatNumber element used in sample code above is explicitly set by the CDA XML Schema as being of type IVL_INT which is an integer range.

However, in other contexts, more than one type of interval […]

Jun 10, 2014|Overall XML Syntax|

The patient element

The Entity Element of recordTarget
Within the CDA Header, the recordTarget XML element is a participation element that connects the patient information to the clinical document.

Refer to the article The recordTarget element, for additional information about the overall structure of the recordTarget element in terms of participation, role, entity, and scope XML elements.

Under the recordTarget element is the role element for the patient, named patientRole, which in turn contains within it the entity element named patient.

patientRole and patient
The relationship of role elements and entity elements is explained in the article “Entity” XML elements and “role” XML elements.

As per that explanation, the patient entity element contains the properties of the patient as a person – those properties, such as name and date of birth, that are independent of the fact that this person is currently in the “role” of “being a patient”. The patientRole element contains the properties of the patient that are related to the context of their role of “being a patient”.

XML Sub-Elements of patient
The first three sub-elements of patient are the three common sub-elements of most CDA elements. Following that, the patient element has the following sub-elements:

  • id – these (there can be more than one) are the identifiers of the patient. Refer to The id element, for additional information. As noted above, the sub-elements of patient (as opposed to patientRole) should be identifiers of the patient that are independent of their “patient role”. So, for example, a social security number or driver’s license number would be appropriate – whereas a hospital-provided patient identifier would not be appropriate.
  • name – this is the name of the patient. Refer to The name element, for additional information. Although the C-CDA specification explicitly states otherwise (due to an error), there can be more than one name element in the US Realm Header template. Refer to C-CDA patient maiden name, for an explanation of why this is useful and details of the C-CDA specification error. In C-CDA, the US Realm Header template requires at least one name element.
  • administrativeGenderCode – this is the gender of the patient. There can be only one administrativeGenderCode element under patient. Refer to The administrativeGenderCode element, for additional information. In the C-CDA US Realm Header template, administrativeGenderCode is required.
  • birthTime – this is the date of birth of the patient. It is a moment in time element. There can be only one birthTime element under patient. Refer to The birthTime element, for additional information. In the C-CDA US Realm Header template, birthTime is required.
  • maritalStatusCode – this is the marital status of the patient. There can be only one maritalStatusCode element under patient. Refer to The maritalStatusCode element, for additional information. In the C-CDA US Realm Header template, maritalStatusCode is not required, but is recommended.
  • religiousAffiliationCode […]
May 19, 2014|Elements, Entities & Roles|

Language codes in C-CDA and MU2

The article The languageCode element, introduces the languageCode XML element in CDA, and overviews its usage and XML syntax.

That article also notes that there are some issues regarding which language codes should be used with languageCode (in its code attribute). This article elaborates on this topic.

Language Codes in CDA
The CDA standard references IETF (Internet Engineering Task Force) RFC 3066 in terms of what values should be used in the code attribute of the languageCode element.

That IETF RFC document has subsequently been replaced by RFC 4646.

RFC 4646 allows for different kinds of language codes to be used. Multiple codes (for example, for language and regional dialect) are separated with hyphens. The first part of the language code uses language abbreviations from ISO (International Standards Organization) 639.

ISO 639, in turn, defines different language code abbreviations in its various parts. ISO 639-1 defines two-letter abbreviations. ISO 639-2 defines three-letter abbreviations for a broader set of languages than ISO 639-1.

Language Codes in C-CDA
The C-CDA specification (more formally, the C-CDA implementation guide) requires the use of two-letter codes in ISO 639-1 for the first part of the language code. So, for example, a common language code, used in the code attribute of the languageCode element, is en-US, for US English. The first part of that code, the language abbreviation en, comes from ISO 639-1.

Language Codes in MU2
The MU2 requirements for using C-CDA documents, do not define new C-CDA templates (refer to Does MU2 define C-CDA document templates?, for additional information). However, in some cases, MU2 overrides the guidance in a C-CDA template. The MU2 guidance on language codes is one of those cases.

MU2 requires the use of three-letter abbreviations from ISO 639-2, not the two-letter abbreviations from ISO 639-1.

However, MU2 does not allow the full range of ISO 639-2 three-letter abbreviations to be used. MU2 only allows abbreviations from ISO 639-2 to be used if they have a corresponding two-letter abbreviation in ISO 639-1.

MU2 is At Odds with HL7 Standards in This Area
As noted above, the MU2 guidance for the use of language codes is different than the guidance in C-CDA specifications. As several HL7 experts have noted, the MU2 guidance here is actually at odds with the underlying HL7 standards that are the foundation of C-CDA: namely, CDA and the HL7 v3 RIM. There is no provision in HL7 methodology for “local implementations” (which, in an HL7 standards context, is how MU2 C-CDA would be characterized) to override the allowed codes to be used in XML elements that represent “simple code elements”.

[Note: Refer to Codes in CDA for an overview of the XML attributes and sub-elements of CDA XML elements that represent coded concepts. In that article, refer to the section titled “Simple Codes” and note that languageCode is one of the CDA XML “simple code” elements that have only a code attribute and do […]

Jul 22, 2014 (May 19, 2014)|Overall XML Syntax|

The languageCode element

languageCode in CDA
In the CDA framework and standard, the languageCode XML element is an optional sub-element of many other CDA XML elements.

Generally, languageCode is used to indicate the language for the part of the CDA document in which it appears, as CDA is an international standard and the text in CDA documents can be in any language. There is also a special use of languageCode for describing the languages that a patient knows, which is addressed later in this article.

Where languageCode Appears in CDA
languageCode is an optional sub-element of the ClinicalDocument root XML element. In that context, it indicates the overall language of the CDA document.

In most CDA documents, languageCode only appears in ClinicalDocument/languageCode, as most CDA documents are monolingual. However, multilingual CDA documents are supported by allowing for languageCode to appear in additional parts of the CDA document.

Thus, languageCode is an optional sub-element of the structuredBody and nonXMLBody elements used to represent the CDA body in structured and unstructured CDA documents, respectively. It is also an optional sub-element of the section element to allow a given section to use a different language than the CDA document overall.

Similarly, languageCode is also an optional sub-element of the act, observation, observationMedia, and procedure clinical act statement elements to allow individual clinical acts to have a different language than the section they are in and/or the CDA document overall.

Patient Communication Language
In addition to representing the language of the CDA document, the languageCode element is used in CDA as an optional sub-element of one or more languageCommunication elements, which in turn are sub-elements of the patient element. Refer to The patient element and The languageCommunication element, for additional information about the patient and languageCode elements.

In this context, languageCode represents the languages that the patient knows.

In C-CDA, the US Realm Header template required by all C-CDA templates (and MU2 document types) makes the use of languageCommunication/languageCode mandatory, if languageCommunication is used.

languageCode XML Syntax
Refer to Codes in CDA for an overview of the XML attributes and sub-elements of CDA XML elements that represent coded concepts. In that article, refer to the section titled “Simple Codes” and note that languageCode is one of the CDA XML “simple code” elements that have only a code attribute and do not support the use of the codeSystem, displayName, or codeSystemName attributes.

In all contexts in CDA in which it is used, only a single instance of languageCode is used (to represent the languages that a multilingual patient knows, multiple instances of the languageCommunication element are used).

The Values for the code Attribute of languageCode
As noted, the languageCode element has a single attribute named code. That code attribute contains the code that represents the language.

There are some issues […]

May 19, 2014|Elements|

The languageCommunication element

Within the CDA Header, the recordTarget XML element is a participation element that connects the patient information to the clinical document. Under the recordTarget element is the role element for the patient, which is named patientRole, and contains within it an entity element named patient.

Refer to the articles: The recordTarget element, The patientRole element, and The patient element, for additional information about these elements.

Within the patient entity element, there is an optional element named languageCommunication for representing the languages that the patient knows.

One languageCommunication Element Per Language
Each languageCommunication represents one language communication proficiency of the patient. If the patient speaks multiple languages and/or has varying proficiency with a language (e.g. different levels of speaking, reading, or writing the language), multiple langaugeCommunication elements should be used.

XML Sub-Elements of languageCommunication
The first three sub-elements of languageCommunication are the three common sub-elements of most CDA elements. Following that, the languageCommunication element has the following sub-elements:

  • languageCode – this is a coded element representing the language described by the languageCommunication element. In the CDA specification, languageCode is optional, but in the C-CDA specification (more formally, the C-CDA CDA implementation guide), the US Realm Header template requires that there must be one (and only one) languageCode sub-element of every languageCommunication element. Refer to The languageCode element, for information. Refer to Language codes in C-CDA and MU2 for details about the codes required for MU2, which are different than those specified in the general C-CDA specification.
  • modeCode – this is a coded element representing the language ability that the patient has with the language in languageCode. Refer to The modeCode element, for additional information. This is an optional element.
  • proficiencyLevelCode – this is a coded element representing the proficiency that the patient has with the language in languageCode. Refer to The proficiencyLevelCode element, for additional information. This is an optional element, but it is recommended for inclusion in the C-CDA US Realm Header template.
  • preferenceInd – this is a “Boolean” (true/false) element indicating if the language in languageCode is the patient’s preferred language, or not. Refer to The preferenceInd element, for additional information. This is an optional element.

There are no special attributes associated with the languageCommunication element.

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements|

The preferenceInd Element

The article The languageCommunication element presents the usage and XML syntax for the languageCommunication element, which is a sub-element of the patient entity element in a CDA document.

One of the sub-elements of the languageCommunication element is named preferenceInd.

preferenceInd is a coded XML element that is used to capture whether or not the language being represented by the languageCommunication element is the preferred language of the patient.

Refer to the article Codes in CDA for details of the XML syntax for all coded XML elements.

The proficiencyLevelCode is a “Boolean” element that can take either the value “true” or “false”.

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements|

The proficiencyLevelCode Element

The article The languageCommunication element presents the usage and XML syntax for the languageCommunication element, which is a sub-element of the patient entity element in a CDA document.

One of the sub-elements of the languageCommunication element is named proficiencyLevelCode.

proficiencyLevelCode is a coded XML element that is used to capture the language proficiency of the patient in the language being represented by the languageCommunication element. Refer to the article Codes in CDA for details of the XML syntax for all coded XML elements.

The code system that should be used with proficiencyLevelCode is named LanguageAbilityProficiency (OID: 2.16.840.1.113883.5.61). It includes four possible values for the code attribute: “E” (Excellent), “G” (Good), “F” (Fair), and “P” (Poor).

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements|

The modeCode element

In CDA documents, the modeCode XML element is used (differently) in two different contexts:

  • Under ClinicalDocument/recordTarget/patientRole/patient/languageCommunication, the modeCode sub-element is used to describe a language ability for a language that the patient uses for communication.
  • Under the performer sub-element of one of the clinical act statements, the modeCode sub-element is used to describe the nature of the interaction between the performer and the clinical act statement.

The modeCode Element is a Coded Element
In both of the contexts in which it is used, the modeCode element is a coded element. Refer to Codes in CDA, for an overview of the XML syntax of all coded elements in CDA.

However, the specific code system that should be used with modeCode varies based on the context in which it is used.

The modeCode Element Code System for Language Ability
When it appears under ClinicalDocument/recordTarget/patientRole/patient/languageCommunication to express language ability, the code system for modeCode is named LanguageAbilityMode (OID: 2.16.840.1.113883.5.60). It includes six possible values for the code attribute: “ESGN” (Expresses Signed), “ESP” (Expressed Spoken), “EWR” (Expressed Written), “RSGN” (Received Signed), “RSP” (Received Spoken), and “RWR” (Received Written).

The modeCode Element Code System for Nature of Performer Interaction
When it appears under the performer sub-element of one of the clinical act statements to describe the nature of the interaction between the performer and the clinical act statement, the code system for modeCode is named ParticipationMode (OID: 2.16.840.1.113883.5.1064). It includes over ten values such as: “FACE” (Face-To-Face), “VIDEOCONF” (Video Conference), and “PHONE” (Phone).

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements|

The place element

Within the CDA Header, the recordTarget XML element is a participation element that connects the patient information to the clinical document. Under the recordTarget element is the role element for the patient, which is named patientRole, and contains within it an entity element named patient.

Refer to the articles: The recordTarget element, The patientRole element, and The patient element, for additional information about these elements.

Within patient, there is an optional role element named birthPlace for the patient’s birth place (refer to The birthPlace element, for additional information).

Under the birthPlace role element, the place element is the entity element for the birth place.

birthPlace and place
The relationship of role elements and entity elements is explained in the article “Entity” XML elements and “role” XML elements.

As per that explanation, the place entity element contains the properties of the place that are independent of the fact that this place is in the “role” of “being the place of birth of someone”. The birthPlace element would contain the properties of the place that are related to the context of its role of “being a place of birth” – although as a practical matter, there really aren’t any such properties that are interesting.

The relationship between birthPlace and place is analogous to the relationship between patientRole and patient. The birthPlace and patientRole elements are role elements, while place and patient are entity elements.

XML Sub-Elements of place
The first three sub-elements of place are the three common sub-elements of most CDA elements.

Those are optionally followed by the name element which represents the name of the place. Refer to The name element, for information about the XML syntax of this element. Use of the name sub-element of place is optional. In C-CDA, the US Realm Header template allows a maximum of one name sub-element.

That is optionally followed by the addr element which represents the address of the place. Refer to The addr element, for information about the XML syntax of this element. Use of the addr sub-element of place is optional in CDA, but in C-CDA, the US Realm Header template requires one (and only) addr sub-element.

Attributes of place
The classCode attribute of the place element, is defined with a fixed (and default) value of “PLC”. Commonly in XML syntax, when there is a fixed, default value for an attribute, that attribute is left out in the XML syntax for the element in an XML document. Refer to The classCode attribute, for additional information.

Like many entity elements, place has a determinerCode attribute, which is defined with a fixed (and default) value of “INSTANCE” and which is not explicitly included. Refer to The determinerCode attribute, for additional information.

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements, Entities & Roles|

The birthPlace element

The article The patient element presents the usage and XML syntax for the patient entity element in a CDA document.

One of the sub-elements of the patient element is named birthPlace, which associates the patient’s place of birth with the patient.

The birthPlace element is a role element, and it contains the place entity element for the place of birth (refer to The place element, for additional information).

birthPlace and place
The relationship of role elements and entity elements is explained in the article “Entity” XML elements and “role” XML elements.

As per that explanation, the place entity element contains the properties of the place that are independent of the fact that this place is in the “role” of “being the place of birth of someone”. The birthPlace element would contain the properties of the place that are related to the context of its role of “being a place of birth” – although as a practical matter, there really aren’t any such properties that are interesting.

The relationship between birthPlace and place is analogous to the relationship between patientRole and patient. The birthPlace and patientRole elements are role elements, while place and patient are entity elements.

XML Sub-Elements of birthPlace
The first three sub-elements of the birthPlace element are the three common sub-elements of most CDA elements.

Since there are no useful “properties of the role”, the only other sub-element of birthPlace is the place entity element.

Attributes of birthPlace
The classCode attribute of the birthPlace element, is defined with a fixed (and default) value of “BIRTHPL”. Commonly in XML syntax, when there is a fixed, default value for an attribute, that attribute is left out of the element in the XML document. Refer to The classCode attribute, for additional information.

Other CDA PRO Know Articles Referenced In This Article

May 19, 2014|Elements, Entities & Roles|