search

smart-on-fhir / smart-health-card-decoder

Sample code for a SMART Health Card validator
MIT License
3 stars 2 forks source link

Include optional text in vaccine coding #18

Closed turgid-tributary closed 1 year ago

turgid-tributary commented 1 year ago

Hello - newcomer here! šŸ‘‹

The Context

I'm working on building Smart Health Links that contain a patient's immunization history, and am using the Commons Project's SHC Web Reader to view the links. I use this library to build the SHCards in the Links, and the viewer uses this lib to verify SHCards in the links.

I'd like to add a bit of readability to the immunization resources themselves. Right now, I include the CVX code of the vaccine in the bundle, but I would also like to include the human readable name of the vaccine. This will prevent the SHC Web Reader from having to understand the codes from the various coding systems to find vaccine names.

It seems the "text" property of the vaccine code within the immunization resource might be the right place for this? If not, I'm all ears.

The Change

Extends the existing ImmunizationResource type's vaccineCode to include the optional "text" property. I believe this is in line with the https://build.fhir.org/ig/HL7/fhir-shc-vaccination-ig/StructureDefinition-shc-vaccination-dm.html spec which indicates vaccineCode is a http://hl7.org/fhir/R4/datatypes.html#CodeableConcept

jmandel commented 1 year ago

There are a couple of things to untangle here:

Right now, I include the CVX code of the vaccine in the bundle, but I would also like to include the human readable name of the vaccine.

  1. If you're trying to create SHCs to follow https://build.fhir.org/ig/HL7/fhir-shc-vaccination-ig/StructureDefinition-shc-vaccination-dm.html and you intend for them to be represented as SHC QRs, you'll also need to follow this guidance, which prohibits use of CodeableConcept.text and Coding.display, in order to ensure that payloads are consistently small and that verifier apps rely on coded rather than free-text information. If you're displaying this sort of information to end-users, https://terminology.smarthealth.cards/ValueSet-immunization-covid-all.html gives you the various display names for these immunization codes, so you don't/shouldn't rely on their presence in the data payload. This technique also allows for the selection of language- and region-specific variations on the names, which can't all be pre-packed into the data payload.

  2. If you're working with SHCs in a non-QR context, you have more flexibility to include additional data in the payloads. So adding an optional .text (and .display) to the types in this project isn't strictly an error, but your use case seems to fall into (1).

Let me know if this makes sense.

turgid-tributary commented 1 year ago

Thanks for the detailed response, Josh! The SHCs I'm using are outside the context of QR codes. I can see the hesitancy to add this change, however, given the current implementation's bias towards QR encoded cards. If we did add this change by itself, there wouldn't be any guarantee the without CodeableConcept.text elements part of the guidance is followed when creating QR codes.

Long term, I can see adding the value sets like https://terminology.smarthealth.cards/ValueSet-immunization-covid-all.html to this library or another. Then I could pull the display names for the CVX codes directly from the valueset.