Inera Core Implementation Guide
0.2.0 - ci-build Sweden

Inera Core Implementation Guide - Local Development build (v0.2.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

DocBook to FHIR Narrative Transformation Guide

DocBook to FHIR Narrative Guide

Overview

This guide describes how to transform DocBook-formatted messages (1177 Inkorg and other Inera services) into FHIR Composition or DocumentReference resources with proper Narrative content.

Source Format: DocBook XML (subset supported by 1177 Inkorg)
Target Format: FHIR Narrative.div (restricted XHTML subset)

Key Decisions:

  1. Composition.text (Narrative) vs Composition.section for structure
  2. Inline formatting in XHTML vs semantic sections with coded entries
  3. Visual fidelity (boxes, colors) vs portable structured data

DocBook Subset Used by 1177 Inkorg

The 1177 Inkorg service uses a specific subset of DocBook for formatted patient messages. See ConceptMap: DocBook to Narrative for detailed element mappings.

Supported Elements:

DocBook Element Purpose 1177 Usage Example
article Document root Wrapper for entire message
section Logical section Groups related content (appointment details, instructions)
title Heading Section titles, can include emphasis[@role] for styled boxes
para Paragraph Text blocks
emphasis[@role] Styled content bold, italics, underline, collapsible, information, observe, frame
ulink, link Hyperlinks External links (1177.se) and internal anchors
itemizedlist Bulleted list Instructions, checklists with @mark='bullet' or 'hyphen'
variablelist Key-value pairs Appointment details (Datum: / Tisdag 10 mars 2022)
bibliography References Links to external resources

DocBook Roles in 1177 Inkorg (via emphasis[@role]):

Role Visual Presentation FHIR Mapping
bold Bold text <strong> or <b>
italics Italic text <em> or <i>
underline Underlined text <u> or <span style='text-decoration:underline'>
collapsible Expandable section with ▶ icon <div class='collapsible'> (requires custom JS)
information Gray box with heading (Viktigt inför ditt besök) <div class='info-box'> with CSS
observe Yellow box with heading (Tänk på) <div class='warning-box'> with CSS
frame White bordered box <div class='framed-box'> with CSS

FHIR Narrative Constraints

FHIR Narrative uses a restricted subset of XHTML 1.0 Strict:

Allowed Tags: div, span, p, h1-h6, a, ul, ol, li, dl, dt, dd, table, tr, td, th, b, i, u, em, strong, br

Not Allowed: DocBook-specific elements (article, section, emphasis), interactive elements (<details>, <button>), <img> without data URI

Root Element: All Narrative content must be in a single <div xmlns='http://www.w3.org/1999/xhtml'>

Reference: FHIR Narrative Data Type


Strategy 1: Composition.text (Narrative-Only)

Use Composition.text with XHTML Narrative when:

  • Message is primarily presentational (appointment reminders, informational letters)
  • No structured data extraction needed
  • Visual fidelity to 1177 Inkorg appearance is important
  • Simple transformation from DocBook to XHTML

Example 1: Screening Invitation with Narrative (Patient Administrative)

DocBook Source (1177 Inkorg - Screening Invitation):

<?xml version="1.0"?>
<article>
  <section>
    <title>Kallelse till cellprovtagning</title>
    <para>Du kallas nu till cellprovtagning (gynekologisk cellprovskontroll). Alla kvinnor mellan 23-64 år i Region Stockholm erbjuds regelbunden cellprovtagning.</para>
  </section>
  <section>
    <variablelist>
      <varlistentry>
        <term>Datum:</term>
        <listitem>Tisdag 15 april 2025</listitem>
      </varlistentry>
      <varlistentry>
        <term>Tid:</term>
        <listitem>Kl. 10:00</listitem>
      </varlistentry>
      <varlistentry>
        <term>Mottagning:</term>
        <listitem>Barnmorskemottagningen Täby Centrum, Entrance B, plan 2</listitem>
      </varlistentry>
      <varlistentry>
        <term>Adress:</term>
        <listitem>Täby Torg 3, 187 66 Täby</listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section>
    <title><emphasis role="collapsible">Därför är du kallad till cellprovtagning</emphasis></title>
    <para>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen. Cellprovet kan upptäcka tidiga cellförändringar som behandlas innan de hinner bli cancer.</para>
  </section>
  <section>
    <title><emphasis role="information">Viktig information</emphasis></title>
    <itemizedlist mark="bullet">
      <listitem>Ta inte cellprov om du har mens - boka om tiden.</listitem>
      <listitem>Du behöver inte förbereda dig på något särskilt sätt.</listitem>
      <listitem>Ta gärna med en lista på eventuella mediciner du tar.</listitem>
    </itemizedlist>
  </section>
  <section>
    <title><emphasis role="observe">Om du inte kan komma</emphasis></title>
    <para>Kontakta mottagningen senast 24 timmar innan din tid. Ring <ulink url="tel:08-123456" type="_self">08-123 456</ulink> eller boka om via 1177.se.</para>
  </section>
</article>

FHIR Composition with Narrative:

{
  "resourceType": "Composition",
  "id": "screening-invitation-20250415",
  "status": "final",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "57024-2",
      "display": "Health Quality Measure Document"
    }]
  },
  "category": [{
    "coding": [{
      "system": "https://inera.se/fhir/core/CodeSystem/composition-category",
      "code": "screening-invitation",
      "display": "Screening Invitation"
    }]
  }],
  "subject": {
    "reference": "Patient/191212121212"
  },
  "date": "2025-03-15T10:00:00+01:00",
  "author": [{
    "reference": "Organization/region-stockholm-screening"
  }],
  "title": "Kallelse till cellprovtagning",
  "text": {
    "status": "generated",
    "div": "<div xmlns='http://www.w3.org/1999/xhtml'><div class='section'><h2>Kallelse till cellprovtagning</h2><p>Du kallas nu till cellprovtagning (gynekologisk cellprovskontroll). Alla kvinnor mellan 23-64 år i Region Stockholm erbjuds regelbunden cellprovtagning.</p></div><div class='section'><dl><dt>Datum:</dt><dd>Tisdag 15 april 2025</dd><dt>Tid:</dt><dd>Kl. 10:00</dd><dt>Mottagning:</dt><dd>Barnmorskemottagningen Täby Centrum, Entrance B, plan 2</dd><dt>Adress:</dt><dd>Täby Torg 3, 187 66 Täby</dd></dl></div><div class='collapsible'><h3>▶ Därför är du kallad till cellprovtagning</h3><p>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen. Cellprovet kan upptäcka tidiga cellförändringar som behandlas innan de hinner bli cancer.</p></div><div class='info-box'><h3>Viktig information</h3><ul><li>Ta inte cellprov om du har mens - boka om tiden.</li><li>Du behöver inte förbereda dig på något särskilt sätt.</li><li>Ta gärna med en lista på eventuella mediciner du tar.</li></ul></div><div class='warning-box'><h3>Om du inte kan komma</h3><p>Kontakta mottagningen senast 24 timmar innan din tid. Ring <a href='tel:08-123456'>08-123 456</a> eller boka om via 1177.se.</p></div></div>"
  }
}

Formatted XHTML (for readability, actual Narrative is single-line):

<div xmlns='http://www.w3.org/1999/xhtml'>
  <div class='section'>
    <h2>Kallelse till cellprovtagning</h2>
    <p>Du kallas nu till cellprovtagning (gynekologisk cellprovskontroll). 
    Alla kvinnor mellan 23-64 år i Region Stockholm erbjuds regelbunden cellprovtagning.</p>
  </div>
  
  <div class='section'>
    <dl>
      <dt>Datum:</dt>
      <dd>Tisdag 15 april 2025</dd>
      <dt>Tid:</dt>
      <dd>Kl. 10:00</dd>
      <dt>Mottagning:</dt>
      <dd>Barnmorskemottagningen Täby Centrum, Entrance B, plan 2</dd>
      <dt>Adress:</dt>
      <dd>Täby Torg 3, 187 66 Täby</dd>
    </dl>
  </div>
  
  <div class='collapsible'>
    <h3>▶ Därför är du kallad till cellprovtagning</h3>
    <p>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen. 
    Cellprovet kan upptäcka tidiga cellförändringar som behandlas innan de hinner bli cancer.</p>
  </div>
  
  <div class='info-box'>
    <h3>Viktig information</h3>
    <ul>
      <li>Ta inte cellprov om du har mens - boka om tiden.</li>
      <li>Du behöver inte förbereda dig på något särskilt sätt.</li>
      <li>Ta gärna med en lista på eventuella mediciner du tar.</li>
    </ul>
  </div>
  
  <div class='warning-box'>
    <h3>Om du inte kan komma</h3>
    <p>Kontakta mottagningen senast 24 timmar innan din tid. 
    Ring <a href='tel:08-123456'>08-123 456</a> eller boka om via 1177.se.</p>
  </div>
</div>

CSS for 1177 Styling (optional, provided separately):

.info-box {
  background-color: #f0f0f0;
  border: 1px solid #ccc;
  padding: 1em;
  margin: 1em 0;
}

.warning-box {
  background-color: #fff3cd;
  border: 1px solid #ffc107;
  padding: 1em;
  margin: 1em 0;
}

.framed-box {
  border: 2px solid #000;
  padding: 1em;
  margin: 1em 0;
}

.collapsible h3::before {
  content: '▶ ';
  cursor: pointer;
}

.collapsible.expanded h3::before {
  content: '▼ ';
}

Transformation Rules (DocBook → Narrative XHTML)

DocBook Pattern FHIR Narrative XHTML Notes
<article> <div xmlns='http://www.w3.org/1999/xhtml'> Root wrapper
<section> <div class='section'> or omit Group related content
<title> <h2>, <h3>, etc. Heading level based on nesting
<para> <p> Direct mapping
<emphasis role='bold'> <strong> or <b> Semantic vs visual
<emphasis role='italics'> <em> or <i> Semantic vs visual
<emphasis role='underline'> <u> XHTML 1.0 Strict allows <u>
<emphasis role='information'> <div class='info-box'><h3>Title</h3>... Gray box (requires CSS)
<emphasis role='observe'> <div class='warning-box'><h3>Title</h3>... Yellow box (requires CSS)
<emphasis role='frame'> <div class='framed-box'><h3>Title</h3>... White bordered box
<emphasis role='collapsible'> <div class='collapsible'><h3>Title</h3>... Requires JavaScript
<ulink url='...' type='_blank'> <a href='...' target='_blank'> External links
<link url='#id'> <a href='#id'> Internal anchor links
<itemizedlist mark='bullet'> <ul> Unordered list
<itemizedlist mark='hyphen'> <ul class='hyphen'> CSS for hyphen markers
<listitem> <li> List item
<variablelist> <dl> Definition list
<varlistentry> <dt> + <dd> pair Term and definition
<term> <dt> Definition term
<listitem> (in variablelist) <dd> Definition description

Strategy 2: Composition.section (Structured Sections)

Use Composition.section when:

  • Message has clear logical sections (appointment details, instructions, references)
  • Structured data extraction needed (dates, locations, medications)
  • Interoperability and machine-readability important
  • Mix of narrative and coded entries

Example 2: Appointment Confirmation with Structured Sections (Patient Administrative)

{
  "resourceType": "Composition",
  "id": "appointment-structured-20220310",
  "status": "final",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "57133-1",
      "display": "Referral note"
    }]
  },
  "subject": {
    "reference": "Patient/191212121212"
  },
  "date": "2022-03-01T10:00:00+01:00",
  "author": [{
    "reference": "Organization/soderby-vardcentral"
  }],
  "title": "Bokad tid - Söderby Vårdcentral",
  
  "section": [
    {
      "title": "Välkommen till Söderby Vårdcentral",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "48765-2",
          "display": "Allergies and adverse reactions"
        }]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Vi har bokat tid till dig hos Anton Andersson, läkare, för undersökning.</p></div>"
      }
    },
    {
      "title": "Bokningsdetaljer",
      "code": {
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "184644006",
          "display": "Appointment details"
        }]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><dl><dt>Datum:</dt><dd>Tisdag 10 mars 2022</dd><dt>Klockan:</dt><dd>11.00</dd><dt>Plats:</dt><dd>Sandstigen 15, Söderby Våningsplan 5</dd></dl></div>"
      },
      "entry": [{
        "reference": "Appointment/appointment-20220310-1100"
      }]
    },
    {
      "title": "Viktigt inför ditt besök",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "69730-0",
          "display": "Instructions"
        }]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml' class='info-box'><ul><li>Covid-19: För att undvika smittspridning är det viktigt att du stannar hemma även vid lindriga förkylningssymptom.</li><li>Utför inte kraftig fysisk aktivitet eller tungt arbete innan besöket.</li><li>Kontakta oss före besöket om du får förhinder.</li></ul></div>"
      }
    }
  ]
}

Benefits of Composition.section

Aspect Narrative-Only With Sections
Searchability Full-text search only Search by section.code, filter by section type
Structured Data Embedded in XHTML, hard to extract section.entry references Appointment, Medication, etc.
Extensibility Add new sections in text Add new Composition.section with code
Rendering Single block of XHTML Applications can show/hide sections, reorder
Interoperability Human-readable only Machine-readable section codes (LOINC, SNOMED)

Composition.text vs Composition.section: Decision Guide

Use Composition.text (Narrative-Only) when:

Message is informational (appointment reminder, test result notification)
No structured data needed (no Appointment, Observation, Medication references)
Visual fidelity important (1177 Inkorg styled boxes must be preserved)
Simple transformation (direct DocBook → XHTML mapping)
Read-only content (patient views message, no clinical actions)

Example Use Cases:

  • Appointment reminders with instructions
  • General health information letters
  • Referral confirmations
  • Administrative notifications

Use Composition.section when:

Logical document structure (appointment details, medication list, test results)
Structured data extraction (reference Appointment, Medication, Observation)
Interoperability requirements (share with other systems, NPÖ integration)
Machine-readable sections (coded section.code for filtering, search)
Clinical workflow integration (trigger alerts, add to problem list)

Example Use Cases:

  • Discharge summaries with medication changes
  • Referrals with clinical details and attachments
  • Test results with observations and interpretations
  • Care plans with goals and interventions

Example 3: Clinical Note as Narrative Text

For clinical documentation that originates as structured text (e.g., SOAP notes, progress notes), use Composition.section with rich narrative while referencing structured observations.

Use Case: Progress note from primary care visit documenting patient's diabetes management.

{
  "resourceType": "Composition",
  "id": "progress-note-diabetes-20251209",
  "status": "final",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "11506-3",
      "display": "Progress note"
    }]
  },
  "category": [{
    "coding": [{
      "system": "http://loinc.org",
      "code": "LP173421-1",
      "display": "Report"
    }]
  }],
  "subject": {
    "reference": "Patient/191212121212"
  },
  "encounter": {
    "reference": "Encounter/encounter-20251209"
  },
  "date": "2025-12-09T14:30:00+01:00",
  "author": [{
    "reference": "Practitioner/dr-andersson"
  }],
  "title": "Återbesök - Diabetes typ 2",
  
  "section": [
    {
      "title": "Subjektiv bedömning (S)",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "61150-9",
          "display": "Subjective Narrative"
        }]
      },
      "text": {
        "status": "additional",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Patienten kommer för <strong>uppföljning av diabetes typ 2</strong>. Mår <em>generellt bra</em>, men rapporterar trötthet på eftermiddagarna. Följer kostråd och promenerar 30 min dagligen. Glömt Metformin ca 2-3 gånger senaste månaden.</p><p><u>Ingen hypoglykemi</u> rapporterad. Inga nya symtom. Sömn och aptit normal.</p></div>"
      }
    },
    {
      "title": "Objektiv bedömning (O)",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "61149-1",
          "display": "Objective Narrative"
        }]
      },
      "text": {
        "status": "generated",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><dl><dt>Vikt:</dt><dd>78 kg (föregående 80 kg)</dd><dt>BMI:</dt><dd>26.5</dd><dt>Blodtryck:</dt><dd>135/85 mmHg</dd><dt>HbA1c:</dt><dd>52 mmol/mol (föregående 58 mmol/mol)</dd></dl><p>Status: Inga fotsår. Perifera pulsar palpabla bilateralt. Sensibilitet intakt.</p></div>"
      },
      "entry": [
        {"reference": "Observation/weight-20251209"},
        {"reference": "Observation/bp-20251209"},
        {"reference": "Observation/hba1c-20251209"}
      ]
    },
    {
      "title": "Bedömning (A)",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "51848-0",
          "display": "Assessment Narrative"
        }]
      },
      "text": {
        "status": "additional",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p><strong>Diabetes typ 2 i förbättring</strong>. HbA1c har sjunkit från 58 till 52 mmol/mol - <em>mycket bra utveckling</em>. Viktminskning 2 kg sedan förra besöket. Fortsatt lätt förhöjt blodtryck (målvärde &lt;130/80).</p><div class='info-box'><h4>Behandlingsmål</h4><ul><li>HbA1c &lt;52 mmol/mol - <strong>uppnått</strong> ✓</li><li>Blodtryck &lt;130/80 - ej uppnått, följs</li><li>Viktminskning 5 kg - pågår (2/5 kg)</li></ul></div></div>"
      },
      "entry": [
        {"reference": "Condition/diabetes-type2"}
      ]
    },
    {
      "title": "Åtgärd/Plan (P)",
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "18776-5",
          "display": "Plan of care note"
        }]
      },
      "text": {
        "status": "additional",
        "div": "<div xmlns='http://www.w3.org/1999/xhtml'><ol><li><strong>Fortsätt nuvarande medicinering</strong>: Metformin 500mg x2. Påmind om vikten av regelbunden dos.</li><li><strong>Kostråd upprepade</strong>: Minska kolhydrater på kvällen för att motverka eftermiddagströtthet.</li><li><strong>Blodtrycksuppföljning</strong>: Hemblodtrycksmätning 2 ggr/dag i 1 vecka, rapportera via 1177.</li><li><strong>Återbesök om 3 månader</strong> för HbA1c-kontroll och blodtrycksutvärdering.</li></ol><div class='warning-box'><h4>Observera</h4><p>Vid symtom på hypoglykemi (svettning, skakighet, yrsel): Ta snabbt kolhydrat (juice/druvsocker) och kontakta vården.</p></div></div>"
      },
      "entry": [
        {"reference": "MedicationStatement/metformin"},
        {"reference": "CarePlan/diabetes-management"}
      ]
    }
  ]
}

Key Features for Clinical Notes:

  1. text.status = "additional": Narrative contains additional information beyond structured data
  2. Inline formatting: Use <strong>, <em>, <u> for emphasis within paragraphs
  3. Structured lists: Use <ol>, <ul>, <dl> for plans, observations, key-value pairs
  4. Mixed content: Combine narrative text with references to Observation, Condition, MedicationStatement
  5. Visual emphasis boxes: Use .info-box for treatment goals, .warning-box for important safety information

Hybrid Approach: Sections with Rich Narrative

Combine both strategies:

  • Composition.section for structure and coded entries
  • section.text (Narrative) for rich formatting within each section
  • section.entry for references to structured resources
{
  "section": [{
    "title": "Viktigt inför ditt besök",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "69730-0",
        "display": "Instructions"
      }]
    },
    "text": {
      "status": "generated",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml' class='info-box'><h3>Viktigt inför ditt besök</h3><ul><li>Covid-19: För att undvika smittspridning är det viktigt att du stannar hemma även vid lindriga förkylningssymptom.</li><li>Utför inte kraftig fysisk aktivitet eller tungt arbete innan besöket.</li></ul></div>"
    },
    "entry": [{
      "reference": "DocumentReference/covid-instructions"
    }]
  }]
}

Handling DocBook Special Cases

Collapsible Sections (emphasis[@role='collapsible'])

DocBook:

<section>
  <title><emphasis role="collapsible">Därför är du kallad till cellprovtagning</emphasis></title>
  <para>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen...</para>
</section>

Option 1: Static Expanded (simple, always visible):

<div xmlns='http://www.w3.org/1999/xhtml'>
  <h3>Därför är du kallad till cellprovtagning</h3>
  <p>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen...</p>
</div>

Option 2: Collapsible with JavaScript (requires custom rendering):

<div xmlns='http://www.w3.org/1999/xhtml'>
  <div class='collapsible'>
    <h3 onclick='toggleSection(this)'>▶ Därför är du kallad till cellprovtagning</h3>
    <div class='content' style='display:none'>
      <p>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen...</p>
    </div>
  </div>
</div>

Option 3: Separate Section (FHIR-native):

{
  "section": [{
    "title": "Därför är du kallad till cellprovtagning",
    "text": {
      "status": "generated",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Regelbunden cellprovtagning ger ett starkt skydd mot cancer i livmoderhalsen...</p></div>"
    },
    "emptyReason": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/list-empty-reason",
        "code": "withheld",
        "display": "Information Withheld (initially collapsed)"
      }]
    }
  }]
}

Information Boxes (emphasis[@role='information/observe/frame'])

DocBook:

<section>
  <title><emphasis role="information">Viktigt inför ditt besök</emphasis></title>
  <itemizedlist mark="bullet">
    <listitem>Covid-19: ...</listitem>
  </itemizedlist>
</section>

FHIR Narrative (with CSS classes):

<div xmlns='http://www.w3.org/1999/xhtml'>
  <div class='info-box'>
    <h3>Viktigt inför ditt besök</h3>
    <ul>
      <li>Covid-19: ...</li>
    </ul>
  </div>
</div>

Alternative: Semantic Section Codes:

{
  "section": [{
    "title": "Viktigt inför ditt besök",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "69730-0",
        "display": "Instructions"
      }]
    },
    "extension": [{
      "url": "https://inera.se/fhir/core/StructureDefinition/section-style",
      "valueCodeableConcept": {
        "coding": [{
          "system": "https://inera.se/fhir/core/CodeSystem/section-style",
          "code": "information-box",
          "display": "Information Box (Gray)"
        }]
      }
    }],
    "text": {
      "status": "generated",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml'><ul><li>Covid-19: ...</li></ul></div>"
    }
  }]
}

Variable Lists (Key-Value Pairs)

DocBook:

<variablelist>
  <varlistentry>
    <term>Datum:</term>
    <listitem>Tisdag 10 mars 2022</listitem>
  </varlistentry>
  <varlistentry>
    <term>Klockan:</term>
    <listitem>11.00</listitem>
  </varlistentry>
</variablelist>

FHIR Narrative (definition list):

<div xmlns='http://www.w3.org/1999/xhtml'>
  <dl>
    <dt>Datum:</dt>
    <dd>Tisdag 10 mars 2022</dd>
    <dt>Klockan:</dt>
    <dd>11.00</dd>
  </dl>
</div>

Alternative: Table:

<div xmlns='http://www.w3.org/1999/xhtml'>
  <table>
    <tr><td><strong>Datum:</strong></td><td>Tisdag 10 mars 2022</td></tr>
    <tr><td><strong>Klockan:</strong></td><td>11.00</td></tr>
  </table>
</div>

DocBook emphasis[@role] Mapping Strategies

The DocBook emphasis element with @role attribute serves dual purposes in 1177 Inkorg:

  1. Pure formatting (bold, italics, underline) - visual styling of text
  2. Semantic styling (information, observe, frame, collapsible) - visual markers with meaning

FHIR offers two approaches for mapping these roles:

Strategy A: Direct XHTML Formatting (Presentation-Focused)

Map DocBook roles directly to XHTML tags and CSS classes within Narrative.div.

Pros:

  • Simple, direct transformation
  • Preserves exact visual appearance from 1177 Inkorg
  • Works well for read-only patient messages
  • No need for custom extensions or code systems

Cons:

  • Loses semantic meaning (e.g., "this is a warning" vs "this is yellow text")
  • Hard to query (can't search for "all warnings" without parsing HTML)
  • Rendering depends on CSS being available
  • Not portable across systems with different styling

Formatting Roles → XHTML Tags

DocBook Role XHTML Mapping Semantic Meaning Notes
emphasis[@role='bold'] <strong> or <b> Strong emphasis Prefer <strong> for semantic, <b> for visual-only
emphasis[@role='italics'] <em> or <i> Emphasis Prefer <em> for semantic, <i> for visual-only
emphasis[@role='underline'] <u> Unarticulated annotation Valid in XHTML 1.0 Strict, represents underline
para with emphasis[@role='bold'] inside <p><strong>text</strong></p> Inline emphasis For emphasis within paragraph

Example:

<!-- DocBook -->
<para>Patienten rapporterar <emphasis role="bold">måttlig smärta</emphasis> och 
<emphasis role="italics">lätt yrsel</emphasis> efter behandling.</para>
<!-- FHIR Narrative XHTML -->
<p>Patienten rapporterar <strong>måttlig smärta</strong> och 
<em>lätt yrsel</em> efter behandling.</p>

Semantic Roles → CSS Classes + div

For semantic roles that indicate type of content (information box, warning, collapsible), map to <div> with CSS class.

DocBook Role XHTML Mapping CSS Class Visual Style Semantic Meaning
title/emphasis[@role='information'] <div class='info-box'><h3>Title</h3>...</div> .info-box Gray background, ℹ️ icon Informational content, important but not urgent
title/emphasis[@role='observe'] <div class='warning-box'><h3>Title</h3>...</div> .warning-box Yellow background, ⚠️ icon Warning/caution, requires attention
title/emphasis[@role='frame'] <div class='framed-box'><h3>Title</h3>...</div> .framed-box White background, border Distinct content, no urgency implication
title/emphasis[@role='collapsible'] <div class='collapsible'><h3>▶ Title</h3>...</div> .collapsible Expandable, initially collapsed Optional/supplementary information
emphasis[@role='bgcolor'] <span style='background-color:#color'> N/A Custom background color Highlight specific text

Example:

<!-- DocBook -->
<section>
  <title><emphasis role="information">Viktigt inför ditt besök</emphasis></title>
  <itemizedlist mark="bullet">
    <listitem>Ta inte cellprov om du har mens.</listitem>
    <listitem>Du behöver inte förbereda dig på något särskilt sätt.</listitem>
  </itemizedlist>
</section>
<!-- FHIR Narrative XHTML with CSS class -->
<div class='info-box'>
  <h3>Viktigt inför ditt besök</h3>
  <ul>
    <li>Ta inte cellprov om du har mens.</li>
    <li>Du behöver inte förbereda dig på något särskilt sätt.</li>
  </ul>
</div>

Required CSS (provided separately, not in FHIR resource):

.info-box {
  background-color: #f0f0f0;
  border-left: 4px solid #0066cc;
  padding: 1em;
  margin: 1em 0;
}

.info-box::before {
  content: 'ℹ️ ';
}

.warning-box {
  background-color: #fff3cd;
  border-left: 4px solid #ffc107;
  padding: 1em;
  margin: 1em 0;
}

.warning-box::before {
  content: '⚠️ ';
}

.framed-box {
  border: 2px solid #333;
  padding: 1em;
  margin: 1em 0;
}

.collapsible h3 {
  cursor: pointer;
  user-select: none;
}

.collapsible h3::before {
  content: '▶ ';
  display: inline-block;
  transition: transform 0.3s;
}

.collapsible.expanded h3::before {
  transform: rotate(90deg);
}

.collapsible .content {
  display: none;
}

.collapsible.expanded .content {
  display: block;
}

Strategy B: Semantic Composition.section Codes (Data-Focused)

Map DocBook semantic roles to Composition.section.code and optional section.extension for visual styling hints.

Pros:

  • Preserves semantic meaning independent of presentation
  • Queryable (search for all "warning" sections using section.code)
  • Portable across systems (rendering can adapt to local UI)
  • Supports accessibility (screen readers can announce "Warning section")
  • Structured data integration (link warnings to CarePlan, alerts)

Cons:

  • More complex transformation (need to create sections, assign codes)
  • Requires defining custom CodeSystem for section styles (or use extensions)
  • Visual rendering less predictable (depends on client implementation)
  • May not match 1177 Inkorg appearance exactly

Semantic Roles → section.code

Define a custom CodeSystem for section semantic types:

CodeSystem: https://inera.se/fhir/core/CodeSystem/section-semantic-type

Code Display Definition Corresponds to DocBook
information Information Informational content requiring attention emphasis[@role='information']
warning Warning Cautionary information requiring careful attention emphasis[@role='observe']
notice Notice Framed or highlighted content without urgency emphasis[@role='frame']
supplementary Supplementary Optional/collapsible content emphasis[@role='collapsible']

Extension for Visual Styling Hints

Extension: https://inera.se/fhir/core/StructureDefinition/section-presentation-style

Provides rendering hints without dictating exact appearance.

ValueSet: section-presentation-style

  • info-box - Gray background, info icon
  • warning-box - Yellow background, warning icon
  • framed-box - Border, no color
  • collapsible - Initially collapsed, expandable

Example: Information Box as Semantic Section

DocBook:

<section>
  <title><emphasis role="information">Viktigt inför ditt besök</emphasis></title>
  <itemizedlist mark="bullet">
    <listitem>Ta inte cellprov om du har mens - boka om tiden.</listitem>
    <listitem>Du behöver inte förbereda dig på något särskilt sätt.</listitem>
  </itemizedlist>
</section>

FHIR Composition with Semantic Section:

{
  "section": [{
    "title": "Viktigt inför ditt besök",
    "code": {
      "coding": [{
        "system": "https://inera.se/fhir/core/CodeSystem/section-semantic-type",
        "code": "information",
        "display": "Information"
      }]
    },
    "extension": [{
      "url": "https://inera.se/fhir/core/StructureDefinition/section-presentation-style",
      "valueCodeableConcept": {
        "coding": [{
          "system": "https://inera.se/fhir/core/CodeSystem/section-presentation-style",
          "code": "info-box",
          "display": "Information Box"
        }]
      }
    }],
    "text": {
      "status": "generated",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml'><ul><li>Ta inte cellprov om du har mens - boka om tiden.</li><li>Du behöver inte förbereda dig på något särskilt sätt.</li></ul></div>"
    }
  }]
}

Benefits:

  • Can query: Composition?section-code=information to find all informational sections
  • Client decides rendering: Web UI → gray box, Mobile app → blue header, Screen reader → "Information section"
  • Future-proof: New clients can render appropriately without CSS dependency

Example: Warning Box as Semantic Section

DocBook:

<section>
  <title><emphasis role="observe">Om du inte kan komma</emphasis></title>
  <para>Kontakta mottagningen senast 24 timmar innan din tid.</para>
</section>

FHIR Composition:

{
  "section": [{
    "title": "Om du inte kan komma",
    "code": {
      "coding": [{
        "system": "https://inera.se/fhir/core/CodeSystem/section-semantic-type",
        "code": "warning",
        "display": "Warning"
      }]
    },
    "extension": [{
      "url": "https://inera.se/fhir/core/StructureDefinition/section-presentation-style",
      "valueCodeableConcept": {
        "coding": [{
          "system": "https://inera.se/fhir/core/CodeSystem/section-presentation-style",
          "code": "warning-box",
          "display": "Warning Box"
        }]
      }
    }],
    "text": {
      "status": "generated",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Kontakta mottagningen senast 24 timmar innan din tid.</p></div>"
    }
  }]
}

Comparison: Strategy A vs Strategy B

Aspect Strategy A: Direct XHTML Strategy B: Semantic Sections
Visual Fidelity ✅ Exact match to 1177 Inkorg ⚠️ Depends on client rendering
Semantic Preservation ❌ Lost (just styled divs) ✅ Preserved via section.code
Queryability ❌ Requires HTML parsing ✅ Search by section.code
Portability ❌ Requires CSS stylesheet ✅ Adapts to client capabilities
Transformation Complexity ✅ Simple (1:1 mapping) ⚠️ More complex (sections + codes)
Accessibility ⚠️ Screen readers see styled text ✅ Screen readers announce semantic type
Future-Proof ❌ Locked to CSS classes ✅ Clients evolve rendering
Use Case Patient-facing messages (1177 Inkorg) Clinical documents (NPÖ, exchange)

For Patient Administrative Messages (1177 Inkorg → DocumentReference):

  • Use Strategy A (Direct XHTML) for simplicity and visual fidelity
  • Store in DocumentReference.content.attachment with contentType='text/html'
  • Include CSS stylesheet reference in DocumentReference metadata

For Clinical Documentation (Progress notes, Discharge summaries → Composition):

  • Use Strategy B (Semantic Sections) for interoperability
  • Map emphasis[@role='information/observe'] to section.code
  • Use inline formatting (<strong>, <em>, <u>) within section.text.div for textual emphasis
  • Add section-presentation-style extension as rendering hint

For Inline Emphasis (within paragraphs in either strategy):

  • bold<strong> (semantic emphasis) or <b> (visual bold)
  • italics<em> (semantic emphasis) or <i> (visual italic)
  • underline<u> (unarticulated annotation, use sparingly)

Example: Hybrid in Clinical Note:

{
  "section": [{
    "title": "Bedömning",
    "code": {
      "coding": [{
        "system": "http://loinc.org",
        "code": "51848-0",
        "display": "Assessment"
      }]
    },
    "text": {
      "status": "additional",
      "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Diabetes typ 2 i <strong>förbättring</strong>. HbA1c <em>mycket bra</em> utveckling.</p><div class='info-box'><h4>Behandlingsmål</h4><ul><li>HbA1c &lt;52 mmol/mol - <strong>uppnått</strong> ✓</li></ul></div></div>"
    }
  }]
}

Here:

  • Inline <strong> for textual emphasis ("förbättring")
  • Inline <em> for mild emphasis ("mycket bra")
  • CSS class .info-box for treatment goals section (visual styling)
  • section.code = "51848-0" (Assessment) for semantic type

Implementation Recommendations

For 1177 Inkorg Messages → FHIR DocumentReference

Recommended Approach:

  1. Store original DocBook in DocumentReference.content.attachment.data (Base64)
  2. Transform DocBook to XHTML Narrative and store in DocumentReference.content.attachment with contentType='text/html'
  3. Use DocumentReference.type to categorize message (appointment, test result, etc.)
  4. Reference related resources (Appointment, Observation) via DocumentReference.context.related

Example:

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "57133-1",
      "display": "Referral note"
    }]
  },
  "subject": {
    "reference": "Patient/191212121212"
  },
  "date": "2022-03-01T10:00:00+01:00",
  "author": [{
    "reference": "Organization/soderby-vardcentral"
  }],
  "content": [
    {
      "attachment": {
        "contentType": "application/docbook+xml",
        "data": "PD94bWwgdmVyc2lvbj0iMS4wIj8+CjxhcnRpY2xlPgo8c2VjdGlvbj4KPC9hcnRpY2xlPg==",
        "title": "Original DocBook Message"
      }
    },
    {
      "attachment": {
        "contentType": "text/html",
        "data": "PGRpdj48aDI+VsOkbGtvbW1lbjwvaDI+PC9kaXY+",
        "title": "HTML Rendering"
      },
      "format": {
        "system": "http://ihe.net/fhir/ValueSet/IHE.FormatCode.codesystem",
        "code": "urn:ihe:iti:xds:2017:mimeTypeSufficient",
        "display": "mimeType Sufficient"
      }
    }
  ],
  "context": {
    "related": [{
      "reference": "Appointment/appointment-20220310-1100"
    }]
  }
}

For Clinical Documents → FHIR Composition

Recommended Approach:

  1. Use Composition.section for major document sections
  2. Transform DocBook sections to FHIR sections with coded section.code
  3. Use section.text (Narrative) for rich formatting within sections
  4. Reference structured resources via section.entry

Transformation Tools and Libraries

XSLT Transformation (DocBook → FHIR Narrative XHTML):

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:template match="article">
    <div xmlns="http://www.w3.org/1999/xhtml">
      <xsl:apply-templates/>
    </div>
  </xsl:template>
  
  <xsl:template match="section">
    <div class="section">
      <xsl:apply-templates/>
    </div>
  </xsl:template>
  
  <xsl:template match="title">
    <h2><xsl:apply-templates/></h2>
  </xsl:template>
  
  <xsl:template match="para">
    <p><xsl:apply-templates/></p>
  </xsl:template>
  
  <xsl:template match="emphasis[@role='bold']">
    <strong><xsl:apply-templates/></strong>
  </xsl:template>
  
  <xsl:template match="emphasis[@role='information']">
    <div class="info-box">
      <h3><xsl:apply-templates/></h3>
    </div>
  </xsl:template>
  
  <xsl:template match="ulink">
    <a href="{@url}" target="{@type}"><xsl:apply-templates/></a>
  </xsl:template>
  
  <xsl:template match="itemizedlist">
    <ul><xsl:apply-templates/></ul>
  </xsl:template>
  
  <xsl:template match="listitem">
    <li><xsl:apply-templates/></li>
  </xsl:template>
  
  <xsl:template match="variablelist">
    <dl><xsl:apply-templates/></dl>
  </xsl:template>
  
  <xsl:template match="term">
    <dt><xsl:apply-templates/></dt>
  </xsl:template>
  
  <xsl:template match="varlistentry/listitem">
    <dd><xsl:apply-templates/></dd>
  </xsl:template>
  
</xsl:stylesheet>

Summary and Best Practices

✅ Best Practices

  1. Preserve Original DocBook: Store in DocumentReference.content.attachment as Base64
  2. Use FHIR Narrative for Display: Transform DocBook to XHTML for Composition.text or section.text
  3. Choose Strategy Based on Use Case:
    • Simple informational messages → Composition.text (Narrative-only)
    • Clinical documents with structure → Composition.section with coded sections
  4. CSS for 1177 Styling: Provide separate stylesheet for .info-box, .warning-box, .framed-box
  5. Handle Collapsible Sections: Expand all by default, or use separate Composition.section with emptyReason
  6. Map to Structured Resources: When possible, reference Appointment, Observation, Medication via section.entry or DocumentReference.context.related

🚫 Common Pitfalls

❌ Don't use DocBook elements directly in Narrative.div (invalid XHTML)
❌ Don't rely on JavaScript for interactive elements (

, collapsible) unless custom renderer guaranteed
❌ Don't lose semantic information (use <strong> instead of <b> when meaning is emphasis)
❌ Don't forget xmlns='http://www.w3.org/1999/xhtml' on root <div>
❌ Don't create Narrative without text.status (required: generated, extensions, additional, empty)


References