Merge pull request #63 from NHSDigital/feature/NRLF-402_oas_feedback_…

…narrative [NRLF-402] OAS Feedback (Narrative)
NHSDigital · Mar 24, 2023 · 21036fd · 21036fd
2 parents 981bed1 + 59c73b8
commit 21036fd
Show file tree

Hide file tree

Showing 4 changed files with 118 additions and 41 deletions.
diff --git a/nrl.drawio b/nrl.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2023-03-24T10:41:58.071Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.8.16 Chrome/106.0.5249.199 Electron/21.4.0 Safari/537.36" etag="YtVIL4MAk1VrwZUP88kN" version="20.8.16" type="device"><diagram name="Page-1" id="cqCiDIYexOJ1daW3aimP">7VrJcts4EP0aVWUOcnERKeloLclMleNymYdx5gaTEIWYJDggqCVfPw0S4CJQisZRTKWciww0gMbSr183QA/sebz7xFC6/kwDHA0sI9gN7MXAsibOGH6FYF8KXMstBSEjQSkya4FHvmEpNKQ0JwHOWh05pREnaVvo0yTBPm/JEGN02+62olF71hSFWBN4Pop06d8k4Gu5LWtcy//EJFyrmU13WrbESHWWO8nWKKDbhsheDuw5o5SXpXg3x5E4O3Uu5biPR1qrhTGc8HMGPH32Hj6t2dK+3z6Fz2OLpvt/hnIbGd+rDeMA9i+rlPE1DWmComUtnTGaJwEWWg2o1X3uKE1BaILwK+Z8L42Jck5BtOZxJFtXNOGy0RxBPeOMvuA5jSgr1mAbxtjycdWiDt4GSblescijxyBFGc2Zj0/s3ZJwQizE/ES/UWUsADmmMeZsD+MYjhAnm/Y6kIRbWPWrLQIFaZT/YSBzVCreoCiXUw0sN4L1zp6hEIqCfQMd4PRf4E+eVs1MtaeMbsCLoG7cen8tVAdYT6WiEwZ36BmcuWU6FJEwgbIPpw0K7dkGM07AXW5lQ0yCoEQJzsg39FzoEzhJKUl4cTrObOAsOmAQielmyH8JC4QpPCQ0wdUKxXR41+X5cqra35qQOI593a5S+9C4MayxxIgkL2mLsy0vlT+Irddahua4PYSuVhkg8BAq1Zpej55JH+6tO+2hpf2cbYoZRHcwEts/yemKyhdRuXFUdbFrNi72qrYj/KnuCbUvSiOU60GiosYcZ5oeeMXulVccjVdGgkYeQTvBMDuMT1aUQRgjNNE5ZcVoLM6H0SD3BbX0zx9FXa7A7IFPJif5xLixJ9NRi06cy9CJ7bwVnZhmp51P80nL2X+YXLq93jjp9a9lmO8T2VXxidMrn9jfz1OsA4IpXBqz7HdC0nSvEwximYozlO9fiEKsN6MQS4PJ/eNdM7w0bO7+m1Mu7TLMCsPcQgdzlO6K81ftCjNw8Fkei2B0EXXZPuM41oDYprDtmnDspajw4C1cgQ+uOiSKGvSAnZW5QseIY748TjqNuHYI06NA1MjmKLRGRgtWpmveSERs60uvqYC8blx4J8ZPIpTp1YQaVW4EjTNCTR1dqrT0+kONfWaocXsNNa7GIc4vnrqejjRtArh42JmepAa4B1vW1Gzxw+RCiav1VlFHT068lMDZatjwMHBIh/yB0d1eF3/wvIc/3kWEsK12iKiIv7cAoT+MHbHpgjDwC8o67OdhtiF+x5gP3sJ7n4a9htivv03cF1yOIt1Sj9inLNDld9RHYPQO00LC+T5NO+rbZdVHnStI6l71flBlcb/U+4F7ZlLX7/uBfjHU3g9MkeXNGUZc5HggRbFwzPJ3ID65JeJr3u+HhW6/O/U06Rp2O7z/WIYnFVttpUOl9ucnfPoV4eCZofoyJu8Ahy3v6PLvGm+ZAUC1/uZdmrv+xwF7+R8=</diagram></mxfile>
diff --git a/nrl.png b/nrl.png
diff --git a/specification/nrl-producer-api.yaml b/specification/nrl-producer-api.yaml
@@ -7,16 +7,22 @@ info:
   description: |
     ## Overview
 
-    The National Record Locator (NRL) enables organisations to share Patient data nationwide.  It acts as an Index, or Directory, of patient data.  Rather than handling the data itself it shares pointers held in partner systems, using the FHIR R4 DocumentReference standard.
+    The National Record Locator (NRL) enables organisations to share Patient data nationwide.  It acts as an Index, or
+    Directory, of patient data.  Rather than handling the data itself it shares pointers held in partner systems, using
+    the [FHIR R4 DocumentReference](http://hl7.org/fhir/documentreference.html) standard.
+
+    ![National Record Locator](https://raw.githubusercontent.com/NHSDigital/nrl-producer-api/master/specification/nrl.png)
 
     Users of the service fall into the categories of:
 
     * Producers - capable of creating and managing pointers
     * Consumers - capable of searching and reading pointers
 
-    The service removes the need for organisations to create duplicate copies of information across systems and organisations, by enabling access to up-to-date information directly from the source.
+    The service removes the need for organisations to create duplicate copies of information across systems and
+    organisations, by enabling access to up-to-date information directly from the source.
 
-    It can be used to store and publish pointers to patient data held in health systems across England and to look up where relevant patient data is held.
+    It can be used to store and publish pointers to patient data held in health systems across England and to look up
+    where relevant patient data is held.
 
     There is a growing list of health and social care organisations authorised to share records using NRL.
 
@@ -90,7 +96,7 @@ info:
 
     In particular:
 
-    * resource names are capitalised and singular, and use US spellings, for example `/Immunization` not `/immunisations`
+    * resource names are capitalised and singular, and use US spellings, for example `Organization` not `organisations`
     * array names are singular, for example `entry` not `entries` for address lines
     * data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object
 
@@ -110,11 +116,10 @@ info:
 
     ## Environments and testing
 
-    | Environment       | Base URL                                                               |
-    | ----------------- | ---------------------------------------------------------------------- |
-    | Sandbox           | `https://sandbox.api.service.nhs.uk/nrl-producer-api/FHIR/R4/`     |
-    | Integration test  | `https://int.api.service.nhs.uk/nrl-producer-api/FHIR/R4/`         |
-    | Production        | `https://api.service.nhs.uk/nrl-producer-api/FHIR/R4/`             |
+    | Environment       | Base URL                                                       |
+    | ----------------- | ---------------------------------------------------------------|
+    | Sandbox           | `https://sandbox.api.service.nhs.uk/nrl-producer-api/FHIR/R4/` |
+    | Integration test  | `https://int.api.service.nhs.uk/nrl-producer-api/FHIR/R4/`     |
 
     ### Sandbox testing
 
@@ -167,7 +172,7 @@ servers:
 paths:
   /DocumentReference:
     post:
-      summary: Create / Supersede
+      summary: Create new, or Supersede existing, document pointers
       operationId: createDocumentReference
       responses:
         "201":
@@ -197,27 +202,83 @@ paths:
         - $ref: "#/components/parameters/requestId"
         - $ref: "#/components/parameters/correlationId"
       description: |
-        Create new Pointers, or Supersede existing ones.
-
-        * `id` is a composite of the ODS Code and an identifier that is locally unique to your system.  NRL does not generate globally unique ids, instead relies on producers to provide a locally unique id prefixed with their ODS code, making it globally unique.
-        * `subject` MUST be a `Patient` reference.
-        * `custodian` MUST be an `Organization` reference, and must match the `NHSD-End-User-Organisation-ODS`
-        * `type` MUST match one of the Document Types agreed during on-boarding.
+        Create new pointers, or Supersede existing ones.
+
+        To create a document pointer you must ensure:
+
+        * The body must be a valid [FHIR R4 DocumentReference](http://hl7.org/fhir/documentreference.html)
+        * `id` is a composite of the ODS Code and an identifier that is locally unique to your system.  NRL does not
+          generate globally unique ids, instead relies on producers to provide a locally unique id prefixed with their
+          ODS code, making it globally unique. e.g.
+          ```
+          XYZ-1234567890
+          ```
+        * `subject` MUST be a `Patient` reference using a valid NHS number. e.g.
+          ```
+          "subject": {
+            "identifier": {
+              "system": "https://fhir.nhs.uk/Id/nhs-number",
+              "value": "3495456481"
+            }
+          },
+          ```
+        * `custodian` MUST be an `Organization` reference using a valid ODS code, agreed during [on-boarding](#onboarding). e.g.
+          ```
+          "custodian": {
+            "identifier": {
+              "system": "https://fhir.nhs.uk/Id/ods-organization-code",
+              "value": "Y05868"
+            }
+          }
+          ```
+        * `type` MUST match one of the Document Types agreed during [on-boarding](#onboarding). e.g.
+          ```
+          "type": {
+            "coding\": [
+              {
+                "system": "http://snomed.info/sct",
+                "code": "1363501000000100",
+                "display": "Royal College of Physicians NEWS2 (National Early Warning Score 2) chart"
+              }
+            ]
+          }
+          ```
         * `content` MUST have at least one entry.
         * `content[].format[]` SHOULD indicate the mechanism for accessing documents, e.g.
-          * `{ "code": "ssp", "display": "Spine Secure Proxy" }`
-          * Further standards to be agreed.
+          ```
+          "format": [
+            {
+              "code": "ssp",
+              "display": "Spine Secure Proxy"
+            }
+          ]
+          ```
+
+        To supersede existing pointers you must further specify:
+
+        * at least one existing pointer in the `relatesTo` with a `code` of `replaces`.
+          ```
+          [
+            {
+              "code": "replaces",
+              "target": {
+                "type": "DocumentReference",
+                "identifier": {
+                  "value": "XYZ-1234567890"
+                }
+              }
+            }
+          ]
+          ```
 
-        To supersede existing pointers you must specify:
-        * at least one existing pointer in the `relatesTo` with a `target` or `replaces`.
         * The following fields MUST match the pointers being superseded:
           * `subject`
           * `type`
 
         This will cause a new pointer to be created and superseded pointers to be deleted.  Multiple documents can
         be superseded.
     get:
-      summary: Search (GET)
+      summary: Retrieve document pointers (GET)
       operationId: searchDocumentReference
       parameters:
         - $ref: "#/components/parameters/subject"
@@ -229,7 +290,7 @@ paths:
         - $ref: "#/components/parameters/correlationId"
       responses:
         "200":
-          description: Search successful response
+          description: successful response
           content:
             application/fhir+json;version=1:
               schema:
@@ -402,14 +463,17 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Perform a Search using GET query string parameters.
+        Search through document pointers.
 
-        Results are restricted to pointers you created.
+        Results are restricted to pointers you created, but can be further filtered by `subject` and `type`.
 
-        Results are limited to 20 records, further results are
+        Results are limited to 20 records per request, and further records are available by submitting subsequent
+        requests with the `next-page-token` found in the `meta` portion of the response.
+
+        This operation is also available as a http POST, which is the preferred method (see below).
   /DocumentReference/_search:
     post:
-      summary: Search (POST)
+      summary: Retrieve document pointers (GET)
       operationId: searchPostDocumentReference
       parameters:
         - $ref: "#/components/parameters/odsCode"
@@ -422,7 +486,7 @@ paths:
               $ref: "#/components/schemas/RequestParams"
       responses:
         "200":
-          description: Search successful response
+          description: Successful response
           content:
             application/fhir+json;version=1:
               schema:
@@ -595,15 +659,23 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Search Producer records, but implemented as a POST operation
-        because of limitations associated with GET:
+        Search through document pointers.
+
+        Results are restricted to pointers you created, but can be further filtered by `subject` and `type`.
+
+        Results are limited to 20 records per request, and further records are available by submitting subsequent
+        requests with the `next-page-token` found in the `meta` portion of the response.
+
+        This operation is also available as a http GET for convenience (see above), but POST is preferred for the
+        following reasons.
 
         * query string parameters are visible on the network and in logs, and may have privacy implications for consumers.
         * GET operations can be cached by intermediary network infrastructure, such as CDNs, routers and proxies.
-        * URLs have a maximum length of 2,048 characters which complex searches can exceed.  NRL does not currently exceed this limit, but may evolve in the future.
+        * URLs have a maximum length of 2,048 characters which complex searches can exceed.  NRL does not currently
+        exceed this limit, but may evolve in the future.
   /DocumentReference/{id}:
     get:
-      summary: Read
+      summary: Get a single document pointer
       operationId: readDocumentReference
       parameters:
         - $ref: "#/components/parameters/id"
@@ -612,7 +684,7 @@ paths:
         - $ref: "#/components/parameters/correlationId"
       responses:
         "200":
-          description: Read successful response
+          description: Successful response
           content:
             application/fhir+json;version=1:
               schema:
@@ -689,9 +761,11 @@ paths:
             X-Request-Id:
               $ref: "#/components/headers/RequestId"
       description: |
-        Read a single pointer you created
+        Read a single document pointer by specifying the `DocumentReference.id`.  Note that you will only be able to
+        retrieve document pointers that have been created by the organisation specified in the `ODS-End-User-Organisation-ODS`
+        header, and agreed during [on-boarding](#onbaroding).
     put:
-      summary: Update
+      summary: Update a single document pointer
       operationId: updateDocumentReference
       parameters:
         - $ref: "#/components/parameters/id"
@@ -700,7 +774,7 @@ paths:
         - $ref: "#/components/parameters/correlationId"
       responses:
         "200":
-          description: Update successful response
+          description: Successful response
           $ref: "#/components/responses/Success"
           content:
             application/fhir+json;version=1:
@@ -720,7 +794,7 @@ paths:
                           display: Resource updated
                     diagnostics: Resource updated
         "201":
-          description: Update successful response
+          description: Successful response
           $ref: "#/components/responses/Success"
           content:
             application/fhir+json;version=1:
@@ -749,8 +823,11 @@ paths:
         * `subject`
         * `custodian`
         * `type`
+
+        Note that unlike NRL STU3 changing the `status` field does NOT delete document pointers.  To delete document
+        pointers please use the `DELETE` endpoint.
     delete:
-      summary: Delete
+      summary: Delete a single document pointer
       operationId: deleteDocumentReference
       parameters:
         - $ref: "#/components/parameters/id"
@@ -759,7 +836,7 @@ paths:
         - $ref: "#/components/parameters/correlationId"
       responses:
         "204":
-          description: Delete successful response
+          description: Successful response
           $ref: "#/components/responses/Success"
           content:
             application/fhir+json;version=1:
@@ -780,7 +857,7 @@ paths:
                     diagnostics: Resource removed
         "200":
           $ref: "#/components/responses/Success"
-          description: Delete successful response
+          description: Successful response
           content:
             application/fhir+json;version=1:
               example:
@@ -799,7 +876,7 @@ paths:
                           display: Resource removed
                     diagnostics: Resource removed
       description: |
-        Delete a single DocumentReference record
+        Delete a single document pointer that your created.
 components:
   requestBodies:
     DocumentReference:
@@ -1516,7 +1593,6 @@ components:
       example: "https://fhir.nhs.uk/Id/ods-organization-code|Y05868"
     RequestQueryType:
       type: string
-      pattern: ^http\:\/\/snomed\.info\/sct\|(\d+)$
       example: "http://snomed.info/sct|736253002"
     NextPageToken:
       type: string

diff --git a/specification/nrl.png b/specification/nrl.png