Referral order

In R4, the standalone ReferralRequest from DSTU2 was merged into ServiceRequest. A referral is a ServiceRequest with a referral category and a target Practitioner / specialty.

DSP content_type

`order.referral`

FHIR target

`ServiceRequest (category=referral, intent=plan)`

Field-by-field

DSP	FHIR R4	Notes
`type: REFERRAL_ORDER`	`ServiceRequest.category = referral`	`http://snomed.info/sct\|3457005` or US Core referral category.
`intent`	`ServiceRequest.intent` (typically `plan` or `order`)
target specialty	`ServiceRequest.performerType` (SNOMED)
target provider	`ServiceRequest.performer` → Practitioner / PractitionerRole
reason for referral	`reasonCode` / `reasonReference`
supporting info (labs, notes)	`supportingInfo`	References to Condition, Observation, DocumentReference.
referral letter (DSP `document`)	`Composition` with `type`=LOINC `57133-1`	Or `DocumentReference` attachment. Link via `ServiceRequest.supportingInfo`.

Side-by-side example

DSP 1.0's public documentation does not yet include a dedicated referral order schema page (the order.referral URL currently 404s). The DSP example below is inferred from the base order schema + common referral patterns — treat as illustrative until the Microsoft docs publish the canonical shape.

DSP (inferred shape)

{
  "id": "ref-001",
  "type": "REFERRAL_ORDER",
  "context": { "content_type": "order.referral" },
  "description": "Referral to Cardiology for atypical chest pain workup",
  "intent": "plan",
  "reason": "Atypical chest pain, workup requested",
  "reason_references": ["cond-cp-001"],
  "order_data": {
    "specialty": {
      "text": "Cardiology",
      "codes": [{"system":"snomed","code":"394579002"}]
    },
    "to_provider": "Dr. Elena Park, MD",
    "urgency": "routine",
    "supporting_documents": ["doc-001"]
  }
}

FHIR R4 (DSP-FHIR profile)

{
  "resourceType":"ServiceRequest",
  "status":"active","intent":"plan",
  "category":[{"coding":[{"system":"http://snomed.info/sct","code":"3457005","display":"Patient referral"}]}],
  "code":{"text":"Referral to Cardiology"},
  "performerType":{"coding":[{"system":"http://snomed.info/sct","code":"394579002","display":"Cardiology"}]},
  "performer":[{"display":"Dr. Elena Park, MD"}],
  "priority":"routine",
  "reasonCode":[{"text":"Atypical chest pain, workup requested"}],
  "reasonReference":[{"reference":"Condition/cond-cp-001"}],
  "supportingInfo":[{"reference":"DocumentReference/referral-letter-001"}],
  "subject":{"reference":"Patient/pat-67890"},
  "encounter":{"reference":"Encounter/enc-12345"}
}

DSP → FHIR mapping

Skeleton for DspReferralOrder → ServiceRequest(category=referral). DSP 1.0 has not yet published the canonical referral shape, so this map covers the inferred fields.

map "https://dsp-fhir.org/StructureMap/DspReferralOrderToServiceRequest" = "DspReferralOrderToServiceRequest"

uses "https://dsp-fhir.org/StructureDefinition/DspResource" alias DspResource as source
uses "http://hl7.org/fhir/StructureDefinition/ServiceRequest" alias ServiceRequest as target

group DspReferralOrderToServiceRequest(source src : DspResource, target tgt : ServiceRequest) {
  src.id as id -> tgt.id = id;
  src -> tgt.status = 'active';
  src -> tgt.intent = 'order';
  src -> tgt.category as cat, cat.coding as co,
    co.system = 'http://terminology.hl7.org/CodeSystem/service-category',
    co.code = 'referral' "category";

  src.payload as p then {
    p.specialty as sp -> tgt.performerType as pt, pt.text = sp "performer-type";
    p.reason as r -> tgt.reasonCode as rc, rc.text = r "reason";
    p.description as d -> tgt.code as code, code.text = d "code-text";
  };

  src.confidence as conf -> tgt.extension as ext then {
    conf -> ext.url = 'https://dsp-fhir.org/StructureDefinition/dsp-confidence-score',
            ext.value = create('decimal') as v, v.value = conf;
  } "confidence";
}

FHIR → DSP (canonical `$graphql` read)

Standard FHIR $graphql selects every native ServiceRequest field used by the referral profile.

Canonical query

query DspReferralOrder($id: ID!) {
  ServiceRequest(id: $id) {
    id status intent priority
    code { text coding { system code display } }
    performerType { text coding { system code display } }
    performer { reference display }
    reasonCode { text }
    reasonReference { reference }
    supportingInfo { reference }

    confidence: extension(url: "https://dsp-fhir.org/StructureDefinition/dsp-confidence-score") {
      valueDecimal
    }
    turnRefs: extension(url: "https://dsp-fhir.org/StructureDefinition/dsp-transcript-turn-ref") {
      transcript: extension(url: "transcript") { valueReference { reference } }
      turn:       extension(url: "turn")       { valueInteger }
    }
  }
}

DSP reconstruction adapter

function toDspReferralOrder(s) {
  const turnRefs = s.turnRefs ?? [];
  return {
    id: s.id,
    type: 'REFERRAL_ORDER',
    intent: s.intent,
    description: s.code?.text,
    reason: s.reasonCode?.[0]?.text,
    reason_references: s.reasonReference?.map(r => r.reference),
    order_data: {
      specialty: {
        text: s.performerType?.text ?? s.performerType?.coding?.[0]?.display,
        codes: (s.performerType?.coding ?? []).map(toDspCode),
      },
      to_provider: s.performer?.[0]?.display ?? s.performer?.[0]?.reference,
      urgency:     s.priority,
      supporting_documents: s.supportingInfo?.map(r => r.reference),
    },
    confidence_score: s.confidence?.[0]?.valueDecimal,
    provenance:       turnRefs.map(t => t.turn?.valueInteger),
    transcript_ref:   turnRefs[0]?.transcript?.valueReference?.reference,
  };
}

No data loss. Every DSP-originated field maps to a native FHIR field.

SQL-on-FHIR v2 ViewDefinition that flattens every field above — including DSP extensions — into a tabular projection. Runnable as-is on any spec-conformant engine (Pathling, sof-exec, Aidbox SQL-on-FHIR, Databricks). See the SQL-on-FHIR v2 spec. These ViewDefinitions also ship as JSON in the IG zip.

`dsp_service_request_referral` — DSP Referral (ServiceRequest)

Flattens DSP dsp referral (servicerequest) orders. Filtered by category=referral.

{
  "resourceType": "ViewDefinition",
  "url": "https://dsp-fhir.org/ViewDefinition/dsp-service-request-referral",
  "name": "dsp_service_request_referral",
  "title": "DSP Referral (ServiceRequest)",
  "status": "draft",
  "description": "Flattens DSP dsp referral (servicerequest) orders. Filtered by category=referral.",
  "resource": "ServiceRequest",
  "fhirVersion": [
    "4.0.1"
  ],
  "where": [
    {
      "path": "category.coding.where(code='referral').exists()"
    }
  ],
  "select": [
    {
      "column": [
        {
          "name": "id",
          "path": "id",
          "type": "id",
          "description": "Server-assigned logical id."
        },
        {
          "name": "version_id",
          "path": "meta.versionId",
          "type": "id",
          "description": "FHIR version id (drives NEW/UPDATED classification)."
        },
        {
          "name": "last_updated",
          "path": "meta.lastUpdated",
          "type": "instant",
          "description": "Instant of last mutation."
        },
        {
          "name": "meta_source",
          "path": "meta.source",
          "type": "uri"
        },
        {
          "name": "payload_version",
          "path": "meta.tag.where(system='https://dsp-fhir.org/CodeSystem/payload-version').code.first()",
          "type": "code",
          "description": "DSP payload version this resource was last emitted under."
        },
        {
          "name": "confidence_score",
          "path": "extension('https://dsp-fhir.org/StructureDefinition/confidence-score').value.ofType(decimal)",
          "type": "decimal",
          "description": "DSP confidence (0..1)."
        },
        {
          "name": "transcript_ref",
          "path": "extension('https://dsp-fhir.org/StructureDefinition/transcript-turn-refs').extension('transcript').value.ofType(Reference).reference",
          "type": "string",
          "description": "DocumentReference/<id>/_history/<v> that pins the transcript version for turn indices."
        },
        {
          "name": "turn_indices",
          "path": "extension('https://dsp-fhir.org/StructureDefinition/transcript-turn-refs').extension('turn').value.ofType(integer)",
          "type": "integer",
          "collection": true,
          "description": "Turn indices joined by $ground into transcript content."
        },
        {
          "name": "spoken_forms",
          "path": "extension('https://dsp-fhir.org/StructureDefinition/spoken-forms').extension('form').value.ofType(string)",
          "type": "string",
          "collection": true
        },
        {
          "name": "search_terms",
          "path": "extension('https://dsp-fhir.org/StructureDefinition/search-terms').extension('term').value.ofType(string)",
          "type": "string",
          "collection": true
        },
        {
          "name": "status",
          "path": "status",
          "type": "code"
        },
        {
          "name": "intent",
          "path": "intent",
          "type": "code"
        },
        {
          "name": "priority",
          "path": "priority",
          "type": "code"
        },
        {
          "name": "subject_patient_id",
          "path": "subject.reference.substring(8)",
          "type": "string"
        },
        {
          "name": "encounter_id",
          "path": "encounter.reference.substring(10)",
          "type": "string"
        },
        {
          "name": "authored_on",
          "path": "authoredOn",
          "type": "dateTime"
        },
        {
          "name": "requester_practitioner_id",
          "path": "requester.reference.where($this.startsWith('Practitioner/')).substring(13).first()",
          "type": "string"
        },
        {
          "name": "code_system",
          "path": "code.coding.system.first()",
          "type": "uri"
        },
        {
          "name": "code",
          "path": "code.coding.code.first()",
          "type": "code"
        },
        {
          "name": "code_display",
          "path": "code.coding.display.first()",
          "type": "string"
        },
        {
          "name": "code_text",
          "path": "code.text",
          "type": "string"
        },
        {
          "name": "reason_code_text",
          "path": "reasonCode.text.first()",
          "type": "string"
        },
        {
          "name": "reason_reference",
          "path": "reasonReference.reference.first()",
          "type": "string"
        },
        {
          "name": "body_site_code",
          "path": "bodySite.coding.code.first()",
          "type": "code"
        },
        {
          "name": "performer_practitioner_role_id",
          "path": "performer.reference.where($this.startsWith('PractitionerRole/')).substring(17).first()",
          "type": "string"
        },
        {
          "name": "performer_related_person_id",
          "path": "performer.reference.where($this.startsWith('RelatedPerson/')).substring(14).first()",
          "type": "string"
        },
        {
          "name": "specialty_code",
          "path": "performerType.coding.code.first()",
          "type": "code"
        },
        {
          "name": "specialty_display",
          "path": "performerType.coding.display.first()",
          "type": "string"
        }
      ]
    }
  ]
}

Referral order

order.referral

ServiceRequest (category=referral, intent=plan)

Field-by-field

Side-by-side example

DSP (inferred shape)

FHIR R4 (DSP-FHIR profile)

DSP → FHIR mapping

FHIR → DSP (canonical $graphql read)

Canonical query

DSP reconstruction adapter

dsp_service_request_referral — DSP Referral (ServiceRequest)

`order.referral`

`ServiceRequest (category=referral, intent=plan)`

FHIR → DSP (canonical `$graphql` read)

`dsp_service_request_referral` — DSP Referral (ServiceRequest)