Plugin

Purpose

The Plugin is a separate API and deployment that acts as the primary data source for DataEngine:

• Holds or connects to the actual data storage (Plugin DB).
• Exposes HTTP endpoints that understand semantic IDs and JSON Schema sent by DataEngine.
• Returns data and metadata in a shape that DataEngine can map into AAS submodels and submodel elements.

DataEngine itself remains stateless with respect to business values; it only orchestrates between templates and Plugin data.

Plugin Manifest

Each Plugin exposes its capabilities to DataEngine via a Plugin Manifest. The manifest tells DataEngine:

• Which semantic IDs the plugin can provide values for.
• Whether the plugin can provide Shell Descriptors and/or Asset Information.
• Where the plugin is hosted (URL) and how it should be addressed.

Conceptually, a manifest entry contains at least the following fields:

{
  "supportedSemanticIds": [
    "http://example.com/idta/digital-nameplate/thumbnail",
    "http://example.com/idta/digital-nameplate/contact-name",
    "http://example.com/idta/digital-nameplate/email"
  ],
  "capabilities": {
    "hasShellDescriptor": true,
    "hasAssetInformation": false,
    "hasAssetIdSearch": true
  }
}

Field Overview

• supportedSemanticIds
  List of semantic IDs that this plugin can serve. DataEngine uses this information to decide which plugin(s) to call for a given submodel or submodel element.

• capabilities
  Flags describing what kind of data the plugin can provide:

  • hasShellDescriptor – plugin can provide metadata required to build Shell Descriptors.
  • hasAssetInformation – plugin can provide assetInformation content for shells.
  • hasAssetIdSearch – plugin supports filtering shells by SpecificAssetId values. When true, DataEngine will pass an aastwinengine-assetids header to GET /metadata/shells to filter results. If false or absent, DataEngine returns 501 Not Implemented for asset ID search requests.

How DataEngine Uses the Manifest

• At startup, DataEngine loads one or more Plugin Manifests.
• For each request, it builds a semantic tree of required IDs and uses the manifests to:
  • Select the appropriate plugin(s) that support those semantic IDs.
  • Apply Multi-Plugin conflict rules when multiple plugins claim the same semantic ID.
• This allows adding or replacing plugins without changing DataEngine code—only the manifest configuration needs to be updated.

Endpoints

1. Manifest

1.1 Get Plugin Manifest

• Method: GET
• Route: /manifest
• Query parameters: None
• Request body: None
• Responses:
  • 200 OK – Returns the plugin manifest (JSON object describing plugin capabilities / configuration).

{
  "supportedSemanticIds": [
  ],
  "capabilities": {
    "hasShellDescriptor": true,
    "hasAssetInformation": false,
    "hasAssetIdSearch": true
  }
}

Summary: Returns the plugin manifest data used by the DataEngine to discover this plugin's capabilities.

---

2. MetaData

Base route: /metadata

2.1 Get Shell Descriptors (Paginated)

• Method: GET
• Route: /metadata/shells
• Query parameters:
  • limit (int, optional) – Maximum number of shell descriptors to return.
  • cursor (string, optional) – Cursor for pagination.
• Headers:
  • aastwinengine-assetids (string, optional) – JSON array of SpecificAssetId filter objects. When present, the plugin must return only shell descriptors whose asset IDs match at least one of the provided filters. Requires the hasAssetIdSearch capability to be true.

    [
      { "name": "serialNumber", "value": "SN-4711" },
      { "name": "batchId", "value": "B-0042", "semanticId": "http://example.com/ids/sm/batch" }
    ]

• Request body: None
• Responses:
  • 200 OK – Returns a ShellDescriptors containing a collection of shell descriptors and optionally a pagination cursor.

{
  "paging_metadata": {
    "cursor": ""
  },
  "result": [
    {
      "globalAssetId": "",
      "idShort": "",
      "id": "",
      "specificAssetIds": [
        {
          "name": "",
          "value": ""
        }
      ]
    }
  ]
}

Summary: Returns a paged list of Asset Administration Shell (AAS) descriptors known by the plugin.

---

2.2 Get Single Shell Descriptor

• Method: GET
• Route: /metadata/shells/{AasIdentifier}
• Route parameters:
  • AasIdentifier (string, required) – Base64-encoded AAS identifier.
• Request body: None
• Responses:
  • 200 OK – Returns a ShellDescriptor with metadata for the requested AAS.

    {
      "globalAssetId": "",
      "idShort": "",
      "id": "",
      "specificAssetIds": [
        {
          "name": "",
          "value": ""
        }
      ]
    }

Summary: Returns the descriptor metadata for a single Asset Administration Shell, identified by a base64-encoded AAS identifier.

---

2.3 Get Asset Information

• Method: GET
• Route: /metadata/assets/{shellIdentifier}
• Route parameters:
  • shellIdentifier (string, required) – Base64-encoded shell identifier.
• Request body: None
• Responses:
  • 200 OK – Returns an Asset with asset-level information for the given shell.

{
  "globalAssetId": "",
  "specificAssetIds": [
    {
      "name": "",
      "value": ""
    }
  ],
  "defaultThumbnail": {
    "path": "",
    "contentType": ""
  }
}

Summary: Returns asset metadata associated with a given shell, using a base64-encoded shell identifier.

---

3. Submodel Data

3.1 Query Submodel Data

• Method: POST
• Route: /data/{submodelId}
• Headers:
  • Content-Type: application/json
• Route parameters:
  • submodelId (string, required) – Base64-encoded submodel identifier.
• Request body:
  • JSON Schema defining the data query (optional, but must not be null).
  • If null, the request is rejected with 400 Bad Request.
• Responses:
  • 200 OK – Returns a JsonObject representing submodel data that matches the query.

{
  "SemanticId_of_ContactInformations": {
    "SemanticId_of_ContactInformation": [
      {
        "SemanticId_of_name": "Jane Smith",
        "SemanticId_of_description": "Software Engineer",
        "SemanticId_of_phone": "+49 987 654321",
        "SemanticId_of_fax": "+49 987 654320",
        "SemanticId_of_email": "jane.smith@example.com",
        "SemanticId_of_ipCommunication": [
          {
            "SemanticId_of_AddressOfAdditionalLink": "10.0.0.1",
            "SemanticId_of_TypeOfCommunication": "FTP",
            "SemanticId_of_AvailableTime": "08:00 - 18:00"
          }
        ]
      }
    ]
  }
}

Summary: Queries AAS submodel data for the given submodel identifier using a JSON Schema filter. The submodelId is base64-decoded internally before executing the query.

---

Relation to DPP-Plugin

• A concrete implementation of this concept is the DPP-Plugin (Digital Product Passport Plugin).
• DPP-Plugin implements:
  • The Plugin contract expected by DataEngine.
  • A concrete database schema for storing submodel / submodel element values.
• See the separate DPP-Plugin repository for:
  • DPP Plugin Repository

---