Referral Profile

Canonical	../StructureDefinition/nexus-core-referral
Status	draft · 1.26.0
Base	ServiceRequest (constraint)
Source	FSH · JSON

Defines the Nexus EMR FHIR profile for referrals: a request that another clinician or service accept the patient, for consultation, second opinion, or ongoing management. Aligned to the pan-Canadian CA-eReC / Ontario eReferral contract, which is the shape Nexus already exchanges with Ocean. Distinct from NexusEmrCoreServiceRequest, which governs laboratory, imaging and procedure ORDERS and fixes intent to order.

TypedFhir API / Pydantic schema

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

class ServiceRequestSchema(BaseModel):
    """AI-facing shape of the ServiceRequest 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[
        "active",
        "completed",
        "draft",
        "entered-in-error",
        "on-hold",
        "revoked",
        "unknown",
    ] | None = Field(
        None,
        description=(
            "draft | active | on-hold | revoked | completed | entered-in-error. The status of the "
            "order. Indicates the current state of the service request. Note: This is a modifier "
            "element. The status affects how the request should be processed. "
            "ServiceRequest.status — 1..1"
        ),
    )
    intent: Literal[
        "directive",
        "filler-order",
        "instance-order",
        "option",
        "order",
        "original-order",
        "plan",
        "proposal",
        "reflex-order",
    ] | None = Field(
        None,
        description=(
            "order. Whether the request is a proposal, plan, an original order or a reflex order. "
            "Fixed to `order` on this profile, which governs laboratory, imaging and procedure "
            "ORDERS. A referral is `proposal` -- it asks a receiving service to accept the "
            "patient and carries no authorization to act -- and is profiled as NexusCoreReferral. "
            "Note: This element distinguishes between different stages of the ordering workflow. "
            "A resource that needs `proposal` is not an order and does not belong on this "
            "profile. ServiceRequest.intent — 1..1"
        ),
    )
    category: Concept | None = Field(
        None,
        description=(
            "Service Category. The category of service being ORDERED: laboratory tests, "
            "diagnostic imaging, or procedures. The bound value set is the base FHIR "
            "ServiceRequest category value set, which enumerates exactly five concepts (108252007 "
            "Laboratory procedure, 363679005 Imaging, 409063005 Counselling, 409073007 Education, "
            "387713003 Surgical procedure). It contains no referral concept and is not a subtree "
            "one could be added under, so a referral is NOT expressible here and must not be "
            "forced into the nearest neighbour. Referrals carry the receiving service or "
            "specialty in category and are profiled as NexusCoreReferral. Note: There may be "
            "multiple axis of categorization depending on the context or use case for retrieving "
            "or displaying the resource. The level of granularity is defined by the category "
            "concepts in the value set. ServiceRequest.category — 1..1. codes (required): "
            "108252007 | 363679005 | 387713003 | 409063005 | 409073007"
        ),
    )
    priority: Literal["asap", "routine", "stat", "urgent"] | None = Field(
        None,
        description=(
            "routine | urgent | asap | stat. Indicates how quickly the ServiceRequest should be "
            "addressed with respect to other requests. ServiceRequest.priority — 0..1"
        ),
    )
    code: Concept | None = Field(
        None,
        description=(
            "Service requested with raw code support. What service is being ordered (e.g., "
            "specific lab test, imaging study, or procedure). REQUIRED: text element for human "
            "readability RECOMMENDED: SNOMED CT, LOINC, or other standard terminology when "
            "available OPTIONAL: Raw EMR codes for source system preservation Nexus EMR does not "
            "mandate a specific coding system for service request codes. The text element ensures "
            "human readability even when coded values are not recognized. 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: Many laboratory "
            "and radiology procedure codes embed the specimen/organ system in the test order "
            "name, for example, serum or serum/plasma glucose, or a chest x-ray. The specimen "
            "might not be recorded separately from the test code. ServiceRequest.code — 1..1"
        ),
    )
    order_detail: Concept | None = Field(
        None,
        description=(
            "Additional order information. Additional details and instructions about the how the "
            "services are to be delivered. For example, and order for a urinary catheter may have "
            "an order detail for an external or indwelling catheter, or an order for a bandage "
            "may require additional instructions specifying how the bandage should be applied. "
            "Note: For information from the medical record intended to support the delivery of "
            "the requested services, use the `supportingInformation` element. "
            "ServiceRequest.orderDetail — 0..*"
        ),
    )
    subject: Reference | None = Field(
        None,
        description=(
            "Individual or entity the service is ordered for. The patient for whom the service is "
            "being requested. Must reference using Nexus EMR patient identifier. Note: References "
            "should use identifier-based references following Nexus EMR patterns. "
            "ServiceRequest.subject — 1..1"
        ),
    )
    encounter: Reference | None = Field(
        None,
        description=(
            "Encounter in which the request was created. The encounter during which this service "
            "request was created. Optional but provides important clinical context. Note: Linking "
            "to encounter helps establish the clinical context of the request. "
            "ServiceRequest.encounter — 0..1"
        ),
    )
    authored_on: FuzzyDate | None = Field(
        None,
        description=(
            "Date request was initially authored. When the request was originally "
            "authored/created in the system. Note: This is the creation date, not when the "
            "service should be performed. ServiceRequest.authoredOn — 1..1"
        ),
    )
    performer_type: Concept | None = Field(
        None,
        description=(
            "Performer role. Desired type of performer for doing the requested service. Note: "
            "This is a role, not a participation type. In other words, does not describe the task "
            "but describes the capacity. For example, “compounding pharmacy”, “psychiatrist” or "
            "“internal referral”. ServiceRequest.performerType — 0..1"
        ),
    )
    location_code: Concept | None = Field(
        None,
        description=(
            "Requested location. The preferred location(s) where the procedure should actually "
            "happen in coded or free text form. E.g. at home or nursing day care center. "
            "ServiceRequest.locationCode — 0..*"
        ),
    )
    reason_code: Concept | None = Field(
        None,
        description=(
            "Explanation/Justification for procedure or service. An explanation or justification "
            "for why this service is being requested in coded or textual form. This is often for "
            "billing purposes. May relate to the resources referred to in `supportingInfo`. Note: "
            "This element represents why the referral is being made and may be used to decide how "
            "the service will be performed, or even if it will be performed at all. Use "
            "`CodeableConcept.text` element if the data is free (uncoded) text as shown in the "
            "[CT Scan example](servicerequest-example-di.html). ServiceRequest.reasonCode — 0..*"
        ),
    )
    body_site: Concept | None = Field(
        None,
        description=(
            "Location on Body. Anatomic location where the procedure should be performed. This is "
            "the target site. Note: Only used if not implicit in the code found in "
            "ServiceRequest.code. If the use case requires BodySite to be handled as a separate "
            "resource instead of an inline coded element (e.g. to identify and track separately) "
            "then use the standard extension "
            "[procedure-targetBodyStructure](extension-procedure-targetbodystructure.html). "
            "ServiceRequest.bodySite — 0..*"
        ),
    )