Key Code Design

Key codes are a proposed addition to ADL2 that would add freely named synonyms ('keys') to the terms defined in an archetype, e.g. as follows:

terminology: {
	term_definitions: [
		"en": [
			"id1": {
				key: "imaging_investigation",
				text: "Imaging investigation",
				description: "An action related to an investigation by an imaging technique",
				at_code: "at0000"
			},
			"id2": {
				key: "planned",
				text: "Planned",
				description: "Imaging investigation is planned",
				at_code: "at0001"
			},
			etc
		]
	]
}

They provide a human-comprehensible synonym of the id-codes and would be used in the formation of developer-friendly paths.

Various technical question need to be answered about their design however. These are addressed below.

Basic Rules

The basic syntax rules for keys are similar to identifiers in many programming and schema languages.

no white space
underscore allowed, dash not allowed
may start with digits
may not start or end with underscore

What does a key refer to - a node or a path?

Consider the openEHR adverse_reaction_risk archetype, shown here in the ADL Workbench:

adverse reaction

In the terminology, each of the node names in the above is taken from that node’s text field. Here’s the whole terminology:

Keys for some of the above node might be as shown in the table below. Note that they might be chosen to be shorter or a ‘summarised’ version in the same way that programmers often try to avoid very long variable names. No recommendation on the style (short or long) is made here.

code	text	key

code	text	key
id1	Adverse reaction risk	adverse_reaction_risk
id2	-	-
id3	Substance	substance
id21	Initial exposure	initial_exposure
id28	Onset of reaction	onset
id29	Duration of reaction	duration
id41	Clinical management description	management
id48	Supporting clinical record information	supporting_info

The following is a path that uses some of the above nodes:

/data[id2]/items[id10]/items[id21]

If we simply add in the current text values, as the ADL WB does, we get this:

/data[id2]/items[id10|Reaction event|]/items[id21|Initial exposure|]

This is not terribly readable either. Let’s go one step further by removing the id codes and using the keys instead:

/data/items[reaction_event]/items[initial_exposure]

First of all, what happened to the initial `[id2]` code? Remember that while id-codes are required on all nodes, if they identify nodes with no siblings, they don’t require a term definition. So removing them makes no difference to the validity of the path.

We can now go a further step:

/data/reaction_event/initial_exposure

This path abstracts away the items property from the reference model class CLUSTER. This is a safe thing to do if we treat that property as being the sole compositional relationship in `CLUSTER`. The result is a mixed model + RM path that is convenient to use for developers.

RULE: keys identify nodes (not whole paths) with respect to sibling nodes under multiply-valued compositional attributes.

Uniqueness

A consequence of the above rule is that keys must at least be unique with respect to the sibling node within the same container object.

However, it is likely that we want to go further and require that keys are unique within a whole archetype. Since archetypes can be specialised, this means within the flat archetype.

RULE: keys must be unique with respect to all other keys within the inheritance-flattened archetype, at any level.

Basic Rules

What does a key refer to - a node or a path?

Uniqueness

Do all nodes need keys?