Creating an Extension Definition – part 2: The URL.

In the previous post, we talked about the steps you might follow when creating an Extension Definition as part of profiling a resource. There were 2 steps that we glossed over because of space – the url, and extra work required for coded datatypes and identifiers. Let’s take a look at the url.

The url property (for example StructureDefinition.url or ValueSet.url) are intended to be globally unique identifiers for the resource (‘identifier’ is an overloaded word – we’re not talking about the Identifier datatype). When another resource wants to refer to it, then it can use the url to do so. (Note that we are not talking about FHIR references between resources – just that the resource wants to identify it)

When thinking about extensions, there are 2 main circumstances where we use the url:

• Where a resource instance has an extension value, there is a url property on that extension instance that identifies the Extension Definition (StructureDefinition resource).
• Within the Extension Definition, if the datatype is a coded one, then the url is used to refer to the ValueSet containing the possible values for that item. (Actually, it is also possible to have a direct FHIR reference to the ValueSet as well, though that’s less flexible).

We’ll consider the first use here – how the instance can identify the extension definition. Using it to refer to the ValueSet (and other resources) will be discussed in the next post (though it works in pretty much the same way)

The first thing to point out is that the URL doesn’t have to be the actual location of the extension definition. In the words of the spec:

Except for child extensions defined within complex extensions, the URL SHALL be an absolute URL. The StructureDefinition that defines the extension SHOULD be available at the identified location so that resource processors can access the definition from the URL

So you don’t HAVE to store the extension definition at the url, but it’s best practice to do so.

Lets take a step back and have a think about extensions and interoperability in general.

Extensions were developed to allow the resources to remain small and tightly focussed, yet support the additional elements that most real use cases will require to be exchanged. As the author of a resource, if we are populating the ‘core’ elements in the resource (eg Procedure.code) then we can be quite sure that any FHIR compliant client will know what it means (They might not actually process it – but that’s a different story).

But this doesn’t apply to our extension. To understand it, the client is going to need to retrieve the extension definition, decide if they are interested in it and update the application accordingly. There’s a certain amount of work involved in doing this and so the more widely used an extension is used, the more chance that the client will do that work – in fact the more chance that they already understand it. It’s in our interest to promote re-use.

You can think of different ‘levels’ of extensions

At the top there are those extensions that are defined in the spec. These are elements that are not so commonly used as to justify being in the core spec, but sufficiently common to try to get implementers to use them rather than developing their own – think religion, time of birth & nationality. Because they are so easy to find – they are listed at the top of each resource in the spec – the likelihood is very high that they will be used.

The next level is National extensions – those appropriate for a country. For example the New Zealand Maori tribal affiliations of Iwi and Hapu. Of great interest in New Zealand – less so in the UK. Generally, these extensions will be managed by the HL7 Affiliate for that country

And then there are local extensions – those that are specific to a single vendors implementation for example.

(This is not an ‘official’ list – there may well be others – but hopefully you get the point)

Each of these levels needs a registry – a place to store the extension definitions (and other artefacts), and the url to that registry is a logical ‘root’ for the url. For example:

• http://hl7.org/fhir is the root for the ones in the spec (Managed by HL7 International. So we have http://hl7.org/fhir/StructureDefinition/birthPlace for the patients birthplace
• http://fhir.hl7.org.nz could be the New Zealand one
• http://orionhealth.com/fhir would be the one for Orion Health ones.

The point of all this is that the url you use will depend on which level your extension definition is pitched at – the ‘higher’ the better. Right now the governance processes are patchily defined, but if you do think that you have an extension that belongs at the HL7 level, then contact the Work Group that looks after the resources you are interested in (there’s a link at the top of each resource page)

If you think you’re extension has national interest, then a good place to start will be to contact the local affiliate for advice. There’s a list of them – along with contact details – on the HL7 web site.

Otherwise, you’ll need to make your own arrangements. One option you could consider is to stand up an instance of the HAPI web server (We talked about that last year) as it has all the capabilities needed to store and expose these artifacts. You will need to think about all of the ‘-ities’ – availability, reliability, scalability, security. It is unlikely that you will get a high volume of traffic, but because it’s such an integral part of your resources being useable you do want to make sure that it is available most of the time. A good idea is to lodge a copy of your artefact (extension definition, valueset) in simplifier – it’s just a matter of getting an account there and uploading it.

And remember that regardless of where the Extension Definition is hosted, once it has been used in production it needs to remain there – unchanged – pretty much forever as it is describing clinical data. Which brings us to the topic of versioning – what do you do if you want to change an extension definition?

Well, in short, you can’t.

I guess you could add to descriptive elements – improved description, adding keywords but because someone may have taken and stored one of your resources with an extension in it, you cannot change its meaning.

What you can do is to change the status to ‘retired’ so that a client knows that it is no longer in use, and create a new one. But for the reasons mentioned above, even if you’re not using it any more, it does need to remain.

Creating extensions is a serious business!

Next up (and last in this little series) will be coded elements.

Other posts in this series:

• Part 1 – Creating an extension
• Part 3 – Coded items