Guidance on writing Profiles of FHIR

From IHE Wiki
Jump to navigation Jump to search

This is an outline only, details will be added as requested (send email to

Current Guidance on 'use' of FHIR

FHIR is an emerging standard from HL7. It is currently at "Standard for Trial Use" (STU). This is an acceptable stage for IHE Profile use, but would be less stable than a Normative standard. Sometimes IHE will Profile a STU standard because it is the best fit. See Standards Selection Process

An IHE Profile that is using a STU standard must stay at "Trial Implementation". That is the IHE Profile can not progress to "Final Text" until the underlying standard is "Normative". See IHE Profile Phases of Development. See Final Text Process

Because FHIR is seen as unstable by some, we agree the FMM of the used FHIR parts should be exposed prominently within the IHE Profile supplement. (see below)

Current Guidance on writing Profiles of FHIR

  • First priority is supplement form like any other IHE Profile - It is the Normative content
    • Yes this is a PDF publication mechanism, but it is what we have as approved Governance
    • Supplement should expose the FHIR Maturity Model (FMM) evaluation of the parts (e.g. Resources) used from FHIR. This helps expose to the reader of the supplement the level of maturity. A lower number means less stable FHIR specification.
      • Title page have text at 12 point (smaller than other text on the title page) "HL7® FHIR® STU 3",
      • and the range of FMM (this example is 1-5) -- "Using Resources at FMM Levels 1-5"
      • Introduction to the Supplement - should explain this FMM in more detail
      • See MHD as an example or the current supplement template here
    • Volume 1 is very close to what is visualized for FHIR Implementation Guide. Defining Actors, Transactions, Options; and showing how they work together.
    • Volume 2+ should be kept to minimum, but must include ALL normative requirements (SHALL) of the profile
      • When a FHIR resource is constrained in an IHE profile, the table documenting those constraints should contain the same column headings
        • FHIR Resource Element Name, IHE Constraint, Mapping, Notes
        • For rules (invariant) put a unique note number in the table, with the rules expressed in table end-notes
      • When documenting a constrained FHIR resource in an IHE profile the table should contain all elements in the resource, not just those constrained by IHE.
      • When a FHIR resource is extended in an IHE profile, the table documenting those constraints should contain the same column headings
      • ITI has a Volume 2 “Appendix Z on FHIR”. This is published now as a standalone supplement, and will be updated as needed. It is intended to be referenced by IHE FHIR-based profiles for ‘common’ stuff, eg error codes, cardinality definitions, security considerations. ITI expects the contents will grow over time, and other domains might suggest future expansions to the content by submitting a CP.
      • When a bug is found in FHIR, or where a new capability is needed in FHIR; the committee should submit a Change Request (CR) to FHIR, and include the resulting CR number as an "Open Issue" in their IHE Profile supplement. This aids with keeping track for future revisions and knowledge.
A link to submit a report is found at the bottom of all of HL7's FHIR pages. To do so requires a "gForge" account, which can be requested from the tracker logon page; account requests are usually approved within a day. Alternatively, several IHE committee members are familiar with submitting tracker issues.
    • wiki Profiles page
      • This is very important for FHIR profiles, at this time, as it will be the place where links to additional resources
    • Getting community input on your profile should leverage the FHIR chat system (zulip)
      • There is an IHE stream for our use
        • posting outside this stream is okay. The stream is just there for our use, not as a constraint.
      • You may find it useful to start a new thread for your profile
  • Second priority is FHIR conformance resources: -- Informative at this time
    • Published on IHE FTP site in the Implementation Material See below for more detail on FTP site layout, filenames, and URL
    • wiki Profiles page should have a "FHIR Implementation Guide" section that itemizes
    • URLs for your conformance resources would be<Resource>/<yourfilename>
    • StructureDefinition to hold constraints on each FHIR Resource
      • Cardionality constraints
      • vocabulary (valueset) constraints
      • mapping
      • Use of "Must Support" -- In the context of IHE Profiles documented using the FHIR conformance resources, when the FHIR StructureDefintion "Must Support" is indicated on any data element it SHALL be interpreted as "Required if known". If the sending application has data for the element, it is required to populate the element with a non-empty value. If the value is not known, the element may be omitted. A receiving application may ignore the information conveyed by the element. A receiving application shall not raise an error solely due to the presence or absence of the element. This definition of Must Support is derived from IHE "Required if Known - R2 and "HL7v2 concept “Required but may be empty - RE” described in HL7v2 V28_CH02B_Conformance.doc.
      • etc???
    • CapabilityStatement to show minimal conformance requirements per Actor
      • Query parameters that must be supported
      • Resources must be supported (or will be used)
      • ???
  • Third priority is examples
    • For any Resource in your profile, there should be an example on the IHE FTP site at Implementation Material
    • Any publicly available FHIR reference implementation server that you know supports your profile should also be mentioned in your Profiles wiki page "FHIR Implementation Guide" section

Not forbidden from experimenting beyond

FHIR use of IHE FTP Directory

There are two different things we will publish in the Implementation Materials.

  1. Example resources, messages, interactions
  2. FHIR conformance resources (StructureDefinition, CapabilityStatement, ValueSet, etc)
    • These are going to be registered on the FHIR Registry, and that will be the primary way they will be discovered.
    • All of these, regardless of domain will need to exist in the same directory, following the FHIR URL convention.
    • Eventually this FTP may be replaced by GIT, or may be reflected directly onto
    • The Implementation Materials has a 'fhir' directory for all of these
      • StructureDefinition directory for all of the StructureDefinitions
        • your filename for your StructureDefinition will be "IHE."<Profile-acronym>+"."+<Resource-name>+".structuredefinition"+[".json"|".xml"]
        • your identifier (StructureDefinition.url) will be ""+filename (without the +".structuredefinition"+[".json"|".xml"])
      • CapabilityStatement directory for all the CapabilityStatements
        • CapabilityStatement filename: <Profile-acronym>+<actor-name>+".capabilitystatement.xml"+[".json"|".xml"]
        • your filename for your CapabilityStatement will be "IHE."<Profile-acronym>+"."+<actor-name>+".capabilitystatement"+[".json"|".xml"]
        • your identifier (CapabilityStatement.url) will be ""+filename (without the +".capabilitystatement"+[".json"|".xml"])
      • ValuSet directory for all the ValueSets

Near Future

The following are some items the IHE-FHIR-wg is close to having a recommendation. These should be considered experimental, but likely to become guidance.

  • Guidance on how to link your conformance resources on HL7 FHIR Registry
    • I am working through how we do this. Today it can be done through Simplifier, but each of us would need to create accounts, each of us would create independent projects. The problem with this is that a critical step is in the hands of individuals, rather than the committee. This gets problematic when updates need to happen but the original profile author is no-longer active in the committee.
    • Simplifier
  • Use of GIT for publication rather than FTP
    • Rob Horn is looking at using GITHUB. This might be more easy to automate with the FHIR Registry.
  • Use of ClinFHIR as a tool to capture Volume 1 like material


These are also potential items the IHE-FHIR-wg might further develop. These are less likely to become recommended, and a Profile author should be very cautious with these items.

  • Implementation Guide publication is not mature enough to support IHE governance
    • Experience with FHIR ImplementationGuide resource and various tooling shows that it not ready for use