Relationship Element

Overview

A RelationshipElement is a SubmodelElement used to express a relationship between two references: first and second. Each reference points to another element or concept within or outside the Asset Administration Shell.

Unlike scalar or collection-based SubmodelElements, a RelationshipElement always contains two references that together define the meaning of the relationship.

DataEngine supports RelationshipElement by applying a deterministic semanticId expansion strategy that allows unambiguous resolution of both references via Plugins.

Semantics and intent

• A RelationshipElement represents a directed relationship between two references.
• The relationship semantics are defined by a single semanticId.
• The two references have distinct roles:
  • first: source reference
  • second: target reference
• Both references may be of type ModelReference or ExternalReference.
• Because both references share the same semanticId, ambiguity arises during value resolution if no additional differentiation is applied.

How DataEngine handles RelationshipElement

DataEngine applies the following handling rules for RelationshipElement elements:

• The base semanticId is extracted from the template during submodel or submodel element requests.
• To avoid ambiguity, DataEngine derives reference-specific semantic IDs using a configurable separator:
  • <semanticId>_first
  • <semanticId>_second
• Derived semantic IDs are generated only for references of type ModelReference.
• ExternalReference values are treated as static and must be provided by the template.
• DataEngine requests values for the derived semantic IDs from the Plugin.
• Returned values are mapped back to the corresponding first or second reference.
• This approach ensures a clear one-to-one mapping between semantic IDs and reference values.

Example

Submodel template (from Template Repository)

{
  "modelType": "RelationshipElement",
  "idShort": "HasPart",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "https://admin-shell.io/idta/HierarchicalStructures/HasPart/1/0"
      }
    ]
  },
  "first": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "http://admin-shell.io/aasx-package-explorer/functions/asciidoc/heading1/1/0"
      }
    ]
  },
  "second": {
    "type": "ModelReference",
    "keys": [
      {
        "type": "Submodel",
        "value": ""
      }
    ]
  }
}

Value provided by Plugin

The Plugin returns values for the reference-specific semantic IDs. As first is ExternalReference, DataEngine will not ask plugin for its value.

{
    "https://admin-shell.io/idta/HierarchicalStructures/HasPart/1/0": {
        "https://admin-shell.io/idta/HierarchicalStructures/HasPart/1/0_second": "https://mm-software.com/submodel/000-001/Nameplate"
    }
}

DataEngine response to user

DataEngine maps the resolved values back to the corresponding references while preserving template structure.

{
  "modelType": "RelationshipElement",
  "idShort": "HasPart",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "https://admin-shell.io/idta/HierarchicalStructures/HasPart/1/0"
      }
    ]
  },
  "first": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "http://admin-shell.io/aasx-package-explorer/functions/asciidoc/heading1/1/0"
      }
    ]
  },
  "second": {
    "type": "ModelReference",
    "keys": [
      {
        "type": "Submodel",
        "value": "https://mm-software.com/submodel/000-001/Nameplate"
      }
    ]
  }
}

Constraints and behavior

• RelationshipElement must clearly distinguish between first and second references.
• Derived semantic IDs are created only for ModelReference entries.
• ExternalReference values must be fully provided by the template and are not modified.
• Template authority is strict:
  • No adding or removing references
  • No changing reference roles or order
• If a plugin does not return a value for a derived semantic ID, DataEngine falls back to the template value.
• Missing references are handled gracefully without failing the entire request.