Creating examples in FHIR

One of the things that the FHIR project team is particularly keen on is having lots of examples in the spec. People (especially implementers & developers) understand examples more easily than just plain text – and an example helps illustrate what the spec is trying to say.

And the examples in the spec are guaranteed to be correct – they are automatically validated as the spec is generated.

Creating examples of FHIR resources is actually quite easy – all you need are the schema and a validating XML editor (like XML Spy or Oxygen) and you’re good to go (a validating editor will ensure that the example you create is valid according to the schema – which is 90% of the way there).

There’s a couple of ways of doing this – those who are actually building the spec can do it from their local copy of the spec and commit directly to the version control system – but this does require setting up the environment and having commit privileges into the repository, so is not suitable for everyone.

In this post, we’ll assume that we don’t have that, and will create the examples externally. It’s actually quite easy.

First, download the schema from the spec site and unzip into a suitable folder. You’ll see that each resource has it’s own schema (these are automatically generated by the FHIR build process when a resource is defined – it’s quite a cool concept actually).

Next, create a new XML file in your editor, and associate that with the schema file. How you do this will depend on your editor – in Oxygen (which I use) there’s an icon on the toolbar that looks like a pin (with a mouseover called ‘associate schema’) – just click that, and you can select the schema.

Once that’s done, it’s a just a simple (!) matter of entering in the sample data. Because you associated the schema with the file at the beginning, the editor is able to supply you with valid options at each point (in Oxygen just enter a ‘<’ symbol and you get a popup of choices).

One thing that can be a bit tricky are references to external resources. As these are examples, they don’t have to refer to real instances of resources (though it’s nice to do so – https://fhir.orionhealth.com/blaze/fhir/Patient/77662 points to a real patient in Blaze for example). You can also (should also) put a description of the resource in the display property of the reference so a reader knows a bit about what you’re trying to say.

In some cases you really do want to show the referenced resource as well – for example in a MedicationPrescription you might want the Medication details. In this case the ‘contained’ option can be useful – though you might want to include a comment about it only being an example – please don’t do this for real!

You should also try to use realistic codes as well – these can be a bit tedious to find, but make a bit difference to the ‘quality’ of the example.

And don’t be afraid to use extensions if you need them, they’re really simple to use and a core part of the spec. Just use a made-up profile reference – like http://myserver/fhir/Profile/myProfile#myextension (but a bit nicer that that <s>)

And don’t forget the text narrative!

Once you’ve got your example, how to get it into the spec?

Well, the easiest way is to get one of the committers to do that for you. You could simply email the file to one of them or – more elegantly I feel – save the example in one of the public test servers, and send the id of the resource instead. (This will be assigned by the server, or you can try PUTting it yourself). This has the added advantage that the servers will also generally validate the resource as a final check before saving  – Blaze is particularly brutal as it applies the schematron as well as the XSD validators.

Oh – you probably need to remove the reference to the schema before you can upload it eg:

<ReferralRequest xmlns="http://hl7.org/fhir" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:schemaLocation="http://hl7.org/fhir ../../schema/referralrequest.xsd">

becomes

<ReferralRequest xmlns="http://hl7.org/fhir" >

do that at the last minute (I tend to get it all working in Oxygen, then copy from there and paste into my REST client – I use POSTMan in chrome – then remove the declaration).

Who to send it to? I’m tempted to say ‘send it to Lloyd or Graham’ – but I’m not sure they would thank me for that <s> – so send it to me at the moment and I’ll make sure it gets to the right person.

Creating examples manually won’t work for all scenarios – more complex ones like referral might need a different approach (like the tool being planned for the Clinical Connectathon) – but is quite adequate for simpler cases like a Condition, AllergyIntolerance or CarePlan.

So that’s it. Go forth and example-ize!