ePI IG for APAC markets, published by Gravitate Health Project. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/cander2/aseanepi/ and changes regularly. See the Directory of published versions

Technical Style Guide

Objective

To provide standardized instructions for structuring ePI content; and ensure the consistency, clarity and quality of ePIs across organizations, jurisdictions, and regulators. These recommendations are subject to local regulatory rules. Refer to local regulatory guidance for actual requirements.

Introduction

A Technical Style Guide defines the standard format and structure for writing technical documents within or across organizations. This is of great value to the international ePI project because the associated technologies and standards (e.g., XML, HTML, style sheets) are highly flexible and offer a wide array of options.

The risk of divergence is therefore high if all organizations and regulators across jurisdictions chose to structure their ePIs in different ways. Although still compliant with FHIR, the resulting divergence could complicate global implementation and maintenance. This results in an unnecessary increase in software development and maintenance costs and process inefficiencies.

Through standardization, we ensure ePI content is more consistent, accessible, easier to maintain, interoperable across systems, is more search engine friendly, and more friendly for artificial intelligence.

The content of this guide is not novel. It consolidates a selection of common best practices from Health Level 7 (HL7), web development, and web standards for convenience.

Scope

In-scope

• XML and JSON structure, formatting, attributes, and elements
• HTML and XHTML structure, formatting, attributes, and elements
• Chapters 7-11 (except section 4 of chapter 9) and 15 of the HTML 4.0 standard
• Text, tables, images, and internally contained style attributes

Out of scope

• Regulatory content requirements
• Content style (e.g., Font, font colour, font size)
• External style attributes from a style sheet

Guidance

ePI Structure (XML, JSON, XHTML)

By default, the structured elements of a FHIR document are based on Extensible Markup Language (XML) or JavaScript Object Notation (JSON).

However, there is an exception for Narrative text (E.g., paragraphs, lists, images, tables, hypertext links). Whether the ePI is XML or JSON, the narrative text is captured as EXtensible HyperText Markup Language (XHTML) or Markdown.

Markdown is a simplified standard for structuring plain text. In an ePI, Markdown is used in data fields that only require brief, basic text (E.g., Document title, section heading title).

XHTML is used in data fields that require full rich narrative text of varying lengths (E.g., paragraphs of text, tables, lists, images in the section content of a drug label).

For example, here is an ePI section structured with XML (Red) and narrative as XHTML (Blue):

<section id="7c4f5a60-0d4e-ee11-be6e-000d3aaa06fe">
    <title value="1. What X is and what it is used for" />
    <code>
      <coding>
        <system value="https://spor.ema.europa.eu/v1/lists/200000029659/terms/" />
        <code value="200000029895" />
        <display value="1. What X is and what it is used for" />
      </coding>
    </code>
    <text>
      <status value="generated" />
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>The therapeutic indications in line with section 4.1 of the SmPC should be stated here. It should be stated in which age group the medicine is indicated, specifying the age limits, e.g. “X is used to treat {specify indication} in”.</p>
      </div>
    </text>
</section>
    

For example, here is an ePI section structured with JSON (Red) and the narrative as XHTML (Blue):

{
  "title" : "1. What X is and what it is used for",
  "code" : {
    "coding" : [
      {
        "system" : "https://spor.ema.europa.eu/v1/lists/200000029659/terms/",
        "code" : "200000029895",
        "display" : "1. What X is and what it is used for"
      }
    ]
  },
  "text" : {
    "status" : "additional",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>The therapeutic indications in line with section 4.1 of the SmPC should be stated here. It should be stated in which age group the medicine is indicated, specifying the age limits, e.g. “X is used to treat {specify indication} in</p></div>"
  }
}
    

Style vs. Inline Text Formatting vs. Style Sheet

Text style refers to visual characteristics applied to the whole document to achieve an overall look and feel. E.g., Font type, Font size, Font colour, Table borders, Table cell shading, type of bullets.

Inline text formatting refers to visual characteristics applied to specific portions of text within the document. E.g., Bold, italic, superscript, subscript, hypertext link.

Inline text lives within a ePI document. Styles are applied from outside the document using a Style Sheet. A style sheet is made up of one or both of the following:

• Extensible Stylesheet Language Transformations (XSLT) is used to transform content from one document format to another (e.g., convert XML to user friendly PDF); move content around (e.g., move Section 2 before Section 1); or transform content (e.g., transform this number format from “10000000” to “10,000,000” or “1x10⁷”).
• Cascading Style Sheet (CSS) is used to style the content after transformation. E.g., make all text in the document Aptos font; font size 11pt; black font colour. The CSS can also be used to add interactive elements like expand/collapse buttons; column filters on large tables.

Keeping style and content separate is a key benefit of structured content. Keeping them separate in an ePI document ensures the following:

• Maintenance: Easier to update a single central style sheet, that applies a global change to all ePIs across a portfolio, rather than updating each ePI individually.
• Reusability: Style sheets can be reused across multiple document types to apply a consistent appearance across an organization. E.g., reuse a common house table style across labeling, CMC, and Clinical documents.
• Context: Different style sheets can be used to serve different objectives. e.g., transform an ePI into an accessibility friendly webpage with high contrast mode; or use another style sheet to transform the ePI into a print friendly PDF with pagination and page breaks.

Accessibility

In most jurisdictions WCAG Level AA is recommended for use.

Character set

The default standard for all content characters is Unicode Transformation Format 8-bit (UTF-8).

UTF-8 is a character encoding standard used to ensure text is presented consistently when exchanged across systems.

Content Guidelines

Narrative Text

All text must be contained within one of the following five tags:

• Paragraph <p>
• Ordered list <ol>
• Unordered list <ul>
• Table <table>
• Footer <footer>

Content Span <span>

Paragraphs

The paragraph tag <p> can contain text and inline formatting tags as children. E.g.,

• Parse <strong> (instead of Bold <b>)
• Emphasis <em> (instead of Italics <i>)
• Superscript <sup>
• Subscript <sub>
• Image <img>
• Content Span <span>

The <strong> and <em> tags are used to give semantic meaning to text.

<strong> is used to indicate that the text has strong importance or emphasis. It typically renders the text in bold.

<em> This tag is used to emphasize text, usually rendering it in italics.

The bold tag <b> and italics tag <i> are only used to convey the appearance of text and do not convey any semantic meaning.

Developers can use the semantic meaning behind <strong> and <em> tags to deliver benefits like the following:

• Improve Accessibility: Accessibility services, like screen readers, are already designed to understand the structure and importance of content within semantic tags.
• Consistent Styling: Semantic tags can be targeted with style sheets to apply styling consistently across web browsers and devices (mobile, desktop, wearable).
• Better User Experience: Developers can reuse known and effective best practices to create intuitive and user-friendly experiences.

Note:

• The Paragraph tag <p> cannot contain lists or tables as children.
• Use Paragraph tags instead of Line Break <br> tags. Line Breaks and white space between content blocks (e.g., paragraphs, tables) should be handled by the style sheet as needed.

In-line Style Attribute

The style attribute can be added to tags to apply inline formatting. E.g.,

<p style="text-decoration: underline">Underlined Sub-heading</p>

or

<p>Example of how to <span style="text-decoration: underline">underline</span> specific text</p>

The following is a list of classes that can be used together with the style attribute:

Lists

Lists are defined using the Unordered List tag <ul> (i.e., bulleted list) or the Ordered List tag <ol> (i.e., numbered or alphabetical list).

<ul> and <ol> tags must only contain List Item <li> tags as children. List Item <li> tags can contain other tags as children; e.g., divider <div>, paragraph <p>, heading <h1> to <h6>, images <img>, and tables <table>.

For example, this shows how to multiple paragraphs in a single bullet.

<ul>
<li>
<div>    
<p>Bullet text with paragraphs</p>
<p> next paragraph in the bullet </p>
</div>
</li>
<li>Next bullet</li>
</ul>
                    

Nested lists are made by adding another layer of <ul> or <ol> tags as children to a List.

For example, this shows how to create a nested list with a leading paragraph.

<ol>
<li>
Bullet text #1
</li>
<li>
<div><p>Bullet text #2</p>
<ul>
<li>Sub-bullet text #1</li>
<li>Sub-bullet text #2</li>
</ul>
</div>
</li>
</ol>
                    

Hyperlinks

The Anchor tag <a> and its attributes are used to represent hypertext links. E.g.,

Visit W3Schools.com!

Escape characters

The following characters are reserved in XML for specific purposes and must be escaped. E.g., Within the ePI’s XML, ampersand “&” cannot be used in narrative text. “&” must be used in its place.

Web browsers and apps will always convert the escaped form “&” back to the normal form “&”. The escaped form is only reserved for the XML content.

Common Symbols

Symbols can be added as regular text as long as they are UTF-8 compliant or they can be replaced with named entities. Like the escape characters mentioned in Section 4.4, web browsers or applications convert named entities back to the normal symbol in the display.

The following table is a list of commonly use symbols. Refer to the HTML specification or W3C resources for a more comprehensive list.

Diacritical Marks

Diacritical marks work in a similar manner as symbols with named entities. The following table is a list of commonly use marks. Refer to the HTML specification or W3C resources for a more comprehensive list.

Tables

The table tag <table> and its children (see table below) are used to structure a table.

Only <thead>, <tbody>, <tfoot>, <caption>, and <colgroup> tags are permitted as children of <table>.

The <th> and <td> tags may contain inline elements, paragraphs, headings, lists, and image tags as children. Only include text or content in <caption>, <th>, <td>, and <tfoot>. All other tags are only used for structure.

Note: Avoid using Tables for formatting and alignment. There are alternative best practice solutions that achieve the same objective in a standardized manner.

Example: Simple Table

Example: Merge cells across columns

Example: Merge cells across rows

Images

The preferred format for images is Scalable Vector Graphics (SVG). SVG is an XML based format that can be scaled to any size without losing quality. SVG is ideal for graphics that need to look sharp at any size. This is ideal for ePI since graphics need to be resized for different size screens (wearable, mobile, desktop); or resized to suit printed cartons, paper leaflets, and instructions for use.

All images must be embedded within the ePI’s XML as Base64 objects. This allows an ePI to be exchanged as a single XML or JSON file. Each image is managed as a single Base64 object in a single Contained Binary resource within the ePI. E.g.,

<contained>
 <Binary>
     <id value="companylogo" />
     <contentType value="image/svg+xml" />
     <data value="Base64 data goes here" />
 </Binary>
</contained>
    

The image tag <img> is then placed in the content to show where the image is supposed to go. E.g.,

<text>
    <status value="generated" />
    <div xmlns="http://www.w3.org/1999/xhtml">
        <p><img src="#companylogo" alt="Company logo" />Product Name</p>
    </div>
</text>
    

Note:

• Include a brief but meaningful description of the image using the “alt” attribute in the image tag <img> to facilitate accessibility features like screen reading.
• Colours should meet the WCAG Level AA for contrast.

Audio and Video

It is best practice not to embed audio or video files within an ePI given their large size. Instead, the ePI should link to external copies of audio and video files.

Note: Check local regulations to confirm if audio and video files are allowed to be used with an ePI.

Languages

Each language should be a separate ePI document. E.g., one ePI for English and a separate ePI for its French translation.

The style sheet will be used to control the direction of text. E.g., the XML may show Arabic text as left to right but the style sheet will convert the content to correctly show as right to left; Japanese will appear as left to right but the style sheet can convert the content to show as top to bottom or right to left pages.

Math formulas

Mathematical Markup Language (MathML) or similar structured mathematical notations are not compliant with the FHIR specification at this time. Simple formulas can be recreated in the narrative. For example, (a + b)² could be expressed as:

<p>a + b²</p>

Complex formulas must be incorporated into the ePI as an image and then referenced in the text using the image tag <img> (Refer to section 5.4 for guidance on images).

Appendices

References

• HL7 FHIR XHTML Styling specification - Narrative - FHIR v5.0.0
• W3Schools Online Web Tutorials
• HTML specification v4.0 - HTML 4.0 Specification
• HL7 FHIR narrative text specification - Narrative - FHIR v5.0.0
• Mathematical Markup Language (MathML) Version 3.0 2nd Edition
• Scalable Vector Graphics (SVG) 2 specification
• XHTML™ 1.0 in XML Schema
• Jordan Food and Drug Administration’s (JFDA) HTML Validator guidance - Leaflet · Debug

Named entities

• W3C Schools HTML ISO-8859-1 Reference
• ISO/IEC 8859-1:1998 - Information technology — 8-bit single-byte coded graphic character sets — Part 1: Latin alphabet No. 1