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.

We’ll describe this process in 3 posts.

• This one will describe the overall requirements, and will create and save the supporting resources in the registry
• Next up we’ll talk about how we can use clinFHIR to create the Profile and the Extension Definition
• And finally we’ll again use clinFHIR to create a resource conformant with our new profile.

Just a reminder here that clinFHIR is intended as a teaching tool. While it generates ‘correct’ profiles (Grahames server won’t accept them otherwise), it is not a complete tool as furore’s ‘forge’ tool is. It’s not as complete in functionality, and it shouldn’t be used to edit the profiles that are being generated as part of the spec .

So the Use Case we had was to generate a profile against Patient that specifies some functionality that applies in New Zealand. Specifically we will:

• Add an extension to represent the patients ‘iwi’ (tribal affiliation) of a patient if they are a New Zealand Māori. This extension would be a CodeableConcept bound to a ValueSet that contains the list of iwi (it’s a relatively small list)
• Make the patient identifier single, and require that it is from the NHI (National Health Identifier) system.
• Remove the ability to attach a photo to a patient.

So to do this, there are a number of supporting infrastructural resources we need to create and save in a registry (currently Grahames server) first. These are:

• The ValueSet resource that contains the list of iwi.
• A couple of NamingSystem resources to represent the NHI and the Iwi in the ValueSet.
• The Extension definition (a StructureDefinition resource) that we can associate with the Patient to actually record the iwi in a resource instance.
• The profile on patient itself (also a StructureDefinition) that brings all these together.

Here’s a picture of what this will look like when it’s all done.

Although we’re saving everything in the same server (Grahames), we’re actually using different ‘types’ of functionality – registry and repository – so we’ve indicated how they are different in the diagram. The NamingSystem resources don’t have a direct relationship from the profile or ValueSet so we’ve used a dotted line to indicate that this ‘looser’ relationship.

Our resource instance will ‘claim conformance’ to the profile.

So let’s get on with creating the ValueSet and NamingSystem resources. We have to do this manually as clinFHIR doesn’t (yet) have functionality to build them. In any case, if you’re following this exercise then they should be already in the registry (unless Grahame has cleared his server). We used an XML editor to create them, and then just used a REST tool to PUT them to the server (using PUT allows us to specify the id of the resource on the server).

Thinking first about the ValueSet –  because there isn’t a standard set of codes that we can use (at least that I could find), we created our own list. This is an example of where the ValueSet defines its own codes, rather than drawing them from some other terminology. Here’s a snippet from the ValueSet (It’s not a complete resource – for clarity we’ve only showing the parts we want to discuss):

{
    "resourceType": "ValueSet",
    "id": "nziwi",
    "url": "http://fhir-dev.healthintersections.com.au/open/ValueSet/nziwi",
    "define": {
        "system": "http://fhir.hl7.org.nz/valueset/iwi",
        "concept": [
            {
                "code": "kt",
                "display": "Kai Tahu"
            }
        ]
    }
}

A couple of things worth pointing out:

• The ‘url’ value is actually a URI – a globally unique identifier. It CAN be the actual location of the ValueSet (as it is here – and therefore a URL), but it doesn’t HAVE to be. It is simpler when it is a URL, so that’s what we’ll go with.
• Each concept has a code (which we made up) – which is unique within the context of this system, and a display for the user.
• The define.system value is a string that defines the ‘set’ of values – iwi. It needs to be globally unique – which is why it looks like a URI within domain that we control – but how would a consumer unfamiliar with iwi know what this codeset means? The answer is the NamingSystem resource.

As its name suggests, the NamingSystem resource defines what the value of the system property in a Coding or an Identifier datatype means. Here’s the one we created for Iwi (again, abbreviated):

{
    "resourceType": "NamingSystem",
    "id": "nziwi",
    "type": "codesystem",
    "name": "NZ Iwi",
    "description": "The set of New Zealand Iwi",
    "uniqueId": [
    	{
    		"type": "uri",
    		"value": "http://fhir.hl7.org.nz/valueset/iwi"
    	}
    ]
}

Of note:

• The ‘type’ value is ‘codesystem’ this time – indicating that it used to define the system for a – well – codesystem.
• The ‘uniqueId’ is where the actual uri itself is defined. As you can see, a single ‘system’ can have more than one type of Id – for example an oid (though those are really opaque – a uri is much nicer to the implementer)

So if you come across a system value that isn’t defined in the spec, you should be able to find out about it by querying your registry like this:

http://fhir-dev.healthintersections.com.au/open/NamingSystem?value=http://fhir.hl7.org.nz/valueset/iwi

– provided that the person who defined the system properly registered it of course. Check out the spec for the list of search criteria you can use. At the time of writing, the systems defined in the spec aren’t present as NamingSystem resources on Grahames server – I suspect that will happen once DSTU-2 has passed, and people have a bit more headspace.

We should also create a NamingSystem for our NHI. It looks something like this:

{
    "resourceType": "NamingSystem",
    "id": "nznhi",
    "type": "identifier",
    "name": "NZ NHI",
    "uniqueId": [
    	{
    		"type": "uri",
    		"value": "http://hl7.org.nz/ns/nhi"
    	}
    ]
}

So that’s all for the moment. We’ve created the supporting resources that clinFHIR can then use  to create a profile against Patient with an extension for iwi. We’ll describe this process in the next post.