NHS England Design and Development Approach

WARNING

This guidance is under active development by NHS England and content may be added or updated on a regular basis.

Purpose

To standardise all pages within the FHIR NHS England Implementation Guide (IG)

General Rules

Information SHALL be unique to NHS England IG. There SHOULD NOT be any duplication of HL7 FHIR content nor any information within the profile unless it gives context for additional NHS England IG information.
Information SHALL NOT contradict HL7 FHIR.
Conformance language SHALL be written in accordance with https://build.fhir.org/conformance-rules.html#conflang .
External links to HL7 FHIR SHALL be the same version as NHS England IG.
Each header SHALL be in Title case unless the header wording is an element, then is SHALL be in camelCase and as an inline code.
Elements and values SHALL be written as an inline code.
The first index title will be in the markdown form as # Header1.
Each following page first title shall be in the from ## Header2.
Sub headers within these pages SHALL be in the form ### Header3 or #### Header4 where needed
Each table SHALL be in HTML code.
All lists SHOULD be in alphabetical order.
Line breaks SHALL be written as <br>.
The end of each page SHALL have a page break, denoted by three dashes.
Codenames that are not headers SHALL be written in absolute terms and as inline code, e.g. `Patient.contact.name`
FHIR assets names SHALL match the casing of their defintion on HL7 FHIR. Typically this will be written in PascalCase, such as ValueSet or CodeSystem.
When refering to SNOMED CT, it SHALL be written in capitals.
When refering to SNOMED CT codes, the words Concept, Description, and Id SHALL be used in Title case.
FHIR elements SHALL be fully qualified when discussed in guidance, e.g. Procedure.note.authorReference rather than note.author
CSS shall be used to control table column widths
All asset and major IG page design changes will be logged in the Version History change log

Web Accessibility

All id's on a page SHALL be unique where they can be controlled by the NHSE IG development team
All table tags SHALL have a meaningful title attribute
All rendered images SHALL be within a div with a title that is to be used as the alt text, or SHALL have alt text set
All added / amended pages SHALL be checked for WCAG 2.0 AA issues prior to publication

Naming Conventions

Markdown	Usage
Title Case	Any headers that are not elements
<code>camelCase</code>, or `camelCase`	Any elements and it’s values
<code>PascalCase</code>, or `PascalCase`	Any FHIR assets

Headers

Markdown	Usage
# [Header 1]	Any Index page title. Note: Profiles SHALL not be in inline code for the first header
## { {page-title}}	Any other page title
## `{ {page-title}}`	Any other page title which is an element
## [header 2]	Sub header for index page
### [header 3] #### [header 4]	Sub headers for any pages

Hyperlinks

Markdown	Usage
<a href="[link]">[link title]</a>	External Links. Only to be used to link to pages within https://hl7.org/fhir/ and https://simplifier.net/
{ {pagelink:[Topic url]}}	Internal Link. For referencing within the IG.

Note: the Topic url can be found using the dropdown button within the IG editor, or for pages named 'Index' these are manually created and can be found at the top of the page. See Topic for more details.

External links SHALL have class="external" set.

Information Boxes

There are two information boxes in use in the IG, a blue box and a yellow box.

Blue should be used for additional callouts of information, e.g.:

<div markdown="span" class="alert alert-info"><i class="fa fa-asterisk"></i> <code>England-Patient</code> was added after specific review and feedback from the Digital and Interoperable Medicines Programme. It was not added under a Clinical & Technical Assurance sprint
</div>

England-Patient was added after specific review and feedback from the Digital and Interoperable Medicines Programme. It was not added under a Clinical & Technical Assurance sprint

Yellow should be used for important information, e.g.:

<div markdown="span" class="alert alert-warning" role="alert"><h4><i class="fa fa-info-circle"></i> Important</h4>
Where the prescription is available, it is recommended to reference via a URL - using the <code>Patient.managingOrganization.identifier</code> element rather than adding the <code>Patient</code> as a bundle - to avoid duplication.
</div>

Important

Where the prescription is available, it is recommended to reference via a URL - using the Patient.managingOrganization.identifier element rather than adding the Patient as a bundle - to avoid duplication.

Balloted Information

Where guidance has been added or changed between ballots, it SHALL be highlighted in green.

For tr, td, li elements, this is done by adding class="balloted"

For Extensions, Profiles, ValueSets, CodeSystems that have been ADDED, this is done by adding this to the top of the relevant page - this will turn the whole of that Extension, ValueSet, CodeSystem green, or if added to a Profile page, the whole page green.

<div id="newAsset" markdown="span" class="alert alert-success" role="alert"><h4><i class="fa fa-star"></i> Important</h4>

This [Asset Type] underwent Clinical and Technical Assurance during Sprint X. This is a new [Asset Type] added to NHS England IG, and should undergo review under Ballot Y.
</div>

The same div, without the id="newAsset" can be used on a page to add a green banner to the page. This should be used on any guidance page that is not an asset, e.g. within CodeableConcept guidance.

Important

This [Asset Type] underwent Clinical and Technical Assurance during Sprint X. This is a new [Asset Type] added to NHS England IG, and should undergo review under Ballot Y.

Rendering Additional Content

Where guidance has been added in another IG, such as the glossary, this can be rendered in an IG using the Simpifier { }, which can work across projects and organisations.

For example, the Glossary is rendered via:

{ {render:hl7fhirukcorer4/index-duplicate-49}}

Important

Currently, Simplifier commands, such as FQL or pagelink / tree / xml / json / render, will not be processed by the rendered page.

Images can be rendered using the same { } command, and SHALL be within a div with id beginning "renderParent", and SHALL contains a title attirbute which will be used for the alt text.

<div id="renderParent" title="The logos of organisations involved in developing and implementing UK Core">
{ {render:ukcorelogos2023}}
</div>

Extension Layout

Extensions SHALL have a page within the ‘All Extensions’ folder with the naming convention of ‘Extension England-[extensionName]’, and you must ensure the pages within the folder are in alphabetical order.

Each extension SHALL have an example.

The page layout SHALL be as the following:

## StructureDefinition Extension-England-[ExtensionName]

<div id="transpose">
@ ```
from
	StructureDefinition
where
	name = 'ExtensionEnglandAdditionalContact'
select
	Canonical_URL: url,
	Description: description,
	Profile_Purpose: purpose
```

<table id="addToTranspose">
<tr><td>Context of Use</td>
<td>{ {pagelink:Profile-[Profile],text:[Profile]}}</td>
</tr>
</table>

</div>
<br>

<div class="tab">
 <button class="tablinks active" onclick="openTab(event, 'Tree View')">Tree View</button>
   <button class="tablinks" onclick="openTab(event, 'Table View')">Table View</button>
   <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
   <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
  <button class="tablinks" onclick="openTab(event, 'Examples')">Examples</button>
</div>

<div id="Tree View" class="tabcontent" style="display:block">
  <h3>Tree View</h3>
{ {tree:https://fhir.nhs.uk/StructureDefinition/Extension-England-[ExtensionName]}}
</div>
<div id="Table View" class="tabcontent">
  <h3>Table View</h3>
{ {table:https://fhir.nhs.uk/StructureDefinition/Extension-England-[ExtensionName]}}
</div>
<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml:https://fhir.nhs.uk/StructureDefinition/Extension-England-[ExtensionName]}}
</div>
<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json:https://fhir.nhs.uk/StructureDefinition/Extension-England-[ExtensionName]}}
</div>

<div id="Examples" class="tabcontent">
  <h3>Examples</h3>
  <b>[Example]</b> - An example to illustrate using the extension.<br>
{ {pagelink:Example-England-[Profile]-Extension-[ExtensionName]}}
<br><br>
</div>

### Guidance
[A link to the ValueSet if the Extension has a binding, or a link to the Resource / Profile if the Extension has references]

---

ValueSet Layout

ValueSets SHALL have a page within the ‘All ValueSets’ folder with the naming convention “ValueSet [ValueSet id]”, e.g. ValueSet England-EthnicCategory, and you must ensure the pages within the folder are in alphabetical order.

The layout SHALL be in the following format:

## England [ValueSet title]

<div class="tab">
 <button class="tablinks active" onclick="openTab(event, 'HTML View')">HTML View</button>
 <button class="tablinks" onclick="openTab(event, 'Table View')">Table View</button>
  <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
  <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
</div>

<div id="HTML View" class="tabcontent" style="display:block">
  <h3>HTML View</h3>
{ {render:https://fhir.nhs.uk/ValueSet/England-[ValueSet]}}
</div>

<div id="Table View" class="tabcontent">
  <h3>Table View</h3>
{ {table:https://fhir.nhs.uk/ValueSet/England-[ValueSet]}}
</div>

<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml:https://fhir.nhs.uk/ValueSet/England[ValueSet]}}
</div>

<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json:https://fhir.nhs.uk/ValueSet/England-[ValueSet]}}
</div>

---

The page SHALL be referenced within table on the ‘ValueSets and Codesystems’ page in alphabetical order.

The page SHALL be referenced within the appropriate profile ‘Bindings (differential)’ table within the profile page.

CodeSystem Layout

CodeSystems SHALL have a page within the “All CodeSystems” folder with the naming convention “CodeSystem [CodeSystem id]”, e.g. CodeSystem England-EthnicCategory, and you must ensure the pages within the folder are in alphabetical order.

The layout SHALL be in the following format:

## England [CodeSystem title]

<div class="tab">
 <button class="tablinks active" onclick="openTab(event, 'HTML View')">HTML View</button>
 <button class="tablinks" onclick="openTab(event, 'Table View')">Table View</button>
  <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
  <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
</div>

<div id="HTML View" class="tabcontent" style="display:block">
  <h3>HTML View</h3>
{ {render:https://fhir.nhs.uk/CodeSystem/England-[CodeSystem]}}
</div>

<div id="Table View" class="tabcontent">
  <h3>Table View</h3>
{ {table:https://fhir.nhs.uk/CodeSystem/England-[CodeSystem]}}
</div>

<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml:https://fhir.nhs.uk/CodeSystem/England-[CodeSystem]}}
</div>

<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json:https://fhir.nhs.uk/CodeSystem/England-[CodeSystem]}}
</div>

---

The page SHALL be referenced within table on the ‘ValueSets and Codesystems’ page under the appropriate ValueSet.

Example Layout

Each example SHALL have its own page within the folder ‘Examples Index’, listed in alphabetical order. The page SHALL be named ‘Example England-[example name]’.

Each example SHALL also be added to the example tab within the relevant profile and extension table.

The page layout SHALL be as the following:

### An example to illustrate the [reason for example]

<div class="tab">
 <button class="tablinks active" onclick="openTab(event, 'Table View')">Table View</button>
 <button class="tablinks" onclick="openTab(event, 'Tree View')">Tree View</button>
  <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
  <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
</div>

<div id="Table View" class="tabcontent" style="display:block">
  <h3>Table View</h3>
{ {table:[Example id]}}
</div>

<div id="Tree View" class="tabcontent">
  <h3>Tree View</h3>
{ {tree:[Example id]}}
</div>

<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml:[Example id]}}
</div>

<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json:[Example id]}}
</div>

---

Profiles

Each Profile SHALL consist of multiple pages, all residing within a folder that SHALL be named Profile-England-[profile]. This folder SHALL reside withinin the folder 'Profiles and Extensions'.

The pages within the folder SHALL follow the structure:

Index (mandatory)
Extensions (optional)
Bindings (differential) (optional)
Constraints (differential) (optional)
[Profile Element name] (multiple) (optional)

Index Page

Unless stated as optional, the index page SHALL have, in order, the following:

Topic
Structure Definition
Profile Purpose
A profile table with the following views:
- Snapshot
- Differential
- Hybrid
- XML snapshot
- JSON snapshot
- Examples
Profile Specific Implementation Guidance

Topic

A profile index page should have a YAML header:

a topic, which allows the page to be referenced using { {pagelink:topic}} within the IG.
a system, the canonical url for the resource, which allows Simplifier render commands to be used without specifying a url

A YAML header SHALL be the first item on a page, it SHALL be unique, and it SHALL be in the following format:

---
topic: [Section]-[ResourceName]
subject: [resource canonical url]
---

Example Topics:

Guidance-DataType
Library-Extensions
Profile-MedicationDispense
Home-ContactUs

Note: The topic only needs to be added for pages that will be linked to directly, and for pages with non unique names, such as Index - for uniquely named pages e.g. ValueSet England-[ValuesetName], the default generated topic is ok.

Structure Definition

The structure definition contains the profile’s description and profile purpose, rendered from the xml file using Firely Query Language (FQL). This contains a short description of the profiles purpose and the profile itself within a table. The profile table reference SHALL be rendered as below, ensuring that each view has the correct profile link.

The tabs and rendered views SHALL be enclosed within a <nocheck> tag to allow for skipping of the spell checker due to the many spelling mistakes within the base HL7 render.

All examples relating to the profile, including those for extensions in the profile, SHALL be included within the Examples view. A profile SHALL have at least one example.

# StructureDefinition-England-[profile]

<div id="transpose">
@ ```
from
	StructureDefinition
where
	name = 'England[profile name]'
select
	Canonical_URL: url,
  Current_Version: version,
  Last_Updated: date,
	Description: description
```
</div>
<br>

@ ```
from
	StructureDefinition
where
	name = 'England[profile name]'
select
	Profile_Purpose: purpose
```

<nocheck>
<div class="tab fhirTree">
 <button class="tablinks active" onclick="openTab(event, 'Snapshot View')">Snapshot View</button>
  <button class="tablinks" onclick="openTab(event, 'Differential View')">Differential View</button>
  <button class="tablinks" onclick="openTab(event, 'Hybrid View')">Hybrid View</button>
   <button class="tablinks" onclick="openTab(event, 'Table View')">Table View</button>
   <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
  <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
  <button class="tablinks" onclick="openTab(event, 'Examples')">Examples</button>
</div>

<div id="Snapshot View" class="tabcontent" style="display:block">
  <h3>Snapshot View</h3>
{ {tree: https://fhir.nhs.uk/StructureDefinition/England-[profile], snapshot}}
</div>

<div id="Differential View" class="tabcontent">
  <h3>Differential View</h3>
{ {tree: https://fhir.nhs.uk/StructureDefinition/England-[profile], diff}}
</div>

<div id="Hybrid View" class="tabcontent">
  <h3>Hybrid View</h3>
{ {tree: https://fhir.nhs.uk/StructureDefinition/England-[profile], hybrid}}
</div>

<div id="Table View" class="tabcontent">
  <h3>Table View</h3>
{ {table: https://fhir.nhs.uk/StructureDefinition/England-[profile], snapshot}}
</div>

<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml: https://fhir.nhs.uk/StructureDefinition/England-[profile], snapshot}}
</div>

<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json: https://fhir.nhs.uk/StructureDefinition/England-[profile], snapshot}}
</div>

<div id="Examples" class="tabcontent">
  <h3>Examples</h3>
<b>[profile]</b> - An example to illustrate the [reason for example].
<br>{ {pagelink:Example-England-[profile]}}
</div>
</nocheck>

Profile Specific Implementation Guidance

This contains any relevant information specifically to the profile. Within this page it may contain use cases. The title SHALL be added to the index page, but any information below is optional.

## Profile Specific Implementation Guidance: ##

[add any specific implementation or use case guidance]

Extensions

Any extension referenced within the profile SHALL be added to the Extensions page and table, along with the element in which it is to be used and a link to the extension page within the IG.

If no information on the use of any extensions is needed, then the page SHALL be in the following format:

## Extensions

More information about the extensions can be found using the links below.

<table class="assets" title="Extension list">
<tr>
<th class="width20">Extension</th>
<th class="width20">Context</th>
<th class="width30">Link</th>
<th class="width30">Comment</th>
</tr>
<tr>
<td>[extension name]</td>
<td>[context of use]</td>
<td>{ {pagelink:Extension-England-[extension]}}</td>
<td>[information on the use of the extension]</td>
</tr>
</table>

---

Bindings

Any coding / CodeableConcept element within the profile or within an extension within the profile, that is bound to a England ValueSet, SHALL be added to the Bindings (differential) page and table, via a listing of the element in which it is to be used, the binding strength and a link to the ValueSet page within the IG.

## Bindings (differential)

More information about the bindings to NHS England ValueSets can be found below.

<table class="assets" title="Bindings list">
<tr>
<th class="width30">Context</th>
<th class="width20">Strength</th>
<th class="width50">Link</th>
</tr>
<tr>
<td>[context of use]</td>
<td>[strength]</td>
<td>{ {pagelink:ValueSet-England-[ValueSet]}}</td>
</tr>
</table>

---

Constraints

Any profile or profile element that has an additional constraint applied SHALL be added to the Constraints (differential) table, via a listing of the key, strength, expression and description of the constraint.

## Constraints (differential)

More information about the constraints on the <code>England-[profile]</code> profile can be found below.

<table class="assets" title="Constraints list">
<tr>
<th class="width15">Key</th>
<th class="width15">Severity</th>
<th class="width30">Expression</th>
<th class="width40">Human Description</th>
</tr>
<tr>
<td>[constraint key]</td>
<td>[strength]</td>
<td>[fhirpath criteria to be valid]
</td>
<td>[human readable description of valid criteria].</td>
</tr>
</table>

---

Elements in the expression SHALL be enclosed in <code> tags, e.g.

<code>effective</code>.exists() or (<code>effective</code>.empty() and (<code>status</code> in ('partial' | 'preliminary' | 'final' | 'amended' | 'corrected' | 'appended')).not())

Where the severity is a warning, the Human Description will say SHOULD, where the severity is error, it will say SHALL.

Profile Elements

Any profile element that has information relevant to NHS England and is different to HL7 or UK Core SHALL be documented on its own page. The name of the page SHALL be the element naming in camelCase. If the binding to the element differs from HL7 or NHSE IG then it SHALL be referenced here, along with the relevant page link. Initially, the information in each element comes from the definition or comment or requirement values that existed in the equivelant NHS Digital asset.

The words ‘optional’ or ‘mandatory’ relating to the element are no longer needed as this has been deemed as duplication of either the element cardinality or MVC.

The page SHALL use the following format:

## `{ {page-title}}`

[information]

---

Rules

Referencing Profiles

All Binding references within a profile SHALL be explicitly shown via the relevant element page, apart from the element identifier.assigner.

Links to active NHS England profiles SHALL be done using pagelink

Important

Links to draft profiles SHOULD only be present in IG's in development. An IG that is to be balloted SHOULD have these profiles referenced to base profiles, and these links swapped.

Links to HL7 resources SHALL be written as:

<a href="https://hl7.org/fhir/R4/[Resource].html">[Resource] Resource</a>

Referencing all profiles SHALL be done using the following sentences:

For a single resource:

The resource being referenced SHALL conform to { {pagelink:Profile-[profile]}}.

For a multiple resources, with at least one NHSE IG profile:

 The resource being referenced SHALL conform to one of the following: 
- { {pagelink:Profile-[profile]}}
- { {pagelink:Profile-[profile]}}

Where the reference is to Resource:

Where a NHSE IG profile exists the resource being referenced SHALL conform to the profile.

Identifier

If there are no recognised business identifiers, then do not create a page for identifier.

Slices

If an element has a slice, this SHOULD be identified in the text, for example:

The slice `ServiceRequest.category:genomicsWholeCaseSequencing` has been added to aid in identifying the category of service request for Genomics use cases.

Extensions

If an element has an extension, this SHOULD be identified in the text, for example:

`ServiceRequest.priority` has the NHS England extension { {pagelink:Extension-NHS England-PriorityReason}}.

Sub Element Guidance

Guidance for a sub element, e.g. [Resource].[element].[subelement], SHOULD be written on a page at the element level.

For example:

## <code>performer</code>

The resource referenced in `Procedure.performer.actor` SHALL conform to one the following:
- { {pagelink:Profile-Organization}}
- { {pagelink:Profile-Patient}}
- { {pagelink:Profile-Practitioner}}
- { {pagelink:Profile-PractitionerRole}}
- { {pagelink:Profile-RelatedPerson}}

The resource referenced in `Procedure.performer.onBehalfOf` SHALL conform to { {pagelink:Profile-Organization}}.

---

In line examples

If there is an inline example to be rendered, to provide an example of the usage of a specific resource element, the example SHOULD be prefixed with a fully qualified description of the usage:

#### Example of `Immunization.vaccineCode` usage:

And the inline example SHALL be in the following format:

<div class="tab">
 <button class="tablinks active" onclick="openTab(event, 'Table View')">Table View</button>
  <button class="tablinks" onclick="openTab(event, 'Tree View')">Tree View</button>
  <button class="tablinks" onclick="openTab(event, 'XML View')">XML View</button>
  <button class="tablinks" onclick="openTab(event, 'JSON View')">JSON View</button>
</div>

<div id="Table View" class="tabcontent" style="display:block">
  <h3>Table View</h3>
{ {table:NHS England-Immunization-Sn-AstraZenecaVaccine-Example}}
</div>

<div id="Tree View" class="tabcontent">
  <h3>Tree View</h3>
{ {tree:NHS England-Immunization-Sn-AstraZenecaVaccine-Example}}
</div>

<div id="XML View" class="tabcontent">
  <h3>XML View</h3>
{ {xml:NHS England-Immunization-Sn-AstraZenecaVaccine-Example}}
</div>

<div id="JSON View" class="tabcontent">
  <h3>JSON View</h3>
{ {json:NHS England-Immunization-Sn-AstraZenecaVaccine-Example}}
</div>

Non-unique sub headings

Where an element contains a heading for specific guidance, such as Display / Propogation / Consumer / Provider, with the same name as is used on another element, this guidance must have an unique id attribute, based on the element and heading:

<h3 id="clinical-codes-display">Display</h3>

<h3 id="original-term-text-display">Display</h3>