DSP-FHIR IG — outline

Download the draft IG package

Full source tree — sushi-config, FSH (profiles, extensions, logical models, value sets), all DSP ↔ FHIR FML mapping skeletons, CapabilityStatement, OperationDefinition, narrative pages, and a worked example Bundle. Ready to run through sushi + the HL7 IG Publisher.

⬇ dsp-fhir-ig.zip (draft v0.1.0)

Draft / exploratory. Not an HL7 ballot artifact. Not affiliated with Microsoft or Nuance. Released under CC0.

DSP is modelled as FHIR StructureDefinition(kind=logical) — DspPayload, DspContext, DspTranscript, DspResource, and per-content_type submodels (DspConditionResource, DspOrderMedicationResource, DspOrderImagingResource, etc.). This makes DSP FHIR-native enough that $validate works on incoming DSP, and gives FML maps a typed source.

The draft ships executable FHIR Mapping Language skeletons for every resource mapping in both directions. Forward maps live under input/maps/dsp-to-fhir/; reverse reconstruction maps live under input/maps/fhir-to-dsp/. Partners compile with sushi or the FML compiler and execute via StructureMap/$transform on matchbox / HAPI — no bespoke per-partner converter needed.

The IG download also includes all resource profile definitions in input/fsh/profiles.fsh plus a profile catalog at input/profiles/README.md. Grounding state (R1) remains controller logic rather than FML.

• Read: canonical $graphql query published as an IG artifact (see graphql), with Encounter/$everything and REST _include as documented fallbacks. IPS Patient/$summary is the spiritual ancestor of the canonical query — adopters should read both.
• Write: transaction Bundle at POST [fhir-base]; entries carry ifMatch for optimistic concurrency and Provenance. $validate (against IG profiles) SHOULD be run pre-commit.
• Standard ops the IG relies on: $validate, Encounter/$everything, CodeSystem/$lookup, ValueSet/$expand, PlanDefinition/$apply / ActivityDefinition/$apply, Patient/$match (and IG-profiled RelatedPerson/$match), Composition/$document, US Core $docref, Bulk Data $export?_since=. See operations for the full audit and worked examples.
• Push: SubscriptionTopic (R4B/R5) https://dsp-fhir.org/SubscriptionTopic/dsp-ready triggers on encounter finalization; payload URL fires the canonical query. Use Subscription R5 Backport $events / $status for replay and liveness.
• Callbacks: external_callback_url is the partner-supplied endpoint. The DSP spec does not prescribe an auth scheme; the IG recommends SMART on FHIR Backend Services (client-credentials with a signed JWT), mirroring Bulk Data conventions.
• Custom operations: only one — $ground (transcript turn-join). Everything else previously drafted as a custom op resolved to an existing FHIR or IG operation. See operations.

R1 · Transcript turn-index stability

Turn indices SHALL be immutable within a DocumentReference.meta.versionId of the transcript. A re-transcription (correction, alternate model, redaction) SHALL create a new version of the DocumentReference. Any clinical resource carrying transcript-turn-refs SHALL either (a) reference the specific transcript version (DocumentReference/xyz/_history/3), or (b) be re-emitted with updated indices against the new transcript version.

Why: without this rule, integer turn-refs can silently point to different content after a transcript revision. Grounding becomes unprovable. This is the only DSP semantic that cannot survive naively.

R2 · Recording content binding

Recordings SHALL be served from a FHIR Binary endpoint on the same server that issued the Media / DocumentReference resource, and that endpoint SHALL enforce SMART on FHIR scopes appropriate to the recording's patient compartment. External signed URLs (e.g. CDN hand-offs) are permitted only via a server-issued redirect that validates the caller's token first.

Why: PHI-bearing audio sitting behind a stable public URL is a data breach waiting to happen. The rule keeps recording access within the auth boundary the rest of the resources already live in.

R3 · Payload-version negotiation

Servers SHALL advertise accepted and emitted DSP payload-version values in CapabilityStatement via the dsp-payload-versions extension on CapabilityStatement.rest. Servers SHALL NOT auto-upgrade a payload's version on read; clients ask for a specific version or accept the server default. On write, servers SHALL reject with 422 if the declared payload-version isn't in the accepted set.

Why: DSP will evolve. Silent version coercion is the fastest way to break partners in production.

R4 · Provenance per ingest

Every $dsp-ingest (or equivalent transaction) SHALL produce at least one Provenance resource whose target lists every clinical resource created or updated, and whose entity references the source transcript DocumentReference (and recording, if present). This is the traceability substrate DSP already assumes.