From c7b926419cfc6614040bd7fb6c4c125f1b833b59 Mon Sep 17 00:00:00 2001 From: s-heppner Date: Tue, 14 Jul 2026 13:47:42 +0200 Subject: [PATCH 1/2] Update outdated package READMEs Did a general pass over the root, `sdk`, and `server` READMEs and brought them back in line with the current state of the code. Previously these files still described the pre-2.1.0 state in a few places and carried some long-standing typos and stale references, for example missing server interfaces, an outdated `API_BASE_PATH` default, a wrong package name and submodule count, and dead links. The changes correct these outdated sections so the documentation matches the actual packages, interfaces, and configuration again. --- README.md | 4 +++- sdk/README.md | 5 ++--- server/README.md | 12 +++++++++--- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e72d6b48..cb9b7677 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Each of them has a similar table at the top of the release notes. This repository is structured into separate packages. The `sdk` directory provides the AAS metamodel as Python objects and fundamental functionalities to handle AAS. The `server` implements a specification-compliant Docker HTTP server for AASs. -The `compliance_tool` is to be determined. +The `compliance_tool` is a command-line tool for checking whether JSON and XML files comply with the AAS specification. * [SDK](./sdk/README.md): * Modelling of AASs as Python objects @@ -36,6 +36,8 @@ The `compliance_tool` is to be determined. * [Server](./server/README.md): Docker Image of a specification compliant HTTP Server implementing the interfaces: * Asset Administration Shell Repository * Submodel Repository + * Registry + * Discovery * [Compliance Tool](./compliance_tool/README.md): A command-line tool for checking compliance of JSON and XML files to the specification of the AAS diff --git a/sdk/README.md b/sdk/README.md index 841e874e..4490ea88 100644 --- a/sdk/README.md +++ b/sdk/README.md @@ -8,7 +8,6 @@ for Industry 4.0 Systems. ## Features * Modelling of AASs as Python objects - * **except for**: *HasDataSpecification* * Reading and writing of AASX package files * (De-)serialization of AAS objects into/from JSON and XML * Storing of AAS objects in CouchDB, Backend infrastructure for easy expansion @@ -17,7 +16,7 @@ for Industry 4.0 Systems. ### Project Structure -The BaSyx Python SDK project provides the `basax.aas` Python package with 6 submodules: +The BaSyx Python SDK project provides the `basyx.aas` Python package with 5 submodules: * `basyx.aas.model`: The AAS metamodel implemented in python * `basyx.aas.adapter`: Adapters for various file formats @@ -55,7 +54,7 @@ Development/testing/documentation/example dependencies: * `lxml-stubs` (Apache License) * `types-python-dateutil` (Apache License v2.0) -Dependencies for building the documentation (see `docs/add-requirements.txt`): +Dependencies for building the documentation (see the `docs` extra in `pyproject.toml`): * `Sphinx` and its dependencies (BSD 2-clause License, MIT License, Apache License) * `sphinx-rtd-theme` and its dependencies (MIT License, PSF License) * `sphinx-argparse` (MIT License) diff --git a/server/README.md b/server/README.md index f2da379a..3bcc5751 100644 --- a/server/README.md +++ b/server/README.md @@ -5,6 +5,8 @@ The server currently implements the following interfaces: - [Asset Administration Shell Repository Service][4] - [Submodel Repository Service][5] +- [Registry Service][12] +- [Discovery Service][13] It uses the [HTTP API][1] and the [*AASX*][7], [*JSON*][8], and [*XML*][9] Adapters of the [BaSyx Python SDK][3], to serve regarding files from a given directory. The files are only read, changes won't persist. @@ -20,9 +22,9 @@ Pull the latest version via: $ docker pull eclipsebasyx/basyx-python-server:latest ``` -Or pin to a specific release: +Or pin to a specific release by replacing `` with the desired release number: ``` -$ docker pull eclipsebasyx/basyx-python-server:2.0.1 +$ docker pull eclipsebasyx/basyx-python-server: ``` ## Building @@ -58,7 +60,7 @@ The container can be configured via environment variables. The most important on | Variable | Description | Default | |-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| -| `API_BASE_PATH` | Base path under which the API is served. | `/api/v3.0/` | +| `API_BASE_PATH` | Base path under which the API is served. | `/api/v3.1/` | | `INPUT` | Path inside the container pointing to the directory from which the server takes its start-up data (*AASX*, *JSON*, *XML*). | `/input` | | `STORAGE` | Path inside the container pointing to the directory used by the server to persistently store data (*JSON*). | `/storage` | | `STORAGE_PERSISTENCY` | Flag to enable data persistence via the [LocalFileBackend][2]. AAS/Submodels are stored as *JSON* files in the directory specified by `STORAGE`. Supplementary files, i.e. files referenced by `File` SubmodelElements, are not stored. If disabled, any changes made via the API are only stored in memory. | `False` | @@ -80,6 +82,8 @@ Example configurations can be found in the `./example_configurations` directory. Currently, we offer: - [repository_standalone](example_configurations/repository_standalone/README.md): Standalone repository server +- [registry_standalone](example_configurations/registry_standalone/README.md): Standalone registry server +- [discovery_standalone](example_configurations/discovery_standalone/README.md): Standalone discovery server ## Running without Docker (Debugging Only) @@ -144,3 +148,5 @@ This Dockerfile is inspired by the [tiangolo/uwsgi-nginx-docker][10] repository. [9]: https://basyx-python-sdk.readthedocs.io/en/latest/adapter/xml.html [10]: https://github.com/tiangolo/uwsgi-nginx-docker [11]: https://hub.docker.com/r/eclipsebasyx/basyx-python-server +[12]: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.1_SSP-001 +[13]: https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.1.1_SSP-001 From 285642d0c6204a68c046edb8a09832aef031af0d Mon Sep 17 00:00:00 2001 From: s-heppner Date: Wed, 15 Jul 2026 22:54:55 +0200 Subject: [PATCH 2/2] Work in review feedback --- README.md | 3 ++- server/README.md | 22 ++++++++++++---------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index cb9b7677..f3a64d16 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,8 @@ The `compliance_tool` is a command-line tool for checking whether JSON and XML f * [Server](./server/README.md): Docker Image of a specification compliant HTTP Server implementing the interfaces: * Asset Administration Shell Repository * Submodel Repository - * Registry + * Asset Administration Shell Registry Service + * Submodel Registry Service * Discovery * [Compliance Tool](./compliance_tool/README.md): A command-line tool for checking compliance of JSON and XML files to the specification of the AAS diff --git a/server/README.md b/server/README.md index 3bcc5751..1a3e4217 100644 --- a/server/README.md +++ b/server/README.md @@ -5,7 +5,8 @@ The server currently implements the following interfaces: - [Asset Administration Shell Repository Service][4] - [Submodel Repository Service][5] -- [Registry Service][12] +- [Asset Administration Shell Registry Service][12] +- [Submodel Registry Service][14] - [Discovery Service][13] It uses the [HTTP API][1] and the [*AASX*][7], [*JSON*][8], and [*XML*][9] Adapters of the [BaSyx Python SDK][3], to serve regarding files from a given directory. @@ -40,10 +41,10 @@ Note that when cloning this repository on Windows, Git may convert the line sepa ### Storage -The server makes use of two directories: +The repository and registry servers make use of two directories: -- **`/input`** - *start-up data*: Directory from which the server loads AAS and Submodel files in *AASX*, *JSON* or *XML* format during start-up. The server will not modify these files. -- **`/storage`** - *persistent store*: Directory where all AAS and Submodels are stored as individual *JSON* files if the server is [configured](#options) for persistence. The server will modify these files. +- **`/input`** - *start-up data*: Directory from which the server loads its start-up data during start-up. The repository server loads AAS and Submodel files in *AASX*, *JSON* or *XML* format, while the registry server loads AAS and Submodel descriptors from *JSON* files only. The server will not modify these files. +- **`/storage`** - *persistent store*: Directory where the server's data is stored as individual *JSON* files if the server is [configured](#options) for persistence. The repository server stores AAS and Submodels, while the registry server stores AAS and Submodel descriptors. The server will modify these files. The directories can be mapped via the `-v` option from another image or a local directory. To mount the host directories into the container, `-v ./input:/input -v ./storage:/storage` can be used. @@ -58,12 +59,12 @@ To expose it on the host on port 8080, use the option `-p 8080:80` when running The container can be configured via environment variables. The most important ones are summarised below: -| Variable | Description | Default | -|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| -| `API_BASE_PATH` | Base path under which the API is served. | `/api/v3.1/` | -| `INPUT` | Path inside the container pointing to the directory from which the server takes its start-up data (*AASX*, *JSON*, *XML*). | `/input` | -| `STORAGE` | Path inside the container pointing to the directory used by the server to persistently store data (*JSON*). | `/storage` | -| `STORAGE_PERSISTENCY` | Flag to enable data persistence via the [LocalFileBackend][2]. AAS/Submodels are stored as *JSON* files in the directory specified by `STORAGE`. Supplementary files, i.e. files referenced by `File` SubmodelElements, are not stored. If disabled, any changes made via the API are only stored in memory. | `False` | +| Variable | Description | Default | +|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| +| `API_BASE_PATH` | Base path under which the API is served. | `/api/v3.1/` | +| `INPUT` | Path inside the container pointing to the directory from which the server takes its start-up data. The repository server takes *AASX*, *JSON* and *XML* files, while the registry server takes AAS/Submodel descriptors from *JSON* files only. | `/input` | +| `STORAGE` | Path inside the container pointing to the directory used by the repository or registry server to persistently store data (*JSON*). | `/storage` | +| `STORAGE_PERSISTENCY` | Flag to enable data persistence via the [LocalFileBackend][2]. AAS/Submodels (repository server) or AAS/Submodel descriptors (registry server) are stored as *JSON* files in the directory specified by `STORAGE`. Supplementary files, i.e. files referenced by `File` SubmodelElements, are not stored. If disabled, any changes made via the API are only stored in memory. | `False` | | `STORAGE_OVERWRITE` | Flag to enable storage overwrite if `STORAGE_PERSISTENCY` is enabled. Any AAS/Submodel from the `INPUT` directory already present in the LocalFileBackend replaces its existing version. If disabled, the existing version is kept. | `False` | @@ -150,3 +151,4 @@ This Dockerfile is inspired by the [tiangolo/uwsgi-nginx-docker][10] repository. [11]: https://hub.docker.com/r/eclipsebasyx/basyx-python-server [12]: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRegistryServiceSpecification/V3.1.1_SSP-001 [13]: https://app.swaggerhub.com/apis/Plattform_i40/DiscoveryServiceSpecification/V3.1.1_SSP-001 +[14]: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRegistryServiceSpecification/V3.1.1_SSP-001