---
# System prepended metadata

title: Patient-Shared Health Document via SMART Health Links

---

# 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)