# Generate VHL - Verifiable Health Link v0.0.2-current

* [**Table of Contents**](toc.md)
* [**Artifacts Summary**](artifacts.md)
* **Generate VHL**

## OperationDefinition: Generate VHL 

| | |
| :--- | :--- |
| *Official URL*:http://example.org/fhir/OperationDefinition/generate-vhl | *Version*:0.0.2-current |
| Active as of 2026-03-12 | *Computable Name*:GenerateVHL |

 
This operation generates a QR code containing a Verifiable Health Link (VHL) for transmission or display. 
Input Parameters: 
* sourceIdentifier: Patient identifier (required)
* exp: Expiration time in Epoch seconds (optional)
* flag: Single-character flags in alphabetical order - L (long-term use), P (Passcode required), U (direct file access) (optional)
* label: Short description up to 80 characters (optional)
* passcode: User-supplied passcode for passcode-protected VHLs (optional)
 
Output Generation: 
* Returns a Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.
* The QR code embeds the full SHL payload including the manifest URL and decryption key for secure access to health documents.
 



## Resource Content

```json
{
  "resourceType" : "OperationDefinition",
  "id" : "OperationDefinition-generate-vhl",
  "url" : "http://example.org/fhir/OperationDefinition/generate-vhl",
  "version" : "0.0.2-current",
  "name" : "GenerateVHL",
  "title" : "Generate VHL",
  "status" : "active",
  "kind" : "operation",
  "date" : "2026-03-12T12:40:14+00:00",
  "publisher" : "IHE IT Infrastructure Technical Committee",
  "contact" : [{
    "telecom" : [{
      "system" : "url",
      "value" : "https://www.ihe.net/ihe_domains/it_infrastructure/"
    }]
  },
  {
    "telecom" : [{
      "system" : "email",
      "value" : "iti@ihe.net"
    }]
  },
  {
    "name" : "IHE IT Infrastructure Technical Committee",
    "telecom" : [{
      "system" : "email",
      "value" : "iti@ihe.net"
    }]
  }],
  "description" : "This operation generates a QR code containing a Verifiable Health Link (VHL) for transmission or display.\n\nInput Parameters:\n- sourceIdentifier: Patient identifier (required)\n- exp: Expiration time in Epoch seconds (optional)\n- flag: Single-character flags in alphabetical order - L (long-term use), P (Passcode required), U (direct file access) (optional)\n- label: Short description up to 80 characters (optional)\n- passcode: User-supplied passcode for passcode-protected VHLs (optional)\n\nOutput Generation:\n- Returns a Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.\n- The QR code embeds the full SHL payload including the manifest URL and decryption key for secure access to health documents.",
  "jurisdiction" : [{
    "coding" : [{
      "system" : "http://unstats.un.org/unsd/methods/m49/m49.htm",
      "code" : "001"
    }]
  }],
  "code" : "generate-vhl",
  "system" : false,
  "type" : true,
  "instance" : false,
  "parameter" : [{
    "name" : "sourceIdentifier",
    "use" : "in",
    "min" : 1,
    "max" : "1",
    "documentation" : "An identifier for the patient. Required if 'bundle' is not provided.",
    "type" : "Identifier"
  },
  {
    "name" : "exp",
    "use" : "in",
    "min" : 0,
    "max" : "1",
    "documentation" : "Optional. Number representing expiration time in Epoch seconds, as a hint to help the SHL Receiving Application determine if this QR is stale.",
    "type" : "integer"
  },
  {
    "name" : "flag",
    "use" : "in",
    "min" : 0,
    "max" : "1",
    "documentation" : "Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)",
    "type" : "string"
  },
  {
    "name" : "label",
    "use" : "in",
    "min" : 0,
    "max" : "1",
    "documentation" : "Optional. String no longer than 80 characters that provides a short description of the data behind the SHLink.",
    "type" : "string"
  },
  {
    "name" : "passcode",
    "use" : "in",
    "min" : 0,
    "max" : "1",
    "documentation" : "Optional. User-supplied passcode for passcode-protected VHLs. If provided, the VHL Sharer SHALL securely hash and store this passcode for validation during manifest retrieval (ITI-YY5). The 'P' flag SHALL be included in the flag parameter when a passcode is set.",
    "type" : "string"
  },
  {
    "name" : "qrcode",
    "use" : "out",
    "min" : 1,
    "max" : "1",
    "documentation" : "A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.\n\nVHL Payload Construction:\n1. Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier\n2. Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters) - this is the 'key' parameter\n3. Construct the manifest URL as a query on the base List resource:\n   - If VHL Sharer supports Include DocumentReference Option:\n     [base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id]&_include=List:item\n   - If VHL Sharer does NOT support Include DocumentReference Option:\n     [base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id]\n4. Create the SHL payload as a JSON object with:\n   - url: the manifest URL from step 3\n   - key: the base64url-encoded encryption key from step 2 (43 characters)\n   - exp: (optional) expiration time in Epoch seconds\n   - flag: (optional) flags string (e.g., 'P' for passcode, 'L' for long-term, 'U' for direct file access)\n   - label: (optional) description string (max 80 characters)\n   - v: version number (defaults to 1)\n   - extension: (conditional) object containing implementation-defined extensions. Required when the VHL Sharer supports the OAuth with SSRAA Option, in which case it SHALL include fhirBaseUrl (the FHIR base URL of the VHL Sharer, e.g., https://vhl-sharer.example.org)\n5. Minify the JSON payload, Base64url-encode it, and prefix with vhlink:/\n\nQR Code Generation (HCERT/CWT Encoding):\nThe VHL Sharer SHALL encode the VHL payload within an HCERT structure as per the [WHO SMART TRUST specification] (https://smart.who.int/trust/). The HCERT claim key SHALL be 5 for VHL. The QR code is then generated per the HCERT Specification.\n\nFor complete HCERT specification, see: https://smart.who.int/trust/hcert_spec.html\n\nFor HCERT logical model, see: https://smart.who.int/trust/StructureDefinition-HCert.html\n\nFor SHL payload details, see: https://build.fhir.org/ig/HL7/smart-health-cards-and-links/links-specification.html#construct-a-smart-health-link-payload",
    "type" : "Binary"
  }]
}

```
