Building an Extension Definition

In FHIR, extensions are the way that you add elements to a resource that are not part of the core specification. By design, the core FHIR resources only have the most common elements that are used and it is expected that most real implements will need to add extensions to represent the specific Use Cases that they are working with.

One ‘rule’ in FHIR is that extensions MUST have a publicly available definition that a recipient can access to find out what it means (technically this is a StructureDefinition resource). This is done using a ‘canonical’ Url – one that is globally unique. It can either ‘resolve’ (ie type it into a web browser and it will be returned), or can be an ‘index’ for definitions stored in a registry like the official HL7 registry which is an instance of simplifier.

Ideally, Extension Definitions will be reused where that is appropriate – it increases interoperability when multiple people use the same definition. So before creating a new definition check the registry – and the specification – to see if there is already one you can use. If there is not, then you’ll need to create one (and, preferably, upload it to the fhir registry). There are a number of ways that you can do this – the Forge tool is the most comprehensive, but clinFHIR also allows you to create simple extensions, and we’ll discuss that here.

A couple of points before we start.

• Extensions can do anything that a ‘normal’ element can. This includes coded elements (in which case you can bind it to a ValueSet) and references to other resources.
• It is also possible for a single extension to support multiple datatypes, however clinFHIR doesn’t support that yet.
• As mentioned above – every definition will have a unique Url. In clinFHIR this is created for you by combining the name of the definition with the server where it is created (this is the ‘conformance’ server)

So let’s create an Extension Definition! (We’ll call it a ‘definition’ and sometimes ‘extension’ for brevity).

From clinFHIR select the Extension Definition builder. You’ll get a screen like this:

The boxes to the left allow you to search for definitions that are on the conformance server (HAPI 3 in this example). To the top right is a button labelled ‘New Extension Definition’. Clicking that button shows this dialog:

Start by entering a name for the definition (no spaces) and clicking the ‘Check’ button. Provided that the name is unique on the server, the green ‘Save’ button appears at the upper right, the the Url will appear in the box at the top right. You can alter this Url, but generally you can leave it alone.

Now enter a description of what the definition is representing, the publisher, and how many times it can appear in any given resource instance.

Next, you can enter a ‘context’ for the extension. This is which resource types can use the extension – and where in the extension it will be found. Clicking the ‘add context’ link to the middle right displays a dialog where you can select the resource type, and path within the resource. (If you’re not sure about the path, just leave it at the default). In the example below, we’ve indicated that this is an extension to be used in a Condition resource – but you can select any resource, and have more than one per extension.

The last thing to do is to indicate the datatype for your extension – but first a word about simple and complex extensions.

• A ‘simple’ extension is one that has only a single element – with a single value of the indicated datatype. For example, birthPlace
• A ‘complex’ extension can have multiple ‘child’ elements, each with its own datatype and value. (Actually, extensions can nest indefinitely, though it is unusual to have more than 2 levels). An example is ClinicalTrial.

Which you use will depend on your Use Case, but in clinFHIR they created the same way. Click on the ‘Add element’ to the middle right, and you’ll get a dialog where you can enter the details for a child element. If you only add a single child, then it will be represented as a simple extension – more than one will be a complex one.

You should always enter a description, but the child code is only needed (indeed it is required) when there is more than one child.

As we discussed above, you can use any datatype you need. If you enter a coded datatype (CodeableConcept, Coding or code) then a link labelled ‘Bind Valueset’ will appear. This allows you to ‘bind’ the ValueSet to that element – ie indicate the values for the element.

In the example above, the ValueSet ‘moonPhases’ has been selected, with a ‘required’ strength – indicating that the only permissable values are from this dataSet.

Don’t worry if you don’t know what ValueSet to use – you can always add it later on, or leave it to the FHIR experts to find it.

Once you’ve added the datatypes, click ‘Save’ to save the definition. Here’s a completed example:

Once you’ve created your definition (remember it is saved on the Conformance server) it is available for selecting in the Logical Modeler – and for use by a resource instance,

If you want to edit the definition at a later date, then you first locate it in the Builder by using the search parameters as shown below:

You can then click the edit button (lower right) to alter it.

To finish this page, a quick word about workflow. FHIR recognizes 3 statuses for the underlying StructureDefinition resource.

• Draft – it is still being built.
• Active – it is in use
• Retired – it is no longer in active use, but needs to be retained because there may be resource instances that refer to it.

This workflow is enforced by clinFHIR – you can delete a draft definition, but after it has been made active, it can only be retired.