Release 5

This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version in it's permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

4.1 Using Codes in Resources

Terminology Infrastructure icon Work GroupMaturity Level: NormativeStandards Status: Normative

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 specification (HL7 v3 icon code system, or HL7 V2 icon table)
  • Some external terminology or ontology such as LOINC icon, or SNOMED CT icon
  • A locally maintained dictionary, look up table or enumeration in an application (for further discussion of locally defined value sets, see "Profiling FHIR")

These methods 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. Note that 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).

The FHIR framework for using coded values is based on the fundamental framework defined in section 5 of the HL7 v3 Core Principles icon document, including the separation between code systems and value sets.

The general pattern for representing coded values is using the following four elements:

system A URI that identifies the system (see below)
version A string value representing a version of the original code system (see Code System Versioning)
code A string value that identifies a concept as defined by the code system
display A description of the concept as defined by the code system

The Coding datatype represents this pattern. This example shows a LOINC code with the LOINC system, the version of LOINC used for the definition, and the display assigned by LOINC:

  
{ 
  "system" : "http://loinc.org",
  "version" : "2.62",
  "code" : "55423-8",
  "display" : "Number of steps in unspecified time Pedometer"
}
When codes are carried in resources, one of several different datatypes is used:
codeThe instance represents the code only. The system is implicit - it is defined as part of the definition of the element, and not carried in the instance.
CodingA datatype that has a code and a system element that identifies where the definition of the code comes from
CodeableConceptA type that represents a concept by plain text and/or one or more coding elements (See the datatype notes for a discussion of code translations and using text in CodeableConcept)
CodeableReferenceA type that can have either a reference to another resource, or a to a concept using a CodeableConcept
In addition, the following datatypes also carry coded values, or content that can be treated as a code and bound to a valueset:
QuantityThe instance has system and code elements for carrying a code for the type of unit, and these can be bound to a value set
stringThe instance carries a string. In some cases, applications may wish to control the set of valid strings for a particular element, so the string value can be treated as a coded element (like code)
uriLike string, URIs can be treated as a coded element

Notes:

The set of coded values that is allowed in an element is known as a "value set". Anywhere these datatypes are used, the specification "binds"> a value set to the element, and for the types code, Coding, and CodeableConcept, always does.

  • Code Systems define concepts and give them meaning through formal definitions, and assign codes that represent the concepts
  • Value Sets specifies a set of codes defined by code systems that can be used in a specific context
  • Bindings apply a value set to an element and specify the rules around the use of the value set

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

The code system identifier of the concept is necessary for interoperable data exchange. Each code system is assigned a uri. The combination of the code system identifier (uri) and the concept identifier (e.g. code) is unique. Note that code system version may be necessary to achieve uniqueness when the code system does not follow concept permanence rules.

In the case of the mixed list example from the previous paragraph, there are two code systems: LOINC icon (http://loinc.org) and a local one with the uri: http://example.com/codesystems/additional-test-codes. The value set definition includes concept identifier (codes) from each of the two code systems. ValueSet.url (e.g. "http://example.com/fhir/ValueSet/test-codes") is the canonical identifier for the value set. The value set uri is not the same as the code system uri. Concepts are always identified by code and system, except for the simple datatype code where the code system is fixed in a specification (e.g. core specification, implementation guide, profile) and not represented explicitly.

Note that for some code systems, there is a single correct mechanism by which to represent codes defined by the system as a single URL. These single URLs are used in the context of the RDF format to enable ontological reasoning. The URL is often a direct reference to a web source that can provide additional definitional material about the concept. Where the mechanism is known, and defined by the code system, it is described in this specification.

The URL in a system is always a reference to a code system, not to a value set. The system ensures that codes can be unambiguously traced back to their original definition, and that logical comparisons, matching and inferences can be performed consistently by different systems. For this reason, choice of the correct URI for the system attribute is critical.

The correct value to use in the system for a given code system can be determined by working through the following list, in order:

  • Terminology.hl7.org icon (THO) - If a code system is listed here, the canonical CodeSystem URL SHALL be used.
  • Not listed in Terminology.hl7.org icon, and the code system is external to HL7, the CodeSystem identifier authorized by HTA SHALL be used.
    • Check the HL7 Terminology Authority (HTA) JIRA project to determine if a request is in process to obtain an identifier
    • If none of the HTA resources address your issue,
    • Monitor the HTA request and update your specification when an authoritative identifier is available
  • Not listed in Terminology.hl7.org icon, and the code system is internal to HL7, and is expected to be used in a production system
    • If you don't see your CodeSystem in THO,
      • Create a canonical URL following this pattern: terminology.hl7.org/CodeSystem/xxxxx (where xxxx is a meaningful text string)
        • This will start the process to create a NamingSystem resource in terminology.hl7.org for your CodeSystem
        • The CodeSystem content may remain within the IG
    • When the CodeSystem is at a state where the IG authors/developers/interested parties are confident it is sufficient, and as early in the process as possible,
    • Set yourself as a watcher on the UP JIRA ticket and update your specification when your CodeSystem is in THO
  • Not listed in Terminology.hl7.org icon, and the code system is intended to never be used in a production system, and will be used to create a value set bound with Example binding strength
    • If the example concept codes will be used in multiple IGs,
      • Use the following URL pattern: [ig-base-canonical]/CodeSystem/example-xxxxx (from one of the multiple IGs, there is no reason to define the same example CodeSystem in multiple IGs)
    • If the example concept codes will only ever be used in a single IG:
      • Create an identifier following this pattern: [ig-base-canonical]/CodeSystem/example-xxxxx (where xxxxx is a specific string that conveys intent)

In the unusual situation where a code system is not resolved by this list, create a temporary identifier following this pattern: terminology.hl7.org/temporary/CodeSystem/xxxx. Contact the HL7 Vocabulary co-chairs.

For publishers of code systems, the following considerations should be kept in mind when defining the correct URI to use:

  • Once defined and in production use, in rare situations, the code system URI may change. Implementers should design their system to support a code system identifier change. Terminology.hl7.org implements NamingSystem resources to manage code system identifiers and their effective date range.
  • An http: address SHOULD resolve to some useful description of the code system. Ideally, if a user makes a request of the address with the media type set to a FHIR media type, the server will respond with a CodeSystem resource, but some other human or computable definition is allowed
  • HTTP addresses should be permalinks which may re-direct to the current correct content
  • A scope of the code system URI and the correct usage of codes and displays in its namespace will be clearly defined by HTA. See examples for SNOMED CT icon, RxNorm icon, LOINC icon, and NDC icon
  • All code systems internal to HL7 use Terminology.hl7.org icon as the base. Generally, allocation of URLs is hierarchical, and most care is required in choosing the Base URL.
    • The url pattern is: terminology.hl7.org/CodeSystem/xxxxxx/xxxxxxx

Note: if the code system is made available packaged inside a ValueSet resource, the correct URL for the system value is ValueSet.codeSystem.system, not ValueSet.uri.

All code systems define a set of concepts, assign specific codes to them, and provide definitional material to guide implementers in the correct use and understanding of the codes. Many code systems define relationships between the different concepts - is-a, part-of, classifies-with, and many other relationships. These features are represented in the CodeSystem resource, and exchanged using one of the code datatypes described above.

Some code systems define rules for how complex expressions can be built using the basic concepts defined by the code system. This is sometimes referred to as "post-coordination". Some of the more notable code systems that define grammars for expressions are:

There are many others. Any expression defined by the code system is still regarded as a 'code' and represented as such.

This example shows a SNOMED CT expression:

  
{ 
  "system" : "http://snomed.info/sct",
  "code" : "128045006:{363698007=56459004}"
}

No display is provided in this example. See the discussion here: https://confluence.ihtsdotools.org/x/UwbJAQ icon

When an element is bound to a value set, it has a binding that has these properties:

NameA descriptive name used when presenting information about the binding
StrengthHow the binding should be understood - see below
ReferenceA URL that defines the value set. Usually, this is a direct reference to a ValueSet resource, but can be a more indirect reference, where the value set is inferred
DescriptionA text description of the use of the codes. If there is no reference, this must be populated. When there is a reference, this can be used to make additional notes about the use and implementation of the value set

A binding is always represented using an ElementDefinition.binding.

Additional Bindings and the element ElementDefinition.binding.additional is considered Trial Use for FHIR Release 5.

In addition, elements may have additional bindings. These additional bindings do not replace the main binding, but provide additional information about the use of codes in the element. Additional bindings have the following properties:

purpose The use of this additional binding:
  • required | extensible | preferred: These bindings have the same meaning as they do on the main binding, but are usually accompanied by some additional usage details that restrict their application to particular context where a tighter binding is possible than in the general case
  • component: the value set is a component of the main conformance binding. This is used to provide additional documentation about the use of the main value set, or parts of it. E.g. the main value set may allow for both SNOMED CT and LOINC, but the author wishes to provide additional specific documentation about how they are used (differently)
  • maximum: If the main conformance binding has strength = extensible, then any codes used to extend that value set SHALL come from this specified value set. Note that this additional binding replaces the extension http://hl7.org/fhir/StructureDefinition/elementdefinition-maxValueSet extension which is no longer defined in FHIR Release 5 (todo: actually delete it, and replace existing uses)
  • minimum: Define a minimum set of codes that all conformant applications are required to accept as valid values. This is an obligation for implementing applications, and is typically associated with additional obligations expressing just what the application should do with the codes. Note that this additional binding replaces the extension http://hl7.org/fhir/StructureDefinition/elementdefinition-minValueSet extension which is no longer defined in FHIR Release 5 (todo: actually delete it, and replace existing uses)
  • candidate: A value set that is a candidate to substitute for the overall conformance value set in some situations; usually these are defined in the documentation, or in the usage element
  • current: A value set that is required to be used with new records. This would be the main conformance value set except that legacy records exist that don't meet this requirement, and never will. Again, this is an application obligation, not something that can be tested in the resource instances themselves
  • ui: This value set is provided to help with user look up in a given context
  • starter: This value set is a good set of codes to start with when designing your system. These are typically the important or commonly used codes. This is useful thing to provide when the conformance value set is very large, or infinite because of a grammar. Many systems can't implement these so a starter set can help them get going
valueSet A canonical URL that refers to the value set for the additional binding
documentation Markdown that describes the use of this value set in this element, given the purpose and usage
shortDoco A short plain text string, typically just a sentence, that summarizes the documentation, for use in the tabular formal of a profile
usage A set of qualifiers that restrict the scope of use for the additional binding. Typically, the binding is restricted by jurisdiction/realm, but it may also be restricted to particular clinical or workflow contexts. This specification does not detail exactly how implementations determine when usage criteria apply, so this is a subject that should be addressed in implementation guides when usages are specified
any If an element repeats, the main binding applies to all the repeats equally. By default, the same is true for an additional binding, but setting any = true means that the additional binding can be met by any one of the repeats. This allows multiple bindings for different repeats without the overhead of slicing. Setting any to true only really makes sense for additional bindings with purpose = conformance

There are a number of places in the specification where value sets are referenced in order to bind a coded value to a value set:

ElementDefinition.binding.valueSetUsed to bind a defined element to a value set, and also ElementDefinition.binding.additional.valueSet
ConceptMap.source[x] and .target[x]Used to indicate the scope of the mapping in the Concept Map - from one value set to another
Questionnaire.item.answerValueSetIndicates that answers to a set of questions come from a value set
ValueSet.compose.include.valueSetThe content of a value set includes the content in the imported value set too
OperationDefinition.parameter.binding.valueSetUsed to bind a defined parameter to a value set
ValueSet Reference ExtensionIndicates that a coded value was chosen from the specified value set

When referencing value sets, the reference is usually made to the definition of a value set - that is, a value set that defines what codes are in the value set. A terminology server is required to convert this definition to the actual expansion that specifies what codes are in the value set in the context of operation.

There are two types of value set references in this list, direct and logical.

A direct value set reference has the type Reference, and refers directly to a ValueSet based on a URL, usually to a terminology server running a FHIR RESTful API. When accessing a value set based on this kind of reference, a system should access the URL directly (after converting a relative reference to an absolute reference according to the local context). If this process fails, the system is unable to resolve the value set and must handle the error appropriately.

Example:

GET fhir/Questionnaire/234

<Questionnaire>
  ...
  <question>
    <options>
      <reference value="ValueSet/234234"/>
    </options>
  </question>
  ....
</Questionnaire>

This specifies that the values for a questionnaire come from the ValueSet with id 234234 on the same FHIR end-point. To resolve this, the system would GET fhir/ValueSet/234234

Typically, a direct reference like this is good for in-process references, in closed or carefully managed eco-systems. In a more general context, these references tend to be fragile over time because web URLs - including RESTful API URLS - are easily reassigned. For this reason, systems are encouraged to use logical value set references.

A logical value set reference has the type uri, where an absolute URI is provided that matches the one in ValueSet.url. The value set URL can - and is preferred to be - a web address that resolves directly to a fixed web address that serves as the authoritative source for that value set. Alternatively, the system can query its terminology server(s) to resolve a value set with that URL as its identity.

Example:

<StructureDefinition>
  ...
  <element>
    ...
    <binding>
      ...
      <valueSet value="http://hl7.org/fhir/ValueSet/clinical-findings"/>
    </binding>
    ...
  </element>
  ....
</StructureDefinition>

This specifies that the element is bound to the value set with a ValueSet.url of http://hl7.org/fhir/ValueSet/clinical-findings icon. One way to access this value set is to try GET http://hl7.org/fhir/ValueSet/clinical-findings - which works, for this value set - http://hl7.org/fhir/ValueSet/clinical-findings returns the authoritative value set for this URL.

Alternatively, the value set could be resolved using a local terminology server. If that's running a FHIR Terminology Server, then this would work like this:

GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findings

if the terminology server knows the value set, then it will return the value set. If the URL doesn't resolve to an authoritative value set, and the terminology server(s) don't know the value set, the system is unable to resolve the value set and must handle the error appropriately.

The value set URL is allowed to be a URI such as a UUID (e.g. urn:uuid:c0e0d027-1250-4278-8f44-33a49dc67916). These value sets can never be accessed directly, and must come from a terminology server. Note that HL7 Terminology defines many value sets that have a logical URL that is not resolvable (examples for SNOMED CT icon, RxNorm icon, and LOINC icon)

Using a logical reference which is a direct reference to the authoritative value set is the easiest and most reliable approach. However, this requires suitable hosting arrangements, and cannot always be guaranteed, so it is not required.

Version specific Logical References

A value set has a two-part identifier: a url, and a version. Some value sets only ever have a single 'version'; a revision of the value set contents will cause a new url to be assigned. Others, however, maintain the same URL, and change the version. A terminology server may have multiple value sets for the same ValueSet.url with different versions.

To be precise about which version of a value set is being referred to in a value set reference, append the version to the canonical URL with a '|' like this:

<valueSet value="http://hl7.org/fhir/ValueSet/clinical-findings|0.8"/>

This is a version specific reference to a value set. Searching for this on a terminology server would look like this:

GET fhir/ValueSet?url=http://hl7.org/fhir/ValueSet/clinical-findings&version=0.8

Note that if a value set reference does not have a version, and the server finds multiple versions for the value set, the system using the value set should pick the latest version of the value set and use that. Note that this applies to all conformance resources.

Note that as a matter of ongoing development, a few elements that have coded datatypes are not bound to any value set at all. Bindings are to be provided for these elements.

Almost all the elements that have a coded datatype are bound to a value set. The bindings are associated with various degrees of flexibility as to how closely the value set should be followed:

requiredTo be conformant, the concept in this element SHALL be from the specified value set.
extensibleTo be conformant, the concept in this element SHALL be from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), alternate codings (or, data type allowing, text) may be included instead.
preferredInstances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.
exampleInstances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.

The precise conformance criteria for 'required' and 'extensible' binding strengths vary by the datatype to which they are applied, as described in the paragraphs below.

Irrespective of the binding strength, when a StructureDefinition is used to describe local usage, it can bind the element to a different value set in order to be much more precise about exactly which coded values can be used for these elements, and/or increase the strength of the binding. There are different rules for this, depending on the binding strength, as discussed below. Generally it is expected that jurisdictions, projects and vendors will work together to choose actual working value sets.

To be conformant, the data element SHALL contain one of the values in the expansion of the bound value set.

If the binding strength is required, the data element SHALL contain one of the values in the bound value set.

Required binding strength is used for elements where the value needs to be strictly controlled so the element can be interpreted with confidence. Required binding strength SHALL be used for elements with type code unless the element has a context-free (i.e. no binding.additional.usage present) additional binding with purpose = maximum. Exceptions to this rule need to be approved by the FHIR-I work group which will document the patterns that qualify as exceptions.

In the base FHIR specification, required binding strength is typically only used with the 'code' datatype. In profiles, it may be used more broadly when there is agreement within a context of use that a specified set of codes are the only ones that can be used.

The following rules apply when required bindings are used with the CodeableConcept datatype:

  • at least one Coding element SHALL be present
  • one of the Coding values SHALL be from the specified value set
  • text can be provided as well, and is always recommended, but is not an acceptable substitute for the required code

If a required binding is applied to an element with maximum cardinality > 1, the binding applies to all the elements.

Note: when a binding is applied to a CodeableReference, these rules also apply to its concept property.

The following rules apply when required bindings are used with the code datatype outside of a Coding:

  • The codes in the value set expansion must be distinct independent of the code system.
  • If the value set draws from multiple code systems or an HL7 defined code system, the value set must specify a version of each code system.
    • i.e. If the code system evolves after publication of a specification with the binding, those changes do not have any impact on specification use.
    • Where the value set is defined in the FHIR core specification, the list of allowed codes will be fixed in the core specification XML schema
  • the element is bound to some external standard that defines the set of valid codes that can be used (typical examples are Mime Types icon, Language Codes icon, UCUM icon, etc.)
  • The list of codes that can be used can only be extended in subsequent releases of the FHIR specification
  • Comparison between codes is always case sensitive unless the codes are selected by reference (e.g. ValueSet.compose), and the referenced specification clearly states otherwise.
  • If the bound value set is defined external to the specification, the binding must specify a value set version.

When an element is bound to a required value set, derived profiles may state rules on which codes can be used, including removing codes from allowed use, but cannot specify additional codes for these elements.

For examples of Required bindings, see Terminology Binding Examples.

To be conformant, the data element SHALL contain one of the values in the expansion of the bound value set if any of the codes within the value set can apply to the concept being communicated.

Extensible bindings are used when there is consensus at the specification or profiling level about the coded values that should be used, but it is impossible to create a bounded list of codes that are known to cover all use cases, including ones that are yet to arise.

Note that it is the value set binding that is extensible, not the value set itself. In the interests of brevity and clarity, please consider all references to value set in the text below to refer to an evaluation of the content logical definition (CLD) of the extensibly-bound value set unless the reference is explicitly noted to refer to a value set definition. If the value set can be expanded, then a proper expansion is equivalent to the evaluation of the CLD.

If there is no applicable concept in the value set (based on human review), an alternate concept (either system /code pair, system/version/code triplet, or text) may be used instead. The alternate concept can have any level of specificity in an is-a hierarchy (see Condition instance #2).

  1. If there is a concept that matches the meaning in the extensibly-bound value set then use that concept.
  2. If there is not a concept that matches the meaning in the extensibly-bound value set and there is at least one applicable concept in the extensibly-bound value set with a meaning which includes but is more general than the meaning that is intended to be represented by the element in the resource instance, then:
    • The code that is used in the instance SHALL be taken from one of the applicable concepts from the value set and SHOULD be the closest more general available match for the intended element instance meaning. If the datatype is Coding then the only concept that can be sent is the applicable concept from the value set.
    • If the datatype is CodeableConcept, a more specific code that is not in the extensibly bound value set that more completely represents the intended meaning MAY be included in the instance as an additional Coding, but it cannot be used instead of the code from the value set expansion. This helps ensure that systems know which codes they should expect to receive and build logic for, and it facilitates interoperability.
  3. Only if the above two cases do not apply then:
    • Alternate code(s) from outside the value set may be used instead.
    • Text in CodeableConcept.text MAY be sent.

For clarity, this table summarizes the rules around extensibility for each bindable data type:

CodeableConcept
  1. a Coding drawn from the ValueSet is present, or
  2. a Coding that represents a concept inexpressable by the ValueSet is present, or
  3. CodeableConcept.text present with no Codings, or
  4. any extension is present that conveys an alternative concept inexpressable by the ValueSet
Coding
  1. a Coding drawn from the ValueSet is present, or
  2. a Coding that represents a concept inexpressable by the ValueSet is present, or
  3. any extension is present that conveys an alternative concept inexpressable by the ValueSet
Quantity
  1. Quantity.code and Quantity.system are from the ValueSet, or
  2. Quantity.code and Quantity.system represents a concept inexpressable by the ValueSet is present, or
  3. any Quantity.extension is present that conveys an alternate unit concept inexpressable by the ValueSet
uri, string
  1. a value drawn from the ValueSet is present, or
  2. A value expressing a concept inexpressable by the ValueSet is present
  3. any extension is present that conveys an alternative concept inexpressable by the ValueSet (e.g., if a datatype other than URI needs to be conveyed)
code
  1. a value drawn from the ValueSet is present, or
  2. any extension is present that conveys an alternative concept inexpressable by the ValueSet

The same rules apply for the concept property of a CodeableReference.

If an extensible binding is applied to an element with maximum cardinality > 1, the binding applies to all the element repetitions.

For an extensibly-bound element, derived profiles may state rules on which codes can be used, but cannot select new or additional codes for these elements unless no codes with appropriate meanings are found in the extensibly-bound value set in the parent profile. You can only constrain, not relax.

Note that if the valueset-reference extension is being used and the code in the element instance is from outside the extensibly-bound value set, the extension must reference a different value set definition that the code was chosen from (or if no other value set reference is available the extension cannot be used in that instance).

See examples to help explain the difficult but important subject of Extensible bindings.

Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.

Preferred bindings are used when there is consensus at the specification level about the coded values that are the best to be used, but there is recognition that some implementation contexts are unable to use the recommended codes for a variety of reasons. Applications should consider adopting the preferred value set wherever possible, as these preferred value sets are the most likely to serve interoperability purposes in the future. For these bindings:

  • code: Preferred binding SHALL NOT be used with the code datatype because the meaning is not predictable due to the inability to specify the system.url for a code that is not included in the bound ValueSet
  • Coding: The value SHOULD be from the specified value set, but another code and/or text can be used in its place
  • CodeableConcept: One of the Coding values SHOULD be from the specified value set, but another code and/or text can be used in its place

For examples of Preferred bindings, see Terminology Binding Examples.

When an element is bound to a preferred value set, derived profiles MAY bind the element to any value set they choose.

Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.

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:

  • code: Example binding SHALL NOT be used with the code datatype because the meaning is not predictable due to the inability to specify the system.url for a code that is not included in the bound ValueSet
  • 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 in the base FHIR specification, though implementation guides for particular jurisdictions may adopt value sets that require licenses. In addition, well-specified realm-specific ValueSets may also be used as example bindings in the base specification.

For examples of Example bindings, see Terminology Binding Examples.

When an element is bound to an example value set, derived profiles may bind the element to any value set they choose.

A binding strength of 'required' or 'extensible' does not indicate that ALL of the codes in the bound value set will be supported. It constrains the set of codes that are allowed to be shared. If systems flag an element as mustSupport, the minimumValueSet extension SHOULD be used to identify a specific subset (possibly the full set) of the bound codes that must be supported by implementers.

If no MIN value set is specified, then there is no guidance for implementers regarding which code(s) must be supported. However, at least one of the codes MUST be supported.

When binding a ValueSet to an element, values may be limited by declaring a maximum value set in the additional bindings.

A binding may be further constrained to declare a value set for use when the binding strength is 'extensible' or 'preferred'. This value set is the value set from which additional codes can be taken from. This defines a 'required' binding over the top of the 'extensible' binding.

Systems with legacy or external data that was constructed without an awareness of the terminology requirements asserted in a binding may have trouble complying with the expectations of the binding. Both 'required' and 'extensible' bindings impose an expectation of systems to map their existing data to the value set. For 'required' bindings, if no mapping is possible, the element can't be sent (not even with an extension). If the element and its ancestor elements all have a 'min' cardinality of 1 or more, then the system cannot produce a conformant instance. For extensible bindings, if a mapping has been tried and there is no corresponding concept, then the legacy data may be freely sent. However, this still imposes the expectation of performing a mapping, and this might not be possible if new externally sourced data with arbitrary codes is being regularly received. If no mapping has been performed, then the element would need to be omitted, or the instance would not be able to claim conformance to the specification that imposed the binding.

R5 introduces some new binding capabilities through the Additional Binding extension. This extension allows specifications to specify more refined types of bindings. In particular, the 'current' binding allows a specification to differentiate between terminology requirements that apply to data captured by a system from the time it complies with a specification as opposed to historical or externally sourced data. Implementers that find the bindings asserted by specifications are too onerous for external or historical data, but are reasonable for 'current' data, might encourage specification authors to consider making use of this Additional Binding extension to better reflect the expectations of systems.

Servers may support a variety of implementation guides. There is no guarantee that all data they have available on their FHIR interfaces will necessarily comply with all implementation guides. On the other hand, some clients might not be able to safely consume data that does not comply with a given IG. In environments where there will be a need to expose a mixture of IG-conformant and non-IG conformant data, but some consumers will depend on data being conformant to safely consume, then Resource.meta.profile can be used to explicitly flag the instances that conform. Clients can then filter using the _profile search parameter to ensure they only receive data they can safely handle - with the known cost that they won't necessarily have access to all data that exists.

  • Subsequent versions of FHIR may replace example value sets with preferred bindings if enough consensus emerges in the relevant sphere.
  • 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 change over time.
  • Extension minValueSet may be used to define the minimum value set that is required for conformance.

FHIR has defined a Terminology Service specification which sets requirements for systems that support the use of codes, value sets and code systems.