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


This Implementation Guide (IG) includes Primary Profiles to ensure data minimization (DM), and Fallback Profiles with relaxed constraints that include all allowable data (AD). More detail about the difference between DM and AD profiles is available below.

Profile groups

  • Patient

    For representing the minimal information needed to identify a patient in a SMART Health Card.

  • Vaccination

    For representing a vaccination for an infectious disease such as COVID-19 or influenza.

  • Laboratory results observation

    For representing laboratory test results related to infection with or immunity to an infectious disease.

  • Bundles

    Defines the contents of the fhirBundle element in a SMART Health Card for a given use case.

How to use profiles for implementation

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

The recommended workflow for reading profiles of a given resource in this IG is as follows:

  1. Begin by reading the IG’s home page and this page in their entirety.
  2. Review this page in its entirety.
  3. Use the “Profile Groups” navigation menu, or the list of profile groups above to review the implementation instructions for each profile group in the IG.
    1. If multiple pairs of primary/fallback profiles are available within this Profile Group, note that you should choose the pair with the narrowest applicable scope. For example, if there is a set of profiles for your country, you should use those rather than the generic set.
    2. Review the “Snapshot” tab on the primary profile you plan to use within each profile group. The elements listed here SHOULD/SHALL be included based on MustSupport (S in the “Flags” column) and cardinality (in the “Card.”) column. Elements not listed here SHOULD NOT or SHALL NOT be included. Details on interpreting cardinality and MustSupport for this IG are available below.
      • For more information about the data type for a given element, click the data type link in the “Type” column. This will bring you to the relevant portion of the FHIR specification for that data type.
      • The “Description & Constraints” column has a short description of each element. Some elements may also have a “Binding” listed here, which indicates values SHALL come from the specified list. (This IG uses “Required” for all value set bindings, but other IGs may use more flexible binding strengths.)
  4. For each element included in a given resource, review the detailed definition for the element in this IG. To find this, click the element’s name in the “Snapshot” table of the relevant profile. The detailed definition may have more implementation and conformance information including applicable invariants.
  5. If you wish to validate your resource, start by validating against the primary (DM) profile for a given FHIR resource, and attempt to resolve any errors.

    If an Issuer has a good faith belief that resolving a validation error against a primary (DM) profile would reduce utility for Holders or Verifiers, they MAY instead validate against the less constrained fallback (AD) profile instead.

    Issuers should be aware that adding in extraneous information to FHIR resources may not make it possible for the SMART Health Card to fit in a legible QR code. Issuers should refer to SMART Health Cards Framework for details.

Conformance to profiles

All resources meant to conform with this IG SHOULD conform to the relevant primary (DM) profiles, and SHALL conform to the relevant fallback (AD) profiles.

In some cases, multiple pairs of primary/fallback profiles of the same resource are provided (e.g., “Universal Patient” vs. “US-Only Patient”). Implementers SHALL use the most specific set of profiles for their given use case. For example, a US-based implementer SHALL use the “US-Only Patient” profiles. Likewise, an implementer producing resources representing COVID-19 lab results SHALL use the COVID-19-specific lab results profiles.

Note that in FHIR, a profile is derived from either the base FHIR resource (like Patient) or another profile. In this IG, a Fallback Profile is typically derived from the base FHIR resource, and the corresponding Primary Profile is derived from the Fallback Profile. The Primary Profile can therefore be considered a child of the Fallback Profile. A child profile cannot remove or relax a constraint defined in the parent profile. Instead, child profiles typically impose stricter constraints than the parent profile.

The diagram below shows the relationship of the Primary and Fallback Profiles, namely that the Primary Profile is a subset of the Fallback Profile:

MustSupport interpretation

Elements in FHIR can be labeled as MustSupport, denoted in profiles by this symbol: S.

MustSupport does not mean an element is required. Required elements are those with a minimum cardinality of 1 or greater.

Instead, MustSupport indicates implementers “SHALL provide ‘support’ for the element in some meaningful way”.

In this Implementation Guide, “support in some meaningful way” is defined as follows:

  • Issuers:

    1. Issuers SHALL populate any elements marked as MustSupport if and only if the necessary data are available in their system. See Missing data below for details.

    2. Issuers SHOULD NOT populate any elements that are not marked as MustSupport unless they believe the element contains valuable information for Holders and/or 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. To avoid contradicting cardinality, all required elements (minimum cardinality > 0) are therefore also labeled as MustSupport.

  • Verifiers:

    1. Verifiers SHALL read and meaningfully process elements marked BOTH as MustSupport and Is-Modifier. Note that Is-Modifier elements by definition cannot be safely ignored as they may change the meaning of the resource.

    2. For other elements flagged with MustSupport, Verifiers MAY process at their own discretion.

Required elements

Elements with a minimum cardinality of 1 or greater are considered required.

Missing data

  • If an Issuer does not have data for a MustSupport data element, the data element SHALL be omitted from the resource. Implementers SHALL NOT produce placeholder data when data are not available; instead, omit the element.
  • If an Issuer does not have data for a required data element (minimum cardinality > 0), the Issuer SHALL NOT produce the resource.

Data minimization and privacy

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.

Additionally, FHIR payload within a SMART Health Card SHALL be small enough to allow the entirety of the SMART Health Card to fit within a single Version 22 QR code. This limits the amount of data that SHOULD be included in FHIR resources that appear in SMART Health Card payloads.

To ensure only the minimal amount of data are being included, Issuers SHOULD validate their FHIR resource instances against the primary (DM) profiles listed above. See the Validation section for information on how to validate a resource against a profile.


  • Implementers SHOULD NOT populate or Resource.text elements. Resource.meta SHOULD NOT be populated, except for in the vaccination and laboratory test results profiles.

  • Implementers SHALL use resource:0 syntax for IDs and references.
    • Implementers SHALL populate Bundle.entry.fullUrl elements with short resource-scheme URIs (e.g., {"fullUrl": "resource:0}).
    • Implementers SHALL populate Reference.reference elements with short resource-scheme URIs (e.g., {"patient": {"reference": "resource:0"}}) which SHALL 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.

  • String length should be limited; invariants are used within the IG to produce warnings when strings exceed the expected length for a MustSupport element (except for patient name).

  • Implementers SHOULD use YYYY-MM-DD precision for all dateTime fields EXCEPT for laboratory results (described below). Greater precision will result in a warning when validating a resource.


Bundles meant to populate the fhirBundle element of a SMART Health Card with a type of SHALL conform to one of the Bundles profiled in this IG.

The profiles of Bundle in this IG MAY be used with other types of SMART Health Cards.


NOTE: At the time of publication, several code systems used for identifying vaccines (AIR, ATC, GTIN, ICD-11, GLN, and the UK edition of SNOMED-CT) are not supported by the default terminology server (``) used by the FHIR validator, which may result in validation errors. To successfully validate resources using these code systems, an alternate terminology server that supports these code systems must be used.

Resources may be assessed for conformance using one of the tools listed under “Conformance testing” on this page, or manually with the FHIR Validator (described below).

Note that these tools do not check for MustSupport conformance as this depends on the particulars of the data available to the actor producing the resource. Implementers MUST manually check MustSupport conformance based on the criteria described above.

To validate a specific resource against a profile, the FHIR Validator can be used, where package.tgz is downloaded from the IG:

# Run to get latest validator_cli.jar (~80MB)
curl -L -O

# Run to get latest package from this IG to validate against
curl -L -O

# Run to validate; note you will need to update the paths to (1) validator_cli.jar; (2) package.tgz;
# (3) the resource you wish to validate.
# You will also need to specify the URI of the profile you wish to validate against. This can be found
# under "Defining URL" on any of the profile pages in this IG.
java -jar path/to/validator_cli.jar -version 4.0.1 \
-ig path/to/package.tgz \
-profile \

The command above would validate path/to/immunization.json against the SHCVaccinationDM profile. To validate against a different profile, change shc-vaccination-dm to the identifier of the profile you want to validate against. This can be found at the end of the canonical URL listed at the top of each profile’s page in the IG.

Additional testing and validation tools may be found here.


The SMART Health Cards specification and this IG are suitable for international use.

Additionally, this IG includes specific profiles for the following jurisdictions:

  • United States

Other jurisdictions are welcome to define their own profiles that reflect their local concerns – please contact the local HL7 affiliate or the authors of this specification for assistance.

Jurisdictional profiles will typically add constraints to those defined in the “fallback” profiles defined above. For example, jurisdictional profiles might add constraints limiting the patient identifier to a specific type of national patient/consumer id, or define a specific value set using codes from a local SNOMED-CT edition for vaccines.

Typically jurisdictional profiles will include both “primary” and “fallback” profiles; both SHALL inherit from the generic “fallback” profile or the generic “primary” profile.

  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