---
type: "datatype"
title: "Coding"
datatype: "Coding"
---
# Coding

- [Datatypes](/datatypes)
- [Definitions](/datatypes-definitions#Coding)
- [Examples](/datatypes-examples#Coding)
- [Mappings](/datatypes-mappings#Coding)
- [Profiles](/datatypes-profiles#Coding)

## Overview

See also [Examples](datatypes-examples#Coding), [Detailed Descriptions](datatypes-definitions#Coding), [Mappings](datatypes-mappings#Coding), [Profiles](datatypes-profiles#Coding) and [Extensions]([%extensions-location%]extensions-datatypes#Coding)

A Coding is a representation of a defined concept using a symbol from a defined "code system" - see [Using Codes in resources](terminologies) for more details.

This datatype can be [bound](terminologies#Coding) to a [ValueSet](valueset).

\[%dt Coding 2%\]

The meaning of the Coding is defined by the code. The `system` provides the source of the definition of the code, along with an optional version reference. The display is a human display for the text defined by the system - it is not intended for computation.

The `system` is an absolute URI that identifies the code system that defines the `code`. Choosing the correct system is important; for more information about the code system URI, read [Managing Terminology System URIs](terminologies#system). If the code is taken from a CodeSystem resource, `CodeSystem.url` is the correct value for the system element. Resolvable URLs are generally preferred by implementers over non-resolvable URNs, particularly opaque URNs such as OIDs (urn:oid:) or UUIDs (urn:uuid:). The system URI SHALL NOT contain a reference to a value set (e.g., `ValueSet.url`), since value sets just define the set of codes which are intended for use in a specific context, not the meaning of the codes themselves.

A code system version may also be supplied. If the meaning of codes within the code system is consistent across releases, this is not required. The version SHOULD be exchanged when the system does not maintain consistent definitions across versions. Note that the following systems SHOULD always have a version specified:

-   National releases of SNOMED CT (consistency of definitions varies amongst jurisdictions, and some jurisdictions may make their own rules on this)
-   Various versions of ICD (note: the major releases are labeled as different code systems altogether, but there is variation within versions)

More generally, any classification (e.g., a code system that includes concepts with relative definitions such as "not otherwise coded" will require a version. See the [discussion of code system versions in the Code System resource](codesystem#versioning) for further discussion on versioning.

If present, the `code` SHALL be a syntactically correct symbol as defined by the `system`. In some code systems such as SNOMED CT, the symbol may be an expression composed of other predefined symbol (e.g., post-coordination). Note that codes are case sensitive unless specified otherwise by the code system. The `display` is a text representation of the code defined by the `system` and is used to display the meaning of the code by an application that is not aware of the `system`.

If the 'display' element is populated, the string used in `display` SHALL be one of the display strings defined for that code by the code system. Code systems may define multiple display strings for a single code, by use of:

-   `CodeSystem.concept.display`
-   `CodeSystem.concept.designation.value` (including in supplements)

Note that displays defined in value sets (`ValueSet.include.concept.display` and `ValueSet.include.concept.designation.value`) are not allowed in `Coding.display`.

If one of the available display strings is labeled as preferred, it SHOULD be used (note that `CodeSystem.concept.display` is preferred for the base resource language if it is populated, but other display strings may be preferred in other languages, or for other usages). If the code system does not define a text representation for display (e.g., SNOMED CT Expressions) then the 'display' element cannot be populated, and the meaning of the code won't be accessible to systems that don't understand the code expression.

In some cases, the `system` might not be known - only the code is known. In this case, no useful processing of the code may be performed unless the system is known implicitly through knowledge of the context (e.g., from a known device/source). This practice should be avoided where possible, as information sharing in a wider context is very likely to arise eventually, and codes cannot be used in the absence of a known system. Thus, systems SHOULD populate the `Coding.system` whenever the system is known.

If the system is present, and there is no code, then this is understood to mean that there is no suitable code in the system in which to represent the concept. The implication of this is that implementers SHOULD never provide a system without a code unless this is the intended meaning AND it is appropriate for the code system and version. (e.g., the code system does not have an 'OTHER' concept.) This approach cannot be used if an appropriate code might exist within the code system but does not exist within the bound ValueSet.

If two codings have the same `system`, `version` and `code` then they have the same meaning. If the version information is missing, or the `system`, `version` or the `code` elements differ, then how the codes are related can only be determined by consulting the definitions of the system(s) and any [mappings](conceptmap) available.

A coding may be marked as a "userSelected" if a user selected the particular coded value in a user interface (e.g., the user selects an item in a pick-list). If a user selected coding exists, it is the preferred choice for performing translations etc.

**Constraints**

\[%dt.constraints Coding%\]

The context of use (as defined in the resource or applicable profile) usually makes rules about what codes and systems are allowed or required in a particular context by [binding](terminologies) the element to a value set.

Coding is used in the following places: \[%dtusage Coding%\]

\[%impl-note%\] This specification defines two types for representing coded values:

-   **Coding**: a simple direct reference to a code defined by a code system
-   **CodeableConcept**: a text description and/or a list of Codings (i.e., a list of references to codes defined by code systems)

The `Coding` datatype corresponds to the simple case of selecting a single code from a code list. However, this type is rarely used in the FHIR specifications; long experience with exchanging coded values in HL7 shows that in the general case, systems need to able to exchange multiple translation codes, and/or an original text.

The `Coding` datatype is used directly when there is certainty that the value must be selected directly from one of the available codes, and the list of possible codes is agreed to by all participants. This is not usually the case in the context of FHIR - general interoperability - so Coding is mostly used in extensions, which are usually intended to be defined for a well-controlled context of use. \[%end-note%\]

## Elements

- **[Coding.system](/datatypes-definitions#Coding.system)** [0..1]: [uri](/uri) The identification of the code system that defines the meaning of the symbol in the code.
- **[Coding.version](/datatypes-definitions#Coding.version)** [0..1]: [string](/string) The version of the code system which was used when choosing this code. Note that a well-maintained code system does not need the version reported, because the meaning of codes is consistent across versions. However this cannot consistently be assured, and when the meaning is not guaranteed to be consistent, the version SHOULD be exchanged
- **[Coding.code](/datatypes-definitions#Coding.code)** [0..1]: [code](/code) A symbol in syntax defined by the system. The symbol may be a predefined code or an expression in a syntax defined by the coding system (e.g. post-coordination)
- **[Coding.display](/datatypes-definitions#Coding.display)** [0..1]: [string](/string) A representation of the meaning of the code in the system, following the rules of the system
- **[Coding.userSelected](/datatypes-definitions#Coding.userSelected)** [0..1]: [boolean](/boolean) Indicates that this coding was chosen by a user directly - e.g. off a pick list of available items (codes or displays)

## Bindings

- **Coding.code**: `!`

## Requirements

- **Coding.system**: Need to be unambiguous about the source of the definition of the symbol
- **Coding.code**: Need to refer to a particular code in the system
- **Coding.display**: Need to be able to carry a human-readable meaning of the code for readers that do not know the system
- **Coding.userSelected**: This has been identified as a clinical safety criterium - that this exact system/code pair was chosen explicitly, rather than inferred by the system based on some rules or language processing

## Comments

- **Coding.system**: The URI may be an OID (urn:oid:...) or a UUID (urn:uuid:...). OIDs and UUIDs SHALL be references to the HL7 OID registry. Otherwise, the URI should come from HL7's list of FHIR defined special URIs or it should be an absolute reference to some definition that establishes the system clearly and unambiguously
- **Coding.version**: Where the terminology does not clearly define what string should be used to identify code system versions, the recommendation is to use the date (expressed in FHIR date format) on which that version was officially published as the version date
- **Coding.userSelected**: Amongst a set of alternatives, a directly chosen code is the most appropriate starting point for new translations. There is some ambiguity about what exactly 'directly chosen' implies, and trading partner agreement may be needed to clarify the use of this element and its consequences more completely

## Mappings

- **Coding.system**: RIM Mapping: ./codeSystem
- **Coding.system**: ORIM Mapping: fhir:Coding.system rdfs:subPropertyOf dt:CDCoding.codeSystem
- **Coding.system**: v2 Mapping: C*E.3
- **Coding.version**: RIM Mapping: ./codeSystemVersion
- **Coding.version**: ORIM Mapping: fhir:Coding.version rdfs:subPropertyOf dt:CDCoding.codeSystemVersion
- **Coding.version**: v2 Mapping: C*E.7
- **Coding.code**: RIM Mapping: ./code
- **Coding.code**: ORIM Mapping: fhir:Coding.code rdfs:subPropertyOf dt:CDCoding.code
- **Coding.code**: v2 Mapping: C*E.1
- **Coding.display**: RIM Mapping: CV.displayName
- **Coding.display**: ORIM Mapping: fhir:Coding.display rdfs:subPropertyOf dt:CDCoding.displayName
- **Coding.display**: v2 Mapping: C*E.2 - but note this is not well followed
- **Coding.userSelected**: RIM Mapping: CD.codingRationale
- **Coding.userSelected**: ORIM Mapping: fhir:Coding.userSelected fhir:mapsTo dt:CDCoding.codingRationale. fhir:Coding.userSelected fhir:hasMap fhir:Coding.userSelected.map. fhir:Coding.userSelected.map a fhir:Map; fhir:target dt:CDCoding.codingRationale. fhir:Coding.userSelected\#true a [ fhir:source "true"; fhir:target dt:CDCoding.codingRationale\#O ]
- **Coding.userSelected**: v2 Mapping: Sometimes implied by being first