Family FHIR – with sushi

I was trying to remember how to represent family relationships in FHIR – to record that one person is related to another, maybe a mother / daughter relationship, assuming that each person is already represented by a Patient resource. I asked my good friend Brian Postlethwaite who kindly didn’t say “I’ve told you this before”, but rather pointed me at the RelatedPerson resource and the example in the spec.

For example, to create a link from mother to child, what you do is to create the 2 Patient resources that represent the mother and the child, then create a RelatedPerson resource that directly references the child (the ‘to’ of the relationship) through the RelatedPerson.patient element, and then use the mothers Patient.link to refer to that RelatedPerson (the ‘from’). In effect both the mothers Patient and the RelatedPerson resources both have information about the mother (hopefully not contradictory) and it’s the RelatedPerson.patient &  RelatedPerson.relationship that provides the relationship to the child. The Patient.link then has a type of ‘seealso’ to the Related person.

One reason for having a separate ‘linking’ resource is to allow for the situation where there isn’t a Patient resource to act as the related person – for example the related person might be a friend or caregiver not in the system. It also allows for multiple relationships between Patients, but it is a wee bit complicated, so having already forgotten once, I decided to write it here for when I next forget…

Then, I thought, it would great to have a diagram of this relationship (I like pictures). There are a couple of ways I could do this – using GraphBuilder would be the simplest as I could just build it directly – but as I’m currently experimenting with FHIR Shorthand, I thought I’d give that a try.

The following are the overall steps I followed.

1. Install sushi. See the online instructions
2. Create a folder to hold the FSH files.
3. Add a package.json file in the folder. Sushi needs this – I just copied the one I had used before.
4. Create the FSH file/s that define the instances and the relationships between them. I’m using Visual Studio Code, but any text editor would do.
5. Run sushi in the folder to generate the instances.
6. Make a bundle of the resource instances
7. Copy the bundle into the Bundle Visualizer

There are a few steps there, but they do illustrate some tools and techniques that could be useful elsewhere, so worth the effort I feel.

Here’s the FSH file I created:

//------- first create the Patient resources
//The patient instance for the mother
Instance:   mum
InstanceOf: Patient
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Mother</div>"
* text.status = #additional
* name.text = "Mary Mother"
//create links to the Related person children
* link.other = Reference(sonRelation)
* link.type = #seealso
* link[1].other = Reference(daughterRelation)
* link[1].type = #seealso

//The Patient data for the son
Instance:   son
InstanceOf: Patient
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Son</div>"
* text.status = #additional
* name.text = "Samual Son"
* link.other = Reference(sisterRelation)
* link.type = #seealso

//The patient data for the daughter
Instance:   daughter
InstanceOf: Patient
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Daughter</div>"
* text.status = #additional
* name.text = "Daughter"
* link.other = Reference(brotherRelation)
* link.type = #seealso


//--------- now the relationships


//The mother to son link
Instance:   sonRelation
InstanceOf: RelatedPerson
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Relationship between Mother and Son</div>"
* text.status = #additional
* patient = Reference(son)
* relationship.coding.code = #SON

//The mother to daughter
Instance:   daughterRelation
InstanceOf: RelatedPerson
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Relationship between Mother and Daughter</div>"
* text.status = #additional
* patient = Reference(daughter)
* relationship.coding.code = #DAU

//brother to sister
Instance:   sisterRelation
InstanceOf: RelatedPerson
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Sibling Relationship from brother to sister </div>"
* text.status = #additional
* patient = Reference(daughter) //This references the daughter (as a sister)
* relationship.coding.code = #NSIS

//sister to brother
Instance:   brotherRelation
InstanceOf: RelatedPerson
* text.div = "<div xmlns='http://www.w3.org/1999/xhtml'>Sibling Relationship from sister to brother </div>"
* text.status = #additional
* patient = Reference(son) //This references the son (as a brother)
* relationship.coding.code = #BRO

Note that it’s quite possible to create multiple FSH definitions like this in a single file – which is handy when creating a number of small resource instances (or profiles for that matter). I decided to model a mother with 2 children (son and daughter) so I needed 3 Patient resources, plus 4 RelatedPerson instances for the linkages. I also added sibling relations between brother and sister (mostly because it made the resource graph look a bit nicer).

Running Sushi creates the resource instances, but we need something more to visualize the relationships. The simplest way is to create a Bundle of the resource instances, then paste that bundle into the Bundle Visualizer which has a number of displays to ‘look into’ the bundle and its contents.

To create the bundle, I wrote a short nodejs script (you need to install node to run sushi in the first place so it’s already there). It’s quite simple – it just creates a minimal Bundle, then iterates through all the output folder contents, and adds them to the bundle. (Remember that Sushi places the resources it creates into a separate folder that will be the input into the Implementation Guide generation. We aren’t using that for this project, but it is handy to have all the resources in a common folder).

Here’s the script:

#!/usr/bin/env node
// make a bundle containing all of the resources in the folder

const fs = require('fs');

let bundleOutputFileName = "./bundle.json"
let bundle = {resourceType:'Bundle',type:'collection',entry:[]}
let folderPath = "./build/input/resources/";
let folder = fs.readdirSync(folderPath);

folder.forEach(file => {
    let fullPath = folderPath + file;
    let resource = fs.readFileSync(fullPath);
    if (resource) {
        let json = JSON.parse(resource)
        if (json.resourceType) {
            let entry = {}
            entry.resource = json
            bundle.entry.push(entry)
        }
    }
})

fs.writeFileSync(bundleOutputFileName,JSON.stringify(bundle,null,2))
console.log('Bundle created')

So the end result is a Bundle with all the resources in it. To view in the BundleVisualizer  just copy the bundle contents, then use the ‘Import Bundle’ link in the visualizer (upper left) to display a text area into which you can paste the bundle json. Don’t bother with an identifier – just click the Import button that appears after pasting in the json, and the Visualizer will do the rest. Handily, it will also validate the bundle and contents – the Validation server is displayed – and can be changed – in the NavBar of the visualizer at the top of the screen.

Here’s what the bundle looked like in the visualizer:

Just out of interest, I also used GraphBuilder to do the same exercise. In some ways GraphBuilder is easier as it’s easier to create the resource references visually – which is a bit tricky in this example. But, on the other hand, the bundle visualizer has better display functions. (I also hit a bug that I *think* I fixed)

And a reminder that this is not the same as relating people for the purposes of recording family history – use  FamilyMemberHistory for that. And the genomics folk also have specialized resources for what they need.

But for a simple recording of a family tree, relatedPerson works just fine.