Basic Meta-Model (BMM)

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 describes the Basic Meta-Model (BMM), a model of object models. It may be considered as an approximate replacement for the UML XMI. It is human-readable and writable, and supports generic types (open and closed), container types, and multiple inheritance.

This specification is in the STABLE state. The development version of this document can be found at www.openehr.org/releases/BASE/latest/bmm.html.

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

Users are encouraged to comment on and/or advise on these paragraphs as well as the main content. Feedback should be provided either on the technical mailing list, or on the specifications issue tracker.

The elements of meta-models are sometimes named confusingly in the literature and within various programming language technologies. In this specification, we have used the following terms:

The openEHR ADL Workbench (AWB) fully implements this specification, and provide a convenient way of illustrating BMM semantics. The screenshots used in this specification are all from the ADL Workbench. The tool is written in the Eiffel language, and is available as open source on Github. The BMM libraries can be found in the EOMF Github repository.

A modelling tool known as Archie implements BMM in Java, and can be found in the openEHR Github area.

One of the key needs in any open computing environment is a computable representation of its own models. This is for a number of purposes, including reasoning about them, performing validation and consistency checking, building software and generating documentation. This is particularly true of openEHR and other archetype-based frameworks, where a further need is to be able to validate archetypes and templates with respect to the reference model, and also to validate runtime instance data against operational templates and the reference model.

A number of computable representations of the openEHR published models have been available in the past. Currently models are represented in two computable forms, namely UML and BMM (i.e. the format described in this specification).

The primary use of the UML expression is for specification publishing. In this role, UML diagrams and static models are built, and then post-processed to correct signatures of class properties and functions. The post-processing corrects UML’s shortcomings and errors in non-singular relations, generic (template) types, and qualified attributes. The result can be used for publishing documentation with feature signatures that are formally correct and will be understood by developers in most programming languages. It can also be serialised and used computably, e.g. in other visualisation or modelling tools. UML’s own serial format, XMI is thus generally unsuitable for such uses, due to the formal errors, as well as its excessive complexity. XMI is also notoriously non-standard across UML tools.

As a result, openEHR introduced the Basic Meta-Model (BMM) in 2009 as a way of representing correct object-oriented semantics of information models for use in tools, along with a serial format by default expressed in the openEHR ODIN syntax.

The BMM provides a standalone alternative to UML/XMI which correctly represents all types, including open and closed generic types, inheritance of generic types, and various other problems with UML. As a meta-model it is adapted to the task, i.e. representing entity types that can appear in object models, rather than the over-generalised semantics of the UML meta-model. This reduced scope, and the fact that it contains no diagram semantics enables its serial form to be very human-readable.

The Basic Meta-Model supports the representation of object models in the ISO RM/ODP information and computational points of view, i.e. in programming terms, 'classes, properties and methods'. It is designed to enable both human authoring and machine extraction (e.g. from a UML tool or programming language classes) of textual schemas. The semantics of the model are heavily influenced by the formal approach to object-orientation described by Bertrand Meyer in Object-oriented Software Construction [Meyer_OOSC2] and also the Eiffel language, which is significantly better match to object modelling than the UML 2.x meta-model.

Until version 3.0.0, BMM supported only the information point of view, i.e. no methods. As of version 3.1.0, computed class features (functions and procedures) may also be included. Nevertheless, BMM is often used to express models of data. Tools that use the BMM can provide views of an object model expressed in BMM that are particularly useful to information modelling, such as 'closure' view show below. This is a computed reachability graph of a fully inheritance-flattened class and all properties, including recursive references.

One of the main uses of the BMM in the ADL Workbench and other similar tools is to provide a computable form of the information model for use with domain-level content models, such as archetypes. The following shows an archetype for which each node has its class shown (in colour), and additionally, the inclusion of non-archetyped attributes from the classes of the archetype nodes.

Newer tools are able to include the computational features.

This specification defines a BMM object model, i.e. the in-memory object structure of a BMM. The related BMM Persistence specification defines an object model for a serialised schema form. The latter enables serialisation of a BMM into a concrete syntax such as ODIN, JSON or XML.

The BMM packages are as follows:

Related is the bmm_persistence package, which contains the BMM Persistence classes.

These are illustrated below.

The model_access package provides an interface for the application to load BMM schemas and convert them to BMM model form, and is shown below. In this model, a schema is a concrete serial form of a model or part of a model. One or more schema files are parsed, validated and then converted to create a single BMM_MODEL instance.

More than one format for representing serialised BMM models is possible, each having its load, validation and error-reporting logic. The common elements of the load, validate and convert logic are defined by the non format-specific classes in the package, with specific forms of the classes BMM_SCHEMA_DESCRIPTOR and BMM_SCHEMA required for each concrete format. The package above shows the relevant classes for the P_BMM version 2.x format, which is normally saved in .bmm files. Other formats may be saved in files with different extensions.

The singleton class BMM_MODEL_ACCESS acts as the entry point for client software to obtain access to loaded BMM models. Since the latter start as schema files which are typically nested according to an 'include' hierarchy, they must be parsed, validated and merged to create each 'top-level' model. The schemas are accessed via instances of the BMM_SCHEMA_DESCRIPTOR object, one for each schema file. The load() routine loads a BMM schema file by direct deserialisation.

If the file is structurally correct (say ODIN, JSON etc), an in-memory schema instance will result (e.g. P_BMM_SCHEMA in the case of the P_BMM format), and its validate_created method called. If this succeeds, SCHEMA_DESCRIPTOR.schema will be set to this instance. Subsequently, schema.merge() will be called repeatedly, which results in each schema instance being the merged result of its include children and itself. After merging, BMM_SCHEMA_DESCRIPTOR.validate_merged() will be called, and if successful, a call to create_model() will result in BMM_SCHEMA_DESCRIPTOR.model being populated.

Each successfully loaded model is thus instantiated as a BMM_MODEL, and referenceable via BMM_MODEL_ACCESS.valid_models, which keys models by model identifiers (BMM_SCHEMA_CORE.identifier). The methods model_for_namespace() and model_for_namespace() are used to access a given model for a namespace to which the model applies.

The following screenshot shows the BMM schema configuration dialog in the AWB, including some meta-data, validation status etc, and also the schema nesting structure. A single hierarchy of schemas corresponds to a single instantiated BMM model.

The screenshot below shows a number of merged BMM models loaded into the AWB, including some of the packages and classes for the openehr_ehr_extract_1.0.4 model.

The core package defines the main BMM model. The following figure shows it in overview.

A BMM model is structured in the same basic way as a UML model, i.e. with a hierarchical package containment structure and a set of class definitions. Class definitions consist of property definitions, each of which refers to a type, which in turn refers to a 'base class'.

In a BMM model, names typically appear in the common case-sensitive form used by the model users, and may therefore follow one of a number of common conventions, including 'camel case', 'snake-case' and so on. When used computationally within an instantiated BMM model, it is assumed that case-insensitive matching is used. This means that the class name "Hashable" refers to the same class as "HASHABLE". Note however that underscores are not removed during matching, so that the classes "HashMap" and "HASH_MAP" are understood as different classes.

In BMM, packages have the same role as in UML - as non-semantic organisational logical containers of classes, usually corresponding to file system folders in software implementations. They provide an organisational convenience, and in an instantiated BMM model, contain references to class definitions. A model validity checker ensures that every class is contained within exactly one package.

Package paths are only used in BMM to specify package structures in the serialsed form in an efficient way, i.e. by using paths to avoid defining a hierarchy in which only lower packages contain classes. They are not used as namespaces as in UML. Consequently, all classes in a BMM model should be uniquely named.

A documentation attribute is inherited from BMM_MODEL_ELEMENT into BMM_CLASS, BMM_PROPERTY, BMM_MODEL and BMM_PACKAGE (the latter two via BMM_PACKAGE_CONTAINER), enabling packages, classes and properties to be individually documented.

The BMM_MODEL class defines the single instance of each distinct BMM model that may exist within a collection of models, such as shown in the model_access package above. It provides an interface that enables any class definition to be retrieved, as well as various accessor functions to interrogate the model. A BMM Model has a name (model_name attribute) that is used to identify the model as a whole within a system using multiple models. It contains a number of other meta-data attributes describing authorship etc, and otherwise contains a list of package and class definitions.

The following UML diagram shows the BMM model of classes and types, collectively known as entities.

The general structure of a BMM consists of a set of classes, whose features (properties, routines) are each typed by an instance of BMM_TYPE. The following shows the typing of properties. Structures specific to generic and container types are shown in relevant sections below.

One of the foundational distinctions in the BMM is between class and type, in common with the type systems of the modern forms of most object-oriented languages, but in contrast to the UML meta-model. Classes are definitional entities, while 'type' has two meanings:

In a static model, types are references. For simple types, they refer to the corresponding simple class definition, but for generic types, they refer to a particular usage of a generic class definition. A generic class may generate numerous types.

This central division is reflected in the two classes BMM_CLASS and BMM_TYPE. The common parent class BMM_ENTITY defines a small number of properties that classify both classes and types in a model: entity_metatype, is_abstract and is_primitive. These are combined to produce a String classifier entity_category, which can be used to help visualise elements of a BMM model.

The Boolean attribute is_abstract on an entity indicates an abstract class in a BMM model, or a type based on an abstract class. The attribute is_primitive indicates that a class in a BMM model is considered to be part of a primitive type set (typically corresponding to primitive types in another type system); for types, it is derived from the setting of the base_class. Primitive status has no effect on BMM model semantics, and is provided as a convenience for visualisation and type-system mapping.

The taxonomy represented by BMM_ENTITY.entity_category is illustrated below.

Types are understood as the formal classifiers of object instances in BMM, in both a static sense and dynamically, i.e. at execution time, when polymorphic attachment is possible. Types are defined indirectly via the definitions of classes and their constituent parts. Types are used for three purposes in a BMM model:

Every type entity can be mapped back to its generating class(es), which provide the definitional basis for the type. The BMM class BMM_TYPE and its descendants define the kinds of types available in a BMM model. The BMM_TYPE class includes features common to all meta-types:

Below BMM_TYPE are the abstract meta-type BMM_UNITARY_TYPE and the concrete meta-type BMM_CONTAINER_TYPE and its specialisation BMM_INDEXED_CONTAINER_TYPE. BMM_UNITARY_TYPE corresponds to meta-types whose instances are unitary i.e. singular, while the container meta-types correspond to collections of instances. The latter are further described below. This division is made to enable BMM to directly support collections in the type system.

Unitary meta-types are further distinguished as either formal generic parameters (BMM_PARAMETER TYPE) and defined types, i.e. types with class definitions, via the abstract meta-type BMM_DEFINED_TYPE. The subtypes of the BMM defined meta-type are BMM_SIMPLE_TYPE and BMM_GENERIC TYPE, corresponding to the standard notions of type familiar in modern programming languages. The class definitions of instances (i.e. BMM model class deifintions) of these meta-types are available via the property _base_class, of meta-type BMM_CLASS for a BMM simple type, and BMM_GENERIC_CLASS for BMM generic type.

A simple type is a type based only on a simple class, which is a class with no formal generic parameters. An instance of a simple type is fully described by the class on which it is based, with the ony difference being the usual object-oriented possibility of polymorphic attachments of sub-objects whose dynamic types conform to their static type counterparts in the original simle type. Thus, for example, a class Organisation may have a property managers of static type List<Person>. An instance of the simple type Organisation might have its managers property attached to an instance of List<Manager>, which is legal as long as Manager conforms to Person, which it will do it the same-named classes inherit in the usual sense.

A generic type is any type based on a generic class, which has one or more open type parameters that are substituted for actual types in its declaration. For example, the generic type Interval<Quantity> can be used in a model that contains the generic class Interval<T:Ordered> and Quantity. A typical programmatic usage of such a type, and its instantiated BMM model structure are shown below.

The parameters of a generic type may be:

Consequently, a generic type may be:

The feature is_partially_closed () defined on BMM_GENERIC_TYPE can be used to distinguish the latter two cases.

The following diagram shows the BMM instance structure created for a generic type based on a generic class and another generic type.

The following shows the BMM instance structure of a generic type that is fully open.

In object-oriented type theory, 'container' types are generic types whose outer class happens to have the semantics of a container object, such as a list, set etc. Container types such as List<T> and Set<T> are used ubiquitously in object models. In the BMM, containers and non-container generic types are distinguished via the meta-classes BMM_GENERIC_TYPE and BMM_CONTAINER_TYPE. This allows the BMM to treat container types in a special way. A BMM_CONTAINER_TYPE can be thought of as a 1:N counterpart to a BMM_UNITARY_TYPE, such as the type List<Paragraph> with respect to Paragraph. BMM_GENERIC_TYPE is typically used for objects considered to be singular, but whose types are a product of the base class and one or more parameter types, e.g. Interval<Quantity>.

The explicit provision of BMM_CONTAINER_TYPE enables BMM models to mention logical linear container types such as Array<T>, List<T> and Set<T>, on the assumption of their standard semantics in computer science , without worrying about providing concrete types which may be numerous and also variable across programming languages, e.g. ArrayedList<T>, LinkedSet<T>, ArrayedStack<T> and so on. (This corrects one of the errors in UML, which does not represent containment via typing, but via cardinality, and uniqueness constraints.)

The following diagram shows how the container type List<Paragraph> is represented in a BMM model.

One other container type is also ubiquitous in object models and object-oriented programming: indexed containers, commonly known under the type name Hash<K,V>, HashMap<K,V>, HashTable<K,V>, Dictionary<K,V> and so on. This type always takes two parameters, a key type and a value type. The key type must be such that hash values can be generated, and may be any type, but practically speaking, is almost always a String or Integer, or a Date/Time type if such exists.

The indexed container is represented by the meta-type BMM_INDEXED_CONTAINER_TYPE, which inherits from BMM_CONTAINER_TYPE, and adds the property index_type. The following diagram shows how the container type Hash<String, Person> is represented in a BMM model.

In object-oriented theory, the important relationship between types is substitutability, which governs which instances may be dynamically attached to property references of particular declared static types. In the BMM, a type is conformant to another type if the base classes of its constituent elements are inheritance descendants of the corresponding elements of the other type. This is known in object-oriented type theory as covariant conformance.

An algorithm to determine conformance of two type-names (e.g. to implement BMM_MODEL.type_conforms_to()) is as follows:

This section describes the semantics of the BMM_CLASS meta-class, its sub-types, constituent parts and relationships. The parts of a class are collectively known as features, and consist of functions, procedures, constants and properties. The following UML illustrates classes and relationships to constituent feature meta-types. (Features are described in detail in the following section.)

Class definitions are the definitional basis of a BMM model, i.e. they are the means of defining the types that are statically used in the model, and the dynamic types generated at runtime. Types are thus derived entities.

BMM distinguishes between simple and generic class definitions via two descendants of BMM_CLASS, i.e. BMM_SIMPLE_CLASS and BMM_GENERIC_CLASS, with the first providing a concrete form of BMM_CLASS that applies to non-generic classes, and the latter defining the additional semantics of generic classes. The meta-type BMM_ENUMERATION is a specialisation of BMM_SIMPLE_CLASS used to represent enumeration classes in BMM models. The non-simple meta-types are further described below.

The enumeration meta-type adds a set of enumeration labels and optional String or Integer values, in the manner of contemporary languages such as Java and C#. This meta-type allows classes to be declared in a BMM to be enumerations without either having to manufacture a representation from simple class definitions, or having to replicate the representation of enumerations in some target language. The following screenshot shows how a BMM integer enumeration class appears within a BMM model.

The types String and Integer are assumed to be defined via primitive classes of the same names.

The generic class meta-type BMM_GENERIC_CLASS adds generic parameters to BMM_CLASS, enabling formal generic parameters to be represented. Each such parameter is expressed using an instance of BMM_PARAMETER_TYPE which names the parameter and optionally allows a type constraint to be associated with it, in the usual object-oriented fashion. In BMM, formal parameters have single-letter names, such as 'T', 'U' etc, following typical usage in programming languages. The following example shows a generic class Interval<T:Ordered>, which is a class Interval with one formal parameter T constrained to be of type Ordered or any descendant.

Any class definitions can be marked as being 'primitive' within a BMM model, enabling them to be visualised and queried as a separate group without otherwise impacting on the semantics of the entity in BMM meta-type system. The following shows part of a BMM model in which a number of classes are classified as primitive (shown in light and dark grey).

Primitive classes are normal BMM classes, other than being marked primitive for convenience, and do not have different semantics.

Within the definitions of each class in a BMM model are found the definitions of its features, consisting of routines, properties and constants. The overall meta-model of features, as well as the elements that occur within them, namely parameters and local variables is shown below, and described in this section.

The abstract classes in this model that define the taxonomy of types are as follows:

Class features consist of the formal sub-parts of a class, namely:

All formally defined model elements (i.e. instances of the meta-type BMM_FORMAL_ELEMENT) have a scope, represented by the scope meta-attribute. The scope meta-type indicates the kind of model element within which the current element is scoped, and the value

The is_nullable attribute of the meta-class BMM_MUTABLE indicates whether instances are optional or mandatory within their context, i.e. whether the value of the reference may be null (or 'void') at execution or persistence time. This flag maps on to the UML notion of optionality (i.e. whether a property or routine parameter has [0..1] existence) and also to the broader notion of void-safety.

In modelling or programming terms, the features defined on a particular class within a model constitute the features it introduces with respect to its inheritance parent(s). We can think of this list of features as the differential set. A 'top-level' class with no declared inheritance ancestor is considered to inherit by default from the Any class, and its feature set is relationally differential to the top class.

In contrast, the effective set of features for an instance at runtime is the result of evaluating these lists of features down the inheritance hierarchy to obtain the flat set of features. The features properties and flat_properties defined on BMM_CLASS provide access to these two lists for any class.

All class features have formal signatures. The simplest type of signature is that of properties and constants, which may be expressed formally as follows:

This indicates that both meta-types have a return type, being the type of the value they are attached to at execution time.

The two types of routines, i.e. functions and procedures include 0 or more formal parameters in their signatures, with functions also having a return type. The general form of routine signatures is thus as follows:

Typical examples of function signatures:

Typical procedure signatures include the following:

Constant features in a class are represented by the BMM meta-class BMM_CONSTANT, which is an immutable descendant of BMM_EVALUABLE. A constant has a value, which may be of any type, including complex types. The scope of a constant is its enclosing class.

Class properties are defined via the meta-class BMM_PROPERTY, and its two subtypes, BMM_UNITARY_PROPERTY and BMM_CONTAINER_PROPERTY, corresponding to the unitary and container type meta-types. The BMM_PROPERTY meta-type defines semantics common to all properties, including type, a reference to an instance of BMM_TYPE representing the class property type in the BMM model.

Functions and procedures are kinds of routine, which are computational features of a class. In BMM, they are represented, along with constituent parts, namely parameters and local variables by descendants of the class BMM_FORMAL_ELEMENT.

The formal parameter definitions of both kinds of routines are represented by an ordered list of instances of the meta-class BMM_PARAMETER, which is understood as a kind of variable scoped to the owning routine. A formal parameter may optionally have the read/write direction defined, which indicates whether the variable contains an input value, should only be written to, or both, i.e. read then written to. The inherited is_nullable meta-attribute indicates whether each parameter is mandatory or not.

An additional feature of the meta-model for functions is the notion of operator, which supports the representation of a function call in a formal expression as an operator symbol with one or two operands, in the typical form found in programming languages and first order logics. The BMM approach considers an operator as an optional addition to any function of arity 1 or 2 that may reasonably be represented in an abstract syntax using operator syntax. Operators thus support the use of expressions like weight > 90 to mean weight.gt (90), where weight is of type Real, and the function gt(other: Real) is defined.

At the finest level of detail of a model definition are what are typically thought of as (local) variables and (literal) values. These are represented by the classes BMM_LOCAL and BMM_VALUE respectively. Both variables and values have a type, with type being inferred for the latter from its value when parsed or otherwise created.

The BMM supports single and multiple inheritance, although it does not distinguish between different types of inheritance relation as some programming languages do. Inheritance is formally defined to be between a class definition (an instance of BMM_CLASS) and a defined type, i.e. a BMM_SIMPLE_TYPE or BMM_GENERIC_TYPE. This is because the inheritance parents of a class may be any of:

The general case for all three is represented by the corresponding type, i.e., a simple type or generic type.

The evaluation of inheritance relations defined in a BMM model results in an acyclic graph such that ancestors and descendants can be visualised for any class. The following screen shot shows the ancestors view of a class OBSERVATION.

The next screenshot shows the descendants view of one of the ancestor classes of the same class.

Inheritance between generic classes works in the same way as for simple classes, with the additional semantics of formal parameter inheritance, which are as follows:

The following example shows the class DV_INTERVAL<T:DV_ORDERED> inheriting from Interval<T:Ordered>. Here the number of open generic parameters remains unchanged, while the type constraint Ordered is being covariantly narrowed to DV_ORDERED, which inherits from the Ordered type.

A simple class may also inherit from a closed generic type, with the parameters of the latter fixed to specific type(s), as shown in the following example.

The general case is that any number of formal generic parameters may be substituted or left open down the inheritance lineage, as shown by the variants in the following example.

Multiple inheritance is typically used in the definition of classes that have a Liskov substitution inheritance relation as well as a re-use inheritance relation. The following shows a class DV_INTERVAL<T> multiply inheriting from Interval<T> and DATA_VALUE, where the latter is considered the substitutable type, and the former an interface re-use.