Submodel Registry#

GitHub Metamodel API

The BaSyx Submodel Registry implements the Asset Administration Shell Submodel Registry Service. It stores Submodel Descriptors as standalone registry entries so that clients can discover where Submodels are available.

The Registry manages descriptive and routing metadata. It does not store or serve the Submodel content itself.

What Is a Submodel Descriptor?#

A Submodel Descriptor identifies a Submodel and describes how clients can reach it. Depending on the deployment and use case, it can contain information such as:

  • the Submodel identifier and idShort;

  • semantic identification information;

  • endpoints at which the Submodel can be accessed;

  • supplemental semantic IDs and other discovery metadata.

The complete payload definition is specified in the Specification of the Asset Administration Shell, Part 2: Application Programming Interfaces. A SubmodelDescriptor is an API payload type; it is not the Submodel metamodel object stored by a Repository.

Registry or Repository?#

Use the Submodel Registry when a client needs to discover a Submodel or determine which service endpoint provides it. Use a Submodel Repository when a client needs to store, retrieve, or modify the actual Submodel content.

A typical deployment uses both components:

  1. A Submodel Repository stores and serves a Submodel.

  2. The Submodel Registry stores a descriptor containing the Submodel identifier and the Repository endpoint.

  3. A client searches the Registry and receives the descriptor.

  4. The client follows the advertised endpoint to interact with the Submodel in the Repository.

The Registry and Repository do not have to run in the same process or at the same network location. This separation allows one Registry to advertise Submodels provided by multiple services or organizations.

Alternatively, the BaSyx AAS Environment combines the Submodel Registry and Submodel Repository capabilities in a single component.

See Using the Submodel Registry for a walkthrough from descriptor registration to lookup, update, and deletion.

Main Capabilities#

The Submodel Registry supports management of standalone Submodel Descriptors. It provides operations for listing, creating, retrieving, updating, and deleting descriptors.

It also supports:

  • cursor-based pagination for descriptor collections;

  • filtering Submodel Descriptors by creation and update timestamps;

  • structured queries for more expressive descriptor searches;

  • asynchronous bulk creation, update, and deletion of Submodel Descriptors;

  • service self-description.

See API Documentation for the authoritative list of operations, parameters, schemas, and responses.

Important Behavior#

Standalone and AAS-associated Submodel Descriptors#

The standalone Submodel Registry manages standalone SubmodelDescriptor resources. Clients address each one by its Submodel identifier at /submodel-descriptors/{submodelIdentifier}.

A Submodel Descriptor registered below an AAS Descriptor is a separate registration in the AAS Registry. Its route includes both the parent AAS identifier and the Submodel identifier. Creating, replacing, or deleting a standalone descriptor does not automatically change an AAS-associated descriptor, and changing an AAS-associated descriptor does not automatically change the standalone registration.

Repository-to-Registry Integration#

Manual Registry calls are not the only way to maintain descriptors. When Submodel Registry integration is enabled, the standalone Submodel Repository maintains the standalone descriptor as Submodel content changes. It also refreshes embedded descriptors in existing AAS Descriptors that reference that Submodel. The integration is disabled by default and requires the Repository and Registries to use the same BaSyx database. It is not an HTTP synchronization between independent services.

This synchronization is triggered by Repository mutations. Direct writes to either Registry API remain scoped to the descriptor registration addressed by that API. The usage walkthrough demonstrates those direct standalone Registry calls.

Identifier Encoding#

The Submodel identifier in a request path is Base64URL-encoded. Identifiers in JSON request bodies, query JSON, and bulk-delete identifier arrays remain unencoded.

Pagination and Filters#

Collection requests use cursor-based pagination. See the shared guide for page size, response structure, and continuation requests.

createdFrom and updatedFrom filter on the descriptor’s administration.createdAt and administration.updatedAt values. The Registry does not generate or update these values on writes; the registering application must maintain them. Bounds are inclusive, and when both timestamp filters are supplied, either condition can match.

The ordinary descriptor-list endpoint supports limit, cursor, createdFrom, and updatedFrom; it does not provide a semanticId filter parameter. Use Structured Queries to search descriptor fields such as semantic identification.

Updates#

PUT creates a missing descriptor and replaces an existing descriptor. The body identifier must match the decoded path identifier. Submit the complete descriptor, including endpoints and metadata that should remain. PUT is not a partial update. Replacing or deleting a descriptor does not modify the Submodel content in a Repository.

Bulk Operations#

Bulk descriptor creation, update, and deletion are asynchronous. Submit the request to the bulk endpoint, then use the returned handle to poll the bulk status and result endpoints. Bulk processing is atomic: if one descriptor operation fails, the complete transaction is rolled back.

Retrieving a completed result consumes the handle, including for failed jobs. See Bulk Operations for submission, polling, result retrieval, expiry, and failure behavior.

Database Schema#

The Registry uses PostgreSQL and expects the shared BaSyx database schema to be initialized and migrated by the BaSyx Configuration Service. The Registry validates the schema during startup and does not initialize it itself. See Setting Up the Submodel Registry for the required startup order.

Configuration#

See General Configuration for the shared server, database, and feature settings used by BaSyx Go components.

API Documentation#

Use the following API documentation depending on whether you need the behavior of a running BaSyx component or the standardized API definition:

The OpenAPI document shipped with the current BaSyx Go Submodel Registry identifies API version 3.2.0 and declares the Submodel Registry Full, Bulk, and Query profiles (SSP-001, SSP-003, and SSP-004). Use the Swagger UI of the running component to determine its actual exposed contract and configuration.

With the default empty context path, the service exposes:

  • Swagger UI at /swagger;

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

When server.contextPath is configured, both locations are served below that context path. Swagger can also be disabled through configuration. See Swagger UI Docs for details.