Encounter Profile

Canonical	../StructureDefinition/nexus-emr-core-encounter
Status	draft · 1.26.0
Base	Encounter (constraint)
Source	FSH · JSON

Defines the Encounter resource constraints for the Nexus EMR project (CII), conforming to CA-Core+ requirements.

TypedFhir API / Pydantic schema

The typed accessor surface Encounter exposes for Encounter — 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 EncounterSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.

class EncounterSchema(BaseModel):
    """AI-facing shape of the Encounter 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")

    status: Literal[
        "arrived",
        "cancelled",
        "entered-in-error",
        "finished",
        "in-progress",
        "onleave",
        "planned",
        "triaged",
        "unknown",
    ] | None = Field(
        None,
        description=(
            "Where the encounter is in its lifecycle. The current status of the encounter. Tracks "
            "the lifecycle of the encounter. Note: This is a modifier element. The status affects "
            "how the encounter should be interpreted. Encounter.status — 1..1"
        ),
    )
    class_: str | None = Field(
        None,
        description=(
            "Classification of patient encounter. Classification of patient encounter, from the "
            "required v3-ActEncounterCode binding. Ambulatory (`AMB`) is the common case and the "
            "expected default for a clinic visit. It is NOT fixed: a virtual encounter is `VR` "
            "and an admission is `IMP`, and writing `AMB` for either asserts something the record "
            "does not support. Note: **Map from the appointment's modality, where one is known.** "
            "In-person becomes `AMB`; video, telephone and secure-message all become `VR`. That "
            "mapping is the one this guide states, and it is the reason this element is not fixed "
            "to `AMB` -- the modality axis exists precisely to distinguish a video consult from "
            "one in the room, and collapsing it here would leave that distinction living only on "
            "an extension of the Appointment, which not every Encounter has. A reader should NOT "
            "infer scope from the breadth of the binding. Nexus EMR encounters are predominantly "
            "ambulatory; `IMP` is admitted so that an admission a discharge summary refers to can "
            "be represented at all, not as a statement that inpatient workflows are modelled "
            "here. Encounter.class — 1..1"
        ),
    )
    type: Concept | None = Field(
        None,
        description=(
            "Encounter type with raw code support. Specific type of encounter (e.g., "
            "consultation, follow-up, emergency). RECOMMENDED: Standard terminology codes when "
            "available OPTIONAL: Raw EMR codes for source system preservation Where this code was "
            "mapped from a source system's own vocabulary, carry the raw coding alongside the "
            "mapped one, flagged `userSelected = true`. See [Carrying the raw "
            "code](../guide/patterns/raw-codes.md). Note: Since there are "
            "many ways to further classify encounters, this element is 0..*. Encounter.type — "
            "0..*"
        ),
    )
    service_type: Concept | None = Field(
        None,
        description=(
            "Service type with raw code support. Broad categorization of the service that is to "
            "be provided during this encounter. RECOMMENDED: Standard terminology codes when "
            "available OPTIONAL: Raw EMR codes for source system preservation. Note: Where this "
            "code was mapped from a source system's own vocabulary, carry the raw coding "
            "alongside the mapped one, flagged `userSelected = true`. See [Carrying the raw "
            "code](../guide/patterns/raw-codes.md). Encounter.serviceType "
            "— 0..1"
        ),
    )
    priority: Concept | None = Field(
        None,
        description=(
            "Indicates the urgency of the encounter. Indicates the urgency of the encounter. "
            "Encounter.priority — 0..1"
        ),
    )
    subject: Reference | None = Field(
        None,
        description=(
            "The patient present at the encounter. The patient who is the focus of the encounter. "
            "Must reference using Nexus EMR patient identifier. Note: References should use "
            "identifier-based references following Nexus EMR patterns. Encounter.subject — 1..1"
        ),
    )
    participant: dict | None = Field(
        None,
        description=(
            "List of participants involved in the encounter. The healthcare professionals and "
            "organizations participating in the encounter. Encounter.participant — 0..1"
        ),
    )
    appointment: Reference | None = Field(
        None,
        description=(
            "The appointment this encounter fulfils (1:1 in primary care). The Appointment that "
            "scheduled this Encounter. **Primary care: exactly one.** The booked appointment and "
            "the visit that happened are the same event seen from the scheduling and clinical "
            "sides, and consumers may assume one appointment per encounter for primary-care data. "
            "**Not guaranteed in general.** Zero is valid (a walk-in or unscheduled visit has no "
            "appointment). More than one is valid (an Encounter fulfilling several bookings). And "
            "several Encounters MAY reference the same Appointment -- that is how a booked visit "
            "that becomes multiple encounters is represented, and nothing here forbids it. "
            "Clinical resources arising from the visit associate to the **Encounter**, not to the "
            "Appointment. Encounter is the anchor; the Appointment is how the visit got "
            "scheduled. Note: A reader wanting 'the appointment for this visit' takes the single "
            "entry in primary-care data and MUST tolerate zero. A reader wanting 'the "
            "encounter(s) for this appointment' must SEARCH Encounter by this element -- R4 has "
            "no reverse element on Appointment. See the query-capability note: search support for "
            "that direction is not yet declared in a CapabilityStatement. Encounter.appointment — "
            "0..*"
        ),
    )
    period: dict | None = Field(
        None,
        description=(
            "The start and end time of the encounter. The start and end time of the encounter. "
            "Start time is required, end time is optional for ongoing encounters. Note: If the "
            "encounter is ongoing, the end date will be empty. Encounter.period — 1..1"
        ),
    )
    reason_code: Concept | None = Field(
        None,
        description=(
            "Encounter reason with raw code support. Coded reason the encounter takes place. "
            "RECOMMENDED: SNOMED CT or other standard terminology when available OPTIONAL: Raw "
            "EMR codes for source system preservation Where this code was mapped from a source "
            "system's own vocabulary, carry the raw coding alongside the mapped one, flagged "
            "`userSelected = true`. See [Carrying the raw "
            "code](../guide/patterns/raw-codes.md). Note: For systems "
            "that need to know which was the primary diagnosis, these will be marked with the "
            "standard extension primaryDiagnosis (which is a sequence value rather than a flag, 1 "
            "= primary diagnosis). Encounter.reasonCode — 0..*"
        ),
    )
    diagnosis: dict | None = Field(
        None,
        description=(
            "The list of diagnoses relevant to this encounter. The diagnoses relevant to this "
            "encounter. These may be conditions identified during the encounter. "
            "Encounter.diagnosis — 0..*"
        ),
    )
    location: dict | None = Field(
        None,
        description=(
            "List of locations where the encounter occurred. List of locations where the patient "
            "has been during this encounter. Note: Multiple locations may indicate patient "
            "movement during the encounter. Encounter.location — 0..*"
        ),
    )
    service_provider: Reference | None = Field(
        None,
        description=(
            "The organization providing the service. The organization that is primarily "
            "responsible for this encounter's services. Note: This may be different from the "
            "location's managing organization. Encounter.serviceProvider — 0..1"
        ),
    )
    visit_class: str | None = Field(
        None,
        description=(
            "Classification of patient encounter. Classification of patient encounter, from the "
            "required v3-ActEncounterCode binding. Ambulatory (`AMB`) is the common case and the "
            "expected default for a clinic visit. It is NOT fixed: a virtual encounter is `VR` "
            "and an admission is `IMP`, and writing `AMB` for either asserts something the record "
            "does not support. Note: **Map from the appointment's modality, where one is known.** "
            "In-person becomes `AMB`; video, telephone and secure-message all become `VR`. That "
            "mapping is the one this guide states, and it is the reason this element is not fixed "
            "to `AMB` -- the modality axis exists precisely to distinguish a video consult from "
            "one in the room, and collapsing it here would leave that distinction living only on "
            "an extension of the Appointment, which not every Encounter has. A reader should NOT "
            "infer scope from the breadth of the binding. Nexus EMR encounters are predominantly "
            "ambulatory; `IMP` is admitted so that an admission a discharge summary refers to can "
            "be represented at all, not as a statement that inpatient workflows are modelled "
            "here. Salient field — class.display | class.code"
        ),
    )