General Rules

• Information SHALL be unique to UK Core. There SHOULD NOT be any duplication of HL7 FHIR content nor any information within the profile unless it gives context for additional UK Core 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 UK Core.
• 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 UK core 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

Headers

Hyperlinks

Note: External links SHALL have class="external" set.

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 YAML Headers for more details.

Note: When linking to an Asset on a different Simplifier IG, the link SHALL only include a ?version= url parameter if a specific published version is to be targetted. By not includeing a ?version= url parameter, the link will automatically target the default (published or current) version.

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>UKCore-MedicationAdministrationCategory</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>

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>MedicationDispense.authorizingPrescription.identifier</code> element rather than adding the <code>MedicationRequest</code> as a bundle - to avoid duplication.
</div>

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 UK Core, 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.

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 { {render: command, which can work across projects and organisations.

For example, the Glossary is rendered via:

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

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>

Checklists

Profile Checklist

A checklist to be used when creating or modifying a profile.

Extension Checklist

A checklist to be used when creating or modifying an extension.

ValueSet Checklist

A checklist to be used when creating or modifying a ValueSet.

CodeSystem Checklist

A checklist to be used when creating or modifying a ValueSet.

Example Checklist

A checklist to be used when creating or modifying an example.

Extension Layout

Extensions SHALL have a page within the ‘All Extensions’ folder with the naming convention of ‘Extension UKCore-[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:

---
subject: [Extension URL]
issue: [Extension ID]
---
## StructureDefinition { {variable:issue}}

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

{ {page:Home/ProfilesandExtensions/ExtensionTemplate.page.md}}

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

<h3 id="guidance-{ {variable:issue}}">Extension Specific Guidance</h3>
[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 UKCore-EthnicCategory, and you must ensure the pages within the folder are in alphabetical order.

The layout SHALL be in the following format:

---
subject: [ValueSet URL]
issue: [ValueSet id]
---
## UK Core [ValueSet Title]

{ {page:Home/Terminology/AllValueSets/ValueSetTemplate.page.md}}

The page SHALL be referenced within table on the ‘ValueSets and Codesystems’ page in all tab indexes.

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 UKCore-EthnicCategoryEngland, and you must ensure the pages within the folder are in alphabetical order.

The page SHALL be referenced within table on the ‘ValueSets and CodeSystems’ page in the ‘Narrative’ index under the appropriate ValueSet, and the ‘Alphabetical (CodeSystems)’ index.

The layout SHALL be in the following format:

---
subject: [CodeSystem URL]
issue: [CodeSystem id]
---
## UK Core [CodeSystem title]

{ {page:Home/Terminology/AllCodeSystems/CodeSystemTemplate.page.md}}

Example Layout

Each example SHALL have its own page within either the ‘Profile Examples’ or ‘Extension Examples’ folder, listed in alphabetical order. The page SHALL be named ‘Example UKCore-[Example id]’.

Each example SHALL be referenced within table on the ‘Examples Index’ page in all tab indexes.

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:

---
subject: UKCore-[Resource]-[Reason]-Example
---
### An example to illustrate the [reason for example]

{ {page:Home/Examples/ExampleTemplate.page.md}}

Profile Layout

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

Each Profile SHALL be referenced within table on the 'Profiles Index’ page in all tab indexes.

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
• Example Usage Scenarios
• Profile Specific Implementation Guidance
• Mandatory and MustSupport Content

YAML Headers

A UK Core profile index page should have four YAML headers:

• 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 usage, the canonical url for the base resource, which allows Simplifier fql commands to determine refrerences to this profile
• a issue, the id for the resource, which allows Simplifier FQL and variables to display

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 url]
usage: [base url]
issue: [resource id]
---

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 UKCore-[ValuesetName], the default generated topic is ok.

StructureDefinition

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.

Profile pages built for STU3 Ballot and beyond, SHALL have a system within the YAML header, and can replace the snapshot / differential / hybrid tabs, with a single TreeView tab, and utilize the new Simplifier buttons, as these render the page faster. In addition, these should include the new Usage tab. These can all be done via a template.

# StructureDefinition { {variable:issue}}

<nocheck>
{ {page:Home/ProfilesandExtensions/ProfileTemplate.page.md}}

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

Example Usage Scenarios

Any example use cases that are specific to the profile and relevant to the UK Core can be added here. If there are no examples, then this section is not to be added to the page. If there are example, then it SHALL be in the following format:

<div id="ProfileGuidance">
### Example Usage Scenarios

The following are feasible use cases for the UK Core [profile] profile:

- [usage scenario]. 

---

Profile Specific Implementation Guidance

This contains any relevant information specifically to the profile. Within this page it may contain use cases or the minimum viable content. 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]

If a profile is derived, it SHALL include a { {pagelink}} to the parent profile as per the examples below:

## Profile Specific Implementation Guidance: ##

This is a derived profile of { {pagelink:Profile-Observation,text:UKCore-Observation}} and this page only shows the differences between the two. Refer to the base Profile for more implementation guidance.

or

## Profile Specific Implementation Guidance: ##

The UKCore-Observation-VitalSigns-BloodPressure profile further derives from { {pagelink:Profile-Observation-VitalSigns,text:UKCore-Observation-VitalSigns}} and this page only shows the differences between the two. Refer to { {pagelink:Profile-Observation,text:UKCore-Observation}} and { {pagelink:Profile-Observation-VitalSigns,text:UKCore-Observation-VitalSigns}} for more implementation guidance.

Mandatory and MustSupport Content

The MustSupport content is any element in which has information that the provider and consumer systems SHOULD send or collect and SHALL have a MustSupport flag AND short set. Note, if mandatory root level data elements (e.g. 1..1 or 1..*) are present then these SHALL have MustSupportflag ANDshort` and be included in the table.

This SHALL be determined by use cases, and by analysis of the MustSupport flags used by other FHIR IG's, such as US Core, Aus Base, Wales DHCW, NHSE IG, HL7 EU Lab.

If a profile is not derived, the MustSupport section can be rendered via a template

{ {page:Home/ProfilesandExtensions/ProfileMustSupportTemplate.page.md}}

If a profile is derived, it SHALL include a { } to the parent profile as per the examples below, and include a table of elements.

### Mandatory and Must Support Data Elements

The following elements, in addition to those in the corresponding { {pagelink:Profile-Observation,text:UKCore-Observation}} parent profile, are identified as MustSupport, and it is expected that consumers and suppliers SHALL support these as per the { {pagelink:Guidance-MustSupport}}.

<table class="assets" title="MustSupport element list">
<tr>
<th class="width30">Element</th>
<th class="width70">Reason</th>
</tr>
<tr>
<td><code>Observation.value[x]</code></td>
<td>A quantity SHALL be present.</td>
</tr>
</table>

or

The following elements, in addition to those of the the corresponding { {pagelink:Profile-Observation,text:UKCore-Observation}} and { {pagelink:Profile-Observation-VitalSigns,text:UKCore-Observation-VitalSigns}} parent profiles, are identified as MustSupport, and it is expected that consumers and suppliers SHALL support these as per the { {pagelink:Guidance-MustSupport}}.

<table class="assets" title="MustSupport element list">
<tr>
<th class="width30">Element</th>
<th class="width70">Reason</th>
</tr>
<tr>
<td><code>Observation.value[x]</code></td>
<td>A quantity SHALL be present.</td>
</tr>
</table>

This section must end with:

</div>

---

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:

If there are only standard UK Core Extensions:

{ {page:Home/ProfilesandExtensions/ProfileExtensionsTemplate.page.md}}

---

If there are R5 pre-adopted backport Extensions AND / OR HL7 core defined Extensions:

## 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>bodyPosition</td>
<td>Observation</td>
<td><a href="https://hl7.org/fhir/R4/extension-observation-bodyPosition.html">Core-defined Extension observation-bodyPosition</a></td>
<td></td>
</tr>
<tr>
<td>bodyStructureR5</td>
<td>Observation</td>
<td>{ {pagelink:Extension-UKCore-ObservationBodyStructure}}</td>
<td>This is a pre-adopted R5 element, for more details, see { {pagelink:Library-Extensions-PreAdopt}}.</td>
</tr>
</table>

---

Bindings

Any coding / CodeableConcept element with a binding within the profile SHALL be rendered via FQL. Any CodeableConcept element with a binding within an extension within the profile, that is bound to a UKCore ValueSet, SHALL be added to 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.

No Extensions with bindings:

{ {page:Home/ProfilesandExtensions/ProfileBindingsTemplate.page.md}}

---

Where an Extension with binding exists:

{ {page:Home/ProfilesandExtensions/ProfileBindingsTemplate.page.md}}

<table class="addToBindings">
<tr>
<td>MedicationStatement.extension:medicationPrescribingOrganizationType</td>
<td>extensible</td>
<td>{ {pagelink:ValueSet-UKCore-MedicationPrescribingOrganizationType}}</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.

{ {page:Home/ProfilesandExtensions/ProfileConstraintsTemplate.page.md}}

---

Elements in the Human Description SHALL be enclosed in markdown ` tags.

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 the UKCore and is different to HL7 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 then it SHALL be referenced here, along with the relevant page link.

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 UKCore profiles SHALL be done using pagelink

Links to draft profiles SHALL be written as

[UKCore-CarePlan (draft)](https://simplifier.net/guide/UKCoreImplementationGuideAssetsinDevelopment/Home/ProfilesandExtensions/Profile-UKCore-CarePlan)

Links to HL7 resources SHALL be written as:

[[Resource] Resource](https://hl7.org/fhir/R4/[Resource].html)

Referencing all profiles SHALL be done using the following sentences:

• For a single resource:

Where possible, it is expected that the resource being referenced SHOULD conform to  { {pagelink:Profile-[profile]}}.

• For a multiple resources, with at least one UK Core profile:

Where possible, it is expected that the resource being referenced SHOULD conform to one of the following UK Core profiles:
- { {pagelink:Profile-[profile]}}
- { {pagelink:Profile-[profile]}}

• Where the reference is to Resource:

Where a UK Core profile exists the resource being referenced SHOULD 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, included it's discriminatorfor 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 UKCore extension { {pagelink:Extension-UKCore-PriorityReason}}.

Sub Element Guidance

Guidance for a sub element, e.g. [Resource].[element].[subelement], SHALL 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, '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:UKCore-Immunization-Sn-AstraZenecaVaccine-Example}}
</div>

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

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

If a profile element contains more than one inline example they SHALL each be contained within their own parent 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>