[Task] Asset Administration Shell - describe semantics of RelationshipElement submodel element

[BirgitBoss]

Is your task related to a problem? Please describe.
SAMM shall support the semantic definition of relationship and annotated relationship submodel elements in the Asset Administration Shell (AAS).

Describe the solution you'd like
Introduce a predefined characteristic "Relationship" with two attributes first and second. "First" relates to "second" as described in the description of the property. The values of first and second are not predefined and subject to inheritance.

Example:for instance:
Door with ID=1223 isPartOf PessengerCar with id=XYZ
semantic of Property with Relationship Characteristic =
isPartOf between (first) CarParts and (second) Vehicle

Note: in AAS the relationship is between existing elements, thus just references. For example the Door instance with ID =1223 might be described in a different twin than the Vehicle instance with id=XYZ.

Describe alternatives you've considered
none

Additional context
see also #138 (reference element)
https://industrialdigitaltwin.org/wp-content/uploads/2021/09/07_details_of_the_asset_administration_shell_part1_v3_en_2020.pdf

Updated in the meanwhile:
https://industrialdigitaltwin.org/content-hub/aasspecifications
Look for Part 2

[atextor]

A agree that for modeling custom relationships beyond Properties there should be a well-defined way. I think for that, there are three ways in principle:

1. Add relationships as a meta model element. This approach has not real benefits: It would increase the size of the meta model while not contributing anything that can't be expressed in other, more flexible ways as well. For this reason I would not investigate this further.
2. Create a Relationship Characteristic as suggested above (I would prefer "Relationship" as a name over "RelationshipElement", since it is a model element and the -Element suffix is redundant), with first and second attributes of a reference type. I think this implies solving [Task] Asset Administration Shell - describe semantics of ReferenceElement submodel element #138 first to have Reference available.
   
   However, for introducing the AnnotatedRelationShipElement and the inheritance from Relationship in a clean way, it might be favorable to first address cleaning up the definition of Characteristic inheritance: [Task] Clean definition of Characteristic inheritance #148. Also, a think a discussion is warranted on this: Should the mechanism of annotating data not be applicable to other structural/model elements than relationships as well (for example, on an Entity)? Even more importantly: Does the payload for a RelationshipElement looks different than the one for an AnnotatedRelationshipElement? If yes, then modeling this a Characteristics might not be right approach after all.
3. The third approach is the most straightforward albeit semantically slightly questionable: Create Relationship as a shared Abstract Entity (i.e., in bamm-e), with first and second as Abstract Properties. Then AnnotatedRelationShipElement could be defined as a regular Entity that extends the Abstract Entity. Unfortunatly I could not find a JSON payload example for usage of RelationShipElement in the linked AAS specification document, but I think the mapping should be straightforward.

Personally I'd prefer option 2 (Characteristic, as proposed), but with Characteristic inheritance cleanly defined first and having a clear description of how the annotations should be handled.

[chris-volk]

From https://industrialdigitaltwin.org/content-hub/downloads https://industrialdigitaltwin.org/wp-content/uploads/2021/11/Details_of_the_Asset_Administration_Shell_Part_2_V1.pdf Details of the Asset Administration Shell - Part 2 Page 88:

For a RelationshipElement named “CurrentFlowsFrom” the payload is minimized to the following:

{
   "CurrentFlowsFrom":{
      "first":[
         {
            "type":"Submodel",
            "value":"http://customer.com/demo/aas/1/1/1234859590"
         },
         {
            "type":"Property",
            "value":"PlusPole"
         }
      ],
      "second":[
         {
            "type":"Submodel",
            "value":"http://customer.com/demo/aas/1/0/1234859123490"
         },
         {
            "type":"Property",
            "value":"MinusPole"
         }
      ]
   }

[atextor]

For adding support for RelationshipElement, we must first clarify on which meta model level theses references are located. As opposed to AAS, in SAMM the model level is clearly separated from the data (instance) level. So in the terminology of ISO/IEC 42010 (M0 = instance level, M1 = model level, M2 = meta model level, M3 = meta meta model level), JSON data is M0, the Aspect Model is M1, SAMM is M2 and RDF+SHACL is M3. For the RelationshipElement, the distiction between M1 (model) and M0 (data) is relevant. For a regular Aspect Model, this looks like this:

Now my question is, is the RelationShip expressed from M1 to M1, M0 to M1 or from M0 to M0?

Proposal 1: Only on model level (M1 to M1)

This proposal corresponds to the second bullet point in my previous post.
You mention that the relationship is between elements (of the model I presume). This means, I would expect to model this as a Characteristic, which can have additional attributes that refer to arbitrary model elements. But what whould that mean for the M0 level? What does a Property using this Characteristic mean?

Proposal 2: Data to model references (M0 to M1)

This proposal solves the problem of proposal 1, and corresponds to the third bullet in my previous post. We model the relationship as an Entity, with Properties that refer to the identifiers of model elements (in this example using the samm:curie datatype, used in the same way as the Unit Reference Characteristic:

This works, but has a major shortcoming: It delegates the expression of relationships between model elements to the implementers of the Aspect. The author of the Aspect Model can not relate model elements. Furthermore, it might confuse developers who only look at the JSON payload, they might mistake the reference that actually points to a model element for a reference to some other JSON key in the same document - this happens to align in most cases, but falls apart once samm:payloadName is used for a Property.

Proposal 3: Data to data references (M0 to M0)

This is essentially using JSON References, as specified and popularized by OpenAPI's $ref properties. One JSON property has a value that refers to another place in the same document (or in a document in another file).

This alleviates the problem of references crossing meta-model-level-boundaries, but it retains the problem that relationships can not be expressed by the modeller.

Summary

I'm not happy with any of the proposals. (1) is not usable, (2) and (3) are error-prone and violate the separation of semantic description with data. Schema and comparable information does not belong into the data itself. If you have any other idea of how to approach this and would like to visualize it, I'll attach the sources of the diagrams (.graphml format).
2023-12-12-aas-samm-relationship.zip

[BirgitBoss]

From https://industrialdigitaltwin.org/content-hub/downloads https://industrialdigitaltwin.org/wp-content/uploads/2021/11/Details_of_the_Asset_Administration_Shell_Part_2_V1.pdf Details of the Asset Administration Shell - Part 2 Page 88:

For a RelationshipElement named “CurrentFlowsFrom” the payload is minimized to the following:

{
   "CurrentFlowsFrom":{
      "first":[
         {
            "type":"Submodel",
            "value":"http://customer.com/demo/aas/1/1/1234859590"
         },
         {
            "type":"Property",
            "value":"PlusPole"
         }
      ],
      "second":[
         {
            "type":"Submodel",
            "value":"http://customer.com/demo/aas/1/0/1234859123490"
         },
         {
            "type":"Property",
            "value":"MinusPole"
         }
      ]
   }

With V3.0 it is (Page 103), Besides Model References also external references are allowed