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: VHLPayload - Detailed Descriptions

Active as of 2026-11-13

Definitions for the VHLPayload logical model.

See the documentation on how to interpret the contents of this table

0. VHLPayload
Definition

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.

ShortVHL Payload
Control0..*
Is Modifierfalse
Logical ModelInstances of this logical model are not marked to be the target of a Reference
2. VHLPayload.url
Definition

The manifest URL for this VHL, expressed as a FHIR search URL on the List resource. This profile requires the URL to carry _id, code, status and patient.identifier; _include=List:item is added only where the VHL Sharer supports the Include DocumentReference Option. The folder ID conveyed in _id is the primary authorization mechanism for the VHL.

ShortManifest URL for the SMART Health Link.
Control1..1
Typeurl
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
ExampleURL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
4. VHLPayload.key
Definition

Decryption key for the files returned in the manifest: 32 random bytes, base64url-encoded, giving 43 characters. The VHL Receiver uses this as the symmetric key for JWE dir / A256GCM decryption of document binaries retrieved via ITI-68.

ShortDecryption key
Control1..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplekey: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
6. VHLPayload.exp
Definition

Number representing expiration time in Epoch seconds, as a hint to help the SMART Health Links Receiving Application determine if this QR is stale. (Note: epoch times should be parsed into 64-bit numeric types.)

ShortExpiration time
Control0..1
Typedecimal
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplerepresenting January 1, 2026 12:00:00 AM: 1767225600000
8. VHLPayload.flag
Definition

String formed by concatenating single-character flags in alphabetical order. This profile uses L (long-term use: the folder is expected to remain available and may change over time) and P (a passcode is required when retrieving the manifest), so a VHL that is both carries LP. This profile does not use the SHL U flag and a VHL Sharer SHALL NOT set it: a VHL always references a folder whose contents are reached through Retrieve Manifest [ITI-YY5], which is where the Receiver is authenticated against the trust network and any passcode and consent filtering are applied.

ShortFlag indicating link characteristics.
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplerepresenting 'Long-term use and requires passcode': LP
10. VHLPayload.label
Definition

String no longer than 80 characters that provides a short description of the data behind the SMART Health Link.

Shortshort description of the data behind the SMART Health Link.
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplelabel: Back-to-school immunizations for Oliver Brown
12. VHLPayload.v
Definition

SMART Health Links protocol version.

ShortProtocol version
Control0..1
Typeinteger
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplemeaning default version: 1
14. VHLPayload.extension
Definition

Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).

ShortImplementation-defined extensions
Control0..1
TypeBackboneElement
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
16. VHLPayload.extension.id
Definition

Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

ShortUnique id for inter-element referencing
Control0..1
Typestring
Is Modifierfalse
XML FormatIn the XML format, this property is represented as an attribute.
Summaryfalse
18. VHLPayload.extension.extension
Definition

May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.

ShortAdditional content defined by implementations
Comments

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

Control0..*
TypeExtension
Is Modifierfalse
Summaryfalse
Alternate Namesextensions, user content
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
ext-1: Must have either extensions or value[x], not both (extension.exists() != value.exists())
SlicingThis element introduces a set of slices on VHLPayload.extension.extension. The slices are Unordered and Open, and can be differentiated using the following discriminators:
  • value @ url
20. VHLPayload.extension.modifierExtension
Definition

May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions.

Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).

ShortExtensions that cannot be ignored even if unrecognized
Comments

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

Control0..*
TypeExtension
Is Modifiertrue because Modifier extensions are expected to modify the meaning or interpretation of the element that contains them
Summarytrue
Requirements

Modifier extensions allow for extensions that cannot be safely ignored to be clearly distinguished from the vast majority of extensions which can be safely ignored. This promotes interoperability by eliminating the need for implementers to prohibit the presence of extensions. For further information, see the definition of modifier extensions.

Alternate Namesextensions, user content, modifiers
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
ext-1: Must have either extensions or value[x], not both (extension.exists() != value.exists())
22. VHLPayload.extension.fhirBaseUrl
Definition

The FHIR base URL of the VHL Sharer, for example https://vhl-sharer.example.org. It lets the VHL Receiver perform UDAP Discovery and Dynamic Client Registration with the VHL Sharer before making an authenticated manifest request through ITI-YY5.

Where the VHL Sharer does not claim that option this element SHALL NOT be present, so that VHL Receivers are not led into attempting UDAP Discovery unnecessarily.

ShortFHIR base URL of the VHL Sharer
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension

See the documentation on how to interpret the contents of this table

0. VHLPayload
Definition

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.

ShortVHL Payload
Logical ModelInstances of this logical model are not marked to be the target of a Reference
2. VHLPayload.url
Definition

The manifest URL for this VHL, expressed as a FHIR search URL on the List resource. This profile requires the URL to carry _id, code, status and patient.identifier; _include=List:item is added only where the VHL Sharer supports the Include DocumentReference Option. The folder ID conveyed in _id is the primary authorization mechanism for the VHL.

4. VHLPayload.key
Definition

Decryption key for the files returned in the manifest: 32 random bytes, base64url-encoded, giving 43 characters. The VHL Receiver uses this as the symmetric key for JWE dir / A256GCM decryption of document binaries retrieved via ITI-68.

6. VHLPayload.flag
Definition

String formed by concatenating single-character flags in alphabetical order. This profile uses L (long-term use: the folder is expected to remain available and may change over time) and P (a passcode is required when retrieving the manifest), so a VHL that is both carries LP. This profile does not use the SHL U flag and a VHL Sharer SHALL NOT set it: a VHL always references a folder whose contents are reached through Retrieve Manifest [ITI-YY5], which is where the Receiver is authenticated against the trust network and any passcode and consent filtering are applied.

8. VHLPayload.extension
Definition

Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).

ShortImplementation-defined extensions
Control0..1
TypeBackboneElement
10. VHLPayload.extension.fhirBaseUrl
Definition

The FHIR base URL of the VHL Sharer, for example https://vhl-sharer.example.org. It lets the VHL Receiver perform UDAP Discovery and Dynamic Client Registration with the VHL Sharer before making an authenticated manifest request through ITI-YY5.

Where the VHL Sharer does not claim that option this element SHALL NOT be present, so that VHL Receivers are not led into attempting UDAP Discovery unnecessarily.

ShortFHIR base URL of the VHL Sharer
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension

See the documentation on how to interpret the contents of this table

0. VHLPayload
Definition

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.

ShortVHL Payload
Control0..*
Is Modifierfalse
Logical ModelInstances of this logical model are not marked to be the target of a Reference
2. VHLPayload.url
Definition

The manifest URL for this VHL, expressed as a FHIR search URL on the List resource. This profile requires the URL to carry _id, code, status and patient.identifier; _include=List:item is added only where the VHL Sharer supports the Include DocumentReference Option. The folder ID conveyed in _id is the primary authorization mechanism for the VHL.

ShortManifest URL for the SMART Health Link.
Control1..1
Typeurl
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
ExampleURL": https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m
4. VHLPayload.key
Definition

Decryption key for the files returned in the manifest: 32 random bytes, base64url-encoded, giving 43 characters. The VHL Receiver uses this as the symmetric key for JWE dir / A256GCM decryption of document binaries retrieved via ITI-68.

ShortDecryption key
Control1..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplekey: rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q
6. VHLPayload.exp
Definition

Number representing expiration time in Epoch seconds, as a hint to help the SMART Health Links Receiving Application determine if this QR is stale. (Note: epoch times should be parsed into 64-bit numeric types.)

ShortExpiration time
Control0..1
Typedecimal
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplerepresenting January 1, 2026 12:00:00 AM: 1767225600000
8. VHLPayload.flag
Definition

String formed by concatenating single-character flags in alphabetical order. This profile uses L (long-term use: the folder is expected to remain available and may change over time) and P (a passcode is required when retrieving the manifest), so a VHL that is both carries LP. This profile does not use the SHL U flag and a VHL Sharer SHALL NOT set it: a VHL always references a folder whose contents are reached through Retrieve Manifest [ITI-YY5], which is where the Receiver is authenticated against the trust network and any passcode and consent filtering are applied.

ShortFlag indicating link characteristics.
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplerepresenting 'Long-term use and requires passcode': LP
10. VHLPayload.label
Definition

String no longer than 80 characters that provides a short description of the data behind the SMART Health Link.

Shortshort description of the data behind the SMART Health Link.
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplelabel: Back-to-school immunizations for Oliver Brown
12. VHLPayload.v
Definition

SMART Health Links protocol version.

ShortProtocol version
Control0..1
Typeinteger
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension
Examplemeaning default version: 1
14. VHLPayload.extension
Definition

Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).

ShortImplementation-defined extensions
Control0..1
TypeBackboneElement
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
16. VHLPayload.extension.id
Definition

Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.

ShortUnique id for inter-element referencing
Control0..1
Typestring
Is Modifierfalse
XML FormatIn the XML format, this property is represented as an attribute.
Summaryfalse
18. VHLPayload.extension.extension
Definition

May be used to represent additional information that is not part of the basic definition of the element. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension.

ShortAdditional content defined by implementations
Comments

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

Control0..*
TypeExtension
Is Modifierfalse
Summaryfalse
Alternate Namesextensions, user content
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
ext-1: Must have either extensions or value[x], not both (extension.exists() != value.exists())
SlicingThis element introduces a set of slices on VHLPayload.extension.extension. The slices are Unordered and Open, and can be differentiated using the following discriminators:
  • value @ url
20. VHLPayload.extension.modifierExtension
Definition

May be used to represent additional information that is not part of the basic definition of the element and that modifies the understanding of the element in which it is contained and/or the understanding of the containing element's descendants. Usually modifier elements provide negation or qualification. To make the use of extensions safe and manageable, there is a strict set of governance applied to the definition and use of extensions. Though any implementer can define an extension, there is a set of requirements that SHALL be met as part of the definition of the extension. Applications processing a resource are required to check for modifier extensions.

Modifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).

ShortExtensions that cannot be ignored even if unrecognized
Comments

There can be no stigma associated with the use of extensions by any application, project, or standard - regardless of the institution or jurisdiction that uses or defines the extensions. The use of extensions is what allows the FHIR specification to retain a core level of simplicity for everyone.

Control0..*
TypeExtension
Is Modifiertrue because Modifier extensions are expected to modify the meaning or interpretation of the element that contains them
Summarytrue
Requirements

Modifier extensions allow for extensions that cannot be safely ignored to be clearly distinguished from the vast majority of extensions which can be safely ignored. This promotes interoperability by eliminating the need for implementers to prohibit the presence of extensions. For further information, see the definition of modifier extensions.

Alternate Namesextensions, user content, modifiers
Invariantsele-1: All FHIR elements must have a @value or children (hasValue() or (children().count() > id.count()))
ext-1: Must have either extensions or value[x], not both (extension.exists() != value.exists())
22. VHLPayload.extension.fhirBaseUrl
Definition

The FHIR base URL of the VHL Sharer, for example https://vhl-sharer.example.org. It lets the VHL Receiver perform UDAP Discovery and Dynamic Client Registration with the VHL Sharer before making an authenticated manifest request through ITI-YY5.

Where the VHL Sharer does not claim that option this element SHALL NOT be present, so that VHL Receivers are not led into attempting UDAP Discovery unnecessarily.

ShortFHIR base URL of the VHL Sharer
Control0..1
Typestring
Primitive ValueThis primitive element may be present, or absent, or replaced by an extension