Merge pull request #449 from NHSDigital/feature/eja-eli-414-spin-our-own-FHIR-operation-outcome

feat: replace fhir-resources with lightweight pydantic models

Author: eddalmond1

poetry.lock

@@ -30,7 +30,6 @@ eval-type-backport = "^0.2.2"
 mangum = "^0.19.0"
 wireup = "^2.1.0"
 python-json-logger = "^3.3.0"
-fhir-resources = "^8.0.0"
 python-dateutil = "^2.9.0"
 pyhamcrest = "^2.1.0"
 boto3 = "^1.40.57"
@@ -91,6 +90,8 @@ ignore = ["COM812", "D"]
 [tool.pyright]
 include = ["src/"]
 pythonVersion = "3.13"
+venvPath = "."
+venv = ".venv"
 
 [tool.pytest.ini_options]
 log_cli = true

pyproject.toml

@@ -1,68 +1,77 @@
 repos:
-- repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.0.1
-  hooks:
-    - id: check-added-large-files
-    - id: check-case-conflict
-    - id: check-merge-conflict
-    - id: check-yaml
-    - id: detect-aws-credentials
-      args: [--allow-missing-credentials]
-    - id: end-of-file-fixer
-    - id: trailing-whitespace
-    - id: mixed-line-ending
-- repo: local
-  hooks:
-  - id: scan-secrets
-    name: Scan secrets
-    entry: ./scripts/githooks/scan-secrets.sh
-    args: ["check=staged-changes"]
-    language: script
-    pass_filenames: false
-- repo: local
-  hooks:
-  - id: check-file-format
-    name: Check file format
-    entry: ./scripts/githooks/check-file-format.sh
-    args: ["check=staged-changes"]
-    language: script
-    pass_filenames: false
-- repo: local
-  hooks:
-  - id: check-markdown-format
-    name: Check Markdown format
-    entry: ./scripts/githooks/check-markdown-format.sh
-    args: ["check=staged-changes"]
-    language: script
-    pass_filenames: false
-- repo: local
-  hooks:
-  - id: check-english-usage
-    name: Check English usage
-    entry: ./scripts/githooks/check-english-usage.sh
-    args: ["check=staged-changes"]
-    language: script
-    pass_filenames: false
-- repo: local
-  hooks:
-  - id: lint-terraform
-    name: Lint Terraform
-    entry: ./scripts/githooks/check-terraform-format.sh
-    language: script
-    pass_filenames: false
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.7
-  hooks:
-    - id: ruff
-      args: [ --fix ]
-    - id: ruff-format
-- repo: https://github.com/RobertCraigie/pyright-python
-  rev: v1.1.394
-  hooks:
-  - id: pyright
-- repo: https://github.com/milin/giticket
-  rev: v1.3
-  hooks:
-    - id: giticket
-      args: [ '--regex=(?i)ELID-\d+', '--format=[{ticket}] {commit_msg}', '--mode=regex_match' ]
-      stages: [commit-msg]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: detect-aws-credentials
+        args: [--allow-missing-credentials]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+  - repo: local
+    hooks:
+      - id: scan-secrets
+        name: Scan secrets
+        entry: ./scripts/githooks/scan-secrets.sh
+        args: ["check=staged-changes"]
+        language: script
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: check-file-format
+        name: Check file format
+        entry: ./scripts/githooks/check-file-format.sh
+        args: ["check=staged-changes"]
+        language: script
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: check-markdown-format
+        name: Check Markdown format
+        entry: ./scripts/githooks/check-markdown-format.sh
+        args: ["check=staged-changes"]
+        language: script
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: check-english-usage
+        name: Check English usage
+        entry: ./scripts/githooks/check-english-usage.sh
+        args: ["check=staged-changes"]
+        language: script
+        pass_filenames: false
+  - repo: local
+    hooks:
+      - id: lint-terraform
+        name: Lint Terraform
+        entry: ./scripts/githooks/check-terraform-format.sh
+        language: script
+        pass_filenames: false
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: poetry run pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+  - repo: https://github.com/milin/giticket
+    rev: v1.3
+    hooks:
+      - id: giticket
+        args:
+          [
+            '--regex=(?i)ELID-\d+',
+            "--format=[{ticket}] {commit_msg}",
+            "--mode=regex_match",
+          ]
+        stages: [commit-msg]

scripts/config/pre-commit.yaml

@@ -5,10 +5,11 @@
 from enum import Enum
 from http import HTTPStatus
 
-from fhir.resources.operationoutcome import OperationOutcome, OperationOutcomeIssue
 from flask import make_response
 from flask.typing import ResponseReturnValue
 
+from eligibility_signposting_api.model.operation_outcome import OperationOutcome, OperationOutcomeIssue
+
 logger = logging.getLogger(__name__)
 
 
@@ -61,10 +62,10 @@ def build_operation_outcome_issue(self, diagnostics: str, location: list[str] |
         return OperationOutcomeIssue(
             severity=self.fhir_issue_severity,
             code=self.fhir_issue_code,
+            details=details,
             diagnostics=diagnostics,
             location=location,
-            details=details,
-        )  # pyright: ignore[reportCallIssue]
+        )
 
     def generate_response(self, diagnostics: str, location_param: str | None = None) -> ResponseReturnValue:
         issue_location = [f"parameters/{location_param}"] if location_param else None
@@ -73,9 +74,9 @@ def generate_response(self, diagnostics: str, location_param: str | None = None)
             id=str(uuid.uuid4()),
             meta={"lastUpdated": datetime.now(UTC)},
             issue=[self.build_operation_outcome_issue(diagnostics, issue_location)],
-        )  # pyright: ignore[reportCallIssue]
+        )
 
-        response_body = json.dumps(problem.model_dump(by_alias=True, mode="json"))
+        response_body = json.dumps(problem.model_dump(mode="json", exclude_none=True))
         return make_response(response_body, self.status_code, {"Content-Type": "application/fhir+json"})
 
     def log_and_generate_response(

src/eligibility_signposting_api/common/api_error_response.py

@@ -0,0 +1,73 @@
+"""
+FHIR OperationOutcome models for API error responses.
+
+Lightweight pydantic models for FHIR-compliant error responses without
+requiring the heavyweight fhir-resources package.
+
+See: https://www.hl7.org/fhir/operationoutcome.html
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class OperationOutcomeIssue(BaseModel):
+    """
+    FHIR OperationOutcome.Issue component.
+
+    Represents a single issue associated with an action.
+    """
+
+    severity: str = Field(
+        ...,
+        description="fatal | error | warning | information",
+    )
+    code: str = Field(
+        ...,
+        description="FHIR issue type code",
+    )
+    details: dict[str, Any] = Field(
+        ...,
+        description="Additional details about the error (CodeableConcept)",
+    )
+    diagnostics: str = Field(
+        ...,
+        description="Additional diagnostic information about the issue",
+    )
+    location: list[str] | None = Field(
+        default=None,
+        description="FHIRPath of element(s) related to issue",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class OperationOutcome(BaseModel):
+    """
+    FHIR OperationOutcome resource.
+
+    A collection of error, warning, or information messages that result
+    from a system action.
+    """
+
+    resourceType: str = Field(  # noqa: N815
+        default="OperationOutcome",
+        frozen=True,
+        description="FHIR resource type",
+    )
+    id: str | None = Field(
+        default=None,
+        description="Logical id of this artifact",
+    )
+    meta: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Metadata about the resource",
+    )
+    issue: list[OperationOutcomeIssue] = Field(
+        ...,
+        min_length=1,
+        description="A single issue associated with the action",
+    )
+
+    model_config = {"extra": "forbid"}

src/eligibility_signposting_api/model/operation_outcome.py

@@ -0,0 +1,23 @@
+"""Hamcrest matchers for FHIR OperationOutcome models."""
+
+from hamcrest.core.matcher import Matcher
+
+from eligibility_signposting_api.model.operation_outcome import OperationOutcome, OperationOutcomeIssue
+
+from .meta import BaseAutoMatcher
+
+
+class OperationOutcomeIssueMatcher(BaseAutoMatcher[OperationOutcomeIssue]): ...
+
+
+class OperationOutcomeMatcher(BaseAutoMatcher[OperationOutcome]): ...
+
+
+def is_operation_outcome_issue() -> Matcher[OperationOutcomeIssue]:
+    """Create a matcher for OperationOutcomeIssue."""
+    return OperationOutcomeIssueMatcher()
+
+
+def is_operation_outcome() -> Matcher[OperationOutcome]:
+    """Create a matcher for OperationOutcome."""
+    return OperationOutcomeMatcher()