Skip to content

Resource Note Extension

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-emr-resource-note
Statusdraft · 1.33.0
BaseExtension (constraint)
ContextDomainResource (element)
SourceFSH · JSON

An attributed note recorded on a resource with no note element of its own, such as the comment thread on a DocumentReference. Each repeat is one note in the Task Note turn shape -- author and time required, markdown text, machine authors as identifier-only logical references -- so every thread in the EMR reads and validates identically. A note's text may be corrected in place, under the author and time it was recorded with, and readers order the thread by the value's time, oldest first. Where a resource defines a native note element, that element is the home and this extension is not used. Only the note's author corrects it; time stays the time it was first recorded, and the earlier text survives only in version history, which a store holding these threads SHALL keep. Each note SHOULD carry an id, unique within the resource and unchanged by a correction. It is equivalent to HL7's http://hl7.org/fhir/StructureDefinition/note from the extensions pack, with the value constrained to the Task Note shape; an export to a system that uses that extension maps one to the other.

FSH

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

// ResourceNoteExtension.fsh
// An attributed note recorded on a resource that has no `note` element of its own.
//
// WHY AN EXTENSION. R4 gives many resources a native `note` element and this IG's position is
// that where one exists it is the home -- a Task's conversation lives in `Task.note`, and a
// writer reaching for this extension there is reaching past the element the resource already
// offers. But several resources define no `note` at all (DocumentReference is the one that
// forced the question: its comment thread has nowhere native to live), and for those the only
// honest mechanism is an Annotation-valued extension on the resource itself. Anchoring the
// context at DomainResource rather than at DocumentReference is deliberate: the next resource
// without a `note` element gets the same thread the same way, instead of minting a sibling
// extension per resource.
//
// WHY THE TASK NOTE SHAPE. The value is not a bare Annotation but the Task Note datatype
// profile -- one conversation turn: author and time required, markdown text, and the
// identifier-only logical-reference shape for machine authors (harness graphs, decision-support
// rules) that base R4 cannot express on `Annotation.author`. A note on a document is the same
// animal as a turn on a task, on a different anchor, and giving it the same named shape means
// every thread in the EMR reads and validates identically -- including who wrote it, which for
// a clinical remark is the whole point.
//
// THREAD SEMANTICS. The extension repeats, one note per repeat. A correction changes the note's
// `text` in place -- its author and time stay as recorded -- and nothing deletes a recorded note.
// Only the note's author corrects it. `time` is when the note was first recorded, not when it was
// last corrected; the earlier text survives only in the resource's version history, so a store
// holding these threads SHALL keep that history. Each note SHOULD carry an `id`, unique within the
// resource and unchanged when its text is corrected -- it is how a writer finds the note again.
// Readers order by the value's `time`, oldest first.
// Because the notes ride the resource they annotate, reading a thread is reading the resource
// -- no search, no client-side matching, no second fetch.
//
// EQUIVALENT TO HL7's `note`. The extensions pack publishes
// `http://hl7.org/fhir/StructureDefinition/note`: an Annotation on any resource, with the same rule
// that it is not used where a native `note` exists. This extension says the same thing with the
// value narrowed to the Task Note turn shape. An export to a system that uses HL7's extension maps
// one to the other, repeat for repeat; the canonical and the semantics here are unchanged.

Extension: ResourceNoteExtension
Id: nexus-emr-resource-note
Title: "Resource Note Extension"
Description: "An attributed note recorded on a resource with no `note` element of its own, such as the comment thread on a DocumentReference. Each repeat is one note in the Task Note turn shape -- author and time required, markdown text, machine authors as identifier-only logical references -- so every thread in the EMR reads and validates identically. A note's `text` may be corrected in place, under the author and time it was recorded with, and readers order the thread by the value's `time`, oldest first. Where a resource defines a native `note` element, that element is the home and this extension is not used. Only the note's author corrects it; `time` stays the time it was first recorded, and the earlier text survives only in version history, which a store holding these threads SHALL keep. Each note SHOULD carry an `id`, unique within the resource and unchanged by a correction. It is equivalent to HL7's `http://hl7.org/fhir/StructureDefinition/note` from the extensions pack, with the value constrained to the Task Note shape; an export to a system that uses that extension maps one to the other."
* ^url = "https://fhir.apps.health/StructureDefinition/nexus-emr-resource-note"
* ^status = #draft
* ^date = "2026-09-02"
* ^publisher = "WELLSTAR Technologies Corp."
* ^contact.name = "Nexus EMR FHIR Implementation Guide"
* ^contact.telecom.system = #url
* ^contact.telecom.value = "https://fhir.apps.health"
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "DomainResource"
* . ^short = "An attributed note on the resource (ordered by time)"
* . ^definition = "One note recorded on the resource: who said it, when, and what they said. Repeats form the resource's thread, ordered by the value's `time`, oldest first. A note's `text` may be corrected in place; its author and time stay as recorded."
* . ^comment = "Only for resources without a native `note` element. Where R4 defines one (Task, Observation, and the rest), the native element is the home and this extension is not used there."
* extension 0..0
* url 1..1
* value[x] 1..1 MS
* value[x] only NexusEmrTaskNote
* value[x] ^short = "The note: one conversation turn -- author and time required"