FHIR profiles and implementation guides (2)

In a previous article we introduced the concept of FHIR implementation guides. Recently our FHIR team at Firely had another in-depth discussion about this topic. In this follow up I’d like to share some more details concerning the concept architecture of implementation guides.

An implementation guide contains a set of documentation pages. Let’s explore these two concepts in further detail.

Implementation Guide

  • Provide a set of conceptually related documentation content
    • Via a list of references to Documentation Pages
    • Describe resources defined by one or more conformance packages
  • Define the content navigation structure
    • Given a specific documentation page, specify the list of child pages
    • Given a specific documentation page, specify a list of related pages (“see also”)
  • Define the common presentation template
    • Define the common page layout
    • Define common visual styles
    • Define navigation controls (e.g. main menu, navigation bar, links to children etc.)
  • Possible representations (not defined yet)
    • A directory structure with files
    • A ZIP file
    • A composition resource providing references to included resources

Documentation Page

  • A stand-alone resource, addressable via URL
    • Initial implementation could use a resource profile based on Basic resource
    • Possible candidate for promotion to a standard resource
  • Shared/reusable; may be included in zero, one or several implementation guides
    • Example: an implementation guide for a hospital may include documentation pages published by a national organization.
  • Contains editorial content
    • Structured content (HTML; markdown)
    • Basic formatting; must be suitable for display in differently styled implementation guides
  • Define page topic via a resource reference
    • Allows searching for documentation pages concerning a specific resource
  • Optionally provide references to local page resources such as images
  • Optionally provide references to related external information, e.g. YouTube, HL7 etc.
  • Does NOT provide references to other Documentation Pages
    • Implementation Guide defines navigation structure

Sharing common documentation pages

A specific documentation page may be included in one ore more implementation guides. For example, a hospital implements resources defined by a national organization. The implementation guide for the hospital includes the relevant documentation pages from the national implementation guide. This implies that a documentation page itself has no navigation context; the navigation structure must be defined by the implementation guide. Specifically, an implementation guide defines the list of child pages for a specific documentation page. Different implementation guides can include a common documentation page in different positions within the navigation hierarchy.

Publishing documentation pages

A documentation page can express the topic of the page via a resource reference. This provides documentation search capabilities for FHIR servers; given a specific resource, a server can resolve the associated documentation pages. For example, a FHIR registry could present a list of links to related documentation pages on the detail page for a specific resource. However because an individual documentation page does not have a navigation context, the server can only present a stand alone, bare rendering of a documentation page. A user must visit the associated implementation guide(s) in order to navigate to related documentation pages.

Publishing Documentation

Implementation guides and documentation pages will be published to a FHIR registry server. A FHIR registry server could provide:

  • List / search conformance packages
    • Detail page for a conformance package can present links to related implementation guides
  • List / search implementation guides
    • Hyperlink to an implementation guide leads to the start page, as defined by the implementation guide author
  • List / search documentation pages
    • Less useful, because stand-alone pages have no navigation context
    • Optionally the server could present a list of associated implementation guides that include/reference a specific documentation page

About Michel Rutten

Technical specialist at Firely. Lead developer of Forge, the official FHIR profiling tool.