basyx-go-components

module
v1.0.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 13, 2026 License: MIT

README

Go Report Card

BaSyx Go Logo

BaSyx Go Components

Welcome to the BaSyx Go project! This guide is designed to help new developers onboard quickly, understand the architecture, and contribute effectively.

Table of Contents

  1. Project Overview
  2. Architecture Overview
  3. Setup & Installation
  4. Environment Variables & Configuration
  5. Code Style & Conventions
  6. Module Structure
  7. Common Workflows
  8. API Usage
  9. Contribution Guidelines
  10. Repository Automation
  11. Troubleshooting & Error Reference
  12. Glossary of Terms & Abbreviations

1. Project Overview

BaSyx Go Components is an open-source implementation of the Eclipse BaSyx framework in Go, providing Asset Administration Shell (AAS) API components like registries, repositories, and more. The project is modular, scalable, and designed for industrial digital twin scenarios.

2. Architecture Overview

The project is composed of microservices for AAS and Submodel registries, AAS and Submodel repositories, the AAS discovery service, and the AASX file server. Each service exposes REST APIs and interacts with a PostgreSQL database. Security is enforced via OIDC and ABAC middleware. See docu/security/REGISTRY_SECURITY.md for a detailed flow and architecture diagram.

3. Setup & Installation

Prerequisites
  • Go >= 1.20
  • Docker & Docker Compose
  • PostgreSQL (for local development)
Steps
  1. Clone the repository: 
    git clone https://github.com/eclipse-basyx/basyx-go-components.git
cd basyx-go-components
  2. Install dependencies: 
    go mod tidy
  3. Start services (example): 
    go run ./cmd/submodelrepositoryservice/main.go -config ./cmd/submodelrepositoryservice/config.yaml -databaseSchema ./basyxschema.sql
  4. Run integration tests: 
    go test -v ./internal/submodelrepository/integration_tests
  5. Use Docker Compose for multi-service setup: 
    docker-compose -f examples/BaSyxMinimalExample/docker-compose.yml up

4. Environment Variables & Configuration

Configuration is managed via YAML files in cmd/<service>/config.yaml and environment variables. Key variables include database connection settings (see docu/errors.md for troubleshooting):

maxOpenConnections: 500
maxIdleConnections: 500
connMaxLifetimeMinutes: 5

Or via .env:

POSTGRES_MAXOPENCONNECTIONS=500
POSTGRES_MAXIDLECONNECTIONS=500
POSTGRES_CONNMAXLIFETIMEMINUTES=5

5. Code Style & Conventions

  • Use Go modules (go.mod) for dependency management
  • Follow GoDoc conventions (godoc_tips.md)
  • Run the linter before submitting PRs: 
    ./lint.sh
  • Use //nolint:<linter> comments sparingly and explain why
  • Auto-generated model files may not conform to all linter rules

6. Module Structure

  • cmd/ - Service entry points, configs, Dockerfiles
  • api/ - OpenAPI specs and API layer
  • internal/ - Core business logic, persistence, integration tests
  • pkg/ - Autogenerated API Files
  • examples/ - Minimal working examples, Docker Compose setups
  • docu/ - Documentation, error explanations, security notes
  • basyx-database-wiki/ - Database schema documentation

See structure.md and related files for details on each module.

7. Common Workflows

Build & Run
  • Build and run services: 
    go run ./cmd/<service>/main.go -config ./cmd/<service>/config.yaml
  • Use VSCode launch scripts in .vscode/launch.json for debugging
Test
  • Run all tests: 
    go test -v ./internal/...
  • Run integration tests for a component: 
    go test -v ./internal/<component>/integration_tests
Lint
  • Run linter: 
    ./lint.sh

8. API Usage

  • OpenAPI specs are in api/<service>/openapi.yaml
  • Use generated API clients in pkg/
  • Example endpoint: /submodels/{id}/submodel-elements/{idShort}/attachment
  • See structure_api.md for details

9. Contribution Guidelines

  • Fork the repository and create a feature branch
  • Write clear commit messages and PR descriptions
  • Add/update GoDoc comments for all exported code
  • Run tests and linter before submitting
  • Cover new features with integration tests
  • Document public APIs in OpenAPI YAML files

10. Repository Automation

  • CI/CD pipelines run tests and linter on each PR
  • Ensure your local environment matches CI versions (see linter.md)
  • Use provided tasks in VSCode or CLI for build/test/lint automation

11. Troubleshooting & Error Reference

12. Glossary of Terms & Abbreviations

  • AAS: Asset Administration Shell – digital representation of assets
  • Submodel: Modular part of an AAS
  • SME: Submodel Element
  • OIDC: OpenID Connect – authentication protocol
  • ABAC: Attribute-Based Access Control
  • OpenAPI: Specification for RESTful APIs

For further details, see the docs folder, the basyx wiki and links above. If you encounter issues, please open an issue on GitHub or consult the error documentation.

Database Schema

See basyx-database-wiki and sql_examples for details on tables, relationships, and large object handling.

Frequently Asked Questions

Q: How do I add a new component?

  • Add main.go in cmd/<COMPONENT_NAME>/main.go
  • Implement the logic in internal/<COMPONENT_NAME>/
  • Save and Use OpenAPI specs in api/<COMPONENT_NAME>/openapi.yaml
  • Add tests in internal/<COMPONENT_NAME>/integration_tests/

Q: How do I handle file attachments?

  • Use the File SME logic in internal/submodelrepository/persistence/Submodel/submodelElements/FileHandler.go
  • See integration tests for upload/download examples

Q: Where do I find API documentation?

  • OpenAPI YAML files in api/
  • GoDoc for package-level documentation

Further Reading

For any questions, open an issue or contact the maintainers.

Directories

Path Synopsis
cmd
aasregistryservice command
Package main implements the AAS Registry Service server.
 Package main implements the AAS Registry Service server.
aasrepositoryservice command
Package main implements the Asset Administration Shell Repository Service server.
 Package main implements the Asset Administration Shell Repository Service server.
conceptdescriptionrepositoryservice command
Package main implements the Concept Description Repository Service server.
 Package main implements the Concept Description Repository Service server.
digitaltwinregistryservice command
Package main implements the Digital Twin Registry service (AAS Registry + Discovery).
 Package main implements the Digital Twin Registry service (AAS Registry + Discovery).
discoveryservice command
Package main implements the Discovery Service server.
 Package main implements the Discovery Service server.
registryofinfrastructuresservice command
Package main implements the Registry of Infrastructures Service server.
 Package main implements the Registry of Infrastructures Service server.
submodelregistryservice command
Package main implements the Submodel Registry Service server.
 Package main implements the Submodel Registry Service server.
submodelrepositoryservice command
Package main implements the Submodel Repository Service server.
 Package main implements the Submodel Repository Service server.
internal
aasregistry/api
Package aasregistryapi implements Asset Administration Shell Registry Service
 Package aasregistryapi implements Asset Administration Shell Registry Service
aasregistry/persistence
Package aasregistrydatabase provides a PostgreSQL-backed persistence layer for the AAS Registry.
 Package aasregistrydatabase provides a PostgreSQL-backed persistence layer for the AAS Registry.
aasrepository/api
package openapi
 package openapi
aasrepository/persistence
Package persistence contains the implementation of the AssetAdministrationShellRepositoryDatabase interface using PostgreSQL as the underlying database.
 Package persistence contains the implementation of the AssetAdministrationShellRepositoryDatabase interface using PostgreSQL as the underlying database.
aasrepository/persistence/utils
Package aas_repository_utils contains utility functions for the Asset Administration Shell Repository component, such as parsing and handling of aas-related data.
 Package aas_repository_utils contains utility functions for the Asset Administration Shell Repository component, such as parsing and handling of aas-related data.
common
nolint:all
 nolint:all
common/builder
Package builder provides utilities for constructing complex AAS (Asset Administration Shell) data structures from database query results.
 Package builder provides utilities for constructing complex AAS (Asset Administration Shell) data structures from database query results.
common/descriptors
Package descriptors contains the data‑access helpers that read and write Asset Administration Shell (AAS) and Submodel descriptor data to a PostgreSQL database.
 Package descriptors contains the data‑access helpers that read and write Asset Administration Shell (AAS) and Submodel descriptor data to a PostgreSQL database.
common/jws
Package jws provides utilities for handling JSON Web Signatures (JWS).
 Package jws provides utilities for handling JSON Web Signatures (JWS).
common/model
* DotAAS Part 1 | Metamodel | Schemas * * The schemas implementing the [Specification of the Asset Administration Shell: Part 1](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).
 * DotAAS Part 1 | Metamodel | Schemas * * The schemas implementing the [Specification of the Asset Administration Shell: Part 1](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).
common/model/grammar
Package grammar defines the data structures for representing the AAS Access Rule Language.
 Package grammar defines the data structures for representing the AAS Access Rule Language.
common/queries
Package queries provides functions to build SQL queries for extensions.
 Package queries provides functions to build SQL queries for extensions.
common/security
Package auth provides authentication and authorization functionality for BaSyx Go components.
 Package auth provides authentication and authorization functionality for BaSyx Go components.
common/testenv
Package testenv provides testing utilities for integration tests and benchmarks.
 Package testenv provides testing utilities for integration tests and benchmarks.
conceptdescriptionrepository/api
Package api provides the Concept Description Repository API service implementation.
 Package api provides the Concept Description Repository API service implementation.
conceptdescriptionrepository/persistence
Package persistence contains the implementation of the Concept Description Repository API service's persistence layer, which is responsible for storing and retrieving concept descriptions.
 Package persistence contains the implementation of the Concept Description Repository API service's persistence layer, which is responsible for storing and retrieving concept descriptions.
digitaltwinregistry
Package digitaltwinregistry package implements a custom discovery service for the Digital Twin Registry.
 Package digitaltwinregistry package implements a custom discovery service for the Digital Twin Registry.
discoveryservice/api
discoveryservice/persistence
Package persistencepostgresql provides PostgreSQL-based persistence implementation for the Eclipse BaSyx Discovery Service.
 Package persistencepostgresql provides PostgreSQL-based persistence implementation for the Eclipse BaSyx Discovery Service.
healthprobe command
Package main provides a tiny static health probe used in distroless container images.
 Package main provides a tiny static health probe used in distroless container images.
registryofinfrastructuresservice/api
Package api implements the HTTP-facing service logic for the Registry of Infrastructures (RoI).
 Package api implements the HTTP-facing service logic for the Registry of Infrastructures (RoI).
registryofinfrastructuresservice/persistence
Package registryofinfrastructurespostgresql provides PostgreSQL-based persistence implementation for the Eclipse BaSyx RegistryOfInfrastructures Service.
 Package registryofinfrastructurespostgresql provides PostgreSQL-based persistence implementation for the Eclipse BaSyx RegistryOfInfrastructures Service.
smregistry/api
Package smregistryapi implements Submodel Registry Service
 Package smregistryapi implements Submodel Registry Service
smregistry/persistence
Package smregistrypostgresql provides PostgreSQL-based persistence implementation
 Package smregistrypostgresql provides PostgreSQL-based persistence implementation
submodelrepository/api
Package api for the SubmodelRepositoryAPIAPI service
 Package api for the SubmodelRepositoryAPIAPI service
submodelrepository/config
Package config provides configuration constants for the submodel repository.
 Package config provides configuration constants for the submodel repository.
submodelrepository/errors
Package errors provides centralized error definitions for the submodel repository.
 Package errors provides centralized error definitions for the submodel repository.
submodelrepository/logger
Package logger provides centralized logging functionality for the submodel repository.
 Package logger provides centralized logging functionality for the submodel repository.
submodelrepository/persistence
Package persistence contains the implementation of the SubmodelRepositoryDatabase interface using PostgreSQL as the underlying database.
 Package persistence contains the implementation of the SubmodelRepositoryDatabase interface using PostgreSQL as the underlying database.
submodelrepository/persistence/submodelElements
Package submodelelements provides handlers for different types of submodel elements in the BaSyx framework.
 Package submodelelements provides handlers for different types of submodel elements in the BaSyx framework.
submodelrepository/persistence/utils
Package submodel_repository_utils contains utility functions for the Submodel Repository component, such as parsing and handling of submodel-related data.
 Package submodel_repository_utils contains utility functions for the Submodel Repository component, such as parsing and handling of submodel-related data.
submodelrepository/transaction
Package transaction provides transaction management utilities for the submodel repository.
 Package transaction provides transaction management utilities for the submodel repository.
pkg
aasregistryapi
aasrepositoryapi/go
Package openapi provides the generated HTTP controller and routing bindings for the Asset Administration Shell Repository API.
 Package openapi provides the generated HTTP controller and routing bindings for the Asset Administration Shell Repository API.
conceptdescriptionrepositoryapi/go
discoveryapi
registryofinfrastructuresapi
smregistry
submodelrepositoryapi/go
Package openapi Submodel Repository API
 Package openapi Submodel Repository API

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.