R4 Support in Vonk


Vonk 3.0 provides support for both FHIR STU3 and R4 in one server.

One endpoint, two FHIR versions

FHIR grew from DSTU1 to R4, with DSTU2 and STU3 as intermediate releases. R5 is already on the horizon and it won’t end there. With the release of R4, we decided to make Vonk FHIR version independent, starting with STU3 and R4. Vonk version 3.0 – currently in beta –supports both versions on a single endpoint. This means you only need a single instance and endpoint. Upgrading from STU3 and R4 can be done gradually.


Besides building multiple FHIR versions in one server, we could have chosen to build a specific server for each FHIR version. But we did not and this is why:

  • Ease of deployment: Deploy once, run any version you need.
  • Solid maintenance: Since we also have just one codebase, bugs solved in one version are automatically solved for all versions.
    And that also applies to the plugins or facades that you have built on top of Vonk!
  • Metadata driven: Vonk is driven by the metadata in the Administration database. This allows us to support Custom Resources. So we wanted to stay consistent and support a new FHIR version with metadata as well.
  • Upgrade gradually: Because clients can use both versions on the same server, you get more options to upgrade multiple different clients until they are all on the same version again.


Up until now Vonk only provided support for STU3. In order not to break existing interfaces this will be the default FHIR version if none is specified. But from now on you can – and should – specify per request in which FHIR version you would like to communicate. To do this, you can use the fhirVersion parameter as defined in the FHIR specification. Examples:

GET <base>/Patient?name=duck
Accept = application/fhir+json; fhirVersion=3.0

POST <base>/Patient
Content-Type = application/fhir+xml; fhirVersion=4.0
Accept = application/fhir+xml; fhirVersion=4.0

You can find more examples on the special documentation page on working with multiple FHIR versions in Vonk.

In essence, the data for both FHIR versions lives side-by-side, pretty much ignorant of each other. The exception to this is that the id of a resource must be unique for the resourcetype across FHIR versions. Vonk enforces this to avoid confusion about resources in different FHIR versions having the same id – possibly resulting in errors that are hard to trace.

So if you create a resource in R4, you can only read it in R4. If you try to read it in R3 you will receive a message that the resource is available but not in the requested format. A delete is special: since it need not return data, it can work without knowing in which FHIR version to format the response. So you can use it without fhirVersion and it will delete whatever resource is at the requested endpoint.

Currently, Vonk does not provide automatic conversion of resources from STU3 to R4 or vice versa. But the setup with supporting multiple FHIR versions in one server does leave room for this scenario. Mappings are always biased by their purpose, so we welcome your ideas on how or why you would like to see the mapping between versions done.

For more details, please check the release notes.

What about my plugins?

Integrating multiple FHIR versions required some breaking changes, as can be derived from the major version number increase, from 2.x to 3.x. But we have made upgrading your plugins easy. The major changes are:

  • Does my plugin support just STU3, R4, or both? You can define this in the plugin configuration.
  • IConformanceContributor is replaced by ICapabilityStatementContributor. The methods are mostly the same, but now you can express for which FHIR version you want to put your contribution in the CapabilityStatement.

To make life easier for you there is a skeleton plugin project on Github. See PR 15 for the changes that are caused by Vonk 3.0.0-beta1.

And my Facade?

Upgrading your Facade should also be easy. But it varies a little with your approach, since Facades can be implemented in two ways:

  1. As a plugin to a Vonk Server, registering implementations for ISearchRepository and IResourceChangeRepository.
  2. As a Server on itself, building the whole pipeline as part of the implementation.

If you have chosen the first option, the changes are very limited: mainly namespace changes. Besides that you currently probably only have support for STU3, so you need to adjust the PipelineOptions to exclude R4 services.

If you have built the Facade as a full Server – as was needed before Vonk Plugins were invented – you need to apply more configuration changes.

For both scenarios, we will list the upgrade changes after we finished beta2, when the changes are expected to be stable.


We released this beta1 because we wanted to deliver you an R4 capable Vonk as soon as possible. This means that it may have some rough edges that we will iron out in beta2.

In the upcoming releases we will also upgrade some features that have not been upgraded to simultaneous FHIR version support yet, like Subscription, Re-indexing and import of your own conformance resources from a directory.

Post a comment

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

Want to stay on top of Interoperability and Health IT? 

Subscribe to our newsletter for the latest news on FHIR.