[ERSSUP-89272]-[]-[RM102a - Open API Specification (OAS) wording updates]-[NR]

nitishRastogiNHS · nitishRastogiNHS · commit e0589865ba74 · 2025-09-03T09:58:32.000+01:00
diff --git a/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml b/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml
@@ -35,6 +35,9 @@ description: |
     -  You can check if a cached service has changed via [[HYPERLINK_A037]].
     -  You can retrieve the attributes of an entire shortlist of services (1-20) via [[HYPERLINK_A035]].
 
+  ## Known Issues
+  The HealthcareService.type attribute is being returned as a singular object by this endpoint. As per the [FHIR standard](https://hl7.org/fhir/R4/), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
   ## Sandbox test scenarios
   You can test the following scenarios in our sandbox environment
   
diff --git a/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml b/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml
@@ -34,6 +34,9 @@ description: |
     -  You can check if a cached service has changed via [[HYPERLINK_A037]].
     -  You can fetch the attributes of a single service via [[HYPERLINK_A033]].
 
+  ## Known Issues
+  The HealthcareService.type attribute is being returned as a singular object by this endpoint. As per the [FHIR standard](https://hl7.org/fhir/R4/), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
   ## Sandbox test scenarios
   You can test the following scenarios in our sandbox environment
   
diff --git a/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml b/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml
@@ -4,6 +4,15 @@ description: |
   ## Overview
   Use this endpoint to retrieve a file that is attached to a referral or advice request.
 
+  Referral information can also include:
+    - Structured clinical information added by an integrated primary care system
+    - Service provider activity
+    - Advice and guidance conversation
+
+  This additional clinical information must be retrieved via [[HYPERLINK_A007]]
+
+  [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information.
+
   ## Supported security patterns
   - Application-restricted, unattended access
   - Healthcare worker, user-restricted access
diff --git a/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml b/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml
@@ -93,6 +93,11 @@ description: |
 
   You can retrieve reference data used in viewing a referral using [[HYPERLINK_A004]]
 
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
   ## Sandbox test scenarios
 
   You can test the following scenarios in our sandbox environment
diff --git a/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml b/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml
@@ -5,6 +5,10 @@ description: |
   
   Use this endpoint to generate a PDF file that summarises clinical information for a referral.
 
+  This does not include files attached to a referral or advice request. These must be retrieved via [[HYPERLINK_A042]]
+
+  [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information.
+
   ## Supported security patterns
   - Application-restricted access
   - Healthcare worker, user-restricted access
diff --git a/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml b/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml
@@ -10,7 +10,9 @@ description: |
   ## Important notes when creating a referral
   The maximum amount of services allowed on a given shortlist is 20.
   
-  The act of shortlisting alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted). 
+  The act of shortlisting alone will not result in a referral being sent/booked to any of the shortlisted services (even if only one service is shortlisted).
+  A shortlist of a single triage service should be avoided as this relies on the patient to progress the referral, potentially leading to a delay to care. Especially if the referral priority is 2WW or Urgent.
+
   Use [[HYPERLINK_A016]] if there is a need to support the sending/booking of the referral into a shortlisted service.
 
   ## Important notes when sending an e-Referral Pathway Start Date
@@ -60,6 +62,11 @@ description: |
 
   You can generate a letter for the patient, which summarises the current state of their referral and any steps the patient may need to follow, by using [[HYPERLINK_A019]].
 
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
 summary: Create referral (A011, FHIR STU3)
 operationId: a011-create-referral
 tags:
diff --git a/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml b/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml
@@ -75,6 +75,11 @@ description: |
   You can check to see what referral letter information has been added to a referral by using [[HYPERLINK_A005]], 
   [[HYPERLINK_A007]], and [[HYPERLINK_A006]] endpoints where necessary.
 
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
   ## Sandbox test scenarios
 
   You can test the following scenarios in our sandbox environment:
diff --git a/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml b/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml
@@ -41,6 +41,11 @@ description: |
   I need to accept an inbound referral after its review
 
   So that I can confirm the patient's referral is appropriate for the current service and booked appointment date/time.
+
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
   
 summary: Accept referral (A013, FHIR STU3)
 operationId: a013-accept-referral
diff --git a/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml b/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml
@@ -44,6 +44,11 @@ description: |
   I need to reject an inbound referral back to the referrer after its review with an explanation of why
 
   So that the referrer can address the reason for rejection and progress the referral appropriately.
+
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
   
 summary: Reject referral (A014, FHIR STU3)
 operationId: a014-reject-referral
diff --git a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml
@@ -24,6 +24,10 @@ description: |
 
   ## Important note
   You need to provide the 'commissioning rule organisation' when calling [[HYPERLINK_A015]] to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]].
+
+  When slots are retrieved using this endpoint, they can include slots with or without a named clinician associated with them. Your integrated application must support both scenarios.
+
+  Slots with a named clinician will have an additional "actor" which defines the SDS User ID of the clinician, this will be on the Schedule associated to the Slot.
   
   ## Related endpoints
 
@@ -34,6 +38,9 @@ description: |
     - when trying to book an appointment into a service, the slot advertised is no longer available
     - when trying to book an appointment into a service, no response is received within message timeout period (currently 2 minutes)
 
+  ## Known Issues
+  This endpoint is using the :Practitioner search parameter. The "schedule.actor" search parameter is incorrectly using the ":Practitioner" modifier. As per the [FHIR standard](https://hl7.org/fhir/R4/) the ":identifier" modifier should be used when searching to indicate that an Identifer is used rather than a literal, relative, internal or absolute reference. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
   ## Sandbox test scenarios
 
   You can test the following scenarios in our sandbox environment:
diff --git a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml
@@ -27,6 +27,12 @@ description: |
     - when trying to book an appointment into a service, the slot advertised is no longer available *or*
     - when trying to book an appointment into a service, no response is received within the message timeout period (currently 2 minutes)
 
+  ## Important note when booking slots
+
+  When appointment slots are booked using this endpoint, it may be necessary to provide the named clinician details. This is because slots can be setup with or without a named clinician. Your integrated application must support both scenarios.
+
+  When booking a slot using [[HYPERLINK_A016]], the named clinician details must be added to the "Appointment.partcipant" list. As shown in the "Booking with named clinician" example.
+
   ## Use case
   As an authenticated user
 
@@ -43,6 +49,11 @@ description: |
 
   Where deferring the booking responsibility to a directly bookable service, or referring the patient into a triage service, you can calculate the date when the patient can expect to be contacted (by the receiving service) using reference data from [[HYPERLINK_A004]].
 
+    ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  
 summary: Book or defer appointment (A016, FHIR STU3)
 operationId: a016-book-or-defer-appointment
 tags:
diff --git a/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml
@@ -39,6 +39,11 @@ description: |
 
   You can calculate the date when the patient will need to be contacted (by the triage service) using reference data from [[HYPERLINK_A004]].
 
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
 summary: Create referral and send for triage (A021, FHIR STU3) [deprecated]
 operationId: a021-create-referral-request-and-send-for-triage
 tags:
diff --git a/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml b/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml
@@ -51,6 +51,11 @@ description: |
       The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code.
       - Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications.
 
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
 summary: Cancel appointment, action later (A022, FHIR STU3)
 operationId: a022-cancel-appointment-action-later
 tags:
diff --git a/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml b/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml
@@ -5,8 +5,11 @@ description: |
   Use this endpoint to retrieve the summary of an advice and guidance request. This endpoint provides important 
   contextual information about the advice and guidance request (e.g. the service/specialty to which advice has been requested, etc).
 
-  This does not include the actual advice and guidance conversation between the referrer and the service provider. 
-  The conversation can be retrieved via [[HYPERLINK_A025]].
+  This does not include the advice and guidance conversation between the referrer and the service provider. The conversation must be retrieved via [[HYPERLINK_A025]].
+
+  An advice request can include file attachments and structured clinical data added via an integrated primary care system. These must be retrieved via [[HYPERLINK_A042]] and [[HYPERLINK_A043]], respectively.
+
+  [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information.
 
   ## Supported security patterns
   - Application-restricted access, unattended access
diff --git a/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml b/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml
@@ -5,7 +5,9 @@ description: |
   Use this endpoint to retrieve the advice and guidance conversation between the referring organisation 
   and service providing organisation.
 
-  A 'conversation' takes the form of the messages between a referrer (seeking advice) and a provider or specialist. Messages can include attachments.
+  A conversation takes the form of messages between a referrer (seeking advice) and a provider or specialist. Messages can include file attachments. These must be retrieved via [[HYPERLINK_A042]]
+
+  [Read](https://digital.nhs.uk/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings/e-referral-service/retrieve-clinical-referral-information-as-a-service-provider) our building healthcare software guide for detailed information.
 
   ## Supported security patterns
   - Application-restricted access, unattended access
diff --git a/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml b/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml
@@ -61,6 +61,11 @@ description: |
   You can use [[HYPERLINK_A006]] to retrieve the clinical attachments for a referral/advice request.
 
   You can use [[HYPERLINK_A007]] to retrieve the clinical information summary PDF for a referral.
+
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
   
 summary: Convert advice and guidance request to referral (A027, FHIR STU3)
 operationId: a027-convert-a&g-to-referral
diff --git a/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml b/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml
@@ -74,7 +74,12 @@ description: |
     - In order to retrieve an attachment using the [[HYPERLINK_A042]] (or deprecated [[HYPERLINK_A006]]) endpoint, the attachment must be available for download. 
     The availability status of attachments associated with a referral are returned via this endpoint as a eRS-AvailabilityStatus-1 code.
       - Further details on attachment availability status and eRS-AvailabilityStatus-1 codes can be found in the [[HYPERLINK_A005]] and [[HYPERLINK_A042]] specifications.
-  
+
+  ## Known Issues
+
+  1. The Participant.type attribute is being mapped as a single type for this endpoint. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be an array. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+  2. The participant of an Appointment references a value set. As per the Appointment [FHIR profile](https://hl7.org/fhir/STU3/appointment-definitions.html#Appointment.participant.type), this attribute should be a coding system. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information.
+
 summary: Record triage outcome (A028, FHIR STU3)
 operationId: a028-record-triage-outcome
 tags:
diff --git a/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml b/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml
diff --git a/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml b/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml
diff --git a/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml
diff --git a/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml b/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml
diff --git a/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml b/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml
diff --git a/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml b/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml
diff --git a/specification/e-referrals-service-api.yaml b/specification/e-referrals-service-api.yaml
