SMART Health Cards: Vaccination & Testing Implementation Guide
0.2.0 - ci-build

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



This FHIR Implementation Guide (IG):

  1. Describes the clinical information necessary to create a SMART Health Card identifying vaccination and testing status for infectious diseases such as COVID-19.
  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 constrain 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 Health Card-specific FHIR endpoint like [base]/Patient/:id/$HealthWallet.issueVc. This IG is not applicable to general purpose FHIR endpoints like [base]/Patient/:id/Immunization; these are governed by other IGs like US Core.

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 for verification purposes.

Secondarily, we want to define patterns that support future use cases including:

  • clinical data indicating current or previous COVID-19 infection status (e.g., laboratory testing results evaluating presence of RNA, antigens, or antibodies)
  • clinical data pertaining to other infectious diseases

We therefore avoid constraints that limit use in other diseases unless such constraints are necessary to support COVID-19 use cases.

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.


The primary actors are:

  1. Issuers who produce the FHIR resources described in this IG. These are typically the entities responsible for giving vaccinations, including health systems, pharmacies, and doctors offices.
  2. Verifiers who read and analyze the FHIR resources described in this IG.
  3. Patients 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.

Issuers and Verifiers are considered “implementers” of this IG.

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 VaccineCredentialImmunization 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 FDA-approved or 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.

Conformance verbs

This specification uses the conformance verbs SHALL, SHOULD, and MAY as defined in RFC 2119.

MustSupport interpretation

  • Issuers SHALL populate any elements marked as MustSupport if the necessary data are available in their system.
  • Issuers SHOULD NOT populate any elements that are not marked as MustSupport unless they believe the element contains valuable information for Verifiers. This is due to the payload size constraints of SMART Health Cards; see the Data minimization section below for more details on how to reduce payload size when implementing.
  • Verifiers SHALL be able to “meaningfully process” elements flagged with both MustSupport and the Is-Modifier property. For other elements flagged with MustSupport, Verifiers MAY process at their own discretion.

Note that MustSupport does not indicate an element is required to be present in resource instances. Required elements are those with a minimum cardinality of 1 or greater.


  • VaccineCredentialPatient: Describes a minimal set of patient information to assist Verifiers in determining or verifying identity.

  • VaccineCredentialImmunization: Represents an immunization, includes vaccine information such as the CVX code identifying the vaccine, who administered the vaccine, etc.

  • [VaccineCredentialAntibodyResultValueSet] [experimental]: Represents the results of an antibody test. Included because a positive antibody test could be interpreted as showing immunity to the disease. This profile is considered “experimental” as it does not pertain to the core scope of the IG.

  • [VaccineCredentialVaccineReactionObservation] [experimental]: Represents an adverse reaction to a vaccination. Included because an adverse reaction may be interpreted by some actors as justification for not receiving the full series of a vaccination. This profile is considered “experimental” as it does not pertain to the core scope of the IG.

Additionally, the following profiles from other IGs are used to represent key resources needed to implement this IG:

  • USCoreLocation represents the location (geographic, not body site) where the patient received their vaccination.


The VaccineCredentialBundle collects resources conforming to the profiles listed above. Resources conforming to profiles outside this IG MAY also be included in Bundles conforming to VaccineCredentialBundle.

Each Bundle resource SHALL include resources related to one patient and one target disease. The target disease is identified as follows:

TODO: Add guidance on when specific resources should be included in the bundle.


  1. Scenario 1: A patient receives two doses of the Moderna COVID-19 vaccine. The first dose was administered on January 1, 2021, and the second dose on January 29, 2021.

    Example resources:

  2. Scenario 2: A patient receives two doses of the Pfizer-BioNTech COVID-19 vaccine. The first dose was administered on January 1, 2021, and the second dose on January 29, 2021.

    Example resources:

  3. Miscellaneous examples:

    1. ExampleImmunizationNoCVX: Immunization resource showing how to record a vaccine without a published CVX code.

Implementation notes

Data minimization

A number of constraints apply to all Health Cards as documented in the SMART Health Card specification.

  • Implementers SHOULD NOT populate, Resource.meta, or Resource.text elements.
  • Implementers SHOULD populate Bundle.entry.fullUrl elements with short resource-scheme URIs (e.g., {“fullUrl”: “resource:0}).
  • Implementers SHOULD populate Reference.reference elements with short resource-scheme URIs (e.g., {“patient”: {“reference”: “resource:0”}}) which SHOULD resolve within the bundle.
  • Implementers SHOULD NOT populate CodeableConcept.text or Coding.display when using any value from a value set with a required binding, or using specified values from a value set with an extensible binding.
  • Likewise, implementers SHOULD NOT populate CodeableConcept.text or Coding.display when specifying codes that are fixed in profiles.
  • Use YYYY-MM-DD precision for all dateTime fields. Greater precision will result in a warning when validating a resource.