PACIO Advance Healthcare Directive Interoperability Implementation Guide
2.0.0-ballot - STU 2 – Ballot

PACIO Advance Healthcare Directive Interoperability Implementation Guide, published by HL7 International / Patient Empowerment. This guide is not an authorized publication; it is the continuous build for version 2.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/pacio-adi/ and changes regularly. See the Directory of published versions

## CapabilityStatement: ADI CapabilityStatement

Official URL: http://hl7.org/fhir/us/pacio-adi/CapabilityStatement/adi | Version: 2.0.0-ballot
Standards status: Trial-use | Maturity Level: 2 | Computable Name: PacioAdiCapabilityStatement

This Section describes the expected capabilities of the PACIO Advance Directive Interoperability (ADI) Server actor which is responsible for providing responses to the queries submitted by the ADI Requestors.

There are two primary vehicles in which Advance Directive Information can be conveyed: DocumentReference and Bundle. Through a DocumentReference, the ADI may be encoded inside directly as content data or referred to through a content reference (pointing to the ADI included in a resource like Binary) or reference a Bundle with the type=document for FHIR encoded data. The resources referred to by the Composition in the document bundle include Patient, Observation,Goal, ServiceRequest, Organization, RelatedPerson, Consent, List, and Provenance.

Raw OpenAPI-Swagger Definition file | Download

## ADI CapabilityStatement

- Implementation Guide Version: 0.0.1
- FHIR Version: 4.0.1
- Supported formats: xml, json
- Published: 2023-11-09
- Published by: HL7 Patient Empowerment Working Group (PE WG)

This Section describes the expected capabilities of the PACIO Advance Directive Interoperability (ADI) Server actor which is responsible for providing responses to the queries submitted by the ADI Requestors.

There are two primary vehicles in which Advance Directive Information can be conveyed: DocumentReference and Bundle. Through a DocumentReference, the ADI may be encoded inside directly as content data or referred to through a content reference (pointing to the ADI included in a resource like Binary) or reference a Bundle with the type=document for FHIR encoded data. The resources referred to by the Composition in the document bundle include Patient, Observation, Goal, ServiceRequest, Organization, RelatedPerson, Consent, List, and Provenance.

### FHIR RESTful Capabilities

The ADI Server SHALL:

1. Support all profiles defined in this Implementation Guide.
2. Implement the RESTful behavior according to the FHIR specification.
3. Return the following response classes:
   - (Status 400): invalid parameter
   - (Status 401/4xx): unauthorized request
   - (Status 403): insufficient scope
   - (Status 404): unknown resource
   - (Status 410): deleted resource.
4. Support json source formats for all ADI interactions.
5. Support the searchParameters on each profile individually and in combination.

The ADI Server SHOULD:

1. Support xml source formats for all ADI interactions.

Security:

1. See the Guidance section for requirements and recommendations.
2. A server SHALL reject any unauthorized requests by returning an HTTP 401 "Unauthorized", HTTP 403 "Forbidden", or HTTP 404 "Not Found" response code.

### RESTful Capabilities by Resource/Profile:

Summary of Search Criteria

Resource Type | Supported Profiles | Supported Searches | Supported `_includes` | Supported `_revincludes` | Supported Operations
--- | --- | --- | --- | --- | ---
Bundle |  | _id, composition, identifier, timestamp, type |  |  |
Composition | ADI-Composition-Header, ADI-PACPComposition |  |  |  |
Consent | ADI-HealthcareAgentConsent |  |  |  |
DocumentReference | ADI-DocumentReference | _id, authenticator, author, category, contenttype, custodian, date, description, encounter, event, facility, format, identifier, language, location, patient, period, related, relatesto, relation, relationship, security-label, setting, status, subject, type |  |  |
Goal | ADI-PersonalGoal |  |  |  |
List | ADI-PersonalPrioritiesOrganizer |  |  |  |
Observation | ADI-DocumentationObservation, ADI-PersonalInterventionPreference, ADI-OrganDonationObservation, ADI-AutopsyObservation, ADI-CareExperiencePreference |  |  |  |
Organization |  |  |  |  |
Patient | us-core-patient | _id, active, address, address-city, address-country, address-postalcode, address-state, address-use, birthdate, death-date, deceased, email, family, gender, general-practitioner, given, identifier, language, link, name, organization, phone, phonetic, telecom, race, ethnicity |  |  | $match
Provenance | ADI-Provenance |  |  |  |
RelatedPerson | ADI-HealthcareAgent, ADI-Guardian |  |  |  |

#### Bundle

Conformance Expectation: SHALL

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `create`, `read`, `update`.
- SHOULD support `search-type`, `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Bundle resource using: `GET [base]/Bundle/[id]`
- A Server SHOULD be capable of returning a Bundle resource using: `GET [base]/Bundle/[id]/_history/vid`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHOULD | _id | token | `GET [base]/Bundle?_id=[id]`
SHOULD | composition | reference | `GET [base]/Bundle?composition=[composition]`
SHOULD | identifier | token | `GET [base]/Bundle?identifier=[system]|[code]`
SHOULD | timestamp | date | `GET [base]/Bundle?timestamp=[timestamp]`
SHOULD | type | token | `GET [base]/Bundle?type=[system]|[code]`

#### Composition

Conformance Expectation: MAY

Supported Profiles: ADI-Composition-Header, ADI-PACPComposition

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a Composition resource using: `GET [base]/Composition/[id]`
- A Server SHOULD be capable of returning a Composition resource using: `GET [base]/Composition/[id]/_history/vid`

#### Consent

Conformance Expectation: MAY

Supported Profiles: ADI-HealthcareAgentAuthority, ADI-HealthcareAgentConsent

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a Consent resource using: `GET [base]/Consent/[id]`
- A Server SHOULD be capable of returning a Consent resource using: `GET [base]/Consent/[id]/_history/vid`

#### DocumentReference

Conformance Expectation: SHALL

Supported Profiles: ADI-DocumentReference

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a DocumentReference resource using: `GET [base]/DocumentReference/[id]`
- A Server SHOULD be capable of returning a DocumentReference resource using: `GET [base]/DocumentReference/[id]/_history/vid`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | _id | token | `GET [base]/DocumentReference?_id=[id]`
MAY | authenticator | reference | `GET [base]/DocumentReference?authenticator=[authenticator]`
MAY | author | reference | `GET [base]/DocumentReference?author=[author]`
SHOULD | category | token | `GET [base]/DocumentReference?category=[system]|[code]`
SHOULD | contenttype | token | `GET [base]/DocumentReference?contenttype=[system]|[code]`
SHALL | custodian | reference | `GET [base]/DocumentReference?custodian=[custodian]`
SHALL | date | date | `GET [base]/DocumentReference?date=[date]`
MAY | description | string | `GET [base]/DocumentReference?description=[description]`
MAY | encounter | reference | `GET [base]/DocumentReference?encounter=[encounter]`
MAY | event | token | `GET [base]/DocumentReference?event=[system]|[code]`
MAY | facility | token | `GET [base]/DocumentReference?facility=[system]|[code]`
SHOULD | format | token | `GET [base]/DocumentReference?format=[system]|[code]`
SHALL | identifier | token | `GET [base]/DocumentReference?identifier=[system]|[code]`
MAY | language | token | `GET [base]/DocumentReference?language=[system]|[code]`
MAY | location | uri | `GET [base]/DocumentReference?location=[uri]`
SHALL | patient | reference | `GET [base]/DocumentReference?patient=[patient]`
SHALL | period | date | `GET [base]/DocumentReference?period=[period]`
MAY | related | reference | `GET [base]/DocumentReference?related=[related]`
MAY | relatesto | reference | `GET [base]/DocumentReference?relatesto=[relatesto]`
MAY | relation | token | `GET [base]/DocumentReference?relation=[system]|[code]`
MAY | relationship | composite | `GET [base]/DocumentReference?relationship=[code]&[value]`
MAY | security-label | token | `GET [base]/DocumentReference?security-label=[system]|[code]`
MAY | setting | token | `GET [base]/DocumentReference?setting=[system]|[code]`
SHALL | status | token | `GET [base]/DocumentReference?status=[status]`
MAY | subject | reference | `GET [base]/DocumentReference?subject=[subject]`
SHALL | type | token | `GET [base]/DocumentReference?type=[system]|[code]`

#### Goal

Conformance Expectation: MAY

Supported Profiles: ADI-PersonalGoal

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a Goal resource using: `GET [base]/Goal/[id]`
- A Server SHOULD be capable of returning a Goal resource using: `GET [base]/Goal/[id]/_history/vid`

#### List

Conformance Expectation: MAY

Supported Profiles: ADI-PersonalPrioritiesOrganizer

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a List resource using: `GET [base]/List/[id]`
- A Server SHOULD be capable of returning a List resource using: `GET [base]/List/[id]/_history/vid`

#### Observation

Conformance Expectation: MAY

Supported Profiles: ADI-DocumentationObservation, ADI-PersonalInterventionPreference, ADI-OrganDonationObservation, ADI-AutopsyObservation, ADI-CareExperiencePreference

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a Observation resource using: `GET [base]/Observation/[id]`
- A Server SHOULD be capable of returning a Observation resource using: `GET [base]/Observation/[id]/_history/vid`

#### Organization

Conformance Expectation: SHALL

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Organization resource using: `GET [base]/Organization/[id]`
- A Server SHOULD be capable of returning a Organization resource using: `GET [base]/Organization/[id]/_history/vid`

#### Patient

Conformance Expectation: MAY

Supported Profiles: us-core-patient

Reference Policy: `resolves`

Profile Interaction Summary:

- SHALL support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server SHALL be capable of returning a Patient resource using: `GET [base]/Patient/[id]`
- A Server SHOULD be capable of returning a Patient resource using: `GET [base]/Patient/[id]/_history/vid`

Search Parameter Summary:

Conformance | Parameter | Type | Example
--- | --- | --- | ---
SHALL | _id | token | `GET [base]/Patient?_id=[id]`
SHOULD | active | token | `GET [base]/Patient?active=[system]|[code]`
MAY | address | string | `GET [base]/Patient?address=[address]`
MAY | address-city | string | `GET [base]/Patient?address-city=[address-city]`
MAY | address-country | string | `GET [base]/Patient?address-country=[address-country]`
MAY | address-postalcode | string | `GET [base]/Patient?address-postalcode=[address-postalcode]`
MAY | address-state | string | `GET [base]/Patient?address-state=[address-state]`
MAY | address-use | token | `GET [base]/Patient?address-use=[system]|[code]`
SHALL | birthdate | date | `GET [base]/Patient?birthdate=[birthdate]`
MAY | death-date | date | `GET [base]/Patient?death-date=[death-date]`
MAY | deceased | token | `GET [base]/Patient?deceased=[system]|[code]`
SHOULD | email | token | `GET [base]/Patient?email=[system]|[code]`
SHALL | family | string | `GET [base]/Patient?family=[family]`
SHALL | gender | token | `GET [base]/Patient?gender=[system]|[code]`
MAY | general-practitioner | reference | `GET [base]/Patient?general-practitioner=[general-practitioner]`
SHALL | given | string | `GET [base]/Patient?given=[given]`
SHALL | identifier | token | `GET [base]/Patient?identifier=[system]|[code]`
MAY | language | token | `GET [base]/Patient?language=[system]|[code]`
MAY | link | reference | `GET [base]/Patient?link=[link]`
SHALL | name | string | `GET [base]/Patient?name=[name]`
MAY | organization | reference | `GET [base]/Patient?organization=[organization]`
SHOULD | phone | token | `GET [base]/Patient?phone=[system]|[code]`
MAY | phonetic | string | `GET [base]/Patient?phonetic=[phonetic]`
SHOULD | telecom | token | `GET [base]/Patient?telecom=[system]|[code]`
MAY | race | token | `GET [base]/Patient?race=[system]|[code]`
MAY | ethnicity | token | `GET [base]/Patient?ethnicity=[system]|[code]`

Operation: $match

The $match operation is used to manage patient identification in a context where multiple patient databases exist.To ask an MPI to match a patient, clients use the '$match' operation, which accepts a patient resource which may be only partially complete. The data provided is interpreted as an MPI input and processed by an algorithm of some kind that uses the data to determine the most appropriate matches in the patient set.

Conformance Expectation: SHOULD

Documentation:

- A Server SHOULD be capable of returning a unique patient match using: `GET [base]/Patient/$match`

#### Provenance

Conformance Expectation: MAY

Supported Profiles: ADI-Provenance

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a Provenance resource using: `GET [base]/Provenance/[id]`
- A Server SHOULD be capable of returning a Provenance resource using: `GET [base]/Provenance/[id]/_history/vid`

#### RelatedPerson

Conformance Expectation: MAY

Supported Profiles: ADI-HealthcareAgent, ADI-Guardian

Reference Policy: `resolves`

Profile Interaction Summary:

- MAY support `create`, `search-type`, `read`, `update`.
- SHOULD support `vread`, `history-instance`.

Fetch and Search Criteria:

- A Server MAY be capable of returning a RelatedPerson resource using: `GET [base]/RelatedPerson/[id]`
- A Server SHOULD be capable of returning a RelatedPerson resource using: `GET [base]/RelatedPerson/[id]/_history/vid`