Contained resources – MedicationStatement

Continuing our ‘mini-series’ on the SNapp event, one thing you may come across when consuming MedicationStatement resources are ‘Contained’ resources. We’ve talked about them before, but in the interest of having all the SNapp information in the same place let’s take a look at what they are.

Before we do, let’s take a look at the definition of the MedicationStatement resource in the spec. In particular, note that there are 2 ways for the resource to refer to the actual medication it is describing – medicationCodeableConcept and medicationReference (remember that when there is more than one possible datatype for a property, the property name incorporates the datatype).

And note that the multiplicity is 1..1 – you must have one (and only 1) of them.

The medicationCodeableConcept makes sense where all the information you want to record about the medication is found in the terminology that the code refers to. Here’s an example of it in use:

...
"medicationCodeableConcept": {
   "coding": [
     {
       "system": "http://snomed.info/ct",
       "code": "108551001",
       "display": "carvedilol"
     }
   ],
   "text": "carvedilol"
},
...

The medicationReference allows you to refer to a specific resource that represents the medication, and can have a lot more detail. This is useful when the terminology does not have all the data that you wish to record, but is undeniably more difficult to use as the client needs to retrieve the ‘referred to’ resource to get the full details, and it needs to be served up from somewhere. For this reason, many implementations will ‘contain’ the Medication resource inside the MedicationStatement. Here’s an example:

...
"contained": [
   {
     "resourceType": "Medication",
     "id": "med1",
     "code": {
       "coding": [
         {
           "system": "http://snomed.info/ct",
           "code": "7947003",
           "display": "aspirin 81 mg"
         }
       ],
       "text": "aspirin 81 mg"
     },
     "isBrand": false
   }
],
"status": "active",
"medicationReference": {
   "reference": "#med1",
   "display": "aspirin 81 mg"
},
...

(btw – I got these examples from the sample data that clinFHIR generates, as previously discussed. Aspirin is represented as a contained resource)

The contained resource can have any of the values that the resource would normally have (including extensions) but not text, and you can’t nest contained resources (ie a contained resource can’t have its own contained resources). You can, however, have any number of contained resources within the parent.

Note that the ‘parent’ element has got a reference to the id of contained resource which is a simple string prefixed by a ‘#’.

Now, it is possible for individual implementations to be able to restrict this behaviour using profiles. For example. I could have a profile that only allows the CodeableConcept and removes the ability to make a reference to a Medication, whether contained or a discrete resource (Though you’d want to be really sure that there will never be information about the medication that is not in the terminology – so it seems a brave step to make!). The argument about whether any particular piece of information belongs in the terminology rather than the structure is one that can provoke passionate opinions!

Note also that all FHIR clients need to be aware of, and be able to resolve, contained as well as external resources.