Ah, thanks for explaining, this sounds very useful indeed!
2 Likes
I am happy to collaborate and help where I can in defining what the flattened model should look like. (we need to find a better term than flattened !!)
I think we should look to flatten both the two-level (archetype) and three-level (template) models.
4 Likes
There probably needs to be some kind of mechanism to specify how much of the optional parts of the RM should be included. For example, reference ranges are very useful for lab results, but maybe not for medication dosages.
1 Like
If we take the API approach this should be doable.
I think it’s important that the clinical modellers review the output, don’t want to lose important aspects of the model
2 Likes
Not sure what you mean.
- If you mean we’d flatten archetypes+RM without having a containing template things may get pretty confused when implementing since most concrete use cases will need a combination of archetypes (+often template level terminology binding) and when comitting data at least be contained in a COMPOSITION.
- If you mean we’d flatten all three levels together then I am with you. The simplest free-statnding and comittable thing would be templates where the root is a COMPOSITION.
- A third option - that might be the real modular use case you might be looking for - may be to flatten templates for reusable sub-parts of a COMPOSITION, similar to the (Glucose/HbA1c) LABORATORY TEST RESULT EXAMPLE template that is made up of several, partly terminology bound, archetypes - in this case rooted in an OBSERVATION. See image below.
Perhaps we should then also offer a list with a set of commonly used pre-packaged flattened templates with user guides, e.g. vital signs.
2 Likes
When creating a generator that parses an operational template definition (in OPT, webtemplate or other format) it would likely not be too hard to create both JSON schema and OpenAPI outputs in the process (they have a lot of similarities). Some tools like Altova Mapforce (and perhaps Mirth?) support Json schema and many code generators support openAPI.
A quick dirty hack POC version of schema+OpenAPI generator might be drummed up basing code on @bna’s web template → Asciidoc script that @ian.mcnicoll has continued on at https://github.com/freshehr/wt2doc (mentioned in post 20 above) and replace the DocBuilder.ts class etc. A better more properly model based converter may could likely be done fairly quickly by @NeoEHR and his nice builder code or by something from @pieterbos & Co at Nedap or somebody else.
There could of course be many improved JSON structures to target, but to start with the simplified “structured” JSON that Better, EHRbase and others are using would be good to hav for integration tools that may want to loop over a structure. It’s called structSDT in Simplified Data Template (SDT) specification and COMPOSITION data instances can be both imported and exported in platforms like Ehrscape, see images below of the non-standardized way:
If using the standardised openEHR REST API I hope the same could be accomplished using the string application/openehr.wt.structured+json in the http-header Content-Type in the requests as described in the Alternative data formats section of the REST spec overview, when POSTing and GETting COMPOSITIONS. How many openEHR implementations support this already - ping @birger.haarbrandt @bna @pieterbos @borut.fabjan @stoffe @Seref and others?
2 Likes
Streamlined?
Existing technology is enough for doing this. GraphQL is a kind of query language for a data exchange API. If we are able to define a streamlined data model that includes every bit of information of the RM, it would be a responsibility of the data consumer to ask for the information or data points they want. I think it is the most flexible approach to deal with the RM extensive metadata plus the variability of archetypes and templates.
4 Likes
I agree that GraphQL would be interesting, but to live up to developer’s mental models of it, they (at least the ones here at Karolinska) would likely want to be able to think that there is an active data store behind the scenes where you can pull up a composition and interact with it read+write on a specific field, or on a subtree in chunks, via GraphQL using “simplified” template-specific names + whatever other RM things that are unconstrained/unmentioned by the template. To do that I think a contribution builder approach would be good, where either an existing or new blank COMPOSITONs could be instantiated, read and modified and then, when finished, written back. Can we continue GraqphQL-discussion in that thread?
2 Likes
Would that not require the consumer to have some detailed knowledge about how the RM works ?
Which is one of the things I am trying to avoid…just want a concrete (flattened) representation like the Mindmap or Printable version from the ckm
You could have predefined queries for specific use cases or roles (e.g. what data is useful for research purposes), as @siljelb, @heather.leslie and @ian.mcnicoll have commented in the past
1 Like
I think we all share that the export would need to be usable without detailed knowledge of the rm. But anyways there’s the question of how to handle mandatory and optional datapoints. The mandatory datapoint in archetypes are used sparsely and should also be hard requirements for the exported model (e.g. a diagnosis without the mandatory name makes no sense and shouldn’t be considered a diagnosis). On the other hand archetypes and the inherited rm attributes can be overwhelming. Could be going to a hundred optional data ‘attributes’ that would make a developer overwhelmed I assume.
Templates and/or Graphql could help handle that problem.
4 Likes
This is the big challenge and applies to FHIR and other info models just as for openEHR. You can’t ignore that at some level there is going to have to be some common underlying infrastructure, and enough flexibility on the data models to allow them to be ‘finished’ differently in differing contexts, including the impact of whether you are using SNOMED CT.
So the basic models (archetypes/ resources) simply cannot be locked down at international level. they need to be adaptable and that inevitably means that ‘someone’ has to take the responsibility of applying the maximum degree of ‘interop/coherence’ at a more local level., and hiding the more obscure parts of the models, or indeed the sub-structure where they do not apply to a specific local context. And those decisions are what clinician informaticians need to do
This is where the flattening process can be very helpful, it allows people like me to use tooling to generate simpler structures that both hide parts of the archetype that need not be visible to the dev, and to make those important parts of the substructure that are not in the archetype, visible to the devs. We can probably come up with a best-guess at what these might be for ‘most scenarios’ and would give Gary what he wants . To some extent that is exactly what the Ehrscape composition example API call does - it exposes a few RM end-points that are either mandatory or commonly required e.g. participations, subject.
So yes, I agree to get maximum benefit this needs to work at template-level and fold in the three layers - if you just want a ‘raw archetype’ , just create a very simple template with a basic composition, and an unconstrained e.g Blood pressure archetype - export the Web template and use that to generate what ever downstream artefact you want, ignoring the top-level Composition.
1 Like
Thank you for the kind words about my generator @erik.sundvall . I’ve spent the past few hours writing a generator of OpenAPI schemas.
Here is a separate topic with a download link and source code:
2 Likes
I’m not in favour of obfuscating the archetype/template distinction with exports. I think it doesn’t make sense to offer a very simple template with a basic composition. I think it does however make sense to offer some common usecase e.g. result of a BP measurement as a template (bp observation, result-report composition). And export that as OpenAPI (or json-schema, XML, or webtemplate). But the implementer has to be aware that his implementation has to match the context (actual measured bp of the subject of the ‘ehr’, not e.g. a target bp) of the template, or stuff will go horribly wrong for that patient. It is fine to not constrain out many of the elements in the bp observation archetype, as we’d normally do, and leave that up to the implementer. But mandatory elements should at least stay mandatory (shouldn’t be a problem, BP archetype has none, report-result composition has only very straightforward stuff: e.g. start-time: who would want to record a BP without recording the time of the measurement, that has no value).
This would even be very valuable to many openEHR implementers.
We all don’t think it makes much sense to export only archetypes. Since the implementer will have to supply the context information and this will bring back all the complexity of openEHR. And will realistically never be interoperable with native openEHR. But I also think it’s not up to us to keep people from trying. Maybe they come up with something simpler, better, cheaper, faster than openEHR and I’d be all for that. So we should not block export of archetypes. But realistic, it is not. So I wouldn’t enjoy spending time on helping people, who don’t understand the complexity to do this. And I wouldn’t want to be responsible for contributing to another ehealth related clinical disaster.
2 Likes
Not exactly, what I said assumes that we have already solved how to generate that streamlined format (a data structure which directly uses readable data element names extracted from the archetype/template). The only documentation needed to know what it contains would be approximately the one you find in the CKM:
4 Likes
Yes - Heather, Sebastian and myself worked to create that list of 'clinically-relevant parts of the RM and would be a good candidate ‘defaults’ to be folded into the flattened model, although like Silje I would like to be able to override those defaults for a particular use-cases. We do actually have the tags to be able to do that in AOM2/ADL2 - just nor implemented in AD / .opt yet.
3 Likes
I’m curious for that list.
1 Like
Each CKM archetype and Element has a Reference model tab with a short list of ‘clinical’ RM attributes - a bit arbitrary but probably close enough.
@sebastian.garde - are you able to share the underlying XML file?
1 Like
There are even markers in the RM BMM to indicate which RM attributes are interesting and which really are not - ADL Workbench filters using these and can generate any variant of RM flattening onto a template or archetype. It’s easy to put more classifiers like that in BMMs generally.
2 Likes
They are all template-specific “streamlined” things, I belive TD… = Template Data…
- TDS …Schema (XML schema)
- TDD …Document (xml instances adhering to a TDS)
- TDO …Object(s) (Class definitions, used for simplifying programming applications & integrations)
The template specific “streamlined” OpenAPI descriptions discussed in this thread could be used to produce the equivalent of TDO in any programming language (I believe TDO from the back then was usually in some .NET format)
@heath.frankel is likely the main guru on the topic and was involved in creating TDS/TDD/TDO formats many years ago at Ocean Informatics (now called https://oceanhealthsystems.com/). I believe many of the reasons for their creation were basically the same as the ones @ToStupidForOpenEHR brought up and that started this thread - to make it easier for developers and others to, for a specific use case, integrate/interact with openEHR systems - using familiar tools and without a learing too much about openEHR or openEHR specific tools.
When searching for TDS in the old openEHR mailing list archives you’ll find a lot of the same thoughts as in the current discussion, e.g. in 2008 and 2013. I believe the main problem regarding adoption was that the TDS/TDD approach was never published as an official specification back then - it was used by Ocean and some of their customers (including Better/Marand for example).
In 2016-2017 things had changed and there was a willingness from Ocean to share/publish the approach and create a specification, work was started, see the wiki page https://openehr.atlassian.net/wiki/spaces/spec/pages/30408770/Template+Data+Schema+TDS+Specification+and+associated+Template+Data+Document+TDD but never finished because of peoples’ busy schedules. Heath (who was very busy then) sent me some files that I (also busy) never got around to analyze and publish on that wiki page as a basis for further standardisation work. Perhaps it is time to pick that up again and let anybody interested help documenting the approach? @heath.frankel could you attach any files/descriptions for curious people to look at - on that wikipage or in this thread?
Others may have more information and links about TDS/TDD/TDO, please share. @Seref may know of current use at Ocean.
4 Likes