Merge branch 'develop' into update/Metamodel_V3.1.2

s-heppner · web-flow · commit 2d021905e25d · 2026-05-05T13:38:38.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -53,7 +53,7 @@ jobs:
       # that you want to use to test the serialization adapter against.
       # Currently, we need to update this manually, however I'm afraid this is not possible to automatically infer,
       # since it's heavily dependant of the version of the AAS specification we support.
-      AAS_SPECS_RELEASE_TAG: "IDTA-01001-3-0-1_schemasV3.0.8"
+      AAS_SPECS_RELEASE_TAG: "IDTA-01001-3-1-2"
     services:
       couchdb:
         image: couchdb:3
diff --git a/README.md b/README.md
@@ -7,13 +7,14 @@ for Industry 4.0 Systems.
 
 These are the implemented AAS specifications of the [current SDK release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), which can be also found on [PyPI](https://pypi.org/project/basyx-python-sdk/):
 
-| Specification                         | Version                                                                                                                                                                         |
-|---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Part 1: Metamodel                     | [v3.1.2 (01001-3-0-1)](https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.1.2/index.html)                 |
-| Schemata (JSONSchema, XSD)            | [v3.0.8 (IDTA-01001-3-0-1_schemasV3.0.8)](https://github.com/admin-shell-io/aas-specs/releases/tag/IDTA-01001-3-0-1_schemasV3.0.8)                                              |
-| Part 2: API                           | [v3.0 (01002-3-0)](https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/06/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API_.pdf)                 |
-| Part 3a: Data Specification IEC 61360 | [v3.0 (01003-a-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01003-a-3-0_SpecificationAssetAdministrationShell_Part3a_DataSpecification_IEC61360.pdf) |
-| Part 5: Package File Format (AASX)    | [v3.0 (01005-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf)           |
+| Specification                         | Version                                                                                                                                                                           |
+|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Part 1: Metamodel                     | [v3.1.2 (01001-3-0-1)](https://industrialdigitaltwin.io/aas-specifications/IDTA-01001/v3.1.2/index.html)                   |
+| Schemata (JSONSchema, XSD)            | [v3.0.8 (IDTA-01001-3-0-1_schemasV3.0.8)](https://github.com/admin-shell-io/aas-specs/releases/tag/IDTA-01001-3-0-1_schemasV3.0.8)                                                |
+| Part 2: API                           | [v3.1.1 (01002)](https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2025/08/IDTA-01002-3-1-1_AAS-Specification_Part2_API.pdf)                        |
+| Part 3a: Data Specification IEC 61360 | [v3.1.1 (01003-a)](https://industrialdigitaltwin.org/wp-content/uploads/2025/08/IDTA-01003-a-3-1-1_AAS-Specification_Part3a_DataSpecification.pdf) |
+| Part 5: Package File Format (AASX)    | [v3.1 (01005)](https://industrialdigitaltwin.org/wp-content/uploads/2025/06/IDTA_01005-25-01_AAS-Specification_Part5_AASXPackageFileFormat.pdf)                               |
+
 
 If you need support to an older version of the specifications, please refer to our [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases). 
 Each of them has a similar table at the top of the release notes.
diff --git a/sdk/basyx/aas/adapter/aasx.py b/sdk/basyx/aas/adapter/aasx.py
@@ -140,23 +140,31 @@ def read_into(self, object_store: model.AbstractObjectStore,
         :return: A set of the :class:`Identifiers <basyx.aas.model.base.Identifier>` of all
                  :class:`~basyx.aas.model.base.Identifiable` objects parsed from the AASX file
         """
+        # Format of supported and deprecated AASX relationship URL
+        AASX_REL_BASE = "http://admin-shell.io/aasx/relationships"
+        AASX_REL_BASE_DEPRECATED = "http://www.admin-shell.io/aasx/relationships"
+        RELATIONSHIP_TYPE_AASX_ORIGIN = f"{AASX_REL_BASE}/aasx-origin"
+        RELATIONSHIP_TYPE_AASX_ORIGIN_DEPRECATED = f"{AASX_REL_BASE_DEPRECATED}/aasx-origin"
+
         # Find AASX-Origin part
         core_rels = self.reader.get_related_parts_by_type()
         try:
             aasx_origin_part = core_rels[RELATIONSHIP_TYPE_AASX_ORIGIN][0]
         except IndexError as e:
-            if core_rels.get("http://www.admin-shell.io/aasx/relationships/aasx-origin"):
+            if core_rels.get(RELATIONSHIP_TYPE_AASX_ORIGIN_DEPRECATED):
                 # Since there are many AASX files with this (wrong) relationship URls in the wild, we make an exception
                 # and try to read it anyway. However, we notify the user that this may lead to data loss, since it is
                 # highly likely that the other relationship URLs are also wrong in that file.
                 # See also [#383](https://github.com/eclipse-basyx/basyx-python-sdk/issues/383) for the discussion.
-                logger.warning("SPECIFICATION VIOLATED: The Relationship-URL in your AASX file "
-                               "('http://www.admin-shell.io/aasx/relationships/aasx-origin') "
-                               "is not valid, it should be 'http://admin-shell.io/aasx/relationships/aasx-origin'. "
-                               "We try to read the AASX file anyway, but this cannot guaranteed in the future,"
-                               "and the file may not be fully readable, so data losses may occur."
-                               "Please fix this and/or notify the source of the AASX.")
-                aasx_origin_part = core_rels["http://www.admin-shell.io/aasx/relationships/aasx-origin"][0]
+                logger.warning(
+                    "Deprecated AASX relationship URL format used: '%s'. "
+                    "The supported AASX relationship URL format is: '%s'. "
+                    "Support for the deprecated form is kept for compatibility, but data losses may occur. "
+                    "Please fix the format and notify the author of the given AASX.",
+                    RELATIONSHIP_TYPE_AASX_ORIGIN_DEPRECATED,
+                    RELATIONSHIP_TYPE_AASX_ORIGIN,
+                )
+                aasx_origin_part = core_rels[RELATIONSHIP_TYPE_AASX_ORIGIN_DEPRECATED][0]
             else:
                 raise ValueError("Not a valid AASX file: aasx-origin Relationship is missing.") from e
 
diff --git a/sdk/basyx/aas/model/base.py b/sdk/basyx/aas/model/base.py
@@ -28,7 +28,7 @@
 BlobType = bytes
 
 # The following string aliases are constrained by the decorator functions defined in the string_constraints module,
-# wherever they are used for an instance attributes.
+# wherever they are used for an instance's attributes.
 ContentType = str  # any mimetype as in RFC2046
 Identifier = str
 LabelType = str
diff --git a/server/README.md b/server/README.md
@@ -12,9 +12,22 @@ The files are only read, changes won't persist.
 Alternatively, the container can also be told to use the [Local-File Backend][2] instead, which stores Asset Administration Shells (AAS) and Submodels as individual *JSON* files and allows for persistent changes (except supplementary files, i.e. files referenced by `File` SubmodelElements).
 See [below](#options) on how to configure this.
 
+## Docker Hub
+
+Pre-built images are published to [Docker Hub][11] on every release.
+Pull the latest version via:
+```
+$ docker pull eclipsebasyx/basyx-python-server:latest
+```
+
+Or pin to a specific release:
+```
+$ docker pull eclipsebasyx/basyx-python-server:2.0.1
+```
+
 ## Building
 
-The container image can be built via:
+If you need to build the image locally (e.g. for development), run:
 ```
 $ docker build -t basyx-python-server -f Dockerfile ..
 ```
@@ -86,7 +99,7 @@ The server can also be run directly on the host system without Docker, NGINX and
    $ python -m app.interfaces.repository
    ```
 
-The server can be accessed at http://localhost:8080/api/v3.0/ from your host system. 
+The server can be accessed at http://localhost:8080/api/v3.1/ from your host system. 
 
 ## Currently Unimplemented
 Several features and routes are currently not supported:
@@ -123,10 +136,11 @@ This Dockerfile is inspired by the [tiangolo/uwsgi-nginx-docker][10] repository.
 [1]: https://github.com/eclipse-basyx/basyx-python-sdk/pull/238
 [2]: https://basyx-python-sdk.readthedocs.io/en/latest/backend/local_file.html
 [3]: https://github.com/eclipse-basyx/basyx-python-sdk
-[4]: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.0.1_SSP-001
-[5]: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.0.1_SSP-001
-[6]: https://industrialdigitaltwin.io/aas-specifications/IDTA-01002/v3.0/index.html
+[4]: https://app.swaggerhub.com/apis/Plattform_i40/AssetAdministrationShellRepositoryServiceSpecification/V3.1.1_SSP-001
+[5]: https://app.swaggerhub.com/apis/Plattform_i40/SubmodelRepositoryServiceSpecification/V3.1.1_SSP-001
+[6]: https://industrialdigitaltwin.io/aas-specifications/IDTA-01002/v3.1.2/index.html
 [7]: https://basyx-python-sdk.readthedocs.io/en/latest/adapter/aasx.html#adapter-aasx
 [8]: https://basyx-python-sdk.readthedocs.io/en/latest/adapter/json.html
 [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
diff --git a/server/app/interfaces/_string_constraints.py b/server/app/interfaces/_string_constraints.py
@@ -0,0 +1,64 @@
+# Copyright (c) 2026 the Eclipse BaSyx Authors
+#
+# This program and the accompanying materials are made available under the terms of the MIT License, available in
+# the LICENSE file of this project.
+#
+# SPDX-License-Identifier: MIT
+"""
+This module implements constraint functions for the listed constrained string types.
+All types are constrained in length (min and max).
+
+.. warning::
+    This module is intended for internal use only.
+
+The following types aliased in the :mod:`~server.app.interfaces.base` module are constrained:
+
+- :class:`~server.app.interfaces.base.CodeType`
+- :class:`~server.app.interfaces.base.ShortIdType`
+- :class:`~server.app.interfaces.base.LocatorType`
+- :class:`~server.app.interfaces.base.TextType`
+- :class:`~server.app.interfaces.base.SchemeType`
+"""
+
+from typing import Callable, Type
+from basyx.aas.model._string_constraints import check, constrain_attr, _T
+
+
+def check_code_type(value: str, type_name: str = "CodeType") -> None:
+    return check(value, type_name, 1, 32)
+
+
+def check_short_id_type(value: str, type_name: str = "ShortIdType") -> None:
+    return check(value, type_name, 1, 128)
+
+
+def check_locator_type(value: str, type_name: str = "LocatorType") -> None:
+    return check(value, type_name, 1, 2048)
+
+
+def check_text_type(value: str, type_name: str = "TextType") -> None:
+    return check(value, type_name, 1, 2048)
+
+
+def check_scheme_type(value: str, type_name: str = "SchemeType") -> None:
+    return check(value, type_name, 1, 128)
+
+
+def constrain_code_type(pub_attr_name: str) -> Callable[[Type[_T]], Type[_T]]:
+    return constrain_attr(pub_attr_name, check_code_type)
+
+
+def constrain_short_id_type(pub_attr_name: str) -> Callable[[Type[_T]], Type[_T]]:
+    return constrain_attr(pub_attr_name, check_short_id_type)
+
+
+def constrain_locator_type(pub_attr_name: str) -> Callable[[Type[_T]], Type[_T]]:
+    return constrain_attr(pub_attr_name, check_locator_type)
+
+
+def constrain_text_type(pub_attr_name: str) -> Callable[[Type[_T]], Type[_T]]:
+    return constrain_attr(pub_attr_name, check_text_type)
+
+
+def constrain_scheme_type(pub_attr_name: str) -> Callable[[Type[_T]], Type[_T]]:
+    return constrain_attr(pub_attr_name, check_scheme_type)
diff --git a/server/app/interfaces/base.py b/server/app/interfaces/base.py
@@ -19,6 +19,7 @@
 from basyx.aas.adapter._generic import XML_NS_MAP
 from basyx.aas.adapter.xml import XMLConstructables, read_aas_xml_element, xml_serialization
 from basyx.aas.model import AbstractObjectStore
+from basyx.aas.model.datatypes import NonNegativeInteger
 from lxml import etree
 from werkzeug import Request, Response
 from werkzeug.exceptions import BadRequest, NotFound
@@ -28,10 +29,83 @@
 from app.adapter import ServerAASToJsonEncoder, ServerStrictAASFromJsonDecoder, ServerStrictStrippedAASFromJsonDecoder
 from app.model import AssetAdministrationShellDescriptor, AssetLink, SubmodelDescriptor
 from app.util.converters import base64url_decode
+from . import _string_constraints
+
+# The following string aliases are constrained by the decorator functions defined in the string_constraints module,
+# wherever they are used for an instances attributes.
+CodeType = str
+ShortIdType = str
+LocatorType = str
+TextType = str
+SchemeType = str
 
 T = TypeVar("T")
 
 
+class ServiceSpecificationProfileEnum(str, enum.Enum):
+    """
+    Enumeration of all standardized Service Specification Profiles
+    from the AAS Part 2 API Specification (IDTA-01002-3-1).
+    Each profile is uniquely identified by its semantic URI.
+    """
+
+    # --- Asset Administration Shell (AAS) ---
+    AAS_FULL = "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellServiceSpecification/SSP-001"
+    AAS_READ = "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellServiceSpecification/SSP-002"
+
+    # --- Submodel ---
+    SUBMODEL_FULL = "https://admin-shell.io/aas/API/3/1/SubmodelServiceSpecification/SSP-001"
+    SUBMODEL_VALUE = "https://admin-shell.io/aas/API/3/1/SubmodelServiceSpecification/SSP-002"
+    SUBMODEL_READ = "https://admin-shell.io/aas/API/3/1/SubmodelServiceSpecification/SSP-003"
+
+    # --- AASX File Server ---
+    AASX_FILESERVER_FULL = "https://admin-shell.io/aas/API/3/1/AasxFileServerServiceSpecification/SSP-001"
+
+    # --- AAS Registry ---
+    AAS_REGISTRY_FULL = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-001"
+    AAS_REGISTRY_READ = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-002"
+    AAS_REGISTRY_BULK = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRegistryServiceSpecification/SSP-003"
+
+    # --- Submodel Registry ---
+    SUBMODEL_REGISTRY_FULL = "https://admin-shell.io/aas/API/3/1/SubmodelRegistryServiceSpecification/SSP-001"
+    SUBMODEL_REGISTRY_READ = "https://admin-shell.io/aas/API/3/1/SubmodelRegistryServiceSpecification/SSP-002"
+    SUBMODEL_REGISTRY_BULK = "https://admin-shell.io/aas/API/3/1/SubmodelRegistryServiceSpecification/SSP-003"
+
+    # --- AAS Repository ---
+    AAS_REPOSITORY_FULL = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRepositoryServiceSpecification/SSP-001"
+    AAS_REPOSITORY_READ = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRepositoryServiceSpecification/SSP-002"
+    AAS_REPOSITORY_BULK = \
+        "https://admin-shell.io/aas/API/3/1/AssetAdministrationShellRepositoryServiceSpecification/SSP-003"
+
+    # --- Submodel Repository ---
+    SUBMODEL_REPOSITORY_FULL = "https://admin-shell.io/aas/API/3/1/SubmodelRepositoryServiceSpecification/SSP-001"
+    SUBMODEL_REPOSITORY_READ = "https://admin-shell.io/aas/API/3/1/SubmodelRepositoryServiceSpecification/SSP-002"
+    SUBMODEL_REPOSITORY_BULK = "https://admin-shell.io/aas/API/3/1/SubmodelRepositoryServiceSpecification/SSP-003"
+
+    # --- Concept Description Repository ---
+    CONCEPT_DESCRIPTION_REPOSITORY_FULL = \
+        "https://admin-shell.io/aas/API/3/1/ConceptDescriptionRepositoryServiceSpecification/SSP-001"
+    CONCEPT_DESCRIPTION_REPOSITORY_READ = \
+        "https://admin-shell.io/aas/API/3/1/ConceptDescriptionRepositoryServiceSpecification/SSP-002"
+    CONCEPT_DESCRIPTION_REPOSITORY_BULK = \
+        "https://admin-shell.io/aas/API/3/1/ConceptDescriptionRepositoryServiceSpecification/SSP-003"
+
+    # --- Discovery ---
+    DISCOVERY_FULL = "https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-001"
+    DISCOVERY_READ = "https://admin-shell.io/aas/API/3/1/DiscoveryServiceSpecification/SSP-002"
+
+
+# TODO: Maybe remove this in spite of spec? Too complicated structure
+class ServiceDescription:
+    def __init__(self, profiles: List[ServiceSpecificationProfileEnum]):
+        self.profiles: List[ServiceSpecificationProfileEnum] = profiles
+
+
 @enum.unique
 class MessageType(enum.Enum):
     UNDEFINED = enum.auto()
@@ -44,15 +118,16 @@ def __str__(self):
         return self.name.capitalize()
 
 
+@_string_constraints.constrain_code_type("code")
 class Message:
     def __init__(
         self,
-        code: str,
+        code: CodeType,
         text: str,
         message_type: MessageType = MessageType.UNDEFINED,
         timestamp: Optional[datetime.datetime] = None,
     ):
-        self.code: str = code
+        self.code: CodeType = code
         self.text: str = text
         self.message_type: MessageType = message_type
         self.timestamp: datetime.datetime = (
@@ -107,7 +182,7 @@ def __init__(self, *args, content_type="application/xml", **kwargs):
 
     def serialize(self, obj: ResponseData, cursor: Optional[int], stripped: bool) -> str:
         root_elem = etree.Element("response", nsmap=XML_NS_MAP)
-        if cursor is not None:
+        if cursor is not None or not (isinstance(obj, list) and not obj):
             root_elem.set("cursor", str(cursor))
         if isinstance(obj, Result):
             result_elem = self.result_to_xml(obj, **XML_NS_MAP)
@@ -199,19 +274,21 @@ def __call__(self, environ, start_response) -> Iterable[bytes]:
         return response(environ, start_response)
 
     @classmethod
-    def _get_slice(cls, request: Request, iterator: Iterable[T]) -> Tuple[Iterator[T], int]:
+    def _get_slice(cls, request: Request, iterator: Iterable[T]) -> Tuple[Iterator[T], Optional[int]]:
         limit_str = request.args.get("limit", default="10")
         cursor_str = request.args.get("cursor", default="1")
         try:
-            limit, cursor = int(limit_str), int(cursor_str) - 1  # cursor is 1-indexed
-            if limit < 0 or cursor < 0:
-                raise ValueError
+            limit, cursor = (NonNegativeInteger(int(limit_str)),
+                             NonNegativeInteger(int(cursor_str) - 1))  # cursor is 1-indexed
         except ValueError:
             raise BadRequest("Limit can not be negative, cursor must be positive!")
         start_index = cursor
         end_index = cursor + limit
-        paginated_slice = itertools.islice(iterator, start_index, end_index)
-        return paginated_slice, end_index
+        items = list(itertools.islice(iterator, start_index, end_index + 1))
+        has_more = len(items) > limit
+        paginated_slice = iter(items[:limit])
+        next_cursor = cursor + limit if has_more else None
+        return paginated_slice, next_cursor
 
     def handle_request(self, request: Request):
         map_adapter: MapAdapter = self.url_map.bind_to_environ(request.environ)
diff --git a/server/app/interfaces/registry.py b/server/app/interfaces/registry.py
diff --git a/server/app/interfaces/repository.py b/server/app/interfaces/repository.py
