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