Proposal: Decouple SAMM content from SAMM core

Decouple SAMM content from SAMM core

State of the art

Currently, SAMM comprises the following parts:

• Meta Model:
  • Formal description
    • Definitions (RDF/RDFS) - samm: namespace
    • Shapes (SHACL)
  • Textual description
• Shared Characteristics, Characteristic Instances
  • Formal description
    • Definitions (SAMM ) - samm-c: namespace
    • Shapes (SHACL)
  • Textual description
• Shared Entities and corresponding Properties
  • Formal description
    • Definitions (SAMM) - samm-e: namespace
  • Textual description
• Shared catalog of units, based on UNECE Rec20
  • Formal description
    • Catalog (SAMM) - unit: namespace

The following diagram visualizes this architecture (showing SAMM under its previous name BAMM) :

All four namespaces (samm, samm-c, samm-e, unit) as well as the different parts of the textual description are all part of the "SAMM" release. This means that the textual description of the SAMM specification contains the descriptions of the meta model, the shared model elements and the units catalog. Implementations (i.e., in the SDKs) also rely on the structure in that they consider "SAMM" one monolithic artifact that consists of the formal descriptions of both the meta model and the shared model elements. The motivation for this structure is three-fold: Firstly, coherent and consistent releases are made easy; a user can always be sure that model elements that came with a certain SAMM version match the corresponding meta model version. Secondly, the structure requires no overhead in terms of supporting infrastructure, such as additional git repositories and corresponding build scripts that tie a release together. Lastly, the lack of a well-defined package/versioning concept that allows the clean definition of bundles or packages and the dependencies between them impedes decoupling the core meta model from libraries of model elements.

We can make the following observation that is not considered a problem: A meta model release comes with a "standard library" of model elements. This is not unlike a Java release coming with a compiler, a runtime system and the java.* standard library packages. It can reasonably be considered an advantage to facilitate authoring models.

Problems with the state of the art

There are three main problems with the current state that need to be solved:

1. Because the shared model elements are considered a part of the overall SAMM release, their formal definition uses facilities that are not available to regular modelers. Concretely, this means that the shared model element catalog contains Characteristics (e.g., samm-c:Quantifiable) with particular attributes (e.g., samm-c:unit) and accompanying SHACL shapes that define the semantics of their usage. A modeler building an Aspect Model could create their own instance of samm:Characteristic, but they would have no modeling facility to use that could introduce their own Characteristic class with its specific attributes, with SHACL shapes to control usage and structure of the attributes. The concept of an "attribute" is only part of the meta-meta-model used to define the SHACL shapes of SAMM itself, but it is not available to a modeler. While bundling a "standard catalog" of model elements with the meta model is a good thing, limiting the possibilities for the definition of certain model elements to the scope of the meta model release is not.

2. Because the shared model elements are treated differently than model elements that are defined by regular modelers, their documentation is also treated differently. The documentation of the shared model elements is manually written and maintained as part of the SAMM specification, while documentation for model elements by regular modelers are generated from the element definition itself, but uses a different layout and content.

3. The organization of models and model elements into hierarchical namespaces is enabled by having a well-defined URI scheme for identifiers of model elements. However, the mechanism to resolve an aspect model element URI to its corresponding element definition is out of scope in the SAMM specification. A separation of the shared model elements from the meta model definition would thus require a proper definition of how model elements are organized in namespaces that can be shared as units, and how they can be referred to.

Solution proposal

Shared model elements should be defined and treated like any other regular model element that just happen to be bundled with the meta model. The mechanisms for their specification and documentation should be no more or less powerful than those that are available for regular model authoring.

Therefore the following steps should be taken:

1. The SAMM textual documentation should have as inputs only the meta-model related parts and the formal definitions of the shared model elements. In other words, the sections on https://eclipse-esmf.github.io/samm-specification/snapshot/characteristics.html (after the introductory section) and https://eclipse-esmf.github.io/samm-specification/snapshot/entities.html should be entirely generated from the respective element definitions. This implies moving descriptive text from the currently manually maintained description text into the samm:descriptions of the elements. The layouts by the current shared model element sections in the SAMM specification must be unified with the structure and layout of the HTML documentation that is generated by the sds-sdk tooling for Aspect Models. Furthermore, this may imply enhancing the specification of the allowed content of samm:description to allow markup such as Asciidoc or Markdown.

2. The definition of attributes on Characteristics must be made a first-class modeling primitive in SAMM, thus allowing a model author to define Characteristics such as those in the shared elements catalog. A modeler must have the possibility to define Characteristics such as samm-c:Measurement. Characteristics inheritance must be cleanly specified (see https://github.com/eclipse-esmf/esmf-semantic-aspect-meta-model/issues/148 ) and if it is used in SAMM (as it is currently done, as shown by the Characteristics inheritance tree diagram) then it must also be available as a modeling feature.

3. It must be possible for a model author to specify the SHACL shape(s) that accompany a Characteristic. It might be desirable to limit allowed SHACL primitives to a subset to reduce complexity; this needs to be examined in detail. To make that more clear: The SHACL shapes may be used to limit usage, value ranges etc. of Characteristic attributes, i.e., they refer to the model level. SHACL shapes may not refer to the runtime data level as this would massively increase modeling and implementation complexity.

4. It must be investigated if and how it is possible to formalize the mapping of payloads that correspond to a Characteristic and whether it is possible to make this mapping an optional part of a Characteristic definition. Currently the payload mapping for Characteristics is "hard-coded" (i.e., part of the specification), so it would not be possible to move the Characteristics definitions for e.g. samm-c:Collection or samm-c:Either outside the scope of the SAMM without breaking their payload mapping.

To visualize the proposed changes, the following shows the updated architecture: