Discovery

Purpose

The Discovery feature allows clients to discover Asset Administration Shells by their asset identifiers without knowing the AAS IDs upfront. DataEngine delegates the actual filtering to the Plugin.

---

Prerequisites

The Plugin must declare hasAssetIdSearch: true in its manifest capabilities. If this flag is absent or falsein all plugin, the endpoint returns 501 Not Implemented immediately without contacting the Plugin.

{
  "capabilities": {
    "hasShellDescriptor": true,
    "hasAssetInformation": true,
    "hasAssetIdSearch": true
  }
}

---

Endpoints

POST /lookup/shellsByAssetLink

Returns a paginated list of AAS ID strings that match the provided asset links.

• Method: POST
• Route: /lookup/shellsByAssetLink
• Query parameters:
  • limit (int, optional) – Maximum number of results per page.
  • cursor (string, optional) – Pagination cursor from a previous response.
• Request body: JSON array of AssetLink objects.

[
  { "name": "serialNumber", "value": "SN-4711" },
  { "name": "batchId",      "value": "B-0042"  }
]

AssetLink field constraints:

Field	Type	Max Length	Required
name	string	64	yes
value	string	2048	yes

• Responses:
  • 200 OK – Returns matching AAS IDs with pagination metadata.
  • 400 Bad Request – If the request body is empty, or any name/value violates length constraints.
  • 501 Not Implemented – If the plugin does not support asset ID search.

{
  "paging_metadata": {
    "cursor": null
  },
  "result": [
    "https://example.com/ids/aas/1170_1160_3052_6568"
  ]
}

---

Request Flow

POST /lookup/shellsByAssetLink

sequenceDiagram
    participant Client
    participant DataEngine
    participant Plugin

    Client->>DataEngine: POST /lookup/shellsByAssetLink  [AssetLink[]]

    DataEngine->>DataEngine: Validate request body & pagination params
    DataEngine->>DataEngine: Convert AssetLink[] → SpecificAssetId filters
    DataEngine->>DataEngine: Check hasAssetIdSearch capability (Return 501 if false)
    DataEngine->>DataEngine: Serialize filters → JSON header

    DataEngine->>Plugin: GET /metadata/shells + aastwinengine-assetids header

    Plugin-->>DataEngine: Return metadata/shells

    DataEngine->>DataEngine: Extract AAS IDs from metadata->shells
    DataEngine->>DataEngine: Apply cursor-based pagination

    DataEngine-->>Client: Response:{ paging_metadata, result: [aasId1, aasId2] }

Loading

---

Plugin Contract

DataEngine sends the aastwinengine-assetids request header to GET /metadata/shells. The header value is a JSON array of SpecificAssetId filter objects:

[
  {
    "name": "serialNumber",
    "value": "SN-4711"
  },
  {
    "name": "batchId",
    "value": "B-0042"
  }
]

The Plugin must filter its results so that only shell descriptors matching at least one of the provided filters are returned.

---