Reference Element

Overview

A ReferenceElement is a SubmodelElement used to reference another model element or an external concept.Unlike value-carrying elements such as Property, Range, File, or Blob, a ReferenceElement does not contain a scalar or binary value.Instead, it encapsulates a structured Reference that represents a navigation path to another element.

The structure, key types, and order of this reference are defined by the template and must be preserved exactly.

Semantics and intent

• A ReferenceElement represents a pointer, not a value.
• The semanticId defines what kind of reference this element represents.
• The actual reference is stored as a Reference object.
• A Reference consists of an ordered list of keys, where:
  • Each key has a type and a value.
  • The order of keys is semantically significant.
• Because ReferenceElements encode structure and navigation rather than data, runtime population must preserve template authority.

How DataEngine handles ReferenceElement

DataEngine applies the following handling rules for ReferenceElement elements:

• The semanticId is extracted from the template during submodel or submodel element requests.
• Only ModelReference values are dynamically populated.
• ExternalReference values are treated as static and must be fully provided by the template.
• The template remains authoritative for:
  • Key types
  • Key order
  • Number of keys
• DataEngine never adds, removes, reorders, or changes key types.
• For dynamic population, DataEngine uses semanticId expansion per reference key:
  • For each key in a ModelReference, a derived semantic ID is generated using: <BaseSemanticId>_<KeyType>[_<Index>]
  • These derived semantic IDs are requested from the Plugin.
  • Returned values are mapped back to the corresponding keys while preserving order.
  • If a derived semantic ID is missing, DataEngine falls back to the template value.

Example

Submodel template (from Template Repository - For ModelReference)

{
  "modelType": "ReferenceElement",
  "idShort": "ReferenceToTechnicalPropertyArea",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "0173-1#02-ABL358#002"
      }
    ]
  },
  "value": {
    "type": "ModelReference",
    "keys": [
      {
        "type": "Submodel",
        "value": ""
      },
      {
        "type": "SubmodelElementList",
        "value": ""
      },
      {
        "type": "SubmodelElementCollection",
        "value": ""
      }
    ]
  }
}

This reference represents = Submodel → SubmodelElementList → SubmodelElementCollection

Value provided by Plugin

The Plugin returns values using dynamically derived semantic IDs.

{
    "0173-1#02-ABL358#002": {
        "0173-1#02-ABL358#002_Submodel": "https://mm-software.com/submodel/000-001/Nameplate",
        "0173-1#02-ABL358#002_SubmodelElementList": "Marketing",
        "0173-1#02-ABL358#002_SubmodelElementCollection": "0"
    }
}

DataEngine response to user

DataEngine maps the resolved values back into the ModelReference while preserving structure and order.

{
  "modelType": "ReferenceElement",
  "idShort": "ReferenceToTechnicalPropertyArea",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      {
        "type": "GlobalReference",
        "value": "0173-1#02-ABL358#002"
      }
    ]
  },
  "value": {
    "type": "ModelReference",
    "keys": [
      {
        "type": "Submodel",
        "value": "https://admin-shell.io/idta/SubmodelTemplate/TechnicalData/2/0"
      },
      {
        "type": "SubmodelElementList",
        "value": "TechnicalPropertyAreas"
      },
      {
        "type": "SubmodelElementCollection",
        "value": "0"
      }
    ]
  }
}

Constraints and behavior

• Only ModelReference values are dynamically populated.
• ExternalReference values must be provided by the template and are not modified.
• Key count may vary (1..N).
  • If the plugin returns fewer values than keys, remaining keys retain template values.
  • If the plugin returns more values than keys, excess values are ignored.