As described in CKM CR-1001 I’d like to have the option to record “episodic” (opener::451) compositions for the COMPOSITION.care_plan archetype.
As @sebastian.garde pointed out in the CR, there’s probably also a use case for “persistent” compositions for this archetype, and no expected use for “event” or “report”, it was suggested to add a second option to the category in the archetype.
I used the following syntax to achieve that:
Now this isn’t supported by Archetype Designer: there’s no UI option to add this 2nd option, manually editing apparently doesn’t save (but no error, validation or otherwise). @borut.fabjan fyi.
Do we as clinical modellers agree on the design pattern of constraining composition.category to only all the sensible options?
And do we accept this change, given it will result in issues in tooling and application implementations? e.g. making the archetype unsafe to edit in AD.
Is this legal adl1.4?
And is the following a correct conversion to adl2 (used VSCODE plugin, which uses Archie)? @pieterbos
definition
COMPOSITION[id1] matches { -- Care plan
category matches {
DV_CODED_TEXT[id9003] matches {
defining_code matches {[ac9002]} -- Care plan (synthesised)
}
}
...
}
terminology
term_definitions = <
["en"] = <
["at9000"] = <
text = <"persistent">
description = <"persistent">
>
["at9001"] = <
text = <"Term binding for [openehr::451], translation not known in ADL 1.4 -> ADL 2 converter">
description = <"Term binding for [openehr::451], translation not known in ADL 1.4 -> ADL 2 converter">
>
...
>
>
term_bindings = <
["openehr"] = <
["at9000"] = <http://openehr.org/id/431>
["at9001"] = <http://openehr.org/id/451>
>
>
value_sets = <
["ac9002"] = <
id = <"ac9002">
members = <"at9000", "at9001">
>
>
I do believe your analysis is correct and would be supported in ADL1.4 without an issue. Basically, AD needs to change current radio buttons to checkboxes, and allow multiple category codes to be constrained.
However, we would also need those to be further constrainable at template-level
My own feeling, is that new compositions should not have Category constrained in any way and I might even support an approach where archetypes are left unconstrained at all, with decisions on category left to template level.
(The old vs new revision comparison report in CKM could be a little bit more verbose - listing not only the code 451, but also the rubric episodic.)
I would agree with Ian to the extent that it is probably rare that you want to constrain this at all on archetype level. This however seems to be a good use case for at least considering it. Proper tooling support would of course be essential.
Whether you leave it completely unconstrained or only have 2/4 options available in the archetype, you need the ability to constrain this further (usually to one option only) in templates either way?
We still need changes in AD as we need to tidy up existing archetypes that are constrained to a single category (and to allow further template-level constraints)
The category is mandatory in the specs. Usually this is enforced in the archetype eg by a radio button in the UI of AD.
In this situation, however, the proposal is that the archetype supports more than one option for the mandated category eg as checkbox/es. As far as I can see, this will require some validation in the template tooling and supported in CKM to ensure that only one category option is valid per template.
The validation will be at commit time for data, bit nescessarily for model (archetypes nor templates). I can be done by the client app that commits the data to CDR. At least in adl2. @sebastian.garde could you confirm.
Off course usually it makes sense to do it at template time at the latest. But I think it’s fine to leave this responsibility to anyone implementing templates/client app.
Anything against removing the category constraint? It works ok in AD. (Just as UI visualisation shows ‘event’ instead of ‘unconstrained’). Or what editorial guideline would you prefer @heather.leslie, unconstrained in archetypes or sensible options only? I’m fine with either. @sebastian.garde could you please verify unconstrained category archetype works in CKM?
As a modeller, I’d prefer that the template be explicitly constrained as part of my design process. Given that it is mandatory, I don’t understand how it can be left unconstrained in a template.
This issue is just another issue to be addressed in the ongoing discussion about how to expose RM attributes in the tooling to the modellers, it is another aspect of their dataset design and is potentially important part of the documentation fo accurate semantics to be conveyed to a remote implementer.
Theoretically, the category (and any other optional RM or attribute options) should be able to be reviewed at the template and/or form stage.
I don’t think this is different in 1.4, so yes technically this is not so different to a mandatory diagnosis name element in a diagnosis archetype.
CKM has no issue with leaving this unconstrained.
As Heather says, it is a mandatory. The latest point of validation is at commit time for the data.
If you want to leave it open in a template or have 2/4 options available in the template and the final choice is at commit time of actual data, I don’t see anything from a specifications point of view that is forbidding you from doing so. Of course any tooling should make this easy to do, if this is common. And at runtime ensure that data to be committed contains this.
However, if it is not constrained to exactly one option in the template, someone/something will need to make this choice later:
If it is someone, they’d need to know what they are doing at runtime - and the question is if that is a reasonable expectation.
If it is something (an app), that app would need to be designed that way and then the question is what you have gained by not setting it in the template in the first place.
Given that, in summary from my point of view (only):
From a specs point: no problem that I can see to leave it unconstrained until actual data is committed.
However, in terms of practical guidance I would usually/typically expect this to be
– not constrained at archetype level (unless the purpose of the archetype means that some of the options are nonsensical)
– constrained to exactly one option at template level.
We should not talk in terms of being mandatory or not in the RM. There are many attributes that are mandatory and that can only have a value in runtime. Or we have the case of EVENT in the OBSERVATIONS, usually left undefined, to be used as a POINT_EVENT or an INTERVAL_EVENT when data is registered.
So, it should only depend on the use case. Some templates might require to have that attribute completely constrained, to fulfill its semantic definition. Other templates might not, and that could be selected in runtime. Being an attribute of the COMPOSITION, probably the first case will be the most common, but I never liked that tools take decisions on behalf of the modelers, in one way (forcing to constrain that COMPOSITION.category) or the other (not allowing leaving it unconstrained).
It can - it just has to be set in the data. But of course it would be pretty normally to just set it in the template anyway, and reduce data entry at runtime…
From reading this thread it seems to me what @joostholslag and maybe others want to really achieve is to prevent the category from being something wrong. I.e. you would consider persistent or episodic to be ok, but not event. So a constraint could even make sense in an archetype if everyone agreed on some codes that should never be used for certain content types.
