SMART Health Cards: Vaccination & 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

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

The SMART Health Cards community maintains terminology.smarthealth.cards, which provides ValueSets of codes relevant to this IG that can be updated rapidly as public health needs dictate. Data elements in this IG are bound to ValueSets hosted on terminology.smarthealth.cards to support validation of terminology using FHIR tooling. However, the terminology.smarthealth.cards ValueSets are not guaranteed to be complete or correct. Therefore, 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).

Implementers are also encouraged to participate in the community maintaining terminology.smarthealth.cards on Zulip (free account required). Please notify the community of any inconsistencies between terminology.smarthealth.cards ValueSets and canonical version of the relevant code code systems.

Other 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 & Testing Implementation Guide	hl7.fhir.uv.shc-vaccination#1.0.0	R4
HL7 Terminology (THO)	hl7.terminology.r4#5.3.0	R4	Automatically added as a dependency - all IGs depend on HL7 Terminology
FHIR Extensions Pack	hl7.fhir.uv.extensions.r4#1.0.0	R4	Automatically added as a dependency - all IGs depend on the HL7 Extension Pack
SMART Health Cards: Terminology	cards.smarthealth.terminology#0.1.0	R4