# Use Case Catalog - SMART Permission Tickets v0.1.0

* [**Table of Contents**](toc.md)
* **Use Case Catalog**

## Use Case Catalog

This page lists the current `ticket_type` registry for the seven core Permission Ticket use cases.

| | |
| :--- | :--- |
| Use Case 1: Patient Self Access | `https://smarthealthit.org/permission-ticket-type/patient-self-access-v1` |
| Use Case 2: Patient-Delegated Access | `https://smarthealthit.org/permission-ticket-type/patient-delegated-access-v1` |
| Use Case 3: Public Health Investigation | `https://smarthealthit.org/permission-ticket-type/public-health-investigation-v1` |
| Use Case 4: Social Care (CBO) Referral | `https://smarthealthit.org/permission-ticket-type/social-care-referral-v1` |
| Use Case 5: Payer Claims Adjudication | `https://smarthealthit.org/permission-ticket-type/payer-claims-adjudication-v1` |
| Use Case 6: Research Study | `https://smarthealthit.org/permission-ticket-type/research-study-access-v1` |
| Use Case 7: Provider-to-Provider Consult | `https://smarthealthit.org/permission-ticket-type/provider-consult-v1` |

#### Per-Profile Constraints

The table below summarizes required and optional fields for each ticket type:

| | | | | |
| :--- | :--- | :--- | :--- | :--- |
| UC1: Patient Self Access | Required unless self-issued presenter rule applies | — | **(none)** | `permissions`(required) |
| UC2: Patient-Delegated Access | Optional | `RelatedPerson`(required) | **(none)** | `permissions`(required) |
| UC3: Public Health | Optional | `Organization`(required) | `reportable_condition` | `permissions`,`data_period`,`data_holder_filter` |
| UC4: Social Care | Optional | `Organization`(required) | `concern`,`referral` | `permissions` |
| UC5: Payer Claims | Optional | `Organization`(required) | `service`,`claim` | `permissions`,`data_period`,`data_holder_filter` |
| UC6: Research | Optional | `Organization`(required) | `study` | `permissions`,`data_period` |
| UC7: Provider Consult | Optional | `PractitionerRole`(required) | `reason`,`consult_request` | `permissions` |

#### Use Case 1: Patient Self Access

**A patient uses a high-assurance Digital ID wallet to authorize an app to fetch their data from multiple hospitals.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics) or profile-defined `subject_identity_evidence`.
* **Requester:** None (self-access).
* **Identity evidence:** Profiles may require `subject_identity_evidence`; see [Proposal 004](proposal-004-app-issued-tickets.md) for app-issued tickets with embedded IAL2 evidence.
* **Context:** **(none; `context` may be omitted or empty for this ticket type)**.
* **Access:** `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://trusted-issuer.org",
  "aud": "https://network.org",
  "exp": 1775789228,
  "jti": "uc1-4b33cc1d-0f6b-44bf-bd33-80f6d7140f3e",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/patient-self-access-v1",
  "presenter_binding": {
    "method": "jkt",
    "jkt": "JuI6ibZHcMPQICaIZ55PbXpnsudQmKt00D0BiEXNrMc"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "A12345"
        }
      ],
      "birthDate": "1989-09-14",
      "name": [
        {
          "family": "Reyes",
          "given": [
            "Elena"
          ]
        }
      ]
    }
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "AllergyIntolerance",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Observation",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "MedicationRequest",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "data_period": {
      "start": "2021-01-01",
      "end": "2026-01-01"
    }
  },
  "iat": 1775785628
}
```

#### Use Case 2: Patient-Delegated Access

**An adult daughter accesses her elderly mother's records. The relationship is verified by a Trusted Issuer, not the Hospital.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `RelatedPerson` with relationship codings expressing both personal relationship and legal authority type.
* **Context:** **(none; same as UC1 — delegation is expressed by the presence and type of `requester`)**
* **Access:** `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://trusted-issuer.org",
  "aud": "https://network.org",
  "exp": 1775789228,
  "jti": "uc2-8c6f4ec2-4fb6-4c42-9530-6bbd11c77e49",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/patient-delegated-access-v1",
  "presenter_binding": {
    "method": "jkt",
    "jkt": "JuI6ibZHcMPQICaIZ55PbXpnsudQmKt00D0BiEXNrMc"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "https://national-mpi.net",
          "value": "pt-555"
        }
      ],
      "birthDate": "1948-06-15",
      "name": [
        {
          "family": "Reyes",
          "given": [
            "Maria"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "RelatedPerson",
    "relationship": [
      {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
            "code": "DAU",
            "display": "daughter"
          }
        ]
      },
      {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
            "code": "HPOWATT",
            "display": "healthcare power of attorney"
          }
        ]
      }
    ],
    "name": [
      {
        "family": "Reyes",
        "given": [
          "Elena"
        ]
      }
    ]
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Immunization",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "MedicationRequest",
        "interactions": [
          "read",
          "search"
        ]
      }
    ]
  },
  "iat": 1775785628
}
```

#### Use Case 3: Public Health Investigation

**A Hospital creates a Case Report. The Public Health Agency (PHA) uses a ticket to query for follow-up data.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `Organization` (public health agency).
* **Context:** `reportable_condition` (coded condition).
* **Access:** `permissions`, optional `data_period`, `data_holder_filter`, `sensitive_data`.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://issuer.state.example.gov",
  "aud": "https://network.org",
  "exp": 1775957430,
  "jti": "uc3-16ff62cf-2d2d-4b30-8c86-6a13d7ab7d16",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/public-health-investigation-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://state.example.gov/trust-framework/public-health",
    "framework_type": "udap",
    "entity_uri": "https://state.example.gov/organizations/epi-unit"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "M445566"
        }
      ],
      "birthDate": "1978-02-21",
      "name": [
        {
          "family": "Carter",
          "given": [
            "Monica"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "urn:ietf:rfc:3986",
        "value": "https://state.example.gov/organizations/epi-unit"
      }
    ],
    "name": "State Epidemiology Unit"
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Observation",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "DiagnosticReport",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "data_period": {
      "start": "2025-12-01",
      "end": "2026-06-01"
    },
    "data_holder_filter": [
      {
        "kind": "jurisdiction",
        "address": {
          "country": "US",
          "state": "TX"
        }
      }
    ],
    "sensitive_data": "include"
  },
  "context": {
    "reportable_condition": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "840539006",
          "display": "Disease caused by severe acute respiratory syndrome coronavirus 2 (disorder)"
        }
      ]
    }
  },
  "iat": 1775953830
}
```

#### Use Case 4: Social Care (CBO) Referral

**A community-based organization needs to access referral-related data. A Food Bank volunteer needs to update a referral status.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `Organization` (social care hub).
* **Context:** `concern` (coded concern), `referral` (ServiceRequest).
* **Access:** `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://issuer.example.org",
  "aud": "https://network.org",
  "exp": 1775957430,
  "jti": "uc4-0d0f7272-2d85-49ef-8c39-d4a8e8d8a7f2",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/social-care-referral-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://smarthealthit.org/trust-frameworks/reference-demo-well-known",
    "framework_type": "well-known",
    "entity_uri": "https://aco.example.org/entities/social-care-hub"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "S778899"
        }
      ],
      "birthDate": "1963-11-03",
      "name": [
        {
          "family": "Nguyen",
          "given": [
            "Linh"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "urn:ietf:rfc:3986",
        "value": "https://aco.example.org/entities/social-care-hub"
      }
    ],
    "name": "Community Social Care Hub"
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "ServiceRequest",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Observation",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "sensitive_data": "exclude"
  },
  "context": {
    "concern": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "733423003",
          "display": "Food insecurity"
        }
      ]
    },
    "referral": {
      "resourceType": "ServiceRequest",
      "identifier": [
        {
          "system": "http://issuer.example.org/referrals",
          "value": "REF-1001"
        }
      ],
      "status": "active",
      "intent": "order"
    }
  },
  "iat": 1775953830
}
```

#### Use Case 5: Payer Claims Adjudication

**A Payer requests clinical documents to support a specific claim.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `Organization` (Payer).
* **Context:** `service` (coded service), `claim` (Claim resource).
* **Access:** `permissions`, optional `data_period`, `data_holder_filter`.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://issuer.example.org",
  "aud": "https://network.org",
  "exp": 1775957430,
  "jti": "uc5-9096d8d2-3627-45ee-8ea2-5e5a0ab51b7b",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/payer-claims-adjudication-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://payer.example.org/trust-framework",
    "framework_type": "udap",
    "entity_uri": "https://payer.example.org/entities/claims-ops"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "C112233"
        }
      ],
      "birthDate": "1954-07-19",
      "name": [
        {
          "family": "Johnson",
          "given": [
            "Amelia"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "urn:ietf:rfc:3986",
        "value": "https://payer.example.org/entities/claims-ops"
      }
    ],
    "name": "Acme Health Plan Claims Operations"
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "Claim",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "ExplanationOfBenefit",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "DocumentReference",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "data_period": {
      "start": "2025-01-01",
      "end": "2025-12-31"
    },
    "data_holder_filter": [
      {
        "kind": "organization",
        "organization": {
          "resourceType": "Organization",
          "identifier": [
            {
              "system": "http://hl7.org/fhir/sid/us-npi",
              "value": "1234567893"
            }
          ],
          "name": "General Hospital"
        }
      }
    ],
    "sensitive_data": "exclude"
  },
  "context": {
    "service": {
      "coding": [
        {
          "system": "http://www.ama-assn.org/go/cpt",
          "code": "99214",
          "display": "Office or other outpatient visit"
        }
      ]
    },
    "claim": {
      "resourceType": "Claim",
      "identifier": [
        {
          "system": "http://payer.example.org/claims",
          "value": "CLM-884422"
        }
      ],
      "status": "active",
      "use": "claim"
    }
  },
  "iat": 1775953830
}
```

#### Use Case 6: Research Study

**A patient consents to a study. The ticket proves consent exists without requiring the researcher to be a "user" at the hospital.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `Organization` (research institute).
* **Context:** `study` (ResearchStudy resource).
* **Access:** `permissions`, optional `data_period`, `sensitive_data`.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://issuer.example.org",
  "aud": "https://network.org",
  "exp": 1775957430,
  "jti": "uc6-b5774e14-a020-46f2-94d3-2bb95b7ac4af",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/research-study-access-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://research.example.org/trust-framework",
    "framework_type": "udap",
    "entity_uri": "https://research.example.org/entities/study-team-204"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "R445500"
        }
      ],
      "birthDate": "1970-05-30",
      "name": [
        {
          "family": "Lopez",
          "given": [
            "Marina"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "Organization",
    "identifier": [
      {
        "system": "urn:ietf:rfc:3986",
        "value": "https://research.example.org/entities/study-team-204"
      }
    ],
    "name": "Study Team 204"
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Observation",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "data_period": {
      "start": "2024-01-01",
      "end": "2026-12-31"
    },
    "sensitive_data": "exclude"
  },
  "context": {
    "study": {
      "resourceType": "ResearchStudy",
      "identifier": [
        {
          "system": "http://research.example.org/studies",
          "value": "STUDY-204"
        }
      ],
      "status": "active",
      "title": "Diabetes Outcomes Registry"
    }
  },
  "iat": 1775953830
}
```

#### Use Case 7: Provider-to-Provider Consult

**A Specialist (Practitioner) requests data from a Referring Provider.**

##### Ticket Schema

* **Subject:** `Patient` (matched by demographics or identifier).
* **Requester:** `PractitionerRole` (specialist role).
* **Context:** `reason` (coded reason), `consult_request` (ServiceRequest).
* **Access:** `permissions` with specific resource types and interactions.

#### Permission Ticket Artifact 

##### Header

```
{
  "alg": "ES256",
  "kid": "nvOGRCsTz2QIQLsbl0ZQ_ux0tfyh5iave-jvNsANWv8"
}
```

##### Payload (Claims)

```
{
  "iss": "https://issuer.example.org",
  "aud": "https://network.org",
  "exp": 1775957430,
  "jti": "uc7-d6927f7f-74c8-4b1b-a7a5-7f4e6d99390a",
  "ticket_type": "https://smarthealthit.org/permission-ticket-type/provider-consult-v1",
  "presenter_binding": {
    "method": "trust_framework_client",
    "trust_framework": "https://smarthealthit.org/trust-frameworks/reference-demo-well-known",
    "framework_type": "well-known",
    "entity_uri": "https://hospital.example.org/entities/cardiology-group"
  },
  "subject": {
    "patient": {
      "resourceType": "Patient",
      "identifier": [
        {
          "system": "http://hospital.example.org/mrn",
          "value": "K667788"
        }
      ],
      "birthDate": "1981-03-08",
      "name": [
        {
          "family": "Thomas",
          "given": [
            "Jared"
          ]
        }
      ]
    }
  },
  "requester": {
    "resourceType": "PractitionerRole",
    "code": [
      {
        "coding": [
          {
            "system": "http://snomed.info/sct",
            "code": "17561000",
            "display": "Cardiologist"
          }
        ]
      }
    ]
  },
  "access": {
    "permissions": [
      {
        "kind": "data",
        "resource_type": "Condition",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "Observation",
        "interactions": [
          "read",
          "search"
        ]
      },
      {
        "kind": "data",
        "resource_type": "DiagnosticReport",
        "interactions": [
          "read",
          "search"
        ]
      }
    ],
    "sensitive_data": "exclude"
  },
  "context": {
    "reason": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "53741008",
          "display": "Coronary arteriosclerosis"
        }
      ]
    },
    "consult_request": {
      "resourceType": "ServiceRequest",
      "identifier": [
        {
          "system": "http://issuer.example.org/consults",
          "value": "CONSULT-7788"
        }
      ],
      "status": "active",
      "intent": "order"
    }
  },
  "iat": 1775953830
}
```

