Clarification of examples/allowable data

[NCommander]

I've been working on implementing SHC as part of a framework to handle multiple COVID-19 QR codes, and would like to see some clarification in the specification and/or additional examples to handle additional data.

At its heart, the SMART card is essentially FHIR records with additional meta data, and by my reading, the SMART standard allows for things that might not be desirable, or at least, should have examples if they're. Here's the list of the big cases I ran into working on implementing the standard for the Vaksina (https://github.com/NCommander/vaksina) project.

Improvements to the example cards

It would be helpful to have decodes of what a given card for a given reference.

Example 0/1

For example, example 0, with John B. Anyperson, it would be helpful if the decoded data is clearly laid out

• Name: John B. Anyperson
• DoB: 1951-01-20
• Immunizations:
  • Moderna 1
    • Given at 2021-01-01
    • Given at ABC General Hospital
    • Lot number 0000001
  • Moderna 2
    • Given at 2021-01-29
    • Given at ABC General Hospital
    • Lot number 0000007

This can be used to help properly handle unit testing and more. I know Example 01 has Jane B. Anyperson, which has two shots of Pfizer.

Example 02

To be honest, I'm not sure what to do with this example with coding a COVID validator app. It's defined as a health-card, but its not a immunization or covid19 card, so it feels very out of place. I'm only using it as test data to ensure I properly handle non-COVID19 cards through.

Example 03

It wasn't immediately clear that this card was a revoked example until I took a closer case of the data. It has a JWTS expiration time stamp as well, which isn't noted unless you look at each level clearly. It would be useful if the examples clearly denoted why it shouldn't be accepted, and perhaps have both a seperate expired and seperate revoked card.

Needed examples

I've been working through also handling cards specification currently allows, without a clear understanding if that was the intent. Since SMART basically just points to FHIR in a lot of cases, it's hard to know if a given behavior is intended or not, and either examples or clarification would be helpful

Multiple names per patient

The FHIR Patient Record can have multiple name fields on it, as per (https://www.hl7.org/fhir/patient.html), but the standard doesn't address or note this specifically. In general, it would be helpful to have guidelines on how multiple names should be handled with an example case provided.

Multiple patients per card

As written, the SMART card standard technically can encode multiple patients with individual vaccine records. I don't think this was intended, but I've coded an example bundle so I can properly test and handle handle this case in my code: https://github.com/NCommander/vaksina/blob/main/tests/data/fhir/bundle_multiple_people.json

I would greatly appreciate an official example of how this should work, or the wording on the specification denoting that a health card is for one specific individual.

Useful examples

This is more ones that would help validate code is written correctly. I haven't crafted my own examples for these yet, but I'm working on it. While I know Passes are out of scope for SHC specifically, better examples of "real world" data would still be useful for writing validations.

Example records with one shot, or two shots with a booster

This would be useful for validating code paths then the existing records which is one shot.

Bad signature example

This is straight forward, but a card that is declared to be signed with "https://spec.smarthealth.cards/examples/issuer", or claims to be signed with KID "3Kfdg-XwP-7gXyywtUfUADwBumDOPKMQx-iELL11W9s", but isn't. Having examples that are knowingly invalid is extremely helpful for writing consistent test code.

Handling of incomplete Immunization Records

FHIR defines three status codes for an immunization record, complete, entered-in-error, and not-given. While I can understand that SHC are designed to have factual information about a given patient at a time, examples hilighting that you can't blindly accept an immunization record would be appreciated. There are, unfortunately, people who will only look at the example data, and not realize that one has to parse the status field

These are the things I ran into while coding vaksina's SHC parser, and would help me and other implementors a lot. I'd be happy to submit pull requests to help.

~ NCommander

[christianpaquin]

I agree that the examples would benefit some explanations; something we should add to the spec (in short: example 2 is an artificial bundle that requires splitting the QR code in multiple chunks, and example 3 was recently added to illustrate the new revocation and expiration features). Invalid examples are certainly useful for implementers; it's debatable if these should be in the core spec or in testing projects. For example, see the many examples in the testdata folder of the dev tools project. Although these were created to test the dev tools, some could be reused to test a verifier app.

[NCommander]

If we have a set of cards that I can load in that should pass/fail, that would work well for me, as long as I had a canonical set of reasons of how they should fail/pass, and it was clearly linked, but the spec it should self make it clean if things like multiple patients per card are allowed, since unless you look at the FHIR bundle, and realize its an array, its non-obvious.

From what I can tell from the repo, the test cards are just generated and posted, but maybe we should have a specific MD document that goes through each card and why, and then links back to each raw file as needed?

[christianpaquin]

From what I can tell from the repo, the test cards are just generated and posted, but maybe we should have a specific MD document that goes through each card and why, and then links back to each raw file as needed?

Spec examples are generated by this script, which also produces the example.md file. At a minimum we could add a bit more details to each example.

[jmandel]

Spec examples are generated by this script, which also produces the example.md file. At a minimum we could add a bit more details to each example.

Agreed -- I'll add this as a start. Thanks @NCommander for the detailed suggestions.