Building resources from FHIR profiles.

This post finishes off our ‘mini-series’ on creating a simple profile using clinFHIR – now we’ll create a resource based on the profile that we created earlier.

Read more of this post

Using clinFHIR to create a profile

In the previous post, we outlined our plans for creating a profile against the Patient resource, and manually created and saved some of the supporting resources (ValueSet and our NamingSystem) that we’re going to need.

Next up is the extension definition and the actual profile against Patient. Once we’ve done that (which is the topic of this post) we can actually create conformant resources.

Fortunately, we can use clinFHIR to create these artifacts, so start up that application and select the ‘profile builder’ from the front page. (And a reminder that this is very much ‘beta’ software designed for training! Let me know of any issues)

Read more of this post

Creating and using FHIR profiles

One of the things we discussed at the recent seminar in New Zealand was profiling FHIR resources. This is where we take the base resources and then adapt them for specific use cases. While quite simple in concept, there are some complexities ‘under the hood’, so part of the talk was to describe some of the ‘infrastructure’ that makes all this work.

Once we had the set up some of the supporting resources, we used the clinFHIR tool to actually assemble the profile, as this makes it easier for ‘non-technical’ people – especially clinicians – to build these artifacts, and then build a resource that is conformant to that profile.

Read more of this post

FHIR DSTU-2 Profiles

A couple of posts on Profiles in the DSTU-2 candidate from the guys at Furore:

These guys have been involved with – and supported – FHIR from the very beginning, are the maintainers of one of the FHIR test servers (Spark) and are also the authors of the reference profile editor (forge) so they know their stuff!

Extension Viewer Update

I’ve posted an update to the Extension Viewer that I’ve been working on over the holidays.

Read more of this post

Profiling resources in DSTU2 – part 2.

Actually, on reviewing the previous post about profiling in DSTU-2, I realize that there is a simpler way of applying extensions to a profile (in addition to the Conformance package). If you look at the Profile resource, it contains 2 main parts:

  • Metadata about the Resource/Datatype being profiled (name, identifier publisher etc) plus the name of the resource and a link to the base profile that is being modified (eg the profile that describes the core resource in the spec).
  • A collection of elements (of type ElementDefinition) each of which describes one of the elements/properties within the resource.

(To be precise, there are 2 collections of elements in the profile:

  • The differential – which describes the difference between the base profile
  • The snapshot – which describes the profiled resource completely

the reason for the two is to support tooling – we’ll focus on the snapshot for now).

Read more of this post

Profiling FHIR in DSTU-2

As we mentioned in the previous post, profiles have changed significantly in the next DSTU.

Profiling is a really important part of FHIR. The resource themselves are designed to be quite generic ‘building blocks’ that can be used in many different contexts. If you take a look at one, you’ll notice that almost all of the properties are optional and even where coded properties have Terminologies assigned to them, these are often quite ‘loose’ and designed to be amended by a Profile

Read more of this post

FHIR Clinical scenarios: Nutrition Assessment

We’ve had a couple of posts recently (well 3) talking about how we can use FHIR resources to represent some common clinical scenarios as a prelude to the clinical connectathon in September. Each of the scenarios exercised a different part of FHIR (and had a slightly different clinical focus):

  • The Chronic Care Scenario has a heavy emphasis on the Care Plan
  • The Acute Care scenario provoked a discussion on how we should be using the Encounter resource – and further highlighted a need to refer form an Observation to an Encounter
  • And finally the scenario dealing with Allergies led us to think about my favourite resource – the List.

(Here’s a bit more detail…)

There’s been a bit of discussion in the HL7 lists recently about the concept of a Clinical Assessment – and how best to represent it in FHIR. As it turns out, one of the scenarios put forward by Patient Care that we won’t be exercising (yet) is the process around making a Nutrition Assessment, and Elaine (one of the Patient Care co-chairs) has asked if I could do a post on this scenario to help stimulate discussion – so here it is.

Profiling a FHIR Careplan for Immunizations

After the previous discussion on how to represent an Immunization plan, I had intended to talk about how to represent the Immunization protocol (or schedule), and how to apply that to a patients’ plan, but (as so often happens) I got a bit side-tracked, and thought we could first think about how we might create a Profile against the CarePlan resource to represent an immunization plan.

Now, we’ve talked about FHIR profiles before so I’m not going to repeat that here, other than to say that it is the profile that takes a standard resource (or resources) and makes them fit more precisely to a particular Use Case of some sort, so profiling CarePlan to support an Immunization plan seems a perfect fit!

There’s actually quite a lot to do to get a good profile (and I’m sure I haven’t got it completely correct), but at a high level, once you have your use cases you go through the resource and:

  • Alter multiplicity of elements (e.g. to make an optional element required or not used. Remember you can’t make a required element optional though)
  • Specify a particular terminology or codeset for a binding (and often you’ll define a ValueSet to hold the list of allowable codes)
  • Add a new element (as an extension) where it’s needed by the Use Case but not defined in the base resource

(There’s other things you can do as well, but that’s enough for our current needs).

Overall design

Here’s the structure of the Care Plan resource (Sorry about the image quality – its a screen scraping from my computer – here’s the original)

Screen Shot 2014-05-27 at 1.48.31 pm

How we’ll structure our profile overall is to use the goal element to list the diseases that this plan is intended to protect against (using an extension), then optionally link the activities back to the goals/diseases that are covered by that vaccine. That way we can say which activities contribute to protection against which disease. We’ll make this all optional, as not everyone will want to go to this level of detail (and, in truth, is probably a bit overkill). (btw – Another way of doing the same thing would be to add extensions to the activity directly to indicate the diseases being covered)

The activity will generally be the administration of a vaccine, however we’ll keep it a bit flexible to allow for, say, educational sessions as part of the plan. We’ll know which activity is an vaccination because the activity.simple.category will have the value ‘drug’.

We only need to profile the CarePlan resource for this Use Case.

For simplicity, we’ll put all the extensions in the same profile – in real life we might try to re-use existing extensions or to make some of ours a bit more general. This will really need common registries of profiles, which the FHIR team are working on at the moment…


So the following section lists the changes (in a textual format) that we’ve going to make to the CarePlan resource to allow it to hold the information required to represent an immunization plan. Each entry has the path to the element, followed by the multiplicity (which may not be the same as that in the base resource). If the entry is an extension (and remember that extensions can be at any level in a resource) then the path will end in a #{extensionDef code} and the data type will be displayed. Thus:

Careplan.goal#disease (0..1) CodeableConcept

means that this extension is against the goal element of the CarePlan resource, that it’s optional and there can only be one, and that the datatype is CodeableConcept.

If the values of the element (extension or base element) come from a ValueSet, then we’ll place the name of the ValueSet in square brackets at the end. Eg

Careplan.Activity.simple.code (1..1) [immunizationVaccines]

means that the value of the code (which is required in this profile) comes from the valueset whose name is immunizationVaccines. (Actually, this should really be a complete URI, but we’ll keep it simple to avoid cluttering the page). Note that this layout is just the one we’re using for this post – the formal representation will be the profile resource and maybe other artifacts that the core team is working on.  (Actually, I think the next connectathon is going to focus on profiles and conformance)

So, here we go. To minimize space, we’ll only include entries that are different to the base resource, or where there’s a particular comment to make.

We’ll also do this in 2 posts. This one will be more of a ‘design’ session – what we’re going to do and why. The next post will build the actual profile.

Items in the Profile

Careplan#protocolDescription (0..1) string

An extension where we can describe the protocol that this plan was drawn from.

Careplan#protocolUri (0..1) uri

A direct link to the protocol (if known).

CarePlan.patient (1..1)

You have to have a patient in our plan…

Careplan.patient#dob (0..1) date

The patients Date of Birth. This is a bit naughty as you should really retrieve the Patient resource and look up the Date of Birth from there. The reason to include it here as an extension is to allow us to be able to determine if an immunization is overdue just on the information in the plan. In reality, you probably woudn’t do this but, hey, its my blog and I’ll de-normalise if I want to

Careplan.period (0..1)

This would be the age range over which the immunization plan was active – eg from birth to 18 years

Careplan.modified (1..1)

This should be updated when the plan itself is changed – ie a new activity is added, to the status of an existing activity changed. The multiplicity is changed to make it required.

Careplan.concern (0..0)

As this plan is specifically about immunizations, the concern is not needed – i.e. the whole point is to avoid the patient getting those conditions. Change the multiplicity to 0..0 to remove it.

Careplan.goal#disease (0..1) codeableconcept

We’ll use the goal to list the diseases that this plan is intended to protect against, then optionally link the activities back to the goal. That way we can say which activities (immunizations) are protecting against which diseases. Note that there’s only a single disease per goal, but multiple goals per plan.

Careplan.goal.status (0..0)

The overall status of the plan is at the careplan level, not the goal.

Careplan.goal.concern (0..0)

Same notes as for careplan.concern.

Careplan.Activity#immunization (0..1) ResourceReference

An extension that references the Immunization reference. Should be populated when the vaccine is either given or offered and declined.

Careplan.Activity.goal (0..*)

To allow us to link this activity back to the goals (the diseases this vaccination is intended to protect against) if we want to.

Careplan.Activity.status (0..1)

Really the only codes that makes sense here are ‘completed’ and ‘cancelled’. However, this is a fixed code set in FHIR so we can’t change it. If due then we can either leave it blank, or we could use the value ‘not started’ or ‘scheduled’

Careplan.Activity.actionResulting (0..0)

Don’t want to record this in the plan

Careplan.Activity.detail (0..0)

The careplan.activity.notes can capture the level of detail that may be required, so this is not required.

Careplan.Activity.simple.category (1..1)

Fix the value as ‘drug’. We might want to suggest that ‘immunization’ be added as an option to the base resource.

Careplan.Activity.simple.code (1..1) [immunizationVaccines]

This will be the vaccine that is to be given so is mandatory. The value is drawn from the immunizationVaccines ValueSet

Careplan.Activity.simple.code#numberOfDoses (0..1) integer

The number of doses of this vaccine that are going to be given altogether

Careplan.Activity.simple.code#doseSequence (0..1) integer

The sequence number for this dose

Careplan.Activity.simple.timing (1..1) Period

Fix to use a period and make required. The ‘start’ property is required. ‘end’ is optional. This will be the period over which the vaccine must be given to be effective.

Careplan.Activity.simple.location (0..0)

No need to specify location in the plan

Careplan.Activity.Simple.product (0..0)

This information is in the code

Careplan.Activity.simple.dailyAmount (0..0)

 Not needed

Careplan.Activity.simple.quantity (0..0)

Not needed

So now that we have an idea about what our profile is going to look like, we can build the profile itself. That will be the topic of the next post!


FHIR Profiles: an overview

I’ve been spending a lot of time recently looking at Profiles (we’re building a tool to help manage the ones we’re creating at the moment).

As we start to implement FHIR interfaces in real systems, we’ve come to appreciate just how important profiles are going to be. The reason  is that FHIR is essentially a set of basic building blocks (health-IT lego if you will) and some rules around how to manipulate them. The specification is deliberately very flexible to allow the blocks to be used in lots of different scenarios, both in terms of interoperability paradigms (document, message, REST, service) but also in different countries that can have vastly different requirements in terms of content, terminology, privacy and the like.

Furthermore, and again by very deliberate design, the ‘core’ contents of resources are limited to those elements that are currently being used by most implementers world-wide. This is to keep them manageably sized – the so-called ‘80%’ rule (which, unfortunately, has caused a lot of confusion as my colleague Edward has complained about). From a FHIR perspective there is no difference between core and extension properties – it’s just that the core properties are more common. (Perhaps we should have called extensions ‘special’ elements rather than ‘extensions’…)

What all this means is that in practice when you start to use FHIR for real, you’re likely going to need to adapt the resources to suit your own requirements, and that is where profiles come in.

A sample process might be:

  • Start with a set of requirements (Use cases, user stories, story boards etc).
  • Define the behaviours and the data models you’re going to need. (Behaviours – e.g. queries, workflow, updates, services etc. are outside the scope of this post – but you’d document them in the Conformance resource).
  • Once you have the data model (and these may be in a form like openEHR archetypes – or just a simple table), you then need to map these to the FHIR resources. It’s at this point that you’ll likely find:
    • There are some things you want to exchange that aren’t in the current resources
    • The resources have elements that you don’t want to use.
    • You will want to be more specific about some aspects of the resource – e.g. use a specific terminology for an element, or make an element required rather than optional
    • There might even be models for which no resource can be found. Again this is a bit outside the scope of what we’re talking about here – an option is to use the Other resource (originally known as the resource-with-no-name) and define everything as extensions in a profile.

It’s the profile that allows you to define these differences in a way that the people with whom you are interoperating can understand what you’re trying to say.

So what can you do with a profile? Broadly there are 2 things that you use them for:

  • Adapting the core resource structures to meet your requirements
  • Defining extensions on resources – extra properties needed for your use case.

And there’s a third category – metadata. Metadata is all about describing what the purpose of the profile is (what requirements it fulfils) and discoverability.

  • If we are a server then a client can read our conformance resource, which will list the profiles we support (and provide a link to them).
  • If we are a client, we can tell a server that we conform to a profile (the server will probably still check).
  • If we receive a resource with an extension we don’t recognise, it will point to the profile in which it is described so we can decide what to do with it.

It’s important to appreciate that a single resource instance can have extensions from many different profiles, hosted by many different servers (a profile is just a resource after all – anyone can store them). And also important to appreciate that a profile cannot change the definition of a resource in such a way that it cannot be processed without referring to the Profile – this is the reason behind some of the thing you can’t do with profiles.

And when you design – and use – profiles, you really need to be thinking about re-usability – as Lloyd commented on the previous post, it’s better to have a generic profile/extension that can be used in multiple places than a specific extension that can only be used in one. Or even better, use one that someone else has defined – discoverability of ‘prior art’ is something that we really need to work on, which will be facilitated by the availability of public registries for profiles, and better searching – codes, tags – that sort of thing.

Anyway, on with some more detail on Profiles.

Adapting the core resource structure

Each element in a resource can have a number of characteristics

  • Its name
  • One or more datatypes
  • Multiplicity (how many there can be in a resource)
  • Possibly a binding to a terminology (which may or may not be defined in the spec)

Apart from the element name, the Profile can be used to constrain any of these characteristics – within limits. The following sections describe the most common things you might want to use a profile for.


You can specify that for your Use Case, the datatype must be a specified sub-set (or just one) of those defined. For example, Observation.subject can be a Patient, Group, Device or a Location, but in your use case, it might only make sense to be a Patient. Note that you cannot specify a datatype that is not already one of the options (or a recipient that didn’t know about your profile wouldn’t know what to do).


The following table shows how you can alter the multiplicity, with the rows being the multiplicity in the spec and each column being a multiplicity you can specify in the Profile.

(Not used)
(optional, many)
(at least 1)
0..1 yes yes no yes no
0..* yes yes yes yes yes
1..1 no no no yes no
1..* no no no yes yes

In summary:

        • If it’s already optional then you can make it required or not used.
        • If it’s already required then you can’t make it optional
        • If more than one is allowed, then you can restrict the number (this is called ‘slicing’ – refer to the spec for details)
        • If only 1 is specified, then you can’t make it many.

The following snippet shows how we’ve restricted the datatype of ‘asNeeded’ in the MedicationPrescription resource to Boolean, and also made it required, by setting both min and max to 1.

    <type value="MedicationPrescription"/>
    <name value="asNeededConstraint"/>
        <path value="MedicationPrescription.dosageInstruction.asNeeded"/>
            <short value="Only support boolean in the 'asNeeded' property"/>
            <formal value="Only support boolean in the 'asNeeded' property"/>
            <min value="1"/>
            <max value="1"/>
                <code value="boolean"></code>
            <isModifier value="true"/>


Many of the elements can refer to a code-set, a terminology or a ValueSet. These elements generally have the datatype of coding or codeableConcept. In most cases the spec doesn’t say which terminology to use (though there will often be examples or recommendations). You can use a Profile to specify a terminology or ValueSet you want to use.

(Note that the code datatype is generally bound to a fixed set of values than cannot be altered in a Profile. These are reserved for elements that are generally used in workflow scenarios – ‘status’ elements are the most common).

The following snippet shows how we’ve restricted the code values that can be used for medications to those defined in a ValueSet of ULM (Universal List of Medicines) codes that a GP (Ambulatory care) clinician can prescribe. We could also have used a direct reference rather than the  ValueSet, but the ValueSet allows us to filter the list.

    <type value="Medication"/>
    <name value="medicationCodeConstraint"/>
        <path value="Medication.code"/>
            <short value="GP ULM Codes only"/>
            <formal value="Specify that the medication code must come from the NZ ULM codeset"/>
            <min value="0"/>
            <max value="1"/>
            <isModifier value="false"/>
                <name value="List of medications GP's can prescribe"/>
                <isExtensible value="false"/>
                    <reference value="http://www.nzgovt/fhir/ValueSet/ulm-gp"/>

Default Values

You can’t set a default value. The reason for this is that if you could, then it wouldn’t be safe to process a resource without referring to the Profile – which would severely impact on usability.


As we’ve discussed previously, we use extensions where we have some data that we wish to exchange that is not currently in the FHIR resource.  We’ve talked about extensions before and made some notes about them when thinking about code sets, so we won’t go over that again but everything that you can do to a structure (core element) you can do with an extension – in fact much of the definition in the profile is the same for both.

Last Word

As I hope you agree, the profile is an important resource to get your head around – and to use. When the public registries become available, re-use of profiles and extensions is going to become a lot easier – but in the mean time you can practise using Grahames  or Ewouts server.

And remember that the enforcing of the constraints described in the profile is completely up to you. FHIR gives you the mechanics to describe these constraints in and easy to use, computable way. It’s up to you to adhere to / validate those constraints.