Entity

Overview

An Entity is a SubmodelElement used to represent an identifiable object within or outside an Asset Administration Shell (AAS). Unlike simple data-carrying elements, an Entity represents a thing that may itself contain other SubmodelElements or even nested Entities.

According to the IDTA AAS specification, an Entity can be of two types:

• SelfManagedEntity – the entity is managed by the current AAS
• CoManagedEntity – the entity is managed externally and only referenced

DataEngine supports Entity as a structural and hierarchical element, similar to a SubmodelElementCollection, with additional semantics around asset identity.

Semantics and intent

• An Entity represents a real or logical asset.
• An Entity may contain:
  • Other Entities
  • Properties
  • RelationshipElements
  • Any supported SubmodelElement
• Entities form hierarchical structures (trees).

Entity types

SelfManagedEntity

• The entity is owned and managed by the current AAS.
• The entity must be identifiable by either:
  • globalAssetId, or
  • one or more specificAssetIds
• These identifiers are part of the entity's semantic meaning and may require runtime population.

CoManagedEntity

• The entity is externally managed.
• Asset identifiers are not resolved or modified.
• The entity is treated as structural only.

How DataEngine handles Entity

DataEngine applies the following handling rules for Entity elements:

Common behavior (both entity types)

• The Entity semanticId is extracted from the template.
• DataEngine treats the Entity as a branch node in the semantic tree.
• All child elements inside statements are:
  • Parsed recursively
  • Requested from the Plugin using their own semanticIds
  • Populated using existing SubmodelElement handling rules
• Nested Entities are processed recursively.

SelfManagedEntity handling

For SelfManagedEntity, DataEngine performs additional identity resolution.

Global Asset ID:

• If the template contains globalAssetId:
  • DataEngine generates an additional leaf semantic node: <EntitySemanticId>_globalAssetId
  • This semanticId is sent to the Plugin.
  • The returned value is injected into globalAssetId.

Specific Asset IDs:

• If the template defines specificAssetIds:
  • Each SpecificAssetId must include its own semanticId
  • DataEngine extracts semanticIds from each SpecificAssetId
  • Each is treated as a leaf node
  • Plugin values are injected into the value field of the corresponding SpecificAssetId
  • The structure, names, and references of SpecificAssetIds are always template-defined and authoritative.

CoManagedEntity handling

• No additional semantic IDs are generated.
• globalAssetId is not resolved.
• specificAssetId resolution is not supported.
• DataEngine only processes child SubmodelElements defined in statements.

Example

Submodel template (from Template Repository)

A simplified, readable SelfManagedEntity template:

{
  "modelType": "Entity",
  "entityType": "SelfManagedEntity",
  "idShort": "Machine",
  "semanticId": {
    "type": "ExternalReference",
    "keys": [
      { "type": "GlobalReference", "value": "https://example.com/semantics/entity/machine" }
    ]
  },
  "globalAssetId": "",
  "specificAssetIds": [
    {
      "name": "Manufacturer",
      "semanticId": {
        "type": "ModelReference",
        "keys": [
          { "type": "ConceptDescription", "value": "https://example.com/cd/manufacturer" }
        ]
      },
      "value": ""
    },
    {
      "name": "SerialNumber",
      "semanticId": {
        "type": "ModelReference",
        "keys": [
          { "type": "ConceptDescription", "value": "https://example.com/cd/serialnumber" }
        ]
      },
      "value": ""
    }
  ],
  "statements": [
    {
      "modelType": "Property",
      "idShort": "PowerRating",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          { "type": "GlobalReference", "value": "https://example.com/semantics/power" }
        ]
      },
      "valueType": "xs:double",
      "value": ""
    }
  ]
}

Value provided by Plugin

{
  "https://example.com/semantics/entity/machine_globalAssetId": "https://example.com/assets/machine-001",
  "https://example.com/cd/manufacturer": "ACME Corp",
  "https://example.com/cd/serialnumber": "SN-883920",
  "https://example.com/semantics/power": "12.5"
}

DataEngine response to user

{
  "modelType": "Entity",
  "entityType": "SelfManagedEntity",
  "idShort": "Machine",
  "globalAssetId": "https://example.com/assets/machine-001",
  "specificAssetIds": [
    {
      "name": "Manufacturer",
      "value": "ACME Corp"
    },
    {
      "name": "SerialNumber",
      "value": "SN-883920"
    }
  ],
  "statements": [
    {
      "modelType": "Property",
      "idShort": "PowerRating",
      "valueType": "xs:double",
      "value": "12.5"
    }
  ]
}

Constraints and behavior

• The template is authoritative:
  • No adding or removing identifiers
  • No modifying semanticIds or names
• Only SelfManagedEntity supports:
  • globalAssetId resolution
  • specificAssetId resolution
• CoManagedEntity:
  • Does not support asset identity resolution
• DataEngine:
  • Does not infer missing identifiers
  • Does not generate new asset identifiers
  • Preserves entity hierarchy and ordering
• Missing plugin values result in empty fields.