3 Min Read

FHIR Profiles and Implementation Guides

Ward Weistra

Subscribe to our newsletter


Firely has recently been exploring the topic of authoring implementation guides for FHIR profiles. In this blog posting, I’d like to share some of our preliminary ideas with you. First let’s introduce a couple of key concepts.

So what is a FHIR profile? The HL7 FHIR standard defines a set of base resources, e.g. Patient and Observation. The standard base resources have very generic definitions. A FHIR profile allows you to author and publish a customized, more specific resource definition, by specifying a set of constraints and/or extensions on the base resource. Concrete FHIR resources like e.g. a Patient resource can express their conformance to a specific profile. This allows a FHIR server to programmatically validate a given resource against the associated profile definition.

Now assume we’ve authored a set of related profile definitions for our organization. We would like to publish some sort of manifest that lists all the relevant profiles and also some accompanying documentation. For this purpose, the FHIR standard introduces a Conformance Package. A conformance package typically contains:

  • A set of related resource profile definitions
  • A manifest listing all the available profile definitions (based on Composition resource)
  • An implementation guide describing the profiles

An implementation guide provides documentation about the package and the individual profiles targeting FHIR implementers and system integrators. You can find some examples on the official HL7 FHIR registry. As an implementation guide is an integral part of a conformance package, we would like to provide first-class tooling support for authoring implementation guides.

Let’s explore the requirements for an implementation guide:

  • Provide some general documentation about the conformance package
  • Provide detailed documentation for each of the individual resource profiles
  • Include documentation from external sources, e.g. if our package has external references to (third-party) profiles published elsewhere.
  • Include dynamically generated content, e.g. UML diagrams, hyperlinks to related documentation etc.
  • Support distributed content on different servers (conforming to the FHIR REST principles)
  • Define the content hierarchy
  • Provide documentation in multiple languages
  • Provide different sets of documentation targeting different audiences
  • Reuse common content in multiple implementation guides
  • Publish our implementation guide to multiple output channels (Web, mobile, PDF, …)
  • Clearly separate content from design/styling

The above requirements are closely related to Content Management Systems so we can reuse some architectural CMS concepts, e.g. the triangular relationship between content types, output channels and render templates.

CMS Concepts - Multichanneling In order to ensure that our content is suitable for publication to any output channel, we should only provide limited styling options to documentation authors (paragraphs, headings, bulleted lists; cf. Markdown syntax).

Assuming documentation may be distributed over multiple servers (just like FHIR resources and profiles), how do we find the relevant documentation for a given conformance package? Implementation Guide - Resolving Documentation

  • Resolve the global documentation associated with the conformance package itself
  • Enumerate the profiling resources in the conformance package manifest
  • For each related profiling resource
    • Resolve and include the associated documentation (recursively)

The resolving process may be driven by global publication parameters such as  language and audience; e.g. find the available documentation for a given resource, for a specific language and a specific target audience.

In a forthcoming article we will explore this process into more detail and discuss some other aspects of the proposed architecture for authoring implementation guides.

Want to stay on top of Interoperability and Health IT? 

Subscribe to our newsletter for the latest news on FHIR. 

11 thoughts

  1. […] Profiling is the mechanism of adapting FHIR Resources in a certain use-case. (Read Michel Rutten’s blog about profiling if you want to know more about the key concepts.) His concern is this: if everyone […]

  2. Steven on said:

    Hi Michel, I am a developer, in terms of profile, I am wondering other than documentation, how/if I can use the profile for dev purpose. e.g generate code or test cases etc.

    • Michel on said:

      Hi Steven,

      FHIR profiles are expressed as computable StructureDefinition resources. This allows you to create tooling that can automatically perform validation and generate rendering, code, UI, tests etc. from a given profile. Different groups in the community are actively working on relevant tooling, many of which is published as open source.

      Some examples from the FHIR community (you can find more on GitHub):

      – Ruby code generator:
      – ClinFhir UI builder:
      – AEGIS TouchStone conformance testing:
      – Simplifier profile registry:

      Hope this helps you to get started. Also I’d like to invite you to join the Skype chat group on FHIR Profiles & Conformance, as it is a great place to discuss profiling and ask questions to the community. I’ll send you an invitation by e-mail. Happy profiling!


  3. The link to the HL7 examples gets 404…can you correct this?

    Thanks in advance…

  4. […] people are implementing FHIR and are actually “profiling” their use-case (see this previous blog about […]

  5. Still get a 404 Not Found when I go to the “examples” link. Where can I see some examples of profiles and conformance files?

  6. stibbe on said:

    Hello Michel,

    Can you use FHIR profiles and export this to the Swagger tool to validate FHIR profiles and interactions.

Post a comment

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