diff --git a/docs/ADL2/master07.05-adl_identification.adoc b/docs/ADL2/master07.05-adl_identification.adoc index 04eec9d5..49d80dcd 100644 --- a/docs/ADL2/master07.05-adl_identification.adoc +++ b/docs/ADL2/master07.05-adl_identification.adoc @@ -77,7 +77,7 @@ The archetype identifier of any specialised archetype, including all templates, === Version Identifiers -ADL 2 Archetypes contain 3-part version identifiers, with optional qualifiers, following the openEHR Artefact Knowledge Identification specification. Examples below: +ADL 2 Archetypes contain 3-part version identifiers, with optional qualifiers, following the openEHR Archetype Identification specification. Examples below: [source, adl] -------- diff --git a/docs/AOM2/master03-archetype_package.adoc b/docs/AOM2/master03-archetype_package.adoc index bdd8ca55..48062bdb 100755 --- a/docs/AOM2/master03-archetype_package.adoc +++ b/docs/AOM2/master03-archetype_package.adoc @@ -8,7 +8,7 @@ The top-level model of archetypes and templates (all variant forms) is illustrat .`am.aom2.archetype` Package image::{uml_diagrams_uri}/AM-aom2.archetype.svg[id=archetype_package, align="center"] -The `AUTHORED_ARCHETYPE` class adds identifying attributes, flags and descriptive meta-data, and is the ancestor type for two further specialisations - `TEMPLATE` and `OPERATIONAL_TEMPLATE` . The `TEMPLATE` class defines the notion of a 'templated' archetype, i.e. an archetype containing fillers/references (ADL's `use_archetype` statements), typically designed to represent a data set. To enable this, it may contain 'overlays', private archetypes that specialise one or more of the referenced / filler archetypes it uses. Overlays are instances of the `TEMPLATE_OVERLAY` class, have no meta-data of their own, but are otherwise computationally just like any other archetype. +The `AUTHORED_ARCHETYPE` class adds identifying attributes, flags and descriptive meta-data, and is the ancestor type for two further specialisations - `TEMPLATE` and `OPERATIONAL_TEMPLATE`. The `TEMPLATE` class defines the notion of a 'templated' archetype, i.e. an archetype containing fillers/references (ADL's `use_archetype` statements), typically designed to represent a data set. To enable this, it may contain 'overlays', private archetypes that specialise one or more of the referenced / filler archetypes it uses. Overlays are instances of the `TEMPLATE_OVERLAY` class, have no meta-data of their own, but are otherwise computationally just like any other archetype. The `OPERATIONAL_TEMPLATE` class represents the fully flattened form of a template, i.e. with all fillers and references substituted and overlays processed, to form what is in practical terms, a single custom-made 'operational' artefact, ready for transformation to downstream artefacts. Because an operational template includes one or more other archetype structures inline, it also includes their terminologies, enabling it to be treated as a self-standing artefact. diff --git a/docs/Identification/master03-artefact_source_id.adoc b/docs/Identification/master03-artefact_source_id.adoc index 3f1b21df..2142bdb5 100755 --- a/docs/Identification/master03-artefact_source_id.adoc +++ b/docs/Identification/master03-artefact_source_id.adoc @@ -123,6 +123,6 @@ Existing archetypes can be accommodated within such ontologies in two possible w ==== Need for RM Class Name in Identifier -Theoretically, the Reference Model class identifier part (qualified_rm_class_name above) should not be needed in a well constructed identifier, on the basis that there should never be a clash of concept identifiers, regardless of the RM class, even though they can easily be similar. For example, a reasonable `concept_id` for an `ENTRY` (ISO 13606) or `OBSERVATION` (openEHR) structure archetyped to represent a generic lab result result might be 'lab_result'. For the COMPOSITION-level archetype designed to contain any 'lab result' `ENTRY` or `OBSERVATION`, a reasonable name would typically be 'lab_report' (or the equivalent in another language). +Theoretically, the Reference Model class identifier part (qualified_rm_class_name above) should not be needed in a well constructed identifier, on the basis that there should never be a clash of concept identifiers, regardless of the RM class, even though they can easily be similar. For example, a reasonable `concept_id` for an `ENTRY` (ISO 13606) or `OBSERVATION` (openEHR) structure archetyped to represent a generic lab result might be 'lab_result'. For the COMPOSITION-level archetype designed to contain any 'lab result' `ENTRY` or `OBSERVATION`, a reasonable name would typically be 'lab_report' (or the equivalent in another language). Unfortunately, for some informational concepts, the appropriate name for the actual core data level can appear to be perfectly reasonable also as a name for a higher level container of the same data. Without an efficient and essentially global ontology construction service or authority available, the inclusion of the qualified RM class name acts as a reasonable guard against such clashes. diff --git a/docs/Identification/master04-versioning.adoc b/docs/Identification/master04-versioning.adoc index e63ea6f8..43584439 100755 --- a/docs/Identification/master04-versioning.adoc +++ b/docs/Identification/master04-versioning.adoc @@ -92,7 +92,7 @@ Consider first the paths. An archetype path is a formal path through a hierarchi * the order and naming of nodes down the hierarchy is determined by the RM; * the type of every object is determined by the RM; -Further, each node is made unique by the use of archetype at-codes (id-codes) (in ADL 1.4 at-codes) which distinguish sibling child objects under any attribute node. Where there are siblings (there need not always be), these codes must be defined in the archetype terminology by domain semantic definitions (e.g. 'serum sodium', 'O2 saturation level'). +Further, each node is made unique by the use of archetype at-codes (id-codes) which distinguish sibling child objects under any attribute node. Where there are siblings (there need not always be), these codes must be defined in the archetype terminology by domain semantic definitions (e.g. 'serum sodium', 'O2 saturation level'). Typical archetype paths look as follows: diff --git a/docs/Identification/master07-referencing.adoc b/docs/Identification/master07-referencing.adoc index 288c7617..ad3ae90d 100755 --- a/docs/Identification/master07-referencing.adoc +++ b/docs/Identification/master07-referencing.adoc @@ -1,6 +1,6 @@ = Referencing -This section describes how artefact are referenced, by other artefacts and software. The general principal for referencing is that references based on human-readable identifiers are used between source artefacts, in the same way as for software, while references in operational forms of the artefacts or from data may be in the form of either HRIDs or machine identifiers. +This section describes how artefacts are referenced, by other artefacts and software. The general principal for referencing is that references based on human-readable identifiers are used between source artefacts, in the same way as for software, while references in operational forms of the artefacts or from data may be in the form of either HRIDs or machine identifiers. A key semantic difference exists with references as opposed to identifiers. A reference is either a full physical artefact identifier, or else an identifier with partial version information. In both cases, a reference is used to match artefacts carrying full identification. In general, there can be several candidate matches, and therefore a matching algorithm has to be specified in each case, in order to ensure constant meaning for a given reference in all modelling and computing environments. @@ -234,10 +234,10 @@ The semantics of referencing in queries differ from those of the archetype-to-ar [source, cadl] -------- - [openEHR-EHR-OBSERVATION.pulse.v1]/data/events[at0006]/data/items[at0004]/value/value + [openEHR-EHR-OBSERVATION.pulse.v1]/data/events[at0005]/data/items[at0003]/value/value -------- -For this to be valid, the path `/data/events[at0006]/data/items[at0004]/value/value` must exist within the earliest v1.x release of the archetype openEHR-EHR-OBSERVATION.pulse.v1, i.e. v1.0.0. If this path happened to have been added in a more recent minor release, the archetype reference would need to include the first minor version containing that path. +For this to be valid, the path `/data/events[at0005]/data/items[at0003]/value/value` must exist within the earliest v1.x release of the archetype openEHR-EHR-OBSERVATION.pulse.v1, i.e. v1.0.0. If this path happened to have been added in a more recent minor release, the archetype reference would need to include the first minor version containing that path. Once an AQL query processor can work with a valid path, it will match the following data: @@ -387,8 +387,8 @@ A formal definition of reference catering to the above requirements is as follow [source, ebnf] -------- - archetype_data_ref = archetype_ver_ref { ',' archteype_ver_ref } ; - archteype_ver_ref = hrid_root '.' version_id_ref ; + archetype_data_ref = archetype_ver_ref { ',' archetype_ver_ref } ; + archetype_ver_ref = hrid_root '.' version_id_ref ; version_id_ref = 'v' version_id ; -------- diff --git a/docs/Identification/master09-artefact_authentication.adoc b/docs/Identification/master09-artefact_authentication.adoc index ef53021a..d7929170 100755 --- a/docs/Identification/master09-artefact_authentication.adoc +++ b/docs/Identification/master09-artefact_authentication.adoc @@ -36,7 +36,7 @@ Both requirements can be achieved for archetypes and templates with a canonical * concept code; * definition section (comments stripped). -These objects would be represented in the same form as defined by the AOM. A suitable serialisation is the dADL syntax form. XML forms could be used, but they depend on which schema variant is in use, and there is no single normative openEHR XML-schema for the AOM. +These objects would be represented in the same form as defined by the AOM. A suitable serialisation is the ODIN syntax form. XML forms could be used, but they depend on which schema variant is in use, and there is no single normative openEHR XML-schema for the AOM. [.tbd] _TBD_: canonical forms of other artefact types. Since all forms of archetypes and templates are now AOM-based (as of 1.5), a single canonical algorithm based on the AOM (with TOM extensions) can be described.