FHIR Data Standards Wales for PSOM v1.0.0-rc2
Important: This is the release candidate of the FHIR Data Standards Wales for PSOM version 1.0.0-rc2 Implementation Guide. It is intended for trial use, and is published for early comment and feedback. Click here to give feedback.

Profiling Guidelines

Introduction

This page lays out the conventions for creating FHIR profiles and associated conformance resources for the NHS Wales PSOM project. These guidelines are specifically aimed at FHIR R4. This page is titled 'profiling guidelines', but actually addresses all conformance resources (Profiles, Extensions, ValueSets, CodeSystems, CapabilityStatements) and associated examples. We use these terms somewhat interchangeable throughout this document; 'profile' can usually be read as 'the whole set of conformance resources'.

Implementation Guide formatting

The following formatting is applied to Resource names, elements and values.

Resource name

Resource names shall be PascalCased e.g.:

  • CarePlan
  • MessageHeader
  • Task

Resource elements

Resource elements shall be camelCased and in between backticks e.g.:

  • .valueCoding
  • .reasonCode

Values

Values or codes for a specific element shall be in italics e.g.:

  • psom-cancellation
  • accepted

Functional model as base

The PSOM FHIR specifications are fundamentally based on DSCNs and LPDSs. A pivotal component driving FHIR profiling is the 'DSCN 48 ViH PROMs Metadata'. Profiles are crafted to document the representation of DSCNs and LPDSs in FHIR.

Technical layering

Conformance resources, including profiles, adhere to a hierarchical layering of information standards. Three distinct levels of profiles are recognized:

  • UK Core Profiles
    • These are foundational profiles applicable across the United Kingdom.
  • FHIR Standards Wales Profiles
    • These profiles are ideally derived from UK Core profiles and are tailored for NHS Wales systems.
  • FHIR PSOM Wales
    • These are use case-specific profiles, preferably based on FHIR Standards Wales or, alternatively, UK Core profiles. They are designed to support the PSOM use case within NHS Wales.

Associating the functional definition to StructureDefinitions

Each of the PSOM profiles SHALL have a traceable relationship with the Metadata elements. The StructureDefinition.mapping and ElementDefinition.mapping elements serve to associate functional concepts with the resource elements within the profile. The root StructureDefinition.mapping element provides the link to the underlying functional definition and SHALL consist of at least two components:

  • StructureDefinition.mapping.identity: An identifier used within the profile to link resource elements to this mapping. The value is formulated as: 'PROMs-Metadata-[version]'.
  • StructureDefinition.mapping.name: This is a descriptive label for the mapping, fixed as 'NHS Wales DSCN Metadata Mapping'.

Consequently, the root element of the StructureDefinition should define the mapping as follows:

<mapping>
    <identity value="PROMs-Metadata-2024004" />
    <name value="NHS Wales DSCN Metadata Mapping" />
</mapping>

Within a profile, the ElementDefinition.mapping element is used to map a Metadata element to a corresponding FHIR resource element. The following attributes SHALL be specified:

  • ElementDefinition.mapping.identity: This attribute SHALL match the `StructureDefinition.mapping.identity`` to indicate the version of the Metadata DSCN.
  • ElementDefinition.mapping.map: This attribute SHALL contain the specific Item Reference associated with the Metadata element.
  • ElementDefinition.mapping.comment: This attribute SHALL contain the specific Name of the Metadata element.

Here is how a Metadata element should be mapped to a specific element within the profile:

    <element id="CarePlan.identifier">
        <path value="CarePlan.identifier" />
        <mapping>
            <identity value="PROMs-Metadata-2024004" />
            <map value="MPRPX004X" />
            <comment value="Referral Identifier"/>
        </mapping>
    </element>

In addition to the mapping attributes, the ElementDefinition.short attribute SHALL also contain the specific Name of the Metadata element. This serves to provide an additional layer of metadata annotation within the profile.

Implicit Mappings and Profile Creation Criteria

Profiles within this project are created only when there is a need to set specific constraints on FHIR resources. If the sole requirement is to map Metadata DSCN elements to FHIR elements, profiles will not be created. Instead, a mapping table will be provided in this Implementation Guide to handle such cases.

In instances where Metadata DSCN elements cannot be directly mapped to elements in the PSOM profiles, implicit mappings are recommended. This approach facilitates the seamless integration of Metadata elements without necessitating additional profile creation.

Implicit mappings are incorporated into resource elements within existing PSOM profiles that reference another profile capable of accommodating the Metadata element in question. For such mappings, the following attributes SHALL be specified:

  • ElementDefinition.mapping.identity: This attribute contains the applicable value of StructureDefinition.mapping.identity.
  • ElementDefinition.mapping.map: This attribute SHALL contain the specific Item Reference associated with the Metadata element.
  • ElementDefinition.mapping.comment: This attribute is modified to indicate the implicit nature of the mapping. It SHALL contain the Name of the Metadata element and specify the main element path where the mapping occurs, formatted as '[Name] (implicit, main mapping is on [element path])'.

Here is an example of how an implicit mapping should be defined:

    <element id="CarePlan.subject">
        <path value="CarePlan.subject"/>
            <mapping>
                <identity value="PROMs-Metadata-2024004"/>
                <map value="MPDPX003X"/>
                <comment value="Given Name (implicit, main mapping is on Patient.name.given)"/>
            </mapping>
    </element>

Profiling Strategy

The profiling strategy aims to strike a balance between providing detailed guidance for implementers and ensuring reusability and forward compatibility. The level of restrictions in a profile is contingent upon its intended purpose, which may range from documentation to technical validation.

Guiding Principles

To reconcile the need for both specificity and flexibility, we adopt an 'open world' modelling approach. This approach allows for broader reusability while still accommodating necessary constraints and requirements. The following principles govern the creation and management of these profiles:

  • Element Constraints: Only elements that are part of the mapping shall be constrained.
  • Data Set Mappings: All profiles shall include mappings to elements in the corresponding data set.
  • Target Profile Constraints: Only target profiles that are relevant to the mapping shall be constrained.
  • MustSupport Attribute: The mustSupport attribute shall not be used. The presence of a mapping should be interpreted by implementers as a general encouragement to support the element, signifying that a semantic understanding exists.

By adhering to these principles, we aim to create profiles that serve as effective guides for implementation while also being adaptable for various use cases and future needs.

The Task and Questionnaire profiles are heavily influenced by the SDC Implementation Guide.

Example Artifacts

Examples are crafted to align with the DataStandardsWales-PSOM profiles. These examples are intentionally minimalistic, capturing only the PSOM metadata elements or the requisite FHIR elements. When appropriate, the examples are derived from pre-existing DataStandardsWales examples.

Questionnaires

Questionnaires are generated directly from the DSCNs/LPDSs whenever feasible. The elements of a Questionnaire are mapped from corresponding columns in the DSCN as outlined below:

Questionnaire Element DSCN Column Name
.version PROMs Tool/Character Code
.item.linkId Question Reference
.item.text Question Text
.item.type with .item.answerValueSet if Value Set is specified; choice
.item.type if Value Set/Example is Free text; string
.item.type if Value Set/Example is Score/Scale; integer or decimal
.item.answerValueSet Value Set

The Data Item Name, also known as Field Name, is not directly mapped to a Questionnaire element. Instead, this column is utilised for naming the corresponding CodeSystem and ValueSet. When the Value Set/Example column indicates no return value, this aspect is omitted in the Questionnaire, as it is not intended to be filled in by patients.

Implications

Given that Questionnaires are not directly filled in by users, not all attributes are defined, such as:

  • .item.required
  • .item.enableWhen
  • .item.readOnly
  • .item.initial

Questionnaire Terminology

CodeSystems and ValueSets for Questionnaires are crafted to represent the possible answers to a question within a DSCN. For readability, all codes from the CodeSystem are individually included in the ValueSet, rather than incorporating the entire CodeSystem.

Health Boards/Trusts are prohibited from sharing any national PSOM work with external parties or suppliers without the explicit written consent of the Welsh Value in Health Centre. Additionally, the information contained in the Questionnaires must not be used to reproduce a PROM questionnaire form, as this would constitute a breach of copyright from the PROM author. Users must ensure compliance with the terms set forth by the license holder for any PROM questionnaires utilised.

To ensure that consumers of the profiles are aware of these license restrictions, copyright statements are strategically placed in the following locations:

  • Implementation Guide: FHIR Data Standards Wales for PSOM
    • Homepage
    • FHIR Artefacts PSOM Index page
  • Simplifier Projects for DSCN and LPDS
    • Project introduction page
    • Project banner
  • DSCN PROMS FHIR Resources
    • Questionnaire.copyright
    • ValueSet.copyright
    • CodeSystem.copyright
  • GitHub Repository README Files

Versioning and Releases

This project employs package-level versioning as the principal mechanism for versioning FHIR artifacts. In this approach, individual artifacts within a package are not versioned independently; instead, they comprise a cohesive set governed by a single version identifier. The versioning strategy adheres to the principles of Semantic Versioning.

Pre-release versions are designated with the suffixes '-alpha', '-beta', and '-rc', which may be further enumerated with a numerical value (e.g. '-rc1', '-rc2'). The '-alpha' suffix signifies a pre-release version subject to breaking changes. The '-beta' suffix indicates a feature-complete pre-release version ready for extensive testing. The '-rc' suffix, standing for Release Candidate, represents the version closest to being production-ready.

It is important to note that updates to conformance resources generally do not alter their canonical URLs.

Publication management

PSOM FHIR artefacts are versioned and released using FHIR NPM packages. When a new package version is released, release notes must be included. In addition to the package, a new version of the Implementation Guide is also published. This ensures that all stakeholders are aware of any changes and can implement the new version of the package correctly.