Home

ES-DOC CIM

This repository is now (or will be, by April 2016) the formal specification of the es-doc Common Information Model (CIM).

It will include the pythonic definitions of schema and project specific specialisations (e.g. for CMIP6), along with formal specifications of how those pythonic definitions work for:

• The primary CIM (CIM2.0 and upwards is defined here), and
• The specialisation notation used for projects.

(Versions prior to CIM2.0 are also included here, but the primary definitions were in UML, transposed to XSD, so the V1 schema are the primary representations used in the es-doc software stack.)

Some History

In the beginning, the CIM was defined using three architectural layers and a vocabulary layer. The three architectural layers were:

• The "CIM Metamodel", that is, a set of rules of how we would use UML to define the CIM.
• The Conceptual CIM (ConCIM), that is, the CIM defined in UML using the CIM metamodel, and
• The Application CIM (ApCIM), that is, the implementation of the UML using XML schema, which allowed actual CIM documents (in XML) to be validated against XSD representations of the CIM.

The vocabulary layer effectively treated one particular (the Model) CIM document as a special case, by defining a set of nested component descriptions each of was effectively a set of (key, value, docstring) properties and a list of possible sub-components defined in teh same way. This allowed "standardised" comparison of models since they all used the same structure of components and property keys.

These prescribed lists of components and their possible properties were defined in mind-maps, and machinery was built to (effectively) take these definitions and populate XML documents which needed only to be completed by adding the various values to the properties in the trees of components.

Machinery was developed to exploit these XML documents which depended on a python rendering of the XSD content, and then allowed CIM documents to be instantiated in more than just XML, using (amongst other things) python objects to instantiate CIM documents. In essence, this pythonic representation implements the ApCIM. This pythonic representation has been (pre 2016) known as the "mp" formalism, since it formed part of the es-doc metaprogramming framework.

In practice, the esdoc meta-programming framework has all the conceptual parts required to define the CIM, there is

• A metamodel, which is implicit in the rules used to define what may appear in the schema definitions used in the metaprogramming framework,
• A conceptual model, consisting of the schema definitions (e.g., CIM1.5) themselves, and
• Multiple application instances produced by using the esdoc-mp software to produce a python class instances - e.g. CIM1.5 - capable of being imported and used to create, manipulate, and render CIM instances.

Current State

As part of the development of CIM2, a de facto decision was taken to move the primary CIM representation into a pythonic representation based on the existing mp framework. Of necessity the mp framework has evolved, in part because of new requirements from CIM2, and in part because of a blurring of concerns between the concepts of metamodel, ApCIM, and ConCIM. This blurring has been further compounded by the decision to use the same mp framework to define the vocabularies - since they were effectively specialisations of components in CIM1.5, we have chosen in CIM2 to actually make them specialisations. However, because these specialisations are restricted in a number of ways, we have decided to use a more compact notation to define them, which means there is a new metamodel in play as well:

• the compact notation metamodel which describes how to build "mp-aware" CIM2 vocabulary specialisations.

So, as of today, we have

• An implicit metamodel for the metaprogramming framework
• Two meta-programming software stacks which makes explicit that metamodel to produce class instances which can manipulate CIM content provided it conforms to
• Schema definitions defined either using the
  • Primary (implicit) metamodel as python functions which return dictionaries, or
  • (one of two candidate) compact notation metamodels for the extension vocabularies.