Verifiable Health Links
1.0.0-comment - ballot
Verifiable Health Links, published by IHE IT Infrastructure Technical Committee. This guide is not an authorized publication; it is the continuous build for version 1.0.0-comment 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
| Official URL: https://profiles.ihe.net/ITI/VHL/OperationDefinition/generate-vhl | Version: 1.0.0-comment | |||
| Active as of 2026-11-20 | Computable Name: GenerateVHL | |||
This operation generates a Verifiable Health Link (VHL) for transmission or display. The VHL MAY be returned as a QR code (HCERT/CWT) or, when the VHL Sharer supports the VC Envelope Option, as a signed W3C Verifiable Credential.
Input Parameters:
Output Generation:
| Use | Name | Scope | Cardinality | Type | Binding | Documentation |
| IN | sourceIdentifier | 1..1 | string (token) | A FHIR Identifier (business identifier such as MRN, passport number, or national ID) that the VHL Sharer uses to locate the Patient record and that Patient's documents. Serialized as a FHIR token search parameter ( | ||
| IN | exp | 0..1 | positiveInt | Optional. Number representing expiration time in Epoch seconds. | ||
| IN | flag | 0..1 | string (string) | Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required) | ||
| IN | label | 0..1 | string (string) | Optional. String no longer than 80 characters that provides a short description of the data behind the VHL. | ||
| IN | passcode | 0..1 | string (string) | 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. | ||
| IN | purposeOfUse | 0..* | string (token) | Optional. Purpose(s) of use the VHL Holder is authorizing for this share (e.g., TREAT, HPAYMT, HRESCH). The VHL Sharer SHALL persist these value(s) against the generated folder ID. When the VHL Sharer is grouped with an IHE PCF Consent Recorder or Consent Registry, these values SHALL populate Consent.provision.purpose on any Consent created for or bound to this folder. At ITI-YY5 the VHL Sharer MAY use the recorded purpose to enforce consistency with the VHL Receiver's declared purpose claim (e.g., the OAuth access token's purposeOfUse claim, the SSRAA hl7-b2b extension, or credentialSubject.purposeOfUse in the self-issued Verifiable Credential). | ||
| IN | format | 0..1 | code | Optional. Requested carrier for the returned VHL. Allowed values: 'qrcode' (default - HCERT/CWT QR code) or 'vc' (W3C Verifiable Credential). The 'vc' value requires the VHL Sharer to support the VC Enveloped VHL Option; if unsupported, the VHL Sharer SHALL return an OperationOutcome error. If omitted, the VHL Sharer SHALL default to 'qrcode'. | ||
| OUT | qrcode | 0..1 | Binary | A Binary resource containing the QR code image (PNG or SVG format) that encodes the VHL as an HCERT/CWT structure. Populated when format='qrcode' (default). VHL Payload Construction:
For the complete HCERT specification, see HCERT Specification. For the HCERT logical model, see HCert. For SHL payload format details (the schema the VHL payload conforms to), see Construct a SMART Health Link Payload. | ||
| OUT | verifiableCredential | 0..1 | Binary | A Binary resource (contentType application/vc) containing a W3C Verifiable Credential that carries the VHL. Populated only when format='vc' and the VHL Sharer supports the VC Enveloped VHL. The VC is a JSON-LD document per the W3C Verifiable Credentials Data Model v2 with an embedded proof of type DataIntegrityProof per W3C Verifiable Credential Data Integrity 1.0. The VC is issued and signed by the VHL Sharer using its trust-network key (same DSC/key material used for HCERT/CWT signing), so the VHL Receiver validates the VC proof against the trust list via the existing trust framework (no new trust mechanism introduced). The credentialSubject.id carries the VHL as the vhlink: URI. The two carriers convey the same payload fields in different encodings: this one as a base64url-encoded vhlink: URI, the HCERT carrier as a CBOR map at claim key 5. Exactly one of qrcode or verifiableCredential SHALL be populated. For details see ITI-YY3 VC Enveloped VHL Carrier (Option — format=vc). |