Add support for at-code coding system in addition to id-code coding system.

.gitignore

@@ -1,2 +1,2 @@
 *.bak
-/.idea
+.idea

LICENSE

@@ -225,7 +225,7 @@ subject to and limited by the following restrictions:
     extent reasonably practicable, the URI, if any, that Licensor
     specifies to be associated with the Work, unless such URI does not
     refer to the copyright notice or licensing information for the Work;
-    and (iv) , consistent with Ssection 3(b), in the case of an
+    and (iv) , consistent with Section 3(b), in the case of an
     Adaptation, a credit identifying the use of the Work in the Adaptation
     (e.g., "French translation of the Work by Original Author," or
     "Screenplay based on original Work by Original Author"). The credit

computable/plantuml/primitive.plantuml

@@ -0,0 +1,54 @@
+@startuml
+package primitive_types {
+    class "<<Value_Type>>\nBoolean " as Boolean
+    class "<<Value_Type>>\nCharacter " as Character
+    class "<<Value_Type>>\nOctet " as Octet
+    class "<<Value_Type>>\nInteger" as Integer
+    class "<<Value_Type>>\nInteger64" as Integer64
+    class "<<Value_Type>>\nReal" as Real
+    class "<<Value_Type>>\nDouble" as Double
+    class  "Ordered Numeric" as OrderedNumeric
+    class Numeric
+    class Ordered
+    class String
+    class Uri
+}
+
+package terminology {
+    class Terminology_Code
+}
+
+package time {
+    class Temporal
+    class Iso8601_type
+    class Iso8601_date
+    class Iso8601_time
+    class Iso8601_date_time
+    class Iso8601_duration
+}
+
+Any <|-- Boolean
+Any <|-- Numeric
+Numeric <|-- OrderedNumeric
+Any <|-- Ordered
+Ordered <|-- OrderedNumeric
+Any <|-- Terminology_Code
+Ordered <|-- Character
+Ordered <|-- Octet
+Ordered <|-- String
+String <|-- Uri
+
+OrderedNumeric <|-- Integer
+OrderedNumeric <|-- Integer64
+OrderedNumeric <|-- Real
+OrderedNumeric <|-- Double
+
+Ordered <|-- Temporal
+Temporal <|-- Iso8601_type
+Iso8601_type <|-- Iso8601_date
+Iso8601_type <|-- Iso8601_time
+Iso8601_type <|-- Iso8601_date_time
+Iso8601_type <|-- Iso8601_duration
+@enduml
+
+

docs/ADL2/master00-amendment_record.adoc

@@ -4,13 +4,24 @@
 |===
 |Issue|Details|Raiser, Implementer|Completed
 
+4+^h|*AM Release 2.4.0 (unreleased)*
+
+|[[latest_issue]]2.4.0
+|{spec_tickets}/SPECAM-90[SPECAM-90^]. Add support for at-code coding system in addition to id-code coding system. Make the at-code coding system a requirement for openEHR RM compliant implementations.
+|B Lah, +
+I McNicoll, +
+J Holslag, +
+S Iancu, +
+T Beale
+|[[latest_issue_date]]14 Mar 2024
+
 4+^h|*AM Release 2.3.0*
 
-|[[latest_issue]]2.3.0
+|2.3.0
 |{spec_tickets}/SPECAM-75[SPECAM-75^]. Improve specification of constraint patterns (addresses problem {spec_tickets}/SPECPR-374[SPECPR-374^]). Modified <<#date_time_constraint_patterns>> to include timezone constraints.
 |P Pazos, +
 T Beale
-|[[latest_issue_date]]20 Dec 2022
+|20 Dec 2022
 
 |
 |{spec_tickets}/SPECAM-76[SPECAM-76^]. Correct VSONCO rule for redefinition of nodes with multiple occurrences; improve text in <<Redefinition Concepts>> and <<Occurrences Redefinition>> (addresses problem {spec_tickets}/SPECPR-374[SPECPR-374^]).

docs/ADL2/master01-preface.adoc

@@ -65,6 +65,26 @@ For existing users of ADL or archetype development tools, the following provides
 
 The object syntax used to represent the description, terminology and annotations sections of an ADL archetype has been historically known as 'dADL' (i.e. 'data ADL'). Since this syntax is completely generic and has no specific dependency on either ADL or openEHR, it has been separated out into its own specification known as Object Data Instance Notation (ODIN).
 
+=== ADL 2.4
+
+==== Changes
+
+ADL2 was initially released with a new id-coded coding system using id-codes (for nodes), at-codes (for values only) and ac-codes (for value sets).
+
+The primary change in version 2.4 is the introduction of an alternative at-code coding system, identical to that used in ADL1.
+
+Although a conversion algorithm was developed to enable conversion for ADL1 at-codes in archetypes and templates to the new id-codes and coding system, the openEHR implementer community had concerns on the burden and impact and safety risks inherent in converting downstream software artefacts, queries and persisted patient records.
+
+It was decided that the best solution was to allow openEHR-RM based systems and archetypes to continue to use the original ADL1 at-coded coding system instead of the id-coded coding system. This was seen as critical to remove a very significant barrier to transition from ADL1 to ADL2, which in all other respects was widely welcomed by the established openEHR implementer community.
+
+Further information on the choice of coding system is provided at <<_node_identifier_and_coding_systems>>.
+
+NOTE: ADL tools conformant to ADL/AOM 2.3 or earlier will not conform to the at-coded ADL2 archetypes described in ADL 2.4 without additional engineering.
+
+==== Backward Compatibility
+
+When using the AT-coded coding system, this ADL2.4 release is fully backwards compatible with openEHR RM data created based on ADL 1.4 archetypes. But it breaks compatibility with openEHR RM data created using an ID-coded coding system, which was the only option in ADL 2.0 - ADL 2.3 archetypes. So ID-coded ADL2 systems and tools are expected to require additional engineering in order to gain compatibility with at-coded systems.
+
 === ADL 2.0
 
 ==== Changes
@@ -167,7 +187,7 @@ It is strongly recommended that all tool implementors include this information w
 
 ==== dADL (ODIN) Syntax Changes
 
-The dADL (now ODIN) syntax for container attributes has been altered to allow paths and typing to be expressed more clearly, as part of enabling the use of Xpath-style paths. ADL 1.1 dADL had the following appearance: 
+The dADL (now ODIN) syntax for container attributes has been altered to allow paths and typing to be expressed more clearly, as part of enabling the use of Xpath-style paths. ADL 1.1 dADL had the following appearance:
 
 ```
 	school_schedule = <

docs/ADL2/master02-overview.adoc

@@ -1,6 +1,10 @@
 = Overview
 
-ADL uses three syntaxes, cADL (constraint form of ADL), ODIN (Object Data Instance Notation), and openEHR Expression Language (EL), to express constraints on data which are instances of an underlying information model, which may be expressed in UML, relational form, or in a programming language. ADL itself is a very simple 'glue' syntax, which uses two other syntaxes for expressing structured constraints and data, respectively. The cADL syntax is used to express the archetype `definition` section, while the ODIN syntax is used to express data which appears in the `language`, `description`, and `terminology` sections of an ADL archetype. The top-level structure of an ADL archetype is shown in the figure below.
+ADL uses three syntaxes, cADL (constraint form of ADL), ODIN (Object Data Instance Notation), and openEHR Expression Language (EL), to express constraints on data which are instances of an underlying information model, which may be expressed in UML, relational form, or in a programming language.
+
+ADL itself is a very simple 'glue' syntax, which uses two other syntaxes for expressing structured constraints and data, respectively.
+
+The cADL syntax is used to express the archetype `definition` section, while the ODIN syntax is used to express data which appears in the `language`, `description`, and `terminology` sections of an ADL archetype. The top-level structure of an ADL archetype is shown in the figure below.
 
 This main part of this document describes cADL and ADL path syntax, before going on to describe the combined ADL syntax, archetypes, specialisation, terminology integration and templates.
 
@@ -10,11 +14,92 @@ image::{diagrams_uri}/adl_text_overview.svg[id=archetype_structure, align="cente
 
 == An Example
 
-The following is an example of a very simple archetype, giving a feel for the syntax. The main point to glean from the following is that the notion of 'guitar' is defined in terms of _constraints_ on a _generic_ model of the concept "INSTRUMENT". The names mentioned down the left-hand side of the definition section (`INSTRUMENT`, `size` etc) are alternately class and attribute names from an object model.  Each block of braces encloses a specification for some particular set of instances that conform to a specific concept, such as 'guitar' or 'neck', defined in terms of constraints on types from a generic class model. The leaf pairs of braces enclose constraints on primitive types such as `Integer`, `String`, `Boolean` and so on. 
+The following is an example of a very simple archetype, giving a feel for the syntax. The main point to glean from the following is that the notion of 'guitar' is defined in terms of _constraints_ on a _generic_ model of the concept "INSTRUMENT".
+
+The names mentioned down the left-hand side of the definition section (`INSTRUMENT`, `size` etc) are alternately class and attribute names from an object model.
+
+Each block of braces encloses a specification for some particular set of instances that conform to a specific concept, such as 'guitar' or 'neck', defined in terms of constraints on types from a generic class model. The leaf pairs of braces enclose constraints on primitive types such as `Integer`, `String`, `Boolean` and so on.
+
+====
+[IMPORTANT]::
+
+ADL 2.4 introduces an option to use the **at-code coding system** of ADL1, as an alternative to the **id-code coding system** introduced in ADL2.
+
+- The **at-code coding system** must be used for systems that need to be conformant to the _openEHR Reference Model (RM)_.
+- The **id-code coding system** is recommended for non-openEHR RM information models.
+
+ADL2 syntax examples are provided for both coding systems, as `at-coded ADL2` or `id-coded ADL2`.
+
+Further information on the choice of coding system is provided at <<_node_identifier_and_coding_systems>>.
+====
+
+[tabs,sync-group-id=adl-example]
+.Simple 'Guitar' archetype ADL2 example
+====
+at-coded ADL2::
++
+[source, adl]
+--------
+archetype (adl_version=2.4.0; rm_release=1.1.5)
+    adl-test-instrument.guitar.v1.0.4
+
+language
+    original_language = <[iso_639-1::en]>
+
+definition
+    INSTRUMENT[at0000] matches {
+        size matches {|60..120|}                    -- size in cm
+        date_of_manufacture matches {yyyy-mm-??}    -- year & month ok
+        parts matches {
+            PART[at0001] matches {                  -- neck
+                material matches {[ac1]}            -- timber or nickel alloy
+            }
+            PART[at0002] matches {                  -- body
+                material matches {[at3]}            -- timber
+            }
+        }
+    }
+
+terminology
+    term_definitions = <
+        ["en"] = <
+            ["at0000"] = <
+                text = <"guitar">;
+                description = <"stringed instrument">
+            >
+            ["at0001"] = <
+                text = <"neck">;
+                description = <"neck of guitar">
+            >
+            ["at0002"] = <
+                text = <"body">;
+                description = <"body of guitar">
+            >
+            ["at0003"] = <
+                text = <"timber">;
+                description = <"straight, seasoned timber">
+            >
+            ["at0004"] = <
+                text = <"nickel alloy">;
+                description = <"frets">
+            >
+        >
+    >
+
+    value_sets = <
+        ["ac1"] = <
+            id = <"ac1">
+                members = <"at0003", "at0004">
+            >
+        >
+    >
+--------
 
+id-coded ADL2::
++
 [source, adl]
 --------
-archetype (adl_version=2.0.5; rm_release=1.1.5)
+archetype (adl_version=2.4.0; rm_release=1.1.5)
     adl-test-instrument.guitar.v1.0.4
 
 language
@@ -68,3 +153,4 @@ terminology
         >
     >
 --------
+====

docs/ADL2/master04.1-cadl_overview.adoc

@@ -1,9 +1,29 @@
 = cADL - Constraint ADL
-
 == Overview
 
 cADL is a block-structured syntax which enables constraints on data defined by object-oriented information models to be expressed in archetypes or other knowledge definition formalisms. It is most useful for defining the specific allowable configurations of data whose instances conform to very general object models. The general appearance of cADL is illustrated by the following example:
 
+
+[tabs,sync-group-id=adl-example]
+====
+at-coded ADL2::
++
+[source, cadl]
+--------
+    PERSON[at0000] matches {                             -- constraint on a PERSON instance
+        name matches {                                   -- constraint on PERSON.name
+            TEXT[at0001] matches {/.+/}                  -- any non-empty string
+        }
+        addresses cardinality matches {1..*} matches {   -- constraint on
+            ADDRESS[at0002] matches {                    -- PERSON.addresses
+                -- etc --
+            }
+        }
+    }
+--------
+
+id-coded ADL2::
++
 [source, cadl]
 --------
     PERSON[id1] matches {                                -- constraint on a PERSON instance
@@ -17,9 +37,30 @@ cADL is a block-structured syntax which enables constraints on data defined by o
         }
     }
 --------
+====
 
 Some of the textual keywords in this example can be more efficiently rendered using common mathematical logic symbols. In the following example, the `matches` keyword have been replaced by an equivalent symbol:
 
+[tabs,sync-group-id=adl-example]
+
+====
+at-coded ADL2::
++
+[source, cadl]
+--------
+    PERSON[at0000] ∈ {                            -- constraint on a PERSON instance
+        name ∈ {                                  -- constraint on PERSON.name
+            TEXT[at0001] ∈ {/..*/}                -- any non-empty string
+        }
+        addresses cardinality ∈ {1..*} ∈ {        -- constraint on
+            ADDRESS[at0002] ∈ {                   -- PERSON.addresses
+                -- etc --
+            }
+        }
+    }
+--------
+id-coded ADL2::
++
 [source, cadl]
 --------
     PERSON[id1] ∈ {                            -- constraint on a PERSON instance
@@ -33,6 +74,9 @@ Some of the textual keywords in this example can be more efficiently rendered us
         }
     }
 --------
+====
+
+
 
 The full set of equivalences appears below. Raw cADL is persisted in the text-based form, to remove any difficulties when authoring cADL text in normal text editors, and to aid reading in English. However, the symbolic form might be more widely used for display purposes and in more sophisticated tools, as it is more succinct and less language-dependent. The use of symbols or text is completely a matter of taste, and no meaning whatsoever is lost by completely ignoring one or other format according to one's personal preference. This document uses both conventions.