Resource Note Extension¶
| Canonical | ../StructureDefinition/nexus-emr-resource-note |
|---|---|
| Status | draft · 1.26.0 |
| Base | Extension (constraint) |
| Context | DomainResource (element) |
| Source | FSH · 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. The thread is append-only and readers order it 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.
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, and the thread is append-only:
// nothing edits or deletes a recorded note. 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.
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. The thread is append-only and readers order it 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."
* ^url = "../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 = ".."
* ^jurisdiction = urn:iso:std:iso:3166#CA "Canada"
* ^context[0].type = #element
* ^context[0].expression = "DomainResource"
* . ^short = "An attributed note on the resource (append-only, ordered by time)"
* . ^definition = "One note recorded on the resource: who said it, when, and what they said. Repeats form the resource's thread -- append-only, ordered by the value's `time`, oldest first."
* . ^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"