# Text, descriptions and comments for value set items - mandatory or optional? **Category:** [Clinical](https://discourse.openehr.org/c/clinical/5) **Created:** 2020-05-26 14:55 UTC **Views:** 2240 **Replies:** 40 **URL:** https://discourse.openehr.org/t/text-descriptions-and-comments-for-value-set-items-mandatory-or-optional/728 --- ## Post #1 by @ian.mcnicoll > We need a data type that allows: > > * data element names for all > * descriptions for some, but not all I checked and I was wrong. the Description attribute on a term is mandatory. > * ordering for some, but not all and not always sequential or unique We have that now with DV_ORDINAL and the same will apply to DV_SCALE [quote="heather.leslie, post:11, topic:709"] scores associated with some, but not all [/quote] So we are left with 2 issues, I think. 1. Mandatory descriptions- I suspect will not be possible to make descriptions optional for ordinal terms but mandatory for others. Is there an appetite for making Description optional - in a sense we already do that by adding a dummy '*' . We could then use tooling to add '*' as it does now to most terms but not in the context of Ordinals/scales. That makes me a little bit uncomfortable but only a little!! 2. Not having numerics associated with every item in the ordinal/scale. I know there are use cases but they make me really uneasy. If there is no numeric, what is supposed to be used for e.g 'infinite', or what is the point of the numeric? I think I would prefer to separate any text/coded_text options as perhaps a choice against the Ordinal. Do you have any examples that we can chew over? 3. I just found another example of weirdness - numerics without terms https://academic.oup.com/occmed/article/67/5/404/3975235. We can probably work around that --- ## Post #2 by @ian.mcnicoll Correction - Description is only mandatory in AOM/ADL2 - do we think that should be relaxed? I would probably vote yes and leave it to good practice/tooling to 'help us' to add Descriptions in most cases!! --- ## Post #3 by @heather.leslie [quote="ian.mcnicoll, post:2, topic:728"] do we think that should be relaxed? [/quote] I'm no longer absolutely sure exactly which 'description' we are talking about. But agree in principle that they shouldn't be mandatory and good modelling will result in descriptions where it is appropriate. --- ## Post #4 by @siljelb I think descriptions for DV_CODED_TEXT and maybe even the main text for DV_ORDINAL/DV_SCALE *value set items* should be optional, but for *data elements* they should be mandatory. We often have scores/scales with no descriptions for value set items, and sometimes just a numerical value with no text at all. --- ## Post #5 by @heather.leslie Descriptions wherever possible is good modelling policy, in fact the semantics are often very unclear/unsafe without them. However mandation of descriptions implies you can't save an archetype without a description - not going to happen... --- ## Post #6 by @ian.mcnicoll [quote="heather.leslie, post:5, topic:728, full:true"] Descriptions wherever possible is good modelling policy, in fact the semantics are often very unclear/unsafe without them. However mandation of descriptions implies you can’t save an archetype without a description - not going to happen… [/quote] Totally agree So just to be clear what we are talking about - here is an example from an older version of the Frailty archetype where the description was plit between Descripton and comment. ``` ["at0005"] = < text = <"Very Fit"> description = <"People who are robust, energetic and motivated. These people commonly exercise regularly."> comment = <"They are among the fittest for their age."> > ``` The `text` is carried through into patient data, along with the associated code and value (for an ordinal). It is always mandatory. `description` and `comment `are only carried in the archetype and are useful in tooling and sometimes helpful in UI generation but do not end up in the patient data. An AOM 1.4 they are optional, in fact are not formally defined, but the ADL1.4 document implies that description is mandatory. I sense consensus that description and comment should be optional but 'encouraged' - other than perhaps in Ordinals? I'm not sure if that can be enforced in the specs but there is no reason why it could not just be implemented in tooling e.g when a dv_ordinal valuuset is created the usual dummy description is left blank. Do we have some consensus here? Make description optional? What about optional numeric values in DV_SCALE ? I would say no What about optional' text' as per the BORG examples above - again I would say no. --- ## Post #7 by @siljelb [quote="ian.mcnicoll, post:6, topic:728"] What about optional’ text’ as per the BORG examples above - again I would say no. [/quote] I think there are use cases where DV_ORDINAL/DV_SCALE without the text is warranted. See for example the Pain intensity question of PROMIS-29, here: http://www.healthmeasures.net/administrator/components/com_instruments/uploads/15-09-02_02-16-11_PROMIS-29Profilev2.0InvestigatorVersion.pdf [quote="ian.mcnicoll, post:6, topic:728"] What about optional numeric values in DV_SCALE ? I would say no [/quote] Agree, DV_SCALE or DV_ORDINAL without a numeric value doesn't make much sense. [quote="ian.mcnicoll, post:6, topic:728"] Make description optional? [/quote] I'd say yes, it should be optional. --- ## Post #8 by @bna [quote="ian.mcnicoll, post:6, topic:728"] `description` and `comment ` are only carried in the archetype and are useful in tooling and sometimes helpful in UI generation but do not end up in the patient data. [/quote] I agree. We use the `description`as tooltip in the UI. To let the user read more carefully why to choose the specific item. `Description` might be overriden by the application/UI to give more specific description in the specific use-case. We also see use-cases where the users asks for overriding og the `text` attribute. This _kind of_ makes sense to be more specific about the intention in the use-case. The problem is that this is also stored in the data. This is why we, so far, didn't implement such a feature. --- ## Post #9 by @siljelb [quote="bna, post:8, topic:728"] We also see use-cases where the users asks for overriding og the `text` attribute. This *kind of* makes sense to be more specific about the intention in the use-case. The problem is that this is also stored in the data. This is why we, so far, didn’t implement such a feature. [/quote] It would be interesting to see an example of this! :slight_smile: --- ## Post #10 by @varntzen [quote="bna, post:8, topic:728"] I agree. We use the `description` as tooltip in the UI. To let the user read more carefully why to choose the specific item. `Description` might be overriden by the application/UI to give more specific description in the specific use-case. [/quote] Just remember, those descriptions are not primarly made for end-users, but to reviewers and implementers. :slight_smile: --- ## Post #11 by @bna [quote="varntzen, post:10, topic:728"] Just remember, those descriptions are not primarly made for end-users, but to reviewers and implementers. :slight_smile: [/quote] I don't agree. I think the archetype modelling is great since we have this great possibility to put more information to the end-user about the archetype terms. The `comment` field should be used to contain information for the archetype modellers, but the `description` should be written in a way that might be read by the end user. I look forward to some feedback on this! :-) --- ## Post #12 by @vanessap Currently on Better we show by default the "description" from the archetype as a tool-tip to the user on the front end and in many cases it's very useful. It can be overwritten by other text to be shown on frontend, but this does not go to ehr server when creating a composition. On the comment's section of the archetype, I only see it on modelling tools and I agree with @bna that this should be considered as an advice content to the modeller and not shown by default to the end user. --- ## Post #13 by @heather.leslie [quote="ian.mcnicoll, post:6, topic:728"] What about optional numeric values in DV_SCALE ? I would say no [/quote] You provided an example where there were only some values and others left open - https://academic.oup.com/occmed/article/67/5/404/3975235. I've seen other examples and we should also be able to cater for these. --- ## Post #14 by @siljelb I see some items with values but no text, but no items with no values, in that example? --- ## Post #15 by @ian.mcnicoll [quote="siljelb, post:7, topic:728"] See for example the Pain intensity question of PROMIS-29, here: [/quote] Hmmm- I would model this just as as a DV_COUNT, I think --- ## Post #16 by @siljelb [quote="ian.mcnicoll, post:15, topic:728"] Hmmm- I would model this just as as a DV_COUNT, I think [/quote] Maybe, but there's the issue of the first and last values having labels. :woman_shrugging: --- ## Post #17 by @siljelb To try and sum up the discussion from my own understanding: * All value set items, whether in DV_ORDINAL/DV_SCALE or DV_CODED_TEXT data types, should have the possibility of adding `text`, `description` and `comment` text fields to them. * `text` should be mandatory for DV_CODED_TEXT, but optional (though strongly recommended) for DV_ORDINAL/DV_SCALE. The reason why it should be optional for the latter two is to accommodate scales like Borg Scale, which has some items with a numerical value but no text. * `description` should always be optional. A lot of scales only have a short text label for each item, and no description. The alternative is to leave the description empty, which makes less sense. * `comment` should always be optional, and would probably only be used where the value set items contain examples. --- ## Post #18 by @ian.mcnicoll [quote="siljelb, post:17, topic:728"] `text` should be mandatory for DV_CODED_TEXT, but optional (though strongly recommended) for DV_ORDINAL/DV_SCALE. The reason why it should be optional for the latter two is to accommodate scales like Borg Scale, which has some items with a numerical value but no text. [/quote] This is the only one that makes me uncomfortable., otherwise agree. I think I would prefer to fill the gaps, where it makes sense or model as DV_COUNT where as in one of the scales it is only 0 and 10 that have text labels. I know we want to replicate the scales as they were designed as far as possible but very often they do not take account of transfer to IT systems, or the data being visualised outside the context of the full form. --- ## Post #19 by @siljelb [quote="ian.mcnicoll, post:18, topic:728"] This is the only one that makes me uncomfortable., otherwise agree. I think I would prefer to fill the gaps, where it makes sense or model as DV_COUNT where as in one of the scales it is only 0 and 10 that have text labels. [/quote] I can empathise with the unease, but I don't see how we can reasonably fill the gaps. For example for the Borg CR10 scale, which text would you assign to the numeric value '8'? "More severe than 'very severe', but less severe than 'very, very severe (almost maximal)'"? Modelling things like the pain intensity scale of the PROMIS-29 as a DV_COUNT would IMO lead to loss of even more context. --- ## Post #20 by @ian.mcnicoll My clinical safety head would be doing something like 8 Very severe 9 Very severe + 10 Very, very severe 11 Very, very severe + It's a hack, I accept but just leaving 'random scores blank just feels risky. PROMIS-29 Pain scale. ![image|690x195](upload://7rdaRY7pTEvhMFhde4LacfYvtrM.png) For me this is a 'junk score' it is a typical VAS that happens to have the normal guidance '0 means no pain vs. 10 = the worst you can imagine. It is not a scale at all in my book and there is nothing in here that is PROMIS-29 specific. --- ## Post #21 by @ian.mcnicoll ![image|498x101](upload://zDRrykilotnoNwQrfLmpn2vOr0r.png) --- ## Post #22 by @varntzen [quote="bna, post:11, topic:728"] the `description` should be written in a way that might be read by the end user. [/quote] [quote="vanessap, post:12, topic:728"] show by default the “description” from the archetype as a tool-tip to the user [/quote] Agree, "Description" *can* be used that way, but not always., They definately can, if the archetypes are spesific for one purpose, or made for local use. We're reluctant to make the published archetypes into text-book-like instructions on how to use or interpret the various elements in, for example a scale or score. Both because it's not the task of the modelleres to teach end-users clinical knowledge, but also because this opens for discussions on the concept (or scale/score) itself. We try to be neutral and only define as good as possible WHAT the element is, and not as much HOW it to be used in a clinical setting. Otherwise we might introduce possible erronous use or interpretation, causing medical harm. --- ## Post #23 by @ian.mcnicoll In this case I regard these as UI guidance - if 80% of the items have no associated text, that is not a scale IMHO of course :face_with_monocle: --- ## Post #24 by @ian.mcnicoll That's a reasonable approach. Templating with ADL2 will make this easier as we can create template-level codes with associated 'local descriptions and comments where the underlying archetype descriptions are not fit for use as user-tool-tips --- ## Post #25 by @heather.leslie This worries me. As modellers we have a responsibility to be so careful - to be faithful to the original intent as much as we can, flawed though it may well be. If we make unilateral assumptions, interpretations, best guesses or 'fudges', we start to create a divergence that can potentially become amplified as a clinical safety issue in implementation. --- ## Post #26 by @ian.mcnicoll That's a very fair point , and as a principle I'd agree but I'd also argue that there are situations where a scale/score designed on a paper form (often rather badly) does not safely transfer to digital implementation without some tweaking. I agree we should not do that lightly or randomly but nor do I think we need to replicate something developed for paper often as an academic exercise with very limited real-world use, which will have been tweaked in the world as people have tried to implement it. We have seen that already with GCS, possibly one of the best and least contentious scores. It does not translate safely into non-paper use without some tweaking. Interesting but important philosophical discussion. Practically speaking it may be difficult to drop the mandatory text requirement without causing quality issues elsewhere but I'll take it back to SEC. At worst we could just use a space character. I'm actually more concerned about allowing scale items without a value - do you have some real exapmles we can look at. The only one I know of is the 'Spinal Tap - turn it up to 11' Borg CR10 scale **![|503px;x326px;](upload://is2l7pFBag0Wl5CzPLw7SWd1Qyi.png)** I would model that as an Ordinal/Coded_Text choice, although actually it is nonsense IMO. --- ## Post #27 by @linforest Positive. :+1: Maybe we need a reference standard (e.g., LOINC, CIMI) for domain modelling. LOINC Answer List Example LOINC LL3509-8 — UPDRS_Intellectual impairment / Answers: 5; Scale: Ord; Code: 0-4; Score: 0-4 https://loinc.org/LL3509-8/ --- ## Post #28 by @ian.mcnicoll THat is a slightly weird mix of LOINC and SNOMED noInteresting via the LOINC definition I found this for the Borg scale (that has missing text in the original). https://cde.nlm.nih.gov/deView?tinyId=T96cTBoIo ![image|399x500](upload://jpLZTKgyaMhYgTD5QsCGvOx8ial.png) versus the LOINC version that uses blank text https://loinc.org/64113-4/ and Silje's example https://loinc.org/LL2234-4/ Looks like I have supporters but not in LOINC!! --- ## Post #29 by @ian.mcnicoll and just for fun, here is the SNOMED CT approach (supports me!!). ![image|690x414](upload://oAFRBuWvbrAsuBseiNmAGNKLQUT.png) --- ## Post #30 by @linforest SCT FSNs are more descriptive --- ## Post #31 by @linforest [quote="ian.mcnicoll, post:28, topic:728"] Looks like I have supporters but not in LOINC!! [/quote] Requests for improvement could be submitted to LOINC Committee if you'd like to contribute. --- ## Post #32 by @thomas.beale [quote="siljelb, post:17, topic:728"] `text` should be mandatory for DV_CODED_TEXT, but optional (though strongly recommended) for DV_ORDINAL/DV_SCALE. The reason why it should be optional for the latter two is to accommodate scales like Borg Scale, which has some items with a numerical value but no text. [/quote] Need to be a bit careful here. DV_ORDINAL & DV_SCALE have a `symbol` field of type `DV_CODED_TEXT`, which has no 'description', only a `value` field (as you are used to). [Spec link here](https://specifications.openehr.org/releases/RM/latest/data_types.html#_quantity_package). Coded entities, i.e. object nodes and value-set values (= id-codes and at-codes + ac-codes in ADL2) are all a generic `ARCHETYPE_TERM`, consisting of at least `code`, `text`, and `description` fields, and any others you want to add. [Spec link here](https://specifications.openehr.org/releases/AM/latest/AOM2.html#_terminology_package). The model of the symbol field of a DV_ORDINAL or DV_SCALE is of the first type - they are coding actual runtime data values (e.g. 'not present' | '< 100 bpm' | '>= 100 bpm' or '+' | '++' | '+++' etc). The id-codes used on the ELEMENTs of the various score items (a la Apgar, Barthel etc) are of the second type - i.e. they are naming what the model items are (e.g. heartbeat, muscle tone, ...). So those ARCHETYPE_TERMs are our simple model of terminology as it exists in archetypes and templates, used for identifying parts of the archetype, and also defining value set items. We could in theory make 'description' field optional without breaking runtime data, but it would probably break most Archetype modelling tools. I'd be more inclined to keep it mandatory, and have it set by the tool to some automatic string, where the modeller doesn't want to fill it out. In the simplest case, an empty string (always guaranteed to cause confusion later on) or better, some machine-processible string like '[=text]' or whatever you really need there. --- ## Post #33 by @ian.mcnicoll I think we are clear that description only relates to the term inside the ontology section of the archetype/template, and does not appear in the patient instance data. Why should making it optional cause issues for tooling vendors? Right now, what happens is that when a new term is created a 'dummy' description is generated as "*". All that needs to happen is for that to change to an empty string and for any validations on description to be relaxed. Clearly there will need to be a bit of coordination esp between AD and CKM but that is just about timing of relaxing the constraint. @sebastian.garde @borut.fabjan @yampeku - what do you think? Managing these descriptions is a particular overhead for translations and certainly in some cases they are redundant. --- ## Post #34 by @yampeku I'm pretty sure this change wouldn't affect us. We allow empty text and have some logic defined to visualize these archetype nodes even if they have empty (or no) text or descriptions (showing type at least) --- ## Post #35 by @heather.leslie [quote="linforest, post:27, topic:728"] Maybe we need a reference standard (e.g., LOINC, CIMI) for domain modelling. [/quote] We usually try to model the archetype based on the original research as the source of truth, where possible. And we usually do look at the terminology representation to confirm alignment or as a means to clarify where required. However they often have the same problem - that they need to compromise it to represent it within their structure/display constraints a bit, and we run the risk of propagating the compromise as truth. It's a tension that we are always try to balance... but if we do 'fudge' it, we try to document it so that others are aware. --- ## Post #36 by @sebastian.garde *description* is expected to be there according to 1.4 and 2.0 specs. In 1.4 this is hidden in the text: "For any term or constraint definition, this list must at least include the name/value pairs for the names "text" and "description". In 2.0 it has been modelled more explicitly. From my point of view, it is reasonable to relax this but I can also live with the "*" cludge/workaround. If and when this is relaxed in the specs, we need to look into it for CKM to ensure this works everywhere, including displays, translations, conversions to xml and adl2,.... I don't suspect major issues, but there will be places where this is checked which would need to be relaxed and where we then need to ensure it is not relied upon. --- ## Post #37 by @thomas.beale [quote="ian.mcnicoll, post:33, topic:728"] Why should making it optional cause issues for tooling vendors? Right now, what happens is that when a new term is created a ‘dummy’ description is generated as “*”. [/quote] Well in any software, if the spec says a property is mandatory, implementers work on that assumption - that attribute can't be void/null. If you later make it optional, any software that followed the previous version of the spec will either keep working (if it creates default values, empty strings etc) or it will break. [quote="ian.mcnicoll, post:33, topic:728"] All that needs to happen is for that to change to an empty string and for any validations on description to be relaxed. [/quote] An empty string is not an 'optional' attribute, formally. An 'optional' attribute is one that can be null at runtime. An empty string is just a particular value of the String type. NB: I'm not saying that moving to optional `description` will break tools badly; they would probably be fairly easy to update. But there are always unexpected knock-on effects with these kinds of changes. We just need to be careful. I would suggest a careful examination of the requirements, and decide whether you really want `description` and maybe other fields to be optional, or if you want them to be mandatory, but defaulted to specific values e.g. empty string etc, in specific circumstances. --- ## Post #38 by @pieterbos There is nothing in the ADL/AOM 2 standard preventing you from setting it to an empty string, so that's already very possible, just the field is mandatory. This clearly has some benefits, in the sense that sometimes there just is no description. It also has some drawbacks, in the sense that this being mandatory forces people into thinking about adding more information to the archetypes wherever possible, and that it is a relatively costly change, because tools everywhere expect this field to be non-null, and tools that have not been updated will then just not work with the newer archetypes. I have no idea what will break in our software - changing this affects the OPT 2 standard as well, so if this is changed we will probably set it to a default value in the OPT 2 generator wherever it is missing, to not have to fix this everywhere in our code, including form rendering, in the CDR and in applications. We do also show descriptions in our UI, usually behind a tiny icon users can click on. --- ## Post #39 by @yampeku [quote="sebastian.garde, post:36, topic:728"] *description* is expected to be there according to 1.4 and 2.0 specs. In 1.4 this is hidden in the text: "For any term or constraint definition, this list must at least include the name/value pairs for the names “text” and “description”. In 2.0 it has been modelled more explicitly. [/quote] I think that definition means that keys must exist, but says nothing about content (can be empty?) --- ## Post #40 by @ian.mcnicoll So I guess that might be the easiest compromise - keep Description as mandatory but allow empty strings? I have a feeling that AD behaviour has already changed!! @sebastian.garde will that be easy to support in CKM? --- ## Post #41 by @sebastian.garde [quote="yampeku, post:39, topic:728"] think that definition means that keys must exist, but says nothing about content (can be empty?) [/quote] That is my interpretation as well, yes. --- **Canonical:** https://discourse.openehr.org/t/text-descriptions-and-comments-for-value-set-items-mandatory-or-optional/728 **Original content:** https://discourse.openehr.org/t/text-descriptions-and-comments-for-value-set-items-mandatory-or-optional/728