[GPCAPIM-305]: Create common Pydantic FHIR types

.github/agents/unit_test.agent.md

@@ -19,6 +19,9 @@ You are an expert unit test writer for this project.
 - **File Structure:**
   - `gateway-api/src/**/*.py` – Files and folders that require unit tests (you READ from here)
   - `gateway-api/src/**/test_*.py` – All unit tests (you WRITE to here)
+- **Running tests:**
+  - `make test-unit` to run all unit tests
+  - `poetry run pytest path/to/test` from `gateway-api/` to runs specific tests.
 
 ## Unit test practices
 

.github/instructions/copilot-instructions.md

@@ -14,11 +14,11 @@ After deploying the container locally, `make test` will run all tests and captur
 
 Individual test suites can be run with:
 
-- Unit tests: `make unit`
-- Acceptance tests: `make acceptance`
-- Integration tests: `make integration`
-- Schema tests: `make schema`
-- Contract tests: `make contract`
+- Unit tests: `make test-unit`
+- Acceptance tests: `make test-acceptance`
+- Integration tests: `make test-integration`
+- Schema tests: `make test-schema`
+- Contract tests: `make test-contract`
 
 The container must be running in order to successfully run any of the test suites other than the unit tests.
 

.vscode/cspell-dictionary.txt

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

Makefile

@@ -37,7 +37,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

@@ -55,6 +55,16 @@ paths:
                   type: string
                   enum: ["Parameters"]
                   example: "Parameters"
+                meta:
+                  type: object
+                  properties:
+                    lastUpdated:
+                      type: string
+                      format: date-time
+                      example: "2026-01-12T10:00:00Z"
+                    versionId:
+                      type: string
+                      example: "1"
                 parameter:
                   type: array
                   minItems: 1
@@ -76,7 +86,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.33.0"
 pyjwt = "^2.12.0"
+pydantic = "^2.0"
 
 [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/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/elements/identifier.py

@@ -0,0 +1,33 @@
+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 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

gateway-api/src/fhir/elements/test_elements.py

@@ -0,0 +1,88 @@
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from fhir.elements.identifier import Identifier
+
+
+class TestIdentifierInitSubclass:
+    def test_subclass_sets_expected_system(self) -> None:
+        class _Custom(Identifier, expected_system="https://example.com"):
+            pass
+
+        assert _Custom._expected_system == "https://example.com", (
+            "_expected_system should be set by __init_subclass__"
+        )
+
+    def test_multiple_subclasses_have_independent_expected_system(self) -> None:
+        class _A(Identifier, expected_system="system-a"):
+            pass
+
+        class _B(Identifier, expected_system="system-b"):
+            pass
+
+        assert _A._expected_system == "system-a", (
+            "_A._expected_system should be 'system-a'"
+        )
+        assert _B._expected_system == "system-b", (
+            "_B._expected_system should be 'system-b'"
+        )
+
+    def test_subclass_without_expected_system_raises(self) -> None:
+        with pytest.raises(TypeError):
+
+            class _Bad(Identifier):  # type: ignore[call-arg]
+                pass
+
+
+class TestIdentifierModelValidate:
+    def test_valid_system_passes_validation(self) -> None:
+        class _TestId(Identifier, expected_system="https://example.com"):
+            pass
+
+        class _Container(BaseModel):
+            identifier: _TestId
+
+        result = _Container.model_validate(
+            {"identifier": {"system": "https://example.com", "value": "abc-123"}}
+        )
+
+        assert result.identifier.system == "https://example.com", (
+            "system should match the expected system"
+        )
+        assert result.identifier.value == "abc-123", "value should be 'abc-123'"
+
+    def test_invalid_system_fails_validation(self) -> None:
+        class _TestId(Identifier, expected_system="expected-system"):
+            pass
+
+        class _Container(BaseModel):
+            identifier: _TestId
+
+        with pytest.raises(
+            ValidationError,
+            match="Identifier system 'invalid-system' does not match expected "
+            "system 'expected-system'.",
+        ):
+            _Container.model_validate(
+                {"identifier": {"system": "invalid-system", "value": "some-value"}}
+            )
+
+    def test_missing_value_fails_validation(self) -> None:
+        class _TestId(Identifier, expected_system="sys"):
+            pass
+
+        class _Container(BaseModel):
+            identifier: _TestId
+
+        with pytest.raises(ValidationError):
+            _Container.model_validate({"identifier": {"system": "sys"}})
+
+    def test_missing_system_fails_validation(self) -> None:
+        class _TestId(Identifier, expected_system="sys"):
+            pass
+
+        class _Container(BaseModel):
+            identifier: _TestId
+
+        with pytest.raises(ValidationError):
+            _Container.model_validate({"identifier": {"value": "v"}})