DocBook to FHIR Narrative XHTML Mapping - Inera Core Implementation Guide v0.2.0

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

ConceptMap: DocBook to FHIR Narrative XHTML Mapping

Official URL: https://inera.se/fhir/core/ConceptMap/docbook-to-narrative				Version: 0.2.0
Draft as of 2025-12-09				Computable Name: ConceptMapDocBookToNarrative

Mapping between DocBook elements supported by 1177 Inkorg and FHIR Narrative.div XHTML.

DocBook is the required format for 1177 Inkorg messages (AddMessage.Message.Text), but FHIR uses Narrative.div with a restricted XHTML subset (FHIR Narrative data type).

Source: DocBook subset supported by 1177 Inkorg
Target: FHIR Narrative XHTML (limited XHTML 1.0 Strict subset)

FHIR Narrative Constraints:

Only specific XHTML tags allowed: div, span, p, h1-h6, a, ul, ol, li, dl, dt, dd, b, i, u, em, strong, table, etc.
All content must be in a single <div xmlns='http://www.w3.org/1999/xhtml'> root
No DocBook-specific elements (article, section, emphasis[@role]) in output
Custom styling via @class or @style attributes where needed

Reference:

https://inera.atlassian.net/wiki/spaces/OIIK/pages/3590029598/Docbook-formatering+av+meddelande
https://inera.atlassian.net/wiki/spaces/OIIK/pages/3590619160/DocBook+exempel
http://hl7.org/fhir/R4/narrative.html#Narrative

Enable transformation between 1177 Inkorg DocBook format and FHIR Narrative.div for patient communications in DocumentReference and Composition resources

Mapping from https://inera.se/fhir/core/ValueSet/docbook-elements to http://hl7.org/fhir/ValueSet/narrative-xhtml-tags

Group 1 Mapping from https://inera.se/fhir/core/CodeSystem/docbook-elements to http://hl7.org/fhir/narrative-xhtml

Source Code

Relationship

Target Code

Comment

article (article (document root))

is equivalent to

div (<div xmlns='http://www.w3.org/1999/xhtml'>)

Root <article> becomes the required <div> wrapper for FHIR Narrative. All Narrative content must be inside this div.

section (section (document section))

is equivalent to

div-section (<div class='section'> or <div id='section-id'>)

Each <section> becomes a <div> with optional class='section' or id attribute for internal linking. Alternative: use Composition.section instead for structured sections.

info (info (metadata container))

omit ((omit - metadata goes in resource elements))

Metadata from <info> (title, author, date) maps to Composition/DocumentReference resource elements, not Narrative.div

title (title (section or document title))

is equivalent to

heading (<h1>, <h2>, <h3> etc.)

In info/article: <h1>. In section: <h2> or deeper based on nesting. Consider using Composition.title instead of Narrative heading.

para (para (paragraph))

is equivalent to

p (<p>)

Direct mapping: <para> → <p>

emphasis (emphasis (inline emphasis with role attribute))

span-varied (<span>, <b>, <i>, <u>, <em>, <strong> based on @role)

Map based on @role attribute - see role-specific mappings below

emphasis-bold (emphasis[@role='bold'])

is equivalent to

strong (<strong> or <b>)

<emphasis role='bold'>text</emphasis> → <strong>text</strong> (semantic) or <b>text</b> (visual)

emphasis-italics (emphasis[@role='italics'])

is equivalent to

em (<em> or <i>)

<emphasis role='italics'>text</emphasis> → <em>text</em> (semantic) or <i>text</i> (visual)

emphasis-underline (emphasis[@role='underline'])

is equivalent to

u (<u> or <span style='text-decoration:underline'>)

<emphasis role='underline'>text</emphasis> → <u>text</u>

emphasis-collapsible (emphasis[@role='collapsible'])

details (<div class='collapsible'> (non-standard, requires JS))

FHIR Narrative doesn't support <details>. Use <div class='collapsible'> with custom CSS/JS, or expand all content in static view. Alternative: use separate Composition.section with emptyReason.

emphasis-bgcolor (emphasis[@role='bgcolor'])

span-highlight (<span class='highlight'> or <span style='background-color:#ffff00'>)

Use <span> with class or inline style for background color highlighting

emphasis-information (emphasis[@role='information'])

div-info-box (<div class='info-box'> (gray box in 1177))

Gray information box from 1177. Map to <div class='info-box'> with CSS for gray background. Content inside includes heading and list.

emphasis-observe (emphasis[@role='observe'])

div-warning-box (<div class='warning-box'> (yellow box in 1177))

Yellow warning/observe box from 1177. Map to <div class='warning-box'> with CSS for yellow background. Content inside includes heading and list.

emphasis-frame (emphasis[@role='frame'])

div-framed-box (<div class='framed-box'> (white bordered box in 1177))

White framed/bordered box from 1177. Map to <div class='framed-box'> with CSS for border. Content inside includes heading and paragraph.

ulink (ulink (external URL link))

is equivalent to

a-external (<a href='url' target='_blank'>)

<ulink url='https://example.com' type='_blank'>text</ulink> → <a href='https://example.com' target='_blank'>text</a>

link (link (internal document link))

is equivalent to

a-internal (<a href='#anchor'>)

<link url='#section-id'>text</link> → <a href='#section-id'>text</a>. Ensure target div has matching id attribute.

itemizedlist (itemizedlist (bulleted/unordered list))

is equivalent to

ul (<ul> or <ul class='bullet'> or <ul class='hyphen'>)

<itemizedlist> → <ul>. Use @mark attribute to determine list-style-type (bullet vs hyphen) via CSS class.

itemizedlist-bullet (itemizedlist[@mark='bullet'])

is equivalent to

ul-bullet (<ul style='list-style-type:disc'> or <ul class='bullet'>)

Bullet list with disc markers (default for <ul>)

itemizedlist-hyphen (itemizedlist[@mark='hyphen'])

is equivalent to

ul-hyphen (<ul style='list-style-type:"- "'> or <ul class='hyphen'>)

Hyphen list. Use CSS to change list markers to hyphens.

listitem (listitem (list item content))

is equivalent to

li (<li>)

<listitem> → <li> (both in itemizedlist/ul and variablelist/dl contexts)

variablelist (variablelist (definition/variable list))

is equivalent to

dl (<dl> (definition list))

<variablelist> → <dl>. Common in 1177 for key-value pairs (Datum: / Tisdag 10 mars 2022)

varlistentry (varlistentry (variable list entry))

is equivalent to

dt-dd-pair (<dt> + <dd> pair)

Each <varlistentry> contains one <term> (→ <dt>) and one <listitem> (→ <dd>)

term (term (variable list term))

is equivalent to

dt (<dt>)

<term>Datum:</term> → <dt>Datum:</dt>

varlistentry-listitem (listitem (in variablelist context))

is equivalent to

dd (<dd>)

<listitem>Tisdag 10 mars 2022</listitem> → <dd>Tisdag 10 mars 2022</dd> (in variablelist)

bibliography (bibliography (references section))

div-references (<div class='references'> or <h2>Referenser</h2> + content)

Create <div class='references'> section or use <h2>Referenser</h2> followed by list. Alternative: use Composition.section for structured bibliography.

url-attribute (url attribute (for ulink/link))

is equivalent to

href-attribute (href attribute on <a>)

@url → @href

type-attribute (type attribute (for ulink/link))

is equivalent to

target-attribute (target attribute on <a>)

@type='_blank' → @target='_blank' (opens in new window)

mark-attribute (mark attribute (for itemizedlist))

class-or-style (class or style attribute on <ul>)

@mark='bullet' → class='bullet', @mark='hyphen' → class='hyphen' or inline style for list-style-type