NPA-5357: Improve Specification Definitions and Formatting

Author: JackPlowman

specification/examples/responses/GET_QuestionnaireResponse/errors/questionnaire_response_not_found.yaml

@@ -11,4 +11,4 @@ QuestionnaireResponseNotFound:
             - system: "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"
               code: "QUESTIONNAIRE_RESPONSE_NOT_FOUND"
               display: "Questionnaire response not found"
-        diagnostics: "The Questionnaire response could not be found using the provided access request UUID."
+        diagnostics: "The Questionnaire response could not be found using the provided access request ID."

specification/examples/responses/POST_QuestionnaireResponse/success.yaml

@@ -1,6 +1,6 @@
 PostQuestionnaireResponseSuccess:
   summary: Success
-  description: A sample of the payload returned when a QuestionnaireResponse (proxy access request) has been successfully submitted. It contains a unique alpha-numeric reference code to identify the request by.
+  description: A sample of the payload returned when a QuestionnaireResponse (proxy access request) has been successfully submitted. It contains the unique id of the access request.
   value:
     resourceType: "OperationOutcome"
     issue:

specification/validated-relationships-service-api.yaml

@@ -309,19 +309,19 @@ paths:
 
         | Scenario                         | Request                                 | Response                                                      |
         | -------------------------------- | ----------------------------------------| ------------------------------------------------------------- |
-        | Valid access request UUID        | id=156e1560-e532-4e2a-85ad-5aeff03dc43e | HTTP Status 200 with QuestionnaireResponse                    |
-        | Invalid access request UUID      | id=INVALID                              | HTTP Status 400 with INVALID_IDENTIFIER_VALUE message         |
-        | Missing access request UUID      | No id parameter                         | HTTP Status 400 with BAD_REQUEST message                      |
-        | Non-existent access request UUID | id=60d09b82-f4bb-41f9-b41e-767999b4ac9b | HTTP Status 404 with QUESTIONNAIRE_RESPONSE_NOT_FOUND message |
+        | Valid access request ID          | ID=156e1560-e532-4e2a-85ad-5aeff03dc43e | HTTP Status 200 with QuestionnaireResponse                    |
+        | Invalid access request ID        | ID=INVALID                              | HTTP Status 400 with INVALID_IDENTIFIER_VALUE message         |
+        | Missing access request ID        | No ID parameter                         | HTTP Status 400 with BAD_REQUEST message                      |
+        | Non-existent access request ID   | ID=60d09b82-f4bb-41f9-b41e-767999b4ac9b | HTTP Status 404 with QUESTIONNAIRE_RESPONSE_NOT_FOUND message |
 
       operationId: get-questionnaire-response
       parameters:
         - $ref: "#/components/parameters/BearerAuthorization"
         - $ref: "#/components/parameters/RequestID"
         - $ref: "#/components/parameters/CorrelationID"
-        - name: id
+        - name: ID
           in: query
-          description: The unique access request UUID of the QuestionnaireResponse to retrieve
+          description: The unique access request ID of the QuestionnaireResponse to retrieve
           required: true
           schema:
             type: string
@@ -342,13 +342,13 @@ paths:
 
             | HTTP status | Error code                         | Description                                                                                                                               |
             | ----------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-            | 400         | `INVALID_IDENTIFIER_VALUE`         | The access request UUID must be a valid uuid.                                                                                             |
+            | 400         | `INVALID_IDENTIFIER_VALUE`         | The access request ID must be a valid uuid.                                                                                             |
             | 400         | `INVALID_VALUE`                    | Invalid Parameter or Invalid operation.                                                                                                   |
-            | 400         | `BAD_REQUEST`.                     | The access request UUID is required but was not provided in the request.                                                                  |
+            | 400         | `BAD_REQUEST`.                     | The access request ID is required but was not provided in the request.                                                                  |
             | 400         | `MISSING_VALUE`                    | Missing header or parameter. For details, see the `diagnostics` field.                                                                    |
             | 401         | `ACCESS_DENIED`                    | Missing or invalid OAuth 2.0 bearer token in request.                                                                                     |
             | 403         | `FORBIDDEN`                        | Access denied to resource.                                                                                                                |
-            | 404         | `QUESTIONNAIRE_RESPONSE_NOT_FOUND` | No questionnaire response was found for the provided access request UUID.                                                                 |
+            | 404         | `QUESTIONNAIRE_RESPONSE_NOT_FOUND` | No questionnaire response was found for the provided access request ID.                                                                 |
             | 404         | `INVALIDATED_RESOURCE`             | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved                                            |
             | 405         | `METHOD_NOT_ALLOWED`               | The method is not allowed.                                                                                                                |
             | 408         | `TIMEOUT`                          | Request timed out.                                                                                                                        |