Terminology services

Just a short post to call peoples attention to terminology services in FHIR. Rob Hausam (who co-ordinates the Terminology track at the connectathon) made the excellent comment in the Zulip chat that terminology is a ‘cross-cutting’ concern that can be integrated into many different applications – and tracks at connectathon.

There are a number of terminology services defined – this link (and the others in this post) is to the STU-3 candidate version that we’ll be testing at Baltimore so go take a look to see what you can use. Once the spec passes ballot it will be at the http://hl7.org/fhir/index.html location

As an example of using them, clinFHIR uses a couple of these services – let’s take a look at the ValueSet expansion service. This service ‘expands’ a ValueSet to return all the concepts within it. This is needed because a ValueSet will generally contain ‘rules’ defining the contents rather than listing all the options.

More usefully, when calling the service you can define a filter that will restrict the returned to only those whose description matches the filter – really useful for ‘auto-complete’ lists – which is what clinFHIR uses it for.

There are a number of different ways that this service can be invoked (and this can vary between servers). Regardless of the method you use, you will need the URL (which is globally unique) of the ValueSet you are interested in. To do this, take a look at the resource definition in the spec. A coded element will have a link to the ValueSet description in the ‘description & Constraints column. Here’s the link that I found for condition.code – you can see that the URL for this ValueSet is http://hl7.org/fhir/ValueSet/condition-code. The process is different for profiles of course – but that’s a discussion for another day.

Now that you have the URL, the simplest way to call the service is to call it with the URL in an identifier parameter, plus the filter. Strictly speaking the filter parameter is optional – but you should use it for anything other than small ValueSets.

Here’s a sample call:

http://fhir3.healthintersections.com.au/open/ValueSet/$expand?identifier=http://hl7.org/fhir/ValueSet/condition-code&filter=asthma

All going well, you’ll get back the ValueSet resource with the ‘expansion’ node populated with the matching concepts – these can then be used for your User Interface.

But if the server doesn’t support this syntax then you need to find actual resource id on the server and call it slightly differently.

First: query the server for the ValueSet based on the URL. For example:

http://fhir3.healthintersections.com.au/open/ValueSet?url=http://hl7.org/fhir/ValueSet/condition-code

This will return a Bundle of ValueSet resources (it’s a query remember) with – hopefully – only a single resource. You can then get the id of the ValueSet – in this case it is ‘condition-code’

Now we can perform the expansion using the alternative syntax:

http://fhir3.healthintersections.com.au/open/ValueSet/condition-code/$expand?filter=asthma

The result is the same as the first one – a ValueSet with the expansion node populated.

So there you are – it doesn’t get much simpler than that!