Basic Discovery Component#

GitHub Metamodel API

The BaSyx Basic Discovery component implements the Asset Administration Shell Basic Discovery API. It resolves Asset Administration Shell (AAS) identifiers from known asset identifiers and manages the asset links associated with an AAS identifier.

Discovery returns AAS identifiers. Clients use an AAS Registry to resolve those identifiers to service endpoints and an AAS Repository to access the AAS content.

Discovery or Registry?#

Use Basic Discovery when a client knows an asset identifier and needs the corresponding AAS identifier. Use the AAS Registry to retrieve an AAS Descriptor containing service endpoints. Use the AAS Repository to store, retrieve, or modify AAS content.

A typical discovery flow is:

  1. A client submits an asset identifier to Basic Discovery.

  2. Discovery returns matching AAS identifiers.

  3. The client retrieves the corresponding descriptors from the AAS Registry.

  4. The client follows a descriptor’s endpoint to access the AAS in a Repository.

Registering asset links does not create AAS content or an endpoint descriptor. Maintain the corresponding Registry and Repository resources separately. The Digital Twin Registry combines AAS Registry and Basic Discovery APIs in one component.

See Using Basic Discovery for registration, lookup, replacement, and deletion examples.

Main Capabilities#

The Basic Discovery component supports:

  • creating or replacing the asset links associated with an AAS identifier;

  • retrieving the registered asset links for an AAS identifier;

  • resolving AAS identifiers by specific asset identifiers or a global asset identifier;

  • cursor-based pagination of lookup results;

  • deleting an AAS identifier’s discovery registration;

  • service self-description.

See API Documentation for operation parameters, schemas, and responses.

Important Behavior#

Identifier Encoding#

The AAS identifier in /lookup/shells/{aasIdentifier} is Base64URL-encoded. Asset-link names and values in JSON request bodies remain unencoded.

Lookup and Pagination#

Use POST /lookup/shellsByAssetLink for new clients. GET /lookup/shells remains available but is deprecated in the specification; its assetIds query values are Base64URL-encoded JSON objects.

Lookup matches exact asset-link names and values. When multiple links are supplied, the AAS must match all of them. The reserved name globalAssetId selects a global asset identifier. An empty lookup array returns an empty result in the unsecured setup; it is not a request to list every AAS.

Lookup responses contain original, unencoded AAS identifier strings in result, with continuation information in paging_metadata. Follow Pagination, retaining the same lookup body for subsequent pages. Retrieving one AAS identifier’s asset links instead returns a plain JSON array.

Updates and Deletion#

POST /lookup/shells/{aasIdentifier} creates or replaces the complete asset-link set and returns 201 Created in both cases. Include every link that should remain registered. Each submitted entry must have a non-empty name and value.

DELETE /lookup/shells/{aasIdentifier} removes the discovery registration and its asset links. It does not delete AAS content from a Repository.

Registry Integration#

When AAS Registry Discovery integration is enabled, the Registry and Basic Discovery share asset-identifier information for the same AAS. Both components must use the same BaSyx database and schema, and Discovery integration must be enabled explicitly in the Registry.

Changes made through one API can therefore affect what the other API returns:

  • POST /lookup/shells/{aasIdentifier} in the standalone Discovery Service replaces the complete Discovery mapping. In an integrated setup, this can also change the specificAssetIds returned with the corresponding AAS Descriptor.

  • Deleting a Discovery registration can remove linked asset identifiers from the descriptor, but it does not delete the AAS Descriptor or Repository content.

  • Creating or updating an integrated AAS Descriptor can change subsequent Discovery lookup results.

  • The Digital Twin Registry behaves differently: its asset-link POST appends links and requires an existing AAS Descriptor.

The descriptor’s globalAssetId remains a separate descriptor property. When Registry integration writes the descriptor’s asset identifiers to Discovery, the globalAssetId is also represented as an asset link named globalAssetId. A standalone Discovery replacement replaces this link together with the rest of the Discovery mapping, so include it if lookup by global asset ID should remain available. Omitting the link does not clear the descriptor’s globalAssetId property.

Database Schema#

The component uses PostgreSQL and validates the shared BaSyx schema at startup. Initialize and migrate the schema with the BaSyx Configuration Service before starting Discovery. See Setting Up Basic Discovery for the startup order.

Configuration#

See General Configuration for server, database, and security settings. The Compose setup exposes Discovery on port 8086.

API Documentation#

Use the running BaSyx Go Swagger UI for the installed component’s operations, parameters, schemas, and responses. The shipped OpenAPI document identifies API version V3.2.0 and the Discovery Service Full Profile (SSP-001).

With an empty context path, the service exposes:

  • Swagger UI at /swagger;

  • the OpenAPI document at /api-docs/openapi.yaml;

  • service self-description at /description.

A configured server.contextPath prefixes these locations. Swagger can be disabled through configuration. See Swagger UI Docs.