[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.11.0"
+pydantic = "^2.12.5"
 
 [tool.poetry]
 packages = [{include = "gateway_api", from = "src"},

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/R4/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 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 +0,0 @@
-"""FHIR data types and resources."""
-
-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",
-]

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

@@ -0,0 +1,27 @@
+"""FHIR R4 data types and resources."""
+
+from .elements.identifier import Identifier, NHSNumberValueIdentifier, UUIDIdentifier
+from .elements.issue import Issue, IssueCode, IssueSeverity
+from .elements.meta import Meta
+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",
+    "Meta",
+    "NHSNumberValueIdentifier",
+    "OperationOutcome",
+    "Patient",
+    "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/meta.py

@@ -0,0 +1,31 @@
+import datetime
+from dataclasses import dataclass
+from typing import Annotated
+
+from pydantic import Field
+
+
+@dataclass(frozen=True)
+class Meta:
+    """
+    A FHIR R4 Meta element. See https://hl7.org/fhir/R4/datatypes.html#Meta.
+    Attributes:
+        version_id: The version id of the resource.
+        last_updated: The last updated timestamp of the resource.
+    """
+
+    last_updated: Annotated[datetime.datetime | None, Field(alias="lastUpdated")] = None
+    version_id: Annotated[str | None, Field(alias="versionId")] = None
+
+    @classmethod
+    def with_last_updated(cls, last_updated: datetime.datetime | None = None) -> "Meta":
+        """
+        Create a Meta instance with the provided last_updated timestamp.
+        Args:
+            last_updated: The last updated timestamp.
+        Returns:
+            A Meta instance with the specified last_updated.
+        """
+        return cls(
+            last_updated=last_updated or datetime.datetime.now(tz=datetime.timezone.utc)
+        )