Changing a ValueSet in a profile

I learned something today.

Actually, most days I do learn something (and occasionally remember it later on) but this one is worth recording here.

One of the actions that is commonly done when profiling a resource is to change the binding of a coded element to some other ValueSet than the one in the spec. For example, in the UK CareConnect profiles, the Patient.gender element is bound to a different ValueSet.

In the StructureDefinition resource that defines the profile, this done by changing the binding – here’s the entry in the StructureDefinition (actually a child ElementDefinition) where this can be done:

Screen Shot 2017-06-20 at 7.37.36 pm

Note that there are 2 ways to do this – either the valueSetUri element or a valueSetReference. In the past, I’ve assumed that the valueSetReference (being a standard resource reference to a FHIR resource) required that the ValueSet be present at the URI that is the value of the element, whereas the valueSetUri refers to the canonical URL for the ValueSet (the ValueSet.url element).

So I’ve always used the valueSetUri, as I believed that it supported a registry of ValueSets (as well as other conformance resources) – you can query the registry with a query like:


But it turns out that that’s not quite right.

  • valueSetUri is intended to be used when the profile is not pointing at an explicit ValueSet resource – perhaps a document like an RFC that describes the options.
  • valueSetReference is intended to be used when the profile IS pointing to a ValueSet (or to an implicit ValueSet). It SHOULD resolve, but if it doesn’t then it’s perfectly permissible to look it up in a registry. This isn’t the way that ‘ordinary’ resource references work, but does for resources that have a canonical URL (like CodeSystem, ConceptMap and CodeSystem), and is intended to specifically support saving these resources in a separate registry (like Simplifier) if they can’t be directly resolved.

So there you are. If you are using a ValueSet to define the options for a coded element (which is always a good idea) you should always use valueSetReference.

Now I need to go fix clinFHIR. Bother.


As I thought more about this, I realized that this behaviour is not that different to an ‘ordinary’ reference. The reference is saying “The resource can be found at this location” – in fact it’s saying “the most recent version of this resource can be found here”. Because the location is globally unique, there’s nothing stopping there a copy being somewhere else – indeed, that’s exactly what we do in a Bundle – especially a Document bundle’. And you can even be explicit about the version┬áif you need to (as a copy may not be the most recent version of course).

So: not so different then.


About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

3 Responses to Changing a ValueSet in a profile

  1. wscrosswy says:

    Thanks for the informative post! Is there any implication that if a profile changes the binding to a different ValueSet, there must be some defined relationship between the old and new ValueSets? Perhaps that the new ValueSet is a subset of the old ValueSet? Or that concepts in the old ValueSet subsume concepts in the new ValueSet?

    • David Hay says:

      Glad you liked it! No, there isn’t a formal requirement (AFAIK) that there is a relationship between the old and the new – though it’s very likely that there will be significant overlap. Also note that the binding strength does have an impact here – for example, an extensible strength states: To be conformant, codes 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.

    • Lloyd McKenzie says:

      *If* the profile is “normative” from HL7’s perspective (i.e. locked into backwards compatibility mode), then there can be expectations around the relationships of the codes in the two value sets, depending on the strength of the binding. But there’s no expectation for relationships between the value sets themselves. (Take a look at the Value Sets and Code Systems rule here:

Leave a Reply

%d bloggers like this: