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 |
{
"resourceType" : "OperationDefinition",
"id" : "OperationDefinition-generate-vhl",
"text" : {
"status" : "generated",
"div" : "<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>\n</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>\n</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>\n</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>\n</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>\n</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>\n<p>VHL Payload Construction:</p>\n<ol>\n<li>Generate a unique folder ID with 256-bit entropy to serve as the List resource identifier</li>\n<li>Generate a 32-byte (256-bit) random encryption key, base64url-encode it (resulting in 43 characters) - this is the 'key' parameter</li>\n<li>Construct the manifest URL as a query on the base List resource:\n<ul>\n<li>If VHL Sharer supports Include DocumentReference Option:\n[base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id]&_include=List:item</li>\n<li>If VHL Sharer does NOT support Include DocumentReference Option:\n[base]/List?_id=[folder-id]&code=folder&status=current&patient.identifier=[patient-id]</li>\n</ul>\n</li>\n<li>Create the SHL payload as a JSON object with:\n<ul>\n<li>url: the manifest URL from step 3</li>\n<li>key: the base64url-encoded encryption key from step 2 (43 characters)</li>\n<li>exp: (optional) expiration time in Epoch seconds</li>\n<li>flag: (optional) flags string (e.g., 'P' for passcode, 'L' for long-term, 'U' for direct file access)</li>\n<li>label: (optional) description string (max 80 characters)</li>\n<li>v: version number (defaults to 1)</li>\n<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>\n</ul>\n</li>\n<li>Minify the JSON payload, Base64url-encode it, and prefix with vhlink:/</li>\n</ol>\n<p>QR 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.</p>\n<p>For complete HCERT specification, see: https://smart.who.int/trust/hcert_spec.html</p>\n<p>For HCERT logical model, see: https://smart.who.int/trust/StructureDefinition-HCert.html</p>\n<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>\n</div></td></tr></table></div>"
},
"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-13T13:59:49+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"
}
]
}
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