Representation

Model

The UML model of the openEHR code sets and vocabularies is shown below. Note that this model is not intended as a normative model for internal terminology representation in openEHR services. Accordingly it does not directly correspond to the terminology classes defined in the openEHR Data Types or openEHR Base Types specifications.

Figure 1. 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.

Class Definitions

TERMINOLOGY Class

Definition
Effective
BMM
UML

Class	TERMINOLOGY
Description	Container for code sets and/or vocabularies that belong to a given logical terminology.
Attributes	Signature	Meaning
1..1	name: `String `	Name of this terminology.
1..1	language: `String `	Language of this terminology, as an ISO:639 2-letter code.
0..1	code_sets: `List <CODE_SET>`	Code sets in this Terminology.
0..1	vocabularies: `List <TERMINOLOGY_GROUP>`	Vocabularies of coded terms in this terminology.
0..1	version: `String `	Version of this instance of the terminology.
0..1	date: `Iso8601_date `	Date of issue of this version of the terminology.

Class

TERMINOLOGY

Description

Container for code sets and/or vocabularies that belong to a given logical terminology.

Attributes

Signature

Meaning

1..1

name: `String `

Name of this terminology.

1..1

language: `String `

Language of this terminology, as an ISO:639 2-letter code.

0..1

code_sets: List <CODE_SET>

Code sets in this Terminology.

0..1

vocabularies: List <TERMINOLOGY_GROUP>

Vocabularies of coded terms in this terminology.

0..1

version: `String `

Version of this instance of the terminology.

0..1

date: `Iso8601_date `

Date of issue of this version of the terminology.

TERMINOLOGY
Container for code sets and/or vocabularies that belong to a given logical terminology.
Attributes
name: `String ` [1..1]	Name of this terminology.
language: `String ` [1..1]	Language of this terminology, as an ISO:639 2-letter code.
code_sets: `List <CODE_SET>` [0..1]	Code sets in this Terminology.
vocabularies: `List <TERMINOLOGY_GROUP>` [0..1]	Vocabularies of coded terms in this terminology.
version: `String ` [0..1]	Version of this instance of the terminology.
date: `Iso8601_date ` [0..1]	Date of issue of this version of the terminology.

TERMINOLOGY

Container for code sets and/or vocabularies that belong to a given logical terminology.

Attributes

name: `String ` [1..1]

Name of this terminology.

language: `String ` [1..1]

Language of this terminology, as an ISO:639 2-letter code.

code_sets: List <CODE_SET> [0..1]

Code sets in this Terminology.

vocabularies: List <TERMINOLOGY_GROUP> [0..1]

Vocabularies of coded terms in this terminology.

version: `String ` [0..1]

Version of this instance of the terminology.

date: `Iso8601_date ` [0..1]

Date of issue of this version of the terminology.

{
    "name": "TERMINOLOGY",
    "documentation": "Container for code sets and/or vocabularies that belong to a given logical terminology.",
    "properties": {
        "name": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "name",
            "documentation": "Name of this terminology.",
            "is_mandatory": true,
            "type": "String"
        },
        "language": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "language",
            "documentation": "Language of this terminology, as an ISO:639 2-letter code.",
            "is_mandatory": true,
            "type": "String"
        },
        "code_sets": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "code_sets",
            "documentation": "Code sets in this Terminology.",
            "type_def": {
                "container_type": "List",
                "type": "CODE_SET"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "vocabularies": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "vocabularies",
            "documentation": "Vocabularies of coded terms in this terminology.",
            "type_def": {
                "container_type": "List",
                "type": "TERMINOLOGY_GROUP"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "version": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "version",
            "documentation": "Version of this instance of the terminology.",
            "type": "String"
        },
        "date": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "date",
            "documentation": "Date of issue of this version of the terminology.",
            "type": "Iso8601_date"
        }
    }
}

CODE_SET Class

Definition
Effective
BMM
UML

Class	CODE_SET
Description	A code set.
Attributes	Signature	Meaning
1..1	name: `String `	Name of this code set.
1..1	openehr_id: `String `	Identifier used for code set in the openEHR Reference Model. The value is inferred from the `name` attribute. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
1..1	issuer: `String `	Name of the issuing organisation.
0..1	codes: `List <CODE>`	Codes in this code set.
0..1	external_id: `String `	An optional identifier assumed by openEHR to be the identifier of this code set, based on its published name, with spaces replaced by underscores. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
0..1	status: `TERMINOLOGY_STATUS` `{default = }`	Status of this code set.

Class

CODE_SET

Description

A code set.

Attributes

Signature

Meaning

1..1

name: `String `

Name of this code set.

1..1

openehr_id: `String `

Identifier used for code set in the openEHR Reference Model. The value is inferred from the name attribute.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

1..1

issuer: `String `

Name of the issuing organisation.

0..1

codes: List <CODE>

Codes in this code set.

0..1

external_id: `String `

An optional identifier assumed by openEHR to be the identifier of this code set, based on its published name, with spaces replaced by underscores.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

0..1

status: TERMINOLOGY_STATUS
{default = }

Status of this code set.

CODE_SET
A code set.
Attributes
name: `String ` [1..1]	Name of this code set.
openehr_id: `String ` [1..1]	Identifier used for code set in the openEHR Reference Model. The value is inferred from the `name` attribute. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
issuer: `String ` [1..1]	Name of the issuing organisation.
codes: `List <CODE>` [0..1]	Codes in this code set.
external_id: `String ` [0..1]	An optional identifier assumed by openEHR to be the identifier of this code set, based on its published name, with spaces replaced by underscores. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
status: `TERMINOLOGY_STATUS` [0..1] `{default = }`	Status of this code set.

CODE_SET

A code set.

Attributes

name: `String ` [1..1]

Name of this code set.

openehr_id: `String ` [1..1]

Identifier used for code set in the openEHR Reference Model. The value is inferred from the name attribute.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

issuer: `String ` [1..1]

Name of the issuing organisation.

codes: List <CODE> [0..1]

Codes in this code set.

external_id: `String ` [0..1]

An optional identifier assumed by openEHR to be the identifier of this code set, based on its published name, with spaces replaced by underscores.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

status: TERMINOLOGY_STATUS [0..1]
{default = }

Status of this code set.

{
    "name": "CODE_SET",
    "documentation": "A code set.",
    "properties": {
        "name": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "name",
            "documentation": "Name of this code set.",
            "is_mandatory": true,
            "type": "String"
        },
        "openehr_id": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "openehr_id",
            "documentation": "Identifier used for code set in the openEHR Reference Model. The value is inferred from the `_name_` attribute.\n\nValid values take the form of an xs:NCName value, i.e. cannot contain:\n\n* symbol characters `:, @, $, %, &, /, +, ,, ;`;\n* whitespace characters or different parentheses. \n\nAn NCName cannot begin with a number, dot or minus character although these can appear later in the value.",
            "is_mandatory": true,
            "type": "String"
        },
        "issuer": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "issuer",
            "documentation": "Name of the issuing organisation.",
            "is_mandatory": true,
            "type": "String"
        },
        "codes": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "codes",
            "documentation": "Codes in this code set.",
            "type_def": {
                "container_type": "List",
                "type": "CODE"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "external_id": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "external_id",
            "documentation": "An optional identifier assumed by openEHR to be the identifier of this code set, based on its published name, with spaces replaced by underscores.\n\nValid values take the form of an xs:NCName value, i.e. cannot contain:\n\n* symbol characters `:, @, $, %, &, /, +, ,, ;`;\n* whitespace characters or different parentheses. \n\nAn NCName cannot begin with a number, dot or minus character although these can appear later in the value.",
            "type": "String"
        },
        "status": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "status",
            "documentation": "Status of this code set.",
            "type": "TERMINOLOGY_STATUS",
            "default": ""
        }
    }
}

CODE Class

Definition
Effective
BMM
UML

Class	CODE
Description	A single code entity in a code set.
Attributes	Signature	Meaning
1..1	value: `String `	The code string for this code entity, e.g. `"AF"`.
0..1	description: `String `	Optional description of this code, e.g. `"AFGHANISTAN"`. This field may be used to hold translations of the description in a language-specific copy of the English language original code set.
0..1	status: `TERMINOLOGY_STATUS` `{default = }`	Status of this code within the code set.

Class

CODE

Description

A single code entity in a code set.

Attributes

Signature

Meaning

1..1

value: `String `

The code string for this code entity, e.g. "AF".

0..1

description: `String `

Optional description of this code, e.g. "AFGHANISTAN".

This field may be used to hold translations of the description in a language-specific copy of the English language original code set.

0..1

status: TERMINOLOGY_STATUS
{default = }

Status of this code within the code set.

CODE
A single code entity in a code set.
Attributes
value: `String ` [1..1]	The code string for this code entity, e.g. `"AF"`.
description: `String ` [0..1]	Optional description of this code, e.g. `"AFGHANISTAN"`. This field may be used to hold translations of the description in a language-specific copy of the English language original code set.
status: `TERMINOLOGY_STATUS` [0..1] `{default = }`	Status of this code within the code set.

CODE

A single code entity in a code set.

Attributes

value: `String ` [1..1]

The code string for this code entity, e.g. "AF".

description: `String ` [0..1]

Optional description of this code, e.g. "AFGHANISTAN".

This field may be used to hold translations of the description in a language-specific copy of the English language original code set.

status: TERMINOLOGY_STATUS [0..1]
{default = }

Status of this code within the code set.

{
    "name": "CODE",
    "documentation": "A single code entity in a code set.",
    "properties": {
        "value": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "value",
            "documentation": "The code string for this code entity, e.g. `\"AF\"`.",
            "is_mandatory": true,
            "type": "String"
        },
        "description": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "description",
            "documentation": "Optional description of this code, e.g. `\"AFGHANISTAN\"`.\n\nThis field may be used to hold translations of the description in a language-specific copy of the English language original code set.",
            "type": "String"
        },
        "status": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "status",
            "documentation": "Status of this code within the code set.",
            "type": "TERMINOLOGY_STATUS",
            "default": ""
        }
    }
}

TERMINOLOGY_GROUP Class

Definition
Effective
BMM
UML

Class	TERMINOLOGY_GROUP
Description	A single vocabulary, in a particular language, within a Terminology.
Attributes	Signature	Meaning
1..1	name: `String `	Name of this vocabulary.
0..1	concepts: `List <TERMINOLOGY_CONCEPT>`	List of concepts (i.e. coded terms) in this vocabulary.
1..1	openehr_id: `String `	Identifier used for terminology group in the openEHR Reference Model. The value is inferred from the `name` attribute. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
0..1	status: `TERMINOLOGY_STATUS` `{default = }`	Status of this vocabulary.

Class

TERMINOLOGY_GROUP

Description

A single vocabulary, in a particular language, within a Terminology.

Attributes

Signature

Meaning

1..1

name: `String `

Name of this vocabulary.

0..1

concepts: List <TERMINOLOGY_CONCEPT>

List of concepts (i.e. coded terms) in this vocabulary.

1..1

openehr_id: `String `

Identifier used for terminology group in the openEHR Reference Model. The value is inferred from the name attribute.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

0..1

status: TERMINOLOGY_STATUS
{default = }

Status of this vocabulary.

TERMINOLOGY_GROUP
A single vocabulary, in a particular language, within a Terminology.
Attributes
name: `String ` [1..1]	Name of this vocabulary.
concepts: `List <TERMINOLOGY_CONCEPT>` [0..1]	List of concepts (i.e. coded terms) in this vocabulary.
openehr_id: `String ` [1..1]	Identifier used for terminology group in the openEHR Reference Model. The value is inferred from the `name` attribute. Valid values take the form of an xs:NCName value, i.e. cannot contain: symbol characters `:, @, $, %, &, /, +, ,, ;`; whitespace characters or different parentheses. An NCName cannot begin with a number, dot or minus character although these can appear later in the value.
status: `TERMINOLOGY_STATUS` [0..1] `{default = }`	Status of this vocabulary.

TERMINOLOGY_GROUP

A single vocabulary, in a particular language, within a Terminology.

Attributes

name: `String ` [1..1]

Name of this vocabulary.

concepts: List <TERMINOLOGY_CONCEPT> [0..1]

List of concepts (i.e. coded terms) in this vocabulary.

openehr_id: `String ` [1..1]

Identifier used for terminology group in the openEHR Reference Model. The value is inferred from the name attribute.

Valid values take the form of an xs:NCName value, i.e. cannot contain:

symbol characters :, @, $, %, &, /, +, ,, ;;
whitespace characters or different parentheses.

An NCName cannot begin with a number, dot or minus character although these can appear later in the value.

status: TERMINOLOGY_STATUS [0..1]
{default = }

Status of this vocabulary.

{
    "name": "TERMINOLOGY_GROUP",
    "documentation": "A single vocabulary, in a particular language, within a Terminology.",
    "properties": {
        "name": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "name",
            "documentation": "Name of this vocabulary.",
            "is_mandatory": true,
            "type": "String"
        },
        "concepts": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "concepts",
            "documentation": "List of concepts (i.e. coded terms) in this vocabulary.",
            "type_def": {
                "container_type": "List",
                "type": "TERMINOLOGY_CONCEPT"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        },
        "openehr_id": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "openehr_id",
            "documentation": "Identifier used for terminology group in the openEHR Reference Model. The value is inferred from the `_name_` attribute.\n\nValid values take the form of an xs:NCName value, i.e. cannot contain:\n\n* symbol characters `:, @, $, %, &, /, +, ,, ;`;\n* whitespace characters or different parentheses. \n\nAn NCName cannot begin with a number, dot or minus character although these can appear later in the value.",
            "is_mandatory": true,
            "type": "String"
        },
        "status": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "status",
            "documentation": "Status of this vocabulary.",
            "type": "TERMINOLOGY_STATUS",
            "default": ""
        }
    }
}

TERMINOLOGY_CONCEPT Class

Definition
Effective
BMM
UML

Class	TERMINOLOGY_CONCEPT
Description	A single terminology concept in a vocabulary.
Attributes	Signature	Meaning
1..1	id: `String `	The code of this concept.
1..1	rubric: `String `	The rubric, i.e. linguistic expression, of this concept, in the language of this terminology instance.
0..1	status: `TERMINOLOGY_STATUS` `{default = }`	Status of this concept within the vocabulary.

Class

TERMINOLOGY_CONCEPT

Description

A single terminology concept in a vocabulary.

Attributes

Signature

Meaning

1..1

id: `String `

The code of this concept.

1..1

rubric: `String `

The rubric, i.e. linguistic expression, of this concept, in the language of this terminology instance.

0..1

status: TERMINOLOGY_STATUS
{default = }

Status of this concept within the vocabulary.

TERMINOLOGY_CONCEPT
A single terminology concept in a vocabulary.
Attributes
id: `String ` [1..1]	The code of this concept.
rubric: `String ` [1..1]	The rubric, i.e. linguistic expression, of this concept, in the language of this terminology instance.
status: `TERMINOLOGY_STATUS` [0..1] `{default = }`	Status of this concept within the vocabulary.

TERMINOLOGY_CONCEPT

A single terminology concept in a vocabulary.

Attributes

id: `String ` [1..1]

The code of this concept.

rubric: `String ` [1..1]

The rubric, i.e. linguistic expression, of this concept, in the language of this terminology instance.

status: TERMINOLOGY_STATUS [0..1]
{default = }

Status of this concept within the vocabulary.

{
    "name": "TERMINOLOGY_CONCEPT",
    "documentation": "A single terminology concept in a vocabulary.",
    "properties": {
        "id": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "id",
            "documentation": "The code of this concept.",
            "is_mandatory": true,
            "type": "String"
        },
        "rubric": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "rubric",
            "documentation": "The rubric, i.e. linguistic expression, of this concept, in the language of this terminology instance.",
            "is_mandatory": true,
            "type": "String"
        },
        "status": {
            "_type": "P_BMM_SINGLE_PROPERTY",
            "name": "status",
            "documentation": "Status of this concept within the vocabulary.",
            "type": "TERMINOLOGY_STATUS",
            "default": ""
        }
    }
}

TERMINOLOGY_STATUS Enumeration

Definition
Effective
BMM
UML

Enumeration	TERMINOLOGY_STATUS
Description	Enumeration of possible lifecycle states of any part of the terminomlogy.
Constants	Signature	Meaning
	trial	Terminology element is in Trial state.
	active	Terminology element is in Active state, i.e. published and in use.
	retired	Terminology element has been Retired, i.e. deprecated.

Enumeration

TERMINOLOGY_STATUS

Description

Enumeration of possible lifecycle states of any part of the terminomlogy.

Constants

Signature

Meaning

trial

Terminology element is in Trial state.

active

Terminology element is in Active state, i.e. published and in use.

retired

Terminology element has been Retired, i.e. deprecated.

TERMINOLOGY_STATUS
Enumeration of possible lifecycle states of any part of the terminomlogy.
Inherits: String
Constants
trial	Terminology element is in Trial state.
active	Terminology element is in Active state, i.e. published and in use.
retired	Terminology element has been Retired, i.e. deprecated.

TERMINOLOGY_STATUS

Enumeration of possible lifecycle states of any part of the terminomlogy.

Inherits: String

Constants

trial

Terminology element is in Trial state.

active

Terminology element is in Active state, i.e. published and in use.

retired

Terminology element has been Retired, i.e. deprecated.

{
    "_type": "P_BMM_ENUMERATION_STRING",
    "name": "TERMINOLOGY_STATUS",
    "documentation": "Enumeration of possible lifecycle states of any part of the terminomlogy.",
    "ancestors": [
        "String"
    ],
    "item_names": [
        "trial",
        "active",
        "retired"
    ],
    "item_documentations": [
        "Terminology element is in Trial state.",
        "Terminology element is in Active state, i.e. published and in use.",
        "Terminology element has been Retired, i.e. deprecated."
    ]
}

XML Representation

The concrete representation of the openEHR code sets and vocabularies is in the XML format described by the XML Schema found in the openEHR specifications-TERM repository, which has the following structure under the /computable/XML directory.

Figure 2. The structure of XML computable expressions in the repository

Content Artefacts

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" version="3.0.0" date="2023-02-07">
	<codeset issuer="ISO" openehr_id="countries" name="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" name="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" version="3.0.0" date="2023-02-07">
	<group openehr_id="attestation_reason" name="attestation reason">
		<concept id="240" rubric="signed"/>
		<concept id="648" rubric="witnessed"/>
	</group>
	<group openehr_id="audit_change_type" 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 openehr_id="composition_category" name="composition category">
		<concept id="431" rubric="persistent"/>
		<concept id="451" rubric="episodic"/>
        <concept id="433" rubric="event"/>
	</group>
	<group openehr_id="property" 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.