Add Resource.text (Narrative) guidance to FHIR IG

In qualification testing we experience that the generic FHIR Core guidance around DomainResource.text is not clear enough. We should expand on that generic guidance for our purposes. Based on issue MM-865, propose to add the following to the FHIR IG as overarching principle:

Resource.text

Any FHIR Resource that derives from DomainResource supports the text element. This text element has datatype Narrative. Only few resources derive from something other than DomainResource. One such example is Binary. FHIR STU3 says the following about DomainResource.text:

"A human-readable narrative that contains a summary of the resource, and may be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.

Contained resources do not have narrative. Resources that are not contained SHOULD have a narrative."

Datatype Narrative further expands on what "clinically safe" entails and gives more guidance, such as:

Resources SHOULD always contain narrative to support human-consumption as a fallback. Structured data SHOULD NOT generally contain information of importance to human readers that is omitted from the narrative. Creators of FHIR resources should not assume that systems will render (or that humans will see) data that is not in the narrative.

Datatype Narrative also defines types of narrative based on their status code with choices generated, extensions, additional and empty.

Status extensions says "The contents of the narrative are entirely generated from the structured data in the content and some of the content is generated from extensions". This implementation guide expects this to be the common case as most resources can have extension content defined on them. Even if this particular resource instance does not have extension contents, the status code "extensions" still applies. Note that it is of the utmost importance to include modifier extensions in the narrative as they always affect the semantics. Receivers MAY choose to render this narrative as opposed to or in addition to rendering the structured data and/or (modifier) extensions.

Status generated says "The contents of the narrative are entirely generated from the structured data in the content." This implementation guide expects this to be a common case where the sender did not anticipate inclusion of regular extension content into the narrative. Note that it is of the utmost importance to still include modifier extensions in the narrative as they always affect the semantics. Receivers MAY choose to render this narrative as opposed to or in addition to rendering the structured data and/or (modifier) extensions.

Status empty says "No human-readable text provided in this case" and thus basically provides the opposite of "clinically safe" or human readable. This implementation guide does not anticipate a use case for this status code and senders SHOULD NOT use it unless explicitly documented why, e.g. in an information standard. When a receiver encounters such a narrative there is simply nothing he can do with it.

Status additional says "The contents of the narrative may contain additional information not found in the structured data. Note that there is no computable way to determine what the extra information is, other than by human inspection". Again this implementation guide does not anticipate a use case for this status code and senders SHOULD NOT use it unless explicitly documented why in an information standard. When a receiver encounters such a narrative it SHALL treat the information like any other extension: Receiver SHALL support it in accordance with explicitly documented use in the information standard. Receiver MAY support it if it is not explicitly documented. Receiver SHALL, upon supporting status 'additional' make clear to the user that the information is a fragment, and not the entire thing in any way it sees fit.

The expectations for Resource.text or narratives within the context of this implementation guide:

• Sender SHALL provide "clinically safe" Resource.text of status extensions (preferred) or generated, unless explicitly documented in the relevant information standard to do otherwise or unless the resource does not support narrative

• Receiver MAY support Resource.text. If they do, this SHALL be in accordance with the status and explicitly documented use in the relevant information standard

• Receiver SHALL NOT generically depend on presence of a clinically safe narrative as their only means to present data to users when an explicitly documented use case for status empty or additional exists. Also using just the narrative you would not expect to produce graphs, support medication alerts and other functionality

Informal note: Producing a "clinically safe" narrative can be cumbersome. Various reference frameworks like HAPI include a Narrative Generator of some sort.