SMART Health Cards: Vaccination & Testing Implementation Guide
1.0.0 - STU1

SMART Health Cards: Vaccination &amp; Testing Implementation Guide, published by HL7 International / Public Health. This guide is not an authorized publication; it is the continuous build for version 1.0.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-shc-vaccination-ig/ and changes regularly. See the Directory of published versions

## Profiles

Page standards status: Informative

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 implementers SHALL choose the pair with the narrowest applicable scope. For example, if there is a set of profiles for your country, you would 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 most 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 for a given record. 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 instance. 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 instance.

### 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.

Additionally:

- Implementers SHOULD NOT populate `Resource.id` or `Resource.text` elements. `Resource.meta` SHOULD NOT be populated, except for `Resource.meta.security` 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.

  - Implementers SHALL use `YYYY-MM-DDThh:mm:ss+zz:zz` format for `effective[x]` dateTime elements in SHCCovid19LaboratoryResultObservationDM and SHCInfectiousDiseaseLaboratoryResultObservationDM (and their AD counterparts). Additionally, implementers SHALL follow this conformance requirement from FHIR R4's documentation for the dateTime type:

    > If hours and minutes are specified, a time zone SHALL be populated. Seconds must be provided due to schema type constraints but may be zero-filled and may be ignored at receiver discretion. [Emphasis added.]

### Bundles

Bundles meant to populate the `fhirBundle` element of a SMART Health Card AND fall into the scope of this IG described at https://spec.smarthealth.cards/#data-model SHALL conform to one of the profiles of Bundle in this IG.

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

### Validation

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 https://github.com/hapifhir/org.hl7.fhir.core/releases/latest/download/validator_cli.jar

    # Run to get latest package from this IG to validate against
    curl -L -O https://vci.org/ig/vaccination-and-testing/package.tgz

    # 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 http://hl7.org/fhir/uv/shc-vaccination/StructureDefinition/shc-vaccination-dm \
    path/to/immunization.json

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.

#### Terminology validation

ValueSets in this IG are not regularly updated, and therefore are not guaranteed to be complete or correct. Because of this, implementers SHALL independently verify the terminology they use in SMART Health Cards with the canonical version of the relevant code system (e.g., verify CVX codes using the official CDC-published list).

Implementer questions related to terminology should also be directed to the smart/health-cards Zulip stream at chat.fhir.org.

### Internationalization

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 extension 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.

### Dependencies

IG | Package | FHIR | Comment
--- | --- | --- | ---
SMART Health Cards: Vaccination &amp; Testing Implementation Guide | hl7.fhir.uv.shc-vaccination#1.0.0 | R4 |
HL7 Terminology (THO) | hl7.terminology.r4#6.5.0 | R4 | Automatically added as a dependency - all IGs depend on HL7 Terminology
FHIR Extensions Pack | hl7.fhir.uv.extensions.r4#5.2.0 | R4 |
FHIR Tooling Extensions IG | hl7.fhir.uv.tools.r4#0.7.1 | R4 | for example references

Package hl7.fhir.uv.extensions.r4#5.2.0 This IG defines the global extensions - the ones defined for everyone. These extensions are always in scope wherever FHIR is being used (built Mon, Feb 10, 2025 21:45+1100+11:00)

Package hl7.fhir.uv.tools.r4#0.7.1 This IG defines the extensions that the tools use internally. Some of these extensions are content that are being evaluated for elevation into the main spec, and others are tooling concerns (built Sat, Jul 26, 2025 06:59+1000+10:00)

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. ↩