NPA-5757: update schema for status and status reason description (#266)

# Pull Request

## 🧾 Ticket Link

<!-- Add the Jira ticket link here -->

https://nhsd-jira.digital.nhs.uk/browse/NPA-5757

---

## 📄 Description/Summary of Changes

<!-- Describe the changes made in this PR. Include the
purpose/scope/impact of the changes -->

- Updated the examples and description for the PATCH /Consent/{id}
endpoint to specify to supply statusReason along with status

---

## 🧪 Developer Testing Carried Out

<!-- Describe what tests (automated/unit/manual etc.) have been done for
the ticket. Include: -->
<!-- - Any tests added/updated -->
<!-- - Evidence that each acceptance criterion from the Jira ticket is
met -->

- Checked Swagger editor as docs changed

---

## 🧪 Reviewer Testing Required

<!-- Describe how to test the changes that have been made in the ticket.
Include: -->
<!-- - Testing environment details (e.g. sandbox/local setup) -->
<!-- - Steps to verify the changes -->

- [ ] <!-- Add bullet points for testing instructions -->
- [ ] <!-- Add bullet points for testing instructions -->
- [ ] <!-- Add bullet points for testing instructions -->

---

## ✅ Developer Checklist

<!-- Complete before submitting the PR -->

- [x] PR title follows the format: `NPA-XXXX: <short-description>`
- [x] Branch name follows the convention:
`<type>/NPA-XXXX/<short-description>`
- [x] Commit messages follow the template: `NPA-XXXX:
<short-description>`
- [ ] All acceptance criteria from the Jira ticket are addressed
- [ ] Automated tests (unit/integration/API/infrastructure etc. tests)
are added or updated
- [x] Assignees and appropriate labels (e.g. `terraform`,
`documentation`) are added

---

## 👀 Reviewer Checklist

<!-- To be completed by the reviewer -->

- [ ] Changes meet the acceptance criteria of the Jira ticket
- [ ] Code is able to be merged (no conflicts and adheres to coding
standards)
- [ ] Sufficient test evidence is provided (manual and/or automated)
- [ ] Infrastructure/operational/build changes are validated (if
applicable)

---

## 🚀 Post-merge

<!-- Actions to complete after merging -->

After merging and deploying changes to the sandbox, Postman collection
or spec examples please run the Run Postman
collection workflow.

This will run the tests within the collection to check that the sandbox
is working as expected once deployed.

---------

Co-authored-by: ellie-bound1-NHSD <[email protected]>

Author: ChristopherBacon

specification/examples/requests/PATCH_Consent/replace_legal_basis.yaml

@@ -7,9 +7,9 @@ ReplaceLegalBasisRequest:
       value:
         - role:
             coding:
-              - system: http://terminology.hl7.org/CodeSystem/v3-RoleCode
-                code: GUARD
-                display: Guardian
+              - system: https://fhir.nhs.uk/England/CodeSystem/England-NHSProxyLegalBasis
+                code: court-appointed-personal-welfare-deputy
+                display: Court appointed personal welfare deputy
           reference:
             type: RelatedPerson
             identifier:

specification/examples/requests/PATCH_Consent/replace_status.yaml

@@ -11,7 +11,7 @@ StatusUpdate:
       - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
         valueCodeableConcept:
           coding:
-          - system: http://terminology.hl7.org/CodeSystem/consent-reason
-            code: TBC
-            display: TBC
+          - system: https://terminology.hl7.org/CodeSystem/consent-reason
+            code: ROLE_CREATED
+            display: Role created from scratch by GP
 

specification/validated-relationships-service-api.yaml

@@ -942,6 +942,11 @@ paths:
         * JSON Patch operations must be valid according to RFC 6902
         * Status changes must use valid status codes from <http://hl7.org/fhir/consent-state-codes>
 
+         **IMPORTANT: Business Rule Enforcement**
+        If you update the `/status` of a role, you **MUST** also provide a corresponding update to the `/extension` path in the same patch array to provide the `statusReason`.
+
+        Requests that change status without providing a status reason will return an error
+
         ## Access modes
 
         This endpoint supports the following access modes:
@@ -992,12 +997,21 @@ paths:
                 summary: Set status to active with an end date
                 description: |
                   Example of a combined update to a record.
-                  The status will be changed to inactive.
+                  The status will be changed to active.
                   The relationship will be considered as ended following this date.
                 value:
                   - op: replace
                     path: /status
                     value: active
+                  - op: replace
+                    path: /extension
+                    value:
+                    - url: https://fhir.hl7.org.uk/StructureDefinition/Extension-statusReason
+                      valueCodeableConcept:
+                        coding:
+                        - system: http://terminology.hl7.org/CodeSystem/consent-reason
+                          code: "ROLE_ACTIVATED"
+                          display: "Role activated"
                   - op: replace
                     path: /provision/period/end
                     value: "2026-12-31"