openEHR logo

Support Terminology specification

Issuer: openEHR Specification Program

Release: TERM Release-2.2.0

Status: STABLE

Revision: [latest_issue]

Date: [latest_issue_date]

Keywords: terminology, code-set, vocabulary, openehr
openEHR components
© 2008 - 2022 The openEHR Foundation

The openEHR Foundation is an independent, non-profit foundation, facilitating the sharing of health records by consumers and clinicians via open specifications, clinical models and open platform implementations.

Licence

image Creative Commons Attribution-NoDerivs 3.0 Unported. https://creativecommons.org/licenses/by-nd/3.0/

Support

Issues: Problem Reports
Web: specifications.openEHR.org

Amendment Record

Issue Details Raiser Completed

TERM Release 2.2.0

2.2.0

Adding a copy of terminology files Release-2.2.0 of https://github.com/openEHR/terminology and updating related links.

S Iancu

01 Aug 2018

TERM Release 2.1.0

2.1.0

SPECTERM-6: Correct Terminology typos.

I McNicoll

08 Nov 2017

Release 1.0

1.0

SPECRM-219: Use constants instead of literals to refer to terminology in RM.

R Chen

08 Apr 2007

SPECRM-221. Add normal_status to DV_ORDERED. Add new "normal status" terminology group.

H Frankel

SPECRM-217: Additional math function.

S Heard

SPECRM-235: Make attestation-only commit require a Contribution. Add 'attestation' code to audit-change type.

A Patterson

SPECRM-246: Correct openEHR terminology rubrics.

B Verhees,
M Forss

Release 0.9

0.9

SPECRM-184. Separate out terminology from Support IM.

H Frankel

22 Oct 2005

SPECRM-182: Rationalise VERSION.lifecycle_state and ATTESTATION.status_. Add new term set for attestation reason, deprecate attestation state term set.

H Frankel

SPECRM-162. Allow party identifiers when no demographic data. Deprecate some terms from version lifecycle status group, add some new terms.

H Frankel

SPECRM-140. Redevelop Instruction, based on workflow principles. Add term sets for Instruction State machine.

H Frankel

SPECRM-192: Add display-as-absolute facility to delta Events in History

H Frankel

Acknowledgements

The work reported in this specification and related artefacts has been funded in part by the following organisations:

  • FreshEHR Informatics, UK

  • Ocean Informatics, Australia

Trademarks

  • 'openEHR' is a trademark of the openEHR Foundation

1. Preface

1.1. Purpose

This document describes the openEHR Support Terminology and code sets, which define the vocabulary and codes needed for the openEHR Reference, Archetype and Service models. The openEHR terminology is not considered to be in the same space as externally defined terminologies such as SNOMED CT, ICDx etc, since it is not an ontology of real facts, but of informational classifiers needed by the openEHR models. The code sets are generally a means of interfacing external codes such as ISO language identifiers, with openEHR. The audience of this document includes:

  • Standards bodies producing health informatics standards;

  • Software development organisations developing EHR systems;

  • Academic groups studying the EHR;

  • The open source healthcare community.

1.2. Related Documents

Prerequisite documents for reading this document include:

1.3. Status

This specification is in the STABLE state. The development version of this document can be found at https://specifications.openehr.org/releases/TERM/latest/SupportTerminology.html.

Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:

TBD: (example To Be Determined paragraph)

1.4. Feedback

Feedback may be provided on the openEHR Terminology specifications forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the TERM component Change Request tracker.

1.5. Requests for new Terminology Codes

Requests for codes may be made by raising a new issue on the specifications Problem Report tracker; the 'Component' field must be set to 'TERM - openEHR Terminology'.

1.6. Creating and Maintaining Translations

A new translation is created by creating a new translated form of the English-language (or another convenient language, e.g. Spanish, to create Portuguese etc) terminology file.

This may be done by the Git workflow of:

  • fork the repository;

  • create the new file in a directory /computable/XML/xx where xx is a ISO 639 2-character language code;

  • when translation is complete, create a pull request.

Translations are maintained when new codes are added by means of notifications to the GitHub authors of current translations.

2. Overview

This document provides a documentary expression of the openEHR Support Terminology, consisting of code sets and vocabulary that provide values for the coded attributes in the openEHR Reference Model. The computable form of this terminology is available in the openEHR terminology repository, and is the definitive expression. Access to the terminology in the openEHR reference model is via the classes defined in the package rm.support.terminology.

There are two types of coded entities used in openEHR. The first is codes that are self-defining, and which do not have separate rubrics, i.e. the code 'stands for itself'. The ISO country and language codes are examples of this, as are code groups for such concepts as 'integrity check algorithm names'. These are represented in openEHR by the CODE_PHRASE type (found in the rm.data_types.text package). Value sets that cannot meaningfully be translated into other languages and which do not have definitions beyond their code value are usually candidates for being a code set rather than a terminology group. The code sets described in this document are mostly internet vocabularies defined by ISO or IETF. This document does not change the definition, it only a) indicates which codes sets are used for what purpose in openEHR and b) assigns them a logical name by which they are referred to in the openEHR models.

The second category of coded entities are true coded terms, where each code is a concept identifier, for which there is a rubric and description, potentially in multiple languages. In other words, the way of linguistically expressing the concept is dependent on the language one is working in. Most clinical terminologies are in this category, e.g. ICD10, ICPC, as well as the vocabularies in the openEHR Terminology described here. Terms in this category are expressed by instances of the openEHR data type DV_CODED_TEXT, which uses the CODE_PHRASE type to contain its defining code, as well as any mapped codes. The openEHR Terminology is a collection of vocabularies required for various attributes in the openEHR Reference and Archetype Models, each identified by a logical name such as "audit change type".

The openEHR Terminology vocabularies provide mappings to other recognised terminologies or vocabularies where available. Given that the attributes defined here are mostly coded attributes (i.e. predefined in the openEHR Reference Model), mappings tend to be to terms in vocabularies defined by standards organisations such as CEN and HL7, rather than large clinical vocabularies such as WHO ICD10.

3. Terminology

The following subsections describe the purpose of the openEHR Terminology Code sets and Vocabularies. The computable definition may be found in the openEHR terminology repository.

3.1. Code Sets

Code Set Description openEHR Usage Source Reference

Countries

This ISO code set defined by the ISO 3166-1 standard consists of 2-character names of countries and country subdivisions.

COMPOSITION
.territory

Unicode countries list.

Character Sets

This IANA (Internet Naming Authority) code set consists of the names of recognised character sets.

ENTRY
.encoding
DV_ENCAPSULATED
.charset

IANA Character Sets.

Compression algorithms

This code set consists of the names of algorithms used to compress data.

DV_MULTIMEDIA
.compression_algorithm

HL7 CompressionAlgorithms domain.

Integrity check algorithms

This code set consists of the names of algorithms used to generate hashes for the purpose of integrity checks on data.

DV_MULTIMEDIA
.integrity_check_algorithm

HL7 IntegrityCheckAlgorithm domain

Languages

This code set defined by the consists of the "alpha-2" form of names of languages from the ISO 639-1 standard.

Note: This does not cover all languages, whereas ISO 639-2 "alpha-3" covers many more languages of cultural or indigenous interest, but which nevertheless are unlikely to be supported by current software or operating systems. See Library of Congress codes for the latter.

ENTRY
.language
COMPOSITION
.language
DV_ENCAPSULATED
.language

ISO 639-1 codes

Media Types

This IANA (Internet Naming Authority) code set consists of the names of edia types.

DV_MULTIMEDIA
.media_type

names of MIME media types

Normal Status

This code set codifies statuses of quantitative values with respect to a normal range for the measured analyte or phenomenon. Use generally restricted to laboratory results. Maps to some codes in HL7v2 User-defined table 0078 - Abnormal flags.

DV_ORDERED
.normal_status

HL7v3 ObservationInterpretation vocabulary

3.2. Vocabularies

Within the openEHR vocabularies, terms are identified in groups, each with its own identifier. The identifiers of the groups is defined in the Support Information Model, Terminology package. Each set of terms is described below on a per-group basis.

Vocabulary Description openEHR Usage External Reference

Attestation Reason

This vocabulary codifies attestation statuses of Compositions or other elements of the health record.

ATTESTATION
.reason

HL7 ParticipationSignature domain.

Audit Change Type

This vocabulary codifies the kinds of changes to data which are recorded in audit trails.

AUDIT_DETAILS
.change_type

Composition Category

This vocabulary codifies the values of the category attribute in Compositions.

COMPOSITION
.category

Event Math Function

This vocabulary codifies mathematical functions applied to non-instantaneous time series events.

INTERVAL_EVENT
.math_function

Instruction States

This vocabulary codifies the names of the states in the standard Instruction state machine.

ISM_TRANSITION
.current_state

Instruction Transitions

This vocabulary codifies the names of the transitions in the standard Instruction state machine

ISM_TRANSITION
.transition

Null Flavours

This vocabulary codifies 'flavours of null' for missing data items.

ELEMENT
.null_flavour

Participation Function

This vocabulary codifies functions of participation of parties in an interaction.

PARTICIPATION
.function

Participation Mode

This vocabulary codifies modes of participation of parties in an interaction.

PARTICIPATION
.mode

HL7 ParticipationMode domain

Property

This vocabulary codifies purposes for physical properties corresponding to formal unit specifications, and allows comparison of Quantities with different units but which measure the same property.

Regenstrief Unified Codes for Units of Measure.

Setting

This vocabulary codifies broad types of settings in which clinical care is delivered. It is not intended to be a perfect classification of the real world, but instead a practical coarse-grained categorisation to aid querying.

EVENT_CONTEXT
.setting

Subject relationship

This vocabulary codifies the relationship between the subject of care and some other party mentioned in the health record.

PARTY_RELATED
.relationship

Term Mapping Purpose

This vocabulary codifies purposes for term mappings as used in openEHR coded text data.

TERM_MAPPING
.purpose

Version Lifecycle State

This vocabulary codifies lifecycle states of Compositions or other elements of the health record.

ORIGINAL_VERSION
.lifecycle_state
IMPORTED_VERSION
.lifecycle_state
VERSIONED_OBJECT
.lifecycle_state

4. Representation

4.1. Concrete Format

The concrete representation of the openEHR code-sets and vocabularies is in the XML format found in the openEHR terminology repository, which has the following structure.

repo structure
Figure 1. Repository Structure

The concrete representation model is shown in the UML diagram below. Note that this model is not intended as a normative model and does not directly correspond to the normative terminology classes defined in the openEHR Data Types or openEHR Base Types specifications.

TERM terminology
Figure 2. openEHR Terminology Model

The TERMINOLOGY type above may include both code sets and vocabularies, however, for practical purposes, a single instance is used to represent all code sets, while each translation of the vocabularies has its own instance.

The concrete artefacts based on this model are accordingly as follows:

  • single file for all code-sets (no translations needed - codes are self-describing, e.g. 'UTF-8', 'text/plain' etc)

  • single file for each translation of the vocabularies.

The code sets terminology file looks as follows:

<terminology name="openehr" language="en">
	<codeset issuer="ISO" openehr_id="countries" external_id="ISO_3166-1">
		<code value="AF" description="AFGHANISTAN"/>
		<code value="AX" description="ÅLAND ISLANDS"/>
		<code value="AL" description="ALBANIA"/>
		<...>
		<code value="ZW" description="ZIMBABWE"/>
	</codeset>
	<...>
	<codeset issuer="IANA" openehr_id="character sets" external_id="IANA_character-sets">
		<code value="ISO-10646-UTF-1"/>
		<code value="ISO_8859-3:1988"/>
		<code value="UTF-8"/>
		<...>
		<code value="ISO_8859-1:1987"/>
	</codeset>
</terminology>

The vocabulary file for English looks as follows:

<terminology name="openehr" language="en">
	<group name="attestation reason">
		<concept id="240" rubric="signed"/>
		<concept id="648" rubric="witnessed"/>
	</group>
	<group name="audit change type">
		<concept id="249" rubric="creation"/>
		<concept id="250" rubric="amendment"/>
		<concept id="251" rubric="modification"/>
		<concept id="252" rubric="synthesis"/>
		<concept id="523" rubric="deleted"/>
		<concept id="666" rubric="attestation"/>
		<concept id="253" rubric="unknown"/>
	</group>
	<group name="composition category">
		<concept id="431" rubric="persistent"/>
		<concept id="433" rubric="event"/>
	</group>
	<group name="property">
		<concept id="339" rubric="Acceleration"/>
		<concept id="342" rubric="Acceleration, angular"/>
		<concept id="381" rubric="Amount (Eq)"/>
		<concept id="384" rubric="Amount (mole)"/>
		<concept id="497" rubric="Angle, plane"/>
		<concept id="500" rubric="Angle, solid"/>
		<...>
	</group>
	<...>
</terminology>

An XML Schema (XSD) has been defined for these files, for use with software that processes them.