# Addition of required / extensible / preferred / example terminology constraint to AOM and ADL **Category:** [ADL](https://discourse.openehr.org/c/adl/40) **Created:** 2020-08-19 10:26 UTC **Views:** 2010 **Replies:** 21 **URL:** https://discourse.openehr.org/t/addition-of-required-extensible-preferred-example-terminology-constraint-to-aom-and-adl/933 --- ## Post #1 by @thomas.beale The openEHR SEC has decided on the addition of the `required | extensible | preferred | example` 'binding strength' constraint modifier, following the [model used in HL7 FHIR](https://www.hl7.org/fhir/terminologies.html#strength). The change is documented in [openEHR CR SPECAM-68](https://openehr.atlassian.net/browse/SPECAM-68). The change to AOM2 spec looks like this in the UML: ![C_terminology_code|510x368](upload://eEE8mkQJzEUX5MvWPJFxAMeZWuM.png) We have yet to determine how it should look in ADL2. Currently, the various forms of terminology constraint look as follows in ADL2. ``` ​items matches { ​ELEMENT[id11] occurrences matches {0..1} matches { ​name matches { ​DV_CODED_TEXT[id8] matches { ​defining_code matches {[at5]} -- set name to 'Substance' ​} ​} ​value matches { ​DV_CODED_TEXT[id55] matches { ​defining_code matches {[ac1]} -- Type of Substance/Agent ​} ​} ​} ​ELEMENT[id22] occurrences matches {0..1} matches { -- Certainty ​value matches { ​DV_CODED_TEXT[id58] matches { ​defining_code matches {[ac2; at23]} ​} ​} ​} ​... ``` In the above, what appears within the leaf-level `{}` corresponds to the constraint type `C_TERMINOLOGY_CODE`, i.e. `[at5]`, `[ac1]`, and `[ac2; at23]`. We now need a way to modify this constraint to represent the addition of binding strength. Note: the lack of any binding strength constraint is understood to mean 'required', i.e. all coded term constraints in today's archetypes have a strength of 'required'. Possibilities could be: * include a strength keyword inside the brackets, e.g. `[at5 (preferred)]`, `[at5 | preferred]` * include a strength keyword outside the brackets, e.g. `preferred:[at5]`, `extensible:[ac1]` etc. * something else I will probably propose the second option as the default approach. The above example would become, with the addition of constraint strengths done this way: ``` ​items matches { ​ELEMENT[id11] occurrences matches {0..1} matches { ​name matches { ​DV_CODED_TEXT[id8] matches { ​defining_code matches {required:[at5]} -- set name to 'Substance' ​} ​} ​value matches { ​DV_CODED_TEXT[id55] matches { ​defining_code matches {example:[ac1]} -- Type of Substance/Agent ​} ​} ​} ​ELEMENT[id22] occurrences matches {0..1} matches { -- Certainty ​value matches { ​DV_CODED_TEXT[id58] matches { ​defining_code matches {preferred:[ac2; at23]} ​} ​} ​} ​... ``` This seems pretty readable. There may be better ideas around, so we are interested in any ideas from ADL users, tool-builders etc. --- ## Post #2 by @siljelb No opinion about what it should look like in ADL2, but I'd like to express a general HUZZAH! :partying_face: This will make modelling much more flexible, and save us from the ugly DV_CODED_TEXT+DV_TEXT hack. Good work! :D :+1:t2: --- ## Post #3 by @damoca May I suggest something similar to the syntax also used in FHIR? ! Required + Extensible ? Preferred ?? Example Something like: `defining_code matches {[ac1]!}` `defining_code matches {[ac1]+}` `defining_code matches {[ac1]?}` `defining_code matches {[ac1]??}` --- ## Post #4 by @siljelb This is terse which is good, but it's also not very readable. Reminds me of some perl scripts I've had the misfortune of trying to decode. I'm ambivalent. :sweat_smile: --- ## Post #5 by @thomas.beale You said 'some'. I want to see the other Perl scripts, you know, the readable and maintainable ones ;) --- ## Post #6 by @thomas.beale Ok team, question on the real meaning of `extensible`, `preferred` and `example`: it seems to me that `extensible` has to mean that the supplied code, if not from the value-set in the constraint, is at least from the same terminology, but for `preferred`, it seems to me it can be from anywhere. This is not stated like this in FHIR, but I can't see how it makes sense otherwise, to distinguish `extensible` and `preferred` - the word 'extensible' would not mean what it says. thoughts? --- ## Post #7 by @sebastian.garde I struggle with the distinction between *extensible* and *preferred* as well, but it feels acceptable to me that an extensible (say international) value set is extended with e.g. local codes from a different . (Plus, the value set could use codes from more than one terminology already.) *extensible* just means (to me) that you SHALL only extend the value set if the existing codes in it don't fit. *preferred* means you are allowed to replace the whole thing with something different if - say - your local jurisdiction mandates for example the usages a completely different terminology. --- ## Post #8 by @bna Seems logical to me. Preferred doesn't have any semantic meaning except being preferred. You might use whatever you like if you don't prefer the suggestion. As such it has a very low semantic constraint on the model. --- ## Post #9 by @thomas.beale I sometimes feel it is better to discuss these constraint strengths less, since every time we do, I think what a bad idea they are ;) But you are probably both right. I'll do it like that. --- ## Post #10 by @thomas.beale Another question: if we have constraints like: ``` items matches { ELEMENT[id11] occurrences matches {0..1} matches { name matches { DV_CODED_TEXT[id8] matches { defining_code matches {preferred [ac1]} -- prefer ac1 codes } DV_TEXT[id9] -- or plain text } ``` then what are the rules for specialising that terminology constraint? Can a weaker 'soft' constraint be specialised into a stronger one, but not the other way around? I.e. you could specialise the `id8` node into `extensible` or `required`? (This would be the a priori approach in ADL - constraint narrowing down the specialisation lineage). Similarly ... for *adding* new alternative `DV_CODED_TEXT` nodes, should new siblings in specialised children be limited to only *higher* strengths? I.e. if you create a `required DV_CODED_TEXT`, you can't weaken that by adding any other `DV_CODED_TEXT`, but if it were a `preferred DV_CODED_TEXT`, you could add an `extensible` or `required` one in a child archetype? @pieterbos - this is getting into the new validity rule(s) we are thinking of - see what you think. --- ## Post #11 by @ian.mcnicoll These are the current FHIR definitions - I think they are fine. It does allow extensible valuesets to be extended with a different terminology, as long as that does not conflict with an existing code. It also allows for free text, which we are proposing to handle a little differently. This is not about pure semantics, it is about negotiated conformance. but I agree that it should not be possible for a specialisation to weaken the level of binding. However, I don't think we should try to enforce this in validation (even if we could) , just make the normal 'rules of the road' clear. All codes from system [ `http://hl7.org/fhir/binding-strength` ](http://hl7.org/fhir/R4/codesystem-binding-strength.html) |**Code**|**Display**|**Definition**| | --- | --- | --- | |[required](http://hl7.org/fhir/R4/codesystem-binding-strength.html#binding-strength-required)|Required|To be conformant, the concept in this element SHALL be from the specified value set.| |[extensible](http://hl7.org/fhir/R4/codesystem-binding-strength.html#binding-strength-extensible)|Extensible|To be conformant, the concept in this element SHALL be from the specified value set if any of the codes within the value set can apply to the concept being communicated. If the value set does not cover the concept (based on human review), alternate codings (or, data type allowing, text) may be included instead.| |[preferred](http://hl7.org/fhir/R4/codesystem-binding-strength.html#binding-strength-preferred)|Preferred|Instances are encouraged to draw from the specified codes for interoperability purposes but are not required to do so to be considered conformant.| |[example](http://hl7.org/fhir/R4/codesystem-binding-strength.html#binding-strength-example)|Example|Instances are not expected or even encouraged to draw from the specified value set. The value set merely provides examples of the types of concepts intended to be included.| --- ## Post #12 by @thomas.beale [quote="ian.mcnicoll, post:11, topic:933"] However, I don’t think we should try to enforce this in validation (even if we could) , just make the normal ‘rules of the road’ clear. [/quote] Well, anything but `required` will be treated the same as a constraint that simply says this node is a Coded term of some sort, but nothing more. The constraint specification for these case will be ignored by any archetype / data processor implementing ADL/AOM. If some higher level validator / checker wants to do something, that's fine but it's outside ADL scope. --- ## Post #13 by @ian.mcnicoll From a tooling POV is it not the other way around? The current default for an internal codeList is that it is non-extensible. 'required' is the current default. The special handling is when the modeller loosens the constraint and this can be used to advise tooling. But I think I understand re out of AOM/ADL scope. I'm fine with that. --- ## Post #14 by @yampeku We can decide the default semantics we want. Not specifying a constraint usually means "whatever rm says". In this case, probably current behaviour (i.e. Required) should be the default so we don't break anything --- ## Post #15 by @thomas.beale [quote="ian.mcnicoll, post:13, topic:933"] From a tooling POV is it not the other way around? [/quote] If my statement was unclear, I meant: `required` is the default; for any other strength, any value-set or value (ac-code or at-code) that is set in the constraint is just ignored, so this is the same as if the constraint just said: this node has to be a terminology code, with no constraint at all on the value. Anyone disagree with that? --- ## Post #16 by @wouterzanen I have recently stumbled upon a new HL7 FHIR addition, to be able to better differntiate in binding strength, by adding additional value set that can have different puposes to the base valueset: |[maximum](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-maximum)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Maximum Binding|A required binding, for use when the binding strength is 'extensible' or 'preferred'| | --- | --- | --- | --- | |[minimum](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-minimum)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Minimum Binding|The minimum allowable value set - any conformant system SHALL support all these codes| |[required](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-required)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Required Binding|This value set is used as a required binding (in addition to the base binding (not a replacement), usually in a particular usage context)| |[extensible](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-extensible)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Conformance Binding|This value set is used as an extensible binding (in addition to the base binding (not a replacement), usually in a particular usage context)| |[candidate](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-candidate)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Candidate Binding|This value set is a candidate to substitute for the overall conformance value set in some situations; usually these are defined in the documentation| |[current](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-current)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Current Binding|New records are required to use this value set, but legacy records may use other codes. The definition of 'new record' is difficult, since systems often create new records based on pre-existing data. Usually 'current' bindings are mandated by an external authority that makes clear rules around this| |[preferred](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-preferred)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Preferred Binding|This is the value set that is preferred in a given context (documentation should explain why)| |[ui](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-ui)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|UI Suggested Binding|This value set is provided for user look up in a given context. Typically, these valuesets only include a subset of codes relevant for input in a context| |[starter](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-starter)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Starter Binding|This value set is a good set of codes to start with when designing your system| |[component](https://build.fhir.org/codesystem-additional-binding-purpose.html#additional-binding-purpose-component)|http://hl7.org/fhir/CodeSystem/additional-binding-purpose|Component Binding|This value set is a component of the base value set. Usually this is called out so that documentation can be written about a portion of the value set| see: https://build.fhir.org/valueset-additional-binding-purpose.html It is still only a nightly build, but I think it solves some of the weaknesses of the extensible binding in creating some possibilities to constrain extensibility as well as add more differntiation for use cases (e.g. in templates). I think this could be very usefull for openEHR as well. --- ## Post #17 by @thomas.beale I knew this would happen... well, the original classification of 4 is not systematic, and neither is the new one... --- ## Post #18 by @pablo I'm totally ignorant about this area, so I'll ask: is there anything to represent "not extensible"? `extensible` seems to indicate a property a code could have, so if it could have it, it could also NOT have it, if that is the case, how can that be expressed? In the case of `required` and `preferred` since those seem to be boolean, the absence of those might read as NOT, but it's not clear on the case of `extensible`. --- ## Post #19 by @wouterzanen You are right afcourse but would be a good idea to think this through. It is a "hot" topic here at Nictiz right now. --- ## Post #20 by @wouterzanen I don't eactly understand your question. Required would be the only not extensible binding Extensible, preferred and example can all be extended. --- ## Post #21 by @thomas.beale [quote="pablo, post:18, topic:933"] is there anything to represent “not extensible”? [/quote] These are not flags but classifiers. Here are the [FHIR definitions](https://www.hl7.org/fhir/terminologies.html#strength) (which we assume in openEHR). --- ## Post #22 by @pablo I get it, `extensible` is what is User Defined Tables in HL7 v2.x vs. HL7 Defined Tables, which were two ways of expressing internal terminologies in HL7 v2.x messages. In some cases of User Defined Tables, HL7 v2.x specs actually provide a subset or sample table, for others the codes are 100% to be defined by the user. --- **Canonical:** https://discourse.openehr.org/t/addition-of-required-extensible-preferred-example-terminology-constraint-to-aom-and-adl/933 **Original content:** https://discourse.openehr.org/t/addition-of-required-extensible-preferred-example-terminology-constraint-to-aom-and-adl/933