Measurement Rationale Extension¶
| Canonical | ../StructureDefinition/measurement-rationale |
|---|---|
| Status | draft · 1.26.0 |
| Base | Extension (constraint) |
| Context | ObservationDefinition (element) |
| Source | FSH · JSON |
Why this measurement definition exists: the specific ambiguity or unit trap it prevents. Required on every definition, because a definition that cannot name the failure it prevents is a guess, and the failures this guards against (affine unit conversions, off-by-one ordinal scales) produce numbers that render and validate while being wrong. Carried as an extension because R4's ObservationDefinition has no narrative element; it retires into description on a move to R5.
FSH
The authored source of truth: extensions/MeasurementRationale.fsh (edit on GitHub). One FSH file may define several related artifacts.
// MeasurementRationale.fsh
// FHIR-71. Why a measurement definition exists at all -- the trap it prevents, stated on the
// definition that prevents it.
//
// WHAT A MEASUREMENT DEFINITION IS FOR. A number in a chart is a value plus a convention, and the
// value alone does not carry the convention. Two of them cost real money to get wrong:
//
// * HbA1c is reported as NGSP percent and as IFCC mmol/mol. Both are dimensionally valid, UCUM
// will convert between them, and the conversion is AFFINE -- so a ratio-only converter is
// wrong by roughly 1.7 percentage points across the diabetic range, in the direction that
// looks plausible.
// * mMRC dyspnoea runs 0 to 4 and the original MRC scale runs 1 to 5, off by one across the
// entire range. LOINC does not distinguish them; SNOMED does.
//
// Neither failure announces itself. Both produce a number that renders, validates, trends, and is
// wrong -- which is why each definition has to say which trap it is preventing. An entry that
// cannot name one is a guess, and a guess here becomes a rule someone has to argue with later.
//
// WHY AN EXTENSION. R4's `ObservationDefinition` has no `description`, `purpose` or `comment` --
// no narrative element of any kind -- so there is nowhere in the base resource to put this. R5
// adds `description`, and when this specification moves to R5 the rationale belongs there and this
// extension retires. It exists to carry one element across one version gap, not to become a home.
//
// WHERE THE INSTANCES LIVE. This specification defines the SHAPE. The measurement definitions
// themselves are deployment content, layered starter pack -> deployment -> tenant with later
// definitions winning by canonical URL, because adding a measurement must not require releasing a
// library. So this extension is defined here and exampled here rarely: the population that uses it
// is out in the content packs, by design.
Extension: MeasurementRationale
Id: measurement-rationale
Title: "Measurement Rationale"
Description: "Why this measurement definition exists: the specific ambiguity or unit trap it prevents. Required on every definition, because a definition that cannot name the failure it prevents is a guess, and the failures this guards against (affine unit conversions, off-by-one ordinal scales) produce numbers that render and validate while being wrong. Carried as an extension because R4's ObservationDefinition has no narrative element; it retires into `description` on a move to R5."
* ^url = "../StructureDefinition/measurement-rationale"
* ^status = #draft
* ^context[0].type = #element
* ^context[0].expression = "ObservationDefinition"
* value[x] only string
* value[x] 1..1
* value[x] ^short = "The trap this definition prevents, in a sentence"
* value[x] ^definition = "Names the concrete failure: which two conventions are confusable, and what goes wrong when they are confused. Prose, addressed to whoever is deciding whether to change or remove this definition."
* url 1..1