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.
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?
- 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.