Content Source Extension¶
| Canonical | https://fhir.apps.health/StructureDefinition/nexus-content-source |
|---|---|
| Status | draft · 1.33.0 |
| Base | Extension (constraint) |
| Context | DocumentReference.content (element), DiagnosticReport.presentedForm (element) |
| Source | FSH · JSON |
Origin metadata for the file behind one DocumentReference.content or
DiagnosticReport.presentedForm entry: the system the file was delivered through, the channel, and
when the sender sent it.
FSH
The authored source of truth: extensions/ContentSourceExtension.fsh (edit on GitHub). One FSH file may define several related artifacts.
// ContentSourceExtension.fsh
// Where the FILE behind one `DocumentReference.content` or `DiagnosticReport.presentedForm` entry
// came from: the system it was delivered through, the channel, and when the sender sent it.
//
// WHY IT IS ON `content` AND NOT ON THE RESOURCE. A DocumentReference may carry the same document
// in several renditions -- a PDF and a plain-text extraction of it, say -- and only one of them is
// the file that actually arrived. The others are produced locally from it. A fact about the file's
// origin is therefore a fact about ONE rendition, and putting it on the resource root would assert
// it of every rendition including the ones this estate generated itself. So it rides the content
// entry holding the delivered file, and the derived renditions carry nothing.
//
// WHAT IT IS FOR. Documents reach a chart through several channels, and the channel is not
// recoverable from anything else on the resource: `custodian` names the organization that holds
// the document, `author` names who wrote it, and neither says how it got here. A consumer that
// needs to treat delivered documents differently from locally-authored ones -- reconciliation,
// duplicate detection against a feed, or simply telling a user where a file came from -- has no
// other element to read.
//
// THE SOURCE IS AN OPAQUE TOKEN, NOT A BOUND CODE. It names the delivery channel or system as the
// receiving pipeline knows it (`HRM`, Ontario Health's Health Report Manager, is the case this
// shape was drawn from). No value set is declared, deliberately: the set of channels is a
// deployment fact rather than a modelling one, and a required or extensible binding published here
// would make a conformant deployment nonconformant the day it adds a feed. A consumer should match
// the values its own deployment produces and pass through the ones it does not recognise.
//
// THE SAME FACT RIDES A DIAGNOSTIC REPORT'S DELIVERED FORM. A report that arrives as a rendered
// PDF and lands on `DiagnosticReport` holds that file in `presentedForm`, which is the same
// `Attachment` and the same one-rendition-among-several situation as `DocumentReference.content`.
// So the context includes it, and the rule is the same: the delivered rendition carries the
// extension, and a locally produced one carries nothing.
//
// CHANNEL AND SENT TIME. `source` names the system; it does not say whether the file came by fax,
// by mail or electronically, or when the sender sent it. FHIR's only native home for those facts is
// `Communication` (`medium`, `sent`), which is a second resource per report and a join for every
// reader that wants to show "arrived by fax on ...". Nothing in the extensions pack, R5, or any
// national core carries a channel or a sent time on a document. So this extension borrows
// Communication's vocabulary and shape onto the rendition: `channel` is a v3 ParticipationMode code,
// the value set `Communication.medium` names, and `sent` is the sender's transmission time where the
// channel gives one (a fax header, an HRM message, a Bundle timestamp). Both are optional, and an
// instance carrying `source` alone is unchanged and still conformant.
//
// RECEIVED TIME IS NOT HERE. For a DocumentReference it is `date`, when the record was filed. For a
// DiagnosticReport it is the extensions-pack `event-recorded` extension on the resource. Neither is a
// fact about one rendition.
//
// ────────────────────────────────────────────────────────────────────────────────────────────────
// WHY THIS IS NOT CALLED `nexus-emr-file-metadata`, WHICH IS THE NAME THE SHAPE SUGGESTS.
//
// That canonical is spent. Up to 1.10.0 it named a different extension -- on the
// `DocumentReference` ROOT, carrying display and embedded-section hints (`originalFileName`,
// `fileCategory`, `displayHint`, `processingInstructions`, `embeddedSections`) -- and it was
// withdrawn in 1.11.0 with the rest of the experimental clinical-document surface.
//
// A withdrawn canonical is not a free name. This guide's rule is that a published canonical URL is
// permanent: it identifies one definition for as long as anything anywhere remembers it, and that
// obligation does not lapse when the definition is withdrawn. Re-pointing it at a different context
// with a disjoint set of sub-extensions would mean one URL had named two unrelated things, and a
// reader holding pre-1.11.0 data would have no way to know which it had. So this extension takes a
// fresh canonical, and the old one stays dead.
//
// WHAT A READER SHOULD DO with an instance carrying the withdrawn sub-extensions: it is pre-1.11.0
// data, it conforms to nothing this guide currently publishes, and it is not this extension. Carry
// it forward as opaque or drop it. WHAT A WRITER SHOULD DO: write `source`, and `channel` and `sent`
// where the delivery gives them, on the entry holding the delivered file.
// ────────────────────────────────────────────────────────────────────────────────────────────────
Extension: NexusContentSource
Id: nexus-content-source
Title: "Content Source Extension"
Description: """
Origin metadata for the file behind one `DocumentReference.content` or
`DiagnosticReport.presentedForm` entry: the system the file was delivered through, the channel, and
when the sender sent it.
**On the content entry, not on the resource.** A DocumentReference or DiagnosticReport may hold
several renditions of one document and only one of them is the file that arrived; the others are
produced locally. The extension rides the delivered rendition, so derived renditions carry nothing.
**`source` is an opaque token**, naming the delivery channel as the receiving pipeline knows it.
`HRM` -- Ontario Health's Health Report Manager -- is the channel this shape was drawn from and the
value carried in this guide's example. No value set is bound: the set of channels is a deployment
fact, and a binding published here would make a deployment nonconformant the day it adds a feed.
Match the values your deployment produces and pass through the rest.
**`channel` is how the file came**: a v3 ParticipationMode code -- `FAXWRIT` (fax and eFax),
`MAILWRIT` (mail, including a scan of mailed paper), `EMAILWRIT` (email) or `ELECTRONIC` (an
electronic feed such as HRM, Ontario Health's clinical report feed, or a portal). Bound extensible:
where none of the four fits, another code may be used, preferably from ParticipationMode. **`sent` is when the sender sent
it**, where the channel says (a fax header, an HRM message, a Bundle timestamp). Both are optional.
Received time is not here: it is `DocumentReference.date`, or the extensions-pack `event-recorded`
extension on a DiagnosticReport. See [Incoming reports](../guide/patterns/incoming-reports.md).
⚠ **FIRST PASS -- do not treat this as a contract.** The extension is published under a canonical
minted for it, so nothing predates it: there is no earlier address for this shape and no legacy
instance to reconcile against. A store holds instances of it from the point a delivery pipeline
starts stamping them, and no sooner. Write `source`, and `channel` and `sent` where the delivery
gives them, on the entry holding the delivered file.
"""
* ^url = "https://fhir.apps.health/StructureDefinition/nexus-content-source"
* ^status = #draft
* ^date = "2026-09-04"
* ^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 = "DocumentReference.content"
* ^context[1].type = #element
* ^context[1].expression = "DiagnosticReport.presentedForm"
* . ^short = "Origin of the file behind this rendition (delivered renditions only)"
* value[x] 0..0
* url 1..1
* extension contains
source 1..1 MS and
channel 0..1 MS and
sent 0..1 MS
* extension[source].value[x] only string
* extension[source] ^short = "The channel or system the file was delivered through"
* extension[source] ^definition = "An opaque token naming the delivery channel or system that produced this file, as the receiving pipeline knows it -- for example `HRM`, Ontario Health's Health Report Manager. Not bound to a value set: the set of channels a deployment receives from is a deployment fact. It names HOW the file arrived, which is not recoverable from `custodian` (who holds the document) or `author` (who wrote it)."
* extension[channel].value[x] only Coding
* extension[channel].valueCoding from NexusDeliveryChannelVS (extensible)
* extension[channel] ^short = "How the file came: FAXWRIT | MAILWRIT | EMAILWRIT | ELECTRONIC"
* extension[channel] ^definition = "The channel the file was delivered through, as a v3 ParticipationMode code: `FAXWRIT` for fax and eFax, `MAILWRIT` for mail (including a scan of mailed paper), `EMAILWRIT` for email, `ELECTRONIC` for an electronic feed or portal. The same vocabulary `Communication.medium` names. Extensible: where none of the four fits, another code may be used, preferably from ParticipationMode."
* extension[sent].value[x] only dateTime
* extension[sent] ^short = "When the sender sent the file"
* extension[sent] ^definition = "The sender's transmission time, where the channel gives one: a fax header, an HRM message, a document Bundle's timestamp. Not the received time, which is `DocumentReference.date` or, on a DiagnosticReport, the `event-recorded` extension."
ValueSet: NexusDeliveryChannelVS
Id: nexus-delivery-channel
Title: "Delivery Channel"
Description: "The channels a received file is delivered through, from HL7 v3 ParticipationMode: telefax, mail, email, and electronic data. Used by the content-source extension's `channel`."
* ^url = "https://fhir.apps.health/ValueSet/nexus-delivery-channel"
* ^status = #draft
* ^experimental = false
* http://terminology.hl7.org/CodeSystem/v3-ParticipationMode#FAXWRIT "telefax"
* http://terminology.hl7.org/CodeSystem/v3-ParticipationMode#MAILWRIT "mail"
* http://terminology.hl7.org/CodeSystem/v3-ParticipationMode#EMAILWRIT "email"
* http://terminology.hl7.org/CodeSystem/v3-ParticipationMode#ELECTRONIC "electronic data"