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 |
JSON representation of the VHLPayload logical model.
{
"resourceType" : "StructureDefinition",
"id" : "VHLPayload",
"text" : {
"status" : "extensions",
"div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: StructureDefinition VHLPayload</b></p><table border=\"0\" cellpadding=\"0\" cellspacing=\"0\" class=\"xhtTableBorder0\"><tr class=\"xhtRowBorder1\"><th scope=\"col\" style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"The logical name of the element\">Name</a></th><th scope=\"col\" style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Information about the use of the element\">Flags</a></th><th scope=\"col\" style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Minimum and Maximum # of times the element can appear in the instance\">Card.</a></th><th scope=\"col\" style=\"; width: 100px\" class=\"hierarchy xhtCellBorder0\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Reference to the type of the element\">Type</a></th><th scope=\"col\" style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Additional information about the element\">Description & Constraints</a><span style=\"float: right\"><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Legend for this format\"><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3goXBCwdPqAP0wAAAldJREFUOMuNk0tIlFEYhp9z/vE2jHkhxXA0zJCMitrUQlq4lnSltEqCFhFG2MJFhIvIFpkEWaTQqjaWZRkp0g26URZkTpbaaOJkDqk10szoODP//7XIMUe0elcfnPd9zsfLOYplGrpRwZaqTtw3K7PtGem7Q6FoidbGgqHVy/HRb669R+56zx7eRV1L31JGxYbBtjKK93cxeqfyQHbehkZbUkK20goELEuIzEd+dHS+qz/Y8PTSif0FnGkbiwcAjHaU1+QWOptFiyCLp/LnKptpqIuXHx6rbR26kJcBX3yLgBfnd7CxwJmflpP2wUg0HIAoUUpZBmKzELGWcN8nAr6Gpu7tLU/CkwAaoKTWRSQyt89Q8w6J+oVQkKnBoblH7V0PPvUOvDYXfopE/SJmALsxnVm6LbkotrUtNowMeIrVrBcBpaMmdS0j9df7abpSuy7HWehwJdt1lhVwi/J58U5beXGAF6c3UXLycw1wdFklArBn87xdh0ZsZtArghBdAA3+OEDVubG4UEzP6x1FOWneHh2VDAHBAt80IbdXDcesNoCvs3E5AFyNSU5nbrDPZpcUEQQTFZiEVx+51fxMhhyJEAgvlriadIJZZksRuwBYMOPBbO3hePVVqgEJhFeUuFLhIPkRP6BQLIBrmMenujm/3g4zc398awIe90Zb5A1vREALqneMcYgP/xVQWlG+Ncu5vgwwlaUNx+3799rfe96u9K0JSDXcOzOTJg4B6IgmXfsygc7/Bvg9g9E58/cDVmGIBOP/zT8Bz1zqWqpbXIsd0O9hajXfL6u4BaOS6SeWAAAAAElFTkSuQmCC\" alt=\"doco\" style=\"background-color: inherit\"/></a></span></th></tr><tr class=\"xhtRowBorder0 xhtRowEven\"><td style=\"background-image: url(tbl_bck1.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_element.gif\" alt=\"\" style=\"background-color: white; background-color: inherit\" title=\"Element\" class=\"hierarchy\"/> <a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload\" title=\"The payload carried by a Verifiable Health Link.\n\nThis model specializes the [SMART Health Link Payload](http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition-ShlPayload.html).\n\nTwo 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]](ITI-YY3.html) for the construction steps.\n\n**Carriers.** This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:\n\n* **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.\n* **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.\n\nThe WHO SMART Trust HCERT specification types claim key 5 against this model; see [WorldHealthOrganization/smart-trust#130](https://github.com/WorldHealthOrganization/smart-trust/pull/130).\">VHLPayload</a><a name=\"VHLPayload\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">0</span><span class=\"xhtPieceDeEmphasized\">..</span><span class=\"xhtPieceDeEmphasized\">*</span></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\">ShlPayload</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\">VHL Payload<br/><br/>Elements defined in Ancestors:<a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"Manifest URL for the SMART Health Link.\">url</a>, <a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"Decryption key for processing files returned in the manifest. 43 characters, consisting of 32 random bytes base64urlencoded.\">key</a>, <a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"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.)\">exp</a>, <a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"String created by concatenating single-character flags in alphabetical order. L: long-term use. P: requires a Passcode to resolve. U: url resolves to a single encrypted file (not to be used in combination with P).\">flag</a>, <a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"String no longer than 80 characters that provides a short description of the data behind the SMART Health Link.\">label</a>, <a href=\"http://hl7.org/fhir/uv/smart-health-cards-and-links/STU1/StructureDefinition-ShlPayload.html\" title=\"SMART Health Links protocol version.\">v</a></td></tr>\r\n<tr class=\"xhtRowBorder0 xhtRowOdd\"><td style=\"background-image: url(tbl_bck10.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_vjoin.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_element.gif\" alt=\"\" style=\"background-color: #F7F7F7; background-color: inherit\" title=\"Element\" class=\"hierarchy\"/> <span style=\"position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0\" class=\"sr-only\">VHLPayload.</span><a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload.url\" title=\"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.\">url</a><a name=\"VHLPayload.url\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">1</span><span class=\"xhtPieceDeEmphasized\">..</span><span class=\"xhtPieceDeEmphasized\">1</span></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/R4/datatypes.html#url\" class=\"xhtPieceDeEmphasized\">url</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">Manifest URL for the SMART Health Link.</span></td></tr>\r\n<tr class=\"xhtRowBorder0 xhtRowEven\"><td style=\"background-image: url(tbl_bck10.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_vjoin.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_element.gif\" alt=\"\" style=\"background-color: white; background-color: inherit\" title=\"Element\" class=\"hierarchy\"/> <span style=\"position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0\" class=\"sr-only\">VHLPayload.</span><a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload.key\" title=\"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.\">key</a><a name=\"VHLPayload.key\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">1</span><span class=\"xhtPieceDeEmphasized\">..</span><span class=\"xhtPieceDeEmphasized\">1</span></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\" class=\"xhtPieceDeEmphasized\">string</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">Decryption key</span></td></tr>\r\n<tr class=\"xhtRowBorder0 xhtRowOdd\"><td style=\"background-image: url(tbl_bck10.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_vjoin.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_element.gif\" alt=\"\" style=\"background-color: #F7F7F7; background-color: inherit\" title=\"Element\" class=\"hierarchy\"/> <span style=\"position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0\" class=\"sr-only\">VHLPayload.</span><a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload.flag\" title=\"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.\">flag</a><a name=\"VHLPayload.flag\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">0</span><span class=\"xhtPieceDeEmphasized\">..</span><span class=\"xhtPieceDeEmphasized\">1</span></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\" class=\"xhtPieceDeEmphasized\">string</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><span class=\"xhtPieceDeEmphasized\">Flag indicating link characteristics.</span></td></tr>\r\n<tr class=\"xhtRowBorder0 xhtRowEven\"><td style=\"background-image: url(tbl_bck01.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_vjoin_end.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_datatype.gif\" alt=\"\" style=\"background-color: white; background-color: inherit\" title=\"Data Type\" class=\"hierarchy\"/> <span style=\"position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0\" class=\"sr-only\">VHLPayload.</span><a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload.extension\" title=\"Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).\">extension</a><a name=\"VHLPayload.extension\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\">0..1</td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/R4/datatypes.html#BackboneElement\">BackboneElement</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\">Implementation-defined extensions</td></tr>\r\n<tr class=\"xhtRowBorder0 xhtRowOdd\"><td style=\"background-image: url(tbl_bck000.png)\" class=\"hierarchy xhtCellBorder0 xhtCellNoWrap\"><img src=\"tbl_spacer.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_blank.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"tbl_vjoin_end.png\" alt=\"\" style=\"background-color: inherit\" class=\"hierarchy\"/><img src=\"icon_primitive.png\" alt=\"\" style=\"background-color: #F7F7F7; background-color: inherit\" title=\"Primitive Data Type\" class=\"hierarchy\"/> <span style=\"position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0\" class=\"sr-only\">VHLPayload.extension.</span><a href=\"StructureDefinition-VHLPayload-definitions.html#VHLPayload.extension.fhirBaseUrl\" title=\"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.\n\nWhere 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.\">fhirBaseUrl</a><a name=\"VHLPayload.extension.fhirBaseUrl\"> </a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\"/><td style=\"\" class=\"hierarchy xhtCellBorder0\">0..1</td><td style=\"\" class=\"hierarchy xhtCellBorder0\"><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\">string</a></td><td style=\"\" class=\"hierarchy xhtCellBorder0\">FHIR base URL of the VHL Sharer</td></tr>\r\n<tr><td colspan=\"5\" class=\"hierarchy\"><br/><a href=\"https://build.fhir.org/ig/FHIR/ig-guidance/readingIgs.html#table-views\" title=\"Legend for this format\"><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3goXBCwdPqAP0wAAAldJREFUOMuNk0tIlFEYhp9z/vE2jHkhxXA0zJCMitrUQlq4lnSltEqCFhFG2MJFhIvIFpkEWaTQqjaWZRkp0g26URZkTpbaaOJkDqk10szoODP//7XIMUe0elcfnPd9zsfLOYplGrpRwZaqTtw3K7PtGem7Q6FoidbGgqHVy/HRb669R+56zx7eRV1L31JGxYbBtjKK93cxeqfyQHbehkZbUkK20goELEuIzEd+dHS+qz/Y8PTSif0FnGkbiwcAjHaU1+QWOptFiyCLp/LnKptpqIuXHx6rbR26kJcBX3yLgBfnd7CxwJmflpP2wUg0HIAoUUpZBmKzELGWcN8nAr6Gpu7tLU/CkwAaoKTWRSQyt89Q8w6J+oVQkKnBoblH7V0PPvUOvDYXfopE/SJmALsxnVm6LbkotrUtNowMeIrVrBcBpaMmdS0j9df7abpSuy7HWehwJdt1lhVwi/J58U5beXGAF6c3UXLycw1wdFklArBn87xdh0ZsZtArghBdAA3+OEDVubG4UEzP6x1FOWneHh2VDAHBAt80IbdXDcesNoCvs3E5AFyNSU5nbrDPZpcUEQQTFZiEVx+51fxMhhyJEAgvlriadIJZZksRuwBYMOPBbO3hePVVqgEJhFeUuFLhIPkRP6BQLIBrmMenujm/3g4zc398awIe90Zb5A1vREALqneMcYgP/xVQWlG+Ncu5vgwwlaUNx+3799rfe96u9K0JSDXcOzOTJg4B6IgmXfsygc7/Bvg9g9E58/cDVmGIBOP/zT8Bz1zqWqpbXIsd0O9hajXfL6u4BaOS6SeWAAAAAElFTkSuQmCC\" alt=\"doco\" style=\"background-color: inherit\"/> Documentation for this format</a></td></tr></table></div>"
},
"url" : "https://profiles.ihe.net/ITI/VHL/StructureDefinition/VHLPayload",
"version" : "1.0.0-comment",
"name" : "VHLPayload",
"title" : "VHL Payload",
"status" : "active",
"date" : "2026-11-13T03:15:18+00:00",
"publisher" : "IHE IT Infrastructure Technical Committee",
"contact" : [
{
"telecom" : [
{
"system" : "url",
"value" : "https://www.ihe.net/ihe_domains/it_infrastructure/"
}
]
},
{
"telecom" : [
{
"system" : "email",
"value" : "iti@ihe.net"
}
]
},
{
"name" : "IHE IT Infrastructure Technical Committee",
"telecom" : [
{
"system" : "email",
"value" : "iti@ihe.net"
}
]
}
],
"description" : "The payload carried by a Verifiable Health Link.\n\nThis model specializes the [SMART Health Link Payload](http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition-ShlPayload.html).\n\nTwo 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]](ITI-YY3.html) for the construction steps.\n\n**Carriers.** This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:\n\n* **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.\n* **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.\n\nThe WHO SMART Trust HCERT specification types claim key 5 against this model; see [WorldHealthOrganization/smart-trust#130](https://github.com/WorldHealthOrganization/smart-trust/pull/130).",
"jurisdiction" : [
{
"coding" : [
{
"system" : "http://unstats.un.org/unsd/methods/m49/m49.htm",
"code" : "001"
}
]
}
],
"fhirVersion" : "4.0.1",
"kind" : "logical",
"abstract" : false,
"type" : "https://profiles.ihe.net/ITI/VHL/StructureDefinition/VHLPayload",
"baseDefinition" : "http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition/ShlPayload",
"derivation" : "specialization",
"snapshot" : {
"extension" : [
{
"url" : "http://hl7.org/fhir/tools/StructureDefinition/snapshot-base-version",
"valueString" : "1.0.0"
}
],
"element" : [
{
"id" : "VHLPayload",
"path" : "VHLPayload",
"short" : "VHL Payload",
"definition" : "The payload carried by a Verifiable Health Link.\n\nThis model specializes the [SMART Health Link Payload](http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition-ShlPayload.html).\n\nTwo 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]](ITI-YY3.html) for the construction steps.\n\n**Carriers.** This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:\n\n* **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.\n* **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.\n\nThe WHO SMART Trust HCERT specification types claim key 5 against this model; see [WorldHealthOrganization/smart-trust#130](https://github.com/WorldHealthOrganization/smart-trust/pull/130).",
"min" : 0,
"max" : "*",
"base" : {
"path" : "Base",
"min" : 0,
"max" : "*"
},
"isModifier" : false
},
{
"id" : "VHLPayload.url",
"path" : "VHLPayload.url",
"short" : "Manifest URL for the SMART Health Link.",
"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.",
"min" : 1,
"max" : "1",
"base" : {
"path" : "ShlPayload.url",
"min" : 1,
"max" : "1"
},
"type" : [
{
"code" : "url"
}
],
"example" : [
{
"label" : "URL\"",
"valueUrl" : "https://ehr.example.org/qr/Y9xwkUdtmN9wwoJoN3ffJIhX2UGvCL1JnlPVNL3kDWM/m"
}
]
},
{
"id" : "VHLPayload.key",
"path" : "VHLPayload.key",
"short" : "Decryption 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.",
"min" : 1,
"max" : "1",
"base" : {
"path" : "ShlPayload.key",
"min" : 1,
"max" : "1"
},
"type" : [
{
"code" : "string"
}
],
"example" : [
{
"label" : "key",
"valueString" : "rxTgYlOaKJPFtcEd0qcceN8wEU4p94SqAwIWQe6uX7Q"
}
]
},
{
"id" : "VHLPayload.exp",
"path" : "VHLPayload.exp",
"short" : "Expiration time",
"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.)",
"min" : 0,
"max" : "1",
"base" : {
"path" : "ShlPayload.exp",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "decimal"
}
],
"example" : [
{
"label" : "representing January 1, 2026 12:00:00 AM",
"valueString" : "1767225600000"
}
]
},
{
"id" : "VHLPayload.flag",
"path" : "VHLPayload.flag",
"short" : "Flag indicating link characteristics.",
"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.",
"min" : 0,
"max" : "1",
"base" : {
"path" : "ShlPayload.flag",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "string"
}
],
"example" : [
{
"label" : "representing 'Long-term use and requires passcode'",
"valueString" : "LP"
}
]
},
{
"id" : "VHLPayload.label",
"path" : "VHLPayload.label",
"short" : "short description of the data behind the SMART Health Link.",
"definition" : "String no longer than 80 characters that provides a short description of the data behind the SMART Health Link.",
"min" : 0,
"max" : "1",
"base" : {
"path" : "ShlPayload.flag",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "string"
}
],
"example" : [
{
"label" : "label",
"valueString" : "Back-to-school immunizations for Oliver Brown"
}
]
},
{
"id" : "VHLPayload.v",
"path" : "VHLPayload.v",
"short" : "Protocol version",
"definition" : "SMART Health Links protocol version.",
"min" : 0,
"max" : "1",
"base" : {
"path" : "ShlPayload.v",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "integer"
}
],
"example" : [
{
"label" : "meaning default version",
"valueInteger" : 1
}
]
},
{
"id" : "VHLPayload.extension",
"path" : "VHLPayload.extension",
"short" : "Implementation-defined extensions",
"definition" : "Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).",
"min" : 0,
"max" : "1",
"base" : {
"path" : "VHLPayload.extension",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "BackboneElement"
}
],
"constraint" : [
{
"key" : "ele-1",
"severity" : "error",
"human" : "All FHIR elements must have a @value or children",
"expression" : "hasValue() or (children().count() > id.count())",
"xpath" : "@value|f:*|h:div",
"source" : "http://hl7.org/fhir/StructureDefinition/Element"
}
]
},
{
"id" : "VHLPayload.extension.id",
"path" : "VHLPayload.extension.id",
"representation" : [
"xmlAttr"
],
"short" : "Unique id for inter-element referencing",
"definition" : "Unique id for the element within a resource (for internal references). This may be any string value that does not contain spaces.",
"min" : 0,
"max" : "1",
"base" : {
"path" : "Element.id",
"min" : 0,
"max" : "1"
},
"type" : [
{
"extension" : [
{
"url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fhir-type",
"valueUrl" : "string"
}
],
"code" : "http://hl7.org/fhirpath/System.String"
}
],
"isModifier" : false,
"isSummary" : false,
"mapping" : [
{
"identity" : "rim",
"map" : "n/a"
}
]
},
{
"id" : "VHLPayload.extension.extension",
"path" : "VHLPayload.extension.extension",
"slicing" : {
"discriminator" : [
{
"type" : "value",
"path" : "url"
}
],
"description" : "Extensions are always sliced by (at least) url",
"rules" : "open"
},
"short" : "Additional content defined by implementations",
"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.",
"comment" : "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.",
"alias" : [
"extensions",
"user content"
],
"min" : 0,
"max" : "*",
"base" : {
"path" : "Element.extension",
"min" : 0,
"max" : "*"
},
"type" : [
{
"code" : "Extension"
}
],
"constraint" : [
{
"key" : "ele-1",
"severity" : "error",
"human" : "All FHIR elements must have a @value or children",
"expression" : "hasValue() or (children().count() > id.count())",
"xpath" : "@value|f:*|h:div",
"source" : "http://hl7.org/fhir/StructureDefinition/Element"
},
{
"key" : "ext-1",
"severity" : "error",
"human" : "Must have either extensions or value[x], not both",
"expression" : "extension.exists() != value.exists()",
"xpath" : "exists(f:extension)!=exists(f:*[starts-with(local-name(.), \"value\")])",
"source" : "http://hl7.org/fhir/StructureDefinition/Extension"
}
],
"isModifier" : false,
"isSummary" : false,
"mapping" : [
{
"identity" : "rim",
"map" : "n/a"
}
]
},
{
"id" : "VHLPayload.extension.modifierExtension",
"path" : "VHLPayload.extension.modifierExtension",
"short" : "Extensions that cannot be ignored even if unrecognized",
"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.\n\nModifier extensions SHALL NOT change the meaning of any elements on Resource or DomainResource (including cannot change the meaning of modifierExtension itself).",
"comment" : "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.",
"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](http://hl7.org/fhir/R4/extensibility.html#modifierExtension).",
"alias" : [
"extensions",
"user content",
"modifiers"
],
"min" : 0,
"max" : "*",
"base" : {
"path" : "BackboneElement.modifierExtension",
"min" : 0,
"max" : "*"
},
"type" : [
{
"code" : "Extension"
}
],
"constraint" : [
{
"key" : "ele-1",
"severity" : "error",
"human" : "All FHIR elements must have a @value or children",
"expression" : "hasValue() or (children().count() > id.count())",
"xpath" : "@value|f:*|h:div",
"source" : "http://hl7.org/fhir/StructureDefinition/Element"
},
{
"key" : "ext-1",
"severity" : "error",
"human" : "Must have either extensions or value[x], not both",
"expression" : "extension.exists() != value.exists()",
"xpath" : "exists(f:extension)!=exists(f:*[starts-with(local-name(.), \"value\")])",
"source" : "http://hl7.org/fhir/StructureDefinition/Extension"
}
],
"isModifier" : true,
"isModifierReason" : "Modifier extensions are expected to modify the meaning or interpretation of the element that contains them",
"isSummary" : true,
"mapping" : [
{
"identity" : "rim",
"map" : "N/A"
}
]
},
{
"id" : "VHLPayload.extension.fhirBaseUrl",
"path" : "VHLPayload.extension.fhirBaseUrl",
"short" : "FHIR base URL of the VHL Sharer",
"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.\n\nWhere 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.",
"min" : 0,
"max" : "1",
"base" : {
"path" : "VHLPayload.extension.fhirBaseUrl",
"min" : 0,
"max" : "1"
},
"type" : [
{
"code" : "string"
}
]
}
]
},
"differential" : {
"element" : [
{
"id" : "VHLPayload",
"path" : "VHLPayload",
"short" : "VHL Payload",
"definition" : "The payload carried by a Verifiable Health Link.\n\nThis model specializes the [SMART Health Link Payload](http://hl7.org/fhir/uv/smart-health-cards-and-links/StructureDefinition-ShlPayload.html).\n\nTwo 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]](ITI-YY3.html) for the construction steps.\n\n**Carriers.** This model defines the payload's fields, not its serialization, and the two carriers in this profile encode it differently:\n\n* **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.\n* **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.\n\nThe WHO SMART Trust HCERT specification types claim key 5 against this model; see [WorldHealthOrganization/smart-trust#130](https://github.com/WorldHealthOrganization/smart-trust/pull/130)."
},
{
"id" : "VHLPayload.url",
"path" : "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."
},
{
"id" : "VHLPayload.key",
"path" : "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."
},
{
"id" : "VHLPayload.flag",
"path" : "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."
},
{
"id" : "VHLPayload.extension",
"path" : "VHLPayload.extension",
"short" : "Implementation-defined extensions",
"definition" : "Object carrying implementation-defined extensions. Required when the VHL Sharer claims the Sign Manifest Request Option (OAuth with SSRAA).",
"min" : 0,
"max" : "1",
"type" : [
{
"code" : "BackboneElement"
}
]
},
{
"id" : "VHLPayload.extension.fhirBaseUrl",
"path" : "VHLPayload.extension.fhirBaseUrl",
"short" : "FHIR base URL of the VHL Sharer",
"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.\n\nWhere 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.",
"min" : 0,
"max" : "1",
"type" : [
{
"code" : "string"
}
]
}
]
}
}