NRL-1554 Add new content retrieval mechanism extension

Author: eesa456

api/consumer/swagger.yaml

@@ -810,10 +810,12 @@ components:
         extension:
           type: array
           items:
-            $ref: "#/components/schemas/ContentStabilityExtension"
+            oneOf:
+              - $ref: "#/components/schemas/ContentStabilityExtension"
+              - $ref: "#/components/schemas/RetrievalMechanismExtension"
             description: Additional extension for content stability.
           minItems: 1
-          maxItems: 1
+          maxItems: 2
       required:
         - attachment
         - format
@@ -975,6 +977,53 @@ 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", "NDR"]
+            display:
+              type: string
+              enum:
+                ["Spine Secure Proxy", "National Document Repository", "Direct"]
+          required:
+            - system
+            - code
+            - display
     NRLFormatCode:
       allOf:
         - $ref: "#/components/schemas/Coding"

api/producer/swagger.yaml

@@ -1415,10 +1415,12 @@ components:
         extension:
           type: array
           items:
-            $ref: "#/components/schemas/ContentStabilityExtension"
+            oneOf:
+              - $ref: "#/components/schemas/ContentStabilityExtension"
+              - $ref: "#/components/schemas/RetrievalMechanismExtension"
             description: Additional extension for content stability.
           minItems: 1
-          maxItems: 1
+          maxItems: 2
       required:
         - attachment
         - format
@@ -1631,6 +1633,53 @@ 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", "NDR"]
+            display:
+              type: string
+              enum:
+                ["Spine Secure Proxy", "National Document Repository", "Direct"]
+          required:
+            - system
+            - code
+            - display
     NRLFormatCode:
       allOf:
         - $ref: "#/components/schemas/Coding"

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-08-07T11:40:24+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", "NDR"]
+    display: Literal["Spine Secure Proxy", "National Document Repository", "Direct"]
+
+
 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]],
+        Field(max_length=2, min_length=1),
     ]
 
 

layer/nrlf/core/constants.py

@@ -680,6 +680,14 @@ def coding_value(self):
 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",
+    "NDR": "National Document Repository",
+}
 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,16 +3,24 @@
 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.constants import (
+    CONTENT_FORMAT_CODE_URL,
+    CONTENT_RETRIEVAL_SYSTEM_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
 from nrlf.producer.fhir.r4.model import OperationOutcome, OperationOutcomeIssue
 
 
 def format_error_location(loc: List) -> str:
+    # List of extension class names to exclude from error paths
+    exclude_classes = {"ContentStabilityExtension", "RetrievalMechanismExtension"}
+    filtered_loc = [each for each in loc if each not in exclude_classes]
+
     formatted_loc = ""
-    for each in loc:
+    for each in filtered_loc:
         if isinstance(each, int):
             formatted_loc = f"{formatted_loc}[{each}]"
         else:
@@ -26,7 +34,7 @@ def append_value_set_url(loc_string: str) -> str:
 
     if "content" in loc_string:
         if "extension" in loc_string:
-            return f". See ValueSet: {CONTENT_STABILITY_SYSTEM_URL}"
+            return f". See ValueSets: {CONTENT_STABILITY_SYSTEM_URL} & {CONTENT_RETRIEVAL_SYSTEM_URL}"
         if "format" in loc_string:
             return f". See ValueSet: {CONTENT_FORMAT_CODE_URL}"
 

layer/nrlf/core/tests/test_pydantic_errors.py

@@ -99,6 +99,11 @@ def test_validate_content_multiple_content_stability_extensions():
         document_ref_data["content"][0]["extension"][0]
     )
 
+    # Add a third duplicate contentStability extension
+    document_ref_data["content"][0]["extension"].append(
+        document_ref_data["content"][0]["extension"][0]
+    )
+
     with pytest.raises(ParseError) as error:
         validator.validate(document_ref_data)
 
@@ -116,7 +121,7 @@ def test_validate_content_multiple_content_stability_extensions():
                 }
             ]
         },
-        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension: List should have at most 1 item after validation, not 2. See ValueSet: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability)",
+        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension: List should have at most 2 items after validation, not 3. See ValueSets: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability & https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism)",
         "expression": ["content[0].extension"],
     }
 
@@ -133,7 +138,6 @@ def test_validate_content_invalid_content_stability_code():
         validator.validate(document_ref_data)
 
     exc = error.value
-    assert len(exc.issues) == 1
     assert exc.issues[0].model_dump(exclude_none=True) == {
         "severity": "error",
         "code": "invalid",
@@ -146,7 +150,7 @@ def test_validate_content_invalid_content_stability_code():
                 }
             ]
         },
-        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension[0].valueCodeableConcept.coding[0].code: Input should be 'static' or 'dynamic'. See ValueSet: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability)",
+        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension[0].valueCodeableConcept.coding[0].code: Input should be 'static' or 'dynamic'. See ValueSets: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability & https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism)",
         "expression": ["content[0].extension[0].valueCodeableConcept.coding[0].code"],
     }
 
@@ -163,7 +167,6 @@ def test_validate_content_invalid_content_stability_display():
         validator.validate(document_ref_data)
 
     exc = error.value
-    assert len(exc.issues) == 1
     assert exc.issues[0].model_dump(exclude_none=True) == {
         "severity": "error",
         "code": "invalid",
@@ -176,7 +179,7 @@ def test_validate_content_invalid_content_stability_display():
                 }
             ]
         },
-        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension[0].valueCodeableConcept.coding[0].display: Input should be 'Static' or 'Dynamic'. See ValueSet: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability)",
+        "diagnostics": "Failed to parse DocumentReference resource (content[0].extension[0].valueCodeableConcept.coding[0].display: Input should be 'Static' or 'Dynamic'. See ValueSets: https://fhir.nhs.uk/England/CodeSystem/England-NRLContentStability & https://fhir.nhs.uk/England/CodeSystem/England-RetrievalMechanism)",
         "expression": [
             "content[0].extension[0].valueCodeableConcept.coding[0].display"
         ],
@@ -195,7 +198,6 @@ def test_validate_content_invalid_content_stability_system():
         validator.validate(document_ref_data)
 
     exc = error.value
-    assert len(exc.issues) == 1
     assert exc.issues[0].model_dump(exclude_none=True) == {
         "severity": "error",
         "code": "invalid",
@@ -224,7 +226,6 @@ def test_validate_content_invalid_content_stability_url():
         validator.validate(document_ref_data)
 
     exc = error.value
-    assert len(exc.issues) == 1
     assert exc.issues[0].model_dump(exclude_none=True) == {
         "severity": "error",
         "code": "invalid",