All,
the next beta of the archetype workbench, which is progressively implementing all of ADL 1.5 will include ‘annotations’, which is a feature enabling a set of comments to be created on a per-node level in an archetype. The raw ADL appearance of this is typified by the following two test archetypes (go to the bottom): http://www.openehr.org/svn/knowledge2/TRUNK/archetypes/ADL_1.5_test/validity/annotations/
For a given node (i.e. path) and a given language in an archetype or template, the annotations are a set of name-value pairs (technically a Hash of Strings, with String keys). This means you might have the following on some node in an archetype (keys in italics, values to the right):
-
clinical justification: “see xyz examination protocol, at http://medline.org/some/ref.html”
-
data type: “free text with optional preferred coding”
On a template, we would expect the annotations to be more local, e.g.: -
NHS data dictionary: “See doc xxxxx, ref yyyyy”
-
Terminology: “constrained according to NHS ED 4h protocol”
Of course we don’t know exactly how things will turn out, so we need to see some experimentation in the real world.
REQUIREMENTS QUESTIONS - please provide feedback:
-
BASIC REPRESENTATION: all annotations are (unicode) String values with (unicode) String keys,
-
this allows any string, including in script languages like Farsi, Hindi, Chinese etc
-
Q1: is such a structure powerful enough? It might be argued that the keys should be internal codes, i.e. at-codes, or external coded concepts, e.g. SNOMED codes.- PERSISTENCE: where do annotations get recorded?
-
if annotations are regarded as an intrinsic part of an archetype, they are recorded in the archetype: this is what we have currently implemented
-
if annotations are regarded as intrinsically part of the local use environment, then they would be persisted as some adjunct artefact that references an archetype, or else in specialised archetypes/templates, even if no other constraints are added to the archetype proper; we have currently assumed the latter.
-
Q2: if both are assumed, then some rules for a) translations and b) merging are required; SEE BELOW
-
LANGUAGE annotations groups (i.e. set of key, value) on a per-language basis, i.e. ‘en’ annotations separated from ‘es’ from ‘cz’ etc in the usual way
-
Q3: this means that for a given archetype, there is a choice with respect to translations:
-
force translation of all annotations to all languages available for this archetype: this is probably reasonable for international archetypes on CKM, since any such annotations must presumably be relevant no matter what language
-
for any given archetype, within a specific use context, allow just the annotations in the local language to exist? This appears to be reasonable, since just because a CKM archetype had a Swedish translation doesn’t mean your local users in Beijing should translate their annotations to Swedish…
-
If the answer to Q2 is that a mixture is allowed, then we should allow both of above possibilities for translation, and we assume that any local translations are within local archetypes / templates. I.e. you can’t add annotations outside of an archetype or template.- TAG VALUES: should keys be standardised in some way? Currently, we implemented just Strings. The answer depends on our notion of how interoperable annotations should be.
-
Q4: Requirements possibilities:
-
no standardisation (what has currently been assumed)
-
international standardisation only - i.e. only CKM archetypes would have standardised tags; this can be supported with the ‘no standardisation’ option as well, since centralised/standardised tooling could ensure standard tag sets.
-
standardisation at a national level, perhaps in concert (one day) with IHTSDO, and using the Snomed CT ‘national extension’ as a place to do it
-
standardisation within ‘families’ of archetypes. This does not seem so likely, since many tags should be standard across most archetypes developed by a particular programme.
-
Technical options:
-
Q5: make them internal coded terms instead, allowing tools to more easily control which sets of keys are used in a particular place.
-
Q6: but this still doesn’t force any standard set of key values across a group of archetypes, e.g. as created within a single government national repository. Doing that might be an argument to use SNOMED codes from the local extension. Assuming everyone agrees that they will use SNOMED!
-
MERGING: annotations on a given node are keyed by the path to that node in the archetype or template. Currently, annotations in a specialised node in a specialised archetype are treated as distinct, and the annotations are not merged.
-
Q7: it could be argued that in the ‘flat’ form of an archetype or template (including the operational template), the annotations from all specialised versions of the same node should be merged, rather than just keeping the annotations (if any) from the proximal archetype in use.
-
if merging is to be used, how to do it? If the same keys are encountered, do we simply append the string values for a given key? Or use some more sophisticated generation of key values a bit like at-codes, whose depth can always be known. E.g. a key “terminology” might be converted to the key “terminology.1” and “terminology.1.1”. This seems clunky, and might be an argument for making all keys at-coded terms, so that the keys are just normal at-codes like at0001, at0001.1 etc, and obey all the usual rules of these codes, which are already established
-
slight variation: make a new annotations-specific series of code types, “an0001”, “an0001.1”, “an0.1” etc. This would make it easy to keep annotations keys separate from at-codes, enabling the annotations part of an archetype to be thrown away in runtime versions. BUT SEE SNOMED option above.
-
OPERATIONAL USE: it is currently assumed that annotations are design-time only, and can be safely removed in operational expressions of archetypes, i.e. within operational templates (OPTs). However, it could be argued that OPTs should (sometimes?) keep annotations for use within some design time tools.
-
Q8: therefore, should anotations be present in OPTs but removable in downstream generated artefacts?
My own feeling is that we should get a balance between complexity/sophistication and pragmatism as follows, noting that we have little evidence in the field for this so far:
-
BASIC REPRESENTATION: the more I think about it, the more I am inclined to implement tags as ‘an-codes’ rather than just Strings. See following points for why.
-
PERSISTENCE: annotations can only exist in an archetype or template, i.e. no new kind of artefact is required. This means that if all you want to do is add annotations at a local level to a national or international archetype, you have to create a specialised archetype or template. This seems reasonable enough, since if you want to create local annotations, the likelihood is that you want to add some local constraints as well, typically at least on coded fields.
-
LANGUAGES: annotations have to be translated to all languages defined in the archetype in which the annotations were authored. This means that international and national archetypes, likely to have more languages, would indeed have annotations translated across all languages present, with the annotations in each language being of the same path & key structure.
-
TAG STANDARDISATION: YES to coding of the tags using internal codes, e.g. with an ‘an-code’ series (rather than no coding or SNOMED CT coding). WHY?
-
This enable tools to exert some control over translation, same as for at-codes, ac-codes
-
Internal codes can have bindings to external codes, e.g. SNOMED CT codes in the future. Assuming global access to and implementation of SNOMED CT & national extensions is probably too much at this stage. If it does all go SNOMED CT for everyone in the next few years, the binding ability will enable archetypes to easily simulate direct SNOMED CT coding.
-
term definitions for Internal codes for the tags can be changed, without structurally changing the archetype annotations
-
existing specialisation rules can be used to reason about merging, since we already have rules for this on at-codes attached to nodes.- OPERATIONAL TEMPLATE: we should assume that annotations are retained in the operational template (perhaps as a tooling option), since the OPT form is used in design time tools to create final stage artefacts, e.g. software APIs, GUI forms etc, and also documentary rendering of the templates for review.
The current implementation will be release in the next 2 weeks or so. All feedback is welcome, and will be used to improve the facility. Anyone who wants to write test archetypes also welcome. I am particularly interested in the thoughts of clinical people.
- thomas beale
