FHIR Terminology Service

This page is a draft that is intended to be incorporated into the FHIR specification for DSTU 2

Introduction

The FHIR specification includes support for the provision of a consumer level terminology service. The following facilities are provided:

• Editing Value Sets
• Getting a list of codes for UI
• validating that a code is correct
• translating from one code system to another
• maintaining a closure table

This page describes how these services are provided to support both servers and clients. A server that supports all the functionality described here can be described as a "FHIR Terminology Service", and SHALL conform to this conformance statement - [link to be provided].

Security

For the operational services, OAuth is generally not an appropriate form of security for an infrastructural service like a terminology server. A terminology server may choose not to authenticate the clients in any fashion, but can do so in order to limit or account for usage. Since terminology servers do not directly handle patient information, it is not necessary to protect the communications with SSL, but hackers may be able to infer information about patients to observing the kind of codes that are retrieved, so encryption, possibly with client verification of credentials, may still be a good idea.

For the value set maintenance server, OAuth may be appropriate, or some other login method might be used.

Code Systems and Value Sets

The FHIR specification is based two key concepts:

• code system - defines a set of codes with meanings (also known as enumeration, terminology, classification, and/or ontology)
• value set - selects a set of codes from those defined by one or more code systems

Note: Proper differentiation between a code system and a value set is important. For instance, it's not unusual to see a mixed list of codes containing a set of LOINC codes with some additional in-house codes, with no explicit differentiation between them; only the fact that code happens to look like a LOINC code betrays it's origin. In FHIR, on the other hand, each code system that defines codes has a URL, and the codes they define are a pair ("Code Pair") - a name with a namespace. So in this example, there is two code systems: LOINC (http://loinc.org) and a local one (e.g. http://example.com/codesystems/additional-test-codes). Then there's a value set, which says that it includes some codes from each of those two namespaces - a set of Code Pairs. The value set itself gets a 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 code pair. In FHIR, Code Pairs are always represented as "code" and "system", except for the simple type "code" data type where the namespace (e.g. the system element/property) is fixed in the schema and not represented explicitly. The URL in a system element is always a reference to a code system, not to the value set.

Users wishing for more information about the underlying principles may wish to consult the Core Principles (link)

ValueSet Resource

FHIR defines a single resource named "ValueSet" which defines a set of Code Pairs. A value set resource can include code pairs defined elsewhere by:

• importing set of code pairs from other value sets
• including codes from code systems by listing (enumerating) the codes (this is known as an extensional definition)
• including sets of codes from code systems based on their properties (this is known as an intensional definition)

In addition, a Value Set resource can define it's own code system. Codes defined in this inline code system are also included in the value set using the URL explicitly assigned to the code system in the valueset.

The Value Set resource is the fundamental building block for a terminology server - it manages a repository of value sets, allows selected users to edit them, and provides services based on the definitions in the value sets.

External Code Systems

In order to be used with a value set, code must be defined somewhere. They can be defined as part of an inline code system definition, or they can be defined elsewhere, and then used in a value set by quoting the correct namespace. The FHIR specification defines a set of namespaces (link) for commonly encountered code systems, and defines how some work with FHIR (links, SNomed, LOINC, RxNorm). These code systems are often large, and have many internally defined properties that are part of their formal definitions. Inline code systems are not appropriate for these code systems; FHIR does not provide an formal representation at all. Instead, it is assumed that these are externally known.

Most useful terminology servers will make one or more of these external code systems available for use within the value sets that they manage. The list of additional terminologies that a terminology supports beyond those defined in it's value sets is published to clients by (still to figure out how this works).

Implementation Note

When a terminology server exposes an external code system, it makes a set of services available internally that serve the operational interfaces below. The internal server depends on the following logical statements for a terminology:

• it's URL (namespace, and how versioning works)
• what codes are valid
• what properties can be used to select codes
• what implicit value sets exist

The FHIR specification itself defines these things for (links, Snomed CT, LOINC, RxNorm).

Note: A terminology service may choose to expose additional external code system specific related functionality such as exploration, or structured search, but these services are outside the scope of the FHIR terminology service.

Concept Maps

In addition to value sets, the other resource that contributes to the terminology service is a concept map. A concept map can translate between two structures, or two values sets; only the second aspect is relevant for a terminology server. A concept map maps from one value set to another. Note that the mappings are one way - from the source code system to the destination code system, and they are only defined in the context of the source and destination valuesets. The mappings may be useful in other contexts, but this must be determined based on the context of use and meaning; it cannot be taken for granted automatically. Each mapping from source to destination also includes an [equivalence] property that specifies how similar the mapping is (or, in some cases, that there is no valid mapping).

The server can use the concept maps to augment the information provided through the value sets and the inherently known terminologies.

Terminology Maintenance

The terminology service uses the value set resources defined on the system - both the implicit ones associated with the external code systems and those explicitly available at the /ValueSet endpoint - to serve the operational interface defined below. As value sets are created, updated or deleted, the outcomes of the operational services change. A terminology server should validate incoming resources, and ensure integrity of the terminology services. Typically, servers would provide a test and production environment, but there is no explicit notion of this in the interface itself.

Value Set Expansion

As described above, a value set describes a set of rules for what codes or concepts are considered to be in the value set. These rules might be simple - a direct list of codes, or they might be quite complex. A FHIR client (or other process) can simply ask the server to figure out all the details, and give it a list of the current codes in the value set. This is known as "expanding" the valueset. The client passes the server the following information:

• The identity of the value set (or it can pass the value set directly)
• A text filter to use to restrict the codes that are returned (e.g. user input text)
• A date at which the expansion should be evaluated (usually, this is the current date/time, but there are circumstances where that is not appropriate)

The server returns a value set that contains the current list of codes, or an Operation Outcome with an error. Note that some value sets expand to many thousands of codes, or an infinite number, and so these value sets are generally not expanded (the server returns the code "too-costly" - the client can try again with a more specific text filter).

Here's some example uses for the expansion operation: (todo)