Manage FHIR Projects and Resources
14 Min Read

A Definitive Guide to Managing FHIR Projects and Resources

Ardon Toonstra
Ardon Toonstra

Subscribe to our newsletter


Part 1 of Hidden Gems on That Make Your FHIR Work Easier

manage FHIR projects and resources
Photo by Jason D on Unsplash

Welcome to this three-part blog series about features you may not yet know about! We will dive into features that are just beneath the surface and explore how different organizations and myself as a FHIR consultant use them.

This first post starts with general information followed by useful features around FHIR projects and resources on

Simplifier? Simplify what?

Perhaps you are new to What does it simplify or what does it do? In one sentence: it is an online collaboration platform for FHIR projects, allowing you to document your FHIR specifications and share them as stable, versioned FHIR packages with your colleagues or the FHIR implementation community.

And Forge? and Forge are the perfect matches. Create FHIR profiles with Forge, collaborate on, and publish projects with There are numerous ways to create the definitions required by your FHIR project. But, Forge is probably the easiest way to do it. It is the only feature-complete graphical user interface and the de-facto standard for FHIR “profiling”. It allows you to create FHIR profiles, extensions, logical models, search parameters, and operation definitions in an easy-to-understand desktop user interface, providing real-time validation feedback. And when you’re ready, you can share them on

Defining projects and resources

To avoid confusion, let’s agree on the definition of projects and resources. organizes content like implementation guides and resources (more on this shortly) into projects. A project is defined as a coherent set of resources. They share a common use case, goal, or purpose. Although a project can contain resources of multiple FHIR versions, it is best to stick to one. This will also avoid confusion with your consumers.

We call everything that goes inside projects resources. This applies to any kind of FHIR resource, like StructureDefinitions, also known as profiles, or instances/examples of FHIR resources, like an Observation resource. Other noteworthy supported FHIR related resources are implementation guides, logical models, package manifests, and mapping files for the FHIR mapping language. Although we try to keep a specialized FHIR repository, it is possible to upload some non-FHIR files to a project for creating implementation guides, such as markdown text files, images, and CSS files.

Now that we’re on the same page, we can dive into features that help you efficiently manage your projects and resources.


There are numerous ways to upload and interact with resources on The user interface supports uploading resources (individually or combined in a zip) from your computer, from a server (fetch from URL), or by copy-and-pasting. Among the paid features, there is a GitHub integration allowing the automatic update of your project.

Sometimes people overlook the FHIR and ZIP APIs of Every project is, in fact, a tiny FHIR server on its own that can search for resources or perform CRUD interactions with a client, authenticated with your account. System-wide searches and history searches are also supported. To retrieve the endpoint of a project or resource, click on API in the top-right menu when visiting either a project or resource page.

Location of FHIR and ZIP API endpoint information in Simplifier.
Location of FHIR and ZIP API endpoint information in Simplifier.

In the doc, you will find the description of supported search parameters which follows the standard FHIR rules. An example of this could be a search on a canonical identifier of a StructureDefinition. If so, see below how to do it:

GET<project-key>/StructureDefinition?url=<canonical of resource>

It works similarly for a system-wide search on Simplifier:

GET<canonical of resource>

The project ZIP API is useful for synchronizing a whole project. A GET or PUT can be used on<project-key>/zip to retrieve or update your project in a zipped form. Find out more about example requests in the docs. These APIs can integrate standards development processes with, to automate, for example, the synchronization with as part of a build/publication process. Another use case from our customers is to periodically retrieve the project’s content as part of a back-up process. We use the API ourselves, too. Forge uses the API to directly save resources into a project.

Automate your FHIR work with Firely Terminal

Automation by robot at the piano

Since we mentioned automation and integration into building pipelines, we should talk about Firely Terminal (formerly Torinox) too. We view it as the cross-platform Swiss army knife and command-line tool for all kinds of FHIR needs. And the best part?  You can download and use it for free.

Firely Terminal contains a whole set of FHIR utilities. It provides client functionality for FHIR resources and FHIR package servers. It contains a lot of features for managing resources, such as splitting Bundles into individual resources or the other way around, transforming between XML and JSON, zipping and unzipping resources, and generating snapshots. Firely Terminal also incorporates a wide range of FHIR npm package management. More on this in the third blog post. Lastly, Firely Terminal includes the .NET validation logic for profiled resource validation.

Besides being incredibly helpful for standards developing or testing, the power of Firely Terminal lies within the automated build and/or publication processes as it can be incorporated into any architecture. You can use it to periodically validate resources and to create and publish packages. By combining the different features, the possible use cases of Firely Terminal are practically endless. To supports this, the number of STU3 version downloads is more than ten thousand! It is the only product of its kind in the market.


Commonly, a functional or logical model backs up StructureDefinitions. Did you know you can add mappings to any information model inside StructureDefinitions? After the declaration of the relevant mapping information (e.g. name, id, and URI) in the StructureDefinition.mapping, mappings can be given for every element in the ElementDefinition.mapping as shown below.


Sometimes an external mapping is better because of governance reasons as any update to the mapping will result in a new version of the profile. However, keeping the mappings in the profiles has its benefits. Due to structured mappings, consumers of the StructureDefinition can use the mappings in an automated way, to get to exactly the right element. A use case could be to retrieve a profiled element’s datatype, name, or description based on the functional or logical model concept ID to build a user interface.

Mapping overview of a resource
Mapping overview of a resource.

If you want to do it the other way around, inline mappings will guide consumers to the mapped concept for more information. This is where adds value: mappings are nicely shown in a table at the mapping tab of a resource page. If you use the mapping.comment to capture the concept name or description of the external mapping, you will have a nice mapping table here. As shown in the screenshot and profiles of Nictiz. The StructureDefinition.mapping.uri is given as a link by This makes it easy to get to the underlying mapped definitions!

History and diff viewer keeps track of every uploaded version of the resources. On a resource page, these are shown in the history tab. Every version can be compared in a stand-alone diff viewer. A bonus is the possibility to select your favorite FHIR format (XML/JSON) for the diff viewer.

History and diff viewer feature location
History and diff viewer feature location.

Download a project as a FHIR server

One of my favorite gems is the option to download any public STU3 project as a FHIR server. Within minutes a fully-featured FHIR server can be locked and loaded with all conformance resources (profiles, search parameters, value sets etc.) and example instances that exist in the project.

This is helpful for both authors and consumers.  As an author, it is a perfect way to test the specifications in a RESTful environment. For instance, you can try out customer search parameters. As a consumer, it is helpful because this provides a local test server that contains instances that conform to the required specifications.

How to download a complete project as a FHIR server.

We tried to make this feature as simple as possible. For this purpose, uses a Docker image that runs a FHIR server (Firely Server) with all the settings preset for a smooth start. You can find this gem by clicking “<project name> FHIR server” under downloads on any STU3 project page. If you have already installed Docker, simply open the zip file and execute the script in a command-line interface.

Currently, this feature is only present for STU3 projects.  Let us know if you think this is helpful for your R4 projects as well! Reach out through the feedback button on or send an email directly to

Subscribe to FHIR resources and issues

As an author of FHIR resources, it is highly likely that you would want to access other projects to use as inspiration or because you directly depend on them. As a consumer, besides possible changes to the resources, you could be interested in updates to issues made in projects that have issue tracking enabled (available in the Team and Enterprise plans).  Subscribing to a project of interest comes in handy as this will trigger an email notification whenever something is updated. currently supports notifications for resource and issue changes from a project and resource/issue level. The screenshot shows the bell icon you can click on to be notified. Small fun fact: the number of subscribers is used to dynamically create the list of popular projects on the homepage.

Subscribe location
Subscribing to a project.


We have covered several features and tools that are available in the free plan around projects and resources on The second part of this series will focus on the validation of FHIR resources. The third and last article will reveal what you will need to know about publishing FHIR resources. has got you covered there! Follow me along with these posts to get the most out of and boost your FHIR project.

Reach out to us on if you’ve found a hidden gem that we have not covered here! If you have any questions or feedback, we’d also love to hear from you.

Want to stay on top of Interoperability and Health IT? 

Subscribe to our newsletter for the latest news on FHIR. 

Post a comment

Your email address will not be published.