Document section

Side-by-side example

{
  "legacy_id": "hpi_2",
  "context": {
    "content_type": "document_section",
    "display_description": "HISTORY OF PRESENT ILLNESS",
    "codes": [{"system":"loinc.org","identifier":"10164-2"}],
    "spoken_forms": ["HPI","history","subjective"]
  },
  "content": "The patient is a 25-year-old male who presents for evaluation of cough, cold, fever..."
}

{
  "resourceType":"Composition",
  "status":"preliminary",
  "type":{"coding":[{"system":"http://loinc.org","code":"11506-3","display":"Progress note"}]},
  "subject":{"reference":"Patient/pat-67890"},
  "encounter":{"reference":"Encounter/enc-12345"},
  "date":"2025-06-18T14:30:00Z",
  "author":[{"reference":"Practitioner/pract-001"}],
  "title":"Progress Note",
  "section":[
    {
      "title":"HISTORY OF PRESENT ILLNESS",
      "code":{"coding":[{"system":"http://loinc.org","code":"10164-2"}]},
      "text":{
        "status":"generated",
        "div":"<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>The patient is a 25-year-old male who presents for evaluation of cough, cold, fever...</p></div>"
      },
      "extension":[
        {"url":"https://dsp-fhir.org/StructureDefinition/spoken-forms",
         "extension":[
           {"url":"form","valueString":"HPI"},
           {"url":"form","valueString":"history"},
           {"url":"form","valueString":"subjective"}
         ]},
        {"url":"https://dsp-fhir.org/StructureDefinition/legacy-id","valueString":"hpi_2"}
      ]
    },
    {
      "title":"ASSESSMENT & PLAN",
      "code":{"coding":[{"system":"http://loinc.org","code":"51847-2"}]},
      "entry":[
        {"reference":"Condition/condition-001"},
        {"reference":"MedicationRequest/med-001"},
        {"reference":"ServiceRequest/lab-001"}
      ]
    }
  ]
}

DSP → FHIR mapping

Skeleton for a single DspDocumentSection → Composition.section. In practice this map is invoked from a parent group that creates the Composition and iterates sections.

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

uses "https://dsp-fhir.org/StructureDefinition/DspDocumentSectionResource" alias DspSection as source
uses "http://hl7.org/fhir/StructureDefinition/Composition" alias Composition as target

// Each DSP document_section contributes one Composition.section.
// Typically called from a parent map that creates the Composition and iterates sections.

group DspDocumentSectionToCompositionSection(source src : DspSection, target tgt : Composition) {
  src -> tgt.section as sec then {
    src.payload as p then {
      p.title as t -> sec.title = t "title";
      p.section_type as st -> sec.code as c, c.coding as co,
        co.system = 'http://loinc.org', co.code = st "loinc-section";
      p.text as text -> sec.text as narr then {
        text -> narr.status = 'generated';
        text -> narr.div = text;   // wrap in XHTML <div> in controller
      } "narrative";
    };
    src.spoken_forms as sf -> sec.extension as ext,
      ext.url = 'https://dsp-fhir.org/StructureDefinition/dsp-spoken-forms',
      ext.value = create('string') as v, v.value = sf "spoken-forms";
  } "section";
}

FHIR → DSP (canonical $graphql read)

Each DSP document section is one entry under Composition.section. The reader pulls the parent Composition and maps every section to a DSP document_section.

Canonical query

query DspDocumentSections($id: ID!) {
  Composition(id: $id) {
    id status language
    type { coding { system code display } }
    title
    section {
      title
      code { coding { system code display } }
      text { status div }
      entry { reference }

      legacyId: extension(url: "https://dsp-fhir.org/StructureDefinition/dsp-legacy-id") {
        valueString
      }
      spokenForms: extension(url: "https://dsp-fhir.org/StructureDefinition/dsp-spoken-forms") {
        valueString
      }
      narrativeSource: extension(url: "https://dsp-fhir.org/StructureDefinition/dsp-narrative-source") {
        valueString
      }
    }
  }
}

DSP reconstruction adapter

function toDspDocumentSections(c) {
  return c.section?.map(sec => ({
    legacy_id: sec.legacyId?.[0]?.valueString,
    context: {
      content_type: 'document_section',
      display_description: sec.title,
      codes: (sec.code?.coding ?? []).map(toDspCode),
      spoken_forms: sec.spokenForms?.map(e => e.valueString) ?? [],
    },
    // Prefer the unwrapped narrative source extension over re-parsing the XHTML div
    content: sec.narrativeSource?.[0]?.valueString
          ?? unwrapXhtml(sec.text?.div),
    entries: sec.entry?.map(e => e.reference) ?? [],
  })) ?? [];
}

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.

{
  "resourceType": "ViewDefinition",
  "url": "https://dsp-fhir.org/ViewDefinition/dsp-document-section",
  "name": "dsp_document_section",
  "title": "DSP document-section",
  "status": "draft",
  "description": "Section-unnested view specifically for DSP document_section resources. Includes DSP section-type extension if carried.",
  "resource": "Composition",
  "fhirVersion": [
    "4.0.1"
  ],
  "select": [
    {
      "column": [
        {
          "name": "composition_id",
          "path": "id",
          "type": "id"
        },
        {
          "name": "encounter_id",
          "path": "encounter.reference.substring(10)",
          "type": "string"
        },
        {
          "name": "subject_patient_id",
          "path": "subject.reference.substring(8)",
          "type": "string"
        },
        {
          "name": "composition_last_updated",
          "path": "meta.lastUpdated",
          "type": "instant"
        }
      ],
      "select": [
        {
          "forEach": "section",
          "column": [
            {
              "name": "section_title",
              "path": "title",
              "type": "string"
            },
            {
              "name": "loinc_code",
              "path": "code.coding.where(system='http://loinc.org').code.first()",
              "type": "code"
            },
            {
              "name": "dsp_section_type",
              "path": "extension('https://dsp-fhir.org/StructureDefinition/dsp-section-type').value.ofType(code)",
              "type": "code"
            },
            {
              "name": "text_status",
              "path": "text.status",
              "type": "code"
            },
            {
              "name": "narrative_length_chars",
              "path": "text.div.length()",
              "type": "integer"
            },
            {
              "name": "entry_count",
              "path": "entry.count()",
              "type": "integer"
            }
          ]
        }
      ]
    }
  ]
}