Blog - How to Create your First FHIR Profile image
13 Min Read

How to Create your First FHIR Profile

Ardon Toonstra
Ardon Toonstra

Subscribe to our newsletter


In this blog post, I will show you how to make your first, customized FHIR profile in less than one hour. The fastest way to do this is with Forge.

Forge is a feature-complete FHIR editor for data modelers, developers, and clinical informatics specialists. With this tool you can make your first HL7 FHIR profile under one hour. To demonstrate this I will create a national ‘Dutch Patient’ profile. This will involve some customization because even though our CTO, Ewout Kramer, is in the core team of FHIR none of the specific concepts from the Netherlands made it into the core FHIR specification. Without further ado, let’s dive into it.

Step 1 – Download and run Forge

First, go to and download Forge. You will have to create a free account on before you can download Forge, but don’t worry. This account may come in handy because it will enable you to view and share your work with the click of a button. Please note: Forge is completely free for learning or educational use. However, a paid license is required for commercial use and this can be purchased through one of’s pricing plans.

Once you are logged in to your account, you can download Forge for R4. Accept the terms for both Microsoft (for the .Net runtime if you do not already have that) and Firely (for Forge). I can assure you both companies really exist and will do no harm. After installing both components, Forge will automatically launch.

Launch Forge

Step 2 – Create and name your first FHIR profile

In Forge, choose Open Profiling Folder. Select (or create) a working directory. Mind the ‘Include subfolders‘ checkbox if you have relevant subfolders. Forge will now show you an empty project.

Create and name your own profile

Choose New. This screen shows all available FHIR-based resources and data types. Select the Patient resource and click OK.

Structure definition

In the Session Explorer on the left side, you will see MyPatient.

If you click on MyPatient in the menu on the left, you will open the Properties tab of MyPatient. Here you can:

1) Enter a URL for your StructureDefinition (profile),
2) Change the name of your StructureDefinition (profile), and
3) Provide a description for your StructureDefinition.


Step 3 – Use slicing to add your own unique identifier

Next to the Properties tab, you will find the Element Tree tab. This tab holds the element tree that contains all the elements of the base resource Patient. Forge offers multiple actions to modify a StructureDefinition. For example, you can change the information of the base elements, slice elements, or add extensions to elements.

Selecting an element in the tree will open the Element Properties on the right side of the screen. Some examples of element properties are the name, a short description, cardinality, and the data type.

A patient usually has one or more identifiers. To specify multiple identifiers, you can slice the element identifier. You can do this by selecting the element you want to slice and hit the Slice button. Afterwards, you can add slices by clicking the Add slice button. In this particular example, I added the Dutch Social Security Number, known as a burgerservicenummer (BSN). You can add more slices by selecting the element (identifier in this example) and clicking the Add slice button again.

Once you have created a slice, you can edit its properties in the Element Properties screen.

As you might have noticed, Forge provides an error message once you slice an element. A profile is not valid if it does not contain information on how to discriminate between the slices. Heed the error message and fill in the discriminator details as shown in the screenshot below.

This means that the slices are discriminated based on the value of the identifier system. Next, you need to add a fixed value, pattern, or binding to the system in the BSN slice. While we’re at it, let’s also make system and value mandatory.

An example Patient instance that conforms to our profile will look something like this:

    "resourceType": "Patient",
    "identifier":  [
            "system": "",
            "value": "999911120"

Step 4 – Use extensions to add a role to a patient contact

If the base resource does not contain all the elements you need, you can create an Extension for that. Click on New and then New Extension. In the pop-up screen you can either create the new extension right away with the default name “MyExtension” or provide some metadata. In this example, I want to add a “Role” to a Patient contact so I changed the name of the extension to “Role”.

New extension

Forge will give a warning that the extension is not valid without context information. You will need to provide information on where the extension is allowed to be used in the metadata of the extension. Simply go to the Properties tab, click the plus icon after Context, and then the little flowchart icon next to expression. This will open a helper screen to select the right context. Next, select the Patient resource and contact element. Finally, save the extension to your project folder.

Patient resource and contact element

To add the Role extension to the contact element in the PatientNL profile, I first select the contact element. Next, I click the Extend button.

Role extension

This action adds the “MyExtension” element to the contact element.


Selecting MyExtension will open the Element Properties window on the right side. In this window, you can provide specifications of the extension in the PatientNL profile. You can provide the (slice) name of the extension for instance.

Element properties

Step 5 – Use referencing to make the contact part of a specific organization

At times, you might want an element in a profile to reference another profile in order to specify that the referenced resource should conform to your custom definitions too. For instance, the contact of a patient can be part of an organization. If the profile Organization exists, you can refer to this profile by adding the canonical URL to the organization element in contact. To do this, first select the organization element.

organization element

Then, add the canonical URL to the reference data type in the Element Properties on the right side. Open the Reference type and click on the plus icon next to Target profiles because we are referring to a profile rather than specifying that this reference data type conforms to a profile, which can be done using a reference within Profile. Fill in the profile canonical URL and optionally remove the base HL7 URL. This ensures that the referenced resource needs to conform to your profile. Done!

Canonical URL

Step 6 – Saving your FHIR profile

If your profile has a yellow star in the Session Explorer that means the profile has unsaved changes. To save your newly created profile, you can select your profile in the Session Explorer and click the save icon. Ctrl + Shift + S allows you to save all profiles at the same time.

Save your profile

In the Save as dialog box, choose the name for the .xml file in which your profile will be stored. You will also need to save Role since its definition is a separate StructureDefinition resource. With any XML browser, you can see both the PatientNL.xml and Role.xml file as well as what Forge actually created.

As a default setting, your profile is saved as a differential. This means it only saves the changes you made in comparison with the base resource. If you want to save your complete profile as an XML or JSON file, go to Options and check “Save snapshot component”.

All set. You’ve just created your first FHIR profile!

Share your work with your team or the FHIR community at large.

Forge is integrated with Now that you have an account it is possible to directly render and share your work online via You can read all about how to publish your first FHIR profile in this blog post. In the meantime, happy profiling.

Recommendations for you

Explore more topics

Post a comment

Your email address will not be published. Required fields are marked *