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 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 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=''>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=''>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=''>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=''>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=''>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=''>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=''>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

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:

Bundle 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.

About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

6 Responses to Family FHIR – with sushi

  1. Pingback: Dew Drop – February 10, 2020 (#3130) | Morning Dew

  2. This is my first real introduction to FSH and I do enjoy how easy is it to write up multiple resources together! How does the tooling hold up while you’re doing it – I am guessing there is no autocompletion yet, but are the error messages you get while creating this helpful and descriptive?

    • David Hay says:

      Pretty well actually. The error messages are generally helpful and there is a degree of autocompletion if you use VS Code as the spec suggests – though quite primitive at this stage.

      Of course, I don’t get any errors these days 🙂

      There’s no way I’d do examples manually these days – FSH is a joy compared to JSON or XML, and they’re always improving it…

  3. MF says:

    Hi David,

    Thanks for posting this. I was trying to follow along with the FSH example. However, I keep getting the following error, wondering if you encountered the same or any idea how I can fix this? I am on sushi 0.9.0.

    error: InstanceOf Patient not found for mum
    File: /c/code/simpatico/relationships-example-sushi/example.fsh
    Line: 3 – 12


    • David Hay says:

      Hi Mohammad – looks like it can’t find the R4 Patient resource. Have you got the dependency in the package.json file? ie something like? (I didn’t make that clear in the post, so might be misleading)…

      "dependencies": {
      "hl7.fhir.r4.core": "4.0.1"

  4. MF says:

    Hi David,

    Thanks for getting back to me. Oh okay, right. I did not know about this. I will review the FSU page again to see what dependencies are available.

    Another question, in the example above, we have Parent to Child and Siblings listed there. Would it be correct to make a Child to Parent relationship as well? To show who the parent is for the kids?

    I have created that relationship by adding to son and daughter’s patient resource’s Link prop, with “RelatedPerson/mother”.

    Would this be correct? or am I just dupliating the Child => Parent relationship by doing this as the Parent -> child already exists?

    Sample resources I came up with:


Leave a Reply

%d bloggers like this: