The Eclipse BaSyx Python SDK is a Python implementation of the Asset Administration Shell (AAS) for Industry 4.0 systems. It lets you model, serialize, validate, store, and serve AAS data entirely in Python.
The project is part of the Eclipse BaSyx middleware framework, developed under the umbrella of the Eclipse Foundation.
Note
The SDK version number is independent of the supported AAS specification versions.
These are the AAS specifications implemented by the current release:
| Specification | Version |
|---|---|
| Part 1: Metamodel | v3.1.2 (01001-3-1-2) |
| Schemata (JSONSchema, XSD) | v3.1.2 (IDTA-01001-3-1-2) |
| Part 2: API | v3.1.1 (01002) |
| Part 3a: Data Specification IEC 61360 | v3.1.1 (01003-a) |
| Part 5: Package File Format (AASX) | v3.1 (01005) |
For older specification support, consult the prior releases. Each release has a similar table in its notes.
This mono-repository contains three self-contained Python packages that cover different aspects of working with Asset Administration Shells:
The SDK is the core of this project. It provides:
- AAS Metamodel — full Python object model of the AAS metamodel (Part 1)
- Serialization — read and write AAS data as JSON, XML, or AASX package files
- Backend Storage — persist AAS objects in CouchDB or as local JSON files, with an extensible backend interface
- Experimental RDF Support — serialization to RDF is available on the Experimental/Adapter/RDF branch (see #308 for context)
A Docker image that exposes a specification-compliant HTTP/REST API (AAS Part 2), currently implementing the following service interfaces:
- Asset Administration Shell Repository
- Submodel Repository
- AAS Registry
- AAS Discovery
It can serve AAS data from AASX, JSON, or XML files, optionally with persistent storage via the Local-File Backend.
A command-line utility for checking whether AAS JSON, XML, or AASX files conform to the official schema. Useful for CI pipelines, data validation, and interoperability testing.
Each package in this repository can be set up independently. Refer to the package-level READMEs for detailed installation instructions, usage examples, and configuration options:
- SDK (install from PyPI or conda-forge, quick code example, tutorials)
- Server (Docker build & run, environment variables, persistence options)
- Compliance Tool (install, command-line usage)
The SDK ships with step-by-step tutorials in sdk/basyx/aas/examples/:
| Tutorial | What You Will Learn |
|---|---|
| Create a Simple AAS | Build an Asset Administration Shell with an Asset and a Submodel from scratch |
| Navigate Submodels | Traverse AAS Submodels using IdShorts and IdShortPaths |
| Object Storage | Manage many AAS objects with ObjectStores and resolve references |
| Serialization & Deserialization | Read and write AAS data as JSON and XML |
| AASX Packages | Export AAS shells with related objects and auxiliary files to AASX packages |
| CouchDB Backend | Store and retrieve AAS objects in a CouchDB document database |
A detailed, complete API documentation is available on Read the Docs.
Ready-to-use Docker Compose configurations can be found in server/example_configurations/:
| Configuration | Description |
|---|---|
| Repository Standalone | AAS and Submodel repository server |
| Registry Standalone | AAS and Submodel registry service |
| Discovery Standalone | AAS discovery service |
Q: I can't read a JSON/XML/AASX file from another tool with this SDK. What should I do?
A: The SDK enforces strict compliance with the AAS specification that your file might not comply with. To diagnose the issue:
- Check that the file targets the same AAS specification version supported by your SDK version (Specification Compliance for the current release)
- Run the Compliance Tool on the file to identify schema violations
- If the file is spec-compliant and the SDK still rejects it, please open an issue with the error message and, if possible, a minimal example file.
Q: Can I run the server without Docker?
A: Yes, for debugging purposes. See the Server README for instructions. This mode is not suitable for production.
Q: I need a newer Python version than the latest release supports. Where can I find it?
A: The develop branch
may adopt new Python versions ahead of the next release. It currently supports Python
The Eclipse BaSyx Python SDK team meets bi-monthly to evaluate whether the changes accumulated
on the develop branch warrant a new release. If so, the changes are merged into the main branch and a
new version is published to
PyPI and
conda-forge
using semantic versioning. If not, the decision is deferred to the
next meeting. Security fixes may be released at any time.
We welcome contributions of all kinds. Please read our Contribution Guidelines before getting started.
This project is licensed under the terms of the MIT License.
SPDX-License-Identifier: MIT
For details on third-party dependencies and their licenses, see the NOTICE file.