#FHIR Terminology Services Connectathon

This week I was in Washington DC for the inaugural FHIR terminology services connectathon. This was the first of its kind: a connectathon focused on the terminology services portion of the FHIR specification.

The following organizations were represented:

  • Apelon (on behalf of openHIE)
  • IMO
  • Regenstrief
  • Lantana
  • Nictiz
  • Smart Platforms
  • HL7 (through vocabulary co-chairs from MDPartners and Hausam Consulting)

The focus of the connectathon was on the two simplest operations in the terminology services API:

  • Given a value set definition, generate an expansion that contains the actual codes in the value set
  • Test whether a value set contains a code/system pair

Value Set Operations

In order to use or implement the terminology services API, the first thing to do is to understand value set expansions. Logically, a value set has 3 aspects:

  • A set of metadata that identify the value set and describe its purpose and the rules for its use
  • A “content logical definition” – the rules about what codes from what code systems are included in the value set
  • The list of actual codes in the value set (the expansion)

The key to understanding this is that content logical definition can be both complicated and/or not fully specified. The most common example is that the logical definition doesn’t fix the version of the code system, e.g. “take all procedures from SNOMED CT” – but which version of SNOMED CT? That’s delegated to the run-time environment.

This means that the process of converting from the “content logical definition” to the expansion is complicated, and is basically a job for terminology expert systems.

The FHIR terminology service API includes a very simple operation to fetch the expansion for any given value set:

GET [base]/ValueSet/[id]/$expand

This says that for the server’s value set [id], return the list of codes in the value set. It’s up to the server how it decides to generate the expansion – maybe it generates it each time based on the definition, or maybe it caches it internally and simply sends it.

Value set validation is easier – the client simply gives the server a system and a code and asks whether it’s valid in a particular value set:

GET [base]/ValueSet/[id]/$validate?system=http://loinc.org&code=2344-2

The server returns a true/false – is the code valid, and in the specified valueset? – along with human readable description of any issues detected.

Note that for these operations, there’s a number of syntactical variations to reflect the various conditions under which the operation is executed.

A key part of the first day of the connectathon was a mini-tutorial that was a detailed review of the value set resource, the expansion operation, and the way that the entire terminology service space works in the FHIR eco-system.

Connectathon Test Script

This connectathon introduced a new feature that we intend to introduce in future connectathons: a test script (view the source). The test script contains:

  • An HTML summary of the tests that a server has to pass
  • A list of setup actions to take in order to create the conditions for the test script to execute
  • A series of test cases, each of which consists of:
    • A logical FHIR interaction to perform on the server
    • Rules about the HTTP response
    • Rules about the resource that is returned

Note: The test script is actually written as if it’s a FHIR resource, though we haven’t actually defined a resource for this yet.

For the terminology services connectathon, the test script

  • Defined a series of value sets that contained different kinds of content logical definition
  • Performed a series of different expansion and validation operations, checking that the server returned the right result

For this connectathon, the terminology script could be used in the several different ways – as simply a detailed technical specification of the kind of things that were being tested by the connectathon, or as an executional test sequence using the FHIR Sprinkler tool. For this connectathon, several parties used the script, but needed to vary its content to account for differences in server functionality, and also the inner details of the various SNOMED and other code systems in use.

The test script wasn’t the only way to test – a number of participants used either their browser or the POSTman browser plug-in to test the functionality of the various servers represented at the connectathon.


Since this was the first connectathon, we didn’t have any particular expectations in terms of formal testing outcomes. So it was a pleasant surprise that by the second day, a number of participants were using the test script to automate testing their server for technical conformance to the specification.

In particular, the VSAC prototype FHIR server was passing all 55 tests in the test script – congratulations! (This doesn’t mean that VSAC is going to put up a FHIR server to access all the value sets as of tomorrow, but clearly that’s the end game. Of course, it will take considerable time for them to get to that point and depends on approvals, budgets etc).

That’s our desired end-point, though – that all the primary sources of value sets will make them available through a standard API, one that’s used by all the operational terminology services as well.  Really, this connectathon was initiated by the openHIE community, who are examining the FHIR terminology services API to see whether it’s suitable for adoption as their base terminology API for exactly this use. For the FHIR project, it’s our pleasure to work with openHIE, because there’s strong alignment between our two communities.

This connectathon also produced the normal outcomes that we’ve come to expect:

  • Foster continued growth of a community with strong interactions
  • Significantly increase the knowledge of the FHIR API in that community
  • Generate a series of suggestions for improvement in the FHIR specification itself

I’m really pleased with these outcomes – I’ve come to believe that the terminology space will be a significant early win for the FHIR community. With that in mind, the attendees felt that for future connectathons, it would be good to make them part of the overall FHIR connectathons held the weekend before the HL7 working group meeting. This would have several advantages, the most important of which is that we can start testing out practical ways to further the integration of terminology services into routine use of FHIR for clinical purposes. OpenHIE may also consider holding their own connectathon at some time.

At the moment, the only server that was tested at the connectathon that is publicly available is mine. It’s at http://fhir-dev.healthintersections.com.au/open, and it passes all the tests in the test script. Hopefully we’ll be able to add a couple more servers that will be available in an ongoing fashion.


p.s. I’m intending to make a follow up post soon about how simple the terminology service is to use in practice, but we’re pretty busy preparing the upcoming FHIR DSTU ballot.


  1. Matt Jenks says:

    Grahame, sounds like a worthwhile connectathon and a worthwhile pursuit. At the FHIR connectathon 8, http://wiki.hl7.org/index.php?title=FHIR_Connectathon_8. Mitre demoed a test tool that could be used to validate a FHIR server, http://projectcrucible.org/ which also has an xml script methodology. It was kicked around at the connectathon to attempt to converge these on a rich text scripting language like cucumber, http://cukes.info/. Do you think FHIR will suggest a reference implementation for test scripts based on something like this? Or a best practice, that promotes re-usability across FHIR test cases validation tools?

    • Grahame Grieve says:

      I haven’t looked at crucible much. But when I looked at the underlying scripting language, it seemed very difficult and abstract. If you look at the test script, you’ll see that it’s written as if it was a resource. This was at the request of other core team members who felt that this would be a worthwhile resource to have to share test regimes. Whether we should have something of our own or use something else – something we’ll evaluate through this year

Leave a Reply

Your email address will not be published. Required fields are marked *

question razz sad evil exclaim smile redface biggrin surprised eek confused cool lol mad twisted rolleyes wink idea arrow neutral cry mrgreen


%d bloggers like this: