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 JohnMoehrke@gmail.com)

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 #Normative content in IHE Supplement)

Tools

The person name I have listed is not the only one to give credit to, but is listed to help explain the linage (Provenance) of that tool.

Current Guidance on writing Profiles of FHIR

FHIR offers some new ways to publish what IHE calls a Profile. IHE must first continue to follow our governance and produce normative content in IHE Supplement format. Second priority is to leverage the new FHIR conformance Resources.

Normative content in IHE Supplement

This is what IHE publishes as the Normative content. Following the long standing Supplement format, governance, public-comment, and publication mechanisms that IHE uses for all Profiles.

  • 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.
      • Contact John.Moehrke@gmail.com if you need help submitting tracker items, or tracking them
  • wiki Profiles page
    • All active IHE Profiles should have a Profiles page, and have the FHIR icon indicated on the mention on the Profiles page
    • The existence of a Profile page on the IHE wiki is very important for FHIR profiles as it will be the place where links to additional resources
      • later we might produce html directly from an automated ImplementationGuide build (see future)
    • the profile specific wiki profiles pages should be marked with the FHIR category (see template for how) so that they show up on the FHIR page
  • Getting community input on your profile should leverage the FHIR chat system (zulip) http://chat.fhir.org
    • There is an IHE stream for our use https://chat.fhir.org/#narrow/stream/ihe
      • 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

FHIR conformance resources

The second priority is to produce FHIR conformance resources. These are usually XML files as will be described here. The result of this is published conformance resources which are 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
  • The profile specific wiki Profiles page should have a "FHIR Implementation Guide" section that
    • Link to the http://registry.fhir.org location where the profile specific conformance resources are published (which is likely a simplifier link)
    • Lists all of the FHIR conformance resources that are published on the IHE FTP site
    • List any examples that are on the IHE FTP site (in the domain specific directory)
    • List any TestScripts
    • List any reference implementations or other technical assistance.
    • See PDQm for example
  • URIs for your conformance resources would be rooted at http://ihe.net/fhir/ while they are published on the FTP site
    • see below for content type specific naming conventions
  • ImplementationGuide resource -- don't confuse this with an Implementation Guide, which is human readable HTML. For the human readable we are using our PDF (by way of our wiki)
    • We are using ImplementationGuide resource only as a manifest of conformance resources we are publishing for our Profile
    • List each StructureDefinition, CapabilityStatement, and/or ValueSet
    • See below
  • 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.
    • see more below
  • CapabilityStatement to show minimal conformance requirements per Actor
    • Query parameters that must be supported
    • Resources must be supported (or will be used)
    • see more below

Examples

Third priority is to provide examples to your audience.

  • 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

Profile editors are not forbidden from experimenting beyond this guidance. Please report your lessons learned to the IHE-FHIR workgroup

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 files will eventually 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 http://ihe.net/fhir
    • Note the naming conventions below for each type of conformance resource.
    • The Implementation Materials has a 'fhir' directory for all of these
      • ImplementationGuide directory for all of the ImplementationGuide resource files (not html files)
      • StructureDefinition directory for all of the StructureDefinitions resource files
      • CapabilityStatement directory for all the CapabilityStatements resource files
      • ValueSet directory for all the ValueSets resource files
      • CodeSystem directory for all the CodeSystem resource files

FHIR conformance Resource templates

Implementation Guide - Content recommendation

The ImplementationGuide resource is very unstable right now, it is a combination of information that the HL7 FHIR build tools use to automatically create an Implementation Guide HTML pages for human readable, and partially it is output of this build process itemizing the conformance resources specified in the Implementation Guide.

For now, IHE will use the ImplementationGuide resource only as a manifest of the conformance resources defined in the IHE Profile. There is future work to improve this, but not the current goal.

Note that when you publish your ImplementationGuide to Simplifier it will display as "The resource cannot be rendered". This is because Simplifier can only render an ImplementationGuide that is created using Simplifier, which is only available to paid users. This does not diminish the purpose we are looking for, but is rather evidence of how unstable the Implementation Guide publication process is today.

It is difficult to create an ImplementationGuide resource using tooling, as they are focused on a different goal than we are. So it is best to start with the following and just fill in the few specifics for your IHE Profile.

Update the bold lines.

  • url - follow the url pattern given
  • name - acronym
  • date - update each time you edit and upload
  • description - include url to wiki page
  • package.name - acronym
  • package.description - longer description of your profile
  • package.resource - include entry for each of your conformance resources (StructureDefinition, CapabilityStatement, ValueSet, etc)

Example

Example from PDQm

<?xml version="1.0" encoding="utf-8"?>
<ImplementationGuide xmlns="http://hl7.org/fhir">
   <url value="http://ihe.net/fhir/ImplementationGuide/IHE.PDQm" /> 
   <name value="PDQm" /> 
 <status value="draft" />
 <experimental value="false" />
   <date value="2017-11-02T08:30:26.5335975-05:00" /> 
 <publisher value="Integrating the Healthcare Enterprise (IHE)" />
 <contact>
   <name value="IHE" />
   <telecom>
     <system value="url" />
     <value value="http://ihe.net" />
   </telecom>
 </contact>
   <description value="Implementation Guide for IHE PDQm profile. See http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)" />  
 <copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" />
 <fhirVersion value="3.0.1" />
 <package>
     <name value="PDQm" /> 
     <description value="The Patient Demographics Query for Mobile (PDQm) Profile defines a lightweight RESTful interface to a patient demographics supplier leveraging technologies readily available to mobile applications and lightweight browser based applications." />  
   <resource>
     <example value="false" />
       <name value="Consumer Actor" /> 
       <description value="Initiates query for a Patient resource given query parameters" />  
       <sourceUri value="http://ihe.net/fhir/CapabilityStatement/IHE.PDQm.consumer" />  
   </resource>
   <resource>
     <example value="false" />
       <name value="Supplier Actor" /> 
       <description value="Responds to queries for Patient resource " /> 
       <sourceUri value="http://ihe.net/fhir/CapabilityStatement/IHE.PDQm.supplier" /> 
   </resource>
   <resource>
     <example value="false" />
       <name value="Patient profile" /> 
       <description value="Constraints on Patient resource" /> 
       <sourceUri value="http://ihe.net/fhir/StructureDefinition/IHE.PDQm.Patient" />  
   </resource>
 </package>
</ImplementationGuide>

StructureDefinition - content recommendation

StructureDefinition is critical for developers. It is equivalent to the Volume 2 "Message Encoding", or Volume 3 content

Many tools are good at producing a StructureDefinition. I have found Forge to be good at StructureDefinition. If you use a tool, then all of this is just filling out text entries.

  • name - "IHE."+<Profile-acronym>+"."+<Resource>+["."+<option-name>]
    • e.g. "IHE.PDQm.Patient"
    • If you have options that change the structure, then also have StructreDefinition with them
      • e.g. "IHE.mCSD.Location.Distance"
  • url - follow the url pattern given
  • title - full name of profile
  • status - most likely "draft" for now. Once we have Final-Text we would use "active".(I think)
  • date - update each time you edit and upload
  • publisher - IHE (see below)
  • description - include url to wiki page
  • purpose - describe in words what is constrained
  • copyright - IHE (see below)
  • fhirVersion - version of fhir needed
    • "3.0.1" is STU3
  • snapshot - not necessary, but may contain the STU3 definition of the resource (I have left them empty)
  • differential - your constraints (please use a tool like Forge)

Example

This from PDQm structure definition

<StructureDefinition xmlns="http://hl7.org/fhir">
   <url value="http://ihe.net/fhir/StructureDefinition/IHE.PDQm.Patient" /> 
   <name value="PDQm Patent" /> 
   <title value="IHE Patient Demographics Query for Mobile" /> 
 <status value="draft" />
   <date value="2017-11-01T09:37:21.358-05:00" /> 
 <publisher value="Integrating the Healthcare Enterprise (IHE)" />
 <contact>
   <name value="IHE" />
   <telecom>
     <system value="url" />
     <value value="http://ihe.net" />
   </telecom>
 </contact>
   <description value="See http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)" /> 
   <purpose value="Lightweight RESTful query interface to a patient demographics supplier." /> 
 <copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" />
 <fhirVersion value="3.0.1" />
 <kind value="resource" />
 <abstract value="false" />
 <type value="Patient" />
 <baseDefinition value="http://hl7.org/fhir/StructureDefinition/Patient" />
 <derivation value="constraint" />
 <differential>
   <element id="Patient.animal">
     <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-explicit-type-name">
       <valueString value="Animal" />
     </extension>
     <path value="Patient.animal" />
     <max value="0" />
   </element>
 </differential>
</StructureDefinition>

CapabilityStatement- content recommendation

CapabilityStaement is seen as informative for developers, but not critical. The CapabilityStatement has three different purposes. In this case we are defining what we WANT the Actor to support. Described in the FHIR specification as a "desired solution". It thus defines an Actor 'capability', so you will have one of these for each Actor. For simple client/server systems they are just mirrors.

Often times an IHE Profile Option will cause you to need to publish alternative CapabilityStatements.

No known tool helps at producing a CapabilityStatement. Simpifier does display them. If you use a tool, then all of this is just filling out text entries.

  • name - "IHE."+<Profile-acronym>+"."+<actor-name>"[+<option-name>]
    • e.g. IHE.PDQm.supplier
    • if you profile has options that affect Actors, then add the option name
      • e.g. IHE.mCSD.CareServicesSelectiveConsumer.Location
  • url - follow the url pattern given
  • title - human readable full name of profile + Actor name
    • e.g. "IHE PDQm Supplier actor"
  • date - update each time you edit and upload
  • description - include url to wiki page
  • purpose -- human readable explaination of why 'this' CapabilityStatement exists. This is more narrative than the title, but should not be too wordy. Expect reader will follow the url to the wiki page found in description
  • kind == "requirements" to indicate that this is a requirements capabiltyStatement indicating desired requirements
  • fhirVersion - indicate the FHIR version
    • STU3 is "3.0.1"
  • format -- indicate the mime types
    • "application/fhir+xml"
    • "application/fhir+json"
  • profile - indicate your StructureDefinition
  • rest - indicate your actions and query parameters required

Example

This from PDQm structure definition for the Supplier Actor

<CapabilityStatement xmlns="http://hl7.org/fhir">
' 	<url value="http://ihe.net/fhir/CapabilityStatement/IHE.PDQm.supplier" /> ' 
' 	<name value="IHE PDQm - Supplier (server)" /> ' 
' 	<title value="IHE ITI Patient Demographics Query for Mobile (PDQm) - Supplier (server)" /> ' 
	<status value="draft" />
	<experimental value="false" />
' 	<date value="2017-11-01T09:37:21.358-05:00" /> ' 
	<publisher value="Integrating the Healthcare Enterprise (IHE)" />
	<contact> 
		<name value="IHE"/> 
		<telecom> 
			<system value="url"/> 
			<value value="http://ihe.net"/> 
		</telecom> 
	</contact> 
' 	<description value="see http://wiki.ihe.net/index.php/Patient_Demographics_Query_for_Mobile_(PDQm)" /> ' 
	<copyright value="IHE http://www.ihe.net/Governance/#Intellectual_Property" />
	<kind value="requirements" />
	<fhirVersion value="3.0.1" />
	<format value="application/fhir+xml" />
	<format value="application/fhir+json" />
	<profile>
' 		<reference value="http://ihe.net/fhir/StructureDefinition/IHE.PDQm.Patient" /> ' 
	</profile>
' 
	<rest>
		<mode value="server" />
		<documentation value="PDQm server provides capability to query for Patient resources matching a sub-set of the FHIR core Patient resource query parameters" />
		<security>
			<cors value="false" />
			<description value="Recommend IUA or SMART" />
		</security>
		<resource>

			<type value="Patient" />
			<profile>
				<reference value="http://ihe.net/fhir/StructureDefinition/IHE.PDQm.Patient" />
			</profile>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<interaction>
				
			</interaction>
			<searchParam>
				<name value="_id" />
				<definition value="http://hl7.org/fhir/SearchParameter/Patient-_id" />
				<type value="token" />
				<documentation value="Logical id of this artifact" />
			</searchParam>
 ...


		</resource>
		<interaction>
			
		</interaction>
 ' 
	</rest>
</CapabilityStatement>

Filed CR for future improvements

GF#14299: CapabilityStatement - of requirements kind - should be able to import (nesting) other CapabilityStatements of requirements kind

ValueSet - content recommendation

no guidance at this time. please experiment and help us with your lessons learned

CodeSystem - content recommendation

no guidance at this time. please experiment and help us with your lessons learned

OperationDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

SearchParameter- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

MessageDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

CompartmentDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

TestScript -- content recommendation

Although TestScript is not considered by FHIR to be part of conformance resources, it is a critical Resource for documenting an ImplementationGuide.

no guidance at this time. please experiment and help us with your lessons learned

ElementDefinition- content recommendation

no guidance at this time. please experiment and help us with your lessons learned

other conformance?

no guidance at this time. please experiment and help us with your lessons learned

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 https://simplifier.net
  • Use of GIT for publication rather than FTP
    • This might be more easy to automate with the FHIR Registry.
  • Use of ClinFHIR as a tool to capture Volume 1 like material

Future

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

Glossary

IHE and HL7 are using different words to cover similar areas.

  • IHE Profile --> HL7 Implementation Guide
  • HL7 FHIR Profile --> Message Semantics (e.g. Volume 2, message semantics; or Volume 3 content Profile)