Handling FHIR 'Narrative' on import

Clinical
1

As part of the openEHR-FHIR collaboration, there is a Working group with mixed FHIR/openEHR members working through the FHIR and openEHR datatypes to make recommendations on best-practice mappings, including where technical changes, on either side, might be helpful at some point.

One of the issues that has arisen is the FHIR Narrative element, which appears in most FHIR ‘domain’ resources, and allows the structured content of the resource to be expressed or replicated as HTML (XHTML).

Any resource that is a DomainResource (all resources except Bundle, Parameters and Binary) may include 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 is an XHTML fragment with a flag to indicate its relationship to the data:

The ‘Narrative’ datatype is described here

The issue for us is if/how to handle that Narrative block if it appears in imported FHIR, as this does have some data quaity/clinical safety implications.

If it was always guaranteed to be a human-readable direct ‘copy’ of other structured data in the resource, we could probably use the [openEHR RMfeeder_audit.original_content]( NeoEHR ) attribute, which is available on every archetype node.

However, it is possible that the xhtml is the only content provided by the FHIR resource, or it may introduce new content/clinical ideas that are not in the structured data.

There is flag within the Narrative datatype which categories use

CleanShot 2025-08-28 at 08.52.33
CleanShot 2025-08-28 at 08.52.331263×348 45.8 KB

It is quite possible that there is no clear, universal answer to how to handle this without a detailed local use-case analysis especially for ‘additional’ but it might be useful to at least formulate some guidance on the safest alternatives

e.g. For generated use original_content, for additional, use a new CLUSTER.fhir_narrative archetype in an extension slot, that mimics the Narrative block.

1 Like
2

The INSTRUCTION class has its own narrative element, and as far as I can understand it has the same use case as the FHIR equivalent. Is there a reason other classes don’t have this element?

:astonished_face:this sounds somewhat unsafe?

3

Good point about INSTRUCTION.narrative. I think the intent was as a safety feature as a backup to complex instructions e.g Meds that might be difficult to comprehend. TBH we rarely use this now, but I might expect it for medication orders.

We want to avoid RM changes, of course, but there is definitely some sort of case for adding narrative to other ENTRY calsses, I guess.

Unsafe - potentially yes. I agree, and the FHIR specs do discuss some of these issues plus the even more potentially scary idea of linking fragments of narrative to structured content!!

I doubt if any explicit advice can be given but in an integration context, many of us will find ourselves facing these questions, and some sort of baseline guidance would be really helpful.

2 Likes
4

Echoes of CDA days… :grimacing:

1 Like
5

Quote from Narrative - FHIR v4.0.1:

Resource instances that permit narrative 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. However, in strictly managed trading systems where all systems share a common data model and additional text is unnecessary or even a clinical safety risk, the narrative may be omitted. Implementers should give careful consideration before doing this, as it will mean that such resources can only be understood in the limited trading environment. Closed trading partner environments are very likely to open up during the lifetime of the resources they define. Also, many workflow steps involving finding and aggregating resources are much more difficult or tedious if the resources involved do not have their own text.

6

You don’t know beforehand if the original content is human-readable content, so this won’t be a general solution.

This is the definition of the original_content field:

Optional inline inclusion of or reference to original content corresponding to the openEHR content at this node. Typically a URI reference to a document or message in a persistent store associated with the EHR.

Another quick idea would be to check the IMPORTED_VERSION.commit_audit.description.

Though those are not semantically the same to the purpose of the FHIR narrative (so it’s little hacky IMHO to map those fields). If we need to support exactly the semantics of a human-readable narrative alongside structured data at the top level structure (COMPO, FOLDER, PERSON, ORG etc), that’s something that needs to be added to the RM.

2 Likes
7

A little bit more from FHIR Chat, in relation to the next version of IPS.

#IPS > Referencing from IPS narrative to data @ :speech_balloon:

Linking Narrative to Discrete FHIR Resources

Since the IPS Composition requires each section to have human-readable narrative text as XHTML, we encourage implementers to reference individual discrete entries in the XHTML using the id attribute and an accompanying “textLink” extension that links this id to the resource….

So , for good or bad, we are going to face this issue at least in relation to IPS but also, I suspect in referrals and discharges

1 Like
8

Right now the only way to do that is cute custom archetyped elements which contents at runtime need to be generated somehow.

Though is we want better alignment with fhir we might need a change in the RM itself.

9

Here’s my two cents.

The inclusion of the narrative text was part of the success in the adoption of HL7 CDA. A CDA level 2 allowed a transition from narrative data to semi-structured information. FHIR has inherited part of this functionality with the narrative part of the resources. But that does not mean that we should follow the same path.

For good or for bad, one of the main characteristics of openEHR is that is built based on well structured information models. If, at some point, we need to add an Element to register non-structured information, that should be a decision of the modelers on a case-by-case basis. If we allow to add any narrative for example to a Composition we are opening the systems to storing any kind of non-structured, non-interoperable, non-reusable information., breaking one of the principles of openEHR.

This doesn’t mean that we cannot do anything to improve.

  • If we are exporting data (from the CDR to a readable text for human consumption), the narrative text should come exclusively from the structured Elements, including those Comments/Instructions/… or whatever Elements that the modeler decides to include in the archetype. In FHIR that is status=Generated or status=Extensions. We don’t need a new attribute in the RM for that. We probably only need to add a function get_narrative_text() with some pseudo code showing how implementers should traverse all descendant Elements to get their information and build that text, so that the implementations are somehow aligned.
  • If we are importing data (from a narrative text to structured openEHR), you already mentioned it, let’s look to the feeder_audit and improve it if needed to better represent the original information, but don’t mix it with the structured data part of the RM.
4 Likes
10

In actual fact, most archetypes have a generic ‘Description’ or ‘Clinical description’ data element. This can record a narrative that embraces the structured data but includes clinical nuance not apparent in the structured data elements alone OR it can be used as a landing spot for importing legacy ‘text blobs’ into a new record if necessary, effectively the starting point for more structured data.

It is not quite the same but might be helpful to understand current modelling patterns.

2 Likes
11

Of course, the narrative can, and maybe in most cases should, be calculated. If it’s a method in the RM, it’s still a change. Then it will be an attribute in a serialization format that holds that value, another change to JSON/XML schemas.

My point is that currently openEHR doesn’t have exactly what’s on the FHIR model for the narrative, and FHIR has the narrative for all clinical, administrative, etc. resources.

12

Most of the “clinical concept“ archetypes do, but for example the score/scale/prom archetypes don’t.

1 Like