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
| 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 Carriers. This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:
The WHO SMART Trust HCERT specification types claim key 5 against this model; see WorldHealthOrganization/smart-trust#130. |
| Short | VHL Payload |
| Control | 0..* |
| Is Modifier | false |
| Logical Model | Instances 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 |
| Short | Manifest URL for the SMART Health Link. |
| Control | 1..1 |
| Type | url |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | URL": 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 |
| Short | Decryption key |
| Control | 1..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | key: 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.) |
| Short | Expiration time |
| Control | 0..1 |
| Type | decimal |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | representing 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 |
| Short | Flag indicating link characteristics. |
| Control | 0..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | representing '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. |
| Short | short description of the data behind the SMART Health Link. |
| Control | 0..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | label: Back-to-school immunizations for Oliver Brown |
| 12. VHLPayload.v | |
| Definition | SMART Health Links protocol version. |
| Short | Protocol version |
| Control | 0..1 |
| Type | integer |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | meaning 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). |
| Short | Implementation-defined extensions |
| Control | 0..1 |
| Type | BackboneElement |
| Invariants | ele-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. |
| Short | Unique id for inter-element referencing |
| Control | 0..1 |
| Type | string |
| Is Modifier | false |
| XML Format | In the XML format, this property is represented as an attribute. |
| Summary | false |
| 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. |
| Short | Additional 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. |
| Control | 0..* |
| Type | Extension |
| Is Modifier | false |
| Summary | false |
| Alternate Names | extensions, user content |
| Invariants | ele-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()) |
| Slicing | This element introduces a set of slices on VHLPayload.extension.extension. The slices are Unordered and Open, and can be differentiated using the following discriminators:
|
| 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). |
| Short | Extensions 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. |
| Control | 0..* |
| Type | Extension |
| Is Modifier | true because Modifier extensions are expected to modify the meaning or interpretation of the element that contains them |
| Summary | true |
| 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 Names | extensions, user content, modifiers |
| Invariants | ele-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 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. |
| Short | FHIR base URL of the VHL Sharer |
| Control | 0..1 |
| Type | string |
| Primitive Value | This 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 Carriers. This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:
The WHO SMART Trust HCERT specification types claim key 5 against this model; see WorldHealthOrganization/smart-trust#130. |
| Short | VHL Payload |
| Logical Model | Instances 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 |
| 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 |
| 6. VHLPayload.flag | |
| Definition | String formed by concatenating single-character flags in alphabetical order. This profile uses |
| 8. VHLPayload.extension | |
| Definition | Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA). |
| Short | Implementation-defined extensions |
| Control | 0..1 |
| Type | BackboneElement |
| 10. VHLPayload.extension.fhirBaseUrl | |
| Definition | The FHIR base URL of the VHL Sharer, for example 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. |
| Short | FHIR base URL of the VHL Sharer |
| Control | 0..1 |
| Type | string |
| Primitive Value | This 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 Carriers. This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:
The WHO SMART Trust HCERT specification types claim key 5 against this model; see WorldHealthOrganization/smart-trust#130. |
| Short | VHL Payload |
| Control | 0..* |
| Is Modifier | false |
| Logical Model | Instances 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 |
| Short | Manifest URL for the SMART Health Link. |
| Control | 1..1 |
| Type | url |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | URL": 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 |
| Short | Decryption key |
| Control | 1..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | key: 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.) |
| Short | Expiration time |
| Control | 0..1 |
| Type | decimal |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | representing 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 |
| Short | Flag indicating link characteristics. |
| Control | 0..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | representing '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. |
| Short | short description of the data behind the SMART Health Link. |
| Control | 0..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | label: Back-to-school immunizations for Oliver Brown |
| 12. VHLPayload.v | |
| Definition | SMART Health Links protocol version. |
| Short | Protocol version |
| Control | 0..1 |
| Type | integer |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |
| Example | meaning 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). |
| Short | Implementation-defined extensions |
| Control | 0..1 |
| Type | BackboneElement |
| Invariants | ele-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. |
| Short | Unique id for inter-element referencing |
| Control | 0..1 |
| Type | string |
| Is Modifier | false |
| XML Format | In the XML format, this property is represented as an attribute. |
| Summary | false |
| 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. |
| Short | Additional 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. |
| Control | 0..* |
| Type | Extension |
| Is Modifier | false |
| Summary | false |
| Alternate Names | extensions, user content |
| Invariants | ele-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()) |
| Slicing | This element introduces a set of slices on VHLPayload.extension.extension. The slices are Unordered and Open, and can be differentiated using the following discriminators:
|
| 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). |
| Short | Extensions 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. |
| Control | 0..* |
| Type | Extension |
| Is Modifier | true because Modifier extensions are expected to modify the meaning or interpretation of the element that contains them |
| Summary | true |
| 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 Names | extensions, user content, modifiers |
| Invariants | ele-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 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. |
| Short | FHIR base URL of the VHL Sharer |
| Control | 0..1 |
| Type | string |
| Primitive Value | This primitive element may be present, or absent, or replaced by an extension |