Communication Profile¶
| Canonical | https://fhir.apps.health/StructureDefinition/nexus-emr-core-communication |
|---|---|
| Status | draft (experimental) · 1.33.0 |
| Base | Communication (constraint) |
| Source | FSH · JSON |
Nexus EMR profile for Communication, covering three distinct populations: WELL-internal staff chat about a patient, eReferral correspondence passed through from or to external partners, and outbound delivery (one fax, SMS or email sent to one recipient through a delivery service). First pass -- the pass-through boundary and message threading are not yet settled.
TypedFhir API / Pydantic schema
The typed accessor surface Communication exposes for Communication — generated from this IG's compiled profile; each typed accessor has a validating raw-FHIR twin (xRaw) where marked. The three ports are parity-enforced.
The AI-facing shape: from typed_fhir.facade.generated.schemas import CommunicationSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.
class CommunicationSchema(BaseModel):
"""AI-facing shape of the Communication profile: the facade's typed accessor
surface (curated + salient fields) as a pydantic model. `model_json_schema()` is a
structured-output / tool schema; instantiating validates an extraction."""
model_config = ConfigDict(extra="forbid")
based_on: Reference | None = Field(
None,
description=(
"On an outbound delivery: the earlier delivery a resend repeats. An order, proposal "
"or plan fulfilled in whole or in part by this Communication. Note: On an outbound "
"delivery this narrows R4's meaning: `basedOn` never names a request, only the one "
"earlier outbound delivery a resend repeats (`Communication/<id>`), and nothing else. "
"A first send carries none: the request it was sent from is not stored, so there is "
"nothing to point at. The attempt a resend repeats keeps its own status (typically "
"`not-done`) and is not updated; a chain of resends is read by following `basedOn` "
"back to the first attempt. Communication.basedOn — 0..*"
),
)
in_response_to: Reference | None = Field(
None,
description=(
"The message this one replies to. Prior communication that this communication is in "
"response to. Note: ⚠ FIRST PASS. The chat panel currently threads by neither "
"`inResponseTo` nor `partOf` -- conversation order is reconstructed from timestamps, "
"which is why concurrent messages can interleave wrongly. Declaring the element here "
"is the first step; deciding whether threads are `inResponseTo` chains or a `partOf` "
"grouping is open. Communication.inResponseTo — 0..*"
),
)
status: Literal[
"completed",
"entered-in-error",
"in-progress",
"not-done",
"on-hold",
"preparation",
"stopped",
"unknown",
] | None = Field(
None,
description=(
"preparation | in-progress | not-done | completed | entered-in-error | ... The status "
"of the transmission. Note: Internal chat writes `completed` on send. For eReferral "
"traffic the partner's lifecycle applies and `status` is pass-through -- do not infer "
"local workflow state from it. For an outbound delivery, `status` is the delivery "
"lifecycle: - queued, not yet accepted by the delivery service: `preparation` - "
"accepted by the delivery service: `in-progress` - delivered: `completed` - failed "
"for good: `not-done`, with `statusReason` carrying the delivery service's error code "
"and text - cancelled before the delivery service accepted it: `not-done` - cancelled "
"after the delivery service accepted it: `stopped` `sent` is when the delivery "
"service accepted the message, and `received` is when it reported delivery. A retry "
"after failure is a new Communication whose `basedOn` names the attempt it repeats; a "
"failed attempt keeps `not-done`. Communication.status — 1..1"
),
)
status_reason: Concept | None = Field(
None,
description=(
"Reason for current status. Captures the reason for the current state of the "
"Communication. Note: This is generally only used for \"exception\" statuses such as "
"\"not-done\", \"suspended\" or \"aborted\". The reason for performing the event at all is "
"captured in reasonCode, not here. Communication.statusReason — 0..1"
),
)
category: Concept | None = Field(
None,
description=(
"Which population: internal staff chat, or external eReferral correspondence. Which "
"population this Communication belongs to. Readers should scope on it -- internal "
"chat and external eReferral correspondence have different authorities over their "
"content, and a chat surface that does not scope will surface partner correspondence "
"into a panel never designed for it. **Outbound delivery is not chat.** A "
"Communication carrying `outbound-delivery` from `nexus-communication-category` "
"records a fax, SMS or email sent through a delivery service. A chat surface must "
"exclude it, including one that today selects everything that is not eReferral. ⚠ "
"HERITAGE EMR SITUATION -- UNRESOLVED. If heritage-EMR message history is ever "
"migrated (see `identifier`), it becomes a THIRD population alongside internal chat "
"and eReferral, and this element is where that distinction would have to live. No "
"code for it exists, because the migration decision has not been made. Anyone binding "
"a value set here must resolve that first, or the binding will need widening the "
"moment migration is agreed. Note: Bound extensible to "
"`nexus-communication-category`, which includes every HL7 communication-category code "
"(staff chat writes `notification`) plus this guide's `outbound-delivery`. Extensible "
"because the pass-through boundary is not yet decided: a partner-supplied category, "
"and the Patient Request for Corrections codes a statement of disagreement carries, "
"must stay conformant. Readers MUST still tolerate a text-only category, and must not "
"treat an unrecognized one as invalid. Communication.category — 0..*. codes "
"(extensible): alert | instruction | notification | outbound-delivery | reminder"
),
)
priority: Literal["asap", "routine", "stat", "urgent"] | None = Field(
None,
description=(
"routine | urgent | asap | stat. Characterizes how quickly the planned or in progress "
"communication must be addressed. Includes concepts such as stat, urgent, routine. "
"Note: Used to prioritize workflow (such as which communication to read first) when "
"the communication is planned or in progress. Communication.priority — 0..1"
),
)
medium: Concept | None = Field(
None,
description=(
"How the message was sent: FAXWRIT | EMAILWRIT | SMSWRIT. A channel that was used for "
"this communication (e.g. email, fax). Note: An outbound delivery carries exactly "
"one, from the Communication Medium value set (invariant "
"`nexus-communication-outbound-medium`), and beside that code the `integration` "
"coding naming the clinic sending account that carried it. Bound preferred rather "
"than extensible so that eReferral traffic keeps whatever medium its partner sends; "
"the invariant is what makes it strict for outbound delivery. Communication.medium — "
"0..*. codes (preferred): EMAILWRIT | FAXWRIT | SMSWRIT"
),
)
subject: Reference | None = Field(
None,
description=(
"The patient the communication is about. The patient or group that was the focus of "
"this communication. Note: 0..1 per R4. Internal chat about a patient SHOULD carry it "
"-- a chat message with no subject cannot be scoped to a chart, and cannot be "
"filtered out of one either, which is the access-control concern. An outbound "
"delivery carries the patient the message concerns when there is one, and none for a "
"message about no patient. Communication.subject — 0..1"
),
)
topic: Concept | None = Field(
None,
description=(
"The subject line of an outbound email. Description of the purpose/content, similar "
"to a subject line in an email. Note: For an outbound email, `topic.text` is the "
"subject line as sent; there are no codings. A request to send an email carries the "
"same text in the `nexus-communication-email-subject` extension on the "
"CommunicationRequest, and the Communication written for the send copies it here. Fax "
"and SMS have no subject and carry no `topic`. Communication.topic — 0..1"
),
)
sent: FuzzyDate | None = Field(
None,
description=(
"When the message was sent. The time when this communication was sent. "
"Communication.sent — 0..1"
),
)
received: FuzzyDate | None = Field(
None,
description=(
"When the message was received. The time when this communication arrived at the "
"destination. Communication.received — 0..1"
),
)
recipient: Reference | None = Field(
None,
description=(
"Who the message was addressed to. The entity (e.g. person, organization, clinical "
"information system, care team or device) which was the target of the communication. "
"If receipts need to be tracked by an individual, a separate resource instance will "
"need to be created for each recipient. Multiple recipient communications are "
"intended where either receipts are not tracked (e.g. a mass mail-out) or a receipt "
"is captured in aggregate (all emails confirmed received by a particular time). Note: "
"On an outbound delivery: one recipient per Communication, the recipient's name as "
"`display` (the number or address, for a bare number), and no reference. The "
"recipient as asked was in the request to send, a contained Organization that links "
"no stored record, and the request is not stored: the delivery keeps the name as "
"`display` and the address actually used in the `deliveryAddress` extension. "
"Communication.recipient — 0..*"
),
)
sender: Reference | None = Field(
None,
description=(
"Who sent the message. The entity (e.g. person, organization, clinical information "
"system, or device) which was the source of the communication. Note: Practitioner is "
"the primary provider identity in this IG. Organization covers a partner-system "
"sender on inbound eReferral traffic; Device covers system-generated messages. On an "
"outbound delivery the sender is the clinic Organization; the account that carried it "
"is the `integration` coding in `medium`. RelatedPerson covers a SUBSTITUTE "
"DECISION-MAKER acting for the patient -- a distinct fact from the patient acting "
"themselves, and one that must not be flattened onto Patient: where a right over the "
"record is exercised by proxy, the record has to show that authority was delegated, "
"because that is what is checked when the exercise is challenged. "
"Communication.sender — 0..1"
),
)
reason_code: Concept | None = Field(
None,
description=(
"Indication for message. The reason or justification for the communication. Note: "
"Textual reasons can be captured using reasonCode.text. Communication.reasonCode — "
"0..*"
),
)
payload: dict | None = Field(
None,
description=(
"The message content. Text, attachment(s), or resource(s) that was communicated to "
"the recipient. Note: Internal chat writes `contentString`. eReferral traffic may "
"carry `contentAttachment` or `contentReference` -- a reader that assumes "
"contentString will silently render an empty message. Handle all three. For an "
"outbound delivery the payload is what was sent: - fax: `contentReference` to the "
"DocumentReference sent, as a version-specific reference "
"(`DocumentReference/<id>/_history/<vid>`). This is the documented form: it records "
"the document as it stood when it was faxed, which a later edit does not change. - "
"SMS: one `contentString`, the text sent. - email: the body as one `contentString`, "
"as on the request, plus one `contentReference` per attached DocumentReference. The "
"subject line is `topic.text`, not a payload entry. Communication.payload — 0..*"
),
)
date: FuzzyDate | None = Field(
None,
description=(
"When the message was sent. The time when this communication was sent. Salient field "
"— sent | received"
),
)