Firely Server Terminology
Firely Updates
3 Min Read

Firely Server is Exploring Terminology

Christiaan Knaap
Christiaan Knaap

Subscribe to our newsletter



We added support for a couple of terminology operations to Firely Server.

CodeSystems and ValueSets

FHIR is very particular about specifying which codes you are allowed to use when exchanging data. The validator from the FHIR .NET API is also capable of validating whether you used a code in a resource that is allowed according to the profile that is validated against. This works with a three-step approach:

  1. CodeSystem: a CodeSystem resource describes a coherent set of codes, either by referring to an existing set, like Snomed-CT or LOINC or by specifying the codes within the resource, like the example CodeSystem Marital Status in FHIR
  2. ValueSet: a ValueSet is a combination of (sub)sets of codes from one or more CodeSystem resources.
  3. Then, in a profile (either in the core spec, or a derived profile), an element of type code is bound to a ValueSet, with a binding.

Terminology big and small

Code systems like Snomed-CT and LOINC are large and complex, and are meant to be handled by a full-fledged Terminology server. Firely Server is not a terminology server. So support for code systems and value sets within Firely Server is limited to simpler ones, like the ones that you can get from the specification. Or defined by yourself as part of an Implementation Guide.

Managing your terminology resources

Firely Server already had knowledge about all the CodeSystem and ValueSet resources that are part of the FHIR specification, for use by the validator. Besides that, you can load your own conformance resources into the Firely Server administration endpoint. And that now includes CodeSystem and ValueSet resources. You can load them through the FHIR RESTful API, from a zip file or from a Simplifier project. Previously, only the resources that you had loaded yourself were actually available on the <base>/administration/CodeSystem and /ValueSet endpoints. We decided to make this more consistent, and host the ValueSets and CodeSystems from the specification as well.

As a consequence, when you start Firely Server for the very first time, it will start loading the ValueSets, CodeSystems and other conformance resources from the ‘’ that contains all the conformance resources from the FHIR Specification and is part of the Firely Server distribution. This takes a couple of minutes, but it happens only once.

Using them

FHIR defines a couple of operations on terminology related resources, as listed on the terminology page. Firely Server has implemented four of these. Since Firely Server keeps the conformance resources that influence the way Firely Server operates on it’s /administration endpoint, these operations are also defined on that endpoint:

  1. <base>/administration/CodeSystem/$lookup
  2. <base>/administration/CodeSystem/$compose
  3. <base>/administration/ValueSet/$expand
  4. <base>/administration/ValueSet/$validate-code

You can check the Firely Server documentation on these operations for the exact parameters that we do and don’t support.


We always like to hear what you think. Are these operations useful to you? In the way we implemented them currently? Or is it just clutter? Before we expand support for terminology we want to gather your feedback! Reach us at

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 *