What You Need to Know About Publishing FHIR Resources
Subscribe to our newsletter
SubscribePart 3 of Hidden Gems on Simplifier.net That Make Your FHIR Work Easier
Welcome to the third and final part of our series on Simplifier.net‘s hidden gems and features! In our last articles, we covered features to help you manage FHIR projects and resources and showed you how to validate resources. This time around we will discuss how you can put a ribbon around your work. Let’s dive into publishing FHIR resources on Simplifier.net.
- Part 1 – Project and resources features
- Part 2 – Validation of FHIR Resources
- Part 3 – Publishing resources
What the package?!
It is safe to say that FHIR conformance resources are published in FHIR packages. Even the FHIR specification itself does this (e.g., package hl7.fhir.core 4.0.1). Already back in 2017, our CTO Ewout Kramer realized that we needed packages to publish stable, versioned sets of FHIR resources. In 2018, we built the first version of the FHIR Package server in Simplifier.net. As we were at the forefront of the package revolution, Simplifier.net is now the perfect place to create, document, and publish your FHIR packages.
Also, the entire FHIR tooling ecosystem widely adopted the methodology of packages. For instance, the HL7 Publisher creates packages by default and the HL7 Validator can handle a package as the validation context. Aegis’s conformance testing platform Touchstone allows the import of packages to its’s validation engine. Most FHIR references servers can import and utilize packages by default. And let us not to forget that Forge and Firely Terminal also work great with packages. Forge makes building on top of profiles in a package easy, while Firely Terminal is useful in all aspects around packages, particularly in the automatization of your work.
Checklist pre-publishing
Packages are more than a hidden gem. In a sense, they are like diamonds, because they stay forever. Once a package is created, it cannot be deleted. Only unlisted and hidden from view. You might ask yourself why that is. Packages can depend on other packages. If a package is deleted, this means its dependencies will break. Thereby potentially causing serious challenges for anyone relying on it.
Having mentioned this, you might want to pay special attention to the quality of your work before putting a ribbon around it. The next table shows potential checks prior to the creation of the package. The paragraphs thereafter will provide more detail on the checks and give tips and tricks.
| ID | Name | Content |
| #1 | Project metadata | Is the project metadata filled in and up-to-date? |
| #2 | Resource Metadata | Do all resources have a meaningful title and description? |
| #3 | Completeness | Are all recourses included in the project? No duplicates? Do all profiles have an example? |
| #4 | Status and Version | Do all resources have the correct status and version? |
| #5 | Dependencies | Are the project’s dependencies up-to-date? |
| #6 | Quality Control | Are all resources valid and conform to the projects profiling guidelines? |
#1 Project metadata
It pays off to put effort into providing accurate metadata for your project and its resources. Simplifier.net is also used for demo projects, sandboxes, and further ‘real’ looking projects which are used for testing. So, if you want to get your resources out in the world for people to use and built on, they need to find them and be confident that they are looking at the right version of the resources. Proper metadata gives a project more authority, better search results on Simplifier.net, and in external search engines, and happier end-users.
After creating a project, you will notice that some information is already filled in. This includes the project’s name, a short description or subtitle, FHIR version, its scope (e.g. International, National or test), and in some cases the appropriate nationality. These values can also be adjusted after the creation of the project. Assigned by Simplifier, the project’s URL key is one thing to look at. If this does not look as desired, you can adjust it in the Management section of the project.
Next, a more extensive project description can be added and it will appear on the project ‘homepage’. This markdown editor supports links and images (and even resource rendering, although you will likely not need that feature here). Provide information about the author/organization of the projects, more details about what the project contains and how to reach out for questions or bug reports.
On the project level, canonical base URLs can be claimed to increase the project’s authority. The canonical URLs of resources in the project should match this canonical base to be valid. Of course, claiming a canonical URL can only be done if that’s within your right to do so. For example, do not claim http://hl7.org/fhir/ because it’s owned by HL7.
#2 Resource metadata.
Once a project has well-established metadata, it’s time to have a closer look at the metadata display of FHIR resources. Various fields can be tweaked such as the title and description, but also more technical fields such as the URL key, file path, and custom workflow status. As these are frozen in the user interface of a resource in a package, we will dive into the first two. You can adjust these values for every resource in your project manually, but likely you have better things to do than editing every resource by hand. 😉 Hence, a reason to invest a bit of time in setting up metadata expressions to your liking. Simplifier does its best to use meaningful information from the resource using predefined expressions. These are shown in the default tab of the metadata expressions screen, accessible from the project page Manage drop-down. For example, for resources of type StructureDefinition, the following expressions are given:
StructureDefinition.Title: title | name
StructureDefinition.Description: descriptionThe expressions are written in FHIRPath, with some additional glue to make things easier. For instance, the “|” in the default expression works like an OR operator: firstly, the value of StructureDefinition.title is used, but if empty Simplifier takes the StructureDefinition.name and displays that as a resource title instead. The default settings probably work out well but you might benefit from customizing the expressions to the projects data model.
#3 Completeness
As stated in the first blog post of this series, Simplifier has many ways of uploading resources. We recommend agreeing on the used upload strategy and convention of file names and resource IDs with your collaborators. During upload, these are used to match resources. These agreements and some digital hygiene prevent errors and cleaning up. Using a GitHub.com webhook, as part of the paid plans, also helps a lot in this matter. However, even the best teams with the best setups will encounter technical or human mistakes that result in missing resources or duplicates. Check the numbers in Simplifier or download the entire project to see if it matches the expected number. The file manager, under the project settings, may be helpful to see the total number and filter for files.
Last but not least: developers like examples – do all of the profiles contain an example instance?
#4 Resource status and versions
All conformance resources have a mandatory status field. This indicates whether the resource is in draft, is active, retired or the status is unknown. The profiling editor Forge sets this field by default to draft. In short, this is an important indicator for consumers to know if the resource is appropriate for use or not. Moreover, it is possible to only include active resources during the creation of a package. Therefore, ensure that all resources have the correct status.
Besides a canonical URL, conformance resources have an optional business version. It is worth thinking about how to populate this field. Perhaps over-simplified, there are three options: leave it, script it or manually update it.
- For the first option, the reasoning could be that the FHIR package versioning provides the version and it saves work. However, information about changes in individual resources can then not be seen from their numbering.
- Using the next package version prior to release, the version can be updated in an automated manner. This entails a bit more work and the individual resources still do not completely reflect the changes. However, it reflects that the resources are a set and are compatible with each other. It prevents others from cherry-picking resources and expecting them to be compatible.
- The last option is to manually update the version fields with every change linked to that resource. This is a lot of work and prone to error but it will show the individual resource changes.
If you decide to go for option 2 or 3, you have to check if the versions are correctly filled before publishing.
#5 Dependencies
The project’s dependencies have to be correctly set so make sure that is the case. The project should have a direct or indirect dependency to a FHIR core package. Add or update dependencies through the project’s Dependencies tab. There is a Restore option under the Manage button that applies the dependencies from the package.json file, if you ever updated that file manually.
#6 Quality Control
Last but definitely not least is quality control. The resources themselves should be top-notch and not contain errors. Having thorough quality control saves you additional releases (= work). This should not be done only prior to package creation but rather something throughout the whole development cycle of resources. The previous blog post about validation resources may be helpful in this case!
Since that post, the Simplifier team worked hard on building project-level quality control on top of that. It is now possible to use predefined quality rules or configure your own and run them over the entire project. This includes using the validator for all resources with one click! 🙌
Package creation
We have now arrived to the main part: creating packages made simple with Simplifier. Head to the Packages tab of your project and start the process to create a new package.
Your first package
A first release needs a bit more work as it requires some metadata. For starters, add a name to the package which has specific requirements (e.g., it has two or more namespaces divided with dots) and a convention (e.g., the first namespace should identify the package author). The FHIR NPM package spec provides the details. Next, is the package version which follows SemVer 2. The package description is prefilled with the project’s description, so if you have performed the checklist you should be covered here already.
It is advisable to first create an alpha or beta package before publishing the real deal. This way you can test the publication yourself or a selected group of people to see if all is good. Such a package is easily made by adding “-alpha“, “-beta” or any other dash + label after the version number. This automatically renders the package as pre-release. Pro tip: unlist pre-release and inactive packages upon publishing the production-ready package to guide consumers to the right packages.
Package content
The package creation interface on Simplifier has a tab to configure the content of the package. The default settings are likely good, but it is worth taking a closer look to see if it can be better configured for the project. The default setting is to convert all resources to JSON format as this is expected by the FHIR NPM spec. Also, the package folder structure is default conform to these specs but you can deviate if that is necessary.
A more interesting option would be to include or exclude resources with a draft or retired status. As part of a production-ready package, I suggest checking this option in order to include active resources only. This will prevent confusing your consumers and their tools with an old or experimental profile.
Now let’s have a look at snapshots.
To snapshot or not to snapshot
The main part of a StructureDefinition can consist of two parts: a snapshot and a differential component. A snapshot contains the complete definition of the resource. The complete base definition plus all the added changes of the StructureDefinition layered on top of it. The differential component only contains the changes made in that StructureDefintion itself. A snapshot generally has thousands of lines of syntax while the differential may only contain a hundred lines. Therefore, solely working with the differential is a lot more pleasant. In addition, tooling can create snapshots where and when they are needed. They will likely do that anyway as there are still subtle variations in snapshot generation between tools.
Should you add snapshots in the resources inside the package? Simplifier currently adds the resources as they are uploaded in the package. If you always want them to be included, for example when you are working with tools that can’t generate them, you can choose a process that always adds them or that includes them prior to package creation. Simplifier, however, also provides the option to download a version of the package including all snapshots from any package page. It will then generate and add them upon download.
In most cases, just work with differentials and let the tooling do the work for you!
Release notes
Although it’s not strictly part of the FHIR package itself, Simplifier allows you to add release notes to package versions using a Markdown editor. Let the package consumer know what has changed and they will thank you, knowing upfront where their code might break. Building neat release notes in hindsight equals quite some work. So, try to get a good process going and see what’s possible to generate. For starters, a template for the notes may be helpful or check out the export options if issues are tracked on a separate platform.
Published a package, what’s next?
First of all, be proud of your results so far! Your package will automatically be registered and findable on Simplifier and the official FHIR registry.
Perhaps it is now time to let the world know a new package is ready to be picked up. Maybe the package needs to be loading to your FHIR (test) servers. Or maybe you want to publish your Implementation Guide describing the new release, which could be a topic of a later blog post!
Recap
This post was all about publishing FHIR resources with Simplifier.net. We offered a checklist and went through the package creation process. Hopefully, this provides some helpful tips and tricks! Reach out to us at simplifier@fire.ly if you have any questions or feedback. We’d love to hear from you.
Happy profiling!
