This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

• Using Codes
• Systems
• Value Sets
• v2 Tables
• v3 Namespaces
• Concept Maps
• Terminology Service

1.22.0 Using Codes in Resources

Many elements in the FHIR resources have a coded value: some fixed string (a sequence of characters) assigned elsewhere that identifies some defined "concept". The sequence of characters and its meaning may be defined in one of several places:

• As one of a set of fixed values defined in this specification
• In an internet RFC (e.g. mime type, language)
• An HL7 defined source (v3 code system, or v2 table)
• Some external terminology or ontology such as LOINC, SNOMED CT
• A locally maintained dictionary, look up table or enumeration in an application

All of these kinds of ways of defining codes are collectively called "code systems". This list is far from complete; there are many ways to define code systems, and they vary widely in sophistication and size.

Throughout this specification, coded values are always treated as a pair composed of "system" and "code", where the system is a URL that identifies the code system that defines the codes.

The FHIR framework for using coded values is based on the fundamental framework defined in section 5 of the HL7 v3 Core Principles document.

When codes are carried in resources, one of 3 different data types is used:

1.22.0.1 Controlling the use of Coded Values

The set of coded values that is allowed to be used in an element of one of these 3 data types is known as a "value set". Anywhere these data types are used, the specification "binds" a value set to the element. How this is done is different for the simple code data type and the complex data types (Coding/CodeableConcept).

The difference between a code system and a value set is an important distinction that is often missed by implementers, since strict differentiation is often taked for granted in system design. For instance, it's not unusual to see a system table that is a mixed list of codes, containing some LOINC codes and also some additional in-house codes. Quit often, there is no explicit differentiation between them; only the fact that a code happens to look like a LOINC code betrays it's origin.

In FHIR, on the other hand, explicitly tracking the source of the code is both important and necessary. In order to do this, each code system that defines codes is assigned a URL that identifies it, and all the codes it defines are actually a pair ("Code Pair": a name with a namespace). So in the case of this mixed list example, there is two code systems: LOINC (http://loinc.org) and a local one (let's say it has the URL: http://example.com/codesystems/additional-test-codes). The system table is a single value set (a set of Code Pairs) that includes codes from each of those two namespaces. The value set itself gets it's own URL as an identifier (e.g. "http://example.com/fhir/ValueSet/test-codes)") - this identifies the set of Code Pairs, but is never used as the namespace in a actual code pair, or in an instance. In FHIR, Code Pairs are always represented as "code" and "system", except for the simple data type "code" data type where the namespace (e.g. the system element/property) is fixed in the schema and not represented explicitly. So the URL in a system element is always a reference to a code system, not to a value set.

1.22.0.1.1 Simple Code Data Type

Simple elements with type code are either bound to a value set that contains a list of distinct codes with a specified system (and version, where required), or the element is bound to some external standard that defines the set of valid codes that can be used (typical examples of references are Mime Types, Language Codes, UCUM, etc.).

In all cases, the value of the element SHALL be one of the codes defined by value set or the referenced specification.

Note the following additional rules about these codes:

• Where the value set is defined by FHIR, the list of allowed codes will be fixed in the XML schema
• Comparison between codes is always case sensitive for codes unless the codes are defined by reference, and the referenced specification clearly states otherwise
• The list of codes that can be used can only be extended in subsequent releases of the FHIR specification
• Profiles that define how a resource is used in some context may state rules on which codes can be used, but cannot define new or additional codes for these elements

1.22.0.1.2 Complex Coded Data Types

Elements with type CodeableConcept or Coding are bound to a value set that defines a list of coded values that can be used. Because of the size and complexity of these value sets, schemas are not used to enforce the correct use of valid coded values. Instead, formal definitions of the value sets are provided using the Value Set resource, and a cascading set of rules is used to control how tightly the actual coded values are controlled by the value set. In the base FHIR specification, the binding may be called "incomplete" or "example".

1.22.0.1.2.1 Incomplete Bindings

Incomplete bindings are used when there is consensus at the specification level about the coded values that should be used. For these bindings:

• Coding: the system/code values SHOULD be one of the codes in the value set.
• CodeableConcept: one of the coding elements SHOULD contain a system/code that is in the value set.

When none of the coded values in the value set is correct, some other coded value MAY be used, or (for a CodeableConcept), a text alternative MAY be provided. Implementers are able to choose other codes than those specified in recognition of the fact that:

• Licensing and Legal policy may dictate that particular coded values must or cannot be used
• Even when the specified value set can be used, the specification cannot account for all known use cases in advance

1.22.0.1.2.2 Example Bindings

Example bindings are used when an element has a very broad meaning (such as List.code), or there is no consensus over the correct codes to be used. For these bindings:

• Coding: the system/code values MAY be one of the codes in the value set.
• CodeableConcept: one of the coding elements MAY contain a system/code that is in the value set.

Some other coded value MAY be used, or (for a CodeableConcept), a text alternative MAY be provided. Example value sets are provided to assist implementers to understand the correct use of an element. Value sets based on code systems such as SNOMED CT that have restrictive license terms will only be used as example bindings.

1.22.0.1.2.3 Implementation Details

Irrespective of whether the binding is an incomplete or example binding, when a Profile is used to describe local usage, it can bind the element to a different value set. When a profile redefines a binding, it is able to be much more precise about exactly which coded values can be used for these elements (see Binding Control for more detail).

Generally it is expected that jurisdictions, projects and vendors will work together to choose actual working value sets. Subsequent versions of FHIR may replace example value sets with full bindings if enough consensus emerges.

System values are always case sensitive. Different code systems make their own rules as to whether the codes they define are case sensitive or not. Note that all the codes defined by FHIR itself are case sensitive and SHALL be used in the provided case (usually, but not always, lowercase).

Bindings to value sets provided as part of the specification are always specific to the version of the value set published with the specification. The value set may be sealed by defining a simple list of enumerated codes, or it may include codes by their properties, along with a non-version specific reference to an underlying code system, in which case the list of valid concepts may grow or change over time.