PACIO Advance Directive Interoperability Implementation Guide
2.1.0 - STU 2 United States of America flag

PACIO Advance 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.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-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.1.0
Active as of 2023-11-10 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 TypeSupported ProfilesSupported SearchesSupported _includesSupported _revincludesSupported Operations
Bundle _id, composition, identifier, timestamp, type
CompositionADI-Composition-Header, ADI-PACPComposition
ConsentADI-HealthcareAgentAuthority, ADI-ConsentForHealthcareAgent
DocumentReferenceADI-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
GoalADI-PersonalGoal
ListADI-PersonalPrioritiesOrganizer
ObservationADI-DocumentationObservation, ADI-PersonalInterventionPreference, ADI-OrganDonationObservation, ADI-AutopsyObservation, ADI-CareExperiencePreference
Organization
Patientus-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
ProvenanceADI-Provenance
RelatedPersonADI-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:

ConformanceParameterTypeExample
SHOULD_id token GET [base]/Bundle?_id=[id]
SHOULDcomposition reference GET [base]/Bundle?composition=[composition]
SHOULDidentifier token GET [base]/Bundle?identifier=[system]|[code]
SHOULDtimestamp date GET [base]/Bundle?timestamp=[timestamp]
SHOULDtype 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

Conformance Expectation: MAY

Supported Profiles: ADI-HealthcareAgentAuthority, ADI-ConsentForHealthcareAgent

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:

ConformanceParameterTypeExample
SHALL_id token GET [base]/DocumentReference?_id=[id]
MAYauthenticator reference GET [base]/DocumentReference?authenticator=[authenticator]
MAYauthor reference GET [base]/DocumentReference?author=[author]
SHOULDcategory token GET [base]/DocumentReference?category=[system]|[code]
SHOULDcontenttype token GET [base]/DocumentReference?contenttype=[system]|[code]
SHALLcustodian reference GET [base]/DocumentReference?custodian=[custodian]
SHALLdate date GET [base]/DocumentReference?date=[date]
MAYdescription string GET [base]/DocumentReference?description=[description]
MAYencounter reference GET [base]/DocumentReference?encounter=[encounter]
MAYevent token GET [base]/DocumentReference?event=[system]|[code]
MAYfacility token GET [base]/DocumentReference?facility=[system]|[code]
SHOULDformat token GET [base]/DocumentReference?format=[system]|[code]
SHALLidentifier token GET [base]/DocumentReference?identifier=[system]|[code]
MAYlanguage token GET [base]/DocumentReference?language=[system]|[code]
MAYlocation uri GET [base]/DocumentReference?location=[uri]
SHALLpatient reference GET [base]/DocumentReference?patient=[patient]
SHALLperiod date GET [base]/DocumentReference?period=[period]
MAYrelated reference GET [base]/DocumentReference?related=[related]
MAYrelatesto reference GET [base]/DocumentReference?relatesto=[relatesto]
MAYrelation token GET [base]/DocumentReference?relation=[system]|[code]
MAYrelationship composite GET [base]/DocumentReference?relationship=[code]&[value]
MAYsecurity-label token GET [base]/DocumentReference?security-label=[system]|[code]
MAYsetting token GET [base]/DocumentReference?setting=[system]|[code]
SHALLstatus token GET [base]/DocumentReference?status=[status]
MAYsubject reference GET [base]/DocumentReference?subject=[subject]
SHALLtype 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:

ConformanceParameterTypeExample
SHALL_id token GET [base]/Patient?_id=[id]
SHOULDactive token GET [base]/Patient?active=[system]|[code]
MAYaddress string GET [base]/Patient?address=[address]
MAYaddress-city string GET [base]/Patient?address-city=[address-city]
MAYaddress-country string GET [base]/Patient?address-country=[address-country]
MAYaddress-postalcode string GET [base]/Patient?address-postalcode=[address-postalcode]
MAYaddress-state string GET [base]/Patient?address-state=[address-state]
MAYaddress-use token GET [base]/Patient?address-use=[system]|[code]
SHALLbirthdate date GET [base]/Patient?birthdate=[birthdate]
MAYdeath-date date GET [base]/Patient?death-date=[death-date]
MAYdeceased token GET [base]/Patient?deceased=[system]|[code]
SHOULDemail token GET [base]/Patient?email=[system]|[code]
SHALLfamily string GET [base]/Patient?family=[family]
SHALLgender token GET [base]/Patient?gender=[system]|[code]
MAYgeneral-practitioner reference GET [base]/Patient?general-practitioner=[general-practitioner]
SHALLgiven string GET [base]/Patient?given=[given]
SHALLidentifier token GET [base]/Patient?identifier=[system]|[code]
MAYlanguage token GET [base]/Patient?language=[system]|[code]
MAYlink reference GET [base]/Patient?link=[link]
SHALLname string GET [base]/Patient?name=[name]
MAYorganization reference GET [base]/Patient?organization=[organization]
SHOULDphone token GET [base]/Patient?phone=[system]|[code]
MAYphonetic string GET [base]/Patient?phonetic=[phonetic]
SHOULDtelecom token GET [base]/Patient?telecom=[system]|[code]
MAYrace token GET [base]/Patient?race=[system]|[code]
MAYethnicity 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