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 (system|code, e.g., urn:oid:2.16.840.1.113883.2.4.6.3|PASSPORT123).

Optional. Number representing expiration time in Epoch seconds.

Optional. String created by concatenating single-character flags in alphabetical order. L (long-term use), P (Passcode required)

Optional. String no longer than 80 characters that provides a short description of the data behind the VHL.

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.

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 Creator or Consent Recipient, 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 an equivalent claim carried in a Verifiable Credential).

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'.

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:

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 VHL payload (using the SHL payload format) 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 format details (the schema the VHL payload conforms to), see: https://hl7.org/fhir/uv/smart-health-cards-and-links/links-specification.html#construct-a-smart-health-link-payload

A Binary resource (contentType application/vc+ld+json) 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 (cryptosuite ecdsa-2019) 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 carries the VHL payload (conforming to the SHL payload format) with the same fields that are otherwise embedded at HCERT claim key 5 (url, key, flag, label, exp, v, extension). Exactly one of qrcode or verifiableCredential SHALL be populated.

For details see ITI-YY3 VC Enveloped VHL Carrier (Option — format=vc).