Merge pull request #1005 from NHSDigital/feature/eema1-NRL-1554-ContentRetrievalMechanismExtension

NRL-1554 Add new content retrieval mechanism extension

Author: axelkrastek1-nhs

api/consumer/swagger.yaml

@@ -810,10 +810,12 @@ components:
         extension:
           type: array
           items:
-            $ref: "#/components/schemas/ContentStabilityExtension"
-            description: Additional extension for content stability.
+            oneOf:
+              - $ref: "#/components/schemas/ContentStabilityExtension"
+              - $ref: "#/components/schemas/RetrievalMechanismExtension"
+              - $ref: "#/components/schemas/Extension"
+            description: Additional extensions which include Content Stability and Retrieval Mechanism.
           minItems: 1
-          maxItems: 1
       required:
         - attachment
         - format
@@ -975,6 +977,52 @@ components:
             - system
             - code
             - display
+    RetrievalMechanismExtension:
+      allOf:
+        - $ref: "#/components/schemas/Extension"
+        - type: object
+          properties:
+            url:
+              type: string
+              enum:
+                - "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-RetrievalMechanism"
+            valueCodeableConcept:
+              $ref: "#/components/schemas/RetrievalMechanismExtensionValueCodeableConcept"
+          required:
+            - url
+            - valueCodeableConcept
+    RetrievalMechanismExtensionValueCodeableConcept:
+      allOf:
+        - $ref: "#/components/schemas/CodeableConcept"
+        - type: object
+          properties:
+            coding:
+              type: array
+              items:
+                $ref: "#/components/schemas/RetrievalMechanismExtensionCoding"
+              minItems: 1
+              maxItems: 1
+          required:
+            - coding
+    RetrievalMechanismExtensionCoding:
+      allOf:
+        - $ref: "#/components/schemas/Coding"
+        - type: object
+          properties:
+            system:
+              type: string
+              enum:
+                - "https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism"
+            code:
+              type: string
+              enum: ["SSP", "Direct", "LDR"]
+            display:
+              type: string
+              enum: ["Spine Secure Proxy", "Direct", "Large Document Retrieval"]
+          required:
+            - system
+            - code
+            - display
     NRLFormatCode:
       allOf:
         - $ref: "#/components/schemas/Coding"
@@ -990,12 +1038,14 @@ components:
               enum:
                 - "urn:nhs-ic:record-contact"
                 - "urn:nhs-ic:unstructured"
+                - "urn:nhs-ic:structured"
               description: The code representing the format of the document.
             display:
               type: string
               enum:
                 - "Contact details (HTTP Unsecured)"
                 - "Unstructured Document"
+                - "Structured Document"
               description: The display text for the code.
           required:
             - system

api/producer/swagger.yaml

@@ -1415,10 +1415,12 @@ components:
         extension:
           type: array
           items:
-            $ref: "#/components/schemas/ContentStabilityExtension"
-            description: Additional extension for content stability.
+            oneOf:
+              - $ref: "#/components/schemas/ContentStabilityExtension"
+              - $ref: "#/components/schemas/RetrievalMechanismExtension"
+              - $ref: "#/components/schemas/Extension"
+            description: Additional extensions which include Content Stability and Retrieval Mechanism.
           minItems: 1
-          maxItems: 1
       required:
         - attachment
         - format
@@ -1631,6 +1633,52 @@ components:
             - system
             - code
             - display
+    RetrievalMechanismExtension:
+      allOf:
+        - $ref: "#/components/schemas/Extension"
+        - type: object
+          properties:
+            url:
+              type: string
+              enum:
+                - "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-RetrievalMechanism"
+            valueCodeableConcept:
+              $ref: "#/components/schemas/RetrievalMechanismExtensionValueCodeableConcept"
+          required:
+            - url
+            - valueCodeableConcept
+    RetrievalMechanismExtensionValueCodeableConcept:
+      allOf:
+        - $ref: "#/components/schemas/CodeableConcept"
+        - type: object
+          properties:
+            coding:
+              type: array
+              items:
+                $ref: "#/components/schemas/RetrievalMechanismExtensionCoding"
+              minItems: 1
+              maxItems: 1
+          required:
+            - coding
+    RetrievalMechanismExtensionCoding:
+      allOf:
+        - $ref: "#/components/schemas/Coding"
+        - type: object
+          properties:
+            system:
+              type: string
+              enum:
+                - "https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism"
+            code:
+              type: string
+              enum: ["SSP", "Direct", "LDR"]
+            display:
+              type: string
+              enum: ["Spine Secure Proxy", "Direct", "Large Document Retrieval"]
+          required:
+            - system
+            - code
+            - display
     NRLFormatCode:
       allOf:
         - $ref: "#/components/schemas/Coding"
@@ -1646,12 +1694,14 @@ components:
               enum:
                 - "urn:nhs-ic:record-contact"
                 - "urn:nhs-ic:unstructured"
+                - "urn:nhs-ic:structured"
               description: The code representing the format of the document.
             display:
               type: string
               enum:
                 - "Contact details (HTTP Unsecured)"
                 - "Unstructured Document"
+                - "Structured Document"
               description: The display text for the code.
           required:
             - system

layer/nrlf/consumer/fhir/r4/model.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  swagger.yaml
-#   timestamp: 2025-06-13T14:43:32+00:00
+#   timestamp: 2025-09-05T08:22:10+00:00
 
 from __future__ import annotations
 
@@ -240,6 +240,12 @@ class ContentStabilityExtensionCoding(Coding):
     display: Literal["Static", "Dynamic"]
 
 
+class RetrievalMechanismExtensionCoding(Coding):
+    system: Literal["https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism"]
+    code: Literal["SSP", "Direct", "LDR"]
+    display: Literal["Spine Secure Proxy", "Direct", "Large Document Retrieval"]
+
+
 class NRLFormatCode(Coding):
     system: Annotated[
         Literal["https://fhir.nhs.uk/England/CodeSystem/England-NRLFormatCode"],
@@ -501,6 +507,12 @@ class ContentStabilityExtensionValueCodeableConcept(CodeableConcept):
     ]
 
 
+class RetrievalMechanismExtensionValueCodeableConcept(CodeableConcept):
+    coding: Annotated[
+        List[RetrievalMechanismExtensionCoding], Field(max_length=1, min_length=1)
+    ]
+
+
 class RequestHeader(Parent):
     odsCode: RequestHeaderOdsCode
 
@@ -574,6 +586,13 @@ class ContentStabilityExtension(Extension):
     valueCodeableConcept: ContentStabilityExtensionValueCodeableConcept
 
 
+class RetrievalMechanismExtension(Extension):
+    url: Literal[
+        "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-RetrievalMechanism"
+    ]
+    valueCodeableConcept: RetrievalMechanismExtensionValueCodeableConcept
+
+
 class OperationOutcome(Parent):
     resourceType: Literal["OperationOutcome"]
     id: Annotated[
@@ -633,7 +652,8 @@ class DocumentReferenceContent(Parent):
         ),
     ]
     extension: Annotated[
-        List[ContentStabilityExtension], Field(max_length=1, min_length=1)
+        List[Union[ContentStabilityExtension, RetrievalMechanismExtension, Extension]],
+        Field(min_length=1),
     ]
 
 

layer/nrlf/core/constants.py

@@ -677,9 +677,18 @@ def coding_value(self):
 CONTENT_STABILITY_EXTENSION_URL = (
     "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-ContentStability"
 )
+CONTENT_RETRIEVAL_EXTENSION_URL = "https://fhir.nhs.uk/England/StructureDefinition/Extension-England-RetrievalMechanism"
 CONTENT_STABILITY_SYSTEM_URL = (
     "https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability"
 )
+CONTENT_RETRIEVAL_SYSTEM_URL = (
+    "https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism"
+)
+CONTENT_RETRIEVAL_CODE_MAP = {
+    "Direct": "Direct",
+    "SSP": "Spine Secure Proxy",
+    "LDR": "Large Document Retrieval",
+}
 CONTENT_FORMAT_CODE_URL = "https://fhir.nhs.uk/England/CodeSystem/England-NRLFormatCode"
 CONTENT_FORMAT_CODE_MAP = {
     "urn:nhs-ic:record-contact": "Contact details (HTTP Unsecured)",

layer/nrlf/core/errors.py

@@ -3,7 +3,6 @@
 from pydantic import ValidationError
 from pydantic_core import ErrorDetails
 
-from nrlf.core.constants import CONTENT_FORMAT_CODE_URL, CONTENT_STABILITY_SYSTEM_URL
 from nrlf.core.response import Response
 from nrlf.core.types import CodeableConcept
 from nrlf.producer.fhir.r4 import model as producer_model
@@ -20,28 +19,25 @@ def format_error_location(loc: List) -> str:
     return formatted_loc
 
 
-def append_value_set_url(loc_string: str) -> str:
-    if loc_string.endswith(("url", "system")):
-        return ""
-
-    if "content" in loc_string:
-        if "extension" in loc_string:
-            return f". See ValueSet: {CONTENT_STABILITY_SYSTEM_URL}"
-        if "format" in loc_string:
-            return f". See ValueSet: {CONTENT_FORMAT_CODE_URL}"
-
-    return ""
-
-
-def diag_for_error(error: ErrorDetails) -> str:
+def diag_for_error(error: ErrorDetails, value_set: str, root_location: tuple) -> str:
     loc_string = format_error_location(error["loc"])
+    if root_location:
+        loc_string = format_error_location(root_location) + "." + loc_string
+
     msg = f"{loc_string or 'DocumentReference'}: {error['msg']}"
-    msg += append_value_set_url(loc_string)
+    msg += f", see: {value_set}" if value_set else ""
     return msg
 
 
-def expression_for_error(error: ErrorDetails) -> Optional[str]:
-    return format_error_location(error["loc"]) or "DocumentReference"
+def expression_for_error(error: ErrorDetails, root_location: tuple) -> Optional[str]:
+    loc_string = format_error_location(error["loc"]) or "DocumentReference"
+    if root_location and error["loc"]:
+        loc_string = (
+            format_error_location(root_location)
+            + "."
+            + format_error_location(error["loc"])
+        )
+    return loc_string
 
 
 class OperationOutcomeError(Exception):
@@ -91,15 +87,20 @@ def __init__(self, issues: List[OperationOutcomeIssue]):
 
     @classmethod
     def from_validation_error(
-        cls, exc: ValidationError, details: CodeableConcept, msg: str = ""
+        cls,
+        exc: ValidationError,
+        details: CodeableConcept,
+        msg: str = "",
+        value_set: str = "",
+        root_location: tuple = None,
     ):
         issues = [
             producer_model.OperationOutcomeIssue(
                 severity="error",
                 code="invalid",
                 details=details,  # type: ignore
-                diagnostics=f"{msg} ({diag_for_error(error)})",
-                expression=[expression_for_error(error)],  # type: ignore
+                diagnostics=f"{msg} ({diag_for_error(error, value_set, root_location)})",
+                expression=[expression_for_error(error, root_location)],  # type: ignore
             )
             for error in exc.errors()
         ]