Uploaded image for project: 'MedMij Standaarden'
  1. MedMij Standaarden
  2. MM-1050

Add Resource.text (Narrative) guidance to FHIR IG

    Details

    • Blokkerend:
      Nee
    • Informatiestandaard:
      Alle
    • Informatiestandaard onderdeel:
      Technisch
    • Impact:
      Bestaande leveranciers voldoen al. Nieuwe leveranciers weten dan beter waar ze aan toe zijn. De 'wijziging' is backward compatible.
    • FHIR Category:
      Other
    • Voorgestelde oplossing:
      Hide
      As documented in the initial issue comment.

      https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vissue-MM-1050_FHIR_IG#Resource.text

      Note: the mapping stack contains an active narrative generator so everything passing a mapping already has a narrative in compliance with this guidance. The Qualification materials have all been updated under https://github.com/Nictiz/Nictiz-STU3-testscripts/tree/MM-1050/FHIR3-0-2-MM202001-Dev and are ready for merge into the production branch
      Show
      As documented in the initial issue comment. https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vissue-MM-1050_FHIR_IG#Resource.text Note: the mapping stack contains an active narrative generator so everything passing a mapping already has a narrative in compliance with this guidance. The Qualification materials have all been updated under https://github.com/Nictiz/Nictiz-STU3-testscripts/tree/MM-1050/FHIR3-0-2-MM202001-Dev and are ready for merge into the production branch
    • Release notes:
      Hide

      The FHIR specification on Resource.text is not completely clear and found multi interpretable. Therefore, additional explanation and guidance on this subject is added to the MedMij FHIR IG.

      Show
      The FHIR specification on Resource.text is not completely clear and found multi interpretable. Therefore, additional explanation and guidance on this subject is added to the MedMij FHIR IG.

      Description

      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.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              henket Alexander Henket
              Reporter:
              henket Alexander Henket
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Estimations By Role

                  No roles have been estimated yet.