Writing FHIR Implementation Guides
- Understand the mechanics of creating a FHIR Implementation Guide (IG) for a research use case.
- Describe best practices for authoring a FHIR IG.
- Apply these best practices in creating FHIR IGs for specific research use cases.
This module is meant for readers who are interested in creating their own FHIR Implementation Guides (IGs), and should be read after completing the Reading IGs module.
1 When should you create a FHIR IG?
FHIR IGs describe how FHIR should be used for a specific use case. When using FHIR for research, if there is not an existing IG that covers your use case, it may be worthwhile to create one. Some main reasons for creating a FHIR IG:
You intend for your work to be reused by more than one organization or group.
Your use case is non-trivial and creating a FHIR IG will serve to organize your ideas and concepts, and provide formal documentation.
You need to define multiple resource profiles that belong together or interact with each other.
Your use case is complex enough that it requires some level of automated testing, including test scripts and example resources using your profiles.
2 Benefits of creating a FHIR IG
Creating an IG can:
Specify how your data needs are mapped onto FHIR resources and data elements.
Identify which data elements are required, and how missing data should be handled for required and optional elements.
Define formatting for data elements (e.g., ensuring all dates/times are in the same format and have the desired level of precision).
Establish terminology bindings to specific ValueSets for coded values to prevent representing the same concept with different codes.
3 Who should create a FHIR IG?
FHIR IGs can be created by anyone with an understanding of FHIR and a toolchain for generating the IG. Typically the person in this role is an informaticist, or has substantial informatics experience. If you do not have someone with these skills on your project, you may be able to find someone via the FHIR community.
For research use cases, the Principal Investigator (PI) and relevant clinical experts should collaborate closely with the informaticists creating the IG to make sure it reflects the needs of the research study and is clinically sound. Additionally, informatics experts who understand the systems that will need to support the IG should also be involved in its authoring to ensure implementation is realistic.
4 What skills are necessary to create an IG?
A FHIR IG includes many different elements to describe and define a use case. The authors should be able to write a clear and concise description of the problem being addressed by the IG. This narrative text description should cover the problem overview, what impact the IG will have, the actors and transactions involved, and how this IG relates to other existing FHIR IGs and resources. Diagrams and visual aids can be included to help explain use cases or implementation specifics.
Writing the technical components of the IG will require knowledge of core FHIR resources, data types and terminology. You will need to know how to read FHIR specifications, create profiles and extensions, and understand how your IG relates to other common IGs, such as US Core.
Your IG may likely require using specific terminology and coding systems, such as SNOMED CT, LOINC, ICD or RxNorm. These codes may be further organized into specific ValueSets for use by your IG.
You should be able describe how clients (those who consume data which conforms to your IG) and servers (those who will provide or receive data which conforms to your IG) will use your IG through the FHIR API and RESTful operations. You will need an understanding of REST, JSON, XML and HTTP status codes.
An IG is intended to be computable and testable using tools such as the HL7 Validator and the IG Publisher validator. Testing and validation of your IG will require example instances of data which conforms to your profiles.
Creating an IG will often require collaboration among multiple individuals. Understanding how to use source control (such as GitHub or GitLab) will let you develop the IG collaboratively, and can track changes and versions of your IG.
5 Should IGs be created through HL7®?
Many of the IGs listed in Real World IGs are created and published through the HL7 process. This is process is helpful for IGs that may be widely implemented or need to be updated on an ongoing basis to support implementation. It may not be necessary to create or publish an IG through HL7 if it is meant to be used for a limited time to support a specific study. IGs can also be moved under HL7 after they are created, though it is typically better to do this as early as possible to avoid any intellectual property issues. Researchers interested in the HL7 process can consult with the relevant HL7 Work Group.
6 How is an IG created?
The CodeX FHIR Accelerator has published a set of comprehensive resources on IG authoring that includes a detailed explanation of how to author FHIR IGs. If you are interested in creating a FHIR IG, please use the button below to open this resource in a new window:
Open FSH Seminar > Creating an IG materials →
Additionally, these resources include a hands-on exercise for creating a FHIR IG, and a deep dive on the FSH language used for FHIR profiling. Both are strongly recommended for informaticists who wish to author FHIR IGs.