FHIR Chat · health-cards-issue operation · smart/health-cards

Stream: smart/health-cards

Topic: health-cards-issue operation

Grahame Grieve (Sep 05 2021 at 00:26):

This operation doesn't have a formal definition anywhere yet?

Josh Mandel (Sep 05 2021 at 00:46):

It has a JSON operation definition

Josh Mandel (Sep 05 2021 at 00:47):

Here in the optimistically pluralized and not widely advertised artifacts directory https://github.com/smart-on-fhir/health-cards/tree/main/docs/artifacts

Josh Mandel (Sep 05 2021 at 00:49):

(I don't know if anyone is using this to directly drive any kind of behavior, so I expect it'll turn out to be broken some ways.)

Grahame Grieve (Sep 05 2021 at 00:55):

so this will live in the IG eventually, right? The canonical URL will be http://hl7.org/fhir/uv/shc-vaccination/OperationDefinition/health-cards-issue ?

Grahame Grieve (Sep 05 2021 at 00:56):

I just decided not to generate from it too ;-) (which means I just want the canonical URL, though I can always make a temporary one)

Josh Mandel (Sep 05 2021 at 01:06):

The Vaccination/Testing IG is particular to the data profiling, so it's not where we think a general purpose issuance operation belongs. We still need to bring the core framework through HL7 process.

Grahame Grieve (Sep 05 2021 at 01:14):

ok. well, I can change it later.

Grahame Grieve (Sep 05 2021 at 01:14):

this is a bit odd for me:

Grahame Grieve (Sep 05 2021 at 01:14):

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "verifiableCredential",
    "valueString": "<<Health Card as JWS>>"
  }, {
    "name": "resourceLink",
    "part": [{
        "name": "vcIndex",
        "valueInteger": 0
      }, {
        "name": "bundledResource",
        "valueUri": "resource:2"
      }, {
        "name": "hostedResource",
        "valueUri": "https://fhir.example.org/Immunization/123"
    }]
  }]
}

Grahame Grieve (Sep 05 2021 at 01:14):

wouldn't this be better:

Grahame Grieve (Sep 05 2021 at 01:16):

this seems more natural:

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "verifiableCredential",
    "part": [{
        "name": "signedCredential",
        "valueString": "<<Health Card as JWS>>"
      }, {
        "name": "resourceLink",
        "part": [{
          "name": "bundledResource",
          "valueUri": "resource:2"
        }, {
          "name": "hostedResource",
          "valueUri": "https://fhir.example.org/Immunization/123"
      }]
    }]
  }]
}

Grahame Grieve (Sep 05 2021 at 01:17):

group the card with the links, and get rid of vcIndex

Josh Mandel (Sep 05 2021 at 01:23):

https://github.com/smart-on-fhir/health-cards/issues/88 has discussion; short answer is we didn't want to break our API at the point when we introduced these properties

Grahame Grieve (Sep 05 2021 at 01:44):

If no results are available, a Parameters resource without any parameter is returned:

{
  "resourceType": "Parameters"
}

Josh Mandel (Sep 05 2021 at 01:49):

That's what we say... is this not kosher?

Grahame Grieve (Sep 05 2021 at 01:53):

I think it is, and I'm sure we've specifically discussed this before - it's the only circumstance where you have an empty resource. But it feels to me like it would be appropriate for the server side to return some string message in these cases, so that a user can be communicated with concerning why. And if the server doesn't want to say anything of substance, it can pick it's own non-descript wording to present to the user.

Grahame Grieve (Sep 05 2021 at 01:55):

I'm thinking this will minimise human support needed. ("I don't get any cards, just a message that 'there's no results' - I didn't want any results, just my card!")

Josh Mandel (Sep 05 2021 at 01:55):

It's analogous to an empty search result in my thinking; if the system has no data, it's not necessarily something that needs explaining. But for sure we could add an optional param

Josh Mandel (Sep 05 2021 at 01:57):

Users aren't going to be calling this API any more than they call a search API. Health apps will ask for data of all kinds on behalf of the user without explicitly showing the user anything if there's no data.

Grahame Grieve (Sep 05 2021 at 02:21):

me, I'm thinking that's not so true. Users will want their cards. They'll really need them. I'm imagining it will be a specific operation, not just something done in the background by the app. "Get me my cards." Perhaps I'm wrong.

Josh Mandel (Sep 05 2021 at 02:55):

That's fair; most experience today with users explicitly requesting health cards has been downloading via state public health portals rather than connecting an app to call this operation via SMART on FHIR. For cases where the API is supported, It has been as part of generic patient APIs from healthcare providers (who may have all kinds of USCDI data and won't necessarily be expected to have health cards for most patients, unlike the state portals which can offer cards to the whole population).

Josh Mandel (Sep 05 2021 at 02:59):

I'm not sure what kind of message would really cut down on support calls if a user was expecting their health app to fetch a card and it couldn't, but I'm certainly in favor of adding optional response properties to ensure issuers can pass back a message if they want to. (As an alternative or additionally, I'd think about having issuers statically advertise a URL for health cards support.)

Grahame Grieve (Sep 05 2021 at 05:08):

more that it might cut down the difficulty of resolving the support call, rather than their frequency. But: yes, search can return messages that inform about issues, and I think this could too

Grahame Grieve (Sep 05 2021 at 05:08):

and agree about support info - in the .well-known?

Josh Mandel (Sep 05 2021 at 14:11):

Field in [FHIRServer base].well-known/smart-configuration would work for API based issuers, We might want to provide an ".healthCardIss" property in that file, and then push other health cards issuer data into a file that's discoverable relative to the health card iss url, so the same format could be used for issuers that don't support the API. Some discussion at https://github.com/the-commons-project/vci-directory/issues/52 (website field for example) about what these metadata might be. (That conversation is about metadata in the directory, but as Paul points out it could just as well apply to metadata published by issuers.)

Grahame Grieve (Sep 05 2021 at 20:44):

with regard to credential types, I can't currently request both immunization and lab test covid cards, right? I can say 'all covid cards', but not more than one type of covid card?

Grahame Grieve (Sep 05 2021 at 20:51):

One of the things that's come up a lot with search is unrecognised parameter values. Given that the health-cards operation is taking a Parameters resource as a post, there's no reason for it to contain added parameters from the stack anywhere, and so unrecognised parameters should cause an error. Or at least, the expected behavior should be clarified somewhere

Josh Mandel (Sep 05 2021 at 22:23):

In a single API call, you supply a list of types that the server ANDs together. If you need other cards, you make another API call. (You can always just ask the server for all health cards it has by passing a generic type like #health-card.)

Grahame Grieve (Sep 06 2021 at 01:03):

I can. The idea that the card meanings intersect, while having different and orthogonal granularities... it's kind of screwy, really. if there's another type added (like conditions) the logic will suddenly get much more intricate. I don't have any suggestions, but if more sub-types are added, we'll need to be more specific about groupings and logic

Josh Mandel (Sep 06 2021 at 01:17):

Are you thinking from the issuance perspective or the sharing perspective? The aim has been to get issuers to classify cards up front so that downstream selection logic can work even for wallet apps without a deep understanding of FHIR (i.e., all they need to know is that every card has types). If we relax this goal, we could just have queries written as fhirpath expressions over bundles and ask wallets to evaluate those against all cards stored, to figure out what matches.

Grahame Grieve (Sep 06 2021 at 01:25):

I was just thinking in terms of responding to the operation. The logic is a bit screwy. Her'

Grahame Grieve (Sep 06 2021 at 01:25):

here's my pseudo-code:

Grahame Grieve (Sep 06 2021 at 01:48):

boolean covid = is https://smarthealth.cards#covid19 in credentials?
if (https://smarthealth.cards#health-card or https://smarthealth.cards#immunization) and not (https://smarthealth.cards#laboratory) then
  makeImmunizationCard(...)
if (https://smarthealth.cards#health-card or https://smarthealth.cards#immunization) and not (https://smarthealth.cards#immunization) then
  makeLmmunizationCard(...)

Grahame Grieve (Sep 06 2021 at 01:48):

unless I have it wrong. But I don't think I do. But each new credentialType is going to complicate that logic significantly.

Grahame Grieve (Sep 06 2021 at 01:49):

I thoroughly endorse making wallet apps simple, and the credential type is fine. it's just the weird mix in the request that will be difficult to manage going forward

Josh Mandel (Sep 06 2021 at 01:52):

I don't think you need to explicitly check for the #health-card type in your logic, since all health cards will have it. otherwise looks right to me (and if we wind up having loads more types, let's think about how to structure more cleanly.)

Grahame Grieve (Sep 06 2021 at 01:54):

since all health cards will have it

But not all requests to $health-cards-issue will have it? I wasn't sure how to think about that.

Josh Mandel (Sep 06 2021 at 01:54):

Requests can omit this if they're supplying a subtype like #imnunization becsuse the supertype is logically implied

Josh Mandel (Sep 06 2021 at 01:54):

(the other thing you can do is to always pregenerate cards for the types you support whenever new data arrives, and at issuance API call time just select among them the same way a wallet would.)

Grahame Grieve (Sep 06 2021 at 01:55):

Requests can omit this if they're supplying a subtype like #imnunization becsuse it's logically implies.

What does it mean if you don't specify it, and just specify https://smarthealth.cards#covid19? Nothing will be returned?

Josh Mandel (Sep 06 2021 at 01:57):

If you ask for #covid19 as your only request type, that's equivalent to asking for #covid19 and #health-card together. You should receive any Covid immunization cards and any Covid lab result cards that the server can provide.

Josh Mandel (Sep 06 2021 at 01:58):

https://spec.smarthealth.cards/vocabulary describes the types/subtypes

Grahame Grieve (Sep 06 2021 at 01:58):

so asking for https://smarthealth.cards#health-card or not is irrelevant? It's a useless parameter, even though the example says you provide it

Josh Mandel (Sep 06 2021 at 02:00):

I think it's useless if you're already supplying another type that's a subtype, since "A intersect with B" is the same as "B" if B is a subset of A.

Grahame Grieve (Sep 06 2021 at 02:00):

well, I think that should be documented, since it's not obvious.

Josh Mandel (Sep 06 2021 at 02:01):

(It's arguably useless also if it's the only parameter, but it's explicit, and allows for a future where we change up the type system.)

Grahame Grieve (Sep 06 2021 at 02:01):

the other issue is that correct processing of the request requires for you to not ignore credentialTypes you do not recognise

Josh Mandel (Sep 06 2021 at 02:02):

That's certainly true (it's an "issue" to make sure that's documented/understood, but I don't think it's a design problem - agreed?)

Josh Mandel (Sep 06 2021 at 02:03):

(understanding all requested types is implied, since every card you return needs to include all of the requested types.)

Grahame Grieve (Sep 06 2021 at 02:03):

well, I feel like it's both. Sure, we could call ourselves happy with that design, but it feels fragile to me - resistant to graceful forward change

Josh Mandel (Sep 06 2021 at 02:04):

You can't satisfy the request if you don't understand it.

Grahame Grieve (Sep 06 2021 at 02:05):

generally, we aim for you satisfy the request to the degree you do understand it. That's not always safe, but it's must more robust if things can be designed that way. This piece of API doesn't have that resilience to my way of thinking

Josh Mandel (Sep 06 2021 at 02:05):

Advertising supported types (per the VCI modeling issue linked above) and failing if a client requests something unsupported shouldn't (?) be fragile.

Josh Mandel (Sep 06 2021 at 02:06):

Clients can always just ask for "all health cards" and generally do/should just do that.

Josh Mandel (Sep 06 2021 at 02:07):

All this fancy issuance-time type specificity is already in "do we need it" territory IMO.

Grahame Grieve (Sep 06 2021 at 02:08):

well, it's for privacy reasons, right?

Grahame Grieve (Sep 06 2021 at 02:09):

I just don't like the intersection part. Just make the client list the card-types they want, with fully coordinated codes that are specific. Then it's simple for both client and server

Josh Mandel (Sep 06 2021 at 02:09):

privacy reasons

No, health apps are generally running under a user's control and in any case are limited by their authz scopes.

Fully coordinated codes

Josh Mandel (Sep 06 2021 at 02:10):

Fair enough, re: intersections. Might be overkill to have two axes (I just think intersections are simple -- I realize I'm not in the mainstream on this.)

Grahame Grieve (Sep 06 2021 at 02:12):

I was getting to the interplay around authz scopes. I'd be perfectly happy with we simplified to just use authz scopes, but I'm trying not to comment on requirements, since I don't have real world ones, I'm just exercising the API.

Grahame Grieve (Sep 06 2021 at 02:12):

and regarding intersections: sure, testing intersections is ok. It's the process around them that complicates things

Last updated: Apr 12 2022 at 19:14 UTC