Verifiable Health Link
0.0.2-current - ci-build

Verifiable Health Link, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 0.0.2-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/IHE/ITI.VHL/ and changes regularly. See the Directory of published versions

## : Generate VHL - XML Representation

Active as of 2026-03-12

Raw xml | Download

    <OperationDefinition xmlns="http://hl7.org/fhir">
      <id value="OperationDefinition-generate-vhl"/>
      <text>
        <status value="generated"/>
        <div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition OperationDefinition-generate-vhl</b></p><a name="OperationDefinition-generate-vhl"> </a><a name="hcOperationDefinition-generate-vhl"> </a><h3>Parameters</h3><table class="grid"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>sourceIdentifier</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#Identifier">Identifier</a></td><td/><td><div><p>An identifier for the patient. Required if 'bundle' is not provided.</p>
    </div></td></tr><tr><td>IN</td><td>exp</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#integer">integer</a></td><td/><td><div><p>Optional. Number representing expiration time in Epoch seconds, as a hint to help the SHL Receiving Application determine if this QR is stale.</p>
    </div></td></tr><tr><td>IN</td><td>flag</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a></td><td/><td><div><p>Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)</p>
    </div></td></tr><tr><td>IN</td><td>label</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a></td><td/><td><div><p>Optional. String no longer than 80 characters that provides a short description of the data behind the SHLink.</p>
    </div></td></tr><tr><td>IN</td><td>passcode</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/R4/datatypes.html#string">string</a></td><td/><td><div><p>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.</p>
    </div></td></tr><tr><td>OUT</td><td>qrcode</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/R4/binary.html">Binary</a></td><td/><td><div><p>A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.</p>
    <p>VHL Payload Construction:</p>
    <ol>
    <li>Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier</li>
    <li>Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters) - this is the 'key' parameter</li>
    <li>Construct the manifest URL as a query on the base List resource:
    <ul>
    <li>If VHL Sharer supports Include DocumentReference Option:
    [base]/List?_id=[folder-id]&amp;code=folder&amp;status=current&amp;patient.identifier=[patient-id]&amp;_include=List:item</li>
    <li>If VHL Sharer does NOT support Include DocumentReference Option:
    [base]/List?_id=[folder-id]&amp;code=folder&amp;status=current&amp;patient.identifier=[patient-id]</li>
    </ul>
    </li>
    <li>Create the SHL payload as a JSON object with:
    <ul>
    <li>url: the manifest URL from step 3</li>
    <li>key: the base64url-encoded encryption key from step 2 (43 characters)</li>
    <li>exp: (optional) expiration time in Epoch seconds</li>
    <li>flag: (optional) flags string (e.g., 'P' for passcode, 'L' for long-term, 'U' for direct file access)</li>
    <li>label: (optional) description string (max 80 characters)</li>
    <li>v: version number (defaults to 1)</li>
    <li>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)</li>
    </ul>
    </li>
    <li>Minify the JSON payload, Base64url-encode it, and prefix with vhlink:/</li>
    </ol>
    <p>QR Code Generation (HCERT/CWT Encoding):
    The 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.</p>
    <p>For complete HCERT specification, see: https://smart.who.int/trust/hcert_spec.html</p>
    <p>For HCERT logical model, see: https://smart.who.int/trust/StructureDefinition-HCert.html</p>
    <p>For SHL payload details, see: https://build.fhir.org/ig/HL7/smart-health-cards-and-links/links-specification.html#construct-a-smart-health-link-payload</p>
    </div></td></tr></table></div>
      </text>
      <url value="http://example.org/fhir/OperationDefinition/generate-vhl"/>
      <version value="0.0.2-current"/>
      <name value="GenerateVHL"/>
      <title value="Generate VHL"/>
      <status value="active"/>
      <kind value="operation"/>
      <date value="2026-03-12T12:40:14+00:00"/>
      <publisher value="IHE IT Infrastructure Technical Committee"/>
      <contact>
        <telecom>
          <system value="url"/>
          <value value="https://www.ihe.net/ihe_domains/it_infrastructure/"/>
        </telecom>
      </contact>
      <contact>
        <telecom>
          <system value="email"/>
          <value value="iti@ihe.net"/>
        </telecom>
      </contact>
      <contact>
        <name value="IHE IT Infrastructure Technical Committee"/>
        <telecom>
          <system value="email"/>
          <value value="iti@ihe.net"/>
        </telecom>
      </contact>
      <description
                   value="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."/>
      <jurisdiction>
        <coding>
          <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/>
          <code value="001"/>
        </coding>
      </jurisdiction>
      <code value="generate-vhl"/>
      <system value="false"/>
      <type value="true"/>
      <instance value="false"/>
      <parameter>
        <name value="sourceIdentifier"/>
        <use value="in"/>
        <min value="1"/>
        <max value="1"/>
        <documentation
                       value="An identifier for the patient. Required if 'bundle' is not provided."/>
        <type value="Identifier"/>
      </parameter>
      <parameter>
        <name value="exp"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation
                       value="Optional. Number representing expiration time in Epoch seconds, as a hint to help the SHL Receiving Application determine if this QR is stale."/>
        <type value="integer"/>
      </parameter>
      <parameter>
        <name value="flag"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation
                       value="Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)"/>
        <type value="string"/>
      </parameter>
      <parameter>
        <name value="label"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation
                       value="Optional. String no longer than 80 characters that provides a short description of the data behind the SHLink."/>
        <type value="string"/>
      </parameter>
      <parameter>
        <name value="passcode"/>
        <use value="in"/>
        <min value="0"/>
        <max value="1"/>
        <documentation
                       value="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 value="string"/>
      </parameter>
      <parameter>
        <name value="qrcode"/>
        <use value="out"/>
        <min value="1"/>
        <max value="1"/>
        <documentation
                       value="A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure.

    VHL Payload Construction:
    1. Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier
    2. Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters) - this is the 'key' parameter
    3. Construct the manifest URL as a query on the base List resource:
       - If VHL Sharer supports Include DocumentReference Option:
         [base]/List?_id=[folder-id]&amp;code=folder&amp;status=current&amp;patient.identifier=[patient-id]&amp;_include=List:item
       - If VHL Sharer does NOT support Include DocumentReference Option:
         [base]/List?_id=[folder-id]&amp;code=folder&amp;status=current&amp;patient.identifier=[patient-id]
    4. Create the SHL payload as a JSON object with:
       - url: the manifest URL from step 3
       - key: the base64url-encoded encryption key from step 2 (43 characters)
       - exp: (optional) expiration time in Epoch seconds
       - flag: (optional) flags string (e.g., 'P' for passcode, 'L' for long-term, 'U' for direct file access)
       - label: (optional) description string (max 80 characters)
       - v: version number (defaults to 1)
       - 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)
    5. Minify the JSON payload, Base64url-encode it, and prefix with vhlink:/

    QR Code Generation (HCERT/CWT Encoding):
    The 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.

    For complete HCERT specification, see: https://smart.who.int/trust/hcert_spec.html

    For HCERT logical model, see: https://smart.who.int/trust/StructureDefinition-HCert.html

    For 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 value="Binary"/>
      </parameter>
    </OperationDefinition>