Verifiable Health Link
0.0.2-current - ci-build
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
| Active as of 2026-03-13 |
<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]&code=folder&status=current&patient.identifier=[patient-id]&_include=List:item</li>
<li>If VHL Sharer does NOT support Include DocumentReference Option:
[base]/List?_id=[folder-id]&code=folder&status=current&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-13T13:59:49+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]&code=folder&status=current&patient.identifier=[patient-id]&_include=List:item
- If VHL Sharer does NOT support Include DocumentReference Option:
[base]/List?_id=[folder-id]&code=folder&status=current&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>
IG © 2024+ IHE IT Infrastructure Technical Committee. Package ihe.iti.vhl#0.0.2-current based on FHIR 4.0.1. Generated 2026-03-13
Links: Table of Contents |
QA Report
| New Issue | Issues
Version History |
|
Propose a change