Stream: smart/health-cards
Topic: SHC FHIR IG conference call (Tue Dec 7, 4pm Eastern time)
Max Masnick (Dec 07 2021 at 19:59):
On the agenda for today's call (in about an hour):
- Review branch that allows
Patient.gender
http://build.fhir.org/ig/HL7/fhir-shc-vaccination-ig/branches/gender - Review https://github.com/dvci/shc-terminology
- Call for help with value set for
Observation.bodySite
for lab tests - (Lack of) update from SNOMED
Grahame Grieve (Dec 07 2021 at 20:13):
I won't be on the call, but the gender branch doesn't address all the disposition, because we also said that we'd provide more documentation about jurisdictional adoption / internationalization
Grahame Grieve (Dec 07 2021 at 20:13):
(ok for it to be done later - just don't want it missed)
Max Masnick (Dec 07 2021 at 20:18):
@Grahame Grieve I added a section on this in that branch, but it's not super robust http://build.fhir.org/ig/HL7/fhir-shc-vaccination-ig/branches/gender/profiles.html image.png
Paul Denning (Dec 07 2021 at 20:25):
https://confluence.hl7.org/display/PHWG/2021-12-07+SHC-VT+ballot+reconciliation+meeting Agenda page
Grahame Grieve (Dec 07 2021 at 20:31):
I missed that. I'll word smith it when I get a chance
Grahame Grieve (Dec 08 2021 at 00:50):
how about something like this:
Internationalization
The base SHC specification is suitable for international use. This specification includes profiles for
- United States
Other jurisdictions are welcome to define their own profiles that reflect their local concerns - contact the local HL7 affiliate or the authors of this specification for assistance. In particular, it is expected that jurisdictional profiles will constrain the AD profiles with details such as national patient/consumer identifiers, relevant demographic details around names etc, and specifying which applicable code systems may be used. Some Jurisdictions may need to make additional rules around the representation of names with regard to character set etc.
International Adoption Issues
Patient Name
Implementers of systems that present SHCs for verification should be aware that naming practices vary around the world, both in terms of name order, and the behavior and relevance of prefixes and suffixes on a person's name. If the Patient name has a text field, then this should be presented as is, and the structured parts of the name (family, given) may also be shown as additional details.
Language
The text for a patient's name is typically appropriately presented in their original language, but some patient names may come with more than one presentation form (e.g. Cyrillic/Latin, or Kanji / Hiragana / Katakana). Where more than one name exists, verifiers should generally show all the names, unless it is confident that one should be preferred, based on the language of the user of the verification system.
The other important text is the display values for the various codes. If a display value is provided in line, this may be used, though it's language may be unknown (see Resource.language). The VIC initiative maintains implementation collateral with language appropriate representations for the some of the codes in this specification (see github).
btw: recommend that the profiles call out Resource.language and recommend populating it ("language":"en", = 17 bytes.)
Grahame Grieve (Dec 08 2021 at 00:53):
though some of that text might belong on the core SHC spec, not this IG
Josh Mandel (Dec 08 2021 at 04:13):
Quick note that byte counts need to be assessed in context -- in terms of effect on realistic payloads after compression.
Grahame Grieve (Dec 08 2021 at 04:14):
indeed. it will be a little less than 17 in effect, but not much. But I think, on considering the cross-border workflows, that Resource.language is a worthwhile thing
Josh Mandel (Dec 08 2021 at 04:18):
Can you say more about how it will be used? The resources in a SMART Health Card don't generally include free text in any language. (Naively, including this information and never resource would be 68 + bytes which ~5% of a small budget but yes with compression it's less bad. But this stuff accretes.)
Grahame Grieve (Dec 08 2021 at 05:30):
well, they include text. a Covid certificate has text in a particular language in the following places:
- Patient.name.text|.family|.given|.prefix|.suffix
- Immunization.vaccineCode.coding.display
- Immunization.performer.display
I know that Immunization.vaccineCode.coding.display isn't supposed to be populated, but implementers outside USA have little choice right now, since the verifier apps will look up US specific displays. At least with covid certs we could aspire to make that unnecessary (per value set we're working on) but there's faint hope of that once we get into lab, let alone all the other things that might come later. So I'm assuming that there will be a display, and border apps (at least) will have to care about it's language
Vitor Pamplona (Dec 08 2021 at 13:25):
Display values are ok for wallet apps (credentials are usually in a language the holder can read), but are terrible for verifier apps. Re-signing a translated credential is quite common in multi-jurisdiction activities (i.e. international students coming to the US universities get their "SHCs" translated and resigned by the translating authority before showing it to a verifier).
Vitor Pamplona (Dec 08 2021 at 14:52):
I would strongly recommend following ICAO's 9303 spec for names. These are used by the EU DCC with good outcomes (aligns with ID cards). The idea is to accept the native way to describe the name in UTF-16 and a transliterated version in the roman alphabet (fields must match) encoded as in the Machine Readable Zone (MRZ). The name can also be truncated.
Vitor Pamplona (Dec 08 2021 at 14:55):
As an example, this is the body of a transliterated DCC of a person with an Arabic name
{
"ver": "1.3.0",
"nam": {
"fn": "ابو بكر محمد بن زكريا الرازي",
"fnt": "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",
"gn": "ناصر",
"gnt": "NAXSSR"
},
"dob": "1964-01-01",
"v": [
{
"tg": "840539006",
"vp": "1119349007",
"mp": "EU/1/20/1507",
"ma": "ORG-100031184",
"dn": 1,
"sd": 2,
"dt": "2021-06-11",
"co": "NL",
"is": "Ministry of Health Welfare and Sport",
"ci": "URN:UVCI:01:NL:DADFCC47C7334E45A906DB12FD859FB7"
}
]
}
Josh Mandel (Dec 08 2021 at 14:57):
I'm not sure exactly what it would mean for us to follow this specification. Do you have a sense of how this would play out in FHIR? Also, can you clarify whether there is some intrinsic reason for the choice of UTF-16?
Vitor Pamplona (Dec 08 2021 at 15:02):
On UTF-8 vs UTF-16, Shorter representations can be achieved with UTF-16. It should be preferred for space constrained situations.
For instance, the Chinese letter "語" - its UTF-8 encoding is:
11101000 10101010 10011110
While its UTF-16 encoding is shorter:
10001010 10011110
Vitor Pamplona (Dec 08 2021 at 15:04):
Reminder that both UTF-8 and UTF-16 are not fixed to 8 and 16 bits. Only UTF-32 is fixed to 32 bits. UTF-8 and UTF-16 are variable length (e.g. UTF-8 the code point maybe represented using either 32, 16, 24 or 8 bits)
Vitor Pamplona (Dec 08 2021 at 15:06):
Besides that, since ECMAScript forced JavaScript strings to be all UTF-16 sequences, UTF-16 representations became the new standard for many applications.
Josh Mandel (Dec 08 2021 at 15:08):
When you say that shorter representations can be achieved, you mean for not ASCII characters? Whereas for ASCII that representation is twice as long? Just trying to understand the trade-off you are implying, assuming you were talking about encoding the entire payload of the JWT ...
Vitor Pamplona (Dec 08 2021 at 15:10):
Correct. Remember, most of the world is non ASCII. :)
Josh Mandel (Dec 08 2021 at 15:11):
most of our JWT payload character set, however, is asking. Every FHIR property name, every delimiter character, etc.
Josh Mandel (Dec 08 2021 at 15:11):
So achieving higher efficiency on the display names that might occur at one or two spots in the payload would not be an obvious win If the rest of the payload expands, right? Or am I misunderstanding something?
Vitor Pamplona (Dec 08 2021 at 15:11):
I believe the JavaScript version of the SHC implementation already uses UTF-16, no?
Josh Mandel (Dec 08 2021 at 15:12):
I don't think we have specified this or produced examples. Don't think character encoding has come up outside of our canonicalization schemes where we have proposed utf8
Vitor Pamplona (Dec 08 2021 at 15:12):
If you didn't manually converted to UTF-8 representations, that javascript implementation is already in UTF-16
Vitor Pamplona (Dec 08 2021 at 15:16):
But you can choose UTF-8 as well. I am not that strong about it.
Vitor Pamplona (Dec 08 2021 at 15:16):
For me, the important component is having a latin representation of the name (as an optional, but formalized field)
Vitor Pamplona (Dec 08 2021 at 15:20):
Or a latin representation of any "display" entry
Josh Mandel (Dec 08 2021 at 15:23):
Leaving inside the encoding question, do you want to share an example of what this would look like in FHIR Patient? We've had some discussion about these practices previously, simple adding more than one item to Patient.name[]
. But the main distinction I'm seeing here between what you are suggesting and what Grahame has suggested is whether to divide the name into parts or not. Your example from ICAO suggests (seems to) that names can always be divided into parts and never need to be represented as a single combined string?
Josh Mandel (Dec 08 2021 at 15:29):
(For our reference code, looks like the utf-8 encoding is covered by https://nodeca.github.io/pako/
Pako's deflate detects input data type, and automatically recode strings to utf-8 prior to compress
)
Vitor Pamplona (Dec 08 2021 at 17:08):
I think the FHIR version of the ICAO model would be an array of 2 HumanNames, but I might be wrong.
Vitor Pamplona (Dec 08 2021 at 17:19):
Too bad the HumanName.use
code doesn't have a clear option for transliteration.
Grahame Grieve (Dec 08 2021 at 19:03):
several comments
Grahame Grieve (Dec 08 2021 at 19:15):
-
FHIR specifies UTF-8 always. UTF-16 is not supported. This was a decision taken in consideration of CDA and HL7 v2 usage in east asian countries, who already made that rule.
-
the question of script doesn't deal with name parts, and the ICAO guidance doesn't either. it's considering an orthogonal issue.
-
The FHIR spec says, concerning this: "The forms are differentiated by the character subset each contains", and from the standard's pov, transliteration isn't a 'use'"
The ICAO example in FHIR looks like this:
"name" : [{
"family" : "ابو بكر محمد بن زكريا الرازي",
"given" : "ناصر",
},{
"family" : "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",
"given" : "NAXSSR"
}]
Technically, if one wanted to be explicit, you could do this:
"name" : [{
"family" : "ابو بكر محمد بن زكريا الرازي",
"given" : "ناصر",
"extension" : [{
"url" : "http://hl7.org/fhir/StructureDefinition/language",
"valueCode" : "ar-Arab"
}]
},{
"family" : "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",
"given" : "NAXSSR",
"extension" : [{
"url" : " http://hl7.org/fhir/StructureDefinition/iso21090-EN-representation",
"valueCode" : "ABC"
},{
"url" : "http://hl7.org/fhir/StructureDefinition/language",
"valueCode" : "ar-Latn"
}]
}]
Grahame Grieve (Dec 08 2021 at 19:18):
there's no ISO name representation code for arabic characters - the representation code is intended for Japan (which is why it's an extension). What's happening in the Arabic case isn't quite the same thing, so probably the ISO extension is not quite valid (would need to sit in a room with a bunch of linguists and terminologists and let them argue over that one).
Vitor Pamplona (Dec 08 2021 at 19:27):
FHIR specifies UTF-8 always.
Interesting! I have to pay more attention when working with FHIR on JavaScript then.
Vitor Pamplona (Dec 08 2021 at 19:29):
What I don't like about the array structure is that the relationship between the two array items is not defined. The HumanName array on FHIR might represent completely different names, each should have their own transliteration as per ICAO's model.
"name" : [{
"family" : "ابو بكر محمد بن زكريا الرازي",
"given" : "ناصر",
},{
"family" : "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",
"given" : "NAXSSR"
}]
Vitor Pamplona (Dec 08 2021 at 19:30):
I am not sure if there is a good solution. Maybe FHIR-based implementations simply cannot expect to map names and transliterated names individually.
Josh Mandel (Dec 08 2021 at 19:38):
From my perspective, tagging one name as "this one is romanized" doesn't add information that a client couldn't figure out for itself (i.e., by inspecting the name).
Vitor Pamplona (Dec 08 2021 at 19:40):
The ISO21090 extension @Grahame Grieve mentioned classifies in ABC (Alphabetic), IDE (Ideographic), SYL (Phonetic), which might have valid use cases.
Vitor Pamplona (Dec 08 2021 at 19:42):
But it would be nice to not have extensions on SHCs (space constraints)
Grahame Grieve (Dec 08 2021 at 19:44):
indeed I don't think that extensions are justified here.
Grahame Grieve (Dec 08 2021 at 19:48):
I agree that it could be more explicit, but we discussed this extensively with regard to arabic names somewhere else. It was a few years ago, so I don't recall where we discussed it, sorry.
Vitor Pamplona (Dec 08 2021 at 19:50):
The ISO21090 representation and the passport MRZ encoding seem to also be orthogonal from each other.
Vitor Pamplona (Dec 08 2021 at 19:50):
What a mess.
Vitor Pamplona (Dec 08 2021 at 19:52):
Let's remove all Patient info and just put the patient's faceID biometric vector there. Problem solved. :upside_down:
Vitor Pamplona (Dec 08 2021 at 22:11):
Josh Mandel said:
From my perspective, tagging one name as "this one is romanized" doesn't add information that a client couldn't figure out for itself (i.e., by inspecting the name).
From a verifier perspective, I want to be able to display all names in their appropriate UI. In the example, I would put ناصر ابو بكر محمد بن زكريا الرازي
as a name in the top of the card and NAXSSR<ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY
in the bottom, with a smaller font, similar to the Passport layout.
Vitor Pamplona (Dec 08 2021 at 22:14):
And if a Naxssr Abw Bkr Mxhmd Bn Zkrya Alrazy
is provided, the UI's name component would be Name (Arabic/English)
and the top of the card would have ناصر ابو بكر محمد بن زكريا الرازي/Naxssr Abw Bkr Mxhmd Bn Zkrya Alrazy
Vitor Pamplona (Dec 08 2021 at 22:17):
Like this: Screen-Shot-2021-12-08-at-5.17.01-PM.png
Josh Mandel (Dec 09 2021 at 02:32):
The use makes sense; I'm just saying that you could make the distinction by inspection, without an explicit metadata tag.
Grahame Grieve (Dec 09 2021 at 03:15):
you can, if you know what you're looking for. writing a general purpose detection algorithm is going to be pretty fun. But my basic contention is that you don't need to - you have a series of strings that are names - show them all to a user, and if you're doing id matching (shouldn't be off an SHC, so this is mainly elsewhere) then consider all the names. If that general purpose algorithm falls down, then you need to unicode range determination
Vitor Pamplona (Dec 09 2021 at 04:21):
"Just dump them on the user" is not good UX design. Users expect much more than a dump of the FHIR fields on the screen.
Grahame Grieve (Dec 09 2021 at 07:00):
of course in general I agree. But for names... I don't agree. what else are you going to do but show the names you find in an SHC?
Vitor Pamplona (Dec 09 2021 at 14:58):
Apps generally have a context they are working with in. For instance, if they know their user speaks Chinese by checking the languages installed on their phone, they don't need to show transliterated names. If the user only speaks English, the app doesn't need to present the Chinese version of the name. It's irrelevant.
Vitor Pamplona (Dec 09 2021 at 14:59):
The option to show additional versions of the name will be on the screen somewhere (if they need, it will be accessible), but it's not the default behavior.
Vitor Pamplona (Dec 09 2021 at 15:00):
Same is true for levels of detail of information (showing issuing city for locals vs issuing country for foreigners)
Vitor Pamplona (Dec 09 2021 at 15:01):
An SHC issued by BC should show "Issued by BC" in Canada and "Issued by Canada" in the US. A US user doesn't care which state the holder got his credentials from.
Vitor Pamplona (Dec 09 2021 at 15:07):
A US SHC in India doesn't show the Pharmacy's name. It simply shows "Issued by a pharmacy in the USA". If they click on it, users will get more info, but otherwise it's irrelevant. If the app shows "Issued by CVS", no one knows what those letters are. It's just more confusion for the low level staff trying to process these credentials in the field.
Vitor Pamplona (Dec 09 2021 at 15:09):
In many cases outside the US, SHCs from US-based entities will simply say "Issued by the USA" to avoid user interface freakout. It's not correct. But it doesn't matter. What matters is that users can do their job (pass people trough) fast.
Vitor Pamplona (Dec 09 2021 at 15:16):
Going back to the names. If the app knows the user is verifying against an ID, the app needs to choose to display only the name that will be in the ID (likely the "official" name on the array). But if the holder is a foreigner, the app needs to show the transliterated version (e.g. Americans can't do pattern matching of Chinese characters). If the names are not comparable for a foreigner, the app needs to show the MRZ code and the user needs to compare against that part in the passport. Now, if the user is not performing ID checks against another document, then the app should show the "usual" or "nicknames" available as names.
Vitor Pamplona (Dec 09 2021 at 15:29):
If you think about the business case for each app, you would never say "they don't need to". Because they MUST. It's the only thing they can do to survive. The only differentiator between apps processing the same payload is the amount of smartness baked into the app that makes the life easier for their user base. The value-add for apps is directly proportional to the work they do to contextualize the information. Thus, the more the spec ALLOWS them to contextualize, the better it gets.
Josh Mandel (Dec 09 2021 at 15:51):
the more the spec ALLOWS them to contextualize, the better it gets.
Sure -- and a spec where multiple names are available, and where apps can evaluate them to determine context on the basis of their content (e.g., characters) would seem to meet this bar.
Vitor Pamplona (Dec 09 2021 at 15:54):
Does this make sense?
"name" : [{
"use": "official",
"enc": "IDE",
"family" : "ابو بكر محمد بن زكريا الرازي",
"given" : "ناصر"
},{
"use": "official",
"enc": "MRZ",
"family" : "ABW<BKR<MXHMD<BN<ZKRYA<ALRAZY",
"given" : "NAXSSR"
},{
"use": "usual",
"enc": "IDE",
"family" : "ابو بكر",
"given" : "ناصر"
},{
"use": "usual",
"enc": "ABC",
"family" : "ALRAZY",
"given" : "NASSIR"
}]
Grahame Grieve (Dec 09 2021 at 19:11):
For instance, if they know their user speaks Chinese by checking the languages installed on their phone, they don't need to show transliterated names. If the user only speaks English, the app doesn't need to present the Chinese version of the name. It's irrelevant.
I don't agree with that, because the app doesn't know anything about who the user is talking to - using a verifier app is almost never a solitary experience
Grahame Grieve (Dec 09 2021 at 19:12):
A US SHC in India doesn't show the Pharmacy's name. It simply shows "Issued by a pharmacy in the USA". If they click on it, users will get more info, but otherwise it's irrelevant. If the app shows "Issued by CVS", no one knows what those letters are. It's just more confusion for the low level staff trying to process these credentials in the field.
maybe but nothing about the existing content of an SHC allows for this level of sophistication
Grahame Grieve (Dec 09 2021 at 19:13):
Does this make sense?
Well, what's the definition of 'enc'?
Vitor Pamplona (Dec 09 2021 at 19:23):
Grahame Grieve said:
For instance, if they know their user speaks Chinese by checking the languages installed on their phone, they don't need to show transliterated names. If the user only speaks English, the app doesn't need to present the Chinese version of the name. It's irrelevant.
I don't agree with that, because the app doesn't know anything about who the user is talking to - using a verifier app is almost never a solitary experience
The user of a verifier app is a verifier, not the holder. The app knows plenty about the verifier. The holder is irrelevant to the context used by a Verifier app. The Holder only matters to the Wallet app (which also knows the holder very well).
Vitor Pamplona (Dec 09 2021 at 19:24):
Wallet apps don't even need to show the Patient name by default ;) I don't need to see my name in the card.
Vitor Pamplona (Dec 09 2021 at 19:26):
Well, what's the definition of 'enc'?
Encoding. It's an extended version of the ISO21090 "representation" codes
Grahame Grieve (Dec 09 2021 at 19:30):
I don't need to see my name in the card
Well, you have kids? because my wallet has stuff in it for my kids. And also, my wife and I have our covid certificates in both our wallets, in case we run out of battery on one of our phones
Vitor Pamplona (Dec 09 2021 at 19:33):
Grahame Grieve said:
I don't need to see my name in the card
Well, you have kids? because my wallet has stuff in it for my kids. And also, my wife and I have our covid certificates in both our wallets, in case we run out of battery on one of our phones
The wallet knows your name. It doesn't need to show your name on your credentials. If you add your kids/wife/etc credentials, they are not yours. The app is supposed to know the difference and render them differently.
Vitor Pamplona (Dec 09 2021 at 19:42):
Here's how a Wallet app should display every SHC where the holder == user.
Vitor Pamplona (Dec 09 2021 at 19:44):
No names, no vaccine brand and no other detailed information. Just the calculation on where my protection starts (what really matters).
Vitor Pamplona (Dec 09 2021 at 19:46):
Notice how the biggest value-add (knowing when the protection starts) requires the app to manage scientific knowledge beyond what you will find on an SHCs. That's why users will choose this app as opposed to some random open-source FHIR visualizer app.
Vitor Pamplona (Dec 09 2021 at 19:55):
Here's a second design I worked with: dashboard_with_1_dose_1_code_ios.png
Vitor Pamplona (Dec 09 2021 at 20:11):
From a Verifier, perspective. This is one I have been working with. It allows the verifier (venue host) to host his credentials in the app and show to attendees when they want to see it while serving the main purpose of scanning and storing the credentials of everyone that comes in, separating them by date + tags and then name of the holder.
Screen-Shot-2021-12-09-at-3.09.00-PM.png
Max Masnick (Dec 30 2021 at 21:01):
I logged an issue re: populating Resource.language
: https://jira.hl7.org/browse/FHIR-34808
Last updated: Apr 12 2022 at 19:14 UTC