Stream: cds hooks
Topic: docs / Issue #33 What Markdown flavor and/or restrictions...
Github Notifications (May 04 2017 at 20:57):
kpshek opened Issue #33
In discussion with @brynrhodes and @Isaac Vetter, we had some questions that we should answer in the spec/documentation:
Markdown Support
Is Markdown required or an optional feature that EHRs can support? If Markdown is optional, it would be nice for EHRs to advertise their support for it so that CDS Services can return cards accordingly.Markdown Flavor
What flavor of Markdown should CDS Hooks support? Eg, CommonMark? Github Flavored Markdown? etc.Risks with Embedded HTML in Markdown
Markdown allows for any embedded HTML. Should this be allowed? If so, we need to document how EHRs must mitigate against risks of cards that now contain executable code (JS) or conflicts with CSS classes/names.Risks with embedded HTML is actually no different than risks posed by embedding SMART apps in an EHR. However, we should probably call out good practices (like usage of iframes).
A potential difference between integrating SMART apps and CDS cards into the EHR is the level of integration we expect with CDS cards. The intention is that since the majority of a CDS card is structured data rather than UX (or entirely if there is no embedded HTML), then the rendering of the card should be close or indistinguishable from the native EHR.
Another point of consideration is that allowing for embedded HTML in the Markdown starts to veer CDS cards in the direction of mini SMART apps.
And finally, another option could be allowing for embedded HTML but only a subset of HTML functionality/tags (a whitelist). This would offer CDS cards the ability to style themselves somewhat but perhaps disallow them from incorporating app-like functionality.
Thoughts & discussions from the community is welcome!
Github Notifications (May 04 2017 at 20:57):
kpshek milestoned Issue #33
Github Notifications (May 04 2017 at 21:04):
jmandel commented on Issue #33
I think Markdown is optional, and we should do our best to "pick one". We need to be quite careful about embedded HTML, but I think we need a way to reference at last images (possibly with a restriction to only allow inline base64 data-url images, if we want to avoid calls out to an external server) and tables (I know Markdown enables tables without HTML, but it's kind of a pain IMO).
There's some relevant discussion at:
https://www.hl7.org/fhir/narrative.html#2.4.0
https://www.hl7.org/fhir/security.html#narrative
Github Notifications (May 05 2017 at 10:21):
I'm of the opinion that it should be a strict subset of markdown (we have implemented headings, numbered lists, unordered lists, and links). The EHR in most cases would do actual formatting and styling (after all you cannot assume this is displayed in a browser - and it is highly likely that there are space constraints), while what they need is the structure of the text and links. The alternative of plain text doesn't work well in practice. For real cards provided via hooks today, I have primary statements, secondary statements (long), and supporting evidence (citations with links), and a few other items. All of this is pushed into the detail as there is no better place for it. An alternative might be to move it all to the smart app, but that would mean suggestions are of little use in a real CDS application.
Github Notifications (May 05 2017 at 15:43):
jmandel commented on Issue #33
For real cards provided via hooks today, I have primary statements, secondary statements (long), and supporting evidence (citations with links), and a few other items
This is great feedback, thanks!
Github Notifications (May 07 2017 at 10:47):
seanmsmith23 commented on Issue #33
As much as we'd love to use all of HTML as a CDS-service provider, I think it makes the most sense that cards have a standardized feel so that the provider becomes familiar/comfortable with what they are seeing and why (which I think everyone would benefit from).
I don't have strong feelings about exactly what flavor of Markdown to use. Just so long as we get more flexibility than plaintext.
Last updated: Apr 12 2022 at 19:14 UTC
