Document Status Reason Extension¶
| Canonical | ../StructureDefinition/nexus-document-status-reason |
|---|---|
| Status | draft · 1.26.0 |
| Base | Extension (constraint) |
| Context | DocumentReference (element) |
| Source | FSH · JSON |
Optional free-text reason recorded when a DocumentReference is marked superseded or entered in error. Never required — a status change with no reason is normal, and an active document carries none.
FSH
The authored source of truth: extensions/DocumentStatusReasonExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.
// DocumentStatusReasonExtension.fsh
// Free-text reason captured when a DocumentReference leaves `current` -- why it was superseded,
// or why it was entered in error. Used by NexusEmrCoreDocumentReference.
//
// R4 DocumentReference has no `statusReason` element (R5 does not add one either), and a document
// that has been retired without a word is the record every later reader has to guess at: was the
// consult replaced by a corrected copy, or filed on the wrong chart? The reason is the part of the
// status change that the status code cannot carry.
//
// It rides the version it was recorded with -- the resource is updated in place and every stored
// version keeps the reason that applied to it -- so the store's history is the audit of who changed
// what, when, and why, with no companion resource. Reactivating the document (back to `current`)
// removes the extension: an active document has no reason to be inactive.
Extension: DocumentStatusReasonExtension
Id: nexus-document-status-reason
Title: "Document Status Reason Extension"
Description: "Optional free-text reason recorded when a DocumentReference is marked superseded or entered in error. Never required — a status change with no reason is normal, and an active document carries none."
* ^url = "../StructureDefinition/nexus-document-status-reason"
* ^status = #draft
* ^date = "2026-09-05"
* ^publisher = "WELLSTAR Technologies Corp."
* ^contact.name = "Nexus EMR FHIR Implementation Guide"
* ^contact.telecom.system = #url
* ^contact.telecom.value = ".."
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "DocumentReference"
* . ^short = "Why this document is superseded or entered in error"
* . ^definition = """
Free text explaining why the document left the `current` status: what replaced a superseded
document, or what made an entered-in-error one wrong (a duplicate upload, the wrong patient's
chart). Recorded at the moment the status changes, by the person changing it.
The extension is always optional: staff record a reason when they have one, and the absence of a
reason carries no meaning. Nothing in the model should require it, and consumers must render a
status change with no reason as a complete record.
The reason belongs to the status it was recorded with. Because the DocumentReference is updated
in place, each stored version keeps the reason that applied to that version — reading a historical
version yields that version's reason. A document made `current` again carries no reason at all:
writers remove the extension on reactivation rather than leaving a stale explanation on an
active document.
Free text only: a code set could not name the replacement or the mistake without losing the
detail that makes the reason useful to the next person reading the chart.
"""
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only string
* valueString ^short = "Reason the document is superseded or entered in error, as recorded by staff"
* valueString ^definition = "The reason staff recorded for taking the document out of the current status. Not intended to be parsed."