openEHR Platform Service Model

This specification has benefited from formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

This document specifies core components of the openEHR platform in a formal, abstract form, for use in developing concrete service API definitions such as SOAP, REST, Google protocol buffers and other interface technologies.

The intended audience includes:

Prerequisite documents for reading this document include:

Related documents include:

This specification is in the TRIAL state. The development version of this document can be found at https://specifications.openehr.org/releases/SM/development/openehr_platform.html.

Known omissions or questions are indicated in the text with a 'to be determined' paragraph, as follows:

Feedback may be provided on the technical mailing list.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the SM component Change Request tracker.

Conformance of a data or software artifact to an openEHR specification is determined by a formal test of that artifact against the relevant openEHR Implementation Technology Specification(s) (ITSs), such as a REST API interface or an XML-schema. Since ITSs are formal derivations from underlying models, ITS conformance indicates model conformance.

In order to specify concrete service interfaces (i.e. APIs) to openEHR platform product components, a formal, abstract definition of the platform interfaces is useful, so as to be able to state the formal interface call semantics independent of any particular implementation technology. This approach clarifies the distinction between required semantics and the details contingent in any concrete technology, such as SOAP/WSDL, REST, and so on, each of which has its own characteristics and rules.

It is assumed that native APIs are network-accessible via one or more communications protocols, each with an appropriate protocol adapter. Such protocols include the text-based, such as SOAP/WSDL and REST, as well as the many binary protocols, including Google Protocol Buffers, Apache Thrift, Kafka, ZeroC ICE, and Advanced Message Queueing Protocol (AMPQ). The focus of this specification is the nominal 'native API' that is reached by any of these methods, as shown below.

The following figure illustrates the components of the abstract openEHR Platform, along with their interfaces.

Each component has one or more associated interfaces, i.e. abstract service definitions which define a transactional interface to the service represented by the component. Each interface consists of a number of calls, and each call is defined in an abstract way, i.e. independent of the representations and expressions required by a concrete protocol.

This view does not attempt to define a real product architecture as would be developed by an openEHR platform implementor, but it does establish a formal equivalent of any such architecture. Practically, this entails standardised naming of components and the semantics of their logical interfaces so that platform procurers and users can unambiguously refer to the 'Admin service' or the 'EHR service' within technical or commercial documents. The abstract service architecture described here provides platform implementers a standard reference definition for mapping agreed functionality (such as requested in a tender or other solicitation) into their own architectures, which may be organised quite differently.

The services are as follows.

Regardless of the internal organisation of real product architectures, agreement across a community of producers and users of products that claim to conform to a published platform specification, must by definition be based on something formally statable and testable. As noted above, this is described here in the form of logical components which have logical interfaces, each consisting of a set of calls, of which the latter constitute the finest level of specification.

A logical interface call is understood here in the standard computer science manner, i.e. as a callable routine with a formal, typed signature. Good practice usually dictates that such routines should take the form of either pure functions, or pure procedures, but not both: side-effect producing functions should generally be avoided. In other words, interface calls are either queries that return something but do not change state, or commands that cause a change, but don’t compute or return anything. The separation is sometimes known as command / query separation.

The signatures of query and procedure calls thus take the following syntactic forms:

One of the key assumptions of this specification (and indeed formal standardisation in general) is that although real implementations of a platform may have differently structured components and different naming of functions, arguments etc, that there is a formal equivalence between calls specified in a published standard and those in the implementation. Thus, it must be the case that even if three calls in an implementation are required to achieve the effect of a single call in this specification, that the conditions described here prior and after the call(s) are the same in both cases, and also that the three calls taken together are transactionally protected. If this is not true, it implies that the implementation is introducing unspecified semantics.

A fuller specification of any function or procedure includes its semantics, stated in terms of pre-conditions, post-conditions and exceptions, along with documentation of the same. This is exactly as found in any standard library in most programming languages, and indeed, standardised meta-data keywords and labelling have evolved in most programming documentation systems to support exactly this kind of specification, even where the language doesn’t directly support some of its features, such as pre- or post-conditions.

This specification uses the same form of specification, which can be illustrated as follows:

The above kind of specification can in general be easily mapped to any concrete API technology. In each case, how the arguments are expressed, details of serialisation (for text-based technologies like SOAP and REST), error handling, etc, will be different. Google protocol buffers for example uses an OMG IDL-like approach to specification, i.e. structured type definitions. REST on the other hand is a web-based type of API normally mapped onto HTTP verbs, URIs and HTTP error codes.

The intent of the current specification is thus to express the abstract element of each interface call, so that both back-end semantics can be correctly designed, and API definitions can be correctly written and tested.

The openEHR Platform Service Model package structure is illustrated below. It consists of the packages common, definition and interface. The second contains the service components, while the third contains the interfaces attached to each service component.

The platform.common package shown below defines common elements of the platform service model, including:

The status of a call is represented using a CALL_STATUS object containing various informational fields and a code attribute that carries a value from the enumerated type CALL_STATUS_TYPE or a descendant. The codes defined in CALL_STATUS_TYPE are generic and apply across all services. Particular services may add more codes by inheriting from this class and defining further specific codes.

Some of the interfaces defined in this specification cause creation or update of a versioned 'top-level' openEHR object, i.e. a COMPOSITION, PARTY or similar. Such calls implicitly require the creation of a new CONTRIBUTION on the server side, as well as one or more new ORIGINAL_VERSION objects, and in creation cases, new VERSIONED_OBJECTS.

To perform this work on the server, the UPDATE_VERSION<T> structure is provided in order to enable the appropriate meta-data to be supplied by the caller, leaving out parts that are generated by the service. Thus, a partial version of AUDIT_DETAILS called UPDATE_AUDIT is used, since the time_committed and system_id attributes need to be generated on the server. ATTESTATION instances can be supplied in their full form.

The preceding_version_uid attribute must be specified, except in the case where the version update is a first version. The lifecycle_state must be supplied in all cases, which is a value such as 532|complete|, 553|incomplete|, 523|deleted|, etc from the openEHR terminology.

This approach allows the server side to create the required new ORIGINAL_VERSION<T> object, rather than the client trying to do it.

For each storable top-level type such as COMPOSITION, FOLDER, PARTY descendants etc, a new concrete type may be derived from UPDATE_VERSION<T>. For example, for COMPOSITION, the type UV_COMPOSITION may be defined, inheriting from UPDATE_VERSION<COMPOSITION>.

The platform.interface.definitions package shown below defines service interface to the definitions component in the logical platform architecture.

The interfaces provided in this service are designed to enable any model-like or reference artefacts, other than terminology, to be stored for use by the rest of the system. This includes archetypes, templates, queries, and query sets.

The I_DEFINITION_ADL14 and I_DEFINITION_ADL2 interfaces are provided to enable upload, updating and removal of archetypes and templates based on the ADL 1.4 and ADL 2 standards respectively, for use in an operational system.

In the ADL2 case, archetypes and 'templates' are all instances of archetypes, formally speaking, which means that both source artefacts and Operational Templates (OPTs) can be uploaded. All such artefacts are identified in the same way, via an Archetype human-readable identifier (ARCHETYPE_HRID) and a UUID.

For ADL 1.4, 'templates' are distinct artefacts, and the service enables the upload of source archetypes and ADL 1.4 - based OPTs, which are XML artefacts. In ADL 1.4, archetypes are identified with the older ARCHETYPE_ID, while OPTs are identified with UUIDs.

Queries may be registered in the system for later execution. They are identified by 'qualified names', i.e. String names that may include a namespace and optionally a formalism type. The following schemes may be used:

Examples:

If no namespace is supplied, the namespace "misc" is assumed.

The platform.interface.ehr package shown below defines service interface to the EHR component in the logical platform architecture.

The platform.interface.demographic package shown below defines service interface to the DEMOGRAPHIC_SERVICE component in the logical platform architecture.

The platform.interface.ehr_index package shown below defines service interface to the EHR_INDEX component in the logical platform architecture.

The primary function of the EHR Index service is to enable the recording of associations of subject identifiers (i.e. patient or other subject or care identifiers) with EHR identifiers. In a privacy-supporting environment, this enables EHRs to be persisted with only an EHR id; the EHR Index has to be used to obtain the subject identifier, which will usually be used as a key into a demographic or MPI service, ultimately allowing EHR data to be associated with the correct patient demographic information in a user application.

There is no limit on the number of subject identifiers associated with a given EHR id, and vice versa, since in real environments both situations commonly occur. The two cases are as follows:

To enable management of these problems, other meta-data can be associated with each EHR id / subject id association, represented by the RESOURCE_STATUS type.

A further useful facility that can be provided by this service is to maintain dynamic location information for EHRs. This is enabled by the inclusion of optional LOCATION_DESC instances with index records.

The platform.interface.query package shown below defines service interface to the QUERY_SERVICE component in the logical platform architecture.

The model of querying here is based on the notion of being able to execute either queries previously stored in the DEFINITION service, or else ad hoc queries. For stored queries, no assumption is made as to whether the query language is AQL (the openEHR default) or something else, only that there are stored queries that can be executed in a standard way.

For both kinds of queries, parameters must be provided for open parameters in the stored query.

If either type of query executes successfully, the response is a RESULT_SET, which consists of meta-data, a column definition structure and a set of rows (instances of RESULT_SET_ROW). In order to handle large result sets efficiently and gracefully within applications, the parameters item_offset and items_to_fetch can be provided to control the result size.

A stored query is identified by the identifier associated with it when registered in the DEFINITION service, which is ofthe form:

For example: org.example.departmentx.test::diabetes-patient-overview/1.0.2. The optional version enables multiple forms of the same semantic query to co-exist in the service.

The platform.interface.message package shown below defines service interface to the MESSAGE component in the logical platform architecture.

The Subject Proxy Service (SPS) allows symbolic variables characterising the real world state of a subject which is often a subject of care (i.e a patient) but may be some other entity, to be retrieved and tracked over time. Such variables are useful for many kinds of application, since they provide a standard means of obtaining information that concretely reside in different kinds of back-end systems or devices, or may be requested from live users. The SPS avoids the calling application having to know about the particular standard, representational model, query language or API of the data source for any given variable. Consequently there is no need to even assume that an openEHR back-end system is the source of any given variable.

The following diagram shows conceptually the population of subject proxy variables from back-end systems, via the various intermediate layers of the Subject Proxy Service.

Subject variables may be conveniently used by any application and are relied upon by openEHR Task Plans and Decision Logic Modules, for which the conceptual purpose and typical use are described in the openEHR Process and Planning Overview.

The Subject Proxy Service enables the registration of subject variables by various means. Each subject variable is identified within the service by a canonical name (SUBJECT_VARIABLE.canonical_name, in the model below), which is the name used for it in calls mentioning variables by name.

The canonical name is formed from SUBJECT_VARIABLE.name, prefixed by namespace if it is set, and are unique within the service, regardless of which subjects or applications may use them at any given time. The name attribute is an intelligible natural language names that accurately indicate its meaning, such as "date_of_birth", "is_type1_diabetic" and so on, but may be any name that is legal within the relevant source contexts and valid within this service. Some variable names such as "date_of_birth" are regarded as having a globally agreed definition (e.g. the date recorded as date of birth against the subject in administration systems), while other variables such as has_heart_failure may have a definitions specific to particular guidelines, such as CHA₂DS₂-VASc, a guideline for atrial fibrillation (AF) diagnosis etc. The use of namespaces in the latter cases would have the effect of defining variables such as cha2ds2vasc::has_heart_failure and af_diagnosis::has_heart_failure (where "cha2ds2vasc" and "af_diagnosis" are namespace values), each of which may have a semantically different retrieval definition (for example including or excluding heart murmur).

If namespace is not set, the variable is understood to be in the 'global' namespace, and to have the same meaning for all users. There is nothing to stop a variable existing in both the global namespace and one or more specific namespaces, for example date_of_birth (standard administrative concept) and tribal::date_of_birth (a specific 'date of birth' concept used for ethnic or religious reasons).

To be valid within the service, canonical names may not contain whitespace or any unprintable character, but there are no other restrictions (e.g. of case, or first character being a letter etc).

An application data set, which is a convenience collection of variables registered by / for an application may however use data set-local aliases, for example "dob" for the canonical name "date_of_birth". This allows the names used locally within client computation contexts for the same variable registered in the SPS may differ. It is recommended that this flexibility be used sparingly in order to limit confusion within the overall system design environment.

The SPS supports the following abstract kinds of operations (with variants):

The platform.interface.subject_proxy package shown below defines the service interface and related information structures for the SUBJECT_PROXY service in the openEHR platform architecture.

The data entities used by the SPS are conceptually as follows:

The formal class definitions are shown in the following UML.

The SAMPLE class provides a generic wrapper for any retrieved back-end data, stamping it with a retrieve_time and a is_unavailable flag in case no data could be obtained. The optional effective_time represents the clinically relevant time of the sample, which is comparable to currency in order to determine the freshness of the data. The descendant DATA_FRAME_SAMPLE specialises the payload to full data frame results, which may be large query results, complex data objects etc, or indeed, single values.

The following UML shows the Sample hierarchy.

A binding (represented by ENV_BINDING) is understood as a set of retrieval methods (e.g. API invocations, queries) each defined by a data frame (represented by DATA_FRAME), for a particular execution environment, and independent of any particular subject. A binding may be loaded in the service via the call register_binding(). Each data frame has a primary and optionally a fallback method which can be executed to obtain the data, as well as a retrieval result, in the native format of the API used to access the source system, e.g. openEHR AQL Result_set, a particular FHIR profiled resource, an HL7v2 message, XDS document and so on. The interface I_DATA_BINDING provides a (partially specified) internal API for retrieving a result from a particular data frame.

The retrieved data frame results are of type DATA_FRAME_SAMPLE, representing a single 'sample' of some kind of retrieval result from a back-end system or interoperability gateway. The descendant types provide a few common forms.

The following UML diagram shows the classes and an internal interface relating to bindings.

It is assumed that the configuration contents (i.e. not data frame or variable results) of the SPS are persisted for the life of the system i.e. until the point of any system level re-initialisation actions. The SPS includes a reset() operation that enables all content to be dumped, returning the service to its virgin state.

The usage of the service follows the general pattern:

The calling sequence to achieve this is of the logical form:

The first call registers a binding for a specific environment. See below for how bindings are defined. The next call creates the subject in the service, while the subsequent add_subject_variable calls are used to build up the proxy variable set for the subject.

This calling sequence suits system initialisation when specific subject proxy variables are created for global use for specific subjects. Typical variables in a healthcare IT environment include date_of_birth and sex.

However many variables are defined by particular applications, including guidelines and planning applications. Accordingly, the service provides a way to register an application data set, i.e. a collection of subject variables, for a subject. In this case, the calling sequence will be of the following form.

In this sequence, the subject variables are established via calls to register_application_data_set, each of which will cause the addition or modification of subject variables not already defined for the subject. When use of an application or subject ceases, the relevant data sets can be removed easily via the various remove_xx calls.

The following example illustrates a typical run-time situation for the use of the Subject Proxy Service.