DSP as a FHIR $graphql projection

The cleanest mental model for DSP: it is a shaped projection of FHIR resources associated with an encounter, plus a small sidecar envelope. FHIR's $graphql operation is the canonical way to get exactly that.

Why $graphql fits DSP almost perfectly

Conventions used by every canonical query

A canonical DSP query (R4 + DSP-FHIR IG)

The query is executed at the system level: POST [fhir-base]/$graphql with the encounter id passed as a GraphQL variable. FHIR's GraphQL binding uses *List root fields for lists and takes _reference arguments for reverse-reference searches.

The per-resource field selections (Condition, MedicationRequest, ServiceRequest, …) live on the matching resource mapping pages as the FHIR → DSP tab, so each query stays next to the field-by-field landing table it queries. The shape below is the envelope-level skeleton; substitute the per-resource fragments from each mapping page.

query DSP($encId: ID!) {
  encounter: Encounter(id: $encId) {
    id
    status
    class { code display }
    period { start end }
    subject  { resource { ... on Patient { id identifier { system value } name { given family } gender birthDate } } }
    participant {
      individual { resource { ... on Practitioner { id name { given family } identifier { system value } qualification { code { coding { system code display } } } } } }
    }
    reasonCode { coding { system code display } }

    # DSP envelope extensions (defined by the DSP-FHIR IG)
    payloadVersion: extension(url: "https://dsp-fhir.org/StructureDefinition/payload-version") {
      major:    extension(url: "major")    { valueInteger }
      minor:    extension(url: "minor")    { valueInteger }
      revision: extension(url: "revision") { valueInteger }
      quality:  extension(url: "quality")  { valueCode }
    }
    callbackUrl: extension(url: "https://dsp-fhir.org/StructureDefinition/external-callback-url") { valueUrl }
  }

  # Resource lists — one root field per DSP content_type. The selection set for each list
  # is the canonical query published on its mapping page.
  conditions:   ConditionList(encounter: $encId)        { id }   # see /mapping/condition
  medications:  MedicationRequestList(encounter: $encId){ id }   # see /mapping/medication
  services:     ServiceRequestList(encounter: $encId)   { id }   # see /mapping/lab|imaging|procedure|referral|follow-up|therapy|study
  nutrition:    NutritionOrderList(encounter: $encId)   { id }   # see /mapping/dietary
  immunizations: ImmunizationList(encounter: $encId)    { id }   # see /mapping/immunization
  devices:      DeviceRequestList(encounter: $encId)    { id }   # see /mapping/device
  carePlans:    CarePlanList(encounter: $encId)         { id }   # see /mapping/activity
  compositions: CompositionList(encounter: $encId)      { id }   # see /mapping/document-section

  transcripts: DocumentReferenceList(encounter: $encId, category: "https://dsp-fhir.org/CodeSystem/doc-category|transcript") {
    id status type { coding { code display } }
    content { attachment { url contentType language } }
    context { period { start end } }
    speakerCount: extension(url: "https://dsp-fhir.org/StructureDefinition/speaker-count") { valuePositiveInt }
  }
}

What the response looks like

One HTTP call, one JSON document, grouped by resource type — the same polymorphic grouping DSP's resources[] uses. Per-resource field landings (which native FHIR field or dsp-* extension a DSP value lives in) are documented on each mapping page's field-by-field table.

Fallbacks (when $graphql isn't available)

Before going to REST _include, try Encounter/$everything — one call, widely implemented, returns a Bundle of the encounter and its referenced resources:

GET [fhir-base]/Encounter/{id}/$everything

It's coarser than the canonical $graphql query (no field shaping, no filter on DocumentReference category) but it beats six round-trips. If even $everything isn't available:

REST _include fan-out

$graphql is an optional FHIR operation. Many production servers don't expose it. The DSP-FHIR IG defines two layered fallbacks, in preference order. Prior art for the whole "canonical projection" pattern is IPS Patient/$summary — DSP's canonical query is morally the same shape scoped to an encounter.

GET  [fhir-base]/Encounter/{id}?_include=Encounter:subject
                               &_include=Encounter:participant
                               &_include=Encounter:location
GET  [fhir-base]/Condition?encounter={id}
GET  [fhir-base]/MedicationRequest?encounter={id}
GET  [fhir-base]/ServiceRequest?encounter={id}
GET  [fhir-base]/Composition?encounter={id}&_include=Composition:section:entry
GET  [fhir-base]/DocumentReference?encounter={id}
                                  &category=https://dsp-fhir.org/CodeSystem/doc-category|transcript

Six REST calls versus one GraphQL call. The IG publishes both shapes so implementers pick based on their server. DSP's projection shape is the same either way.

What $graphql does not solve on its own