Wales FHIR Implementation Guide

Naming Conventions

These naming conventions are applicable to FHIR conformance (i.e. StructureDefinition, CodeSystem, ConceptMap, ValueSet, etc.) resources published within Data Standards Wales FHIR profiles and as part of this implementation guide.

Naming Segments

The naming conventions defined here use the following naming segments:

[base URL]: The base URL is https://fhir.nhs.wales/

[ResourceType]: The FHIR resource type e.g. 'StructureDefinition', 'CodeSystem', 'ConceptMap', 'Patient', or 'MedicationStatement'.

[BusinessName]: The business name of the resource. For CodeSystem and ValueSet, the business name shall reflect the name given to the data set as published in the relevant Data Standards Change Notice (DSCN). For ConceptMap resources, the business name shall reflect the name given to the value set that is being mapped from.

[Organisation]: NamingSystem resources may be 'owned' by a particular organisation. In this case use initials e.g. ABUHB (Aneurin Bevan University Health Board), VUNHST (Velindre University NHS Trust) etc. to identify the organisation.

Naming Conventions for Profiles

The following naming convention applies to the FHIR profiles defined in this guide:

The logical id of the profile shall be in the form DataStandardsWales-[ResourceType] e.g.

DataStandardsWales-Patient
DataStandardsWales-MedicationStatement

The URL of the profile shall be in the form [base URL]/StructureDefinition/DataStandardsWales-[ResourceType] e.g.

https://fhir.nhs.wales/StructureDefinition/DataStandardsWales-Patient
https://fhir.nhs.wales/StructureDefinition/DataStandardsWales-MedicationStatement

The name of the profile - specifically the name.value.element - shall be in the form DataStandardsWales[ResourceType] e.g.

DataStandardsWalesPatient
DataStandardsWalesMedicationStatement

The title of the profile shall follow the name.value.element, using title case e.g.

Data Standards Wales Patient
Data Standards Wales Medication Statement

The filename of the profile shall be in the form Profile-DataStandardsWales-[ResourceType] e.g.

Profile-DataStandardsWales-Patient
Profile-DataStandardsWales-MedicationStatement

Naming Conventions for Elements

The fields within a profile that store information are called elements. Any core element name is unchangeable and is dictated by HL7 and UK Core depending on who created the element. We can however create our own which will always follow the camelCase naming convention like inherited elements already do. This also applies to any custom extensions that we may create.

Naming Conventions for Extensions

The following naming convention applies to the FHIR extensions defined in this guide:

The logical id of the extension shall be in the form Extension-DataStandardsWales-[BusinessName] e.g.

Extension-DataStandardsWales-MedicationCourseOfTherapyType
Extension-DataStandardsWales-Occupation

The URL of the extension shall be in the form [base URL]/StructureDefinition/Extension-DataStandardsWales-[BusinessName] e.g.

https://fhir.nhs.wales/StructureDefinition/Extension-DataStandardsWales-MedicationCourseOfTherapyType
https://fhir.nhs.wales/StructureDefinition/Extension-DataStandardsWales-Occupation

The name of the extension - specifically the name.value.element - shall be in the form ExtensionDataStandardsWales[BusinessName] e.g.

ExtensionDataStandardsWalesMedicationCourseOfTherapyType
ExtensionDataStandardsWalesOccupation

The title of the extension shall follow the name.value.element, using title case e.g.

Extension Data Standards Wales Medication Course Of Therapy Type
Extension Data Standards Wales Occupation

The filename of the extension shall be in the form Extension-DataStandardsWales-[BusinessName] e.g.

Extension-DataStandardsWales-MedicationCourseOfTherapyType
Extension-DataStandardsWales-Occupation

Naming Conventions for CodeSystem and ValueSet Resources

The following naming convention applies to FHIR CodeSystem and ValueSet resources:

The logical id of the resource shall be in the form DataStandardsWales-[BusinessName] e.g.

DataStandardsWales-Sex
DataStandardsWales-Title

The URL of the resource shall be in the form [base URL]/[ResourceType]/DataStandardsWales-[BusinessName] e.g.

https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Sex
https://fhir.nhs.wales/ValueSet/DataStandardsWales-Title

The name of the resource - specifically the name.value.element - shall be in the form DataStandardsWales[BusinessName] e.g.

DataStandardsWalesSex
DataStandardsWalesTitle

The title of the resource shall follow the name.value.element, using title case e.g.

Data Standards Wales Sex
Data Standards Wales Title

The filename of the resource shall be in the form [ResourceType]-DataStandardsWales-[BusinessName] e.g.

CodeSystem-DataStandardsWales-Sex
ValueSet-DataStandardsWales-Title

Naming Conventions for ConceptMap Resources

The following naming convention applies to FHIR ConceptMap resources:

The logical id of the resource shall be in the form DataStandardsWales-[BusinessNameValueSetSource]-[BusinessNameValueSetTarget] e.g.

DataStandardsWales-UKCoreBirthSex-Sex
DataStandardsWales-GenderIdentity-HL7AdministrativeGender

The URL of the resource shall be in the form [base URL]/[ResourceType]/DataStandardsWales-[BusinessNameValueSetSource]-[BusinessNameValueSetTarget] e.g.

https://fhir.nhs.wales/ConceptMap/DataStandardsWales-UKCoreBirthSex-Sex
https://fhir.nhs.wales/ConceptMap/DataStandardsWales-GenderIdentity-HL7AdministrativeGender

The name of the resource - specifically the name.value.element - shall be in the form DataStandardsWales-ConceptMap-[BusinessNameValueSetSource]-to-[BusinessNameValueSetTarget] e.g.

DataStandardsWales-ConceptMap-UKCoreBirthSex-to-Sex
DataStandardsWales-ConceptMap-GenderIdentity-to-HL7AdministrativeGender

The title of the resource - specifically the name.value.element - shall be in the form Data Standards Wales Concept Map from [Business Name ValueSet Source] to [Business Name ValueSet Target] e.g.

Data Standards Wales Concept Map from UK Core Birth Sex to Sex
Data Standards Wales Concept Map from Gender Identity to HL7 Administrative Gender

The filename of the resource shall be in the form Data Standards Wales Concept Map from [Business Name ValueSet Source] to [Business Name ValueSet Target] e.g.

ConceptMap-DataStandardsWales-UKCoreBirthSex-Sex
ConceptMap-DataStandardsWales-GenderIdentity-HL7AdministrativeGender

Naming Conventions for NamingSystem Resources

The following naming convention applies to FHIR NamingSystem resources:

The logical id of the NamingSystem shall be in the form DataStandardsWales-[Organisation]-[BusinessName1]-[BusinessName2] e.g.

DataStandardsWales-ABUHB-PAS-PatientIdentifier
DataStandardsWales-LIMS-identifier

The filename of the NamingSystem shall be in the form NamingSystem-[BusinessName] e.g.

NamingSystem-ABUHB-pas-identifier
NamingSystem-LIMS-identifier

Naming Conventions for File Paths and Identifiers

Some file names may become very long depending on the information they are trying to convey. Asset identifiers generally inherit these names and may become invalid if they are over 64 characters, are not alpha numeric, or contain special characters (excluding -). File paths over 260 characters for certain windows systems will also cause problems due to operating system limits. Due to the above the file name and identifiers may have to diverge. The resources impacted the most are examples due to the increased amount of information they're attempting to convey.

The following considerations should be made to prevent this:

Only alphanumeric characters and some special characters (recommend only hyphens -) should be use in file names and identifiers
Ensure nested folder names use minimal characters
Do not nest folders beyond a reasonable amount
Keep full file paths well below 260 characters
Try to keep the file name to the lowest amount of characters while maintaining context
The file name may be longer and provide more context than the identifier.
Use NHS Wales standard abbreviations where possible (e.g. ABUHB or PAS)
If the name/identifier can be conveyed in under 64 characters then do not use any abbreviation
If the name/identifier would be over 64 characters then:
- Abbreviate some of the terms in the end of the file (e.g. full blood count becomes FBC)
- If that is not enough, abbreviate DataStandardsWales to DSW in order to not completely lose the context in the full name
- If this does not resolve the issue then the identifier/name should be reconsidered

Example ValueSet

A fully populated ValueSet example is provided below to demonstrate the naming convention in use:

XML View
JSON View

<ValueSet xmlns="http://hl7.org/fhir">
    <id value="DataStandardsWales-Title" />
    <text>
        <status value="generated" />
        --- We have skipped the narrative for better readability of the resource ---
    </text>
    <url value="https://fhir.nhs.wales/ValueSet/DataStandardsWales-Title" />
    <version value="1.0.1" />
    <name value="DataStandardsWalesTitle" />
    <title value="Data Standards Wales Title" />
    <status value="active" />
    <experimental value="false" />
    <date value="2023-11-10" />
    <publisher value="NHS Wales" />
    <contact>
        <name value="Data Standards" />
        <telecom>
            <system value="email" />
            <value value="data.standards@wales.nhs.uk" />
            <use value="work" />
        </telecom>
    </contact>
    <description value="Title" />
    <copyright value="2023 NHS Wales." />
    <compose>
        <include>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <filter>
                <property value="Status" />
                <op value="=" />
                <value value="active" />
            </filter>
        </include>
    </compose>
    <expansion>
        <timestamp value="2023-08-02T00:00:00+01:00" />
        <total value="11" />
        <offset value="0" />
        <parameter>
            <name value="version" />
            <valueUri value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title|1.0.0" />
        </parameter>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Admr" />
            <display value="Admiral" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Baron" />
            <display value="Baron" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Brig" />
            <display value="Brigadier" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Bshp" />
            <display value="Bishop" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Can" />
            <display value="Canon" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Capt" />
            <display value="Captain" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Col" />
            <display value="Colonel" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Dame" />
            <display value="Dame" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Dr" />
            <display value="Doctor" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Ftr" />
            <display value="Father" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Lady" />
            <display value="Lady" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Lord" />
            <display value="Lord" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Miss" />
            <display value="Miss" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Mjr" />
            <display value="Major" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Mr" />
            <display value="Mr" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Mrs" />
            <display value="Mrs" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Ms" />
            <display value="Ms" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Mstr" />
            <display value="Master" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Mx" />
            <display value="Mx" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Prof" />
            <display value="Professor" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Rev" />
            <display value="Reverend" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Sgt" />
            <display value="Sergeant" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Sir" />
            <display value="Sir" />
        </contains>
        <contains>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <code value="Sstr" />
            <display value="Sister" />
        </contains>
    </expansion>
</ValueSet>

{
    "resourceType": "ValueSet",
    "id": "DataStandardsWales-Title",
    "text": {
        "status": "generated",
        --- We have skipped the narrative for better readability of the resource ---
    },
    "url": "https://fhir.nhs.wales/ValueSet/DataStandardsWales-Title",
    "version": "1.0.1",
    "name": "DataStandardsWalesTitle",
    "title": "Data Standards Wales Title",
    "status": "active",
    "experimental": false,
    "date": "2023-11-10",
    "publisher": "NHS Wales",
    "contact":  [
        {
            "name": "Data Standards",
            "telecom":  [
                {
                    "system": "email",
                    "value": "data.standards@wales.nhs.uk",
                    "use": "work"
                }
            ]
        }
    ],
    "description": "Title",
    "copyright": "2023 NHS Wales.",
    "compose": {
        "include":  [
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "filter":  [
                    {
                        "property": "Status",
                        "op": "=",
                        "value": "active"
                    }
                ]
            }
        ]
    },
    "expansion": {
        "timestamp": "2023-08-02T00:00:00+01:00",
        "total": 11,
        "offset": 0,
        "parameter":  [
            {
                "name": "version",
                "valueUri": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title|1.0.0"
            }
        ],
        "contains":  [
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Admr",
                "display": "Admiral"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Baron",
                "display": "Baron"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Brig",
                "display": "Brigadier"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Bshp",
                "display": "Bishop"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Can",
                "display": "Canon"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Capt",
                "display": "Captain"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Col",
                "display": "Colonel"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Dame",
                "display": "Dame"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Dr",
                "display": "Doctor"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Ftr",
                "display": "Father"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Lady",
                "display": "Lady"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Lord",
                "display": "Lord"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Miss",
                "display": "Miss"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Mjr",
                "display": "Major"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Mr",
                "display": "Mr"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Mrs",
                "display": "Mrs"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Ms",
                "display": "Ms"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Mstr",
                "display": "Master"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Mx",
                "display": "Mx"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Prof",
                "display": "Professor"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Rev",
                "display": "Reverend"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Sgt",
                "display": "Sergeant"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Sir",
                "display": "Sir"
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "code": "Sstr",
                "display": "Sister"
            }
        ]
    }
}