Old Firely Server release notes (v3.x)

Release 3.9.3 hotfix


We changed the behavior of resthook notifications on Subscriptions. See Fix nr 1 below.


  1. SQL Server: The migration that adds the indexes described in Release 3.9.2 hotfix might run longer than the timeout period of 30 seconds. Therefore we added scripts to apply and revert this migration manually. If you encounter the timeout during upgrade: shut down vonk, run the script using SQL Server Management Studio or any similar tool, then start Vonk 3.9.3 again. In both scripts you only need to provide the database name for the database that you want to upgrade. If you run your administration database on SQL Server you can but probably do not need to run this script on it. The administration database is typically small enough to complete the script within 30 seconds.

    1. apply: <vonk-dir>/data/2021211113200_AddIndex_ForCountAndUpdateCurrent_Up.sql

    2. revert: <vonk-dir>/data/2021211113200_AddIndex_ForCountAndUpdateCurrent_Down.sql


  1. Subscriptions: A resthook notification was sent as a FHIR create operation, using POST. This was not compliant with the specification that states it must be an update, using PUT. We changed the default behavior to align with the specification. In order to avoid breaking changes in an existing deployments, you may set the new setting SubscriptionEvaluatorOptions:SendRestHookAsCreate to true - that way Vonk will retain the (incorrect) behavior from the previous versions.

Release 3.9.2 hotfix


All fixes are relevant to SQL Server only.

  1. The 3.9.0 fix that “Improved the handling of concurrent updates on the same resource.” decreased the performance of concurrent transaction handling. We implemented another solution that does not affect performance.

  2. Improved read performance by adding an index.

Release 3.9.1 hotfix


  1. Fixed a bug introduced with 3.9.0 were Vonk would throw the following exception on start-up System.InvalidOperationException: Unable to resolve service for type 'Vonk.Core.Conformance.IDefinitionProvider' while attempting to activate 'Vonk.Fhir.R3.SnapshotGeneration.SnapshotGeneratorR3

  2. Fixed a breaking change to public search API with the implementation of _total parameter. We had introduced a new parameter to the Next method in ResultPage, effectively breaking backwards compatibility. This has been fixed.

Release 3.9.0


  1. We have made Subscriptions more robust. See Subscriptions for details. In summary, if an evaluation of a Subscription fails, Vonk will retry the evaluation periodically for a number amount of tries. You can control the retry period and the maximum number of retries in the subscription settings:

    • RetryPeriod is expressed in milliseconds. Default 30000 (30 sec).

    • MaximumRetries is the maximum amount of times Vonk will retry to send the resources. Default 3 retries.

  2. We have implemented the _total parameter for options none and accurate. Omitting the _total parameter is equivalent to _total=accurate. If the total number of resources is not relevant, using _total=none in the request results in better performance when searching.

  3. It is no longer necessary for the :type parameter to always be provided to distinguish between multiple reference targets. The parameter does not need to be provided anymore when the search only applies to a single target. For example: GET <base>/AllergyIntolerance?patient=xyz The patient:Patient type parameter does not have to be supplied. The ‘patient’ search parameter on AllergyIntolerance has two possible targets. It may reference either a Patient or a Group resource. However, the fhirpath statement that goes with it, selects ‘AllergyIntolerance.patient’, and that reference element may only target a Patient resource.


  1. Indexing values for a string search parameter threw an exception when there was no value but only an extension. This has been corrected.

  2. We made the Provenance.target available as a revInclude Parameter in the CapabilityStatement. Previously, Vonk did not account for the case that a reference is allowed to ANY resource type, which incorrectly resulted in Provenance.target to not be shown in the CapabilityStatement.

All the following fixes are only relevant for SQL Server:

  1. Improved the handling of concurrent updates on the same resource.

  2. Upgraded the version of the SqlClient library to fix issues when running on Linux.

  3. Fixed missing language libraries for SQL Server when running on Docker.

Release 3.8.0


  • We added an important note to the 3.6.0 release notes for MongoDb users.

  • Because of the changes in searching for Quantities (feature 2 below), you will need to do a reindex in order to make use of this. You may limit the reindex to only the search parameters of type ‘quantity’ that you actually use (e.g. Observation.value-quantity).


  1. We upgraded the FHIR .NET API to 1.9, see the 1.9 releasenotes. This will trigger an automatic import of the Conformance Resources at startup.

  2. We upgraded the Fhir.Metrics library to 1.2. This allows for a more uniform search on Quantities (mainly under the hood)

  3. We upgraded the FHIR Mapping plugin to support the FHIR Mapper version 0.5.

  4. The built-in terminology services now support the includeDesignations parameter.

  5. The IVonkContext now lets you access the original HttpContext.

  6. The CapabilityStatement now lists the profiles that are known to Vonk (in its Administration database) under CapabilityStatement.rest.resource.supportedProfile (>= R4 only) and the base profile for a resource under CapabilityStatement.rest.resource.profile.

  7. We extended the security extension on the CapabilityStatement to include the endpoints for register, manage, introspect and revoke.

  8. IAdministrationSearchRepository and IAdministrationChangeRepository interfaces are now publicly available. Use with care.


  1. If the server configured as authorization endpoint in the Smart setting is not reachable, Vonk will log a proper error about that.

  2. An error message for when a query argument has no value is improved.

  3. When SMART-on-FHIR is enabled, and the received token contains a launch context, the _history operation is no longer available. Because Vonk does not retain the search parameter index for historical resources, it cannot guarantee that these resources fall within the launch context (at least not in a performant way). To avoid information leakage we decided to disable this case altogether.

  4. A Create interaction without an id in the resource, with SMART-on-FHIR enabled, resulted in an exception.

  5. You can now escape the question mark ‘?’ in a query argument by prepending it with a backslash ‘'.

  6. A Quantity search using ‘lt’ on MongoDb resulted in too many results.

Release 3.7.0



To accommodate for feature #2 below there is an automatic migration carried out for SQL Server and SQLite. This migration might take some time, so please test it first. For MongoDb, you will have to Rebuild the whole search index. If this is not feasible for your database, please Contact us for assistance.


  1. Patch: We implemented FHIR Patch. You can now update a resource having only partial data for it. See Create, read, update, patch, delete.

  2. Search on accents and combined characters: we improved searching with and on accents and combined characters. Note the database change above.

  3. API 1.7: We upgraded Vonk to use the FHIR .NET API 1.7, having its own releasenotes.

  4. Security: The Docker image is now based on the Alpine image for .NET Core. This has far less security issues than the Ubuntu image that we used before. The base image is aspnet:3.1-alpine:3.11 (newest version 3.12 has an open bug related to SQLite).

  5. Security: We revisited the list of security vulnerabilities, see Security notifications for Firely Server.

  6. Administration: ConceptMaps are now imported at startup.


  1. Searching on _lastUpdated could be inaccurate when time zone differences are in play. We fixed that.

  2. Search arguments for a quantity search weren’t allowed to be greater than 999.

Release 3.6.1


  1. ConceptMap resources can be stored at the Administration endpoint, both through import and through the RESTful API.


Previous versions of Vonk did not include the ConceptMap resources in the import so they will currently not be in your Administration database. If you run your Administration database on SQL Server or MongoDb and want to use the ConceptMap resources from the spec, be sure to rerun the import of the specification resources. You can force Vonk to do so by deleting the .vonk-import-history.json file from the ImportedDirectory (see the settings under AdministrationImportOptions). If you use SQLite, you can simply use the pre-built ./data/admin.db from the binaries.


  1. The FHIR Mapper plugin is upgraded to version 0.3.6.

  2. The FHIR Mapper plugin now fully works on the Administration endpoint.

Release 3.6.0



For MongoDb users: We implemented feature #1 below using the Aggregation Pipeline. This makes an existing issue in MongoDb - SERVER-7568 <https://jira.mongodb.org/browse/SERVER-7568> - a more urgent problem. MongoDb has solved this problem in version 4.4. Therefore we advise you to upgrade to MongoDb 4.4.


  1. Sort: The sorting that was implemented for the SQL/SQLite repositories in the previous version is now also implemented for MongoDb.

  2. Terminology: The local terminology service, built in to the Vonk Administration API, is upgraded to support R4 and R5 (and still R3 of course).

  3. Vonk can now index and search on search parameters that reference a nested resource, like Bundle.message.


    Note that any nested resources have to be indexed by Vonk. For new data that is done automatically. But if you want to use this on existing data, you have to reindex for the search parameters you want to use it on. Those will most notably be Bundle.message and Bundle.composition.

  4. If you accidentally provide a body in a GET or DELETE request, Vonk will now ignore that body instead of returning an error.


  1. CapabilityStatement (rev)includes now use ‘:’ as a separator instead of ‘.’.


  1. The BinaryWrapper plugin is upgraded to 0.3.1, where the included BinaryEncodeService is made more reusable for other plugins (most notably the FHIR mapper).

Release 3.5.0


  1. Search reference by identifier: FHIR R4 allows you to search a reference by its identifier. We added support for this in Vonk. Note that any identifiers in reference elements have to be indexed by Vonk. For new data that is done automatically. But if you want to use this on existing data, you have to reindex for the search parameters you want to use it on. E.g. Observation.patient.

  2. AuditEvent logging: In release 3.3.0 we already added support for logging audit information to a file. With this release we add to that logging that same information in AuditEvent resources. These resources are written to the Vonk Data database (not the Administration database). Users are not allowed to update or delete these resources. See Auditing for more background.

  3. Audit logging: We added [Request] or [Response] to the log lines so you can distinguish them better.

  4. Sort: We started implementing sorting. This release provides sorting for search parameters of the types string, number, uri, reference, datetime and token, on the repositories SQL, SQLite and Memory. On the roadmap is extending this support to MongoDb and to quantity search parameters.

  5. Terminology Integration: You can configure Vonk to route the terminology operations to external terminology servers. You can even configure a preferred server for certain code systems like LOINC or Snomed-CT. On the roadmap is to also allow you to use these servers for validation of codes and for token searches.

  6. We implemented $meta-delete, see Meta plugins.

  7. Loading plugins can lead to unexpected errors. We made the process and the log friendlier, so you can spot configuration errors more easily:

    • The log outputs the version of each of the plugins

    • If a duplicate .dll file is found, Vonk tells you which two dlls are causing this and then exits.

    • If you configured a plugin that you are not licensed to use, this is logged with a friendly hint to acquire a license that does allow you to use it.

  8. The log is now by default configured to use asynchronous logging so Vonk is not limited by the speed of the logging sinks (like the Console and the log file). Please update your logsettings.instance.json if you created your own log settings in that. See Log settings for more background.


  1. You could load invalid XML in the Resource.text through a JSON payload. When that resource was then retrieved in XML, it would fail with an InternalServerError. Vonk will now return an OperationOutcome telling you what the problem is. You can then correct it by using JSON.

  2. Composite search parameters were not parsed correctly. Now they are. So you don’t see warnings like Composite SearchParameter 'CodeSystem.context-type-quantity' doesn't have components. anymore.

  3. Indexing for the _profile search parameter was broken for R4 since Vonk 3.2.1. We fixed it. If you added new resources with Vonk 3.2.1 - 3.4.0, you need to reindex for the Resource._profile parameter.

  4. Audit log: %temp% in the path setting was evaluated as <current directory>\%temp%. Fixed that to evaluate to the systems temporary directory.

  5. The logsettings.json configured the Serilog RollingFile sink by default. That is deprecated, so we replaced it with the File sink.

  6. Rebuild the search index for specific searchparameters now returns an error if you forget to actually specify a search parameter.

  7. An InternalServerError was returned when you validate a resource that is syntactically incorrect. Like a Patient with multiple id’s. Vonk now returns an OperationOutcome with the actual problem.

  8. The configuration for the FHIR Mapper was simplified. You only need to include Vonk.Plugin.Mapping. Check appsettings.default.json for the new pipeline.

  9. Maybe you got accustomed to ignoring a list of warnings at startup of Vonk. We cleaned up the list so that if there is a warning, it is worthwhile investigating the cause of it.

  10. The appsettings and logsettings can contain relative file paths for several settings, like the License:LicenseFile. These were evaluated against the current working directory, but that could lead to problems if that was not the Vonk directory. We solved that: all relative paths are evaluated against the Vonk directory.

  11. The docker image for version 3.4.0 was tagged 3.4.0-. With 3.5.0 we removed the superfluous hyphen at the end.

  12. We updated the documentation on Using Firely Server on Docker on SQL Server to be clearer about the order of the steps to take.

Plugins & Facade

  1. FHIR Mapper

    • Has been upgraded to version 0.3.4.

Release 3.4.0


  1. Upgraded to FHIR .NET API 1.6.0, that features a couple of changes for working with CDA logical models. See the release notes of the API.

  2. Included the FHIR Mapper in the distribution. It is only enabled however when you include the mapping plugin in your license.


  1. When prevalidation is set to the level ‘Core’, Vonk no longer complains about extensions that are not known if they are not core extensions (i.e. having a url starting with ‘http://hl7.org/fhir/StructureDefinition/’).

Release 3.3.0


To use the new features for auditing and R5, you need a new license file including the tokens for those plugins. For evaluation editions you can sign up after which you will receive an email with the license file. If you need these updates in your production license, please contact us.


  1. Vonk was upgraded to FHIR .NET API 1.5.0. See the release notes of the API.

  2. Vonk can now log audit lines in a separate file. This can help you achieve HIPAA/GDPR compliancy. See Auditing for more info.

  3. Failed authorization attempts are now logged from the SMART on FHIR plugin.

  4. Support for _include:iterate and _revinclude:iterate, see Search.

  5. The BinaryWrapper plugin is now two-way. So you can POST binary content and have it stored as a Binary resource, and GET a Binary resource and have it returned in its original binary format.

  6. Experimental support for R5 is now included in the Vonk distribution. For enabling it, see Support for R5.


  1. Indexing of a quantity in resource could fail with a Status code 500 if it had no .value but only extensions.

  2. The use of a SearchParameter of type reference having no target failed. These search parameters are now signalled upon import.

  3. Since R4 it is valid to search for a quantity without specifying the unit. Vonk now accepts that.

  4. A transaction response bundle could contain an empty response.etag element, which is invalid.

  5. Preloading resources was not working since the upgrade to .NET Core 3.0. That has been fixed. It is still only available for STU3 though.

  6. Administration import would state that it moves a file to history when it had imported it. That is no longer true, so we removed this incorrect statement from the log.

  7. $validate-code could cause a NullReference exception in some case.

  8. The generated CapabilityStatement for R4 failed constraint cpb-14.

  9. Content negotiation favoured a mediatype with quality < 1 over a mediatype without quality. But the default value is 1, so the latter is now favoured.

  10. Validate an instance from the database did not account for the informationmodel (aka FHIR version) of the resource.

Plugins & Facade

  1. Document Operation

    • Has been upgraded to Vonk 3.2.0.

    • Was assigned a license token

    • Assigns an id and lastUpdated to the result bundle

  2. Conversion

    • Has been upgraded to Vonk 3.2.0.

    • Was assigned a license token.

  3. Vonk.Facade.Starter has been upgraded to Vonk 3.2.1 and as a consequence also to EntityFrameworkCore 3.1.0.

Release 3.2.1


  1. SMART plugin now understands multiple scopes per access token.

  2. SMART plugin now understands Resource.* claims, in addition to already understanding Resource.read and Resource.write.

Release 3.2.0


Vonk 3.2.0 is upgraded to .NET Core 3.1.0, ASP.NET Core 3.1.0 and EntityFramework Core 3.1.0.

  • For running the server: install the ASPNET.Core runtime 3.1.0.

  • For developing or upgrading Facades that use Vonk.Facade.Relational: upgrade to EF Core 3.1.0.

  • Plugins that target NetStandard 2.0 need not be upgraded.


  1. There are no changes to the databases. The upgrade of EntityFramework Core does not affect the structure of the SQL Server or SQLite databases, just the access to it.


  1. Supported interactions were not enforced for custom operations like e.g. $convert.

  2. If a resource failed Validating incoming resources, the OperationOutcome also contained issues on not supported arguments.

  3. A search with ?summary=count failed.

  4. Added support for FhirPath hasValue() method.

  5. Resolution of canonical http://hl7.org/fhir/v/0360|2.7 failed.

  6. CapabilityStatement.rest.resource.searchInclude used ‘.’ as separator, fixed to use ‘:’ in <resource>:<search parameter code>

  7. Changed default value of License:LicenseFile to vonk-license.json, aligned with the default naming if you download a license from Simplifier.

  8. Reindexing always interpreted a resource as STU3. Now it correctly honours the actual FHIR version of the resource.


  1. BinaryWrapper plugin can now be restricted to a list of mediatypes on which to act.

  2. Vonk used to sort on _lastUpdated by default, and add this as extra sort argument if it was not in the request yet. Now you can configure the element to sort on by default in BundleOptions:DefaultSort. Although Vonk FHIR Server does not yet support sorting on other elements, this is useful for Facade implementations that may support that (and possibly not support sort on _lastUpdated). See also Search size.

  3. Implemented $versions operation

  4. Extended the documentation on:

  5. The SMART authorization plugin can now be configured to not check the audience. Although not recommended, it can be useful in testing scenarios or a highly trusted environment.


    We changed the default value for the setting SmartAuthorizationOptions.Audience from vonk to empty, or ‘not set’. This is to avoid awkward syntax to override it with ‘not-set’. But if you rely on the value vonk, please override this setting in your appsettings[.instance].json or environment variables as described in Changing the settings.

Plugin and Facade API

  1. Vonk.Facade.Relational now supports the use of the .Include() function of EntityFramework Core. To do so, override RelationalQuery.GetEntitySet(DbContext dbContext).

  2. Vonk.Facade.Relational now supports sorting. Override RelationalQueryFactory.AddResultShape(SortShape sortShape) and return a RelationalSortShape using the extension method ``SortQuery().

Release 3.1.3 hotfix


  1. Fixed behavior on conditional updates in transactions. In odd circumstances Vonk could crash on this.

Release 3.1.0

Please also note the changes in 3.0.0 (especially the one regarding the SQL server database)


  1. Validation on multi-level profiled resources no longer fails with the message “Cannot walk into unknown StructureDefinition with canonical”

  2. Improved documentation on upgrading Vonk, the Vonk pipeline, CORS support, plugins and IIS deployment

  3. Using multiple parameters in _sort led to an error for all repositories

  4. Vonk UI capability statement view now works for self-mapped endpoints like /R3 or /R4

  5. A saved resource reference (e.g. Patient.generalPractitioner) on a self-mapped endpoint (e.g. /R4/...) would have its relative path duplicated (/R4/R4/...)


    If you have used self-mapped endpoints (appsettings: InformationModel.Mapping.Map in the ‘Path’ mapping mode) and you have saved resources containing references, it is possible that your database now contains some resources with broken references. Please contact us if this is the case


  1. The new experimental FHIR mapping engine, which is currently exclusively available on our public FHIR server http://vonk.fire.ly

  2. New licensing system, supporting the community edition

  3. Simplifier projects are now imported for FHIR R4 as well

  4. The following plugins have been bundled with the Vonk release (compare your appsettings with the new appsettings.default.json to activate them)

    1. The $document operation (see Documents)

    2. The $convert operation (see Conversion)

    3. The binary wrapper (see Binary)

Plugin and Facade API

  1. Vonk.Facade.Starter has been upgraded to work with Vonk 3.1.0

  2. IConformanceContributor and IConformanceBuilder have moved from Vonk.Core.Pluggability to Vonk.Fhir.R3.Metadata. It is also deprecated, as Vonk.Core.Metadata.ICapabilityStatementContributor is now preferred instead. See Capabilities for more information

  3. Implementations of ISearchRepository can now sort on multiple parameters (in BaseQuery.Shapes). Previously this would result in an error.

  4. Improved documentation on the Important classes and interfaces

  5. See Release 3.0.0 for some additional issues you may encounter upgrading your plugins

Release 3.0.0


Please also note the changes in 3.0.0-beta1

  1. SQL Server: SQL script ‘20190919000000_Cluster_Indexes_On_EntryId.sql’ (found in the /data folder of the Vonk distribution) must be applied to existing Vonk SQL databases (both to the admin and to the data repositories)


    Vonk 3.0.0 (using SQL server) will not start unless this script has been applied to the databases. Please note that running the script can take considerable time, especially for large databases.


  1. Information model (= FHIR version) settings

    1. Although Vonk now supports multiple information models (STU3 and R4) simultaneously, an unused model can be disabled (see Configuring the Firely Server Pipeline)

    2. You can set the default (or fallback) information model (previously: STU3), which is used when Vonk can not determine the information model from context (see Information model)

    3. You can map a path or a subdomain to a specific information model (see Information model), mitigating the need to specify it explicitly in a request

  2. Vonk now uses FHIR .NET API 1.4.0

  3. Several performance enhancements have been made for SQL server and IIS setups

  4. Added R4-style Conditional Update to both STU3 and R4


  1. Circular references within resources are now detected, cancelling validation for now. We will re-enable validation for these resources when the FHIR .NET API has been updated

  2. An $expand using incorrect data returned a 500 (instead of the correct 400)

  3. Vonk now returns a 406 (Not Acceptable) when the Accept header contains an unsupported format

  4. Deletes did not work for R4

  5. Search parameters

    1. Search parameters were read twice (at startup and upon the first request)

    2. Search parameter ‘CommunicationRequest.occurrence’ is not correctly specified in the specification. We provide a correct version.

  6. _history

    1. _history was not usable in a multi information model setup

    2. The resulting Bundle.entry in an STU3 _history response contained the unallowed response field

    3. Added Bundle.entry.response to the R4 _history entry

  7. Batches

    1. Valid entries in batches also containing invalid entries were not processed

    2. Duplicate fullUrls are no longer accepted in a batch request, which previously led to a processing error

    3. An R4 transaction resulted in STU3 entries

    4. Transactional errors did not include fullUrl

Plugin and Facade API

  1. Improved the message you get when the sorting/shaping operator is not implemented by your facade

  2. VonkOutcome (and VonkIssue) has been simplified

  3. VonkConstants has moved from Vonk.Core.Context to Vonk.Core.Common

  4. IResourceChangeRepository.Delete requires a new second parameter: string informationModel. Information model constants can be found in Vonk.Core.Common.VonkConstants.Model

  5. Exclude Vonk.Fhir.R3 or Vonk.Fhir.R4 from the PipelineOptions if you don’t support it in your Facade.

  6. Updated the minimal PipelineOptions for a Facade Plugin in the example appsettings.json:

    • updated Vonk.Core.Operations.SearchConfiguration to Vonk.Core.Operations.Search

    • removed Vonk.UI.Demo

    • removed Vonk.Core.Operations.Validate.SpecificationZipSourceConfiguration from the Exclude

    • updated Vonk.Core.Operations.Terminology to Vonk.Plugins.Terminology


Early Facade implementations were built with by using Vonk services and middleware in a self-built ASP.NET Core web server. This can be seen in the Vonk.Facade.Starter project in the repository with the same name. Due to changes in Vonk this does not work with Vonk 3.0.0. It will be fixed in 3.1.0. But after that such projects cannot be upgraded anymore and will have to be refactored to a proper plugin (as the ViSi.Repository project in the same repository). Please contact us in case of any questions.

Release 3.0.0-beta2


We updated the Security notifications for Firely Server.


Note the changes in 3.0.0-beta1, but there are no new changes in beta2.


  1. Subscriptions works for R4 also. Note that a Subscription will only be activated for resource changes in the same FHIR version as the Subscription itself.

  2. Load Conformance Resources from disk works for R4 also. Use a directory name that ends with .R4 for R4 conformance resources.

  3. Re-indexing for new or changed SearchParameters works for R4 also. Issue a reindex with a fhirVersion parameter in the Accept header, and it will be executed for the SearchParameters defined for that FHIR version.

  4. Allow for non-hl7 prefixed canonical urls for conformance resources (since sdf-7 is lifted). See Custom Resources.

  5. Custom Resources can be validated, both individually and as part of a bundle. See Custom Resources.

  6. If the Accept header lacks a fhirVersion parameter, it will fall back to the fhirVersion parameter of the Content-Type header and vice versa. If both are missing, Vonk will default to STU3.


  1. _include did not work for R4.

  2. _include gave a 500 response code if a resource contains absolute references.

  3. A resource with unknown elements could result in an uncaught Hl7.Fhir.ElementModel.StructuralTypeException.

  4. The homepage stated that Vonk was only for STU3. Fixed that.

  5. Bundle.timestamp element (new in R4) was not populated in bundles returned from Search and History operations.

  6. Some operations could return an OperationOutcome with an issue and a success message.

  7. Better error message if a resource without any meta.profile is not accepted by Validating incoming resources.

  8. Requesting an invalid FHIR version resulted in a ArgumentNullException.

Plugin and Facade API

  1. NuGet package Vonk.Fhir.R4 had a dependency on Vonk.Administration.API, but the latter is not published. We removed the dependency.

  2. IResourceExtensions.UpdateMetadata did not update the id of the resource.

  3. VonkOutcome.RemoveIssue() method has been removed.


  1. Plugin example (Vonk.Plugin.ExampleOperation):

    1. Added an example of middleware directly interacting with the HttpContext (instead of just the VonkContext), see the file VonkPluginMiddleware.cs

    2. CapabilityStatementBuilder was not called.

  2. DocumentOperation (Vonk.Plugin.DocumentOperation):

    1. Composition ID was not determined correctly when using POST.

Release 3.0.0-beta1

Vonk 3.0.0 is a major upgrade that incorporates handling FHIR R4. This runs in the same server core as FHIR STU3. See Multiple versions of FHIR for background info.


If you have overridden the PipelineOptions in your own settings, you should review the new additions to it in the appsettings.default.json. In particular we added Vonk.Fhir.R4 that is needed to support FHIR R4.


MacOS: you may need to clean your temp folder from previous specification.zip expansions. Find the location of the temp folder by running echo $TMPDIR.


  1. SQL Server, SQLite:

    1. vonk.entry got a new column ‘InformationModel’, set to ‘Fhir3.0’ for existing resources.

    2. vonk.ref got a new column ‘Version’.

    3. Database indexes have been updated accordingly.

    Vonk will automatically update both the Administration and the Data databases when you run Vonk 3.0.0.

  2. MongoDb / CosmosDb:

    1. The documents in the vonkentries collection got a new element im (for InformationModel), set to ‘Fhir3.0’ for existing resources.

    2. The documents in the vonkentries collection got a new element ref.ver (for Version).

    3. Database indexes have been updated accordingly.

  3. MongoDb / CosmosDb: Got a light mechanism of applying changes to the document structure. A single document is added to the collection for that, containing VonkVersion and LatestMigration.

  4. MongoDb: The default name for the main database was changed from ‘vonkstu3’ to ‘vonkdata’. If you want to continue using an existing ‘vonkstu3’ database, override MongoDbOption:DatabaseName, see Hierarchy of settings.


  1. Support for FHIR R4 next to FHIR STU3. Vonk will choose the correct handling based on the fhirVersion parameter in the mimetype. The mimetype is read from the Accept header and (for POST/PUT) the Content-Type header. See Multiple versions of FHIR for background info.

  2. Upgrade to HL7.Fhir.Net API 1.3, see its releasenotes.

  3. Administration API imports both STU3 and R4 conformance resources, see Managing Conformance Resources

    1. Note: Terminology operations are still only available for STU3.

    2. Note: Subscriptions are still only available for STU3.

  4. Conditional delete on the Administration API. It works just as on the root, see Create, read, update, patch, delete.

  5. Defining a custom SearchParameter on a Custom ResourceType is now possible.

  6. Canonical uris are now recognized when searching on references (specification)

  7. Vonk calls UseIISIntegration for better integration with IIS (if present).


  1. In the settings, PipelineOptions.Branch.Path for the root had to be /. Now you can choose your own base (like e.g. /fhir)

  2. $meta:

    1. enabled on history endpoint (e.g. /Patient/123/_history/v1)

    2. disabled on type and system level

    3. returned empty Parameters resource if resource had no meta.profile, now returns the resources meta element.

    4. when called on a non-existing resource, returns 404 (was: empty Parameters resource)

    5. added to the CapabilityStatement

  3. History on non-existing resource returned OperationOutcome instead of 404.

  4. The setting for SupportedInteractions was not enforced for custom operations.

  5. CapabilityStatement.name is updated from Vonk beta conformance to Vonk FHIR Server <version> CapabilityStatement.

  6. Terminology services:

    1. $lookup did not work on GET /CodeSystem

    2. $lookup did not support the coding parameter

    3. $expand did not fill in the expansion element.

    4. Operations were not listed in the CapabilityStatement.

    5. Namespace changed to Vonk.Plugins.Terminology, and adjusted accordingly in the default PipelineOptions.

  7. A SearchParameter of type token did not work on an element of type string, e.g. CodeSystem.version.

  8. Search with POST was broken.

  9. If a long running task is active (response code 423, see Import of Conformance Resources and Re-indexing for new or changed SearchParameters), the OperationOutcome reporting that will now hide issues stating that all the arguments were not supported (since that is not the cause of the error).

  10. Overriding an array in the settings was hard - it would still inherit part of the base setting if the base array was longer. We changed this: an array will always overwrite the complete base array. Note that this may trick you if you currently override a single array element with an environment variable. See Hierarchy of settings.

  11. The element meta.source cannot be changed on subsequent updates to a resource (R4 specific)

  12. SearchParameter StructureDefinition.ext-context yielded many errors in the log because the definition of the fhirpath in the specification is not correct. We provided a corrected version in errataFhir40.zip (see Errata to the specification).

  13. Enable or disable interactions was not evaluated for custom operations.

  14. Delete of an instance accepted search parameters on the url.

  15. Transactions: references to other resources in the transaction were not updated if the resource being referenced was in the transaction as an update (PUT). (this error was introduced in 2.0.0).

Plugin and Facade API

  1. A new NuGet package is introduced: Vonk.Fhir.R4.

  2. VonkConstants moved to the namespace Vonk.Core.Common (was: Vonk.Core.Context)

  3. IResource.Navigator element is removed (was already obsolete). Instead: Turn it into an ITypedElement and use that for navigation with FhirPath.

  4. InformationModel element is added to

    1. IResource: the model in which the resource is defined (VonkConstants.Model.FhirR3 or VonkConstants.Model.FhirR4)

    2. IVonkContext: the model that was specified in the Accept header

    3. IModelService: the model for which this service is valid (implementations are available for R3 and R4)

    4. InteractionHandler attribute: to allow you to specify that an operation is only valid for a specific FHIR version. This can also be done in the fluent interface with the new method AndInformationModel. See Interaction Handling

  5. Dependency injection: if there are implementations of an interface for R3 and R4, the dependency injection in Vonk will automatically inject the correct one based on the InformationModel in the request.

  6. If you want to register your own service just for one informationmodel, do that as follows:

    Add a ContextAware attribute to the implementation class:

    [ContextAware (InformationModels = new[] {VonkConstants.Model.FhirR3}]
    public class MySearchRepository{...}

    Then register the service as being ContextAware:

    services.TryAddContextAware<ISearchRepository, MySearchRepository>(ServiceLifeTime.Scoped);
  7. FhirPropertyIndexBuilder is moved to Vonk.Fhir.R3 (and was already marked obsolete - avoid using it)

  8. Implementations of the following that are heavily dependent upon version specific Hl7.Fhir libraries have been implemented in both Vonk.Fhir.R3 and Vonk.Fhir.R4.

    1. IModelService

    2. IStructureDefinitionSummaryProvider (to add type information to an IResource and turn it into an ITypedElement)

    3. ValidationService

  9. IConformanceContributor is changed to ICapabilityStatementContributor. The methods on it have changed slightly as well because internally they now work on a version-independent model. Please review your IConformanceContributor implementations.


  1. Document plugin:

    1. Document Bundle does not contain an identifier

    2. Missing unit test for custom resources

    3. Upgraded to Vonk 2.0.0 libraries (no, not yet 3.0.0-beta1)

  2. Facade example

    1. Added support for searching directly on a reference from Observation to Patient (e.g. /Observation?patient=Patient/3).

    2. Fixed support for _revinclude of Observation on Patient (e.g. /Patient?_revinclude:Observation:subject:Patient).

    3. Upgraded to Vonk 2.0.0 libraries (no, not yet 3.0.0-beta1)

  3. Plugin example

    1. Added examples for pre- and post handlers.

Known to-dos

  1. Re-indexing for new or changed SearchParameters: does not work for R4 yet.

  2. Preloading resources: does not work for R4 yet.

  3. Subscriptions: do not work for R4 yet.

  4. Terminology services: operations do not work for R4.

  5. During Import of Conformance Resources: Files in the import directory and Simplifier projects are only imported for R3.