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. 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].

Notes from Michael Lawley's talk at HL7 Australia - issues to be addressed

• value sets identified by URIs or URLs?
• mention difference between namespace in snomed and this description?
• make rules about repeating codes more obvious (Michael didn't see them)
• make it more obvious when you'd use define.
• also make it more obvious how to publish the list of supported code systems
• make the pages that describe code systems more obvious
• improve the definitions of mapping equivalence, and change "inexact" map to "overlap"
• explain date of expansion better
• paging on expansion if too long?
• date parameter on validation missing
• check that literal URL parameter option is documented for expansion
• make explanation of what are display names clear on snomed page
• clarifications on subsumption testing
• get better snomed CT value set uri from Michael
• allow conceptmap to be specified for a translation?
• talk to Michael L about closure tables

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 even an infinite number, and for these, the server returns an error code "too-costly". In these cases the client can try again with a more specific text filter.

Here's some example uses for the expansion operation:

• get a list of codes to display in a User interface (e.g. a drop down interface)
• a variation on this is to offer the user a text box to type in. As they type, call the expand operation to provide the user with a list of matching codes/concepts (like a browser search)
• fetch a list of codes to use when generating software code
• get a list of codes so that software can check whether a code is valid or not in a particular context

Value Set Validation

As described above, one of the ways to determine whether a code is in a value set is to expand the value set, and see if the code is in the expansion. However this is not an efficient way to test whether a code is valid, and for some value sets, it cannot work. Instead, a FHIR terminology server provides a "validate" operation. The client invokes this with 2 parameters:

• the value set (either by it's URL on the RESTful interface, by it's logical identifier, or as a parameter to the call)
• the code value (either a code+system, a Coding data type, or a CodeableConcept

The server returns a true/false indicating whether the code/concept is valid, and a list of errors and warnings associated with it. The server should also return all the display names that are associated with the code as part of this operation.

Note that if the server is passed a CodeableConcept, the server is able to check whether any of the codes are valid against the value set, and also check whether multiple codings are allowed and/or consistent with each other.

Subsumption testing

The Expand and Validate operations can be used to perform subsumption testing. To test whether code A subsumes code B, perform a validate specifying a value set built of all the codes that are subsumed by A, and test whether B is subsumed by it. Note that a server is allowed (and should, but it not required to) consider concept maps when doing subsumption testing. E.g. if A is a LOINC code, and it has a precise mapping to a SNOMED CT code that subsumes B, then the server can indicate that this is valid.

In order to make it convenient to perform this subsumption testing, code systems that define subsumption heirarchies should define simple URLs to express a value set that includes all the codes subsumed by a code. For instance, for SNOMED CT, the URL http://snomed.info/sct?fhir_vs=isa/[sctid] means all the codes subsumed by [sctid].

Translations

A client can ask a server to translate a concept from one value set to another. Typically, this is used to translate between code systems (e.g. from LOINC to SNOMED CT, or from a CDA code to a v2 code). The client calls the translate operation and passes 3 parameters:

• a code+system, Coding, or CodeableConcept
• the value set for the context of the source
• the value set for the destination

If there is no particular context, the appropriate value sets would be the value sets for the entire coding system at question (e.g. from http://snomed.info/sct to http://loinc.org/vs).

Maintaining a Closure Table

The 3 operations Expand, Validate, and Translate account for most operational requirements associated with terminology use. However there is one difficult but important use case that they do not address, which is integrating a terminology logic into application search.

A typical example of this is a user that wants to find any observations for male patients over the age of 50 who attended a particular clinic within a particular 2 week period, with a diagnosis of gout, and who had an elevated serum creatinine.

in this case, both "diagnosis of gout" and "serum creatinine" involve subsumption queries (e.g. against SNOMED CT and LOINC respectively). This search has to be executed by some logical processing engine that knows how to find this data in a given persistence store. Often, this is some kind of SQL query, though many other technological choices are available. However this is done, the challenge with an operation like this is to integrate the terminological knowledge with search execution. Using the expand operation above, the system executing the search could generate expansions, and then search for these expansions. This has a couple of problems:

• the list of subsumed codes could be very long, and the search operation becomes correspondingly inefficient
• the expansion of the subsumption might not be closed, and so the search operation can't be correct

An alternative approach is to generate a subsumption [closure table], which lists all the possible relationships, and allows for rapid execution of these kind of queries. However this has other problems:

• the subsumption table can be very large (>500000 records for SNOMED CT), even though very few of the codes are used
• subsumption tables are generally built up front, and don't deal with new codes very well
• they still don't offer a solution for non-closed expansions

This is the reason why most systems don't support post-coordination or other forms of coded expressions.

In FHIR, this problem is solved by building a closure table on the fly, as new codes are seen. This technique leaves the FHIR terminology server responsible for the terminological reasoning, and the client responsible for the closure table maintenance. To the client, it doesn't matter whether the concept is post-coordinated or not. Here's a description of how the process works:

1. The client defines a name associated with a particular context in which it wishes to maintain a subsumption based closure table.
2. The client registers this name with the FHIR Terminology server using the $closure operation (described below), with only one parameter, the name of the context
3. any time the client system encounters a new Coding that isn't entered in the closure table, it calls the $closure operation with the context name, and the Coding value it has encountered
4. the server returns a ConceptMap resource with a list of new entries (code : system -> code : system) that the client should add to it's closure table
   1. the server can indicate that entries should be removed from the table by providing a (code : system -> code : system) with equivalence "unmatched" (though it's not known why that would be needed)
5. The client makes these entries into it's closure table
6. to facilitate the initialization process, a server can call $closure with multiple Coding values

The $closure operation takes 2 parameters:

• Closure table context name
• Coding to enter into the table (0 or more - 0 codings is a request to initialise the table)

The operation returns a concept map which has a list of mappings that represent new entries to make in the closure table.

The closure table can be resynchronized by passing an additional version parameter, which is a value taken from the version in one of the delta responses. This is a request to replay all the mapping changes since that delta was sent.

Functional Operations

In order to support terminology operations in FHIR a minimal set of terminology operations would be necessary. These operations are a sub set of the available terminology service operations defined in the Common Terminology Services - Release 2 (CTS2) specification and can be categorized as:

• Administrative Operations
• Search/Query Operations
• Authoring/Maintenance Operations

Functional operations within these categories support the access and management of terminology objects such as Code Systems, Concepts, Value Sets and Concept Mappings. The functional operations necessary to support a FHIR terminology service are outlined here.

Administrative Operations

• Be able to load a standard or local code system

Search/Query Operations

Concepts

• Retrieve the concept details (display name, qualifiers, associations, etc.) for a given code/code system
• Return possible concept matches based on search criteria
• Validate whether a code is valid within a given code system (content)
• Retrieve a list of codes (for example, to populate a user interface)
• Return the decedents of a given concept

Code System

• Retrieve the metadata for a code system

Value Set

• Retrieve the metadata for a value set
• Return a value set based on search criteria
• Determine if a code is valid in a value set
• Generate the Value set Expansion from the Value Set Definition.

Mapping

• Retrieve the metadata for map set
• Retrieve a translation (mapping) of concept(s) from a given source code system to target concept(s) from a target code system

Authoring/Maintenance Operations

Concepts

• Maintain a closure table

Value Set

• Create/editing a value set

Mapping

• Translate (map) from a source code system to a target code system