SMART Health Cards: Vaccination & Testing Implementation Guide
0.6.2 - STU 1 (Ballot Version) International flag

SMART Health Cards: Vaccination & Testing Implementation Guide, published by HL7 International - Public Health Work Group. This is not an authorized publication; it is the continuous build for version 0.6.2). This version is based on the current content of and changes regularly. See the Directory of published versions


Official URL: Version: 0.6.2
Draft as of 2022-09-24 Computable Name: SMARTHealthCardsVaccinationAndTestingIG


This FHIR Implementation Guide (IG):

  1. Describes the clinical information necessary to create a SMART Health Card (SHC) identifying vaccination and laboratory testing status for infectious diseases such as COVID-19. In particular, it describes the content of the subject of a SMART Health Card in which the card types include, and/or, and optionally
  2. Describes a minimal set of patient information (name and contact information) that is also included in the SMART Health Card.

The goal of this IG is to define the conformance criteria of FHIR resources for use specifically in SMART Health Cards. This applies to the contents of both digital and paper Health Cards, including Health Cards produced via a SMART Health Card-specific FHIR endpoint like [base]/Patient/:id/$health-cards-issue. This IG is not applicable to general-purpose FHIR endpoints like [base]/Patient/:id/Immunization, nor is it meant to describe the canonical representation of clinical data in electronic health record systems; these are governed by other IGs like US Core.

Note that this IG is not directly related to the SMART App Launch Framework. The name comes from SMART Health IT, who also developed the SMART Health Card framework that this IG supports. (“SMART” is an acronym for Substitutable Medical Apps, Reusable Technology.) SMART App Launch and SMART Health Cards are designed to work well together (the former being one of multiple methods for issuing the latter), but they don’t have a hard dependency with each other.


The primary actors are:

  1. Issuers who produce the FHIR resources described in this IG. These may be the entities responsible for giving vaccinations or reporting laboratory results, including health systems, pharmacies, clinical labs, and doctors offices.
  2. Holders who receive a SMART Health Card from an Issuer (which contains the FHIR resources described in this IG), and may display it to a Verifier.
  3. Verifiers who read and analyze the FHIR resources described in this IG.

Issuers and Verifiers are considered “implementers” of this IG. Additionally, “wallet applications” used by Holders to store digital versions of their SHC are also considered implementers.

Privacy by design

Special attention is payed in this IG to protecting the privacy of Holders.

The design of the SMART Health Card specification results in the following characteristics of issued SMART Health Cards:

  1. The contents cannot be changed (without re-issuing the entire SMART Health Card).
  2. The entirety of the data within the SMART Health Card is transmitted from the Holder to the Verifier whenever a SMART Health Card is presented.

Therefore, information that is not strictly necessary for a legitimate Verifier use case SHALL NOT be included in SMART Health Cards.

For more information, please see the data minimization and privacy section on the Profiles page.

This diagram shows the typical SHC workflow among these actors:

IssuersVerifiersWalletProviders &Health systemsRetail pharmaciesGovernments &State registriesLabsTravel industrySchools & employersBorder controlEvents & entertainmentHold printed SHCSmartphone appSMART Health Card(Printed or digital)Holder

Use cases

Our primary focus is on the use case of representing the minimal set of clinical data necessary to represent COVID-19 vaccination status and laboratory testing for verification purposes in a SMART Health Card. We support other infectious diseases as a secondary use case. To meet these use cases, we provide profiles of a FHIR Bundle that describes the contents of the fhirBundle element in a SMART Health Card. We also provide profiles of the resources contained within this Bundle.

The SMART Health Cards Framework constrains the size of the FHIR payload embedded within a SMART Health Card to allow the entirety of the SMART Health Card to fit within a single Version 22 QR code. This IG is designed to support creating resources that fit within these size constraints. (While it is possible to generate a denser QR code, the SMART Health Cards Framework developers found that denser QR codes could be difficult to scan.) SMART Health Card payloads are compressed, with the amount of compression varying based on the content of the payload (in general, the more repeated content in the bundle, the higher the compression ratio). This means that it’s not possible to calculate the precise number of uncompressed bytes available for the embedded FHIR Bundle.

To support implementers’ efforts to minimize payload size, this IG provides two different sets of profiles:

  1. Primary Profiles focused on data minimization (DM). These profiles use cardinality constraints to prohibit elements beyond the minimal set needed to meet our use cases.
  2. Fallback Profiles, with relaxed constraints that include all allowable data (AD).

More information can be found on the Profiles page.

In practice, we have found that bundles of resources conforming to the Primary Profiles in this IG do fit within the payload constraints.

Due to size constraints and to preserve patient privacy, information that is not strictly necessary for Verifiers in the context of this IG’s use cases SHALL NOT be included in SMART Health Cards.

If private or sensitive information are included in a SMART Health Card, it will be exposed to the Verifier every time the SMART Health Card is presented. Additionally, information cannot be removed without invalidating the entire SMART Health Card.1 It is therefore critical for Issuers to avoid including any information that could represent a safety or privacy risk to a patient in a SMART Health Card.

Use case 1: immunization records

Scenario 1: A patient receives two doses of the Moderna COVID-19 vaccine, and a third dose of the 2022 bivalent booster. The first dose was administered on January 1, 2021, the second dose on January 29, 2021, and the booster on September 5, 2022. Here is an example of a FHIR Bundle representing this scenario, which contains the following resources:

  1. An instance of a Patient resource conforming to SHCPatientUnitedStatesDM
  2. An instance of an Immunization resource conforming to SHCVaccinationDM to represent the first dose
  3. An instance of an Immunization resource conforming to SHCVaccinationDM to represent the second dose
  4. An instance of an Immunization resource conforming to SHCVaccinationDM to represent the booster (third dose)

Scenario 2: A patient receives two doses of the Jynneos (modified vaccinia Ankara vaccine) vaccine for monkeypox/smallpox. The first dose was administered on August 1, 2022, and the second dose on August 29, 2022. Here is an example of a FHIR Bundle representing this scenario, which contains the following resources:

  1. An instance of a Patient resource conforming to SHCPatientUnitedStatesDM
  2. An instance of an Immunization resource conforming to SHCVaccinationDM to represent the first dose
  3. An instance of an Immunization resource conforming to SHCVaccinationDM to represent the second dose

The example Bundle resources for both scenarios above conform to SHCVaccinationBundleDM.

Use case 2: laboratory test results

Scenario 3: A patient is tested for SARS-CoV-2 (COVID19) antigen via rapid immunoassay on February 17, 2021 with result detectable. Here is an example of a FHIR Bundle representing this scenario, which contains the following resources:

  1. An instance of a Patient resource conforming to SHCPatientUnitedStatesDM
  2. An instance of an Observation resource conforming to SHCCovid19LaboratoryResultObservationDM to represent lab test results

The example Bundle resources for this scenario conforms to SHCInfectiousDiseaseLaboratoryBundleDM.


For the list of profiles defined in this IG please see the Profiles page.

Approach to constraints

The IG is currently focused on coordinating implementers’ representations of relevant clinical data, rather than evaluating risk or applying decision rules based on these clinical data. For example, this IG does not include information about which vaccine products are considered effective, or which dosing protocols are appropriate for a given product. The rationale for focusing on “conveying a clinical history” rather than “evaluating risk or making decisions” is:

  1. Risk evaluation algorithms are likely to evolve faster than IG constraints can be updated.

    For example, constraining the SHCVaccinationDM profile to require specific vaccineCode values (e.g., only CVX#207 and CVX#208 for the current Moderna and Pfizer-BioNTech vaccines) could pose a problem if a new vaccine receives emergency authorization: recipients of the new vaccination would have non-conforming Immunization resources due to the constraints on vaccineCode until the IG could be updated and published.

  2. Risk evaluation algorithms may be actor- or context-dependent.

    For example, some parties may only consider United States Food and Drug Administration (FDA)-approved or Emergency Use Authorization (EUA) vaccines to be acceptable, while others may accept vaccines approved in other countries.

    Embedding stringent validation criteria in our FHIR profiles may make it impossible for implementers with less stringent criteria to use this IG.

  3. More constrained profiles for risk evaluation can be created based on the profiles in this IG, but it’s not possible to remove constraints in a child profile.

  4. Cardinality constraints are applied to specific data elements in Allowable Data profiles when their inclusion (1) does not support our use case and could harm patients; or (2) is contrary to our key design principles. For example, Patient.identifier is not allowed in resources conforming to SHCPatientUnitedStatesAD as this may include a Medical Record Number (MRN) or Social Security Number (SSN) in the United States, which would introduce a significant privacy risk for patients.

Approach to terminology bindings

Value set bindings for MustSupport elements are required, meaning that resources MUST use a code specified in the bound value set. This is to ensure implementers know which code systems can be expected to appear in a given element.

In general, the value sets used in these required bindings are as broad as possible. For example, in the VaccineCVX value set, all codes from the CVX code system are included (as opposed to defining a value set with just COVID-related CVX codes, for example).

In cases where disease-specific value sets exist, this IG may provide profiles with bindings to these restricted value sets (e.g., SHCCovid19LaboratoryResultObservationDM) to help implementers identify the preferred subset of codes for that disease. However, in these cases, this IG will also provide generic equivalents to these profiles with broad value sets (e.g., SHCInfectiousDiseaseLaboratoryResultObservationDM). Implementers MAY fall back to the generic version of such profiles if the code they need is not part of the disease-specific value sets.

Note that when a value set is specified as “Include all codes defined in …”, the definition does not constrain the value set content to a specific version of the code system. As the code system content is updated in new code system versions, the updated content will be available in the value set expansion (and via $validate-code). Also note that value set expansions in the published version of this IG may be out of date; please check with the canonical source of the code system for the most up-to-date set of codes that belong to a value set.

Identity assurance

The SHCVaccinationDM and SHCCovid19LaboratoryResultObservationDM/SHCCovid19LaboratoryResultObservationDM profiles include a mechanism for indicating level of identity assurance of the patient. This uses the IdentityAssuranceLevel value set in this format:

"meta": {
  "security": [{"system": "", "code": "IAL1.2"}]

Issuers SHALL populate these elements if identity assurance information is available.

Compatibility with IIS

Resources representing a vaccination and associated data should be able to be directly populated with data from IIS implementations using the HL7 v2.5.1 Implementation Guide for Immunization Messaging, Release 1.5.

Author contact information

This FHIR Implementation Guide was initially developed by VCI, and is currently an HL7 project sponsored by the Public Health Work Group.

If you have questions or comments about this IG, please reach out to us via one of these channels:

  1. The smart/health-cards stream on (requires free account)
  2. The vaccination HL7 listserv (sign up here)
  3. Email


  • Reece Adamson (The MITRE Corporation2)
  • Cary Anderson (Apple Inc.)
  • Shaumik Ashraf (The MITRE Corporation2)
  • Ricky Bloomfield (Apple Inc.)
  • Paul Denning (The MITRE Corporation2)
  • Neelima Karipineni (The MITRE Corporation2)
  • Josh Mandel (SMART Health IT and Microsoft)
  • Max Masnick (The MITRE Corporation2)
  • Pascal Pfiffner (Apple Inc.)
  • JP Pollak (The Commons Project and Cornell)
  • Isaac Vetter (Epic)

To be included in the credits, please open a pull request on GitHub adding yourself to this file. Anyone on the GitHub contributors list or who has otherwise contributed to this IG may be included.

This IG includes the “Description” and “Electric Bolt” icons from Material Icons, which are licensed under Apache 2.0. The “Quick Jump” functionality is provided by the ninja-keys library, which is MIT licensed.

  1. SMART Health Cards (SHCs) are designed to be “tamper-evident,” meaning that any changes to the contents of a SHC after issuing will be apparent to a Verifier. For example, if an Issuer included a patient’s phone number in their SHC, and the patient subsequently removed their phone number from the SHC, a Verifier would be able to tell that the contents of the SHC had changed since issuing (i.e., that tampering had occurred) – but not specifically what part of the SHC had changed. Typically, Verifiers will reject any SHC that has evidence of tampering. For technical details on how tampering can be detected, please refer to the SMART Health Card specification

  2. MITRE: Approved for Public Release. Distribution Unlimited. Case Number 21-0225.  2 3 4 5