*
* 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,
o this allows any string, including in script languages like
Farsi, Hindi, Chinese etc
o 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?
o if annotations are regarded as an intrinsic part of an
archetype, they are recorded in the archetype: this is what
we have currently implemented
o 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.
o 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
o 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.
o 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.
o 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.
o 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.
o 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?
o This enable tools to exert some control over translation,
same as for at-codes, ac-codes
o 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.
o term definitions for Internal codes for the tags can be
changed, without structurally changing the archetype annotations
o 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.openehr.org/mailman/private/openehr-technical_lists.openehr.org/attachments/20101223/b36bd548/attachment.html>
