# Patient-Shared Health Document via SMART Health Links
> **Status:** Draft
> **Version:** 0.2.0
## Introduction
This implementation guide defines a constrained profile of SMART Health Links (SHLinks) for patient-to-provider sharing of health documents at the point of care. A patient presents a QR code; the provider's EHR scans it, downloads an encrypted PDF, and stores it.
### Requirements
> 1. Patient app creates a SHLink pointing to any FHIR resources, and including a DocumentReference to a "Patient-Shared PDF". This PDF should include:
> - All available USCDI data or a summary of elements specified by IPS, as filtered/selected by the patient. (Discrete data shared in the PDF should also be offered as FHIR discrete data.)
> - Any additional information the patient wants to share
>
> 2. The provider can scan the SHLink QR, resolve + decrypt the data, and store this information.
> - At minimum, the EHR must be able to store the Patient-Shared PDF and present it to users.
> - The EHR may also display, ingest, and use other content from the SHLink.
>
> 3. At no point in this flow does a patient need to sign into an EHR Portal.
>
> — *Kill the Clipboard Working Group, 1/30/2025*
### Scope
This IG defines:
1. SHLink payload constraints for patient-shared documents
2. A FHIR Bundle profile containing the patient summary and DocumentReference
3. Requirements for patient apps (senders) and EHRs (receivers)
### Actors
| Actor | Role |
|-------|------|
| Patient App | Generates SHLink QR containing encrypted patient summary |
| Patient | Presents QR to provider |
| Provider EHR | Scans QR, downloads and stores patient-shared document |
---
## Workflow
```
┌──────────────┐ ┌──────────────┐
│ Patient App │ │ Provider │
│ │ │ EHR │
│ 1. Generate │ 2. Present QR │ │
│ PDF │ ─────────────────────────────────► │ 3. Scan QR │
│ + Bundle │ │ │
│ + SHLink │ │ 4. Decode │
│ │ │ SHLink │
│ │ 5. HTTP GET (+recipient) │ │
│ │ ◄───────────────────────────────── │ │
│ │ │ │
│ │ 6. Encrypted payload │ │
│ │ ─────────────────────────────────► │ 7. Decrypt │
│ │ │ + Store │
│ 8. Audit log │ │ │
└──────────────┘ └──────────────┘
```
> **Try it:** A working prototype with a sample QR code is available at [pshd-shl.exe.xyz/prototype.html](https://pshd-shl.exe.xyz/prototype.html).
---
## SHLink Constraints
This IG profiles the [SMART Health Links specification](https://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/links-specification.html) with the following constraints.
### SHLink Payload (decoded)
```json
{
"url": "https://patient-app.example.com/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM",
"flag": "U",
"key": "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q",
"exp": 1706745600,
"label": "Jessica Argonaut's health summary"
}
```
| Field | Cardinality | Constraint |
|-------|-------------|------------|
| `url` | 1..1 | Endpoint returning encrypted payload |
| `flag` | 1..1 | `U` (direct retrieval; this is the SHLink default) |
| `key` | 1..1 | Decryption key |
| `exp` | 1..1 | **Required.** Expiration timestamp. SHOULD be short-lived for sensitive data. |
| `label` | 0..1 | Human-readable description |
Patient Apps SHALL generate SHLinks with the `U` flag, meaning the link resolves directly to a single encrypted file without requiring a passcode. Since this is the default SHLink behavior, most implementations will already conform.
---
## Retrieval Protocol
With the `U` flag, the SHLink URL resolves directly to a single encrypted file (bypassing the manifest).
### Request
The EHR retrieves the encrypted payload via HTTP GET. The EHR **SHALL** supply a `recipient` query parameter identifying the requesting organization.
```http
GET https://patient-app.example.com/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM
?recipient=Verona+Health+System
```
| Parameter | Cardinality | Description |
|-----------|-------------|-------------|
| `recipient` | 1..1 | Organization name requesting access. Appropriate for display to patient in audit log. |
### Response
```http
HTTP/1.1 200 OK
Content-Type: application/jose
```
Body contains a JWE (JSON Web Encryption) compact serialization string.
### Decryption
Per the SHLink specification, files are encrypted using JWE with:
- `"alg": "dir"` (direct encryption with shared symmetric key)
- `"enc": "A256GCM"` (AES-256-GCM)
- `"cty": "application/fhir+json"` (content type of decrypted payload)
The EHR decrypts using the 32-byte `key` from the SHLink payload (base64url-decoded) to obtain the FHIR Bundle.
**Example JWE structure (compact serialization):**
```
eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiY3R5IjoiYXBwbGljYXRpb24vZmhpcitqc29uIn0
..
<IV>
.
<ciphertext>
.
<authentication tag>
```
The decrypted payload is a FHIR Bundle conforming to the PatientSharedBundle profile.
---
## FHIR Bundle Profile: PatientSharedBundle
The decrypted payload is a FHIR Bundle conforming to this profile.
**Canonical URL:** `https://cms.gov/fhir/StructureDefinition/patient-shared-bundle`
### Structure
```
Bundle (type: collection)
├── Patient (1..1)
├── DocumentReference (1..1) - PatientSharedDocumentReference profile
│ └── content.attachment - embedded PDF (base64)
└── [Additional FHIR resources]* (0..*)
```
### Constraints
| Element | Cardinality | Constraint |
|---------|-------------|------------|
| `type` | 1..1 | Fixed: `collection` |
| `timestamp` | 1..1 | When bundle was assembled |
| `entry` | 2..* | Minimum: Patient + DocumentReference |
| `entry:patient` | 1..1 | Patient resource |
| `entry:documentReference` | 1..1 | Conforms to PatientSharedDocumentReference |
> **Note:** Resources in this Bundle SHOULD NOT include `meta.profile`. Receivers SHALL NOT require `meta.profile` to be present.
### Example
```json
{
"resourceType": "Bundle",
"type": "collection",
"timestamp": "2026-01-30T12:00:00Z",
"entry": [
{
"fullUrl": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a",
"resource": {
"resourceType": "Patient",
"name": [{"given": ["Jessica"], "family": "Argonaut"}],
"birthDate": "1985-03-15",
"gender": "female"
}
},
{
"fullUrl": "urn:uuid:c7a2f8e1-3d4b-5c6a-9e8f-0a1b2c3d4e5f",
"resource": {
"resourceType": "DocumentReference",
"meta": {
"security": [{
"system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
"code": "PATAST",
"display": "patient asserted"
}]
},
"status": "current",
"type": {
"coding": [{
"system": "http://loinc.org",
"code": "60591-5",
"display": "Patient summary Document"
}]
},
"category": [{
"coding": [{
"system": "https://cms.gov/fhir/CodeSystem/patient-shared-category",
"code": "patient-shared",
"display": "Patient-Shared"
}]
}],
"subject": {
"reference": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a"
},
"author": [{
"reference": "urn:uuid:b5e506f4-e14c-4e27-9543-4b8d1e1f3e2a"
}],
"date": "2026-01-30T12:00:00Z",
"description": "Patient-shared health summary",
"content": [{
"attachment": {
"contentType": "application/pdf",
"data": "JVBERi0xLjQKJeLjz9..."
}
}]
}
}
]
}
```
---
## DocumentReference Profile: PatientSharedDocumentReference
**Canonical URL:** `https://cms.gov/fhir/StructureDefinition/patient-shared-document-reference`
**Based on:** [US Core DocumentReference](http://hl7.org/fhir/us/core/StructureDefinition-us-core-documentreference.html)
This profile aligns with the US Core [Writing Clinical Notes](https://build.fhir.org/ig/HL7/US-Core/writing-clinical-notes.html) guidance for patient-asserted content.
### Constraints
| Element | Cardinality | Constraint |
|---------|-------------|------------|
| `meta.security` | 0..* | SHOULD include `PATAST` (patient asserted) from `http://terminology.hl7.org/CodeSystem/v3-ObservationValue` |
| `status` | 1..1 | Fixed: `current` |
| `type` | 1..1 | Fixed: LOINC `60591-5` (Patient summary Document) |
| `category` | 1..* | SHALL include `https://cms.gov/fhir/CodeSystem/patient-shared-category#patient-shared` |
| `subject` | 1..1 | Reference(Patient) in same Bundle |
| `author` | 1..* | SHALL include Reference(Patient) — the patient is the author/sharer |
| `date` | 1..1 | When document was shared |
| `content` | 1..1 | |
| `content.attachment.contentType` | 1..1 | Fixed: `application/pdf` |
| `content.attachment.data` | 1..1 | Base64-encoded PDF |
---
## Terminology
### CodeSystem: PatientSharedCategory
**Canonical URL:** `https://cms.gov/fhir/CodeSystem/patient-shared-category`
| Code | Display | Definition |
|------|---------|------------|
| `patient-shared` | Patient-Shared | Document shared by the patient via patient-mediated exchange |
```json
{
"resourceType": "CodeSystem",
"id": "patient-shared-category",
"url": "https://cms.gov/fhir/CodeSystem/patient-shared-category",
"version": "0.2.0",
"name": "PatientSharedCategory",
"title": "Patient-Shared Document Category",
"status": "draft",
"experimental": true,
"description": "Code indicating a document was shared by the patient via patient-mediated exchange such as SMART Health Links",
"caseSensitive": true,
"content": "complete",
"concept": [
{
"code": "patient-shared",
"display": "Patient-Shared",
"definition": "Document shared by the patient or their authorized representative via patient-mediated exchange"
}
]
}
```
---
## Conformance Requirements
### Patient App (Sender)
**SHALL:**
- Generate SHLink with `flag` = `U`
- Include `exp` (expiration) in SHLink payload
- Serve encrypted payload without requiring authentication
- Return encrypted FHIR Bundle conforming to PatientSharedBundle profile
- Include DocumentReference conforming to PatientSharedDocumentReference profile
- Embed PDF as base64 in `DocumentReference.content.attachment.data`
- Accept `recipient` query parameter on retrieval endpoint
- Audit each SHLink access with recipient and timestamp
**SHOULD:**
- Set short-lived expiration for sensitive data
- Enable patient to view audit log of who accessed their SHLink
- Minimize IP geofencing to enable reasonable international use
- Include Patient resource with sufficient demographics for matching
- Include `meta.security` with `PATAST` on DocumentReference
**MAY:**
- Include additional discrete FHIR resources (medications, conditions, etc.)
### Provider EHR (Receiver)
**SHALL:**
- Scan and decode SHLink QR codes
- Supply `recipient` query parameter identifying requesting organization
- Decrypt payload using key from SHLink
- Parse PatientSharedBundle
- Store the PDF from the DocumentReference
- Display PDF to clinical users
- Indicate patient-shared provenance in clinical UI
**SHALL NOT:**
- Require `meta.profile` to be present on any resource
**SHOULD:**
- Display patient demographics from Bundle for verification
- Support clinician review before filing to chart
**MAY:**
- Parse and display additional FHIR resources from Bundle
- Ingest discrete data into structured EHR fields
---
## Security Considerations
### Encryption
Per the SHLink specification, files are encrypted using JSON Web Encryption (JWE) compact serialization:
| Parameter | Value |
|-----------|-------|
| `alg` | `dir` (direct encryption — key used directly, no key wrapping) |
| `enc` | `A256GCM` (AES-256-GCM authenticated encryption) |
| `cty` | `application/fhir+json` (content type of plaintext) |
The 32-byte symmetric key is embedded in the SHLink payload (base64url-encoded as 43 characters). Security relies on:
1. The key never being transmitted to the server separately
2. The key being embedded in the QR/URL fragment (not logged by servers)
3. Physical control of the QR by the patient
### Expiration
The `exp` field is **required** in this profile. Apps SHOULD set short-lived expirations appropriate to the use case:
| Scenario | Suggested Expiration |
|----------|---------------------|
| In-person visit (QR on phone screen) | 5–15 minutes |
| Printed QR for scheduled appointment | 24–48 hours |
| Ongoing care relationship | Per patient preference |
### Audit
Patient Apps SHALL maintain audit logs of SHLink access including:
- Timestamp
- Recipient organization (from query parameter)
---
## References
- [SMART Health Links Specification (STU1)](https://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/links-specification.html)
- [US Core DocumentReference](http://hl7.org/fhir/us/core/StructureDefinition-us-core-documentreference.html)
- [US Core Writing Clinical Notes](https://build.fhir.org/ig/HL7/US-Core/writing-clinical-notes.html)
- [International Patient Summary (IPS)](http://hl7.org/fhir/uv/ips/)
- [USCDI v3](https://www.healthit.gov/isa/united-states-core-data-interoperability-uscdi)
Sign in with Wallet
Connect another wallet