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

Welcome to our three-part blog highlighting features you may not know about! We’re taking a dive beneath the surface and exploring how they’re used by different organizations – and by FHIR consultants like me.

This first post starts with general information, plus some useful features around FHIR projects and resources on

Simplify what exactly?

If you’re new to, it’s an online collaboration platform that lets you document your FHIR specifications and share them as stable, versioned FHIR packages with your colleagues and/or the FHIR implementation community. and Forge – the perfect match.

There are many ways to create the definitions you need for your FHIR project, but Forge is probably the easiest. It’s the de-facto standard for FHIR ‘profiling’ and the only available feature-complete graphical user interface. 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 Create FHIR profiles with Forge: publish and collaborate with It’s that simple!

Defining projects and resources organizes content into projects: coherent sets of resources that share a use case, goal, or purpose. In this context, the term ‘resource’ can mean any kind of FHIR resource, including StructureDefinitions, implementation guides, profiles, the 150 or so individual units of data included in the FHIR specification, and examples or instances uploaded to the platform. Projects can contain resources from multiple FHIR versions, but sticking to just one will help avoid confusion for your implementers.

Other noteworthy supported FHIR-related resources are logical models, package manifests, and mapping files. We try to keep as a specialized FHIR repository, but you can upload selected non-FHIR files for creating implementation guides, such as markdown text files, images, and CSS files.

Now let’s look at some features that help you manage your projects and resources efficiently.


There are many ways to upload and interact with resources on The user interface supports uploading resources (individually or zipped) from your computer, from a server (fetch from URL), or by copying and pasting. Paid features include a GitHub integration that allows automatic updates for your project.

It’s easy to overlook the platform’s FHIR and ZIP APIs, but every project is actually a tiny FHIR server in its own right, and can search for resources or perform CRUD interactions with a client that’s 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 on its page, like this:

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

The docs include a description of supported search parameters which follow the standard FHIR rules, like this search on the canonical identifier of a StructureDefinition:

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

Here’s a similar 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. The FHIR and ZIP APIs can integrate standards development processes with – for example to automate synchronization with as part of a build/publication process or periodically retrieve content as part of a back-up process. We use the ZIP API ourselves: Forge uses the ZIP API to directly save resources into a project.

Syncing with Forge

You can experience the perfect match between and Forge for yourself by connecting your local profiling folder to a project on The entire folder can be synced in a couple of seconds with just two clicks. If you run into conflicts, Forge provides a conflict resolution interface. The screenshot below shows a summary before a synchronization. The syncing feature uses the ZIP API endpoint.

Forge summary before synchronisation
Location of FHIR and ZIP API endpoint information in Simplifier.

To find out more about the sync options, take a look at our technical documentation on the topic.

Automate your FHIR work with Firely Terminal

Automation by robot at the piano

While we’re talking about automation and integration into building pipelines, we should also mention Firely Terminal (formerly Torinox), 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, and lots of features for managing resources, such as splitting bundles into individual resources or vice versa; transforming between XML and JSON; zipping and unzipping; and generating snapshots. Firely Terminal also incorporates a wide range of FHIR npm package management – more on this in my next blog post – and the .NET validation logic for profiled resource validation.

Besides being incredibly helpful for standards developing or testing, the real power of Firely Terminal lies in its automated build and/or publication processes. It can be incorporated into any architecture and used to periodically validate resources and to create and publish packages: combining its different features makes the potential use cases almost endless. Firely Terminal is the only product of its kind in the market and the number of STU3 version downloads stands at more than ten thousand.


StructureDefinitions are commonly backed up by a functional or logical model. But did you know you can add mappings to any information model inside StructureDefinitions? Once you’ve declared the relevant mapping information (e.g. name, id, and URI) in the StructureDefinition.mapping, you can add mappings for every element in the ElementDefinition.mapping, as shown here:


An external mapping can be better for governance reasons, because you get a new version of the profile every time you update it. But keeping the mappings in the profiles also has its benefits: these structured mappings can be used in an automated way to get to exactly the right element: for example, to retrieve a profiled element’s properties in order to dynamically build a user interface.

Mapping overview of a resource
Mapping overview of a resource.

Conversely, inline mappings guide implementers to the mapped concept for more information. adds value here by providing a tab on the profile page, as shown in this Patient resource created by the Dutch competence centre, Nictiz. Including a value in the `mapping.comment`helps create an easy to understand overview in one place, and also links to the StructureDefinition.mapping.uri, so it’s easy to get to the underlying mapped definitions.

History and diff viewer keeps track of every uploaded version of the resources. You can find them under the history tab on a resource page and compare them in a stand-alone diff viewer using your favourite FHIR format (XML/JSON).

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

Download a project as a FHIR server

One of my favourite hidden gems is the option to download any public STU3 or R4 project as a FHIR server. A fully-featured FHIR server – with all the project’s conformance resources and example instances – can be locked and loaded within minutes. This is the perfect way for authors to test the specifications in a RESTful environment, for example by trying out custom-defined search parameters. For FHIR implementers, it provides a local test server containing instances that conform to the required specifications.

How to download a complete project as a FHIR server.

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

Subscribe to FHIR resources and issues

As an author of FHIR resources, you’ll want to access other projects for inspiration, or because you directly depend on them. As an implementer of FHIR specs, besides possible changes to the resources, you may also want to follow updates in projects that have issue tracking enabled (available in the Team and Enterprise plans). The screenshot below shows how to set up email notifications for resource or issue updates. Small fun fact: the number of subscribers drives the ‘popular projects’ list on the homepage.

Subscribe location
Subscribing to a project.

To recap

This post has looked at some really useful features and tools for managing projects and resources on Part Two focuses on the validation of FHIR resources, and the third and last article reveals what you need to know about publishing FHIR resources. 

Reach out to us on if you have any questions or feedback, or if you’ve found a hidden gem we’ve overlooked!

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. Required fields are marked *