Skip to content

Communication Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-emr-core-communication
Statusdraft (experimental) · 1.33.0
BaseCommunication (constraint)
SourceFSH · 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"
        ),
    )