-
Notifications
You must be signed in to change notification settings - Fork 1
NPA-6376: Content Review #298
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Conversation
|
This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket: NPA-6376 |
|
This branch is work on a ticket in the NHS Digital NPA JIRA Project. Here's a handy link to the ticket: NPA-6376 |
| version: "1.16.0" | ||
| description: | | ||
| ## Overview | ||
| Use this API to access the Validated Relationships Service - the national electronic database of relationships |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Here (and elsewhere) I think we should make the necessary updates to be really clear on language with regards to "verified relationships" and "proxy roles", what they mean, how they differ and then they'll also align 1:1 with the descriptions of the Operations.
Here I would say something along the lines of "...database of proxy roles that have been clinically approved for the purpose of enabling people to access digital services on behalf of those they care for."
| that have been verified for the purpose of enabling citizens to access patient facing services on behalf of | ||
| (as a proxy for) patients they care for. | ||
|
|
||
| The relationships held by this service are strictly for the purpose of enabling access to healthcare services. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If reworded well, the previous sentence probably negates the need for this one, it just restates the same thing, so can probably be removed.
|
|
||
| You can: | ||
|
|
||
| - get verified relationships (to support decision making when granting proxy access) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
-
rework this to just be the list of things you can do now we've completed development (i.e. remove the split of now and future). Suggest the list ought to be:
-
create a new proxy access request
-
get a proxy access request
-
get verified candidate relationships (to support establishing a legal basis when granting proxy access)
-
create a proxy role
-
update a proxy role
-
get a proxy role by Id
-
get proxy roles
| ## Related APIs | ||
| The following APIs are related to this API: | ||
|
|
||
| - [Personal Demographics Service - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) - we use the data held in PDS as a source of data to verify relationships. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Worth adding an entry to this for RPN to disclose our usage - perhaps only when we actually do the work (so an AC on the ticket for implementing that)
https://digital.nhs.uk/developer/api-catalogue/related-person-network---fhir-api
| version: "1.16.0" | ||
| description: | | ||
| ## Overview | ||
| Use this API to access the Validated Relationships Service - the national electronic database of relationships |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
On the API catalogue page there are words in the grey section at the top that are VERY similar to the opening pargraph in the Overview section. Where are these being set? they don't appear to be in the OAS or this GH repo at all. Para in question
Use this API to access the Validated Relationships Service - the national electronic database of relationships that have been verified for the purpose of enabling individuals to access healthcare services on behalf of (proxy) those they care for.
|
|
||
| There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration. | ||
|
|
||
| ## Network access |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest we add a new "Guidance for developers" section after "Technology". Reason being is we're creating a developer docs hub to compliment this API and makes sense to call this out here (as well as on our Proxy service page). Something along the lines of
Guidance for developers
Supplementary documentation and guidance for developers
- National Proxy Service developer documentation (linking out to the docs site - but not yet available)
|
|
||
| [Review all patient access modes](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#patient-access-mode) | ||
|
|
||
| Validated Relationships Service API checks the patient is P9 verified and has a high [vector of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/) (VOT). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would slightly reword this sentence because P9 is part of the VoT. Suggest the below
All API endpoints that support this access mode require that the user has proven their identity to a high level and authenticated using strong authentication credentials. The combination of these forms a Vector of Trust (VoT) profile.
| - `P9.Cm` | ||
|
|
||
| #### Healthcare worker access mode | ||
| If the end user is a healthcare worker then you must use this access mode. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Think we should expand this sentence to incorporate the level. Suggest the below
If the end user is a healthcare worker then you must use this access mode. All API endpoints that support this access mode require that the user has been authenticated with a "very high confidence" authenticator (AAL3).
| | Healthcare worker access | User-restricted | | ||
| | Application-restricted access | Application-restricted | | ||
|
|
||
| For more information on access modes and how to use them, see the developer [security and authorisation guide](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe worth an additional sentence to state:
Each API operation section of this documentation indicates the access modes that the endpoint supports.
|
|
||
| ### Application-restricted access | ||
|
|
||
| This API is application-restricted, meaning we authenticate the calling application but not the end user. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest an additional sentence along the lines of
This should only be utilised where user-restrcited access modes are not feasible or practical.
| * 400 to 499 if it failed because of a client error by your application | ||
| * 500 to 599 if it failed because of an error on our server | ||
|
|
||
| Errors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Correction to align with the section name in the docs (reword of Endpoints -> Operations)
Errors specific to each API are shown in the Operations section
| | FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) | | ||
| | nhs-number | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \| [Python Package index](https://pypi.org/project/nhs-number/) \| [Docs](https://nhs-number.uk-fci.tech/) | | ||
|
|
||
| We currently don't have any open source client libraries or sample code for this API and the source code for the PDS FHIR back end (the Core Spine source code) is not currently in the open. If you think this would be useful, [contact us](https://digital.nhs.uk/developer/help-and-support). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Got some content here that looks to be a copy and paste error from when it was lifted from the PDS service page. Corrected para
We currently don't have any open source client libraries or sample code for this API and the source code for the Validated Relationship Service FHIR application is not currently in the open. If you think this would be useful, contact us.
| Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing) | ||
|
|
||
| * is for formal integration testing | ||
| * includes authorisation with NHS Login |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Expand this bullet to incorporate the various modes we support e.g.
- requires authorisation using a supported access mode
| For any new access request, the necessary details should be collected from a user facing service e.g. | ||
| Proxy Access Service and submitted as a QuestionnaireResponse. | ||
|
|
||
| For the most part demographics information doesn't need to be provided in the access request since it can be pulled from PDS. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd remove this sentence personally, let the Questionnaire schema do the talking of what's required or not
| | Scenario | Request | Response | | ||
| | ---------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | ||
| | Successful request | Valid request with performer identifier value of `9000000009` or `9000000017` | HTTP Status 200 Success response | | ||
| | Duplicate relationship | Request for relationship that already exists, with performer identifier value of `9000000049` | HTTP Status 409 and DUPLICATE_RELATIONSHIP error response | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest Scenario is "Duplicate proxy role" and replace relationship e.g.
Request for a proxy role that already exists, with performer identifier value of 9000000049
| | Scenario | Request | Response | | ||
| | ---------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | ||
| | Successful request | Valid request with performer identifier value of `9000000009` or `9000000017` | HTTP Status 200 Success response | | ||
| | Duplicate relationship | Request for relationship that already exists, with performer identifier value of `9000000049` | HTTP Status 409 and DUPLICATE_RELATIONSHIP error response | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
DUPLICATE_RELATIONSHIP error code should ideally not mention relationship, probably "DUPLICATE" would be sufficient. Suggest we take note of this change and do it when we move over to the split Questionnaires
|
|
||
|
|
||
| ### Sandbox constraints | ||
| - Questionnaire Response is not validated. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
QuestionnaireResponse
| - Questionnaire Response is not validated. | ||
| - Headers are not tested. `X-Request-ID` and `X-Correlation-ID` are disregarded. | ||
|
|
||
| Or perhaps you'd like to try out the sandbox using our 'Try it out' feature. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Remove this line (seems to read out of context) and add an introductory line to the sandbox section (as per above comment)
| This endpoint supports the following access modes: | ||
| - Patient access | ||
|
|
||
| ## Sandbox test scenarios |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest we add an intro line akin to the below, and make this change for ALL of our endpoints
You can test the following scenarios in our sandbox environment:
| - $ref: "#/components/parameters/RequestID" | ||
| - $ref: "#/components/parameters/CorrelationID" | ||
| requestBody: | ||
| description: FHIR QuestionnaireResponse |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
remove the description, it's not really adding anything. The schema tells us the resource type
| location: | ||
| schema: | ||
| type: string | ||
| example: https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/QuestionnaireResponse?ID=156e1560-e532-4e2a-85ad-5aeff03dc43e |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Example is incorrect, ID isn't a querystring parameter, it's a route parameter
https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/QuestionnaireResponse/156e1560-e532-4e2a-85ad-5aeff03dc43e
| | 400 | `INVALID_VALUE` | Invalid Parameter or Invalid operation. | | ||
| | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | ||
| | 403 | `FORBIDDEN` | Access denied to resource. | | ||
| | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm assuming this is when a patient record can't be found for a patient or proxy. This should be a 400 error in my view, not a 404. A 404 pertains to our endpoint and will likely confuse as it hints at one of the below
- The POST endpoint itself does not exist
- The client addressed the wrong URL
It's neither of these things. What we're trying to communicate is that there is a record referenced in the request which is invalid or does not exist. That's essentially validation of the provided NHS numbers, as opposed to a QuestionnaireResponse resource not existing (which is the core of what REST is all about, your status codes are always contextualised by the Resource locator (URI) that you're addressing.
Suggest we move this to a 400, and make the error message more meaningful e.g. "One or more identifiers reference resources that don't exist"
| QuestionnaireResponse document that was previously submitted. | ||
|
|
||
| ## Request Requirements | ||
| A valid access request ID must be provided as a path parameter. This access request ID is returned |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd shorten this to just "A valid access request ID must be provided as a path parameter.", the second sentence isn't really adding anything
| | 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 ID. | | ||
| | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this really a response that this endpoint could return? Suspect it can be removed?
| | 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 ID. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Opportunity to simplify.
Suspect we're making things more complicated for ourselves by making 404's specific to the endpoint. I'd say you could probably simplify to NOT_FOUND and The resource with the specified ID does not exist and then it removes the need to have endpoint specific handling of this standard type of error
| examples: | ||
| internalServerError: | ||
| $ref: "./examples/responses/errors/internal-server-error.yaml#/InternalServerError" | ||
| downstreamServiceError: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IS there a downstream service here? Don't think this example is relevant to this request, it's just a read from our database
| | 400 | `MISSING_IDENTIFIER_VALUE` | Missing performer:identifier or patient:identifier value. | | ||
| | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | ||
| | 403 | `FORBIDDEN` | Access denied to resource. | | ||
| | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What scenario could lead to this error? Doesn't feel relevant to us
| | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | ||
| | 403 | `FORBIDDEN` | Access denied to resource. | | ||
| | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | | ||
| | 404 | `GP_PRACTICE_NOT_FOUND` | GP Practice not found. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
How could we encounter this error? Doesn't feel like an error we should be returning
| | 404 | `GP_PRACTICE_NOT_FOUND` | GP Practice not found. | | ||
| | 405 | `METHOD_NOT_ALLOWED` | The method is not allowed. | | ||
| | 408 | `TIMEOUT` | Request timed out. | | ||
| | 422 | `INVALID_IDENTIFIER_SYSTEM` | Invalid performer:identifier or patient:identifier identifier system. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Refactor to grantee
| | 405 | `METHOD_NOT_ALLOWED` | The method is not allowed. | | ||
| | 408 | `TIMEOUT` | Request timed out. | | ||
| | 422 | `INVALID_IDENTIFIER_SYSTEM` | Invalid performer:identifier or patient:identifier identifier system. | | ||
| | 422 | `INVALID_IDENTIFIER_VALUE` | Malformed performer:identifier or patient:identifier NHS number. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Refactor to grantee
|
|
||
| ## Sandbox test scenarios | ||
|
|
||
| The sandbox supports a limited number of scenarios, and does not attempt to validate requests. The returned result is dependant on the `performer.identifier.value`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
performer -> grantee
| | 400 | `INVALID_VALUE` | Invalid Parameter or Invalid operation. | | ||
| | 401 | `ACCESS_DENIED` | Missing or invalid OAuth 2.0 bearer token in request. | | ||
| | 403 | `FORBIDDEN` | Access denied to resource. | | ||
| | 404 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't see how this error is relevant to us, we don't invalidate records. We aren't listing 404 for just the standard case of "NOT_FOUND" though, so this needs documenting (and implementing if not already the case)
| ## Overview | ||
| Use this endpoint to update an existing proxy role. | ||
|
|
||
| Common update scenarios include: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggestion for revised list:
Supported update scenarios include:
- Update the status and status reason, (optionally) providing an additional free text description
- Update the legal basis
- Update the end date, for time-bound access
| * Updating the end date for time-bound access | ||
|
|
||
| ## Request Requirements | ||
| * The proxy role must exist and be identified by a valid identifier |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor thing, but identifier's are different to id;s in FHIR, so worth reflecting that here, i.e. reword identifier -> id please
| * 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`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Worth also capturing the fact that status changes are validated against a proxy role lifecycle in order to ensure a valid transition.
| path: /status | ||
| value: active | ||
| - op: add | ||
| path: /extension/- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
are we missing the extension path here? how do we know which extension property we're updating?
| updateProvisionEndDate: | ||
| $ref: "./examples/requests/PATCH_Consent/replace_provision_end_date.yaml#/UpdateProvisionEndDate" | ||
| multipleUpdates: | ||
| summary: Set status to active with an end date |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest move this out to a $ref for consistency with how we reference other examples
| | 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 | `INVALIDATED_RESOURCE` | Resource that has been marked as invalid was requested - invalid resources cannot be retrieved | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don;t think this is relevant to us. But we don;t have a "NOT_FOUND" error code documented for 404, so this should replace it (and be implemented if not already)
| | ----------- | -------------------------- | ------------------------------------------------------------- | | ||
| | 500 | `SERVER_ERROR` | An unexpected internal server error has occurred. | | ||
| | 502 | `BAD_GATEWAY` | Connection to the backend service failed. | | ||
| | 503 | `DOWNSTREAM_SERVICE_ERROR` | A downstream service has failed, request cannot be completed. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don;t think there is a downstream service to error for this endpoint is there? Suggest removing
| | ----------- | -------------------------- | ------------------------------------------------------------- | | ||
| | 500 | `SERVER_ERROR` | An unexpected internal server error has occurred. | | ||
| | 502 | `BAD_GATEWAY` | Connection to the backend service failed. | | ||
| | 503 | `DOWNSTREAM_SERVICE_ERROR` | A downstream service has failed, request cannot be completed. | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don;t think there is a downstream service to error for this endpoint is there? Suggest removing
| status: | ||
| type: string | ||
| description: "The status of the consent, following the ConsentStateCodes value set." | ||
| enum: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we ACTUALLY support "draft" and "entered in error" ? What would happen if we received these values as far as the state machine is concerned? Return an error? I don't think we have a use case for these, so shouldn't accept them as valid. So would need removing from docs and validation not allow them through
| type: array | ||
| items: | ||
| type: string | ||
| enum: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
do we ACTUALLY support "draft" and "entered in error" ? What would happen if we received these values as far as the state machine is concerned? Return an error? I don't think we have a use case for these, so shouldn't accept them as valid. So would need removing from docs and validation not allow them through
| description: Unique identifier of the Consent resource | ||
| status: | ||
| type: string | ||
| description: "The status of the consent, following the ConsentStateCodes value set." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest we link out to the FHIR codesystem so implementors can refer to the valueset looks like
|
|
||
| Consent: | ||
| type: object | ||
| required: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We look to be missing a few properties from the Consent schema (for the READ model). These ought to be added to examples and sandbox as well as the implementation if not just missing from the API docs.
- Consent.meta.lastUpdated
- Extensions: grantor, regulatoryBasis
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note that we have a meta OAS component documented below, so we should leverage this here
| - deny | ||
| period: | ||
| type: object | ||
| description: "Timeframe for this provision." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
think we can provide something more meaningful for our context here. What about
The start date on which the proxy role was granted, and (optionally) an end date for time-bound access.
| code: | ||
| type: string | ||
| description: FHIR error code. | ||
| enum: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
will we really return all of these? If not, i'd be tempted to simplify to the ones we're using so as to help consumers out
| $ref: "#/components/schemas/CodeableConcept" | ||
| description: "Classification of the role of consent, bound to http://terminology.hl7.org/CodeSystem/v3-RoleCode" | ||
|
|
||
| StatusReasonExtension: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| @@ -1 +1 @@ | |||
| ReplaceLegalBasisRequest: | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
example will need updating to reflect use of regulatory basis
| path: /status | ||
| value: inactive | ||
| - op: add | ||
| path: /extension/- |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is the - how IOPS advised we implement this? just not sure how this works (my ignorance most likely)
| @@ -1,2 +1,2 @@ | |||
| UpdateProvisionEndDate: | |||
| summary: Set provision end date | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Possible gap:
do we have a use case whereby when access of a role is re-enabled we need to be able to support PATCHing the start date as well? or are you handling that internally when a status change of inactive -> active occurs?
| @@ -12,4 +12,4 @@ InvalidatedResourceError: | |||
| display: "Resource that has been marked as invalid was requested - invalid resources cannot be retrieved" | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
suspect this example will go away since i can't think of a scenario where we should be returning this (as per my other comments)
| @@ -12,4 +12,4 @@ GPPracticeNotFoundError: | |||
| display: "GP Practice could not be found - invalid resources cannot be retrieved" | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why would we raise this error? think i've probably said bin it off elsewhere in the review. What scenario would we check if a GP practice is found when loading a consent resource?
| @@ -12,4 +12,4 @@ ConsentIdentifierMissingError: | |||
| version: "1" | |||
| diagnostics: "Invalid request with error - performer:identifier or patient:identifier parameter not found." | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
uplift of performer:identifier
| search: | ||
| mode: include | ||
| - fullUrl: "https://api.service.nhs.uk/validated-relationships/FHIR/R4/Consent/BBCC67E9" | ||
| resource: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this goes for all examples where we have a Consent resource,
- add missing meta.lastUpdated
- update to reflect removal of performer and items from provision and the use of extensions
- policy uri's across the board can now point to the published ISN instead of "REPLACE_WITH_LINK_TO_PUBLISHED_NATIONAL_PROXY_STANDARD", use
https://digital.nhs.uk/data-and-information/information-standards/governance/latest-activity/standards-and-collections/dapb3051-identity-verification-and-authentication-standard-for-digital-health-and-care-services
IMPORTANT
as discussed with Ellie, we've identified a need to return a Patient resource for the proxy (there may not always be a relatedperson record. THIS CHANGE WILL NEED COMMUNICATING TO NHS login to be implemented before we go live with a supplier
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd do a wholesale find for performer across the whole repo, cus it appears in all sorts of different guises
| resourceType: Patient | ||
| search: | ||
| mode: include | ||
| - fullUrl: https://sandbox.api.service.nhs.uk/validated-relationships/FHIR/R4/RelatedPerson/BE974742 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As discussed with Ellie, for all Patient and RelatedPerson records that we get from PDS, we need to be careful not to return properties that our DPIA doesn't cover us for. I.e. we should trim any properties that aren't in these examples, such as contact info & address
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
...as it stands I suspect the implementation doesn't match our examples (i.e. you'll get more properties on the resource back than you expect)
miiisterjim
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
OK so I think generally my comments boil down to the below. Note that i haven't reviewed the QuestionnaireResponse endpoints schema/examples because that's all going to be reworked in due course when we split the questionnaires for apply/nominate.
- some wording improvements to make the docs clearer
- some fixes i think ought to be done as a priority as they represent bugs, I've noted in my comments where i perceive there to be an impact on NHS Login
- a wholesale review of updates required to replace the use of performer with grantee - for this, I would update the schemas (leaving performer as valid in terms of runtime validation/implementation for backwards compatibility and leave support for the querystring parameter without it being documented on the OAS i.e. still valid technically, but not documented anymore) but everywhere else (examples, documentation, API specs) update to reflect the use of grantee)...leave that to your better judgement on how you wanna manage it though cus hiding things in the docs ain't great, but neither is duplicating performer and grantee documentation (especially where querystring parameter and error codes are concerned
- same wholesale addition and review of all examples of the new properties added from the IOPS changes that aren't in this branch

Pull Request
🧾 Ticket Link
https://nhsd-jira.digital.nhs.uk/browse/NPA-6376
📄 Description/Summary of Changes
🧪 Developer Testing Carried Out
🧪 Reviewer Testing Required
✅ Developer Checklist
NPA-XXXX: <short-description><type>/NPA-XXXX/<short-description>NPA-XXXX: <short-description>terraform,documentation) are added👀 Reviewer Checklist
🚀 Post-merge
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.