Archetype 'comments'.

Specifications ADL
1

Archetypes can contain comments in different forms. Which is confusing.

One is inline comments in a raw ADL, after a special character ‘–’which is ignored by most software tools. Archetype Definition Language 2 (ADL2)

Second is in archetype ontology (terminology in adl2), each node, has a ‘text’ and ‘description’ and optional ‘other_items’ which is a Hash of key: value <String, String>, in CKM (and archetype designer) it’s common practice to add a ‘comment’ as a key. (And CKM also has ‘source’ apparently). Archetype Object Model 2 (AOM2) See this example:

["at0000"] = <
					text = <"Adverse reaction risk">
					description = <"Clinical assessment of the propensity for an individual to experience a harmful or undesirable physiological response if exposed, or re-exposed, to a substance.">
					comment = <"Substances include, but are not limited to: a therapeutic substance administered correctly at an appropriate dosage for the individual; food; material derived from plants or animals; or venom from insect stings.">
					source = <"openEHR,FHIR">
				>

I would suggest we specify this ‘comment’ in the RM to improve clarity and consistency. Als I think the CKM (and AD) syntax is wrong here, these key:value pairs should be in a hash, not just in line like ‘text’ and ‘description’ @sebastian.garde am I missing something?

Third option is archetype editorial style guide specifies the archetype data attribute can have an element with the name ‘comment’. Which is just a regular element like any other, so it’s a node in the Archetype Object Model. And the value for the element gets persisted in the CDR.

Curious for your thoughts.

2

This is the only kind of comment you can have in an ADL file. It’s two standard dashes, not a special character! It’s the same concept as comments in Java (//, /* xxx */) or bash (#) etc.

This is not an ADL comment, it’s ADL meta-data attached to an ARCHETYPE_TERM definition within the terminology. It happens to have the key ‘comment’, but that’s nothing to do with ADL comments, and is not processed by the parser as any kind of comment. The notion of ‘comment’ here is within the archetype term definition, not at the syntax level of the ADL file.

This latter kind of comment is nothing to do with the RM (nor is the former…); it’s in the AOM space, not the RM.

I don’t see what the problem here is, other than possibly something slightly confusing in the CKM (and maybe AD) UI? If that’s the case, I suggest making adjustments to those tools…

3

Adding comment as an explicit field may be useful.
Re the hash key/values:
The serialisation in adl does not have to correspond to the internal model. I guess it would be nice (and parsing this would have been considerably easier…), it is just that it has always been done that way (as explicit keys), even long before CKM existed. The original RM ref impl does it that way, etc.

2 Likes