[GPCAPIM-305]: Create common Pydantic FHIR types

.vscode/cspell-dictionary.txt

@@ -2,4 +2,5 @@ asid
 fhir
 getstructuredrecord
 gpconnect
+searchset
 usefixtures

Makefile

@@ -36,7 +36,7 @@ build-gateway-api: dependencies
 	@poetry run mypy --no-namespace-packages .
 	@echo "Packaging dependencies..."
 	@poetry build --format=wheel
-	@pip install "dist/gateway_api-0.1.0-py3-none-any.whl" --target "./target/gateway-api" --platform musllinux_1_2_x86_64 --only-binary=:all:
+	@pip install "dist/gateway_api-0.1.0-py3-none-any.whl" --target "./target/gateway-api" --platform musllinux_1_2_x86_64 --platform musllinux_1_1_x86_64 --only-binary=:all:
 	# Copy main file separately as it is not included within the package.
 	@rm -rf ../infrastructure/images/gateway-api/resources/build/
 	@mkdir ../infrastructure/images/gateway-api/resources/build/

gateway-api/openapi.yaml

@@ -76,7 +76,7 @@ paths:
                         properties:
                           system:
                             type: string
-                            minLength: 1
+                            enum: ["https://fhir.nhs.uk/Id/nhs-number"]
                             example: "https://fhir.nhs.uk/Id/nhs-number"
                           value:
                             type: string

gateway-api/pyproject.toml

@@ -14,6 +14,7 @@ flask = "^3.1.3"
 types-flask = "^1.1.6"
 requests = "^2.32.5"
 pyjwt = "^2.12.0"
+pydantic = "^2.0"
 
 [tool.poetry]
 packages = [{include = "gateway_api", from = "src"},
@@ -57,7 +58,6 @@ dev = [
     "types-requests (>=2.32.4.20250913,<3.0.0.0)",
     "types-pyyaml (>=6.0.12.20250915,<7.0.0.0)",
     "pytest-mock (>=3.15.1,<4.0.0)",
-    "pytest-nhsd-apim (>=6.0.6,<7.0.0)",
 ]
 
 [tool.mypy]

gateway-api/src/fhir/README.md

@@ -0,0 +1,76 @@
+# FHIR Types in Gateway API
+
+## What is FHIR?
+
+FHIR (Fast Healthcare Interoperability Resources) is the HL7 standard for exchanging healthcare information as structured resources over HTTP APIs.
+
+Read more on the standards: [R4](https://hl7.org/fhir/R4/overview.html) and [STU3](https://hl7.org/fhir/STU3/overview.html).
+
+In this codebase, the FHIR package provides strongly typed Python models for request validation, response parsing, and safe serialization.
+
+## FHIR versions in Clinical Data Sharing APIs
+
+Two FHIR versions are used:
+
+- STU3: used only for inbound Gateway API operation messages with `resourceType` Parameters (the Access Record Structured request payload).
+- R4: used for all other typed resources in this module, including PDS FHIR resources such as Patient.
+
+Version behaviour in the current flow:
+
+- Inbound request body is validated as STU3 Parameters.
+- Outbound provider response body is returned without transformation (mirrored payload).
+- PDS, SDS, and internal typed handling use R4 resource models.
+
+## How Pydantic is used
+
+This package uses Pydantic to make FHIR payload handling explicit and safe:
+
+- Model validation: model_validate(...) is used to parse inbound JSON into typed models.
+- Field aliasing: FHIR JSON names like `resourceType`, `fullUrl`, `lastUpdated` are mapped with `Field(alias=...)`.
+- Type constraints: `Annotated`, `Literal`, and `min_length` constraints enforce schema-like rules.
+- Runtime guards: validators check that `resourceType` and identifier system values match expected FHIR semantics.
+- Polymorphism: the Resource base type dispatches to the correct subclass from `resourceType`.
+- Serialization: `model_dump()`/`model_dump_json()` default to exclude_none=True to avoid emitting empty FHIR fields.
+
+Typical patterns in this code:
+
+- Parse JSON from API input or upstream systems into typed models.
+- Access domain properties (for example, `Patient.nhs_number`) instead of raw dictionary traversal.
+- Serialize models back to canonical FHIR JSON with aliases preserved.
+
+## Example usage
+
+The example below shows how to load a simple FHIR R4 Patient payload and obtain the GP ODS code.
+
+```python
+from fhir.r4 import Patient
+
+payload = {
+ "resourceType": "Patient",
+ "identifier": [
+  {
+   "system": "https://fhir.nhs.uk/Id/nhs-number",
+   "value": "9000000009",
+  }
+ ],
+ "generalPractitioner": [
+  {
+   "type": "Organization",
+   "identifier": {
+    "system": "https://fhir.nhs.uk/Id/ods-organization-code",
+    "value": "A12345",
+   },
+  }
+ ],
+}
+
+patient = Patient.model_validate(payload)
+
+nhs_number = patient.nhs_number
+gp_ods_code = patient.gp_ods_code
+
+print(nhs_number)   # 9000000009
+print(gp_ods_code)  # A12345
+```
+
+If `generalPractitioner` is missing, `patient.gp_ods_code` returns `None`.

gateway-api/src/fhir/__init__.py

@@ -1,22 +1,3 @@
-"""FHIR data types and resources."""
+from .resources.resource import Resource
 
-from fhir.bundle import Bundle, BundleEntry
-from fhir.general_practitioner import GeneralPractitioner
-from fhir.human_name import HumanName
-from fhir.identifier import Identifier
-from fhir.operation_outcome import OperationOutcome, OperationOutcomeIssue
-from fhir.parameters import Parameter, Parameters
-from fhir.patient import Patient
-
-__all__ = [
-    "Bundle",
-    "BundleEntry",
-    "HumanName",
-    "Identifier",
-    "OperationOutcome",
-    "OperationOutcomeIssue",
-    "Parameter",
-    "Parameters",
-    "Patient",
-    "GeneralPractitioner",
-]
+__all__ = ["Resource"]

gateway-api/src/fhir/r4/__init__.py

@@ -0,0 +1,25 @@
+"""FHIR data types and resources."""
+
+from .elements.identifier import Identifier, NHSNumberValueIdentifier, UUIDIdentifier
+from .elements.issue import Issue, IssueCode, IssueSeverity
+from .elements.reference import Reference
+from .resources.bundle import Bundle
+from .resources.device import Device
+from .resources.endpoint import Endpoint
+from .resources.operation_outcome import OperationOutcome
+from .resources.patient import Patient
+
+__all__ = [
+    "Bundle",
+    "Device",
+    "Endpoint",
+    "Identifier",
+    "Issue",
+    "IssueCode",
+    "IssueSeverity",
+    "OperationOutcome",
+    "Patient",
+    "NHSNumberValueIdentifier",
+    "Reference",
+    "UUIDIdentifier",
+]

gateway-api/src/fhir/r4/elements/identifier.py

@@ -0,0 +1,50 @@
+import uuid
+from abc import ABC
+from dataclasses import dataclass
+from typing import ClassVar
+
+from pydantic import model_validator
+
+
+@dataclass(frozen=True)
+class Identifier(ABC):
+    """
+    A FHIR R4 Identifier element. See https://hl7.org/fhir/R4/datatypes.html#Identifier.
+    Attributes:
+        system: The namespace for the identifier value.
+        value: The value that is unique within the system.
+    """
+
+    _expected_system: ClassVar[str] = "__unknown__"
+
+    value: str
+    system: str
+
+    @model_validator(mode="after")
+    def validate_system(self) -> "Identifier":
+        if self.system != self._expected_system:
+            raise ValueError(
+                f"Identifier system '{self.system}' does not match expected "
+                f"system '{self._expected_system}'."
+            )
+        return self
+
+    @classmethod
+    def __init_subclass__(cls, expected_system: str) -> None:
+        cls._expected_system = expected_system
+
+
+class UUIDIdentifier(Identifier, expected_system="https://tools.ietf.org/html/rfc4122"):
+    """A UUID identifier utilising the standard RFC 4122 system."""
+
+    def __init__(self, value: uuid.UUID | None = None):
+        super().__init__(
+            value=str(value or uuid.uuid4()),
+            system=self._expected_system,
+        )
+
+
+class NHSNumberValueIdentifier(
+    Identifier, expected_system="https://fhir.nhs.uk/Id/nhs-number"
+):
+    """A valueIdentifier NHS numbers - used in Parameter"""

gateway-api/src/fhir/r4/elements/issue.py

@@ -0,0 +1,26 @@
+from abc import ABC
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class IssueSeverity(StrEnum):
+    FATAL = "fatal"
+    ERROR = "error"
+    WARNING = "warning"
+    INFORMATION = "information"
+
+
+class IssueCode(StrEnum):
+    INVALID = "invalid"
+    EXCEPTION = "exception"
+
+
+@dataclass(frozen=True)
+class Issue(ABC):
+    """
+    A FHIR R4 OperationOutcome Issue element. See https://hl7.org/fhir/R4/datatypes.html#OperationOutcome.
+    """
+
+    severity: IssueSeverity
+    code: IssueCode
+    diagnostics: str | None = None

gateway-api/src/fhir/r4/elements/reference.py

@@ -0,0 +1,30 @@
+from typing import ClassVar
+
+from pydantic import BaseModel, Field, model_validator
+
+from .identifier import Identifier
+
+
+class Reference(BaseModel):
+    """A FHIR R4 Reference base class."""
+
+    _expected_reference_type: ClassVar[str] = "__unknown__"
+
+    identifier: Identifier
+    reference_type: str = Field(alias="type")
+
+    reference: str | None = None
+    display: str | None = None
+
+    def __init_subclass__(cls, reference_type: str) -> None:
+        cls._expected_reference_type = reference_type
+        super().__init_subclass__()
+
+    @model_validator(mode="after")
+    def validate_reference_type(self) -> "Reference":
+        if self.reference_type != self._expected_reference_type:
+            raise ValueError(
+                f"Reference type '{self.reference_type}' does not match expected "
+                f"type '{self._expected_reference_type}'."
+            )
+        return self