HRM Accompanying Description Extension

Canonical	../StructureDefinition/hrm-accompanying-description
Status	draft · 1.26.0
Base	Extension (constraint)
Context	Observation (element)
Source	FSH · JSON

The accompanying description of an observation within a report ingested from Health Report Manager, preserved exactly as the source message carried it.

FSH

The authored source of truth: extensions/HrmAccompanyingExtensions.fsh (edit on GitHub). One FSH file may define several related artifacts.

// HrmAccompanyingExtensions.fsh
// The three accompanying fields an inbound Health Report Manager observation carries, preserved
// verbatim on the `Observation` they were converted into.
//
// THREE SIMPLE EXTENSIONS, NOT ONE COMPLEX ONE. Each is written independently at the root of the
// `Observation`, each holds a string, and each appears only when the source field was populated.
// Grouping them under a single parent extension would describe a shape the data does not have.
// They are declared in one file because they are one family and are only ever meaningful together.
//
// WHY THEY EXIST WHEN TWO OF THEM ARE ALSO IN `code`. The conversion is lossy in a way that is easy
// to miss. The accompanying subclass becomes `Observation.code.coding.code` and the accompanying
// description becomes its display; where the subclass is absent, the description or the mnemonic
// becomes `code.text` instead, and where nothing is present at all `code.text` becomes the literal
// `Unknown`. So which source field a given `code` came from is NOT recoverable from `code`. These
// extensions make each source field readable on its own terms regardless of what `code` ended up
// holding, and the mnemonic in particular has nowhere else to go.
//
// THE ACCOMPANYING SUBCLASS IS NOT SPLIT HERE, AND NEITHER IS IT IN `code`. Note that this differs
// from the report-level subclass on `DiagnosticReport.code`, which IS split on the first `^`. Both
// carry `CodeSystem/hrm-subclass`, and a value from one is not guaranteed to be spelled like a
// value from the other. See that code system for the full rule.
//
// VALUES ARE OPAQUE SOURCE STRINGS. They are copied from the message without normalisation,
// trimming or validation. Do not parse them, and do not assume two facilities use them alike.
//
// THE ADDRESSES THESE ARE PUBLISHED AT ARE NOT THE ONES THE SOFTWARE WRITES TODAY. Each migration
// note is in its own Description, which is the text that travels inside the package; the handbook
// states the rule and indexes every published artifact in this position, in
// `docs/guide/patterns/canonical-urls.md`.

Extension: HrmAccompanyingSubClass
Id: hrm-accompanying-subclass
Title: "HRM Accompanying SubClass Extension"
Description: """
The accompanying subclass of an observation within a report ingested from Health Report Manager,
preserved exactly as the source message carried it.

**Present only when the source field was populated**, and copied without normalisation, trimming or
validation. Treat it as opaque.

**The same string is normally also the observation's code.** Where it is present it becomes
`Observation.code.coding.code` under `CodeSystem/hrm-subclass`. It is preserved here because which
source field a given `code` was built from is not recoverable from `code` alone.

**It is not split, unlike the report-level subclass.** The subclass on `DiagnosticReport.code` is
split on the first `^`; this one never is. Values from the two are not guaranteed to be spelled
alike even under the same code system.

**Nexus EMR writes this today at
`http://services.well.com/fhir/observation/hrm-accompanying-subclass` (FHIR-372)**: it is live in
stored `Observation.extension` entries and in code, and is under migration to the canonical
declared here. Write the canonical; expect both until the migration completes.
"""
* ^url = "../StructureDefinition/hrm-accompanying-subclass"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Observation"
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only string
* valueString ^short = "Accompanying subclass, verbatim from the source message"
* valueString ^definition = "The accompanying subclass string as the source message carried it, unsplit and unnormalised. Opaque: do not parse it, and do not assume two sending facilities use the same string alike."

Extension: HrmAccompanyingDescription
Id: hrm-accompanying-description
Title: "HRM Accompanying Description Extension"
Description: """
The accompanying description of an observation within a report ingested from Health Report Manager,
preserved exactly as the source message carried it.

**Present only when the source field was populated**, and copied without normalisation, trimming or
validation.

**Where it also appears in `code` depends on what else the message carried.** With an accompanying
subclass present it is both the display on `Observation.code.coding` and `code.text`; without one it
is `code.text` alone. Preserving it here is what makes it readable without first working out which
of those happened.

**Nexus EMR writes this today at
`http://services.well.com/fhir/observation/hrm-accompanying-description` (FHIR-372)**: it is live
in stored `Observation.extension` entries and in code, and is under migration to the canonical
declared here. Write the canonical; expect both until the migration completes.
"""
* ^url = "../StructureDefinition/hrm-accompanying-description"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Observation"
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only string
* valueString ^short = "Accompanying description, verbatim from the source message"
* valueString ^definition = "The accompanying description string as the source message carried it, unnormalised. Human-readable text rather than a code, and not guaranteed to correspond to any code the observation carries."

Extension: HrmAccompanyingMnemonic
Id: hrm-accompanying-mnemonic
Title: "HRM Accompanying Mnemonic Extension"
Description: """
The accompanying mnemonic of an observation within a report ingested from Health Report Manager,
preserved exactly as the source message carried it.

**This is the one of the three with nowhere else to go.** The mnemonic reaches `code.text` only in
the narrow case where the message carried no accompanying description; otherwise this extension is
the only place it survives the conversion.

**Present only when the source field was populated**, and copied without normalisation, trimming or
validation. It is a source-local abbreviation, not a code from any published terminology: do not
match it against one.

**Nexus EMR writes this today at
`http://services.well.com/fhir/observation/hrm-accompanying-mnemonic` (FHIR-372)**: it is live in
stored `Observation.extension` entries and in code, and is under migration to the canonical
declared here. Write the canonical; expect both until the migration completes.
"""
* ^url = "../StructureDefinition/hrm-accompanying-mnemonic"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "Observation"
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only string
* valueString ^short = "Accompanying mnemonic, verbatim from the source message"
* valueString ^definition = "The accompanying mnemonic string as the source message carried it, unnormalised. A source-local abbreviation, not a code from a published terminology."