Verifiable Health Links
1.0.0-comment - ballot International flag

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

Logical Model: VHL Payload

Official URL: https://profiles.ihe.net/ITI/VHL/StructureDefinition/VHLPayload Version: 1.0.0-comment
Active as of 2026-11-13 Computable Name: VHLPayload

The payload carried by a Verifiable Health Link.

This model specializes the SMART Health Link Payload.

Two things distinguish this model from its parent: the U flag is not used, and extension.fhirBaseUrl is defined for the Sign Manifest Request Option (OAuth with SSRAA). See Generate VHL [ITI-YY3] for the construction steps.

Carriers. This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:

  • HCERT/CWT QR code — the payload is a CBOR map with text keys at HCERT claim key 5, with values in their CBOR-native types, so exp and v are integers. The map is the payload; it is neither base64url-encoded nor prefixed. Claim key 5 identifies the content as a VHL, so no type discriminator is carried in the payload. A vhlink:/ string at claim key 5, as earlier drafts specified, SHOULD still be accepted on decode.
  • VC Enveloped VHL Option — the payload is minified, base64url-encoded and prefixed with vhlink:/ to form the credentialSubject.id URI, because a JSON-LD id cannot be a map.

The WHO SMART Trust HCERT specification types claim key 5 against this model; see WorldHealthOrganization/smart-trust#130.

Usages:

  • This Logical Model is not used by any profiles in this Specification

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
Example URL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
VHLPayload.key 1..1 string Decryption key
Example key: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
VHLPayload.exp 0..1 decimal Expiration time
Example representing January 1, 2026 12:00:00 AM: 1767225600000
VHLPayload.flag 0..1 string Flag indicating link characteristics.
Example representing 'Long-term use and requires passcode': LP
VHLPayload.label 0..1 string short description of the data behind the SMART Health Link.
Example label: Back-to-school immunizations for Oliver Brown
VHLPayload.v 0..1 integer Protocol version
Example meaning default version: 1
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.@id 0..1 string Unique id for inter-element referencing
VHLPayload.extension.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
VHLPayload.extension.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored even if unrecognized
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression

This structure is derived from ShlPayload

NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
VHLPayload.key 1..1 string Decryption key
VHLPayload.flag 0..1 string Flag indicating link characteristics.
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format
NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
Example URL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
VHLPayload.key 1..1 string Decryption key
Example key: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
VHLPayload.exp 0..1 decimal Expiration time
Example representing January 1, 2026 12:00:00 AM: 1767225600000
VHLPayload.flag 0..1 string Flag indicating link characteristics.
Example representing 'Long-term use and requires passcode': LP
VHLPayload.label 0..1 string short description of the data behind the SMART Health Link.
Example label: Back-to-school immunizations for Oliver Brown
VHLPayload.v 0..1 integer Protocol version
Example meaning default version: 1
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.@id 0..1 string Unique id for inter-element referencing
VHLPayload.extension.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
VHLPayload.extension.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored even if unrecognized
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression

This structure is derived from ShlPayload

Summary

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
Example URL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
VHLPayload.key 1..1 string Decryption key
Example key: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
VHLPayload.exp 0..1 decimal Expiration time
Example representing January 1, 2026 12:00:00 AM: 1767225600000
VHLPayload.flag 0..1 string Flag indicating link characteristics.
Example representing 'Long-term use and requires passcode': LP
VHLPayload.label 0..1 string short description of the data behind the SMART Health Link.
Example label: Back-to-school immunizations for Oliver Brown
VHLPayload.v 0..1 integer Protocol version
Example meaning default version: 1
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.@id 0..1 string Unique id for inter-element referencing
VHLPayload.extension.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
VHLPayload.extension.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored even if unrecognized
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression

Differential View

This structure is derived from ShlPayload

NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
VHLPayload.key 1..1 string Decryption key
VHLPayload.flag 0..1 string Flag indicating link characteristics.
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format

Snapshot View

NameFlagsCard.TypeDescription & Constraints    Filter: doco
VHLPayload 0..* ShlPayload VHL Payload

Elements defined in Ancestors:url, key, exp, flag, label, v
VHLPayload.url 1..1 url Manifest URL for the SMART Health Link.
Example URL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
VHLPayload.key 1..1 string Decryption key
Example key: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
VHLPayload.exp 0..1 decimal Expiration time
Example representing January 1, 2026 12:00:00 AM: 1767225600000
VHLPayload.flag 0..1 string Flag indicating link characteristics.
Example representing 'Long-term use and requires passcode': LP
VHLPayload.label 0..1 string short description of the data behind the SMART Health Link.
Example label: Back-to-school immunizations for Oliver Brown
VHLPayload.v 0..1 integer Protocol version
Example meaning default version: 1
VHLPayload.extension 0..1 BackboneElement Implementation-defined extensions
VHLPayload.extension.@id 0..1 string Unique id for inter-element referencing
VHLPayload.extension.extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
VHLPayload.extension.modifierExtension This element is a modifier element. This element is included in summaries. 0..* Extension Extensions that cannot be ignored even if unrecognized
VHLPayload.extension.fhirBaseUrl 0..1 string FHIR base URL of the VHL Sharer

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression

This structure is derived from ShlPayload

Summary

 

Other representations of profile: CSV, Excel