openapi: 3.0.0

# This is an OpenAPI Specification (https://swagger.io/specification/)

# for the National Record Locator Consumer FHIR API

# owned by NHS Digital (https://digital.nhs.uk/)

info:

title: National Record Locator Consumer - FHIR API

description: |

## Overview

The National Record Locator (NRL) enables organisations to share patient data nationwide. Rather than storing the

data itself, it is used to share pointers to the data, held in provider systems. It acts as an index and not a data

repository. Each document pointer is defined using the

[FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) standard.


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.

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, and presently

the pointers are classified into the following types:

* [Mental health crisis plan](http://snomed.info/sct/736253002)

* [Royal College of Physicians NEWS2 (National Early Warning Score 2) chart](http://snomed.info/sct/1363501000000100)

* [ReSPECT (Recommended Summary Plan for Emergency Care and Treatment) form](http://snomed.info/sct/1382601000000107)

* [Contingency plan](http://snomed.info/sct/325691000000100)

* [End of life care plan](http://snomed.info/sct/736373009)

* [End of Life Care Coordination Summary](http://snomed.info/sct/861421000000109)

* [Emergency health care plan](http://snomed.info/sct/887701000000100)

* [Lloyd George record folder](http://snomed.info/sct/16521000000101)

* [Advanced care plan](http://snomed.info/sct/736366004)

* [Treatment escalation plan](http://snomed.info/sct/735324008)

* [Summary record]("http://snomed.info/sct|824321000000109")

* [Personalised Care and Support Plan]("http://snomed.info/sct|2181441000000107")

You can also retrieve booking and referal pointers however you can not currently do this by directly integrating with

the National Record Locator, you must instead onboard to the [Booking and Referral - FHIR API](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir)

### As a Consumer

Consumers can use this API to:

* search for pointers, restricted to a single Patient at a time

* read a specific pointer

* operations are restricted to document types agreed during the [onboarding](#api-description__onboarding) process

### What has changed?

This service is a replacement for the existing

[National Record Locator (NRL)](https://digital.nhs.uk/services/national-record-locator), and has the following

changes:

* upgraded from FHIR STU3 to R4.

* improved performance and scalability.

* improved onboarding experience.

* authenticated using [signed JWT](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication) rather than mTLS.

* greater flexibility, by wider support of the [FHIR R4 DocumentReference](https://hl7.org/fhir/R4/documentreference.html) resource.

* the application only supports json type FHIR, not XML (which is also valid FHIR)

### Data availability, timing and quality

Pointers are available to be consumed almost immediately after they have been produced by the provider.

## Who can use this API

This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go

too far with your development. You must demonstrate you have a valid use case as part of digital onboarding.

You must have the capability to verify NHS numbers by one of the following mechanisms:

* full PDS Spine compliant system

* Spine Mini Service PDS (SMSP)

Connecting parties must have an appointed Clinical Safety Officer and undertake a Clinical Safety Assessment.

You can not use this API to retrieve documents, however you should be prepared to retrieve in PDF or Unstructured

formats.

In order to retrieve a document, consumers must be able to interact with the National Record Locator and the Spine

Secure Proxy (SSP).

You can only use this API if your consuming application is only accessible using a valid NHS Smartcard for all users

or a system that uses an authentication method supported by

[NHS Care NHS Care Identity Service 2 (NHS CIS2)](https://digital.nhs.uk/services/identity-and-access-management/nhs-care-identity-service-2).

You must do this before you can go live (see ‘[Onboarding](#api-description__onboarding)’ below).

## API status and roadmap

This API is [in development](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).

To see our roadmap, or to suggest, comment or vote on features for this API, see our

[interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?tag=national-record-locator-api).

If you have any other queries, [contact us](https://digital.nhs.uk/developer/help-and-support).

## Service level

This API is a bronze service, meaning it is operational and supported only during business hours (8am to 6pm),

Monday to Friday, excluding bank holidays.

For more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).

## Technology

This API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).

It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir)

global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except

that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.

It includes some country-specific FHIR extensions, which conform to

[FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically

[fhir.r4.ukcore.stu1 0.5.1](https://simplifier.net/packages/fhir.r4.ukcore.stu1/0.5.1).

You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.

In particular:

* 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

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

This API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).

For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).

## Security and authorisation

This API uses the following access modes:

* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)

## Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action

* 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.

## Open source

You might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:

| Resource | Description | Links |

|---------------------------|-----------------------------------------------------------|----------------------------------------------------------------------------|

| NRL v3 API | Source code for the core API and sandbox | [GitHub repo](https://github.com/NHSDigital/nrlf) |

| NRL v3 Producer API | Source code for the producer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-producer-api) |

| NRL v3 Consumer API | Source code for the consumer API proxy and specification. | [GitHub repo](https://github.com/NHSDigital/nrl-consumer-api) |

| Lambda Pipeline Package | Source code for the lambda pipeline utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-pipeline) |

| Lambda Logging Package | Source code for the lambda logging utility | [GitHub repo](https://github.com/NHSDigital/nrlf-lambda-logging) |

We currently don't have any open source client libraries or sample code for this API. If you think this would be useful, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/107439/client-libraries-and-reference-implementations).

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, you can [upvote the suggestion on our Interactive Product Backlog](https://nhs-digital-api-management.featureupvote.com/suggestions/466692/open-source-core-spine-including-pds-eps-scr-and-more).

## Environments and testing

| Environment | Base URL |

| ----------------- | ---------------------------------------------------------------------- |

| Sandbox | `https://sandbox.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |

| Integration test | `https://int.api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |

| Production | `https://api.service.nhs.uk/record-locator/consumer/FHIR/R4/` |

### Sandbox testing

Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):

* is for early developer testing

* only covers a limited set of scenarios

* is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the

documentation for each endpoint.

Alternatively, you can try out the sandbox using our Postman collection:

Right click the icon and save link as... to save the Postman collection to your device

[](https://github.com/NHSDigital/NRLF/raw/main/postman_collection.json)

### Integration testing

Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):

* is for formal integration testing

* includes authorisation

It also includes ready-to-use test data and scenarios. For details [contact us](https://digital.nhs.uk/developer/help-and-support).

For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).

## Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

As part of this process, you need to demonstrate that you can manage risks and that your software conforms technically with the requirements for this API.

Information on this page might impact the design of your software. For details, see [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/national-record-locator-consumer-fhir/onboarding-support-information).

To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding#using-the-digital-onboarding-portal).

<div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">

<div class="nhsd-a-box nhsd-a-box--border-blue">

<div class="nhsd-m-emphasis-box__image-box">

<figure class="nhsd-a-image">

<picture class="nhsd-a-image__picture">

<img src="http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20" alt="" style="object-fit:fill">

</picture>

</figure>

</div>

<div class="nhsd-m-emphasis-box__content-box">

<div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break"><p class="nhsd-t-body">To get started, sign in or create a <a href="http://onboarding.prod.api.platform.nhs.uk/">developer account</a>, then select 'product onboarding'.</p></div>

</div>

</div>

</div>

## Change log

For details of how this API has changed over time, see the [change log](https://github.com/NHSDigital/NRLF/blob/main/CHANGELOG.md).

version: 1.0.0

license:

name: MIT

contact:

name: NHS Digital API Management

url: "https://digital.nhs.uk/developer/help-and-support"

email: [email protected]

servers:

- url: https://sandbox.api.service.nhs.uk/record-locator/consumer/FHIR/R4

description: Sandbox environment.

- url: https://int.api.service.nhs.uk/record-locator/consumer/FHIR/R4

description: Integration test environment.

- url: https://api.service.nhs.uk/record-locator/consumer/FHIR/R4

description: Production environment.

tags:

paths:

/DocumentReference:

get:

tags:

summary: Retrieve patient's document pointers (GET)

operationId: searchDocumentReference

parameters:

- $ref: "#/components/parameters/subject"

- $ref: "#/components/parameters/custodian"

- $ref: "#/components/parameters/type"

- $ref: "#/components/parameters/nextPageToken"

- $ref: "#/components/parameters/odsCode"

- $ref: "#/components/parameters/odsCodeExtension"

- $ref: "#/components/parameters/requestId"

- $ref: "#/components/parameters/correlationId"

responses:

"200":

description: Successful response

content:

application/fhir+json:

schema:

$ref: "#/components/schemas/Bundle"

example:

resourceType: Bundle

type: searchset

total: 1

entry:

- resource:

resourceType: DocumentReference

id: Y05868-1634567890

meta:

profile:

- http://fhir.nhs.net/StructureDefinition/nrls-documentreference-1-0

masterIdentifier:

system: urn:ietf:rfc:3986

value: urn:oid:1.3.6.1.4.1.21367.2005.3.7

identifier:

- system: urn:ietf:rfc:3986

value: urn:oid:1.3.6.1.4.1.21367.2005.3.7.1234

status: current

docStatus: preliminary

type:

coding:

- system: http://snomed.info/sct

code: "736253002"

display: Mental health crisis plan

category:

- coding:

- system: http://loinc.org

code: 34108-1

display: Outpatient Note

subject:

identifier:

system: https://fhir.nhs.uk/Id/nhs-number

value: "4409815415"

date: "2022-12-20T09:45:41+11:00"

author:

- identifier:

value: Practitioner/A985657ZA

authenticator:

identifier:

value: Organization/Y05868

custodian:

identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: Y05868

description: Physical

securityLabel:

- coding:

- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality

code: V

display: very restricted

content:

- attachment:

contentType: application/pdf

language: en-US

url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/MentalHealthCrisisPlan.pdf

hash: 2jmj7l5rSw0yVb/vlWAYkK/YBwk=

title: Physical

creation: "2022-12-20T09:45:41+11:00"

format:

system: urn:oid:1.3.6.1.4.1.19376.1.2.3

code: urn:ihe:pcc:handp:2008

display: History and Physical Specification

context:

encounter:

- identifier:

value: Encounter/4409815415

event:

- coding:

- system: http://snomed.info/sct

code: "305625009"

display: Seen by mental health counselor

period:

start: "2022-12-20T09:00:41+11:00"

end: "2022-12-20T09:45:41+11:00"

facilityType:

coding:

- system: http://snomed.info/sct

code: "390826005"

display: Mental health caregiver support

practiceSetting:

coding:

- system: http://snomed.info/sct

code: "390826005"

display: Mental health caregiver support

sourcePatientInfo:

identifier:

value: Patient/4409815415

related:

- identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: MENTAL HEALTH OUTREACH

headers:

X-Correlation-Id:

$ref: "#/components/headers/CorrelationId"

X-Request-Id:

$ref: "#/components/headers/RequestId"

x-amazon-apigateway-integration:

type: aws_proxy

httpMethod: POST

uri: ${method_searchDocumentReference}

responses:

default:

statusCode: "200"

passthroughBehavior: when_no_match

contentHandling: CONVERT_TO_TEXT

description: |

Retrieve the document pointers for a single patient. Your request is constrained by the document pointer types

agreed during onboarding. The results can also be filtered to return documents by a given `type` and/or created

by a given producer (`custodian`).

This operation is also available as a http POST, which is the preferred method (see below).

/DocumentReference/_search:

post:

tags:

summary: Retrieve patient's document pointers (POST)

operationId: searchPostDocumentReference

parameters:

- $ref: "#/components/parameters/odsCode"

- $ref: "#/components/parameters/requestId"

- $ref: "#/components/parameters/correlationId"

requestBody:

content:

application/json:

schema:

$ref: "#/components/schemas/RequestParams"

responses:

"200":

description: Search successful response

content:

application/fhir+json:

schema:

$ref: "#/components/schemas/Bundle"

example:

resourceType: Bundle

type: searchset

total: 1

entry:

- resource:

resourceType: DocumentReference

id: Y05868-1234567895

meta:

profile:

- http://fhir.nhs.net/StructureDefinition/nrls-documentreference-1-0

masterIdentifier:

system: urn:ietf:rfc:3986

value: urn:oid:1.3.6.1.4.1.21367.2005.3.9

identifier:

- system: urn:ietf:rfc:3986

value: urn:oid:1.3.6.1.4.1.21367.2005.3.7.1239

status: current

docStatus: final

type:

coding:

- system: http://snomed.info/sct

code: "736253002"

display: Mental Health Crisis Plan

category:

- coding:

- system: http://loinc.org

code: 55112-7

display: Document summary

subject:

identifier:

system: https://fhir.nhs.uk/Id/nhs-number

value: "4409815415"

date: "2022-12-21T10:45:41+11:00"

author:

- identifier:

value: Practitioner/A985657ZA

authenticator:

identifier:

value: Organization/Y05868

custodian:

identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: Y05868

description: Physical

securityLabel:

- coding:

- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality

code: V

display: very restricted

content:

- attachment:

contentType: application/pdf

language: en-US

url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/EOLSummaryReport.pdf

size: 4000

hash: 2jmj7l5rSw0yVb/vlWAYkK/YBwk=

title: Physical

creation: "2021-12-21T10:45:41+11:00"

format:

system: urn:oid:1.3.6.1.4.1.19376.1.2.3

code: urn:ihe:pcc:cm:2008

display: Care Management

context:

encounter:

- identifier:

value: Encounter/4409815415

event:

- coding:

- system: http://snomed.info/sct

code: "861421000000109"

display: End of life care coordination summary

period:

start: "2022-12-21T09:00:41+11:00"

end: "2022-12-21T10:45:41+11:00"

facilityType:

coding:

- system: http://snomed.info/sct

code: "14866005"

display: Hospital outpatient mental health center

sourcePatientInfo:

identifier:

value: Patient/4409815415

related:

- identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: TRAFFORD GENERAL HOSPITAL

headers:

X-Correlation-Id:

$ref: "#/components/headers/CorrelationId"

X-Request-Id:

$ref: "#/components/headers/RequestId"

x-amazon-apigateway-integration:

type: aws_proxy

httpMethod: POST

uri: ${method_searchPostDocumentReference}

responses:

default:

statusCode: "200"

passthroughBehavior: when_no_match

contentHandling: CONVERT_TO_TEXT

description: |

Retrieve the document pointers for a single patient. Your request is constrained by the document pointer types

agreed during onboarding. The results can also be filtered to return documents by a given `type` and/or created

by a given `custodian`.

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.

/DocumentReference/{id}:

get:

tags:

summary: Get a single document pointer

operationId: readDocumentReference

parameters:

- $ref: "#/components/parameters/id"

- $ref: "#/components/parameters/odsCode"

- $ref: "#/components/parameters/odsCodeExtension"

- $ref: "#/components/parameters/requestId"

- $ref: "#/components/parameters/correlationId"

responses:

"200":

description: Search successful response

content:

application/fhir+json:

schema:

$ref: "#/components/schemas/DocumentReference"

example:

resourceType: DocumentReference

id: Y05868-1234567892

status: current

docStatus: final

type:

coding:

- system: http://snomed.info/sct

code: "887701000000100"

display: Emergency health care plan

category:

- coding:

- system: http://loinc.org

code: 68552-9

display: Emergency medicine Emergency department Admission evaluation note

subject:

identifier:

system: https://fhir.nhs.uk/Id/nhs-number

value: "4409815415"

date: "2022-12-22T11:45:41+11:00"

author:

- identifier:

value: Practitioner/A985657ZA

authenticator:

identifier:

value: Organization/Y05868

custodian:

identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: Y05868

securityLabel:

- coding:

- system: http://terminology.hl7.org/CodeSystem/v3-Confidentiality

code: V

display: very restricted

content:

- attachment:

contentType: application/pdf

language: en-US

url: https://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/EPAACS/EmergencyHealthPlan.pdf

creation: "2022-12-22T09:45:41+11:00"

format:

system: urn:oid:1.3.6.1.4.1.19376.1.2.3

code: urn:ihe:pcc:handp:2008

display: History and Physical Specification

context:

encounter:

- identifier:

value: Encounter/4409815415

event:

- coding:

- system: http://snomed.info/sct

code: "702779007"

display: Emergency health care plan agreed

period:

start: "2022-12-20T09:00:41+11:00"

end: "2022-12-20T09:45:41+11:00"

facilityType:

coding:

- system: http://snomed.info/sct

code: "453121000124107"

display: Emergency department healthcare professional

related:

- identifier:

system: https://fhir.nhs.uk/Id/ods-organization-code

value: EMERGENCY DEPT PRIMARY CARE STREAMING

headers:

X-Correlation-Id:

$ref: "#/components/headers/CorrelationId"

X-Request-Id:

$ref: "#/components/headers/RequestId"

x-amazon-apigateway-integration:

type: aws_proxy

httpMethod: POST

uri: ${method_readDocumentReference}

responses:

default:

statusCode: "200"

passthroughBehavior: when_no_match

contentHandling: CONVERT_TO_TEXT

description: |

Read a single document pointer by specifying the `DocumentReference.id`. Note that you will only be able to

retrieve document pointers that have the `type` that was agreed during the [onboarding](#api-description__onboarding) process.

/DocumentReference/_count:

get:

tags:

- DocumentReference

summary: Count document pointers

operationId: countDocumentReference

parameters:

- $ref: "#/components/parameters/subject"

- $ref: "#/components/parameters/odsCode"

- $ref: "#/components/parameters/odsCodeExtension"

- $ref: "#/components/parameters/requestId"

- $ref: "#/components/parameters/correlationId"

responses:

"200":

description: Count DocumentReference operation successful

headers:

X-Correlation-Id:

$ref: "#/components/headers/CorrelationId"

X-Request-Id:

$ref: "#/components/headers/RequestId"

content:

application/fhir+json:

schema:

$ref: "#/components/schemas/Bundle"

x-amazon-apigateway-integration:

type: aws_proxy

httpMethod: POST

uri: ${method_countDocumentReference}

responses:

default:

statusCode: "200"

passthroughBehavior: when_no_match

contentHandling: CONVERT_TO_TEXT

/_status:

get:

tags:

summary: _status endpoint for APIGEE integration

operationId: status

responses:

"200":

description: Consumer API is operational

content:

application/json:

schema:

type: object

properties:

message:

type: string

enum: ["OK"]

x-amazon-apigateway-integration:

type: aws_proxy

httpMethod: POST

uri: ${method_status}

responses:

default:

statusCode: "200"

passthroughBehavior: when_no_match

contentHandling: CONVERT_TO_TEXT

components:

requestBodies:

DocumentReference:

content:

application/fhir+json:

schema:

$ref: "#/components/schemas/DocumentReference"

required: true

schemas:

OperationOutcome:

type: object

properties:

resourceType:

type: string

enum:

- OperationOutcome

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.

meta:

$ref: "#/components/schemas/Meta"

description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.

implicitRules:

type: string

pattern: \S*

description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.

language:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: The base language in which the resource is written.

text:

$ref: "#/components/schemas/Narrative"

description: A human&ndash;readable narrative that contains a summary of the resource and can be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.

issue:

type: array

items:

$ref: "#/components/schemas/OperationOutcomeIssue"

description: An error, warning, or information message that results from a system action.

minItems: 1

required:

- resourceType

- issue

OperationOutcomeIssue:

type: object

properties:

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

severity:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: Indicates whether the issue indicates a variation from successful processing.

code:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: Describes the type of the issue. The system that creates an OperationOutcome SHALL choose the most applicable code from the IssueType value set, and may additional provide its own code for the error in the details element.

details:

$ref: "#/components/schemas/CodeableConcept"

description: Additional details about the error. This may be a text description of the error or a system code that identifies the error.

diagnostics:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: Additional diagnostic information about the issue.

location:

type: array

items:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: "This element is deprecated because it is XML specific. It is replaced by issue.expression, which is format independent, and simpler to parse. \n\nFor resource issues, this will be a simple XPath limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised. For HTTP errors, will be \"http.\" + the parameter name."

expression:

type: array

items:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: A [simple subset of FHIRPath](fhirpath.html#simple) limited to element names, repetition indicators and the default child accessor that identifies one of the elements in the resource that caused this issue to be raised.

required:

- severity

- code

DocumentReference:

type: object

properties:

resourceType:

type: string

enum:

- DocumentReference

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.

meta:

$ref: "#/components/schemas/Meta"

description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.

implicitRules:

type: string

pattern: \S*

description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.

language:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: The base language in which the resource is written.

text:

$ref: "#/components/schemas/Narrative"

description: A human&ndash;readable narrative that contains a summary of the resource and can be used to represent the content of the resource to a human. The narrative need not encode all the structured data, but is required to contain sufficient detail to make it "clinically safe" for a human to just read the narrative. Resource definitions may define what content should be represented in the narrative to ensure clinical safety.

masterIdentifier:

$ref: "#/components/schemas/Identifier"

description: Document identifier as assigned by the source of the document. This identifier is specific to this version of the document. This unique identifier may be used elsewhere to identify this version of the document.

identifier:

type: array

items:

$ref: "#/components/schemas/Identifier"

description: Other identifiers associated with the document, including version independent identifiers.

status:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: The status of this document reference.

docStatus:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: The status of the underlying document.

type:

$ref: "#/components/schemas/CodeableConcept"

description: Specifies the particular kind of document referenced (e.g. History and Physical, Discharge Summary, Progress Note). This usually equates to the purpose of making the document referenced.

category:

type: array

items:

$ref: "#/components/schemas/CodeableConcept"

description: A categorization for the type of document referenced &ndash; helps for indexing and searching. This may be implied by or derived from the code specified in the DocumentReference.type.

subject:

$ref: "#/components/schemas/Reference"

description: Who or what the document is about. The document can be about a person, (patient or healthcare practitioner), a device (e.g. a machine) or even a group of subjects (such as a document about a herd of farm animals, or a set of patients that share a common exposure).

date:

type: string

pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))

description: When the document reference was created.

author:

type: array

items:

$ref: "#/components/schemas/Reference"

description: Identifies who is responsible for adding the information to the document.

authenticator:

$ref: "#/components/schemas/Reference"

description: Which person or organization authenticates that this document is valid.

custodian:

$ref: "#/components/schemas/Reference"

description: Identifies the organization or group who is responsible for ongoing maintenance of and access to the document.

relatesTo:

type: array

items:

$ref: "#/components/schemas/DocumentReferenceRelatesTo"

description: Relationships that this document has with other document references that already exist.

description:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: Human&ndash;readable description of the source document.

securityLabel:

type: array

items:

$ref: "#/components/schemas/CodeableConcept"

description: A set of Security&ndash;Tag codes specifying the level of privacy/security of the Document. Note that DocumentReference.meta.security contains the security labels of the "reference" to the document, while DocumentReference.securityLabel contains a snapshot of the security labels on the document the reference refers to.

content:

type: array

items:

$ref: "#/components/schemas/DocumentReferenceContent"

description: The document and format referenced. There may be multiple content element repetitions, each with a different format.

minItems: 1

context:

$ref: "#/components/schemas/DocumentReferenceContext"

description: The clinical context in which the document was prepared.

required:

- resourceType

- status

- content

Bundle:

type: object

properties:

resourceType:

type: string

enum:

- Bundle

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: The logical id of the resource, as used in the URL for the resource. Once assigned, this value never changes.

meta:

$ref: "#/components/schemas/Meta"

description: The metadata about the resource. This is content that is maintained by the infrastructure. Changes to the content might not always be associated with version changes to the resource.

implicitRules:

type: string

pattern: \S*

description: A reference to a set of rules that were followed when the resource was constructed, and which must be understood when processing the content. Often, this is a reference to an implementation guide that defines the special rules along with other profiles etc.

language:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: The base language in which the resource is written.

identifier:

$ref: "#/components/schemas/Identifier"

description: A persistent identifier for the bundle that won't change as a bundle is copied from server to server.

type:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: Indicates the purpose of this bundle &ndash; how it is intended to be used.

timestamp:

type: string

pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))

description: The date/time that the bundle was assembled &ndash; i.e. when the resources were placed in the bundle.

total:

type: integer

format: int32

description: If a set of search matches, this is the total number of entries of type 'match' across all pages in the search. It does not include search.mode = 'include' or 'outcome' entries and it does not provide a count of the number of entries in the Bundle.

link:

type: array

items:

$ref: "#/components/schemas/BundleLink"

description: A series of links that provide context to this bundle.

entry:

type: array

items:

$ref: "#/components/schemas/BundleEntry"

description: An entry in a bundle resource &ndash; will either contain a resource or information about a resource (transactions and history only).

signature:

$ref: "#/components/schemas/Signature"

description: Digital Signature &ndash; base64 encoded. XML&ndash;DSig or a JWT.

required:

- resourceType

- type

BundleEntry:

type: object

properties:

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

link:

type: array

items:

$ref: "#/components/schemas/BundleLink"

description: A series of links that provide context to this entry.

fullUrl:

type: string

pattern: \S*

description: "The Absolute URL for the resource. The fullUrl SHALL NOT disagree with the id in the resource &ndash; i.e. if the fullUrl is not a urn:uuid, the URL shall be version&ndash;independent URL consistent with the Resource.id. The fullUrl is a version independent reference to the resource. The fullUrl element SHALL have a value except that: \n* fullUrl can be empty on a POST (although it does not need to when specifying a temporary id for reference in the bundle)\n* Results from operations might involve resources that are not identified."

resource:

$ref: "#/components/schemas/DocumentReference"

description: The Resource for the entry. The purpose/meaning of the resource is determined by the Bundle.type.

search:

$ref: "#/components/schemas/BundleEntrySearch"

description: Information about the search process that lead to the creation of this entry.

request:

$ref: "#/components/schemas/BundleEntryRequest"

description: Additional information about how this entry should be processed as part of a transaction or batch. For history, it shows how the entry was processed to create the version contained in the entry.

response:

$ref: "#/components/schemas/BundleEntryResponse"

description: Indicates the results of processing the corresponding 'request' entry in the batch or transaction being responded to or what the results of an operation where when returning history.

BundleEntryResponse:

type: object

properties:

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

status:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: The status code returned by processing this entry. The status SHALL start with a 3 digit HTTP code (e.g. 404) and may contain the standard HTTP description associated with the status code.

location:

type: string

pattern: \S*

description: The location header created by processing this operation, populated if the operation returns a location.

etag:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: The Etag for the resource, if the operation for the entry produced a versioned resource (see [Resource Metadata and Versioning](http.html#versioning) and [Managing Resource Contention](http.html#concurrency)).

lastModified:

type: string

pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))

description: The date/time that the resource was modified on the server.

outcome:

$ref: "#/components/schemas/DocumentReference"

description: An OperationOutcome containing hints and warnings produced as part of processing this entry in a batch or transaction.

required:

- status

BundleEntryRequest:

type: object

properties:

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

method:

type: string

pattern: "[^\\s]+(\\s[^\\s]+)*"

description: In a transaction or batch, this is the HTTP action to be executed for this entry. In a history bundle, this indicates the HTTP action that occurred.

url:

type: string

pattern: \S*

description: The URL for this entry, relative to the root (the address to which the request is posted).

ifNoneMatch:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: If the ETag values match, return a 304 Not Modified status. See the API documentation for ["Conditional Read"](http.html#cread).

ifModifiedSince:

type: string

pattern: ([0-9]([0-9]([0-9][1-9]|[1-9]0)|[1-9]00)|[1-9]000)-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])T([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\.[0-9]+)?(Z|(\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))

description: Only perform the operation if the last updated date matches. See the API documentation for ["Conditional Read"](http.html#cread).

ifMatch:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: Only perform the operation if the Etag value matches. For more information, see the API section ["Managing Resource Contention"](http.html#concurrency).

ifNoneExist:

type: string

pattern: "[ \\r\\n\\t\\S]+"

description: Instruct the server not to perform the create if a specified resource already exists. For further information, see the API documentation for ["Conditional Create"](http.html#ccreate). This is just the query portion of the URL &ndash; what follows the "?" (not including the "?").

required:

- method

- url

BundleEntrySearch:

type: object

properties:

id:

type: string

pattern: "[A-Za-z0-9\\-\\.]{1,64}"

description: Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

mode: