Navigation Package

Overview

The navigation Package defines a hierachical heading structure, in which all individual headings are considered to belong to a "tree of headings". Each heading is an instance of the class SECTION, visible in the lower left side of [rm_composition].

Sections provide both a logical structure for the author to arrange Entries, and a navigational structure for readers of the record, whether they be human or machine. Sections are archetyped in trees with each tree containing a root Section, one or more sub-sections, and any number of Entries at each node. Section trees that are separately archetyped, such as the SOAP headings, or the heading structure for a physical examination, can be combined at runtime by type to form one large heading structure, as shown in the figure below.

ehr with sections
Figure 1. Section View of a General Practice Contact Composition

In terms of understanding of clinical data, Section structures are not essential in a Composition - they can always be removed or ignored (typically in machine processing such as querying) without losing the meaning of the Entries in the Composition. While Sections are often used to group Entries according to status, e.g. 'family history', 'problems', 'observations', it is the Entries themselves that indicate the definitive category of information contained therein. This principle is explained in more detail in [Entry and its Subtypes].

Despite the above, Section structures do not have to be regarded as ad hoc or unreliable structures. On the contrary, as they are archetyped, their structures can be relied upon in the same way as any other structure in the record can be relied on to conform to its archetype. Accordingly, solid assumptions can be made about Sections, based on their archetypes, for the purposes of querying. In fact, the main benefit of Sections is that they may provide significant performance benefits to querying, whether by interactive application or by automated systems.

One potentially confusing aspect of any Section structure is that while the root Section in a tree is logically a Section, it does not appear in a display or printed form as a visible section. This is due to the fact that humans don’t usually write down top-level headings for anything, since there is always a containing structure acting as a top-level organising context (such as the piece of paper one is writing on). For example, consider the way a clinician writes down the problem/SOAP headings on paper. She writes the name of the first problem, then under that, the S/O/A/P headings, then repeats the process for further problems. But she doesn’t write down a heading above the level of the problems, even though there must be one from a data structure point of view.

Class Descriptions

SECTION Class

  • Definition

  • Effective

  • BMM

  • UML

Class

SECTION

Description

Represents a heading in a heading structure, or section tree. Created according to archetyped structures for typical headings such as SOAP, physical examination, but also pathology result heading structures. Should not be used instead of ENTRY hierarchical structures.

Inherit

CONTENT_ITEM

Attributes

Signature

Meaning

0..1

items: List<CONTENT_ITEM>

Ordered list of content items under this section, which may include:

  • more SECTIONs;

  • ENTRYs.

Invariants

Items_valid: items /= Void implies not items.is_empty
SECTION

Represents a heading in a heading structure, or section tree. Created according to archetyped structures for typical headings such as SOAP, physical examination, but also pathology result heading structures. Should not be used instead of ENTRY hierarchical structures.

Inherits: Any, PATHABLE, LOCATABLE, CONTENT_ITEM

Attributes

LOCATABLE.name: DV_TEXT [1..1]

Runtime name of this fragment, used to build runtime paths. This is the term provided via a clinical application or batch process to name this EHR construct: its retention in the EHR faithfully preserves the original label by which this entry was known to end users.

LOCATABLE.archetype_node_id: String [1..1]

Design-time archetype identifier of this node taken from its generating archetype; used to build archetype paths. Always in the form of an at-code, e.g. at0005. This value enables a 'standardised' name for this node to be generated, by referring to the generating archetype local terminology.

At an archetype root point, the value of this attribute is always the stringified form of the archetype_id found in the archetype_details object.

LOCATABLE.uid: UID_BASED_ID [0..1]

Optional globally unique object identifier for root points of archetyped structures.

LOCATABLE.links: List<LINK> [0..1]

Links to other archetyped structures (data whose root object inherits from ARCHETYPED, such as ENTRY, SECTION and so on). Links may be to structures in other compositions.

LOCATABLE.archetype_details: ARCHETYPED [0..1]

Details of archetyping used on this node.

LOCATABLE.feeder_audit: FEEDER_AUDIT [0..1]

Audit trail from non-openEHR system of original commit of information forming the content of this node, or from a conversion gateway which has synthesised this node.

items: List<CONTENT_ITEM> [0..1]

Ordered list of content items under this section, which may include:

  • more SECTIONs;

  • ENTRYs.

Functions

(abstract) Any.is_equal (
other: Any[1]
): Boolean [1..1]

Value equality: return True if this and other are attached to objects considered to be equal in value.

Parameters
other

Other object for comparison.

Any.equal alias "=", "==" (
other: Any[1]
): Boolean [1..1]

Reference equality for reference types, value equality for value types.

Parameters
other

Other object for comparison.

Any.instance_of (
a_type: String[1]
): Any [1..1]

Create new instance of a type.

Any.type_of (
an_object: Any[1]
): String [1..1]

Type name of an object as a string. May include generic parameters, as in "Interval<Time>".

Any.not_equal alias "!=", "≠" (
other: Ordered[1]
): Boolean [1..1]

True if current object not equal to other. Returns not equal().

PATHABLE.parent (): PATHABLE [1..1]

Parent of this node in a compositional hierarchy.

PATHABLE.item_at_path (
a_path: String[1]
): Any

Pre: path_unique (a_path) [1..1]

The item at a path (relative to this item); only valid for unique paths, i.e. paths that resolve to a single item.

PATHABLE.items_at_path (
a_path: String[1]
): List<Any> [0..1]

List of items corresponding to a non-unique path.

PATHABLE.path_exists (
a_path: String[1]
): Boolean

Pre: not a_path.is_empty [1..1]

True if the path exists in the data with respect to the current item.

PATHABLE.path_unique (
a_path: String[1]
): Boolean

Pre: path_exists (a_path) [1..1]

True if the path corresponds to a single item in the data.

PATHABLE.path_of_item (
a_loc: PATHABLE[1]
): String [1..1]

The path to an item relative to the root of this archetyped structure.

LOCATABLE.concept (): DV_TEXT [1..1]

Clinical concept of the archetype as a whole (= derived from the archetype_node_id' of the root node)

LOCATABLE.is_archetype_root (): Boolean [1..1]

True if this node is the root of an archetyped structure.

Invariants

LOCATABLE.Links_valid: links /= Void implies not links.is_empty

LOCATABLE.Archetyped_valid: is_archetype_root xor archetype_details = Void

LOCATABLE.Archetype_node_id_valid: not archetype_node_id.is_empty

Items_valid: items /= Void implies not items.is_empty

 
{
    "name": "SECTION",
    "documentation": "Represents a heading in a heading structure, or  section tree.  Created according to archetyped structures for typical headings such as SOAP,  physical examination, but also pathology result heading structures.  Should not be used instead of `ENTRY` hierarchical structures. \n",
    "ancestors": [
        "CONTENT_ITEM"
    ],
    "properties": {
        "items": {
            "_type": "P_BMM_CONTAINER_PROPERTY",
            "name": "items",
            "documentation": "Ordered list of content items under this section, which may include:\n\n* more `SECTIONs`;\n* `ENTRYs`.",
            "type_def": {
                "container_type": "List",
                "type": "CONTENT_ITEM"
            },
            "cardinality": {
                "lower": 0,
                "upper_unbounded": true
            }
        }
    },
    "invariants": {
        "Items_valid": "items /= Void implies not items.is_empty"
    }
}
SECTION

Section Instance Structures

Problem/SOAP Headings

An example of an section tree representing the problem/SOAP heading structure is shown below.

Composition with sections
Figure 2. "problem/SOAP" Section Structure