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.0" />
    <name value="DataStandardsWalesTitle" />
    <title value="Data Standards Wales Title" />
    <status value="active" />
    <experimental value="false" />
    <date value="2023-08-02" />
    <publisher value="NHS Wales" />
    <contact>
        <telecom>
            <system value="email" />
            <value value="data.standards@wales.nhs.uk" />
        </telecom>
    </contact>
    <copyright value="2023 NHS Wales." />
    <compose>
        <include>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <version value="3.0" />
            <concept>
                <code value="Admr" />
                <display value="Admiral" />
            </concept>
            <concept>
                <code value="Baron" />
                <display value="Baron" />
            </concept>
            <concept>
                <code value="Brig" />
                <display value="Brigadier" />
            </concept>
            <concept>
                <code value="Bshp" />
                <display value="Bishop" />
            </concept>
            <concept>
                <code value="Can" />
                <display value="Canon" />
            </concept>
            <concept>
                <code value="Capt" />
                <display value="Captain" />
            </concept>
            <concept>
                <code value="Col" />
                <display value="Colonel" />
            </concept>
            <concept>
                <code value="Dame" />
                <display value="Dame" />
            </concept>
            <concept>
                <code value="Dr" />
                <display value="Doctor" />
            </concept>
            <concept>
                <code value="Ftr" />
                <display value="Father" />
            </concept>
            <concept>
                <code value="Lady" />
                <display value="Lady" />
            </concept>
            <concept>
                <code value="Lord" />
                <display value="Lord" />
            </concept>
            <concept>
                <code value="Miss" />
                <display value="Miss" />
            </concept>
            <concept>
                <code value="Mjr" />
                <display value="Major" />
            </concept>
            <concept>
                <code value="Mr" />
                <display value="Mr" />
            </concept>
            <concept>
                <code value="Mrs" />
                <display value="Mrs" />
            </concept>
            <concept>
                <code value="Ms" />
                <display value="Ms" />
            </concept>
            <concept>
                <code value="Mstr" />
                <display value="Master" />
            </concept>
            <concept>
                <code value="Mx" />
                <display value="Mx" />
            </concept>
            <concept>
                <code value="Prof" />
                <display value="Professor" />
            </concept>
            <concept>
                <code value="Rev" />
                <display value="Reverend" />
            </concept>
            <concept>
                <code value="Sgt" />
                <display value="Sergeant" />
            </concept>
            <concept>
                <code value="Sir" />
                <display value="Sir" />
            </concept>
            <concept>
                <code value="Sstr" />
                <display value="Sister" />
            </concept>
        </include>
        <include>
            <system value="https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title" />
            <version value="3.0" />
            <filter>
                <property value="Status" />
                <op value="=" />
                <value value="active" />
            </filter>
        </include>
    </compose>
</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",
    "name": "DataStandardsWalesTitle",
    "title": "Data Standards Wales Title",
    "status": "active",
    "version": "1.0.0",
    "date": "2023-08-02",
    "experimental": false,
    "publisher": "NHS Wales",
    "copyright": "2023 NHS Wales.",
    "contact":  [
        {
            "telecom":  [
                {
                    "system": "email",
                    "value": "data.standards@wales.nhs.uk"
                }
            ]
        }
    ],
    "compose": {
        "include":  [
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "version": "3.0",
                "concept":  [
                    {
                        "code": "Admr",
                        "display": "Admiral"
                    },
                    {
                        "code": "Baron",
                        "display": "Baron"
                    },
                    {
                        "code": "Brig",
                        "display": "Brigadier"
                    },
                    {
                        "code": "Bshp",
                        "display": "Bishop"
                    },
                    {
                        "code": "Can",
                        "display": "Canon"
                    },
                    {
                        "code": "Capt",
                        "display": "Captain"
                    },
                    {
                        "code": "Col",
                        "display": "Colonel"
                    },
                    {
                        "code": "Dame",
                        "display": "Dame"
                    },
                    {
                        "code": "Dr",
                        "display": "Doctor"
                    },
                    {
                        "code": "Ftr",
                        "display": "Father"
                    },
                    {
                        "code": "Lady",
                        "display": "Lady"
                    },
                    {
                        "code": "Lord",
                        "display": "Lord"
                    },
                    {
                        "code": "Miss",
                        "display": "Miss"
                    },
                    {
                        "code": "Mjr",
                        "display": "Major"
                    },
                    {
                        "code": "Mr",
                        "display": "Mr"
                    },
                    {
                        "code": "Mrs",
                        "display": "Mrs"
                    },
                    {
                        "code": "Ms",
                        "display": "Ms"
                    },
                    {
                        "code": "Mstr",
                        "display": "Master"
                    },
                    {
                        "code": "Mx",
                        "display": "Mx"
                    },
                    {
                        "code": "Prof",
                        "display": "Professor"
                    },
                    {
                        "code": "Rev",
                        "display": "Reverend"
                    },
                    {
                        "code": "Sgt",
                        "display": "Sergeant"
                    },
                    {
                        "code": "Sir",
                        "display": "Sir"
                    },
                    {
                        "code": "Sstr",
                        "display": "Sister"
                    }
                ]
            },
            {
                "system": "https://fhir.nhs.wales/CodeSystem/DataStandardsWales-Title",
                "version": "3.0",
                "filter":  [
                    {
                        "property": "Status",
                        "op": "=",
                        "value": "active"
                    }
                ]
            }
        ]
    }
}